Understanding — Grant

PROPOSED — not yet upstreamed. Built to the ToIP spec.meta.schema.json for the dtgwg-trust-tasks-tf registry; the slug below is proposed to that namespace, not registry-accepted. The PR is pending; the registry's decision governs.

Proposed slug: understanding/grant · version 0.1 · status draft

A sealed joining party requests scoped access; the host's broker releases a delegated, expiring grant — the underlying credential never leaves the broker, and asking for it is a named refusal.

Abstract

The Understanding — Grant Trust Task converts a sealed agreement into
working access — through a broker, never by credential hand-over. The host
side holds its credentials (a session, a write token, an API key) in a broker;
a sealed joining party requests scope; the broker mints a delegated grant:
host-scoped, expiring, attributable to the grantee, and revocable without
rotating the underlying credential.

The boundary is the specification's reason to exist: the underlying credential
never leaves the broker, and a request for it is a named refusal
(rawCredentialRequested), not a policy choice. This is the same custody
instinct as vault/proxy-login —
exercise a credential without releasing it — surfaced at the moment a
trust ceremony first grants access, where the temptation to "just share the
key" is strongest.

Status of this Document

This is a draft Trust Task specification per SPEC.md §5.3; the schema MAY change without notice. Feedback via the issue tracker.

Conformance

RFC2119(https://www.rfc-editor.org/rfc/rfc2119) and RFC8174(https://www.rfc-editor.org/rfc/rfc8174) key-word conventions apply.

A conforming producer (the joining party) MUST emit a Trust Task document whose type is https://trusttasks.org/spec/understanding/grant/0.1, carrying a verifiable proof from the party that sealed the agreement, and request scope within what the seal covers.

A conforming consumer (the host broker) MUST:

Verify the proof against the sealed agreement's joining party; refuse an unknown or unsealed agreement with grantWithoutSeal.
Refuse any request shaped to obtain the underlying credential with rawCredentialRequested — including requests for unscoped grants, non-expiring grants, or the broker's own verification material.
Bound every grant: explicit host scope, explicit expiry, attributable to this grantee, and revocable at the broker without rotating the underlying credential.
Record every release and every use it mediates, so grant activity is auditable per grantee.

Payload

payload.agreementId (REQUIRED) — the sealed agreement this grant draws on.
payload.scope (REQUIRED) — the hosts and actions requested.
payload.validFor (OPTIONAL) — requested duration; the broker MAY grant less, never more.
payload.ext — extension slot per SPEC.md §4.5.1.

Request

{
  "id": "urn:uuid:39f24d52-6c70-4f2e-e091-809ab2c3d4e5",
  "type": "https://trusttasks.org/spec/understanding/grant/0.1",
  "issuer": "did:key:z6MkJoiningPartyExample",
  "recipient": "did:key:z6MkHostExample",
  "issuedAt": "2026-07-18T17:00:00Z",
  "payload": {
    "agreementId": "seal-17d02b30",
    "scope": {
      "hosts": ["workshop.host.example.com"],
      "actions": ["read", "contribute"]
    },
    "validFor": "PT12H"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2026-07-18T17:00:00Z",
    "verificationMethod": "did:key:z6MkJoiningPartyExample#z6MkJoiningPartyExample",
    "proofPurpose": "assertionMethod",
    "proofValue": "z3FXQmV6ExampleProofValueForUnderstandingGrant"
  }
}

Response

{
  "id": "urn:uuid:4a035e63-7d81-4a3f-f1a2-9ab2c3d4e5f6",
  "type": "https://trusttasks.org/spec/understanding/grant/0.1#response",
  "issuer": "did:key:z6MkHostExample",
  "recipient": "did:key:z6MkJoiningPartyExample",
  "threadId": "urn:uuid:39f24d52-6c70-4f2e-e091-809ab2c3d4e5",
  "issuedAt": "2026-07-18T17:00:02Z",
  "payload": {
    "grantRef": "grant-39f24d52",
    "material": "dg1.eyJhbGciOiJFZERTQSJ9.ExampleDelegatedGrantTokenNotTheUnderlyingCredential",
    "scope": {
      "hosts": ["workshop.host.example.com"],
      "actions": ["read", "contribute"]
    },
    "expiresAt": "2026-07-19T05:00:00Z"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2026-07-18T17:00:02Z",
    "verificationMethod": "did:key:z6MkHostExample#z6MkHostExample",
    "proofPurpose": "assertionMethod",
    "proofValue": "z58aKqExampleProofValueForUnderstandingGrantResponse"
  }
}

Security & Privacy

The response is discloses: secret: the grant material is confidential to the
grantee and MUST travel only over a confidential, mutually-authenticated
binding. The custody boundary bounds the blast radius — a leaked grant exposes
its scope until expiry or withdrawal, never the underlying credential; a
compromised joiner is contained by the same line. The broker's release-and-use
record makes grant activity attributable per grantee, which is a disclosure the
joiner accepted at the seal: mediated access is visible access. Brokers SHOULD
keep grant lifetimes short and let renewal be cheap — a short leash re-walked
beats a long one forgotten.

Assets

Source: specs/understanding/grant/0.1/ — spec.md + payload.schema.json

📎 understanding-grantpayload.schema.json spec.md

upstream: ~/dtgwg-trust-tasks-tf-mage (untracked contribution lane; upstream registry: trustoverip/dtgwg-trust-tasks-tf) · author: Mitchell Travers · the git source wins on any disagreement · (⚔️⊥⿻⊥🧙)😊

← The Trust Tasks · Welcome Visitors