UCAN v0.9.0

[expede]

• 👉 Preview Render 📃
• v0.9 Design Goals #35

Change Log 🪙🪵

Added 📥

• Explicitly restrict keys to RSA, ECDSA, and EdDSA per @ukstv
• Standardize on "proof" instead of "witness" (see Update terminology: Use "witness" instead of "proof" #23)
  • At minimum it leaves the door open for renaming later; we already call them proofs
• [ ] Revocation spec Staying the same, see comment: UCAN v0.9.0 #55 (comment)
• Standardize on "ability" and not "action"
• Break out caveats fields, per @Gozala It might be better if capability constraints / caveats / extras had their own named field #61
• Replace my:... URI with "my" parenthood field
• Changes to UCAN DAG representation
  • CARv2 Agnostic collections
  • Proofs enforced as CIDs only

Removed 📤

• Remove IPFS/DHT requirement
• Remove URI selection by scheme (e.g. no more "with": "dns:*")
  • This was actually very bad and broke the URI contract

Move Out of Core Spec 🪁

• [x] Consider extending my: to all parenthood cases, even specific values (CC @matheus23)
• Transport agnostic point-to-point protocol
• HTTP cache header protocol <- HTTP stuff should live in own spec
• Resource selection (e.g. "with": "ucan:uri:dns")

Resolves 🛠️

• Closes It might be better if capability constraints / caveats / extras had their own named field #61
• Closes Principal IDs and signature verification #77

[expede]

cc @dholms FYI this is going to include removal of the DHT dependency, and replace it with a point-to-point (e.g. HTTP) protocol. If you have any thoughts on this direction, this is the time! 😉

[expede]

Added this line to the 0.9 roadmap:

Consider extending my: to all parenthood cases, even specific values (CC @matheus23)

#21 (comment)

[ukstv]

Hey, I might be missing something here, but as far as I understand, UCAN thing is not really a valid JWT, even in this form. You mention mandatory support of did:key. Apparently, it allows using some exotic signature suites like BLS, which can not be really supported in older JWT libraries, as it does not belong to JOSE algorithms (AFAIK!). Do you apply some constraints on the list of available algorithms, like using only ed25519 and RSA did:key, or is the whole backwards compatibility story a bit of a misnomer?

If my basic understanding is correct, then UCAN supports did methods that use JOSE algorithms exclusively. How can it be both compatible with existing JWT tooling and support advanced did methods?

[expede]

@ukstv Technically DID can support any signature scheme, yup! Today we support EdDSA, ECDSA, and RSA only, which are all in JWT. IIRC EdDSA is in a separate JOSE extension IETF spec, but is extremely widely supported in libraries (it's de facto supported).

We should absolutely be explicit about this in the spec. We also don't allow HMAC verification.

A library supporting more methods "off spec" is possible today (we've done proof of concepts with ION, for example), but can't expect that to be compatible with "any" other implementation. The spec if just here to be the line of "what is interoperable".

If there's a good case made, we're open to effectively forking JWT (at which point, we drop the weird multi-section formatting with .s and stuff, trim a few bytes from redundant fields, etc). Using JWT as-is has a few arguments:

1. Easy to build new implementations out of existing components
2. Extensive tooling (though not for the UCAN parts — we've started on some at ucan.xyz)
3. Familiarity for web devs / "sell to management"

[expede]

Would that not be covered by the alg field in the JWT header?

[expede]

I flipped this to Ready for Review. I think that we're mainly on the same page about the scope of 0.9 from the conversation above, but please do mention anything that should or should not be in here. I think the most controversial things will be:

1. Requiring my: for introduction by parenthood
2. The label nb for extensible fields

Open to folks flagging typos or nitpicks. VERY open to approvals 😜

[matheus23]

Would this explicitly deny using dag-ucan in valid UCANs?

[expede]

That's a really good point!

@Gozala: you're proposing the use of dag-json for the deterministic codec, yes? IIRC dag-ucan didn't go forward.

[Gozala]

Would this explicitly deny using dag-ucan in valid UCANs?

It does sound like it would indeed make dag-ucan incompatible with a spec as it uses CBOR encoding with a following schema #67, when possible.

@expede is this intentional ? Otherwise can we either include CBOR variant or at least change wording so that RAW isn't the only valid option.

[Gozala]

@Gozala: you're proposing the use of dag-json for the deterministic codec, yes? IIRC dag-ucan didn't go forward.

I'm not sure I fully understand that question, I think there are couple of things mixed up, so I"ll try to clarify:

1. dag-ucan did go forward and it uses CBOR encoding when possible (that is turning that CBOR to JSON and then formatting as JWT produces same signature), and RAW encoding otherwise.
2. Idea of introducing dag-ucan multicodec code was dropped in favor of just CBOR because:
   1. It did not provide a lot of benefit, mostly signaling in links
   2. And came with tradeoff that required registering new codecs even though it is CBOR with some schema.
3. I have been advocating for ucan implementations using dag-json as that would allow them to be representation agnostic (could be encoded in CBOR without signature changes). However that is unrelated to dag-ucan.

[expede]

@Gozala There was a previous version that included the dag-ucan multicodec. When that PR was nixed, I dropped its prefix from this document. I just forgot to update this section after dag-json was settled on. I'll add that now 👍

[expede]

@Gozala any concern with limiting it to CIDv1 + base32?

[matheus23]

Only a couple of typos I noticed + a question about allowing a dag-ucan/other codecs in CIDs, but that question is mostly out of interest.
So apart from fixing typos, let's :)

[olizilla]

Some fixes for broken internal links after the great renumbering

I found a couple the old fashioned way when clicking around the rendered version, and used:

$$('a[href^="#"]').filter(el => !document.getElementById(`user-content-${el.getAttribute('href').substring(1)}`)).map(el => el.innerText)

to find the rest. Provided here in case it's handy for future re-numberings. 🔢🔍✨

[hugomrdias]

left some suggestions to fix typos.

[Gozala]

Would this explicitly deny using dag-ucan in valid UCANs?

It does sound like it would indeed make dag-ucan incompatible with a spec as it uses CBOR encoding with a following schema #67, when possible.

@expede is this intentional ? Otherwise can we either include CBOR variant or at least change wording so that RAW isn't the only valid option.

[Gozala]

@Gozala: you're proposing the use of dag-json for the deterministic codec, yes? IIRC dag-ucan didn't go forward.

I'm not sure I fully understand that question, I think there are couple of things mixed up, so I"ll try to clarify:

1. dag-ucan did go forward and it uses CBOR encoding when possible (that is turning that CBOR to JSON and then formatting as JWT produces same signature), and RAW encoding otherwise.
2. Idea of introducing dag-ucan multicodec code was dropped in favor of just CBOR because:
   1. It did not provide a lot of benefit, mostly signaling in links
   2. And came with tradeoff that required registering new codecs even though it is CBOR with some schema.
3. I have been advocating for ucan implementations using dag-json as that would allow them to be representation agnostic (could be encoded in CBOR without signature changes). However that is unrelated to dag-ucan.

[Gozala]

Am I correct in interpreting this as * means all abilities including ones that may be introduced in the future. While ucan/delegate means all abilities that are present in proofs ? If so I think I'm starting to get the distinction, yet I think that could be made more clear.

In other words following capability

{ 
    "with": "owned://did:key:zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV/wnfs", 
    "can": "*" 
  }

Implies that all wnfs:// capabilities of did:key:zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV had been delegated even though they aren't listed by did:key:zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV.

On the other hand following capability:

{ 
    "with": "ucan:*", 
    "can": "ucan/DELEGATE" 
  }

implies that all the of the capabilities from all proofs have been (re)delegated.

Confusing bit here is that two either never overlap (in which case I think there's no point in having ucan/delegate) or they do and following capability:

{ 
    "with": "owned://did:key:zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV/wnfs", 
    "can": "ucan/DELEGATE" 
  }

has different semantics from the 1st one (with same with and "can": "*") and implies to select only explicitly delegated "wnfs" capabilities from did:key:zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV as opposed to all the "wnfs" capabilities from that actor.

If later is true I think disambiguating between these delegations using different URI schemas seems a lot less confusing to me.

[expede]

In other words following capability
[...]
Implies that all wnfs:// capabilities of did:key:zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV had been delegated even though they aren't listed by did:key:zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV.
On the other hand following capability:
[...]
implies that all the of the capabilities from all proofs have been (re)delegated.

Yup, that's the distinction! ucan/delegate only makes sense in the context of ucan:, in the same way that msg/send does make sense for mailto: but not wnfs:.

I'll add some clarifying text to that effect 👍

implies that all the of the capabilities from all proofs have been (re)delegated.

Also {with: "ucan:Qm12345:", can: "ucan/delegate"} would delegate from that one UCAN. This is the any (i.e. "any" / whatever happens to be in Qm12345). It may be a lot of power, or very little.

On the other hand, can: "*", that would assert the maximum rights to the resource ("all rights"), which need to be be ownership, or backed up with exactly that from a proof.

Confusing bit here is that two either never overlap (in which case I think there's no point in having ucan/delegate)

Tell me about not having ucan/delegate then? msg/send also doesn't overlaps with CRUD actions, and often resources can use only one or the other.

[Gozala]

Tell me about not having ucan/delegate then? msg/send also doesn't overlaps with CRUD actions, and often resources can use only one or the other.

There are few things that I think contribute to the confusion:

1. The * is a special form (only thing that does not need to be namespaced). It is used also in with to match anything. However in case of can it's semantics change to mean maximum rights to the resource.
2. It is confusing (and annoying) that * in can field can only be used with some protocol schemas and not the other. In turn it creates more opportunities to have invalid UCANs (I'm pretty sure we even have some of those in our system). It is true that not every can be used in conjunction with every with, but given a special form I'd expect it to.
3. Just like you could use * in "with": "ucan:*" to match pattern I would expect to do the same in can: "store/*" to match all the capabilities that were delegated namespaces with store.

In summary it feels composable but it is not and it is not intuitively obvious which things can be used in conjunction and which can't. This adds to complexity which I fear can lead to implementation incompatibilities due to misinterpretation.

It seems more intuitive to capture whether resource refers to explicitly delegated or implicitly owned capabilities in "resource" selector than in ability. I could be convinced that it should be captured in "ability", but even than using any other identifier but * would be far less confusing.

Alternatively encoding "superuser ability" in a different special form might worth considering

[Gozala]

Ok so here is an example of the delegated capabilities

[
  { 
    "with": "owned://did:key:zAlice/wnfs", 
    "can": "*" 
  },
  {
     "with": "owned://did:key:zBob/wnfs",
     "can": "ucan/delegate"
  }
]

So here is what I find unclear about this:

1. What happens if Alice delegated just specific wnfs capabilities as opposed to super user ability ? Is above redelegation invalid or is it just redelegates ones that Alice delegated ?
2. What happens if Bob delegated "superuser ability" ? Does above UCAN redelegates all the wnfs abilities from Bob including future ones (which would mean it would be no different from using "can": "*") or does not delegate any wnfs ability from Bob ? Or perhaps it implies abilities that were known to "wnfs" at time the delegation occurred (I hope not this one) ?

Update: I am realizing now that can: "*" is reserved only for owned: schema, and "ucan/delegate" for "ucan" schema which would mean above UCAN would be invalid, still I think it illustrates some of the confusion.

[expede]

@Gozala I just watched @hugomrdias's UCAN talk from Iceland (which I missed because I was giving a concurrent talk at the same time), and the way he's framing the foo/* capabilities makes a ton of sense. It's a slightly different way of looking at the problem, but I think it's better. I'll make that change 👍

[Gozala]

@expede I have evaluated changes required to switch from "my:*" schema to "my" field in our implementation and I'm afraid I'm arriving to conclusion that this idea may have been a bad one. I feel bad for pushing for it without evaluating it first, but maybe it is not too late to reconsider ? Here are some of my the unstructured thoughts about it:

• UCAN validator needs to recognize which capabilities can be issued by an actor to distinguish them from ones that are delegated.
  • ucanto validator provides canIssue(capability, issuer): boolean hook to make that configurable.
  • By default it is uses canIssue(cap, iss) => cap.with === iss, implying that only owner of the did can issue capabilities for that did.
  • ucanto does not recognized my:* as one that actor can issue, instead it has my(iss): cap[] hook which is used to expand my:* forms and then select matches from it.
• In other domains decisions made by ucanto may not fit so there needs to be another signaling mechanism which used to be e.g my:wnfs://....
  • However it seems that validating that would still require out of bound checks that claimed resource is actually owned by user.
• I think signaling whether capability is owned by iss or not should be left out of spec that way ucanto can use it's did matching logic while other implementations may embrace my: schema

[expede]

@Gozala

but maybe it is not too late to reconsider ?

I've been waiting for your review exactly for this reason 👍

I think signaling whether capability is owned by iss or not should be left out of spec that way ucanto can use it's did matching logic while other implementations may embrace my: schema

I'd love to dig into this more, because I'm having a hard time piecing together how the validation and rooted authority would work in this version. A sync call may be the fastest way to iterate on some ideas, but let me know! I'll ping you on Discord.

[expede]

cc @Gozala just some commentary on the changes after our call. Does this match your picture?

[expede]

Added the option to use an explicit null to the expiry. The other option that we discussed was setting it to super far in the future (e.g. 9999999999), which is roughly what we do today even if it doesn't capture the intention.

We want this field to be fairly salient — no expiry is potentially dangerous and not listing it makes that easy to miss — hence not having it be optional.

[expede]

@matheus23 from the call with @Gozala earlier, it sounds like the ambiguity of "it may be in the chain or in the proofs and we have to handle either" is just less error prone and actually more ergonomic. I realize that this is comes full circle 😅 Please do push back if it's an "over my dead body"

[Gozala]

For more context, in our uses we can tell if capability can be issued by an actor of it has to be delegated, specifically if it matches ${protocol}://${my_did}/* it can be self issued otherwise it needs to be delegated.

That is to say that how you resolve ambiguity may vary and that is also an argument for not prescribing it via spec.

[expede]

Ah I see. This is what the previous my/as and now the own scheme are for. You can't use a DID in an arbitrary URI as the host field, nor a * path to mean multiple resources of that type. It depends on the definition of the specific URI.

This proposal merely suggests reformatting that into a safer, more widely compatible form.

[expede]

We could potentially pull this out into its own spec, as it's not a hard requirement for the core spec.

[Gozala]

@expede This is kind of a thing that we probably would have expressed as follows instead

1. Can do anything did:key:zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV could do

{ can: "*", with: "did:key:zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" }

2. Can do same DNS stuff as did:key:zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV

{ can: "*", with: "dns://did:key:zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" }

If expressed as above own: becomes unnecessary, for the same reason as my is unnecessary - if issuer is same ID it can self issue, otherwise it must be delegated from the did.

[expede]

@Gozala I see what you're trying to do, but both break the URI schemes which are defined in their own specs. For example, dns://did:key:zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV would need to resolve did:key:zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV as a DNS host as defined in RFC 4501 and RFC 3986.

The example you give above is not formatted as that, and so a DNS parser would fail ahead of a lookup. What own gives you here is a signal that we're not using the dns: URI scheme. The host authority for DNS is the source authority for resolution, not the owner of the DNS name (you may trust Google's resolver, for instance)

Hosts are also case insensitive in the URI spec, but DIDs are not:

host = IP-literal / IPv4address / reg-name
[...]
Although host is case-insensitive, producers and normalizers should use lowercase for registered names and hexadecimal addresses for the sake of uniformity, while only using uppercase letters for percent-encodings.

And the host is intended to resolve to a IP literal, which DIDs don't do.

If you want to use the user field, not all URIs support it, and the URI ABNF requires a host to be specified for the user (helpful railroad diagram here).

Most DID methods are also resources themselves, where you're maintaining PKs on a DID document. Saying { can: "*", with: "did:<foo>:zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" } for example would imply the ability to update the actual DID document, not the resources accessible or owned by that DID.

[expede]

FWIW, Fission has done variants of both of the above in the past, but I've come to realize that once we switched to URI resources, we should probably honour the URIs that we say they are, otherwise there's lots of sharp edges, potential for confusion, attack surface (URI parsing attacks are a thing), and difficulty in reusing existing URI tooling.

[expede]

✂️ my:

[expede]

✂️ my:

[expede]

I realized that we actually do need a top ability for a bunch of linking use cases at Fission (and I believe Bluesky), and that it likely does need to live in the core spec. I had removed it a few days ago after seeing how DAG House is approaching their modelling. This does not alter how they need to think about their abilities at all, and they do not need to adopt */*.

I expanded on the explanation & diagram after explaining the feature to Irakli a few days ago. The syntax is also changed to be consistent with the */* pattern that we see showing up in the wild.

[Gozala]

Thank you so much @expede for all the work & I apologize for the delay.

[Gozala]

@expede If I recall correctly you said motivation for the own:// protocol was due to the fact that did:key: can't have paths in them ? However I was unable to find that restriction & was wondering if maybe that is invalid assumption ?

I was also thinking that:

1. Query params could probably used to restrict what's delegated from one agent to the other.
2. own: could be subsumed by ucan:did:key:zKey instead so we avoid reserving more than one protocol scheme.

[expede]

There's two things:

1. UCAN isn't restricted to did:key. As you mention, the DID spec doesn't restrict the path segment, so any DID method can define path segment, breaking the proposed solution
2. Sure, we could use the ucan: scheme instead. Any thoughts pro/con on using a subscheme?

Maybe I can borrow you in person while we're in person the next few days. I'll ping you on Discord.

[expede]

@Gozala several your comments seems to be on old code — not sure what's happening there. For example:

[hugomrdias]

Left just one inline suggestion for a rendering problem so assume LGTM and approval after that fix.