Skip to main content

COG-17: Capability Granting

Status:      Draft
Version:     0.1
Created:     2026-07-19
Authors:     Mike Anderson
Work in Progress

This specification is under active development. Structure and details may change significantly based on implementation experience and community feedback.

Related specifications

COG-13: Agent Capabilities defines what capabilities are — their structure, resource and ability matching, and runtime enforcement. This document defines how they move: what a principal may grant, how grants are issued and signed, how delegation attenuates authority, and how issued tokens are trusted. Consent surfaces that confer authority — such as Human-in-the-Loop responses (COG-16) — reference this specification rather than defining granting semantics of their own.

This standard specifies capability granting on the Covia Grid — the transfer of authority between principals.

Purpose​

Possession of authority and transfer of authority are different problems. COG-13 answers "may this caller do this, here, now?". This COG answers the complementary questions: "what may this principal give away, to whom, and how does the recipient prove they received it?"

The granting model rests on five principles:

  • Provenance — every unit of authority traces back, through an unbroken signed chain, to a root that owned it
  • No amplification — a grantor can confer at most what they hold; delegation can only narrow, never widen
  • Production-gated granting — new, chain-free authority is minted only at granting surfaces, for callers holding the corresponding granting right; chain delegation of held abilities is transitive and visible, never silent
  • Explicit audience — authority is granted to a principal, never to a bearer; possession of a token by anyone other than its audience confers nothing
  • Time-bounded — granted authority expires; permanence requires re-issuance, not a permanent token
  • Verifiability — grants are verifiable offline wherever possible, so authority crosses venue boundaries without callbacks to the grantor

Terminology​

See COG-1: Architecture for Grid terminology, COG-2 for DIDs, and COG-13 for capabilities.

TermDefinition
PrincipalAn identity that can hold and confer authority — a user, agent, or venue, identified by DID
GrantorThe principal conferring authority
GranteeThe principal receiving authority — the audience of the issued token
GrantA capability {with, can} conferred by a grantor on a grantee, with an expiry
Delegation tokenA signed token (UCAN, COG-3) encoding one or more grants from an issuer to an audience
Grantable authorityThe total authority a grantor is able to confer: root authority plus delegable held authority
Root authorityAuthority a principal holds by owning a resource; requires no proof beyond ownership
Proof chainThe sequence of delegation tokens linking a presented grant back to a root authority
AttenuationThe narrowing of authority at each delegation hop
Granting rightThe meta-ability grant/<ability> — the right to have a grant of <ability> minted or attested on one's instruction at a granting surface, distinct from the right to exercise <ability>
Self-sovereign issuanceA grant signed by the grantor's own key
Venue-attested issuanceA grant signed by a venue on the instruction of an authenticated grantor (custodial model)

Grantable Authority​

A principal's grantable authority is the union of:

  1. Root authority — the resources the principal owns. Every DID-rooted resource (a user's namespaces, an agent's scoped identity) is grantable by its owner without any supporting proof: ownership is the authority.
  2. Held granting rights — grant/… capabilities delegated to the principal by others (see Granting rights). A granting right is exercisable only at a granting surface, together with its proof chain, and only within the bounds of what was received.

A grant MUST lie within the grantor's grantable authority. There is no third source: a principal cannot grant what they neither own nor hold granting rights over, and no granting surface — an issuance operation, a HITL approval (COG-16), or anything else — can manufacture authority. Granting surfaces are consent mechanisms over this model, not sources of power.

Granting rights​

The right to use an ability and the right to confer it are distinct, and the distinction is expressed in the ability hierarchy itself (COG-13): for any ability X, the meta-ability grant/X is the right to issue grants of X.

{ "with": "w/reports/", "can": "grant/crud/read", "exp": 1798000000 }

Alice issuing this to Bob lets Bob grant crud/read on Alice's w/reports/ to others. It does not let Bob read w/reports/ himself — grant/crud/read does not cover crud/read. Use and stewardship are separate rights, conferred together only when both are intended.

The scheme composes under the standard prefix-coverage rules, including recursively:

Held abilityA surface may mintA surface may NOT mint
grant/crud/readcrud/readcrud/write; any grant/…
grant/crudcrud and any crud/…any grant/…
grant/grant/crudgrant/crud, grant/crud/read, …crud/read (no direct use-grants)
grantany ability, granting rights included—

Two distinct mechanisms, structurally disjoint. Holding a use-ability X lets a principal chain-delegate a narrowed X onward under standard transitive attenuation — self-serve, no granting right needed, and visible: the proof chain names every delegator, so re-delegation is audited rather than blocked (blocking would be illusory — a holder of crud/read can always proxy the data out-of-band). Holding grant/X lets a granting surface mint fresh, chain-free authority on the principal's instruction — needed when the recipient requires a clean root (cross-venue trust, no chain disclosure), or when the steward holds no use-right at all. Because grant/X does not cover X, a granting right can never be chained into a use-right: it is exercisable only through a producing surface.

An agent acting under its owner's identity (the user-scoped model of COG-13) exercises the owner's own authority beneath a self-attenuated ceiling — no re-delegation is involved and no granting right is needed. Granting rights matter when authority crosses to a different principal.

No amplification​

At every delegation hop, the conferred capability MUST be covered by the issuer's own authority at that hop, under the resource and ability matching rules of COG-13. The effective authority of a chained grant is the intersection of every hop from root to leaf: each link can narrow the resource scope, the ability, and the validity window, and can never widen any of them. Verifiers MUST enforce this per hop, fail-closed — a chain with a single amplifying link conveys nothing.

Note what verifiers do not check: granting rights. Chain delegation of held use-abilities is transitive by design (standard UCAN semantics), with the chain itself as the audit record. The grant/… rules of this COG bind token production — a granting surface refuses to mint what the caller may not grant — not chain resolution. Verification stays entirely grant-agnostic.

Granting is not attenuation​

Two operations on authority must not be confused:

  • Self-attenuation — a principal narrowing their own effective authority (e.g. a session ceiling, an agent's caps vector, COG-13). This creates no new authority and needs no issuance: it only ever shrinks what the same principal can do.
  • Granting — conferring authority on a different principal. This always requires issuance of a delegation token audienced to the grantee.

The asymmetry is deliberate and security-relevant: narrowing paths can never be used to widen, and widening (for someone else) exists only through the explicit, signed, auditable issuance path defined here.

Grant Structure​

A grant is a capability as defined by COG-13, plus a validity bound:

{ "with": "w/reports/", "can": "crud/read", "exp": 1795000000 }
FieldTypeDescription
withstringResource, per COG-13 resource matching. A bare path denotes the token issuer's own namespace, resolved at evaluation time against the token's signed iss (which always travels with the grant); a custodial issuer therefore writes the principal's absolute DID URL at issuance, since its own iss is not the principal. A DID URL form addresses another principal's resource (valid only when the grantor holds a granting right over it)
canstringAbility, per the COG-13 ability hierarchy
expintegerExpiry (Unix seconds). REQUIRED on issued grants — see Expiry
nbobjectOPTIONAL caveats constraining use, per COG-13

Grants are carried in the attenuations (att) field of a delegation token; the token contributes the issuer (grantor), audience (grantee), validity window, and proof chain (COG-3).

Issuance​

Signing models​

Self-sovereign issuance. The grantor signs the token with their own key. Because root ownership of a DID-rooted resource is verifiable from the DID itself, a self-sovereign chain verifies offline, anywhere: any venue can check that the root issuer owns the root resource and that every hop attenuates correctly, without trusting any intermediary or calling home. This is the preferred model wherever the grantor's client holds their key.

Venue-attested issuance (custodial). The venue signs on the instruction of an authenticated grantor — necessary when the venue custodies the user's identity (e.g. users authenticated by session rather than by key). The token's root issuer is the venue, so its acceptance elsewhere is subject to the verifier's trust policy for venue-attested roots (COG-15). Venues MUST record which authenticated principal instructed each attested issuance.

The two models differ only at the root; attenuation, audience binding, and verification are identical from the first delegation hop onward.

The issuance operation​

Venues SHOULD expose granting as a standard operation (COG-7):

Input fieldTypeDescription
audstringREQUIRED. Grantee DID
attarrayREQUIRED, non-empty. The grants to confer
expintegerREQUIRED. Token expiry (Unix seconds); MUST NOT exceed venue policy caps
prfarrayProof tokens, when granting held (non-root) authority

Output: the signed delegation token.

The venue MUST verify, before signing, that every att entry lies within the caller's grantable authority — root ownership for the caller's own resources, or a proof chain establishing a granting right (grant/…) over the resource — and MUST refuse otherwise. A bare path in the request is absolutised to the caller's DID before signing: in a venue-signed token a stored-bare path would denote the venue's own namespace, not the caller's. (The operation-level ability ucan/delegate (COG-13) gates access to the issuance surface itself; granting rights govern what may be issued through it.) Issuance is a mutating act of consequence: it MUST require an authenticated caller and MUST be deniable by capability policy like any other operation (COG-10).

Delivery​

How an issued token reaches its grantee is out of scope: Job outputs (COG-16), agent messages (COG-9), API responses, or out-of-band channels are all acceptable. Delivery requires no confidentiality for authority purposes — a token is inert in any hands but its audience's — though tokens MAY reveal information (resource paths, relationships) that warrants care.

Verification and Trust​

Verification separates two layers, both fail-closed:

  1. Integrity — every token in the chain carries a valid signature by its issuer; every token is within its validity window; every link connects (each proof's audience is the next token's issuer); validity windows narrow monotonically toward the leaf.
  2. Authority — the presented grant is covered by the leaf token's attenuations; each hop attenuates, per No amplification; and the root is authoritative for the resource: either the root issuer owns it (self-sovereign — universally acceptable), or the root is a venue the verifier trusts for attestation (COG-15).

A verifier's own identity is irrelevant to the result: the same chain yields the same verdict on any venue, which is what lets granted authority travel with its holder across the grid (COG-15).

Expiry and Revocation​

  • Every issued grant MUST be time-bounded. Venues MUST cap requested expiries by policy and SHOULD apply a conservative default lifetime when none is requested. Indefinite grants MUST NOT be issued.
  • Delegation tokens are not revocable before expiry in this version. The design compensates by making expiry cheap: prefer short-lived grants re-issued on demand over long-lived ones. Long-lived authority SHOULD be modelled as a standing relationship at the granting surface (e.g. a recurring approval), not as a long-lived token.
  • Revocation mechanisms (revocation lists, status endpoints, chain-invalidation) are future work for this COG.

Granting Surfaces​

Any mechanism through which a grantor consents to a grant is a granting surface. Surfaces own consent UX and context; this COG owns the semantics beneath all of them:

SurfaceSpecified inNotes
Direct issuance operationthis COGProgrammatic granting by an authenticated principal
HITL responseCOG-16Grants bound to explicit human choices, echo-consented
Venue relay delegationCOG-15A venue/relay grant authorising a venue to act as delegate on cross-venue hops
Identity tokenCOG-15An empty-att token — authentication, not a grant; listed to mark the boundary
Agent attenuation (caps)COG-13Not a grant — self-attenuation of the owner's authority, no issuance involved

A granting surface MUST ensure the grantor's informed consent: the grantor (or their authenticated client) sees resource, ability, and expiry of every grant before issuance. The echo-consent rule of COG-16 is the reference design for human surfaces.

Security Considerations​

  • No bearer authority. Audience binding is the backbone: intercepted, logged, or relayed tokens confer nothing on their holders, and a deputy presenting a caller's proofs cannot convert them to its own use. Weakening audience binding for convenience (bearer-style grants) is not permitted by this specification.
  • Custodial root risk. A venue that issues attested grants can, if compromised, mint arbitrary authority over the resources of every user it custodies. Verifier trust policies for venue-attested roots (COG-15) bound the blast radius; self-sovereign issuance avoids the exposure entirely and SHOULD be preferred where keys permit.
  • Amplification defects. The most dangerous implementation bug is a verifier that checks the leaf but not every hop. Verification MUST walk the full chain to the root and MUST fail closed on any unverifiable link.
  • Re-delegation is audited, not prevented. A holder of a use-ability can chain-delegate it (or simply proxy the resource); the proof chain names every delegator. Grantors who cannot accept that exposure should not grant the ability — or should grant it gated (nb.gate, COG-13).
  • Over-broad grants. Grantors SHOULD confer the narrowest resource, weakest ability, and shortest expiry that serves the purpose; granting surfaces SHOULD make narrow grants the path of least resistance.
  • Granting rights are the sharpest tool. A grant/… capability multiplies exposure: its holder can mint authority for arbitrary third parties for as long as it lives. Confer granting rights narrowly (specific abilities, specific subtrees), briefly, and rarely; recursive rights (grant/grant/…) more rarely still.
  • Consent integrity. An issuance made without the grantor's informed consent is an authority theft regardless of cryptographic validity. Surfaces MUST NOT issue beyond what was displayed and consented to.
  • Chain complexity. Verifiers MAY bound proof-chain depth and token size to prevent resource-exhaustion attacks via pathological chains.
  • Irrevocability. Until revocation exists, every issued token is a commitment for its full lifetime. Expiry caps are the safety net; venues SHOULD set them accordingly.

Examples​

Root grant (self-sovereign)​

Alice grants her agent read access to her reports for a week, signing with her own key. Token payload sketch:

{
  "iss": "did:key:z6MkAlice...",
  "aud": "did:key:z6MkAgent...",
  "exp": 1795600000,
  "att": [ { "with": "did:key:z6MkAlice.../w/reports/", "can": "crud/read" } ],
  "prf": []
}

Empty prf: Alice owns the resource, so her signature is the root authority. Any venue verifies this offline.

Chain delegation (transitive, visible)​

Bob holds crud/read on Carol's shared workspace and chain-delegates a narrowed form to his analyst — self-serve, no granting right involved:

{
  "iss": "did:key:z6MkBob...",
  "aud": "did:key:z6MkAnalyst...",
  "exp": 1795300000,
  "att": [ { "with": "did:key:z6MkCarol.../w/shared/2026/", "can": "crud/read" } ],
  "prf": [ "<Carol → Bob crud/read token>" ]
}

Every hop narrows (resource, ability, expiry); the chain roots at Carol, who owns the resource; and the chain itself is the audit record — any verifier sees that Bob delegated. Transitive by design: Carol granting Bob read accepts that Bob can pass the data on (he could proxy it regardless); the chain makes it visible.

Delegated granting (stewardship, via a surface)​

Carol lets Bob manage read access to her shared workspace — without being able to read it himself:

{
  "iss": "did:key:z6MkCarol...",
  "aud": "did:key:z6MkBob...",
  "exp": 1798000000,
  "att": [ { "with": "did:key:z6MkCarol.../w/shared/", "can": "grant/crud/read" } ],
  "prf": []
}

Bob cannot chain this into a read grant himself (grant/crud/read does not cover crud/read — the chain would fail attenuation). Instead he instructs a granting surface, presenting Carol's token as proof:

// ucan:issue, called by Bob
{ "aud": "did:key:z6MkAnalyst...",
  "att": [ { "with": "did:key:z6MkCarol.../w/shared/2026/", "can": "crud/read" } ],
  "exp": 1795300000,
  "prf": [ "<Carol → Bob grant/crud/read token>" ] }

The surface verifies Bob's grantable authority covers grant/crud/read on a covering resource, then mints a fresh, chain-free token (venue-attested; accepted per the verifier's COG-15 trust policy). Had Carol granted Bob nothing, the surface would refuse — the granting rule binds production, not resolution.

Venue-attested grant from a HITL approval​

A responder approves a HITL ask carrying an offered grant (COG-16). Their venue custodies their identity, so it issues the token: iss = the venue's DID, aud = the requesting agent, att = exactly the echoed grants, exp capped by policy. The agent presents it on later requests; venues that trust the issuing venue for attestation accept it, per their COG-15 trust policy.