example: finish readme, small tuning

toolkit/_example/Readme.md

@@ -1,9 +1,36 @@
+## UCAN examples
+
+This directory contains an example of UCAN usage across multiple agents, and their respective implementations.
+
+Please note that UCAN in itself doesn't enforce any protocol, topology or transport, and as such what you have here is one possibility among many others. In particular:
+- this example is really geared towards using UCAN for an HTTP API
+- it uses a particular flavor of issuer protocol and token exchange. In particular, that issuer gives delegation tokens to anyone asking.
+
+Your situation may be different from this, and would call for a different setup.
+
+Remember that everything in `go-ucan-toolkit` is essentially helpers, pre-made building blocks. You can use them, change them or make your own.
+
+## Scenario 1
+
+Starting simple, if we run `service`, `service-issuer` and `alice-client-server`, we have the following scenario:
+
 ![scenario 1](scenario1.png)
+
+- `service` controls the access to the resource (it's the `Executor` in that diagram). You can think about it as a proxy with authentication.
+- `service-issuer` gives a delegation tokens to clients. `service` and `service-issuer` share the same DID and keypair.
+- `alice-client-server` ask for a token, and periodically makes request
+
+## Scenario 2
+
+Building on the previous scenario, we are adding sub-delegation.
+
 ![scenario 2](scenario2.png)
 
-TODO
+- `alice-client-server` still do the same thing, but also expose a similar token issuer with the same protocol (for simplicity in that example)
+- `bob-client` request a delegation from Alice, and make **direct** request to the service
 
-- differences with a real system
+Note a few things:
-  - issuer protocol + token exchange
+- Alice can finely tune what Bob can do
-  - opinionated with HTTP
+- Bob receives **two** delegations: the original one Alice got and a second one delegating some of that original power to him
-- toolkit is helpers, you can change or write your own thing
+- Bob can make direct calls to the service without having to be proxied somewhere
+- The service doesn't have to know beforehand about Bob or what power is given to him

toolkit/_example/_protocol-issuer/requester.go

@@ -45,7 +45,7 @@ func (r Requester) RequestDelegation(ctx context.Context, audience did.DID, cmd
 		return nil, err
 	}
 
-	req, err := http.NewRequest(http.MethodPost, "http://"+r.issuerURL, buf)
+	req, err := http.NewRequest(http.MethodPost, r.issuerURL, buf)
 	if err != nil {
 		return nil, err
 	}

toolkit/_example/alice-client-issuer/alice.go

@@ -67,7 +67,7 @@ func run(ctx context.Context, ownIssuerUrl string, priv crypto.PrivKey, d did.DI
 		return delegation.New(iss, aud, cmd, policies, subject)
 	}
 
-	cli, err := client.NewWithIssuer(priv, protocol.NewRequester(serviceIssuerUrl), issuingLogic)
+	cli, err := client.NewWithIssuer(priv, protocol.NewRequester("http://"+serviceIssuerUrl), issuingLogic)
 	if err != nil {
 		return err
 	}

toolkit/_example/bob-client/bob.go

@@ -50,7 +50,7 @@ func run(ctx context.Context, aliceUrl string, aliceDid did.DID, serverUrl strin
 
 	log.Printf("Bob DID is %s", d.String())
 
-	cli, err := client.NewClient(priv, protocol.NewRequester(aliceUrl))
+	cli, err := client.NewClient(priv, protocol.NewRequester("http://"+aliceUrl))
 	if err != nil {
 		return err
 	}