Skip to content

Key Delegation v1

Source schema: doc/schemas/key-delegation.v1.schema.json

Registration and management artifact for a scoped delegation of capability-passport signing authority from a participant's sovereign key to a separate proxy key. The participant signs this artifact once to authorise the proxy key; all subsequent operational signing uses the proxy key and carries a compact DelegationProof extracted from this artifact (see capability-passport.v1 issuer_delegation). The signature payload is the canonical JSON of the COMPACT proof contract (delegation_id, proxy_key, principal_key, grants, expires_at), NOT the full artifact. The full artifact is the Seed Directory registration and audit envelope that carries this payload alongside management metadata (schema, issued_at, issuer/node_id, max_chain_depth, parent_delegation_id).

Governing Basis

Project Lineage

Requirements

Stories

Fields

Field Required Shape Description
schema yes const: key-delegation.v1 Schema discriminator. MUST be exactly key-delegation.v1.
delegation_id yes string Stable unique identifier for this delegation. MUST use the delegation:key: prefix followed by a non-empty suffix. The recommended construction is delegation:key:<unix-nanos>:<random-hex> so that ordering and uniqueness are self-evident; schema does not enforce the internal shape beyond the prefix.
proxy_key yes string Delegated Ed25519 public key in DID Key form. This is the key that will sign capability passports and revocations on behalf of issuer/participant_id for the lifetime of this delegation. The private counterpart is held by the proxy key store and MUST NOT appear anywhere in this artifact.
grants yes object Open grant map from grant type to non-empty list of target identifiers. MVP recognizes signing/capability whose targets are capability IDs (e.g. network-ledger, escrow) and signing/agora-record whose targets are Agora record-signing scopes (for example topic-scoped targets or the wildcard "*"). Additional grant types (signing/org, signing/proxy, ...) are reserved for future proposals and MUST be ignored by verifiers that do not recognise them (open-world extension semantics). The wildcard "*" is operationally convenient but semantically equivalent to full authority for the grant type; operators SHOULD prefer explicit targets.
max_chain_depth yes integer Maximum number of additional delegation hops the proxy key is authorised to create. 0 means the proxy key MUST NOT issue further key-delegation.v1 artifacts. Values greater than 0 remain schema-valid (so the artifact can travel through storage layers that pre-date sub-delegation) but MVP runtime implementations MUST reject any delegation with max_chain_depth > 0 until sub-delegation is formally specified.
parent_delegation_id no string Optional reference to the parent delegation from which this one was derived. Absent at the root of the chain (where the issuer is a direct participant key). Present on sub-delegations (max_chain_depth > 0 in an ancestor). Reserved for post-MVP sub-delegation; MVP MUST reject artifacts that set this field.
issued_at yes string RFC 3339 timestamp at which the participant issued this delegation. Informational: the signature payload does not include this field. MUST be in the past relative to local wall clock at verification time (subject to clock-skew tolerance).
expires_at yes string RFC 3339 timestamp after which this delegation MUST be treated as expired. MANDATORY: implementations MUST reject delegation artifacts lacking this field. Part of the signed compact proof payload. Recommended maximum TTL is 365 days; issuance UI SHOULD warn for values exceeding that.
issuer/participant_id yes string Canonical participant:did:key:z... identifier of the issuing participant. Its embedded public key is the principal_key that MUST verify the signature field (after canonicalization of the compact proof payload). Verifiers derive participant:did:key:... from the principal_key carried in a DelegationProof and require byte-equality with this value.
issuer/node_id yes string Node on which the issuing participant's private key resided at the moment of signing. Informational: the signature payload does not include this field. Used for audit and for correlating a delegation artifact to the node that issued it.
signature yes ref: #/$defs/ed25519Signature Ed25519 signature by the private key of issuer/participant_id (the principal_key) over the canonical JSON representation of the COMPACT delegation proof contract: {delegation_id, proxy_key, principal_key, grants, expires_at}, with principal_key being the raw did:key bytes of issuer/participant_id. The signature explicitly does NOT cover the management metadata (schema, issued_at, issuer/node_id, max_chain_depth, parent_delegation_id). This keeps the same signed bytes verifiable both from the full artifact and from an inline DelegationProof copied into a downstream signed artifact (capability-passport.v1 issuer_delegation).
co_signatures no array Reserved for post-MVP M-of-N multisig issuance. When absent, a single primary signature authorises the delegation. When present, each entry is an additional signature over the same compact proof payload by a co-issuer key authorised by an out-of-band multisig policy. MVP verifiers MUST ignore this field; MVP issuers MUST NOT emit it.

Definitions

Definition Shape Description
ed25519Signature object Ed25519 signature over the canonical JSON encoding of the compact delegation proof payload (delegation_id, proxy_key, principal_key, grants, expires_at). Object keys are sorted lexicographically; no insignificant whitespace; arrays left in original order. The canonical payload is identical to the one carried in a DelegationProof embedded in downstream signed artifacts.
## Field Semantics

schema

  • Required: yes
  • Shape: const: key-delegation.v1

Schema discriminator. MUST be exactly key-delegation.v1.

delegation_id

  • Required: yes
  • Shape: string

Stable unique identifier for this delegation. MUST use the delegation:key: prefix followed by a non-empty suffix. The recommended construction is delegation:key:<unix-nanos>:<random-hex> so that ordering and uniqueness are self-evident; schema does not enforce the internal shape beyond the prefix.

proxy_key

  • Required: yes
  • Shape: string

Delegated Ed25519 public key in DID Key form. This is the key that will sign capability passports and revocations on behalf of issuer/participant_id for the lifetime of this delegation. The private counterpart is held by the proxy key store and MUST NOT appear anywhere in this artifact.

grants

  • Required: yes
  • Shape: object

Open grant map from grant type to non-empty list of target identifiers. MVP recognizes signing/capability whose targets are capability IDs (e.g. network-ledger, escrow) and signing/agora-record whose targets are Agora record-signing scopes (for example topic-scoped targets or the wildcard "*"). Additional grant types (signing/org, signing/proxy, ...) are reserved for future proposals and MUST be ignored by verifiers that do not recognise them (open-world extension semantics). The wildcard "*" is operationally convenient but semantically equivalent to full authority for the grant type; operators SHOULD prefer explicit targets.

max_chain_depth

  • Required: yes
  • Shape: integer

Maximum number of additional delegation hops the proxy key is authorised to create. 0 means the proxy key MUST NOT issue further key-delegation.v1 artifacts. Values greater than 0 remain schema-valid (so the artifact can travel through storage layers that pre-date sub-delegation) but MVP runtime implementations MUST reject any delegation with max_chain_depth > 0 until sub-delegation is formally specified.

parent_delegation_id

  • Required: no
  • Shape: string

Optional reference to the parent delegation from which this one was derived. Absent at the root of the chain (where the issuer is a direct participant key). Present on sub-delegations (max_chain_depth > 0 in an ancestor). Reserved for post-MVP sub-delegation; MVP MUST reject artifacts that set this field.

issued_at

  • Required: yes
  • Shape: string

RFC 3339 timestamp at which the participant issued this delegation. Informational: the signature payload does not include this field. MUST be in the past relative to local wall clock at verification time (subject to clock-skew tolerance).

expires_at

  • Required: yes
  • Shape: string

RFC 3339 timestamp after which this delegation MUST be treated as expired. MANDATORY: implementations MUST reject delegation artifacts lacking this field. Part of the signed compact proof payload. Recommended maximum TTL is 365 days; issuance UI SHOULD warn for values exceeding that.

issuer/participant_id

  • Required: yes
  • Shape: string

Canonical participant:did:key:z... identifier of the issuing participant. Its embedded public key is the principal_key that MUST verify the signature field (after canonicalization of the compact proof payload). Verifiers derive participant:did:key:... from the principal_key carried in a DelegationProof and require byte-equality with this value.

issuer/node_id

  • Required: yes
  • Shape: string

Node on which the issuing participant's private key resided at the moment of signing. Informational: the signature payload does not include this field. Used for audit and for correlating a delegation artifact to the node that issued it.

signature

  • Required: yes
  • Shape: ref: #/$defs/ed25519Signature

Ed25519 signature by the private key of issuer/participant_id (the principal_key) over the canonical JSON representation of the COMPACT delegation proof contract: {delegation_id, proxy_key, principal_key, grants, expires_at}, with principal_key being the raw did:key bytes of issuer/participant_id. The signature explicitly does NOT cover the management metadata (schema, issued_at, issuer/node_id, max_chain_depth, parent_delegation_id). This keeps the same signed bytes verifiable both from the full artifact and from an inline DelegationProof copied into a downstream signed artifact (capability-passport.v1 issuer_delegation).

co_signatures

  • Required: no
  • Shape: array

Reserved for post-MVP M-of-N multisig issuance. When absent, a single primary signature authorises the delegation. When present, each entry is an additional signature over the same compact proof payload by a co-issuer key authorised by an out-of-band multisig policy. MVP verifiers MUST ignore this field; MVP issuers MUST NOT emit it.

Definition Semantics

$defs.ed25519Signature

  • Shape: object

Ed25519 signature over the canonical JSON encoding of the compact delegation proof payload (delegation_id, proxy_key, principal_key, grants, expires_at). Object keys are sorted lexicographically; no insignificant whitespace; arrays left in original order. The canonical payload is identical to the one carried in a DelegationProof embedded in downstream signed artifacts.