@openvtc/trust-tasks 0.8.2 → 0.9.0

package/src/_runtime/consume.ts

@@ -1,5 +1,5 @@
 /**
- * Inbound-document orchestration for SPEC.md §7.2 items 4–8.
+ * Inbound-document orchestration for SPEC.md §7.2 item 2 and items 4–8.
  *
  * Hand-written. Mirrors `consume.rs` in trust-tasks-rs, deliberately closely:
  * a TypeScript consumer and a Rust one must reach the same verdict on the same
@@ -12,6 +12,8 @@
  *   transport,
  *   spec: AclGrant_v0_1.SPEC,
  *   proofPolicy: { kind: "verify", verify: myVerifier },
+ *   // ajv, or whatever validator you already run — see PayloadPolicy.
+ *   payloadPolicy: { kind: "validate", validate: myValidator },
  *   doc,
  *   myVid: "did:web:maintainer.example",
  *   now: Date.now(),
@@ -24,12 +26,23 @@
  *   case "handled":    emit(outcome.response); break;
  *   case "rejected":   emit(outcome.error); break;
  *   case "suppressed": logSuppressed(); break;
+ *   case "accepted":   break; // fire-and-forget: nothing to emit
  * }
  * ```
  *
- * Items 1 (framework schema), 2 (payload schema) and 3 (unknown `type`) are
- * *not* attempted here — they belong to the caller's parse and dispatch, and by
- * the time you hold a typed document they have already succeeded.
+ * Items 1 (framework schema) and 3 (unknown `type`) are *not* attempted here —
+ * they belong to the caller's parse and dispatch.
+ *
+ * Item 2 (payload schema) used to be on that list, on the same reasoning: "by
+ * the time you hold a typed document it has already succeeded." That was never
+ * true in TypeScript. `TrustTaskDocument<P>` is a compile-time type and erases
+ * to nothing; a `JSON.parse` result cast to it has been checked by no one. The
+ * package also shipped no schema a caller could have validated against even if
+ * they had wanted to, so the step was delegated to a caller who had no way to
+ * perform it — and every REQUIRED payload member was optional in practice.
+ *
+ * The schema now travels on the generated `SPEC` / `RESPONSE_SPEC`, and
+ * `payloadPolicy` decides what to do with it. See {@link PayloadPolicy}.
  */
 
 import {
@@ -89,6 +102,50 @@ export type ProofPolicy =
    */
   | { kind: "acceptUnverified" };
 
+/** Evaluates a payload against its schema (SPEC §7.2 item 2). */
+export interface PayloadValidator {
+  /**
+   * Check `payload` against `schema` — the value from
+   * {@link SpecPolicy.payloadSchema}, a JSON Schema 2020-12 document with all
+   * cross-file `$ref`s already inlined, so no resolver is needed.
+   *
+   * Return `true` (or `{ ok: true }`) to accept. Return `false`, or
+   * `{ ok: false, errors }`, to reject — the errors land in the
+   * `malformedRequest` message, so a caller can see what failed.
+   */
+  validate(
+    schema: unknown,
+    payload: unknown,
+  ): boolean | { ok: boolean; errors?: readonly string[] };
+}
+
+/**
+ * How {@link consumeInbound} performs SPEC §7.2 item 2 — payload-schema
+ * validation.
+ *
+ * This package bundles no JSON Schema implementation, for the same reason it
+ * bundles no cryptosuite: the engine, its draft support and its resource
+ * limits are the consumer's choice, and a zero-dependency package is worth
+ * keeping. So the schema ships with the generated module and the validator
+ * comes from you — wire up ajv, or whatever you already run.
+ *
+ * **`acceptUnvalidated` is a real choice, not a formality.** TypeScript types
+ * are erased at runtime, so nothing else in this pipeline looks at the payload
+ * at all: with no validator, a document whose payload is missing every
+ * REQUIRED member reaches your handler indistinguishable from a conforming
+ * one. That is why the policy is a required option rather than an optional
+ * one that defaults to skipping.
+ */
+export type PayloadPolicy =
+  /** Validate against `spec.payloadSchema`. Failures map to `malformedRequest`. */
+  | { kind: "validate"; validate: PayloadValidator }
+  /**
+   * Skip item 2 entirely. Appropriate only where something upstream — an API
+   * gateway, a schema-validating transport — has already performed it on the
+   * same bytes.
+   */
+  | { kind: "acceptUnvalidated" };
+
 /** The outcome of {@link consumeInbound}. */
 export type ConsumeOutcome<R> =
   /** Every check passed and the caller's handler produced a response. */
@@ -105,7 +162,18 @@ export type ConsumeOutcome<R> =
    * Callers SHOULD log this: silent suppression is the spec rule, but
    * *invisible* suppression is an operational footgun.
    */
-  | { kind: "suppressed"; reason: RejectReason };
+  | { kind: "suppressed"; reason: RejectReason }
+  /**
+   * Every check passed and the handler completed without producing a
+   * document — a fire-and-forget task.
+   *
+   * SPEC §4.4.1: a specification that defines no success response is one whose
+   * consumers **MUST NOT** emit a `#response`-variant document. Such a handler
+   * has nothing to return, and before 0.9.0 it had nowhere to say so: the
+   * return type demanded a document or an error, and returning neither threw a
+   * bare `TypeError` out of the pipeline. Emit nothing.
+   */
+  | { kind: "accepted" };
 
 /** Wire-safe message for the `rejectIfPresent` path. */
 export const PROOF_NOT_ACCEPTED_BY_POLICY =
@@ -116,6 +184,8 @@ export interface ConsumeOptions<P, R> {
   /** The generated module's `SPEC` (request) or `RESPONSE_SPEC` (response). */
   spec: SpecPolicy;
   proofPolicy: ProofPolicy;
+  /** §7.2 item 2. Required — see {@link PayloadPolicy} for why. */
+  payloadPolicy: PayloadPolicy;
   doc: TrustTaskDocument<P>;
   /** This consumer's own VID, for the §7.2 item 5 recipient check. */
   myVid: string;
@@ -123,11 +193,21 @@ export interface ConsumeOptions<P, R> {
   now: number;
   /** Invoked at most once, only when a rejection needs an error-response id. */
   newErrorId: () => string;
-  /** Business handler, called only once every framework check has passed. */
+  /**
+   * Business handler, called only once every framework check has passed.
+   *
+   * Return a success response, an {@link ErrorResponse} to refuse, or nothing
+   * at all for a specification that defines no success response (§4.4.1) —
+   * which yields the `accepted` outcome.
+   */
   handler: (
     doc: TrustTaskDocument<P>,
     parties: ResolvedParties,
-  ) => Promise<TrustTaskDocument<R> | ErrorResponse> | TrustTaskDocument<R> | ErrorResponse;
+  ) =>
+    | Promise<TrustTaskDocument<R> | ErrorResponse | void>
+    | TrustTaskDocument<R>
+    | ErrorResponse
+    | void;
   /** Override the response `issuedAt` clock, for deterministic tests. */
   clock?: () => string;
 }
@@ -145,13 +225,55 @@ export interface ConsumeOptions<P, R> {
 export async function consumeInbound<P, R>(
   opts: ConsumeOptions<P, R>,
 ): Promise<ConsumeOutcome<R>> {
-  const { transport, spec, proofPolicy, doc, myVid, now, newErrorId, handler, clock } = opts;
+  const { transport, spec, proofPolicy, payloadPolicy, doc, myVid, now, newErrorId, handler, clock } =
+    opts;
 
   const route = (reason: RejectReason): ConsumeOutcome<R> => {
     const error = reject(transport, doc, newErrorId(), reason, clock);
     return error === undefined ? { kind: "suppressed", reason } : { kind: "rejected", error };
   };
 
+  // A JavaScript caller gets no compile-time check that the option is present,
+  // and the old behaviour for an absent policy — skip item 2 silently — is
+  // exactly the defect this argument exists to remove. Say so instead of
+  // failing on a property read three lines down.
+  if (payloadPolicy === undefined) {
+    throw new TypeError(
+      "consumeInbound: `payloadPolicy` is required as of 0.9.0 (SPEC §7.2 item 2). " +
+        'Pass { kind: "validate", validate } to check the payload against ' +
+        "`spec.payloadSchema`, or { kind: \"acceptUnvalidated\" } to state that you " +
+        "are deliberately not checking it.",
+    );
+  }
+
+  // §7.2 item 2 — payload schema. Runs first, in the spec's own order, and
+  // before anything that reasons about what the payload means: a payload that
+  // is not the shape the specification declares should be refused as malformed
+  // rather than interpreted.
+  if (payloadPolicy.kind === "validate" && spec.payloadSchema !== undefined) {
+    let verdict: boolean | { ok: boolean; errors?: readonly string[] };
+    try {
+      verdict = payloadPolicy.validate.validate(spec.payloadSchema, doc.payload);
+    } catch (e) {
+      // A validator that throws has not accepted the document. Treating an
+      // exception as a pass would make a broken validator indistinguishable
+      // from a passing one — the failure mode this policy exists to remove.
+      verdict = { ok: false, errors: [e instanceof Error ? e.message : String(e)] };
+    }
+    const ok = typeof verdict === "boolean" ? verdict : verdict.ok;
+    if (!ok) {
+      const errors = typeof verdict === "boolean" ? undefined : verdict.errors;
+      return route({
+        code: "malformedRequest",
+        message:
+          errors !== undefined && errors.length > 0
+            ? `payload does not conform to its schema (SPEC §7.2 item 2): ${errors.join("; ")}`
+            : "payload does not conform to its schema (SPEC §7.2 item 2)",
+        retryable: false,
+      });
+    }
+  }
+
   // §7.2 items 4 + 5a — expiry and wrong-recipient.
   const basic = validateBasic(doc, now, myVid);
   if (basic !== null) return route(basic);
@@ -196,6 +318,7 @@ export async function consumeInbound<P, R>(
   if (policy !== null) return route(policy);
 
   const result = await handler(doc, resolved.parties);
+  if (result === undefined || result === null) return { kind: "accepted" };
   return isErrorResponse(result)
     ? { kind: "rejected", error: result }
     : { kind: "handled", response: result as TrustTaskDocument<R> };

package/src/_runtime/document.ts

@@ -172,6 +172,15 @@ export interface SpecPolicy {
   readonly isProofRequired: boolean;
   /** §7.3 item 5 — the party filling `recipient` is REQUIRED. */
   readonly isRecipientRequired: boolean;
+  /**
+   * §7.2 item 2 — this variant's payload schema, as a value.
+   *
+   * Carried here because TypeScript types are erased at runtime: a consumer
+   * holding a `TrustTaskDocument<P>` has no artifact to validate against
+   * unless the schema travels with the policy. `undefined` only for a
+   * hand-written policy that omits it.
+   */
+  readonly payloadSchema?: unknown;
 }
 
 /** Why a consumer rejected a document, and the §8.3 code it maps to. */

package/src/_runtime/index.ts

@@ -56,6 +56,8 @@ export {
   refuse,
   type ConsumeOptions,
   type ConsumeOutcome,
+  type PayloadPolicy,
+  type PayloadValidator,
   type ProofPolicy,
   type ProofVerifier,
 } from "./consume.js";

package/src/acl/change-role/0.1/payload.ts

@@ -130,16 +130,340 @@ export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/acl/change-role/0.
 /** Stable alias for this specification's success-response payload shape. */
 export type Response = ACLChangeRoleResponsePayload;
 
+/**
+ * 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/acl/change-role/0.1",
+  "title": "ACL Change Role — payload",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "subject",
+    "fromRole",
+    "toRole"
+  ],
+  "properties": {
+    "subject": {
+      "type": "string",
+      "description": "VID of the party whose role is changing."
+    },
+    "fromRole": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The subject's prior role. Used by the maintainer for the optimistic concurrency check."
+    },
+    "toRole": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The role to transition the subject to."
+    },
+    "reason": {
+      "type": "string",
+      "description": "Optional human-readable rationale."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext",
+      "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "ACL Change Role — response payload",
+      "description": "The success response to an acl/change-role request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/acl/change-role/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "entry"
+      ],
+      "properties": {
+        "entry": {
+          "description": "The AclEntry the maintainer now holds for the subject. entry.role MUST equal the request's payload.toRole.",
+          "$ref": "#/$defs/AclEntry"
+        },
+        "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-]+)+$"
+      }
+    },
+    "AclEntry": {
+      "title": "AclEntry",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "subject",
+        "role"
+      ],
+      "properties": {
+        "subject": {
+          "type": "string",
+          "description": "VID of the party in the ACL. Compared by exact string equality (SPEC.md §4.8); producers SHOULD emit canonical form."
+        },
+        "role": {
+          "type": "string",
+          "description": "Opaque role identifier interpreted by the ACL maintainer."
+        },
+        "scopes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Opaque scope identifiers (e.g. contexts, domains, resource prefixes)."
+        },
+        "allowedKeys": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          },
+          "description": "Key identifiers this subject may invoke the maintainer's signing oracle on. INTERSECTS WITH `scopes` — it can only narrow, never widen: a key named here that lies outside the entry's scopes remains unreachable, exactly as if it were not named. ABSENT means every key within the entry's scopes (the behaviour of entries that pre-date this member); explicit `null` is equivalent to absent, and producers SHOULD omit the member instead. PRESENT-BUT-EMPTY means authorized on NO keys — the opposite of absent, and deliberately so: emptiness is never a wildcard (CONVENTIONS.md §5). A consumer MUST preserve and enforce the absent-vs-empty distinction end to end; collapsing the two (e.g. by testing emptiness alone) re-creates the empty-means-unrestricted class of privilege-escalation defect this family's conventions exist to prevent."
+        },
+        "label": {
+          "type": "string",
+          "description": "Optional human-readable label."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "createdBy": {
+          "type": "string",
+          "description": "VID of the party that originally added this entry."
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "updatedBy": {
+          "type": "string",
+          "description": "VID of the party that last modified this entry."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Optional time after which the entry is no longer effective."
+        },
+        "stepUp": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Per-entry authentication step-up configuration, consumed by the ACL maintainer when it gates an operation behind a step-up (see auth/step-up/policy/0.1). ADDITIVE-ONLY: a per-entry setting MAY raise the assurance required of this subject above the maintainer's system-wide floor, but MUST NOT lower it. The maintainer resolves the effective requirement as the strictest of (system floor, this entry).",
+          "properties": {
+            "approver": {
+              "type": "string",
+              "description": "VID authorized to ratify step-up for this subject — the `recipient` the maintainer addresses an auth/step-up/approve-request to (e.g. the holder's mobile authenticator or browser companion). Absent → the subject is its own approver (mode `self`) when it holds a usable authenticator; if neither an `approver` nor a self authenticator exists, no step-up method is available for this subject and the maintainer's fail-closed rule applies."
+            },
+            "require": {
+              "type": "string",
+              "enum": [
+                "self",
+                "delegated"
+              ],
+              "description": "Minimum step-up mode this subject MUST satisfy for gated operations, raising the system floor. `self` = the subject re-authenticates its own session; `delegated` = a separate `approver` MUST ratify. Omitted → the system floor applies unchanged. A value weaker than the resolved floor is ignored (additive-only)."
+            }
+          }
+        },
+        "approve": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Approve-authority: what this subject may **confer on others** by ratifying an approval, as distinct from `scopes`, which is what it may **exercise itself**. The two axes are independent, and that independence is the point — it is what lets a maintainer configure a least-privilege approver who can authorize an operation in a scope it has no authority to perform.\n\nOMISSION MEANS NOTHING IS CONFERRED. An absent `approve`, an absent `all`, and an empty `scopes` are all equivalent to \"this subject may ratify nothing\". A consumer that does not implement this member therefore confers less than the producer intended rather than more, which is the direction a missed member has to fail in.\n\nA subject with approve-authority is NOT thereby authorized to act. Consumers MUST resolve the two axes separately: reading `approve` to answer \"may this party ratify X\" and `scopes` to answer \"may this party do X\". Collapsing them grants an approver the ability to perform what it was only meant to sign off on.",
+          "properties": {
+            "all": {
+              "type": "boolean",
+              "default": false,
+              "description": "The subject may confer ANY scope. Takes precedence over `scopes`, which a consumer MUST ignore when this is true. Absent or false → only the scopes listed below, if any."
+            },
+            "scopes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Opaque scope identifiers this subject may confer, drawn from the same vocabulary as the entry's own `scopes`. Where a maintainer's scopes are hierarchical, conferring a scope confers its descendants — the same containment rule the maintainer already applies to `scopes`, so the two axes cannot disagree about what a scope means. An empty array confers nothing; it is not a wildcard."
+            }
+          }
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1. Reverse-DNS-namespaced; consumers MUST ignore unrecognized namespaces."
+        }
+      }
+    }
+  }
+} 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": "ACL Change Role — response payload",
+      "description": "The success response to an acl/change-role request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/acl/change-role/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "entry"
+      ],
+      "properties": {
+        "entry": {
+          "description": "The AclEntry the maintainer now holds for the subject. entry.role MUST equal the request's payload.toRole.",
+          "$ref": "#/$defs/AclEntry"
+        },
+        "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-]+)+$"
+      }
+    },
+    "AclEntry": {
+      "title": "AclEntry",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "subject",
+        "role"
+      ],
+      "properties": {
+        "subject": {
+          "type": "string",
+          "description": "VID of the party in the ACL. Compared by exact string equality (SPEC.md §4.8); producers SHOULD emit canonical form."
+        },
+        "role": {
+          "type": "string",
+          "description": "Opaque role identifier interpreted by the ACL maintainer."
+        },
+        "scopes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Opaque scope identifiers (e.g. contexts, domains, resource prefixes)."
+        },
+        "allowedKeys": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          },
+          "description": "Key identifiers this subject may invoke the maintainer's signing oracle on. INTERSECTS WITH `scopes` — it can only narrow, never widen: a key named here that lies outside the entry's scopes remains unreachable, exactly as if it were not named. ABSENT means every key within the entry's scopes (the behaviour of entries that pre-date this member); explicit `null` is equivalent to absent, and producers SHOULD omit the member instead. PRESENT-BUT-EMPTY means authorized on NO keys — the opposite of absent, and deliberately so: emptiness is never a wildcard (CONVENTIONS.md §5). A consumer MUST preserve and enforce the absent-vs-empty distinction end to end; collapsing the two (e.g. by testing emptiness alone) re-creates the empty-means-unrestricted class of privilege-escalation defect this family's conventions exist to prevent."
+        },
+        "label": {
+          "type": "string",
+          "description": "Optional human-readable label."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "createdBy": {
+          "type": "string",
+          "description": "VID of the party that originally added this entry."
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "updatedBy": {
+          "type": "string",
+          "description": "VID of the party that last modified this entry."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Optional time after which the entry is no longer effective."
+        },
+        "stepUp": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Per-entry authentication step-up configuration, consumed by the ACL maintainer when it gates an operation behind a step-up (see auth/step-up/policy/0.1). ADDITIVE-ONLY: a per-entry setting MAY raise the assurance required of this subject above the maintainer's system-wide floor, but MUST NOT lower it. The maintainer resolves the effective requirement as the strictest of (system floor, this entry).",
+          "properties": {
+            "approver": {
+              "type": "string",
+              "description": "VID authorized to ratify step-up for this subject — the `recipient` the maintainer addresses an auth/step-up/approve-request to (e.g. the holder's mobile authenticator or browser companion). Absent → the subject is its own approver (mode `self`) when it holds a usable authenticator; if neither an `approver` nor a self authenticator exists, no step-up method is available for this subject and the maintainer's fail-closed rule applies."
+            },
+            "require": {
+              "type": "string",
+              "enum": [
+                "self",
+                "delegated"
+              ],
+              "description": "Minimum step-up mode this subject MUST satisfy for gated operations, raising the system floor. `self` = the subject re-authenticates its own session; `delegated` = a separate `approver` MUST ratify. Omitted → the system floor applies unchanged. A value weaker than the resolved floor is ignored (additive-only)."
+            }
+          }
+        },
+        "approve": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Approve-authority: what this subject may **confer on others** by ratifying an approval, as distinct from `scopes`, which is what it may **exercise itself**. The two axes are independent, and that independence is the point — it is what lets a maintainer configure a least-privilege approver who can authorize an operation in a scope it has no authority to perform.\n\nOMISSION MEANS NOTHING IS CONFERRED. An absent `approve`, an absent `all`, and an empty `scopes` are all equivalent to \"this subject may ratify nothing\". A consumer that does not implement this member therefore confers less than the producer intended rather than more, which is the direction a missed member has to fail in.\n\nA subject with approve-authority is NOT thereby authorized to act. Consumers MUST resolve the two axes separately: reading `approve` to answer \"may this party ratify X\" and `scopes` to answer \"may this party do X\". Collapsing them grants an approver the ability to perform what it was only meant to sign off on.",
+          "properties": {
+            "all": {
+              "type": "boolean",
+              "default": false,
+              "description": "The subject may confer ANY scope. Takes precedence over `scopes`, which a consumer MUST ignore when this is true. Absent or false → only the scopes listed below, if any."
+            },
+            "scopes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Opaque scope identifiers this subject may confer, drawn from the same vocabulary as the entry's own `scopes`. Where a maintainer's scopes are hierarchical, conferring a scope confers its descendants — the same containment rule the maintainer already applies to `scopes`, so the two axes cannot disagree about what a scope means. An empty array confers nothing; it is not a wildcard."
+            }
+          }
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext",
+          "description": "Ecosystem-defined extension members per SPEC.md §4.5.1. Reverse-DNS-namespaced; consumers MUST ignore unrecognized namespaces."
+        }
+      }
+    }
+  }
+} 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.
+ * 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: true,
   isRecipientRequired: true,
+  payloadSchema: PAYLOAD_SCHEMA,
 } as const;
 
 /**
@@ -152,4 +476,5 @@ export const RESPONSE_SPEC = {
   isBearer: false,
   isProofRequired: true,
   isRecipientRequired: true,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
 } as const;