@openvtc/trust-tasks 0.2.57 → 0.2.59

package/README.md

@@ -1,8 +1,13 @@
 # @openvtc/trust-tasks
 
-Generated TypeScript bindings for the [Trust Tasks
+TypeScript bindings **and the consumer pipeline** for the [Trust Tasks
 framework](https://trusttasks.org) registry.
 
+Two halves: generated types for every specification in the registry, and a
+hand-written implementation of the SPEC.md §7.2 checks that decide whether an
+inbound document may be acted on. See [Consuming a document](#consuming-a-document)
+— types alone will not make a conforming consumer.
+
 Every spec under [`dtgwg-trust-tasks-tf/specs/`](https://github.com/trustoverip/dtgwg-trust-tasks-tf/tree/main/specs)
 that defines a `payload.schema.json` is compiled — via
 `scripts/build-ts-bindings.mjs` (json-schema-to-typescript) — to a
@@ -80,10 +85,70 @@ appending `_v<MAJOR>_<MINOR>`. Multiple versions of the same spec
 land in sibling directories (`0.1/`, `1.0/`, …) and export
 distinct names — there is no "latest" alias by design.
 
+## Consuming a document
+
+A conforming *consumer* applies all eight checks in
+[SPEC.md §7.2](https://trusttasks.org/SPEC#72-consumer-requirements) before
+acting on an inbound document. Three of them — recipient-REQUIRED, proof-REQUIRED
+and audience binding — are declared *per specification* and cannot be derived
+from the document itself, so every generated module exports the declarations as
+`SPEC` (and `RESPONSE_SPEC`, where the spec defines a response).
+
+`consumeInbound` runs items 4–8 and then calls your handler. Items 1–3
+(framework schema, payload schema, unknown `type`) belong to your parse and
+dispatch, and have already succeeded by the time you hold a typed document.
+
+```ts
+import {
+  consumeInbound,
+  respondWith,
+  StaticTransport,
+  AclGrant_v0_1,
+} from "@openvtc/trust-tasks";
+
+const outcome = await consumeInbound<AclGrant_v0_1.Payload, AclGrant_v0_1.Response>({
+  transport: new StaticTransport({ issuer: peerVid }), // what the transport authenticated
+  spec: AclGrant_v0_1.SPEC,
+  proofPolicy: { kind: "verify", verify: myVerifier },
+  doc,
+  myVid: "did:web:maintainer.example",
+  now: Date.now(),
+  newErrorId: () => crypto.randomUUID(),
+  handler: async (accepted, parties) =>
+    respondWith(accepted, crypto.randomUUID(), await applyGrant(accepted.payload, parties)),
+});
+
+switch (outcome.kind) {
+  case "handled":
+    return send(outcome.response);
+  case "rejected":
+    return send(outcome.error); // already addressed per §8.1
+  case "suppressed":
+    // §8.1: an `identityMismatch` the transport cannot safely answer. Emitting
+    // anything here would be an oracle. Log it — silent is the rule, invisible
+    // is a footgun.
+    return log(outcome.reason);
+}
+```
+
+**Choose a proof policy deliberately.** `{ kind: "verify" }` honours in-band
+proofs. `{ kind: "rejectIfPresent" }` is for consumers with integrity from
+another layer — it refuses a proof-bearing document rather than silently
+dropping the proof, which would mislead the producer about the guarantees of
+the exchange. `{ kind: "acceptUnverified" }` is the explicit opt-out and only
+safe where the transport already provides equivalent end-to-end integrity. A
+specification that declares `proof` REQUIRED rejects a proofless document under
+all three.
+
+The pipeline mirrors `consume_inbound` in
+[`trust-tasks-rs`](https://crates.io/crates/trust-tasks-rs) check for check, so
+a TypeScript consumer and a Rust one reach the same verdict on the same
+document.
+
 ## Validating payloads at runtime
 
-This package ships TypeScript types only — it does not bundle a
-JSON-Schema validator. If you need runtime validation, fetch the
+This package does not bundle a JSON-Schema validator, so §7.2 items 1–2
+(framework and payload schema validation) are yours to wire up. Fetch the
 `payload.schema.json` from
 `https://trusttasks.org/spec/<slug>/<version>` and feed it to
 [`ajv`](https://www.npmjs.com/package/ajv) or any other Draft 2020-12

package/dist/_runtime/codes.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Error codes — SPEC.md §8.3 (standard) and §8.5 (extended).
+ *
+ * Hand-written. Mirrors `error.rs` in trust-tasks-rs, including its acceptance
+ * of both the framework 0.2 lowerCamelCase spellings and the frozen 0.1
+ * snake_case ones, so a 0.2 consumer can still read an error response from a
+ * 0.1 peer.
+ */
+/** The framework-defined standard error codes (SPEC.md §8.3). */
+export declare const STANDARD_CODES: readonly ["malformedRequest", "unsupportedType", "unsupportedVersion", "expired", "proofRequired", "proofInvalid", "permissionDenied", "wrongRecipient", "identityMismatch", "taskFailed", "unavailable", "internalError"];
+export type StandardCode = (typeof STANDARD_CODES)[number];
+/**
+ * Normalize a wire `code` to its canonical 0.2 spelling when it is a standard
+ * code, or return it unchanged.
+ *
+ * A consumer comparing a received code against {@link STANDARD_CODES} must
+ * normalize first, or a 0.1 peer's `proof_required` reads as an unrecognized
+ * extended code and falls through to `taskFailed` (§8.5), losing the meaning.
+ */
+export declare function normalizeCode(code: string): string;
+/** Whether `code` is a standard §8.3 code, in either casing. */
+export declare function isStandardCode(code: string): code is StandardCode;
+/**
+ * Build an extended error code under a specification's own slug (SPEC §8.5).
+ *
+ * `typeUri` is normally a generated module's `TYPE_URI`, so the namespace
+ * cannot drift from the type's identity — the same guarantee
+ * `Payload::extended_code` gives in Rust. The `#response` fragment is stripped:
+ * an error raised while handling a response still belongs to the bare slug.
+ *
+ * @throws if the derived slug or `local` is malformed.
+ */
+export declare function extendedCode(typeUri: string, local: string): string;
+/**
+ * Build an extended error code under a *family namespace* — a proper path
+ * prefix of the specification's slug (SPEC §8.5 rule 2).
+ *
+ * For a condition whose meaning is defined once across a family rather than
+ * per specification, such as `did-management:unknownDomain` on every
+ * `did-management/*` task. Prefer {@link extendedCode} otherwise: a family
+ * namespace claims the condition means the same thing across every sibling.
+ *
+ * `namespace` is checked against the slug derived from `typeUri` rather than
+ * taken on trust, so §8.5's prefix rule holds by construction. A sibling's slug
+ * is rejected — it shares a prefix but is not itself one, which is exactly the
+ * confusion §8.5 forbids.
+ *
+ * @throws if `namespace` is neither the slug nor a path prefix of it.
+ */
+export declare function familyCode(typeUri: string, namespace: string, local: string): string;
+/** The slug of a Type URI, with any `#request` / `#response` fragment removed. */
+export declare function slugFromTypeUri(typeUri: string): string;
+//# sourceMappingURL=codes.d.ts.map

package/dist/_runtime/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../src/_runtime/codes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,iEAAiE;AACjE,eAAO,MAAM,cAAc,4NAajB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAqB3D;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGlD;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,YAAY,CAEjE;AAoBD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CASnE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAepF;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAavD"}

package/dist/_runtime/codes.js

@@ -0,0 +1,136 @@
+/**
+ * Error codes — SPEC.md §8.3 (standard) and §8.5 (extended).
+ *
+ * Hand-written. Mirrors `error.rs` in trust-tasks-rs, including its acceptance
+ * of both the framework 0.2 lowerCamelCase spellings and the frozen 0.1
+ * snake_case ones, so a 0.2 consumer can still read an error response from a
+ * 0.1 peer.
+ */
+/** The framework-defined standard error codes (SPEC.md §8.3). */
+export const STANDARD_CODES = [
+    "malformedRequest",
+    "unsupportedType",
+    "unsupportedVersion",
+    "expired",
+    "proofRequired",
+    "proofInvalid",
+    "permissionDenied",
+    "wrongRecipient",
+    "identityMismatch",
+    "taskFailed",
+    "unavailable",
+    "internalError",
+];
+/**
+ * Framework 0.1 snake_case spellings, mapped to their 0.2 lowerCamelCase form.
+ * `expired` and `unavailable` are single words and unchanged.
+ */
+const LEGACY_STANDARD = {
+    malformed_request: "malformedRequest",
+    unsupported_type: "unsupportedType",
+    unsupported_version: "unsupportedVersion",
+    proof_required: "proofRequired",
+    proof_invalid: "proofInvalid",
+    permission_denied: "permissionDenied",
+    wrong_recipient: "wrongRecipient",
+    identity_mismatch: "identityMismatch",
+    task_failed: "taskFailed",
+    internal_error: "internalError",
+};
+const STANDARD_SET = new Set(STANDARD_CODES);
+/**
+ * Normalize a wire `code` to its canonical 0.2 spelling when it is a standard
+ * code, or return it unchanged.
+ *
+ * A consumer comparing a received code against {@link STANDARD_CODES} must
+ * normalize first, or a 0.1 peer's `proof_required` reads as an unrecognized
+ * extended code and falls through to `taskFailed` (§8.5), losing the meaning.
+ */
+export function normalizeCode(code) {
+    if (STANDARD_SET.has(code))
+        return code;
+    return LEGACY_STANDARD[code] ?? code;
+}
+/** Whether `code` is a standard §8.3 code, in either casing. */
+export function isStandardCode(code) {
+    return STANDARD_SET.has(normalizeCode(code));
+}
+/**
+ * The local part of an extended code: a lowercase letter, then letters of
+ * either case, digits, or underscores.
+ *
+ * Both casings are accepted so framework 0.2 lowerCamelCase locals
+ * (`documentRevoked`) and frozen 0.1 snake_case locals (`document_revoked`)
+ * parse under one rule. SPEC §4.10 item 4 SHOULDs lowerCamelCase for new
+ * specifications; only the first character is required to be lowercase.
+ */
+const LOCAL_RE = /^[a-z][A-Za-z0-9_]*$/;
+/** One path segment of a slug: lowercase, hyphen-separated (§6.1). */
+const SEGMENT_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+function validNamespace(namespace) {
+    return namespace.length > 0 && namespace.split("/").every((s) => SEGMENT_RE.test(s));
+}
+/**
+ * Build an extended error code under a specification's own slug (SPEC §8.5).
+ *
+ * `typeUri` is normally a generated module's `TYPE_URI`, so the namespace
+ * cannot drift from the type's identity — the same guarantee
+ * `Payload::extended_code` gives in Rust. The `#response` fragment is stripped:
+ * an error raised while handling a response still belongs to the bare slug.
+ *
+ * @throws if the derived slug or `local` is malformed.
+ */
+export function extendedCode(typeUri, local) {
+    const slug = slugFromTypeUri(typeUri);
+    if (!LOCAL_RE.test(local)) {
+        throw new Error(`extendedCode: local part ${JSON.stringify(local)} must match ${LOCAL_RE} ` +
+            `(a lowercase first character, then letters, digits or underscores)`);
+    }
+    return `${slug}:${local}`;
+}
+/**
+ * Build an extended error code under a *family namespace* — a proper path
+ * prefix of the specification's slug (SPEC §8.5 rule 2).
+ *
+ * For a condition whose meaning is defined once across a family rather than
+ * per specification, such as `did-management:unknownDomain` on every
+ * `did-management/*` task. Prefer {@link extendedCode} otherwise: a family
+ * namespace claims the condition means the same thing across every sibling.
+ *
+ * `namespace` is checked against the slug derived from `typeUri` rather than
+ * taken on trust, so §8.5's prefix rule holds by construction. A sibling's slug
+ * is rejected — it shares a prefix but is not itself one, which is exactly the
+ * confusion §8.5 forbids.
+ *
+ * @throws if `namespace` is neither the slug nor a path prefix of it.
+ */
+export function familyCode(typeUri, namespace, local) {
+    const slug = slugFromTypeUri(typeUri);
+    const segments = slug.split("/");
+    const permitted = segments.map((_, i) => segments.slice(0, i + 1).join("/"));
+    if (!permitted.includes(namespace)) {
+        throw new Error(`familyCode: namespace ${JSON.stringify(namespace)} is neither the slug ` +
+            `${JSON.stringify(slug)} nor a path prefix of it (SPEC §8.5 rule 2). ` +
+            `Permitted: ${permitted.map((p) => JSON.stringify(p)).join(", ")}`);
+    }
+    if (!LOCAL_RE.test(local)) {
+        throw new Error(`familyCode: local part ${JSON.stringify(local)} must match ${LOCAL_RE}`);
+    }
+    return `${namespace}:${local}`;
+}
+/** The slug of a Type URI, with any `#request` / `#response` fragment removed. */
+export function slugFromTypeUri(typeUri) {
+    const PREFIX = "https://trusttasks.org/spec/";
+    if (!typeUri.startsWith(PREFIX)) {
+        throw new Error(`not a Trust Task Type URI: ${JSON.stringify(typeUri)}`);
+    }
+    const rest = typeUri.slice(PREFIX.length).split("#")[0];
+    // Trailing segment is the MAJOR.MINOR version; everything before it is the slug.
+    const parts = rest.split("/");
+    const slug = parts.slice(0, -1).join("/");
+    if (!validNamespace(slug)) {
+        throw new Error(`Type URI ${JSON.stringify(typeUri)} yielded an invalid slug`);
+    }
+    return slug;
+}
+//# sourceMappingURL=codes.js.map

package/dist/_runtime/codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../../src/_runtime/codes.ts"],"names":[],"mappings":"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"}

package/dist/_runtime/consume.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Inbound-document orchestration for SPEC.md §7.2 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
+ * document, or the two reference implementations disagree about what conforms.
+ *
+ * ```ts
+ * import { consumeInbound, StaticTransport, AclGrant_v0_1 } from "@openvtc/trust-tasks";
+ *
+ * const outcome = await consumeInbound({
+ *   transport,
+ *   spec: AclGrant_v0_1.SPEC,
+ *   proofPolicy: { kind: "verify", verify: myVerifier },
+ *   doc,
+ *   myVid: "did:web:maintainer.example",
+ *   now: Date.now(),
+ *   newErrorId: () => crypto.randomUUID(),
+ *   handler: async (accepted, parties) =>
+ *     respondWith(accepted, crypto.randomUUID(), buildResponse(parties)),
+ * });
+ *
+ * switch (outcome.kind) {
+ *   case "handled":    emit(outcome.response); break;
+ *   case "rejected":   emit(outcome.error); break;
+ *   case "suppressed": logSuppressed(); break;
+ * }
+ * ```
+ *
+ * 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.
+ */
+import { type ErrorResponse, type RejectReason, type SpecPolicy, type TrustTaskDocument } from "./document.js";
+import { type ResolvedParties, type TransportHandler } from "./transport.js";
+/** Verifies a document's Data Integrity proof (SPEC §4.7). */
+export interface ProofVerifier {
+    /** Resolve to `true` when the proof verifies against the in-band `issuer`. */
+    verify<P>(doc: TrustTaskDocument<P>): Promise<boolean> | boolean;
+}
+/**
+ * How {@link consumeInbound} treats a document's `proof` member (§7.2 item 7).
+ *
+ * The framework does not assume what integrity guarantees a consumer relies on.
+ * Some verify Data Integrity proofs in-band; some have transport-layer
+ * integrity (signed DIDComm, mTLS-bound HTTPS) and accept in-band proofs only
+ * opportunistically; some have none. Making the choice explicit at the call
+ * site is the point.
+ *
+ * `spec.isProofRequired` is consulted independently of the policy: a
+ * specification that requires a proof rejects a proofless document whichever
+ * policy is chosen.
+ */
+export type ProofPolicy = 
+/**
+ * Verify the proof when present. Failures map to `proofInvalid`. The safe
+ * default for any consumer that honours in-band proofs.
+ */
+{
+    kind: "verify";
+    verify: ProofVerifier;
+}
+/**
+ * Reject a document that carries an in-band proof, with `malformedRequest`.
+ * For consumers with integrity from another layer that are deliberately not
+ * verifying in-band proofs — silently dropping a producer-supplied proof
+ * would mislead the producer about the guarantees of the exchange.
+ */
+ | {
+    kind: "rejectIfPresent";
+}
+/**
+ * SECURITY: accept any document, proof or not, without verifying. Only where
+ * the transport already provides equivalent end-to-end integrity. This is the
+ * explicit opt-out, and the name is deliberately uncomfortable to type.
+ */
+ | {
+    kind: "acceptUnverified";
+};
+/** The outcome of {@link consumeInbound}. */
+export type ConsumeOutcome<R> = 
+/** Every check passed and the caller's handler produced a response. */
+{
+    kind: "handled";
+    response: TrustTaskDocument<R>;
+}
+/**
+ * A framework check failed, or the handler refused. Either way the document
+ * is already addressed per §8.1 — emit it over the transport.
+ */
+ | {
+    kind: "rejected";
+    error: ErrorResponse;
+}
+/**
+ * §8.1: the rejection was `identityMismatch` and the transport authenticated
+ * no sender, so no response may be emitted — one would be an oracle.
+ *
+ * Callers SHOULD log this: silent suppression is the spec rule, but
+ * *invisible* suppression is an operational footgun.
+ */
+ | {
+    kind: "suppressed";
+    reason: RejectReason;
+};
+/** Wire-safe message for the `rejectIfPresent` path. */
+export declare const PROOF_NOT_ACCEPTED_BY_POLICY = "in-band proof not accepted by consumer policy (SPEC \u00A77.2 item 7)";
+export interface ConsumeOptions<P, R> {
+    transport: TransportHandler;
+    /** The generated module's `SPEC` (request) or `RESPONSE_SPEC` (response). */
+    spec: SpecPolicy;
+    proofPolicy: ProofPolicy;
+    doc: TrustTaskDocument<P>;
+    /** This consumer's own VID, for the §7.2 item 5 recipient check. */
+    myVid: string;
+    /** Milliseconds since the epoch, as from `Date.now()`. */
+    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. */
+    handler: (doc: TrustTaskDocument<P>, parties: ResolvedParties) => Promise<TrustTaskDocument<R> | ErrorResponse> | TrustTaskDocument<R> | ErrorResponse;
+    /** Override the response `issuedAt` clock, for deterministic tests. */
+    clock?: () => string;
+}
+/**
+ * Run SPEC §7.2 items 4–8 against `doc`, then either call the handler or build
+ * the routed error response per §8.1.
+ *
+ * ⚠ A handler-returned {@link ErrorResponse} is passed through verbatim — the
+ * framework does not re-apply §8.1 routing to it. A handler rejecting for
+ * identity-style reasons MUST address the response itself (see `reject` in
+ * ./transport.js); `rejectWith` copies `doc.issuer` into `recipient`, which is
+ * safe for ordinary refusals but not for one that contests that identity.
+ */
+export declare function consumeInbound<P, R>(opts: ConsumeOptions<P, R>): Promise<ConsumeOutcome<R>>;
+/**
+ * Build a handler-side refusal addressed to the original producer.
+ *
+ * Convenience over `rejectWith` + `toErrorPayload` for the common case where a
+ * handler refuses for a business reason. Not safe for refusals that contest the
+ * in-band identity — see the warning on {@link consumeInbound}.
+ */
+export declare function refuse<P>(request: TrustTaskDocument<P>, id: string, reason: RejectReason, clock?: () => string): ErrorResponse;
+//# sourceMappingURL=consume.d.ts.map

package/dist/_runtime/consume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consume.d.ts","sourceRoot":"","sources":["../../src/_runtime/consume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,gBAAgB,CAAC;AAExB,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAClE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW;AACrB;;;GAGG;AACD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE;AAC3C;;;;;GAKG;GACD;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE;AAC7B;;;;GAIG;GACD;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAEjC,6CAA6C;AAC7C,MAAM,MAAM,cAAc,CAAC,CAAC;AAC1B,uEAAuE;AACrE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAA;CAAE;AACrD;;;GAGG;GACD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE;AAC5C;;;;;;GAMG;GACD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC;AAEjD,wDAAwD;AACxD,eAAO,MAAM,4BAA4B,0EAC2B,CAAC;AAErE,MAAM,WAAW,cAAc,CAAC,CAAC,EAAE,CAAC;IAClC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,6EAA6E;IAC7E,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;IACzB,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAC1B,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,UAAU,EAAE,MAAM,MAAM,CAAC;IACzB,2EAA2E;IAC3E,OAAO,EAAE,CACP,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,EACzB,OAAO,EAAE,eAAe,KACrB,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC;IAC1F,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,CAAC,EACvC,IAAI,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GACzB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAuD5B;AAaD;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACtB,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC7B,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,MAAM,MAAM,GACnB,aAAa,CAEf"}

package/dist/_runtime/consume.js

@@ -0,0 +1,122 @@
+/**
+ * Inbound-document orchestration for SPEC.md §7.2 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
+ * document, or the two reference implementations disagree about what conforms.
+ *
+ * ```ts
+ * import { consumeInbound, StaticTransport, AclGrant_v0_1 } from "@openvtc/trust-tasks";
+ *
+ * const outcome = await consumeInbound({
+ *   transport,
+ *   spec: AclGrant_v0_1.SPEC,
+ *   proofPolicy: { kind: "verify", verify: myVerifier },
+ *   doc,
+ *   myVid: "did:web:maintainer.example",
+ *   now: Date.now(),
+ *   newErrorId: () => crypto.randomUUID(),
+ *   handler: async (accepted, parties) =>
+ *     respondWith(accepted, crypto.randomUUID(), buildResponse(parties)),
+ * });
+ *
+ * switch (outcome.kind) {
+ *   case "handled":    emit(outcome.response); break;
+ *   case "rejected":   emit(outcome.error); break;
+ *   case "suppressed": logSuppressed(); break;
+ * }
+ * ```
+ *
+ * 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.
+ */
+import { enforceSpecPolicy, rejectWith, toErrorPayload, validateBasic, } from "./document.js";
+import { identityMismatchReason, reject, resolveParties, } from "./transport.js";
+/** Wire-safe message for the `rejectIfPresent` path. */
+export const PROOF_NOT_ACCEPTED_BY_POLICY = "in-band proof not accepted by consumer policy (SPEC §7.2 item 7)";
+/**
+ * Run SPEC §7.2 items 4–8 against `doc`, then either call the handler or build
+ * the routed error response per §8.1.
+ *
+ * ⚠ A handler-returned {@link ErrorResponse} is passed through verbatim — the
+ * framework does not re-apply §8.1 routing to it. A handler rejecting for
+ * identity-style reasons MUST address the response itself (see `reject` in
+ * ./transport.js); `rejectWith` copies `doc.issuer` into `recipient`, which is
+ * safe for ordinary refusals but not for one that contests that identity.
+ */
+export async function consumeInbound(opts) {
+    const { transport, spec, proofPolicy, doc, myVid, now, newErrorId, handler, clock } = opts;
+    const route = (reason) => {
+        const error = reject(transport, doc, newErrorId(), reason, clock);
+        return error === undefined ? { kind: "suppressed", reason } : { kind: "rejected", error };
+    };
+    // §7.2 items 4 + 5a — expiry and wrong-recipient.
+    const basic = validateBasic(doc, now, myVid);
+    if (basic !== null)
+        return route(basic);
+    // §7.2 item 6 — in-band vs transport-derived identity cross-check.
+    const resolved = resolveParties(transport, doc);
+    if ("error" in resolved)
+        return route(identityMismatchReason(resolved.error));
+    // §7.2 item 7 clause B — the consumer's chosen proof policy.
+    if (doc.proof !== undefined) {
+        switch (proofPolicy.kind) {
+            case "verify": {
+                let ok;
+                try {
+                    ok = await proofPolicy.verify.verify(doc);
+                }
+                catch (e) {
+                    ok = false;
+                }
+                if (!ok) {
+                    return route({
+                        code: "proofInvalid",
+                        message: "proof verification failed",
+                        retryable: false,
+                    });
+                }
+                break;
+            }
+            case "rejectIfPresent":
+                return route({
+                    code: "malformedRequest",
+                    message: PROOF_NOT_ACCEPTED_BY_POLICY,
+                    retryable: false,
+                });
+            case "acceptUnverified":
+                break;
+        }
+    }
+    // §7.2 items 5b + 7 clause A + 8 — the policy-driven checks, in one place so
+    // this pipeline and any binding-specific one cannot diverge on the check set.
+    const policy = enforceSpecPolicy(doc, spec);
+    if (policy !== null)
+        return route(policy);
+    const result = await handler(doc, resolved.parties);
+    return isErrorResponse(result)
+        ? { kind: "rejected", error: result }
+        : { kind: "handled", response: result };
+}
+/**
+ * Whether a handler returned an error response rather than a success response.
+ *
+ * Keys off the `trust-task-error` Type URI rather than payload shape: §8 makes
+ * the type the discriminator, and a success payload could coincidentally carry
+ * a `code` member.
+ */
+function isErrorResponse(doc) {
+    return doc.type.split("#")[0].includes("/trust-task-error/");
+}
+/**
+ * Build a handler-side refusal addressed to the original producer.
+ *
+ * Convenience over `rejectWith` + `toErrorPayload` for the common case where a
+ * handler refuses for a business reason. Not safe for refusals that contest the
+ * in-band identity — see the warning on {@link consumeInbound}.
+ */
+export function refuse(request, id, reason, clock) {
+    return rejectWith(request, id, toErrorPayload(reason), clock);
+}
+//# sourceMappingURL=consume.js.map

package/dist/_runtime/consume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consume.js","sourceRoot":"","sources":["../../src/_runtime/consume.ts"],"names":[],"mappings":"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"}