add server/issuer/client examples, and lots of sanding

toolkit/issuer/dlg_issuer.go

@@ -2,6 +2,7 @@ package issuer
 
 import (
 	"context"
+	"fmt"
 	"iter"
 	"time"
 
@@ -14,18 +15,31 @@ import (
 	"github.com/INFURA/go-ucan-toolkit/client"
 )
 
+// DlgIssuingLogic is a function that decides what powers are given to a client.
+// - issuer: the DID of our issuer
+// - audience: the DID of the client, also the issuer of the invocation token
+// - cmd: the command to execute
+// - subject: the DID of the resource to operate on, also the subject (or audience if defined) of the invocation token
+// Note: you can read it as "(audience) wants to do (cmd) on (subject)".
+// Note: you can decide to match the input parameters exactly or issue a broader power, as long as it allows the
+// expected action. If you don't want to give that power, return an error instead.
+type DlgIssuingLogic func(iss did.DID, aud did.DID, cmd command.Command, subject did.DID) (*delegation.Token, error)
+
 var _ client.DelegationRequester = &Issuer{}
 
+// Issuer is an implementation of a re-delegating issuer.
+// Note: Your actual needs for an issuer can easily be different (caching...) than the choices made here.
+// Feel free to replace this component with your own flavor.
 type Issuer struct {
 	did     did.DID
 	privKey crypto.PrivKey
 
 	pool      *client.Pool
 	requester client.DelegationRequester
-	logic     IssuingLogic
+	logic     DlgIssuingLogic
 }
 
-func NewIssuer(privKey crypto.PrivKey, requester client.DelegationRequester, logic IssuingLogic) (*Issuer, error) {
+func NewIssuer(privKey crypto.PrivKey, requester client.DelegationRequester, logic DlgIssuingLogic) (*Issuer, error) {
 	d, err := did.FromPrivKey(privKey)
 	if err != nil {
 		return nil, err
@@ -39,16 +53,6 @@ func NewIssuer(privKey crypto.PrivKey, requester client.DelegationRequester, log
 	}, nil
 }
 
-// IssuingLogic is a function that decides what powers are given to a client.
-// - issuer: the DID of our issuer
-// - audience: the DID of the client, also the issuer of the invocation token
-// - cmd: the command to execute
-// - subject: the DID of the resource to operate on, also the subject (or audience if defined) of the invocation token
-// Note: you can read it as "(audience) wants to do (cmd) on (subject)".
-// Note: you can decide to match the input parameters exactly or issue a broader power, as long as it allows the
-// expected action. If you don't want to give that power, return an error instead.
-type IssuingLogic func(iss did.DID, aud did.DID, cmd command.Command, subject did.DID) (*delegation.Token, error)
-
 // RequestDelegation retrieve chain of delegation for the given parameters.
 // - audience: the DID of the client, also the issuer of the invocation token
 // - cmd: the command to execute
@@ -56,6 +60,10 @@ type IssuingLogic func(iss did.DID, aud did.DID, cmd command.Command, subject di
 // Note: you can read it as "(audience) does (cmd) on (subject)".
 // Note: the returned delegation(s) don't have to match exactly the parameters, as long as they allow them.
 func (i *Issuer) RequestDelegation(ctx context.Context, audience did.DID, cmd command.Command, subject did.DID) (iter.Seq2[*delegation.Bundle, error], error) {
+	if subject != i.did {
+		return nil, fmt.Errorf("subject DID doesn't match the issuer DID")
+	}
+
 	var proof []cid.Cid
 
 	// is there already a valid proof chain?
@@ -86,6 +94,9 @@ func (i *Issuer) RequestDelegation(ctx context.Context, audience did.DID, cmd co
 	if err != nil {
 		return nil, err
 	}
+	if dlg.IsRoot() {
+		return nil, fmt.Errorf("issuing logic should return a non-root delegation")
+	}
 
 	// sign and cache the new token
 	dlgBytes, dlgCid, err := dlg.ToSealed(i.privKey)

toolkit/issuer/http_wrapper.go

@@ -0,0 +1,83 @@
+package issuer
+
+import (
+	"fmt"
+	"io"
+	"iter"
+	"net/http"
+
+	"github.com/ucan-wg/go-ucan/did"
+	"github.com/ucan-wg/go-ucan/pkg/command"
+	"github.com/ucan-wg/go-ucan/pkg/container"
+	"github.com/ucan-wg/go-ucan/token/delegation"
+
+	"github.com/INFURA/go-ucan-toolkit/client"
+)
+
+type RequestResolver func(r *http.Request) (*ResolvedRequest, error)
+
+type ResolvedRequest struct {
+	Audience did.DID
+	Cmd      command.Command
+	Subject  did.DID
+}
+
+// HttpWrapper implements an HTTP transport for a UCAN issuer.
+// It provides a common response shape, while allowing customisation of the request.
+func HttpWrapper(requester client.DelegationRequester, resolver RequestResolver) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			http.Error(w, http.StatusText(http.StatusMethodNotAllowed), http.StatusMethodNotAllowed)
+			return
+		}
+
+		resolved, err := resolver(r)
+		if err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+
+		dlgs, err := requester.RequestDelegation(r.Context(), resolved.Audience, resolved.Cmd, resolved.Subject)
+		if err != nil {
+			http.Error(w, err.Error(), http.StatusInternalServerError)
+			return
+		}
+
+		cont := container.NewWriter()
+		for bundle, err := range dlgs {
+			if err != nil {
+				http.Error(w, err.Error(), http.StatusInternalServerError)
+				return
+			}
+			cont.AddSealed(bundle.Sealed)
+		}
+
+		err = cont.ToBytesGzippedWriter(w)
+		if err != nil {
+			http.Error(w, err.Error(), http.StatusInternalServerError)
+			return
+		}
+	})
+}
+
+func DecodeResponse(res *http.Response) (iter.Seq2[*delegation.Bundle, error], error) {
+	defer res.Body.Close()
+	if res.StatusCode != http.StatusOK {
+		msg, err := io.ReadAll(res.Body)
+		if err != nil {
+			return nil, fmt.Errorf("request failed with status %d, then failed to read response body: %w", res.StatusCode, err)
+		}
+		return nil, fmt.Errorf("request failed with status %d: %s", res.StatusCode, msg)
+	}
+	cont, err := container.FromReader(res.Body)
+	if err != nil {
+		return nil, err
+	}
+	return func(yield func(*delegation.Bundle, error) bool) {
+		for bundle := range cont.GetAllDelegations() {
+			if !yield(&bundle, nil) {
+				return
+			}
+		}
+	}, nil
+}

toolkit/issuer/root_issuer.go

@@ -0,0 +1,78 @@
+package issuer
+
+import (
+	"context"
+	"fmt"
+	"iter"
+
+	"github.com/libp2p/go-libp2p/core/crypto"
+	"github.com/ucan-wg/go-ucan/did"
+	"github.com/ucan-wg/go-ucan/pkg/command"
+	"github.com/ucan-wg/go-ucan/token/delegation"
+
+	"github.com/INFURA/go-ucan-toolkit/client"
+)
+
+// RootIssuingLogic is a function that decides what powers are given to a client.
+// - issuer: the DID of our issuer
+// - audience: the DID of the client, also the issuer of the invocation token
+// - cmd: the command to execute
+// Note: you can read it as "(audience) wants to do (cmd) on (subject)".
+// Note: you can decide to match the input parameters exactly or issue a broader power, as long as it allows the
+// expected action. If you don't want to give that power, return an error instead.
+type RootIssuingLogic func(iss did.DID, aud did.DID, cmd command.Command) (*delegation.Token, error)
+
+var _ client.DelegationRequester = &RootIssuer{}
+
+// RootIssuer is an implementation of a root delegation issuer.
+// Note: Your actual needs for an issuer can easily be different (caching...) than the choices made here.
+// Feel free to replace this component with your own flavor.
+type RootIssuer struct {
+	did     did.DID
+	privKey crypto.PrivKey
+
+	logic RootIssuingLogic
+}
+
+func NewRootIssuer(privKey crypto.PrivKey, logic RootIssuingLogic) (*RootIssuer, error) {
+	d, err := did.FromPrivKey(privKey)
+	if err != nil {
+		return nil, err
+	}
+	return &RootIssuer{
+		did:     d,
+		privKey: privKey,
+		logic:   logic,
+	}, nil
+}
+
+func (r *RootIssuer) RequestDelegation(ctx context.Context, audience did.DID, cmd command.Command, subject did.DID) (iter.Seq2[*delegation.Bundle, error], error) {
+	if subject != r.did {
+		return nil, fmt.Errorf("subject DID doesn't match the issuer DID")
+	}
+
+	// run the custom logic to get what we actually issue
+	dlg, err := r.logic(r.did, audience, cmd)
+	if err != nil {
+		return nil, err
+	}
+	if !dlg.IsRoot() {
+		return nil, fmt.Errorf("issuing logic should return a root delegation")
+	}
+
+	// sign and cache the new token
+	dlgBytes, dlgCid, err := dlg.ToSealed(r.privKey)
+	if err != nil {
+		return nil, err
+	}
+	bundle := &delegation.Bundle{
+		Cid:     dlgCid,
+		Decoded: dlg,
+		Sealed:  dlgBytes,
+	}
+
+	// output the root delegation
+	return func(yield func(*delegation.Bundle, error) bool) {
+		yield(bundle, nil)
+	}, nil
+}