Skip to content

Latest commit

 

History

History
954 lines (728 loc) · 33.7 KB

README.md

File metadata and controls

954 lines (728 loc) · 33.7 KB

UCAN Delegation Specification

Version 1.0.0-rc.1

Editors

Authors

Dependencies

Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Abstract

This specification describes the representation and semantics for delegating attenuated authority between principals. UCAN Delegation provides a cryptographically verifiable container, batched capabilities, hierarchical authority, and a minimal syntatically-driven policy langauge.

Introduction

UCAN Delegation is a delegable certificate capability system with runtime-extensibility, ad hoc conditions, cacheability, and focused on ease of use and interoperability. Delegations act as a proofs for UCAN Invocations.

Delegation provides a way to "transfer authority without transferring cryptographic keys". As an authorization system, it is more interested in "what can be done" than a list of "who can do what". For more on how Delegation fits into UCAN, please refer to the high level spec.

UCAN Envelope Configuration

Type Tag

The UCAN envelope tag for UCAN Delegation MUST be set to ucan/[email protected].

Delegation Payload

The Delegation payload MUST describe the authorization claims, who is involved, and its validity period.

Field Type Required Description
iss DID Yes Issuer DID (sender). All DIDs are represented as string URLs.
aud DID Yes Audience DID (receiver)
sub DID | null Yes Principal that the chain is about (the Subject)
cmd String Yes The Command to eventually invoke
pol Policy Yes Policy
nonce Bytes Yes Nonce
meta {String : Any} No [Meta] (asserted, signed data) — is not delegated authority
nbf Integer (53-bits1) No "Not before" UTC Unix Timestamp in seconds (valid from)
exp Integer | null (53-bits1) Yes Expiration UTC Unix Timestamp in seconds (valid until)

Capability

A capability is the semantically-relevant claim of a delegation. They MUST take the following form:

Field Type Required Description
sub DID | null Yes The Subject that this Capability is about
cmd Command Yes The Command of this Capability
pol Policy Yes Additional constraints on eventual Invocation arguments, expressed in the UCAN Policy Language

Here is an illustrative example:

{
  // ...
  "sub": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp"
  "cmd": "/blog/post/create",
  "pol": [
    ["==", ".status", "draft"],
    ["all", ".reviewer", ["like", ".email", "*@example.com"]],
    ["any", ".tags", 
      ["or",
        ["==", ".", "news"], 
        ["==", ".", "press"]]]
  ]
}

Subject

The Subject MUST be the DID that initiated the delegation chain, or an explicit null. Declaring a DID is RECOMMENDED. For more on the null, please see the Powerline section.

{
  "sub": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp",
  // ...
}

Resource

Unlike Subjects and Commands, Resources are semantic rather than syntactic. The Resource is the "what" that a capability describes.

By default, the Resource of a capability is the Subject. This makes the delegation chain self-certifying.

{
  "sub": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp", // Subject
  // ...
}

In the case where access to an external resource is delegated, the Subject MUST own the relationship to the Resource. The Resource SHOULD be referenced by a uri key in the relevant [Conditions], except where it would be clearer to do otherwise. This MUST be defined by the Subject and understood by the executor.

{
  "sub": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp",
  "cmd": "/crud/create",
  "pol": [
    ["==", ".url", "https://example.com/blog/"], // Resource managed by the Subject
    // ...
  ],
  // ...
}

Powerline

Warning

Similar to cmd: "/" and pol: [], this feature (sub: null) is very powerful. Use with care.

A "Powerline"2 is a pattern for automatically delegating all future delegations to another agent regardless of Subject. This is achieved by explicitly setting the Subject (sub) field to null. At Validation time, the Subject MUST be substituted for the directly prior Subject given in the delegation chain. All other fields MUST continue to validate as normal (e.g. principal alignment, time bounds, and so on).

Powerline delegations MUST NOT be used as the root delegation to a resource. A priori there is no such thing as a null subject a prior.

A very common use case for Powerlines is providing a stable DID across multiple agents (e.g. representing a user with multiple devices). This enables the automatic sharing of authority across their devices without needing to share keys or set up a threshold scheme. It is also flexible, since a Powerline delegation MAY be revoked.

sequenceDiagram
    autonumber

    participant Email Server
    participant Alice Root
    participant Alice's Phone
    participant Alice's Tablet
    participant Alice's Laptop

    Alice Root ->> Alice's Phone: Delegate {sub: null, cmd: "/"}
    Alice Root ->> Alice's Tablet: Delegate {sub: null, cmd: "/"}
    Alice Root ->> Alice's Laptop: Delegate {sub: null, cmd: "/"}

    Email Server ->> Alice Root: Delegate {sub: "did:example:email", cmd: "/msg/send"}

    Alice's Tablet -->> Email Server: INVOKE! {sub: "did:example:email", cmd: "/msg/send", proofs: [❹,❷]}
Loading

Powerlines MAY include other restrictions, such as time bounds, Commands, and Policies. For example, the ability to automatically redelegate read-only access to arbitrary CRUD resources could be expressed as:

{
  "iss": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp",
  "aud": "did:key:zQ3shokFTS3brHcDQrn82RUDfCZESWL1ZdCEJwekUDPQiYBme",
  "sub": null, // 👈 ⚡ Powerline
  "cmd": "/crud/read",
  "pol": [],
  // ...
}

Command

The Command MUST be a / delimited path describing set of commands delegated. Delegation covers exact Command specified and all the commands described by a paths nested under that specified command.

Note

The command path syntax is designed to support forward compatible protocol extensions. Backwards-compatibl️️️️️️️️️️e capabilities MAY be introduced as command subpaths.

Warning

By definition "/" implies all of the commands available on a resource, and SHOULD be used with great care.

Policy

UCAN Delegation uses predicate logic statements extended with jq-inspired selectors as a policy language. Policies are syntactically driven, and MUST constrain the args field of an eventual Invocation.

A Policy is always given as an array of predicates. This top-level array is implicitly treated as a logical and, where args MUST pass validation of every top-level predicate.

Policies are structured as trees. With the exception of subtrees under any, or, and not, every leaf MUST evaluate to true.

A Policy is an array of statements. Every statement MUST take the form [operator, selector, argument] except for negation which MUST take the form ["not", statement].

-- Statements

type Statement union {
  | Equality
  | Inequality
  | Connective
  | Negation
  | Quantifier
}

-- Equality

type EqOp enum {
  | Eq ("==")
  | Neq ("!=")
}

type Equality struct {
  op EqOp
  sel Selector
  val Any
} representation tuple

type LikeOp enum {
  | Like ("like")
}

type Like struct {
  op LikeOp
  sel Selector
  str Wildcard
} representation tuple

-- Inequality

type IneqOp enum {
  | GT  (">")
  | GTE (">=")
  | LT  ("<")
  | LTE ("<=")
}

type Inequality struct {
  op IneqOp
  sel Selector
  val Number
} representation tuple

-- Connectives

type NegateOp {
  | Not ("not")
}

type Negation struct {
  op   NegateOp
  smts [Statement]
} representation tuple

type ConnectiveOp enum {
  | And ("and")
  | Or  ("or")
}

type Connective struct {
  op   ConnectiveOp
  smts [Statement]
} representation tuple

-- Quantification

type QuantifierOp enum {
  | All ("all")
  | Any ("any")
}

type Quantifier struct {
  op  QuantiefierOp
  sel Selector
  smt Statement
} representation tuple

-- Primitives

type Selector = string

type Number union {
  | NumInt   int
  | NumFloat float
} representation kinded

type Wildcard = string

Comparisons

Operator Argument(s) Example
== Selector, IPLD ["==", ".a", [1, 2, {"b": 3}]]
< Selector, (integer | float) ["<", ".a", 1]
<= Selector, (integer | float) ["<=", ".a", 1]
> Selector, (integer | float) [">", ".a", 1]
>= Selector, (integer | float) [">=", ".a", 1]

Literal equality (==) MUST match the resolved selecor to entire IPLD argument. This is a "deep comparison".

Numeric inequalities MUST be agnostic to numeric type. In other words, the decimal representation is considered equivalent to an integer (1 == 1.0 == 1.00). Attempting to compare a non-numeric type MUST return false and MUST NOT throw an exception.

Glob Matching

Operator Argument(s) Example
like Selector, Pattern ["like", ".email", "*@example.com"]

Glob patterns MUST only include one specicial character: * ("wildcard"). There is no single character matcher. As many *s as desired MAY be used. Non-wildcard *-literals MUST be escaped ("\*"). Attempting to match on a non-string MUST return false and MUST NOT throw an exception.

The wildcard represents zero-or-more characters. The following string literals MUST pass validation for the pattern "Alice\*, Bob*, Carol.:

  • "Alice*, Bob, Carol."
  • "Alice*, Bob, Dan, Erin, Carol."
  • "Alice*, Bob , Carol."
  • "Alice*, Bob*, Carol."

The following MUST NOT pass validation for that same pattern:

  • "Alice*, Bob, Carol" (missing the final .)
  • "Alice*, Bob*, Carol!" (final . MUST NOT be treated as a wildcard)
  • "Alice, Bob, Carol." (missing the * after Alice)
  • "Alice Cooper, Bob, Carol." (the * after Alice is an escaped literal in the pattern)
  • " Alice*, Bob, Carol. " (whitespace in the pattern is significant)

Connectives

Connectives add context to their enclosed statement(s).

Operator Argument(s) Example
and [Statement] ["and", [[">", ".a", 1], [">", ".b", 2]]
or [Statement] ["or", [[">", ".a", 1], [">", ".b", 2]]
not Statement ["not", [">", ".a", 1]]

And

and MUST take an arbitrarily long array of statements, and require that every inner statement be true. An empty array MUST be treated as true.

// Data
{ name: "Katie", age: 35, nationalities: ["Canadian", "South African"] }

["and", []]
// ⬆️  true

["and", [
  ["==", ".name", "Katie"], 
  [">=", ".age", 21]
]]
// ⬆️  true

["and", [
  ["==", ".name", "Katie"], 
  [">=", ".age", 21], 
  ["==", ".nationalities", ["American"]] // ️⬅️  false
]]
// ⬆️  false

Or

or MUST take an arbitrarily long array of statements, and require that at least one inner statement be true. An empty array MUST be treated as true.

// Data
{ name: "Katie", age: 35, nationalities: ["Canadian", "South African"] }

["or", []]
// ⬆️  true

["or", [
  ["==", ".name", "Katie"], // ⬅️  true
  [">", ".age", 45] 
]]
// ⬆️  true

Not

not MUST invert the truth value of the inner statement. For example, if ["==", ".a", 1] were false (.a is not 1), then ["not", ["==", ".a", 1]] would be true.

// Data
{ name: "Katie", nationalities: ["Canadian", "South African"] }

["not", 
  ["and", [
    ["==", ".name", "Katie"], 
    ["==", ".nationalities", ["American"]] // ⬅️  false
]]
// ⬆️  true

Quantification

When a selector resolves to a collection (an array or map), quantifiers provide a way to extend and and or to their contents. Attempting to quantify over a non-collection MUST return false and MUST NOT throw an exception.

Quantifying over an array is straightforward: it MUST apply the inner statement to each array value. Quantifying over a map MUST extract the values (discarding the keys), and then MUST proceed onthe values the same as if it were an array.

Operator Argument(s) Example
all Selector, [Statement] ["all", ".a" [">", ".b", 1]]
any Selector, [Statement] ["any", ".a" [">", ".b", 1]]

all extends and over collections. any extends or over collections. For example:

const args = {"a": [{"b": 1}, {"b": 2}, {"z": [7, 8, 9]}]}
const statement = ["all", ".a", [">", ".b", 0]]

// Outer Selector Substitution
["all", [{"b": 1}, {"b": 2}, {"z": [7, 8, 9]}], [">", ".b", 0]]

// Predicate Reduction
["and", [
  [">", 1, 0],
  [">", 2, 0],
  [">", null, 0]
]]

["and", [ 
  true,
  true,
  false // ⬅️
]]

false // ❌
const args = {"a": [{"b": 1}, {"b": 2}, {"z": [7, 8, 9]}]}
const statement = ["any", ".a", ["==", ".b", 2]]

// Reduction
["any", [{"b": 1}, {"b": 2}, {"z": [7, 8, 9]}], ["==", ".b", 2]]

["or", [
  ["==", 1, 2],
  ["==", 2, 2],
  ["==", null, 2]
]]

["or", [
  false,
  true, // ⬅️
  false
]]

true // ✅

Nested Quantification

Quantified statements MAY be nested. For example, the below states that someone with the email [email protected] is required to be among the receipts of every newsletter.

["all", ".newsletters",
  ["any", ".recipients", 
    ["==", ".email", "[email protected]"]]]

Selectors

Selector syntax is closely based on jq's "filters". They operate on an Invocation's args object.

Selectors MUST only include the following features:

Selector Name Examples Notes
Identity . Take the entire argument
Dotted field name .foo, .bar0_ Shorthand for selecting in a map by key (with exceptions, see below)
Unambiguous field name ["."], ["$_*"], ["1"] Select in a map by arbitrary key
Collection values [] Expands out all of the children that match the remaining path. On lists this is a noop. On maps, this extracts values.
List index [0], [42] The list element of a list by 0-index.
Negative list index [-1], [-42] The list element by index from the end. -1 is the index for the last element.
List slices [7:11], [2:], [:42], [0:-2] The range of elements by their indices.
Optional .foo?, ["nope"]? Returns null on what would otherwise fail

Every selection MUST begin and/or end with a single dot. Multiple dots (e.g. .., ...) MUST NOT be used anywhere in a selector.

The optional operator is idempotent, and repeated optionals (.foo???) MUST be treated as a single one.

For example, consider the following args from an Invocation:

{
  "args": {
    "from": "[email protected]",
    "to": ["[email protected]", "[email protected]", "[email protected]"],
    "cc": ["[email protected]"],
    "title": "Meeting Confirmation",
    "body": "I'll see you on Tuesday"
  }
}
Selector Returned Value 
"."
 
{
  "from": "[email protected]",
  "to": ["[email protected]", "[email protected]", "[email protected]"],
  "cc": ["[email protected]"],
  "title": "Meeting Confirmation",
  "body": "I'll see you on Tuesday"
}
 
".title"
 
"Meeting Confirmation"
 
".cc"
 
["[email protected]"]
 
".to[1]"
 
"[email protected]"
 
".to[-1]"
 
"[email protected]"
 
".to[99]?"
 
null

Selecting on Bytes

Bytes MAY be selected into. When doing so, they MUST be treated as a byte array ([u8]), and MUST NOT be treated as a Base64 string or any other representation.

// DAG-JSON
{ "/": { "bytes": "1qnBjPjE" } }

// Hexadecimal
0xd6 0xa9 0xc1 0x8c 0xf8 0xc4

// Selector
".[3]"
// ⬆️  0x8c = 140

Differences from jq

jq is a much larger language than UCAN's selectors. jq includes features like pipes, arithmatic, regexes, assignment, recursive descent, and so on which are not supported in the UCAN Policy language, and thus MUST NOT be implemented in UCAN.

jq produces streams of values (a distrinct concept from arrays), in contrast to UCAN argument selectors which always return an IPLD value. This introduces the primary difference between jq and UCAN argument selectors is how to treat output of the optional (?) operator: UCAN's optional selector operator MUST return null for the failure case.

There are FIXME

Validation

Validation involves substituting the values from the args field into the Policy, and evaluating the predicate. Since Policies are tree structured, selector substitution and predicate evaluation MAY proceed in any order.

If a selector cannot be resolved (there is no value at that path), the associated statement MUST return false, and MUST NOT throw an exception. Note that for consistent semantics, selecting a missing keys on a map MUST return null (but nested selectors without an optional MUST then fail the predicate).

Below is a step-by-step evaluation example:

{ // Invocation
  "cmd": "/msg/send",
  "args": {
    "from": "[email protected]",
    "to": ["[email protected]", "[email protected]"],
    "title": "Coffee",
    "body": "Still on for coffee"
  },
  // ...
}

{ // Delegation
  "cmd": "/msg",
  "pol": [
    ["==", ".from", "[email protected]"],
    ["any", ".to", ["like", ".", "*@example.com"]]
  ],
  // ...
}
[ // Extract policy
  ["==", ".from", "[email protected]"],
  ["any", ".to", ["like", ".", "*@example.com"]]
]

[ // Resolve selectors
  ["==", "[email protected]", "[email protected]"],
  ["any", ["[email protected]", "[email protected]"], ["like", ".", "*@example.com"]]
]

[ // Expand quantifier
  ["==", "[email protected]", "[email protected]"],
  ["or", [
    ["like", "[email protected]", "*@example.com"]
    ["like", "[email protected]", "*@example.com"]]
  ]
]

[ // Evaluate first predicate
  true,
  ["or", [
    ["like", "[email protected]", "*@example.com"]
    ["like", "[email protected]", "*@example.com"]]]
]

[ // Evaluate second predicate's children
  true,
  ["or", [true, false]]
]


[ // Evaluate second predicate
  true, 
  true
]

// Evaluate top-level `and`
true

Any arguments MUST be taken verbatim and MUST NOT be further adjusted. For more flexible validation of Arguments, use [Conditions].

Note that this also applies to arrays and objects. For example, the to array in this example is considered to be exact, so the Invocation fails validation in this case:

// Delegation
{
  "cmd": "/email/send",
  "pol": [
    ["==", ".from", "[email protected]"],
    ["any", ".to", ["like", ".", "*@example.com"]]
  ]
  // ...
}

// VALID Invocation
{
  "cmd": "/email/send",
  "args": {
    "from": "[email protected]",
    "to": ["[email protected]", "[email protected]"],
    "title": "Coffee",
    "body": "Still on for coffee"
  },
  // ...
}

// INVALID Invocation
{
  "cmd": "/email/send",
  "args": {
    "from": "[email protected]",
    "to": ["[email protected]"], // No match for `*@example.com`
    "title": "Coffee",
    "body": "Still on for coffee"
  },
  // ...
}

Semantic Conditions

Other semantic conditions that are not possible to fully express syntactically (e.g. current day of week) MUST be handled as part of Invocation execution. This is considered out of scope of the UCAN Policy language. The RECOMMENDED strategy to express constrains that involve side effects (like day of week) is to include that infromation in the argument shape for that Command (i.e. have a "day_of_week": "friday" field).

Token Validation

Validation of a UCAN chain MAY occur at any time, but MUST occur upon receipt of an Invocation prior to execution. While proof chains exist outside of a particular delegation (and are made concrete in UCAN Invocations), each delegate MUST store one or more valid delegations chains for a particular claim.

Each capability has its own semantics, which needs to be interpretable by the Executor. Therefore, a validator MUST NOT reject all capabilities when one that is not relevant to them is not understood. For example, if a Condition fails a delegation check at execution time, but is not relevant to the invocation, it MUST be ignored.

If any of the following criteria are not met, the UCAN Delegation MUST be considered invalid:

  1. Time Bounds
  2. Principal Alignment
  3. Signature Validation

Additional constraints MAY be placed on Delegations by specs that use them (notably UCAN Invocation).

Time Bounds

A UCAN's time bounds MUST NOT be considered valid if the current system time is before the nbf field or after the exp field. This is called the "validity period." Proofs in a chain MAY have different validity periods, but MUST all be valid at execution-time. This has the effect of making a delegation chain valid between the latest nbf and earliest exp.

// Pseudocode

const ensureTime = (delegationChain, now) => {
  delegationChain.forEach((ucan) => {
    if (!!ucan.nbf && now < can.nbf) {
      throw new Error(`Delegation is not yet valid, but will become valid at ${ucan.nbf}`)
    }

    if (ucan.exp !== null && now > ucan.exp) {
      throw new Error(`Delegation expired at ${ucan.exp}`)
    }
  })
}

Principal Alignment

In delegation, the aud field of every proof MUST match the iss field of the UCAN being delegated to. This alignment MUST form a chain back to the Subject for each resource.

This calculation MUST NOT take into account DID fragments. If present, fragments are only intended to clarify which of a DID's keys was used to sign a particular UCAN, not to limit which specific key is delegated between. Use did:key if delegation to a specific key is desired.

flowchart RL
    invoker((&nbsp&nbsp&nbsp&nbspDan&nbsp&nbsp&nbsp&nbsp))
    subject((&nbsp&nbsp&nbsp&nbspAlice&nbsp&nbsp&nbsp&nbsp))

    subject -- controls --> resource[(Storage)]
    rootCap -- references --> resource

    subgraph Delegations
        subgraph root [Root UCAN]
            subgraph rooting [Root Issuer]
                rootIss(iss: Alice)
                rootSub(sub: Alice)
            end

            rootCap("cap: (Storage, crud/*)")
            rootAud(aud: Bob)
        end

        subgraph del1 [Delegated UCAN]
            del1Iss(iss: Bob) --> rootAud
            del1Sub(sub: Alice)
            del1Aud(aud: Carol)
            del1Cap("cap: (Storage, crud/*)") --> rootCap


            del1Sub --> rootSub
        end

        subgraph del2 [Delegated UCAN]
            del2Iss(iss: Carol) --> del1Aud
            del2Sub(sub: Alice)
            del2Aud(aud: Dan)
            del2Cap("cap: (Storage, crud/*)") --> del1Cap

            del2Sub --> del1Sub
        end
    end

     subgraph inv [Invocation]
        invIss(iss: Dan)
        args("args: [Storage, crud/update, (key, value)]")
        invSub(sub: Alice)
        prf("proofs")
    end

    invIss --> del2Aud
    invoker --> invIss
    args --> del2Cap
    invSub --> del2Sub
    rootIss --> subject
    rootSub --> subject
    prf --> Delegations
Loading

Signature Validation

The [Signature] field MUST validate against the iss DID from the [Payload].

Acknowledgments

Thank you to Brendan O'Brien for real-world feedback, technical collaboration, and implementing the first Golang UCAN library.

Many thanks to Hugo Dias, Mikael Rogers, and the entire DAG House team for the real world feedback, and finding inventive new use cases.

Thank you Blaine Cook for the real-world feedback, ideas on future features, and lessons from other auth standards.

Many thanks to Brian Ginsburg and Steven Vandevelde for their many copy edits, feedback from real world usage, maintenance of the TypeScript implementation, and tools such as ucan.xyz.

Many thanks to Christopher Joel for his real-world feedback, raising many pragmatic considerations, and the Rust implementation and related crates.

Many thanks to Christine Lemmer-Webber for her handwritten(!) feedback on the design of UCAN, spearheading the OCapN initiative, and her related work on ZCAP-LD.

Thanks to Benjamin Goering for the many community threads and connections to W3C standards.

Thanks to Michael Muré and Steve Moyer at Infura for their detailed feedback on the selector design and thoughts on ANBF codegen, and an updated Golang UCAN implementation.

Thanks to Juan Caballero for the numerous questions, clarifications, and general advice on putting together a comprehensible spec.

Thank you Dan Finlay for being sufficiently passionate about OCAP that we realized that capability systems had a real chance of adoption in an ACL-dominated world.

Thanks to the entire SPKI WG for their closely related pioneering work.

Many thanks to Alan Karp for sharing his vast experience with capability-based authorization, patterns, and many right words for us to search for.

We want to especially recognize Mark Miller for his numerous contributions to the field of distributed auth, programming languages, and computer security writ large.

Footnotes

  1. JavaScript has a single numeric type (Number) for both integers and floats. This representation is defined as a IEEE-754 double-precision floating point number, which has a 53-bit significand. ↩ ↩2

  2. For those familiar with design patterns for object capabilities, a "Powerline" is like a Powerbox but adapted for the partition-tolerant, static token context of UCAN. ↩