Various questions about the spec

[nicobao]

I have a few questions about the UCAN Spec :

• the spec explains that UCAN is of the SPKI family. However the paper Capability Myths Demolished linked in the Intuition chapter mentions that SPKI are limited compared to the object capabilities model (see figure 15 below extracted from the paper). The justification in the UCAN spec is "Since offline operation and self-verifiability are two requirements, UCAN adopts an approach closely related to SPKI". Can you provide more background about the trade-offs of the different approaches? The paper appears to present the object capabilities model as a silver bullet.
  
• is there any security recommendation for size of the nonce? It just need to be unique? How to make sure it is unique if the UCANs are generated in a decentralized way by various entities? How to make sure the same function is used by everyone? Is UUID a good implementation? Is the owner responsible for providing recommendation as to how to generate the nonce?
• what does it mean that facts must be externally verifiable? Does self-evident means self-explanatory, meaning the naming of the variable should make sense? See https://github.com/ucan-wg/spec#324-facts
• DIDs never need to be actually resolved using their Method, right?
• there is no example for Attenuation https://github.com/ucan-wg/spec#324-facts - can you provide one?
• what is the root entry point /? See https://github.com/ucan-wg/spec#71-canonical-json-collection
• I don't understand how prf works. How are proofs calculated? Could you provide a practical example of the step that leads to generating the canonical representation?
• Imagine a centralized server providing an API that is authorized using UCAN.
  • To prevent replay attacks, they must keep track of all the UCAN they have generated in some database (let's say in a table in PostgreSQL for simplicity). But they also need to insert new valid delegated UCAN that they receive, right?
  • They also need to keep track of every UCAN that was revoked. The revoked UCAN can be a UCAN that the server never generated themselves, such as a UCAN that was delegated from a UCAN they generated. So the server must provide a public endpoint to revoke UCAN, and keep a separate table with all revoked UCAN. Am I correct?
  • How to prevent the tables of valid UCAN and revoked UCAN to get unecessarily large? I suppose the server SHOULD periodically delete from its database every UCAN that are expired (time validation)?
• I don't understand Session Content ID. What does discharging an invokation means? Invoking it? Does it mean the sender wants to invoke multiple capabilities at the same time? the sender and receiver MAY agree to use the triple of CID, nonce, and signature rather than reissuing - triple but then in I don't see any triple in the provided example:

{ 
  "cid": cid(ucan)
  "nnc": "ABC", 
  "sig": sign(ucan.iss.privateKey, cid(ucan) + "ABC") 
}

Thank you.

(originally posted on StackOverflow https://stackoverflow.com/questions/74152236/ucan-spec-questions-nonce-recommendation-fact-example-prf-proof-owner-ucan-c)

[expede]

@nicobao thanks for reading through the spec, and for your questions! Always good to know what's not totally clear.

A few of the points below make me think that you may be thinking about UCAN from an ACL point of view; I'm happy to get on a call and walk you through how this system is different, which may be easier than text. I'll send you a calendly link in DMs.

This video may be helpful as well: https://youtu.be/grec5KQeU2U?t=161

SPKI are limited compared to the object capabilities model

Capability Myths Demolished one of my favourite papers on this topic :)

ocap requires that you have active agents that are reachable — it doesn't work over a network partition. Design patterns in ocap tend to have a lot of proxies, which means that the actual authority needs to move between machines, which has an additional latency cost. You cannot cache information about authority in ocap, since it has a liveness requirement. If any service in a proxy chain is unreachable (e.g. network goes down), then your system also goes down.

UCAN was originally designed to support local-first and low(er)-latency trustless applications. It continues to work under network partition, and trades off instant revocation for an eventual consistency. This does mean that with UCAN you need to follow the principle of least authority (POLA) because it's "proactive" auth ("this ticket will let you in to the show") rather than "reactive" auth ("are you on the list of aticve members?")

If your okay with your system going down when there's a network partition, CapTP may be worth exploring instead.

is there any security recommendation for size of the nonce? It just need to be unique?

It needs to be unique relative to the rest of the token fields. It's there to make sure that you get a unique CID. Since the expiration field tends to change frequently, there is already quite a lot of variation in CIDs. Primarily, every delegation should have a unique CID.

It's often recommended that a nonce be 12-bytes long, but it's left adjustable to suit your use case. A UUID is almost certainly overkill.

what does it mean that facts must be externally verifiable? Does self-evident means self-explanatory, meaning the naming of the variable should make sense? See https://github.com/ucan-wg/spec#324-facts

It's a section meant for arbitrary statements that are not in dispute — it's not a root of truth beyond signing some data. If you have self-evident data (e.g. this is the preimage to a hash) you don't need to check an external system.

DIDs never need to be actually resolved using their Method, right?

It depends on the DID method. If you use something like ION, you need to resolve the DID to check the signature chain. Almost everyone using UCAN today uses did:key or did:pkh, which do not require external lookups (because they're just wrappers around public keys, so "resolve themselves").

there is no example for Attenuation https://github.com/ucan-wg/spec#324-facts - can you provide one?

Facts do not attenuate, they're just statements.

what is the root entry point /? See https://github.com/ucan-wg/spec#71-canonical-json-collection

UCAN chains are held as hashmaps (pointer machines) describing graphs (CAR files). While you could analyze the graph your self and find the root, it's much easier to have one pointed as the root to "start here". We use / as the key for this one.

I don't understand how prf works. How are proofs calculated? Could you provide a practical example of the step that leads to generating the canonical representation?

Proofs are not calculated; they're asserted. The random-looking string in there is a CID. If I state that I can send email with the company account, I need to provide some proof that I'm allowed to do this, so I include a proof (another UCAN) that shows that the email owner delegated to a my boss who delegated to me that I can send from the account. Because each step is verifiable, and the capability stays at the same level or less (attenuation) on each delegation, I can prove that I have rights to send with that email.

Another scenario: I create some content, like a CRDT map. I write directly into it owner: did:key:myKey. Now I want to collaborate on updates to it. I delegate UCANs from my DID to some collaborators the ability to write new key/values, but (e.g.) not delete any. No matter where that data structure moves around, we know who we're allowed to accept updates for.

Final one: there's a data bucket on a server. It has its own DID. It delegates a UCAN to the user that requested it be created. If the admin for the bucket gets changed, it can revoke the old UCAN (by writing the CID of the old one to its metadata) and issue a new one to the new admin.

The canonical representation is "just" encoding the JWT with dag-json to ensure that the whitespace and key order are consistent for IPLD representations. This is an optimization and is never required.

Imagine a centralized server providing an API that is authorized using UCAN.
To prevent replay attacks, they must keep track of all the UCAN they have generated in some database (let's say in a table in PostgreSQL for simplicity). But they also need to insert new valid delegated UCAN that they receive, right?

To prevent replays, you need to track only the CIDs of UCANs that are delegated to you, until those tokens would expire (because once it's expired it can't be used anyways). This is part of why UCANs need nonces — to make their CIDs unique and make this really straightforward.

They also need to keep track of every UCAN that was revoked. The revoked UCAN can be a UCAN that the server never generated themselves, such as a UCAN that was delegated from a UCAN they generated. So the server must provide a public endpoint to revoke UCAN, and keep a separate table with all revoked UCAN. Am I correct?

Yes, you track revoked CIDs that you know about, until they would have been expired anyways. Depending on your exact use case, this can be the same table as mentioned above.

    How to prevent the tables of valid UCAN and revoked UCAN to get unecessarily large? I suppose the server SHOULD periodically delete from its database every UCAN that are expired (time validation)?

Two things:

1. Don't store the entire token — they're immutable so extract whatever you need from them once and then never need to look at the full token again.

2. You typically prune as they expire, yup

I don't understand Session Content ID. What does discharging an invokation means? Invoking it? Does it mean the sender wants to invoke multiple capabilities at the same time? the sender and receiver MAY agree to use the triple of CID, nonce, and signature rather than reissuing - triple but then in I don't see any triple in the provided example:

This is not required in most flows: it's basically a caching strategy for cases where you're going to have lots of interaction between two parties. If an agent delegates to you for 5 minutes, then why include the entire token again on every request in that 5 minutes if you're going to have a lot of back and forth? Just say "here's a unique nonce from the same user with the same permissions, plus a signature to prove that it's still me".