@openvtc/trust-tasks 0.28.23 → 0.28.24

package/src/messaging/mux/list/0.1/payload.ts

@@ -0,0 +1,793 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/messaging/mux/list/0.1/payload.schema.json
+ */
+
+import type { AttachView, DataIntegrityProof, Ext, GrantId, GrantState, GrantStatement, GrantView, MuxDataIntegrityProof, MuxDid, MuxRole, MuxScope, MuxScopeValue, StatementScope } from "../../../../_shared/components.js";
+
+
+/**
+ * List the delegations a requester holds as a principal, or those on a member DID it controls, a page at a time. The outer document members are owned by the framework — SPEC §6.3.
+ */
+export interface MessagingMuxListPayload {
+  /**
+   * `principal`: the grants delegated to the requester, and the session attaches on this connection. `member`: the grants on a member DID, and its current epoch.
+   */
+  as: MuxRole;
+  /**
+   * As `principal`: only grants from this member DID. As `member`: the member DID to list; absent means the requester itself.
+   */
+  did?: MuxDid;
+  /**
+   * An opaque continuation token from a previous response's `nextCursor`, bound to the requester and the other request members; a responder MUST NOT accept a cursor it did not issue.
+   */
+  cursor?: string;
+  /**
+   * The most grants to return, at most 500; the responder chooses a default (100) and MAY return fewer.
+   */
+  limit?: number;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+}
+/**
+ * The success response to a messaging/mux/list request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/messaging/mux/list/0.1#response.
+ */
+export interface MessagingMuxListResponsePayload {
+  /**
+   * The view answered, echoing the request.
+   */
+  as: MuxRole;
+  /**
+   * Grants in every state, ordered by member DID then grant identifier as principal, and by principal DID then grant identifier as member.
+   *
+   * @maxItems 500
+   */
+  grants: GrantView[];
+  /**
+   * Principal view, first page only: the session attaches on the connection that carried the request. Absent when the request did not arrive on a mux connection.
+   *
+   * @maxItems 5000
+   */
+  attachments?: AttachView[];
+  /**
+   * Member view only: the member DID's current epoch, which a new grant must carry.
+   */
+  epoch?: number;
+  /**
+   * Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`.
+   */
+  nextCursor?: string;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { AttachView, DataIntegrityProof, Ext, GrantId, GrantState, GrantStatement, GrantView, MuxDataIntegrityProof, MuxDid, MuxRole, MuxScope, MuxScopeValue, StatementScope };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/messaging/mux/list/0.1" as const;
+
+/**
+ * The earlier version of this specification that this one declares it
+ * extends (front matter `extends`, SPEC §5.2 "Declared extension"), or
+ * `null`. Only the direct declaration — follow the chain with
+ * `extendsChain` / `readForSpec`.
+ */
+export const EXTENDS: string | null = null;
+
+/**
+ * Why this version is deprecated, or `null` while it is current. A
+ * superseded or retired version is still supported, and is withdrawn from
+ * this package in a later scheduled batch (SPEC "Superseded and Withdrawn
+ * Versions").
+ */
+export const DEPRECATION: string | null = null;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = MessagingMuxListPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/messaging/mux/list/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = MessagingMuxListResponsePayload;
+
+/**
+ * This specification's payload schema, as a value.
+ *
+ * SPEC.md §7.2 item 2 is performed against this. It is shipped as data
+ * rather than only as a `.json` file because TypeScript types are erased
+ * at runtime: without a schema a consumer has nothing to validate, and
+ * every REQUIRED payload member is optional in practice. Cross-file
+ * `$ref`s are already inlined, so it needs no resolver.
+ */
+export const PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trusttasks.org/spec/messaging/mux/list/0.1",
+  "title": "Messaging — Mux List — payload",
+  "description": "List the delegations a requester holds as a principal, or those on a member DID it controls, a page at a time. The outer document members are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "as"
+  ],
+  "properties": {
+    "as": {
+      "$ref": "#/$defs/MuxRole",
+      "description": "`principal`: the grants delegated to the requester, and the session attaches on this connection. `member`: the grants on a member DID, and its current epoch."
+    },
+    "did": {
+      "$ref": "#/$defs/MuxDid",
+      "description": "As `principal`: only grants from this member DID. As `member`: the member DID to list; absent means the requester itself."
+    },
+    "cursor": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "description": "An opaque continuation token from a previous response's `nextCursor`, bound to the requester and the other request members; a responder MUST NOT accept a cursor it did not issue."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 500,
+      "description": "The most grants to return, at most 500; the responder chooses a default (100) and MAY return fewer."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext",
+      "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Messaging — Mux List — response payload",
+      "description": "The success response to a messaging/mux/list request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/messaging/mux/list/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "as",
+        "grants"
+      ],
+      "properties": {
+        "as": {
+          "$ref": "#/$defs/MuxRole",
+          "description": "The view answered, echoing the request."
+        },
+        "grants": {
+          "type": "array",
+          "maxItems": 500,
+          "items": {
+            "$ref": "#/$defs/GrantView"
+          },
+          "description": "Grants in every state, ordered by member DID then grant identifier as principal, and by principal DID then grant identifier as member."
+        },
+        "attachments": {
+          "type": "array",
+          "maxItems": 5000,
+          "items": {
+            "$ref": "#/$defs/AttachView"
+          },
+          "description": "Principal view, first page only: the session attaches on the connection that carried the request. Absent when the request did not arrive on a mux connection."
+        },
+        "epoch": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Member view only: the member DID's current epoch, which a new grant must carry."
+        },
+        "nextCursor": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "description": "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "AttachView": {
+      "title": "AttachView",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "did",
+        "scope",
+        "expiresAt",
+        "deliveryActive"
+      ],
+      "description": "One session attach on a connection.",
+      "properties": {
+        "did": {
+          "$ref": "#/$defs/MuxDid",
+          "description": "The member DID."
+        },
+        "scope": {
+          "$ref": "#/$defs/MuxScope"
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the attach lapses: its signed `exp`."
+        },
+        "deliveryActive": {
+          "type": "boolean",
+          "description": "False while live traffic for the member goes elsewhere — to the member DID's own direct connection, which takes precedence over a mux connection."
+        }
+      }
+    },
+    "MuxScope": {
+      "title": "MuxScope",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 16,
+      "items": {
+        "$ref": "#/$defs/MuxScopeValue"
+      },
+      "description": "A set of capabilities: a non-empty JSON array of MuxScopeValue, compared as a set — order is not significant and a repeated value collapses into one. Never empty: an empty scope is refused, never read as \"all\". There is no default scope anywhere — every attach and every grant names its scope explicitly. A scope is always bounded by the member DID's own access-control capabilities at the mediator."
+    },
+    "MuxScopeValue": {
+      "title": "MuxScopeValue",
+      "type": "string",
+      "enum": [
+        "receive",
+        "pickup",
+        "delete",
+        "send"
+      ],
+      "description": "One capability a member DID extends to a principal's connection. `receive`: live delivery of the member's inbound messages on the connection. `pickup`: message-pickup status and delivery requests naming the member as `recipient_did`, and inclusion in a raw-TSP inbox drain. `delete`: deleting the member's stored messages, including delete-on-ack and delete-on-send; a member without `delete` keeps its messages in its inbox until something holding `delete` collects them. `send`: the mediator accepts on this connection frames whose sender is the member DID — the frame is still signed or authcrypted with the member's own keys; the scope only lets the mediator accept it on this socket."
+    },
+    "MuxDid": {
+      "title": "MuxDid",
+      "type": "string",
+      "minLength": 7,
+      "maxLength": 2048,
+      "pattern": "^did:[a-z0-9]+:\\S+$",
+      "description": "A DID, carried verbatim and compared by exact string equality. Unlike the messaging family's `Vid`, never a hash: the mediator resolves it to verify a statement signed by it. For a member DID reached over TSP, the TSP VID is the DID itself."
+    },
+    "GrantView": {
+      "title": "GrantView",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "statement",
+        "state",
+        "scope",
+        "expiresAt"
+      ],
+      "description": "The mediator's view of one stored grant, as messaging/mux/list and messaging/mux/update return it: the grant statement verbatim, with the state and the effective scope and expiry beside it.",
+      "properties": {
+        "statement": {
+          "$ref": "#/$defs/GrantStatement",
+          "description": "The grant statement exactly as the member signed it and the mediator stored it, proof included, so either party can re-verify it."
+        },
+        "state": {
+          "$ref": "#/$defs/GrantState"
+        },
+        "scope": {
+          "$ref": "#/$defs/MuxScope",
+          "description": "The effective scope: the signed scope, or the narrower one messaging/mux/update set."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "The effective expiry: the signed `exp` rendered as RFC 3339, or the earlier one messaging/mux/update set."
+        },
+        "narrowed": {
+          "type": "boolean",
+          "description": "True when messaging/mux/update narrowed the effective scope or expiry below what the statement signs."
+        },
+        "attachedNow": {
+          "type": "boolean",
+          "description": "Principal view only: whether the member is attached through this grant to the connection that carried the list request."
+        }
+      }
+    },
+    "GrantState": {
+      "title": "GrantState",
+      "type": "string",
+      "enum": [
+        "active",
+        "suspended",
+        "staleKey",
+        "expired",
+        "epochRevoked"
+      ],
+      "description": "A stored grant's state. `active`: valid; the member is attached whenever the principal is connected. `suspended`: the member DID proved control with a key that signed none of its active grants (the unknown-key rule); terminal — the grant cannot be resumed and must be recreated by a fresh member signature. `staleKey`: the key that signed the grant is no longer in the member DID's current authentication relationship; terminal — it does not become active again if the key reappears. `expired`: an active grant past its effective expiry; computed when read, never stored. `epochRevoked`: the member DID advanced its epoch with messaging/mux/revoke-all. A grant revoked with messaging/mux/revoke has no state: it is deleted. A dead grant (every state but `active`) stays listable for the mediator's retention window after its effective expiry, then is pruned."
+    },
+    "GrantStatement": {
+      "title": "GrantStatement",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "issuer",
+        "audience",
+        "grantId",
+        "principal",
+        "scope",
+        "epoch",
+        "iat",
+        "exp",
+        "proof"
+      ],
+      "description": "A member DID's standing statement that the named principal may carry its traffic at this mediator, on any connection, until `exp`, within `scope`, under the member's current `epoch`. Signed by the member with an embedded Data Integrity proof whose purpose is `authentication`, and stored verbatim by the mediator as the only evidence of the delegation.",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "muxGrant",
+          "description": "Always `muxGrant`; names the statement kind, so a statement of one kind is never accepted as another."
+        },
+        "issuer": {
+          "$ref": "#/$defs/MuxDid",
+          "description": "The member DID: the signer, and the DID the statement concerns."
+        },
+        "audience": {
+          "$ref": "#/$defs/MuxDid",
+          "description": "The mediator's DID. A statement names exactly one mediator and is refused by every other."
+        },
+        "grantId": {
+          "$ref": "#/$defs/GrantId"
+        },
+        "principal": {
+          "$ref": "#/$defs/MuxDid",
+          "description": "The principal DID that may carry the member's traffic. MUST differ from `issuer`."
+        },
+        "scope": {
+          "$ref": "#/$defs/StatementScope"
+        },
+        "epoch": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The member DID's current epoch at the mediator. Only messaging/mux/revoke-all advances it."
+        },
+        "iat": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "JWT NumericDate (RFC 7519 §2), whole seconds since 1970-01-01T00:00:00Z UTC: when the statement was signed. MUST NOT be more than 60 seconds in the mediator's future."
+        },
+        "exp": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "JWT NumericDate (RFC 7519 §2): when the statement stops being accepted. REQUIRED; MUST be after `iat` and in the future."
+        },
+        "proof": {
+          "$ref": "#/$defs/MuxDataIntegrityProof"
+        }
+      }
+    },
+    "MuxDataIntegrityProof": {
+      "title": "MuxDataIntegrityProof",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "cryptosuite",
+        "verificationMethod",
+        "proofPurpose",
+        "proofValue"
+      ],
+      "description": "The W3C Data Integrity proof embedded in a mux statement, made by the member DID: the format and verifier Trust Tasks already use for document proofs (SPEC §4.7). The proof covers the whole statement except `proof` itself, as the cryptosuite defines. Closed: a member Data Integrity defines but this list omits is refused.",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "DataIntegrityProof"
+        },
+        "cryptosuite": {
+          "type": "string",
+          "enum": [
+            "eddsa-jcs-2022",
+            "eddsa-rdfc-2022"
+          ],
+          "description": "The W3C Data Integrity EdDSA cryptosuite used."
+        },
+        "verificationMethod": {
+          "type": "string",
+          "minLength": 5,
+          "maxLength": 2048,
+          "pattern": "^did:\\S+#\\S+$",
+          "description": "The DID URL of the verification method that signed. MUST be controlled by the statement's `issuer` and listed in that DID's current `authentication` relationship."
+        },
+        "proofPurpose": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "MUST be `authentication`. Any other value is refused with `messaging/mux:proofPurposeInvalid` — a proof made for another relationship (an `assertionMethod` credential signature, say) is never accepted as control of the DID."
+        },
+        "created": {
+          "type": "string",
+          "format": "date-time",
+          "description": "OPTIONAL: when the proof was made, as Data Integrity defines it. Covered by the proof; the statement's own `iat` is what the mediator checks."
+        },
+        "proofValue": {
+          "type": "string",
+          "minLength": 2,
+          "maxLength": 4096,
+          "pattern": "^z[1-9A-HJ-NP-Za-km-z]+$",
+          "description": "The multibase (base58btc) signature."
+        }
+      }
+    },
+    "StatementScope": {
+      "title": "StatementScope",
+      "type": "array",
+      "maxItems": 16,
+      "items": {
+        "$ref": "#/$defs/MuxScopeValue"
+      },
+      "description": "The scope a member DID signs into a statement: a JSON array of MuxScopeValue, compared as a set — order is not significant and a repeated value collapses. It MUST NOT be empty; an empty signed scope is refused with the task's `emptyScope` code, never read as \"all\". Unlike MuxScope, emptiness is not a schema failure here, so that the refusal is reported per statement rather than failing the whole batch."
+    },
+    "GrantId": {
+      "title": "GrantId",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9._:-]+$",
+      "description": "A grant's identifier, chosen by the member DID's signer and carried in its grant statement; a UUID is RECOMMENDED. A mediator refuses a grant whose identifier is already on the member DID's record."
+    },
+    "MuxRole": {
+      "title": "MuxRole",
+      "type": "string",
+      "enum": [
+        "principal",
+        "member"
+      ],
+      "description": "The side of a delegation a requester acts as. `principal`: the DID that authenticated the connection and to which members' traffic is delegated. `member`: a DID whose traffic is delegated."
+    }
+  }
+} as const;
+
+/** As {@link PAYLOAD_SCHEMA}, for the success-response variant. */
+export const RESPONSE_PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "#/$defs/Response",
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Messaging — Mux List — response payload",
+      "description": "The success response to a messaging/mux/list request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/messaging/mux/list/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "as",
+        "grants"
+      ],
+      "properties": {
+        "as": {
+          "$ref": "#/$defs/MuxRole",
+          "description": "The view answered, echoing the request."
+        },
+        "grants": {
+          "type": "array",
+          "maxItems": 500,
+          "items": {
+            "$ref": "#/$defs/GrantView"
+          },
+          "description": "Grants in every state, ordered by member DID then grant identifier as principal, and by principal DID then grant identifier as member."
+        },
+        "attachments": {
+          "type": "array",
+          "maxItems": 5000,
+          "items": {
+            "$ref": "#/$defs/AttachView"
+          },
+          "description": "Principal view, first page only: the session attaches on the connection that carried the request. Absent when the request did not arrive on a mux connection."
+        },
+        "epoch": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Member view only: the member DID's current epoch, which a new grant must carry."
+        },
+        "nextCursor": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "description": "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "AttachView": {
+      "title": "AttachView",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "did",
+        "scope",
+        "expiresAt",
+        "deliveryActive"
+      ],
+      "description": "One session attach on a connection.",
+      "properties": {
+        "did": {
+          "$ref": "#/$defs/MuxDid",
+          "description": "The member DID."
+        },
+        "scope": {
+          "$ref": "#/$defs/MuxScope"
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the attach lapses: its signed `exp`."
+        },
+        "deliveryActive": {
+          "type": "boolean",
+          "description": "False while live traffic for the member goes elsewhere — to the member DID's own direct connection, which takes precedence over a mux connection."
+        }
+      }
+    },
+    "MuxScope": {
+      "title": "MuxScope",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 16,
+      "items": {
+        "$ref": "#/$defs/MuxScopeValue"
+      },
+      "description": "A set of capabilities: a non-empty JSON array of MuxScopeValue, compared as a set — order is not significant and a repeated value collapses into one. Never empty: an empty scope is refused, never read as \"all\". There is no default scope anywhere — every attach and every grant names its scope explicitly. A scope is always bounded by the member DID's own access-control capabilities at the mediator."
+    },
+    "MuxScopeValue": {
+      "title": "MuxScopeValue",
+      "type": "string",
+      "enum": [
+        "receive",
+        "pickup",
+        "delete",
+        "send"
+      ],
+      "description": "One capability a member DID extends to a principal's connection. `receive`: live delivery of the member's inbound messages on the connection. `pickup`: message-pickup status and delivery requests naming the member as `recipient_did`, and inclusion in a raw-TSP inbox drain. `delete`: deleting the member's stored messages, including delete-on-ack and delete-on-send; a member without `delete` keeps its messages in its inbox until something holding `delete` collects them. `send`: the mediator accepts on this connection frames whose sender is the member DID — the frame is still signed or authcrypted with the member's own keys; the scope only lets the mediator accept it on this socket."
+    },
+    "MuxDid": {
+      "title": "MuxDid",
+      "type": "string",
+      "minLength": 7,
+      "maxLength": 2048,
+      "pattern": "^did:[a-z0-9]+:\\S+$",
+      "description": "A DID, carried verbatim and compared by exact string equality. Unlike the messaging family's `Vid`, never a hash: the mediator resolves it to verify a statement signed by it. For a member DID reached over TSP, the TSP VID is the DID itself."
+    },
+    "GrantView": {
+      "title": "GrantView",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "statement",
+        "state",
+        "scope",
+        "expiresAt"
+      ],
+      "description": "The mediator's view of one stored grant, as messaging/mux/list and messaging/mux/update return it: the grant statement verbatim, with the state and the effective scope and expiry beside it.",
+      "properties": {
+        "statement": {
+          "$ref": "#/$defs/GrantStatement",
+          "description": "The grant statement exactly as the member signed it and the mediator stored it, proof included, so either party can re-verify it."
+        },
+        "state": {
+          "$ref": "#/$defs/GrantState"
+        },
+        "scope": {
+          "$ref": "#/$defs/MuxScope",
+          "description": "The effective scope: the signed scope, or the narrower one messaging/mux/update set."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "The effective expiry: the signed `exp` rendered as RFC 3339, or the earlier one messaging/mux/update set."
+        },
+        "narrowed": {
+          "type": "boolean",
+          "description": "True when messaging/mux/update narrowed the effective scope or expiry below what the statement signs."
+        },
+        "attachedNow": {
+          "type": "boolean",
+          "description": "Principal view only: whether the member is attached through this grant to the connection that carried the list request."
+        }
+      }
+    },
+    "GrantState": {
+      "title": "GrantState",
+      "type": "string",
+      "enum": [
+        "active",
+        "suspended",
+        "staleKey",
+        "expired",
+        "epochRevoked"
+      ],
+      "description": "A stored grant's state. `active`: valid; the member is attached whenever the principal is connected. `suspended`: the member DID proved control with a key that signed none of its active grants (the unknown-key rule); terminal — the grant cannot be resumed and must be recreated by a fresh member signature. `staleKey`: the key that signed the grant is no longer in the member DID's current authentication relationship; terminal — it does not become active again if the key reappears. `expired`: an active grant past its effective expiry; computed when read, never stored. `epochRevoked`: the member DID advanced its epoch with messaging/mux/revoke-all. A grant revoked with messaging/mux/revoke has no state: it is deleted. A dead grant (every state but `active`) stays listable for the mediator's retention window after its effective expiry, then is pruned."
+    },
+    "GrantStatement": {
+      "title": "GrantStatement",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "issuer",
+        "audience",
+        "grantId",
+        "principal",
+        "scope",
+        "epoch",
+        "iat",
+        "exp",
+        "proof"
+      ],
+      "description": "A member DID's standing statement that the named principal may carry its traffic at this mediator, on any connection, until `exp`, within `scope`, under the member's current `epoch`. Signed by the member with an embedded Data Integrity proof whose purpose is `authentication`, and stored verbatim by the mediator as the only evidence of the delegation.",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "muxGrant",
+          "description": "Always `muxGrant`; names the statement kind, so a statement of one kind is never accepted as another."
+        },
+        "issuer": {
+          "$ref": "#/$defs/MuxDid",
+          "description": "The member DID: the signer, and the DID the statement concerns."
+        },
+        "audience": {
+          "$ref": "#/$defs/MuxDid",
+          "description": "The mediator's DID. A statement names exactly one mediator and is refused by every other."
+        },
+        "grantId": {
+          "$ref": "#/$defs/GrantId"
+        },
+        "principal": {
+          "$ref": "#/$defs/MuxDid",
+          "description": "The principal DID that may carry the member's traffic. MUST differ from `issuer`."
+        },
+        "scope": {
+          "$ref": "#/$defs/StatementScope"
+        },
+        "epoch": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The member DID's current epoch at the mediator. Only messaging/mux/revoke-all advances it."
+        },
+        "iat": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "JWT NumericDate (RFC 7519 §2), whole seconds since 1970-01-01T00:00:00Z UTC: when the statement was signed. MUST NOT be more than 60 seconds in the mediator's future."
+        },
+        "exp": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "JWT NumericDate (RFC 7519 §2): when the statement stops being accepted. REQUIRED; MUST be after `iat` and in the future."
+        },
+        "proof": {
+          "$ref": "#/$defs/MuxDataIntegrityProof"
+        }
+      }
+    },
+    "MuxDataIntegrityProof": {
+      "title": "MuxDataIntegrityProof",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "cryptosuite",
+        "verificationMethod",
+        "proofPurpose",
+        "proofValue"
+      ],
+      "description": "The W3C Data Integrity proof embedded in a mux statement, made by the member DID: the format and verifier Trust Tasks already use for document proofs (SPEC §4.7). The proof covers the whole statement except `proof` itself, as the cryptosuite defines. Closed: a member Data Integrity defines but this list omits is refused.",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "DataIntegrityProof"
+        },
+        "cryptosuite": {
+          "type": "string",
+          "enum": [
+            "eddsa-jcs-2022",
+            "eddsa-rdfc-2022"
+          ],
+          "description": "The W3C Data Integrity EdDSA cryptosuite used."
+        },
+        "verificationMethod": {
+          "type": "string",
+          "minLength": 5,
+          "maxLength": 2048,
+          "pattern": "^did:\\S+#\\S+$",
+          "description": "The DID URL of the verification method that signed. MUST be controlled by the statement's `issuer` and listed in that DID's current `authentication` relationship."
+        },
+        "proofPurpose": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "MUST be `authentication`. Any other value is refused with `messaging/mux:proofPurposeInvalid` — a proof made for another relationship (an `assertionMethod` credential signature, say) is never accepted as control of the DID."
+        },
+        "created": {
+          "type": "string",
+          "format": "date-time",
+          "description": "OPTIONAL: when the proof was made, as Data Integrity defines it. Covered by the proof; the statement's own `iat` is what the mediator checks."
+        },
+        "proofValue": {
+          "type": "string",
+          "minLength": 2,
+          "maxLength": 4096,
+          "pattern": "^z[1-9A-HJ-NP-Za-km-z]+$",
+          "description": "The multibase (base58btc) signature."
+        }
+      }
+    },
+    "StatementScope": {
+      "title": "StatementScope",
+      "type": "array",
+      "maxItems": 16,
+      "items": {
+        "$ref": "#/$defs/MuxScopeValue"
+      },
+      "description": "The scope a member DID signs into a statement: a JSON array of MuxScopeValue, compared as a set — order is not significant and a repeated value collapses. It MUST NOT be empty; an empty signed scope is refused with the task's `emptyScope` code, never read as \"all\". Unlike MuxScope, emptiness is not a schema failure here, so that the refusal is reported per statement rather than failing the whole batch."
+    },
+    "GrantId": {
+      "title": "GrantId",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9._:-]+$",
+      "description": "A grant's identifier, chosen by the member DID's signer and carried in its grant statement; a UUID is RECOMMENDED. A mediator refuses a grant whose identifier is already on the member DID's record."
+    },
+    "MuxRole": {
+      "title": "MuxRole",
+      "type": "string",
+      "enum": [
+        "principal",
+        "member"
+      ],
+      "description": "The side of a delegation a requester acts as. `principal`: the DID that authenticated the connection and to which members' traffic is delegated. `member`: a DID whose traffic is delegated."
+    }
+  }
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the request variant, from this specification's
+ * front matter. Pass to `consumeInbound` — items 5b, 7 and 8 are
+ * per-specification and cannot be derived from the document alone, and
+ * item 2 needs the schema this carries.
+ */
+export const SPEC = {
+  typeUri: TYPE_URI,
+  isBearer: false,
+  isProofRequired: false,
+  isRecipientRequired: true,
+  isIssuedAtRequired: false,
+  payloadSchema: PAYLOAD_SCHEMA,
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the success-response variant. `isRecipientRequired`
+ * tracks the *issuer* party's requirement because a response swaps the
+ * parties (§7.3 item 5).
+ */
+export const RESPONSE_SPEC = {
+  typeUri: RESPONSE_TYPE_URI,
+  isBearer: false,
+  isProofRequired: false,
+  isRecipientRequired: true,
+  isIssuedAtRequired: false,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
+} as const;