Skip to main content

COG-19: HITL Self-Sovereign Token Transport

Status:      Draft
Version:     0.1
Created:     2026-07-24
Authors:     Mike Anderson

:::note Related specifications This standard extends Human-in-the-Loop requests (COG-16) with one new ask type, and complements Capability Granting (COG-17): where COG-17 has a venue mint a capability grant, this standard has the venue transport one the user signs themselves. The tokens it carries are ordinary UCANs (COG-3: Authentication Mechanisms) verified under the cross-venue trust rules of COG-15: Cross-Venue Federation and COG-10: Venue Authentication & Access Control. It introduces no new token format and no new authority primitive — only a way to route a user-signed grant from a human to a requester. :::

This standard specifies how a requester — typically a resident agent — obtains a capability token it can use on another venue, by asking its human to sign that token with their own key.

Purpose​

An agent runs on the venue that hosts it. To act on a different venue, where its owner holds resources, it needs authority that venue will accept. A venue-minted grant (COG-17) cannot serve: it is rooted in the issuing venue's authority, so any other venue rejects it. The authority that travels is a self-sovereign grant — one the resource owner signs with their own key, rooted in themselves, and therefore verifiable on any venue where they are the root authority (COG-15).

A user cannot be expected to sign such grants out of band on demand. The natural place to request one is the human-in-the-loop channel the user already watches: the agent asks, the human reviews the requested capabilities and signs — or declines. This standard defines that exchange.

The distinction it rests on​

An access token and a capability grant are the same object — a UCAN is simultaneously a delegation (att capabilities from iss to aud) and the credential the audience presents. The meaningful axis is not token-versus-grant; it is who signs the root, and therefore where the grant is valid:

Venue-minted grant (COG-17)Self-sovereign grant (this COG)
Signer / issthe venuethe user's did:key
Rooted inthe venue's authoritythe user, self-sovereignly
Valid onresources that venue controlsany venue where the user is root authority
Venue's rolemints ittransports it

A token ask carries a self-sovereign grant. It is a scoped delegation — its att is the requested capabilities — never a bare identity token that would confer the user's whole authority.

Terminology​

See COG-1: Architecture for Grid terminology, COG-16 for HITL terminology (request, ask, response, inbox), and COG-3 for UCAN terminology.

TermDefinition
Token askAn ask of type token: a request for a self-sovereign capability grant the human signs client-side
Token specThe token object on a token ask, describing the requested grant
RequesterThe principal that issued the HITL request — the token's default audience
ResponderThe human answering — the inbox owner, who signs with their own key
TransportCarrying the signed grant from responder to requester unchanged; the venue neither mints nor re-signs

Principles​

  1. The venue transports, it does not mint. For a token ask the venue never signs and never alters the grant. It carries a token the responder signed.

  2. The venue is a checked courier, not an issuer. It holds no user key and cannot forge or widen the grant. The token's integrity does not depend on trusting the venue: a compromised venue can at worst fail to deliver, or deliver a token that fails verification at its destination.

  3. Provenance, not policy. The venue verifies that the responder actually signed this grant for the requested audience with a live expiry. It does not judge the capabilities against the request — the responder is authoritative over their own key and MAY have edited them under review.

  4. Only the human answers. As for all granting-bearing HITL responses (COG-17), an agent MUST NOT answer a token ask, including one in its own owner's inbox.

  5. Self-sovereign users only. The responder's iss MUST be a did:key they can sign with. A venue-custodial identity has no client key and uses the mint path (COG-17) instead.

Specification​

The token ask​

A token ask is an ask (COG-16) with type = token and a token spec:

{
  "id": "b-access",
  "type": "token",
  "prompt": "Grant this agent read access to your invoices on venue B?",
  "required": true,
  "token": {
    "caps":     [ { "with": "<resource>", "can": "<ability>" } ],  // REQUIRED, non-empty
    "exp":      3600,            // OPTIONAL, seconds — a requested lifetime hint
    "audience": "<DID>",        // OPTIONAL — default: the request's `from`
    "venue":    "<venue DID>"   // OPTIONAL — informational, for the responder's UI
  }
}
FieldRequirementRole
capsREQUIREDThe requested capabilities, a non-empty array of {with, can}. Describes what the agent asks for; the human decides what to sign.
expOPTIONALA requested lifetime in seconds. A hint — the responder sets the actual expiry when signing.
audienceOPTIONALThe DID the signed token must be audienced to. Defaults to the request's from (the requester).
venueOPTIONALThe target venue, shown in the responder's UI. Purely informational.

The token spec is a first-class validated field. A conforming request builder MUST preserve it intact through submission.

The response​

The answer to a token ask is a signed UCAN JWT string — the grant the responder signed with their own key. It is not a boolean, an option id, or free text, and it triggers no venue minting.

Before transporting, the venue MUST verify, and reject the response on any failure:

  1. The answer is a well-formed UCAN.
  2. Its signature verifies against the responder's did:key, and its iss equals the responder's DID.
  3. Its aud equals the ask's audience (or, absent one, the requester).
  4. It carries an exp, and is within its temporal bounds.

The venue MUST NOT require att ⊆ caps, MUST NOT re-sign, and MUST NOT substitute a venue-minted token.

Delivery​

A verified token is delivered on the requester's job output, under a tokens map keyed by ask id — distinct from the token field a venue-minted grant (COG-17) uses, so the two provenances never collide.

A signed token is a secret. It MUST NOT be persisted in the durable inbox record, and SHOULD be omitted from the response's echoed answers; it is delivered only via tokens. Its leak resistance rests on its bounded exp and its audience binding: a token audienced to the requester is useless to any other principal.

Interaction with grants​

A single request MAY mix token asks with approval/option asks that carry grants (COG-17). The venue-minted grant token and the transported self-sovereign tokens are delivered independently — token and tokens respectively.

Security Considerations​

The trust reduction relative to COG-17 is the point: a minted grant depends on the venue's signature being the authority, whereas a transported grant is signed by the user and merely relayed. The venue is therefore not a trusted party for the token's integrity.

Two residual concerns are handled explicitly:

  • Leakage. The token sits, after delivery, in the requester's job record. Audience binding (The response, rule 3) ensures a leaked token is unusable by any principal but the requester; a bounded exp limits the window. Requesters SHOULD request the narrowest capabilities and shortest lifetime that suffice.

  • Substitution. A malicious venue could drop or replace the token, but cannot forge one: any substitute fails signature and audience verification at the destination. This is a liveness failure, not an authority breach.

Scope and limitations​

This standard specifies the transport — the venue's responsibility. It does not specify how a requester subsequently presents the token at the far venue, which depends on the requester's own identity:

  • An agent with its own key presents the token directly.
  • A key-less agent needs a presentable credential — an ephemeral session key whose DID the request names as audience, or a hosting-venue attestation (COG-15) — to authenticate as the token's audience.

The transport is complete and secure on its own; end-to-end use composes it with whichever presentation mechanism the requester's identity supports.