macp-sdk-typescript 0.17.1 → 0.18.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to `macp-sdk-typescript` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 project uses [Semantic Versioning](https://semver.org/).
 
+## [0.18.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.17.1...v0.18.0) (2026-10-25)
+
+
+### Features
+
+* **receipt:** RFC-MACP-0013 Appendix A decision receipts (W3.10) ([#195](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/195)) ([1ef38ef](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/1ef38ef4e899a74eb7b4c8207f9556a31d0dba0f))
+
 ## [0.17.1](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.17.0...v0.17.1) (2026-10-20)
 
 

package/README.md

@@ -8,25 +8,25 @@ runtime behavior is documented in the [runtime repo's docs](https://github.com/m
 
 ## Install
 
-Requires Node.js >= 20.
+Requires Node.js >= 20 (`engines` in `package.json`); CI runs on Node 22 and 24.
 
 ```bash
 npm install macp-sdk-typescript
 ```
 
-The SDK depends on `@multiagentcoordinationprotocol/proto` from GitHub Packages. Create a `.npmrc` in your project root:
+Everything installs from npmjs, including the `@multiagentcoordinationprotocol/proto` dependency (published there from 0.1.11). No `.npmrc` or GitHub token is needed.
 
-```
-@multiagentcoordinationprotocol:registry=https://npm.pkg.github.com
-```
+## Quick Start
 
-And configure a GitHub PAT with `read:packages` scope:
+Start a local runtime (the same image CI pins):
 
 ```bash
-npm config set //npm.pkg.github.com/:_authToken YOUR_GITHUB_PAT
+docker run -p 50051:50051 -e MACP_ALLOW_INSECURE=1 -e MACP_MEMORY_ONLY=1 ghcr.io/multiagentcoordinationprotocol/macp-runtime:0.9.0
 ```
 
-## Quick Start
+`MACP_ALLOW_INSECURE=1` permits plaintext and dev-agent auth (local development only —
+since runtime 0.5.0 a runtime with no auth configured refuses to start without it);
+`MACP_MEMORY_ONLY=1` skips on-disk persistence. Then connect:
 
 ```typescript
 import { Auth, MacpClient, DecisionSession } from 'macp-sdk-typescript';
@@ -79,6 +79,7 @@ The SDK uses a **three-layer** design:
 See [`docs/guides/architecture.md`](docs/guides/architecture.md) for the full map.
 
 Every session class follows the same pattern:
+
 1. Construct with a `MacpClient` and options
 2. Call `start()` to initiate the session
 3. Call mode-specific methods (propose, vote, accept, etc.)
@@ -94,8 +95,8 @@ await session.start({
   intent: 'pick a deployment strategy',
   participants: ['alice', 'bob'],
   ttlMs: 60_000,
-  contextId: 'ctx-abc',                           // optional opaque context reference
-  extensions: { 'x-trace': Buffer.from('tid') },  // optional typed extension buffers
+  contextId: 'ctx-abc', // optional opaque context reference
+  extensions: { 'x-trace': Buffer.from('tid') }, // optional typed extension buffers
   roots: [{ uri: 'file:///workspace', name: 'repo' }],
 });
 ```
@@ -121,9 +122,9 @@ await session.vote({ proposalId: 'p1', vote: 'approve' });
 await session.commit({ action: 'decided', authorityScope: 'team', reason: '...' });
 
 // Projection queries
-session.projection.voteTotals();                 // { p1: 1 }
-session.projection.majorityWinner();             // 'p1'
-session.projection.hasBlockingObjection('p1');   // false (only severity 'critical' blocks)
+session.projection.voteTotals(); // { p1: 1 }
+session.projection.majorityWinner(); // 'p1'
+session.projection.hasBlockingObjection('p1'); // false (only severity 'critical' blocks)
 ```
 
 ### Proposal Mode
@@ -145,9 +146,9 @@ await session.accept({ proposalId: 'p2', reason: 'bob agrees', sender: 'bob', au
 await session.commit({ action: 'proposal.accepted', authorityScope: 'team', reason: '...' });
 
 // Projection queries
-session.projection.activeProposals();            // proposals with status 'open'
-session.projection.isAccepted('p2');             // true
-session.projection.isTerminallyRejected('p1');   // false
+session.projection.activeProposals(); // proposals with status 'open'
+session.projection.isAccepted('p2'); // true
+session.projection.isTerminallyRejected('p1'); // false
 ```
 
 ### Task Mode
@@ -170,9 +171,9 @@ await session.completeTask({ taskId: 't1', assignee: 'worker', summary: 'done',
 await session.commit({ action: 'task.completed', authorityScope: 'lead', reason: '...' });
 
 // Projection queries
-session.projection.progressOf('t1');   // 1.0
-session.projection.isCompleted('t1');  // true
-session.projection.activeTasks();      // []
+session.projection.progressOf('t1'); // 1.0
+session.projection.isCompleted('t1'); // true
+session.projection.activeTasks(); // []
 ```
 
 ### Handoff Mode
@@ -199,8 +200,8 @@ await session.acceptHandoff({
 await session.commit({ action: 'handoff.accepted', authorityScope: 'team', reason: '...' });
 
 // Projection queries
-session.projection.isAccepted('h1');      // true
-session.projection.pendingHandoffs();     // []
+session.projection.isAccepted('h1'); // true
+session.projection.pendingHandoffs(); // []
 ```
 
 ### Quorum Mode
@@ -222,10 +223,10 @@ await session.approve({ requestId: 'r1', reason: 'ok', sender: 'bob', auth: Auth
 await session.commit({ action: 'quorum.approved', authorityScope: 'ops', reason: '...' });
 
 // Projection queries
-session.projection.hasQuorum('r1');              // true
-session.projection.approvalCount('r1');          // 2
-session.projection.remainingVotesNeeded('r1');   // 0
-session.projection.votedSenders('r1');           // ['alice', 'bob']
+session.projection.hasQuorum('r1'); // true
+session.projection.approvalCount('r1'); // 2
+session.projection.remainingVotesNeeded('r1'); // 0
+session.projection.votedSenders('r1'); // ['alice', 'bob']
 ```
 
 ## Agent Framework
@@ -305,9 +306,16 @@ Composable handler factories for Decision Mode — register them directly on a
 
 ```typescript
 participant
-  .on('Proposal', agent.evaluationHandler(agent.functionEvaluator(async (p) => ({
-    recommendation: 'APPROVE', confidence: 0.9, reason: 'looks good',
-  }))))
+  .on(
+    'Proposal',
+    agent.evaluationHandler(
+      agent.functionEvaluator(async (p) => ({
+        recommendation: 'APPROVE',
+        confidence: 0.9,
+        reason: 'looks good',
+      })),
+    ),
+  )
   .on('Evaluation', agent.votingHandler(agent.majorityVoter({ positiveThreshold: 0.6 })))
   .on('Vote', agent.commitmentHandler(agent.majorityCommitter({ quorumSize: 2 })));
 ```
@@ -389,9 +397,9 @@ To attach to a session that is already in flight and receive accepted history be
 
 ```typescript
 const stream = client.openStream({ auth });
-await stream.sendSubscribe(sessionId);            // full replay then live
+await stream.sendSubscribe(sessionId); // full replay then live
 // or, after a reconnect:
-await stream.sendSubscribe(sessionId, lastSeq);    // resume from cursor
+await stream.sendSubscribe(sessionId, lastSeq); // resume from cursor
 ```
 
 The agent framework's `GrpcTransportAdapter` calls this for you on start, so non-initiator agents see `SessionStart` regardless of join order — and it passes its own resume cursor on a second `start()` (after a `stop()`), so that call resumes rather than replaying the whole session again.
@@ -413,6 +421,43 @@ for await (const change of watcher.changes(controller.signal)) {
 const next = await watcher.nextChange();
 ```
 
+## Decision Receipts
+
+A decision receipt (RFC-MACP-0013 Appendix A, `macp-receipt/1`) records one Commitment in a form a third party can check offline. The verifier reports two things separately:
+
+- **Integrity**: the receipt's `commitment` has its `commitment_hash`. This needs no keys.
+- **Authenticity**: an attestation over the receipt is valid for a key you trust. The SDK implements Ed25519 `jws` attestations only.
+
+```typescript
+import { buildReceipt, verifyReceipt } from 'macp-sdk-typescript/receipt';
+
+// Issue: hash the commitment and sign the receipt body (detached JWS, alg EdDSA).
+const receipt = buildReceipt(commitmentPayload, {
+  sessionId,
+  mode: 'macp.mode.decision.v1',
+  issuer: 'runtime:prod-eu',
+  issuedAt: new Date().toISOString(),
+  signer: { kid: 'prod-2026', privateKey: seed32 }, // or { kid, sign: (bytes) => signature64 }
+  commitmentWire, // optional: Commitment wire bytes, recorded as commitment_wire_b64
+});
+
+// Verify: trusted keys map a kid to an Ed25519 public key (JWK `x`, base64url).
+const result = verifyReceipt(receipt, { 'prod-2026': 'TDVzkxaSf6_Oxu7mmn5TbCkF80s8Ulh33qKQsi0gnZM' });
+// { integrity: 'match', attestations: ['valid'], verdict: 'attested' }
+```
+
+| Field             | Values                                                                                                                                                                                         |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `integrity`       | `match`, `mismatch`, `cannot_verify`, or `null` when the receipt is refused                                                                                                                    |
+| `attestations[i]` | `valid`, `invalid`, `unknown_key` or `unsupported` (any other `alg`, and every `vendor` attestation)                                                                                           |
+| `verdict`         | `attested` (integrity holds and at least one attestation is valid), `integrity_only`, `unverified` (integrity fails, so attestations are not checked), or `refused` (unknown `receipt_format`) |
+
+If you hold the snake_case §3 projection (a receipt's `commitment`) instead of a `CommitmentPayload`, convert it with `commitmentFromProjection(projection)`.
+
+`verifyReceipt` never throws. `buildReceipt` throws `MacpSdkError` on a missing field, and when `commitmentWire` is not the wire encoding of the commitment. Signing is deterministic: the same inputs always produce the same receipt.
+
+The `macp-sdk-typescript/receipt` subpath is browser-safe: it pulls in no gRPC, no `node:crypto` and no `Buffer`. The same functions are also exported from the package root. The tests replay the spec's `schemas/conformance/receipt/` vectors and rebuild the spec's example receipt byte for byte.
+
 ## Error Handling
 
 ```typescript
@@ -454,11 +499,10 @@ cleanly fails that workflow, not just a local check.
 Run the full SDK against a live MACP runtime:
 
 ```bash
-# Build and start the runtime
-docker build -t macp-runtime ../macp-runtime/
+# Start the runtime (CI's pinned image)
 docker run -d --name macp-runtime-test -p 50051:50051 \
-  -e MACP_BIND_ADDR=0.0.0.0:50051 -e MACP_ALLOW_INSECURE=1 \
-  -e MACP_MEMORY_ONLY=1 macp-runtime
+  -e MACP_ALLOW_INSECURE=1 -e MACP_MEMORY_ONLY=1 \
+  ghcr.io/multiagentcoordinationprotocol/macp-runtime:0.9.0
 
 # Run tests
 npm run test:integration

package/dist/commitment-hash.d.ts

@@ -1,4 +1,46 @@
 import type { CommitmentPayload } from './types';
+/**
+ * Escapes a single JSON string value per RFC 8785 §3.2.2.2:
+ *   - short-form escapes for backspace/tab/newline/formfeed/carriage-return,
+ *     `"`, and `\`
+ *   - `\u00xx` (lowercase hex) for other C0 control characters (0x00-0x1F)
+ *   - every other character, including non-ASCII and astral-plane
+ *     codepoints, is emitted literally (NOT escaped).
+ *
+ * Lone surrogates: a bare UTF-16 surrogate code unit not paired into a valid
+ * codepoint is out-of-contract input for this function — a `CommitmentPayload`
+ * should never legitimately contain one, since this SDK's strings originate
+ * from valid UTF-16 sources (JS string literals, JSON-decoded wire payloads,
+ * etc.). If one appears anyway, this function does not detect or escape it
+ * specially: `for (const ch of str)` below yields it as its own one-code-unit
+ * step and it is emitted literally, unescaped, like any other character. The
+ * actual loss happens one step later, in `commitmentHash`, when the finished
+ * JCS string is encoded to bytes via `TextEncoder` — the standard lossy UTF-8
+ * encoder silently substitutes a lone surrogate with
+ * U+FFFD (the Unicode replacement character) before hashing. The observable
+ * consequence: a field containing a lone surrogate (e.g. `'\uD800'`) hashes
+ * IDENTICALLY to the same field containing a literal U+FFFD in that position
+ * — pinned by the "lone surrogate" test in commitment-hash.test.ts. This is
+ * an accepted consequence of D3 (never throw on malformed input), not a
+ * claimed point of compatibility (or divergence) with any other
+ * implementation of RFC-MACP-0013.
+ *
+ * `value` is typed `unknown`, not `string`, on purpose: this function is the
+ * single choke point that keeps `commitmentHash` from ever throwing (D3) —
+ * every field of a `CommitmentPayload` flows through here, and at runtime a
+ * decoded or hand-built payload is not guaranteed to actually match its
+ * static type. Non-string input is coerced via `String()` (never a template
+ * literal or `+`, both of which throw on a bare `Symbol`) rather than
+ * rejected — this file does not "fix" a malformed payload into a valid one,
+ * it only guarantees serialization cannot crash.
+ *
+ * Iterates with `for (const ch of str)`, which walks Unicode codepoints, not
+ * UTF-16 code units. Indexing by code unit would split an astral-plane
+ * codepoint's surrogate pair (e.g. U+1F702) and emit half of it — iterating
+ * by codepoint is what keeps a full character, including a surrogate pair,
+ * together as a single loop step so it can be appended whole.
+ */
+export declare function jcsString(value: unknown): string;
 /**
  * Projects a `CommitmentPayload` (this SDK's camelCase shape) to its RFC
  * 8785 canonical JSON string (snake_case, D2.1) and serializes it directly
@@ -74,6 +116,13 @@ export declare function isCanonicalCommitmentHash(value: string): boolean;
  * is a verdict on the payload encoding — never on the claim.
  */
 export type VerifyOutcome = 'match' | 'mismatch' | 'cannot_verify';
+/**
+ * Strictly decodes a `CommitmentPayload` wire encoding for the decision-receipt
+ * verifier (`./receipt`), which must compare the wire against the receipt's
+ * own `commitment`. `undefined` wherever {@link verifyCommitmentHash} would say
+ * `'cannot_verify'`. Internal: not re-exported from the package root.
+ */
+export declare function decodeCommitmentWire(wire: Uint8Array): CommitmentPayload | undefined;
 /**
  * Verifies a claimed commitment hash against a `CommitmentPayload`'s Protobuf
  * wire encoding (RFC-MACP-0013 §6.1), returning exactly one of:

package/dist/commitment-hash.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.jcsString = jcsString;
 exports.canonicalizeCommitmentPayload = canonicalizeCommitmentPayload;
 exports.commitmentHash = commitmentHash;
 exports.isCanonicalCommitmentHash = isCanonicalCommitmentHash;
+exports.decodeCommitmentWire = decodeCommitmentWire;
 exports.verifyCommitmentHash = verifyCommitmentHash;
 /**
  * RFC-MACP-0013 canonical commitment hashing.
@@ -19,16 +21,22 @@ exports.verifyCommitmentHash = verifyCommitmentHash;
  * only strings, one boolean, and one optional 2-string nested object. No
  * JSON numbers, no JSON arrays. That leaves only object-member ordering and
  * string escaping, both of which are small enough to hand-write and test
- * directly rather than pull in this SDK's first non-gRPC/proto runtime
- * dependency. `node:crypto` is a Node builtin, not a dependency.
+ * directly rather than pull in a JCS dependency.
+ *
+ * SHA-256 comes from `@noble/hashes` (pure JS, audited, zero dependencies)
+ * rather than `node:crypto`, so this module, and the decision-receipt module
+ * built on it (`./receipt`), load in a browser bundle as well as in Node.
+ * Strings are encoded with `TextEncoder`, not `Buffer`, for the same reason.
  */
-const node_crypto_1 = require("node:crypto");
+const sha2_1 = require("@noble/hashes/sha2");
+const utils_1 = require("@noble/hashes/utils");
 /**
  * Domain-separation label mixed into the hash preimage (RFC-MACP-0013 §4).
  * Changing this string changes every hash this module produces — that is a
  * protocol MINOR version bump, not a routine edit.
  */
 const LABEL = 'macp-commitment-hash/1';
+const UTF8 = new TextEncoder();
 /**
  * Escapes a single JSON string value per RFC 8785 §3.2.2.2:
  *   - short-form escapes for backspace/tab/newline/formfeed/carriage-return,
@@ -45,8 +53,8 @@ const LABEL = 'macp-commitment-hash/1';
  * specially: `for (const ch of str)` below yields it as its own one-code-unit
  * step and it is emitted literally, unescaped, like any other character. The
  * actual loss happens one step later, in `commitmentHash`, when the finished
- * JCS string is encoded to bytes via `Buffer.from(preimage, 'utf8')` — Node's
- * standard lossy UTF-8 encoder silently substitutes a lone surrogate with
+ * JCS string is encoded to bytes via `TextEncoder` — the standard lossy UTF-8
+ * encoder silently substitutes a lone surrogate with
  * U+FFFD (the Unicode replacement character) before hashing. The observable
  * consequence: a field containing a lone surrogate (e.g. `'\uD800'`) hashes
  * IDENTICALLY to the same field containing a literal U+FFFD in that position
@@ -211,8 +219,7 @@ function canonicalizeCommitmentPayload(payload) {
 function commitmentHash(payload) {
     const jcs = canonicalizeCommitmentPayload(payload);
     const preimage = `${LABEL}:${jcs}`;
-    const digest = (0, node_crypto_1.createHash)('sha256').update(Buffer.from(preimage, 'utf8')).digest('hex');
-    return `sha256:${digest}`;
+    return `sha256:${(0, utils_1.bytesToHex)((0, sha2_1.sha256)(UTF8.encode(preimage)))}`;
 }
 /**
  * The same shape `commitmentHash` always produces: `sha256:` followed by 64
@@ -376,6 +383,24 @@ function decodeCommitmentPayloadStrict(wire) {
     }
     return payload;
 }
+/**
+ * Strictly decodes a `CommitmentPayload` wire encoding for the decision-receipt
+ * verifier (`./receipt`), which must compare the wire against the receipt's
+ * own `commitment`. `undefined` wherever {@link verifyCommitmentHash} would say
+ * `'cannot_verify'`. Internal: not re-exported from the package root.
+ */
+function decodeCommitmentWire(wire) {
+    if (!(wire instanceof Uint8Array))
+        return undefined;
+    try {
+        return decodeCommitmentPayloadStrict(wire);
+    }
+    catch (err) {
+        if (err instanceof CannotVerify)
+            return undefined;
+        throw err;
+    }
+}
 /**
  * Verifies a claimed commitment hash against a `CommitmentPayload`'s Protobuf
  * wire encoding (RFC-MACP-0013 §6.1), returning exactly one of:

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from './proposal';
 export * from './proto-registry';
 export * from './retry';
 export * from './quorum';
+export { RECEIPT_FORMAT, buildReceipt, commitmentFromProjection, verifyReceipt, type AttestationOutcome, type BuildReceiptOptions, type DecisionReceipt, type JwsAttestation, type ReceiptAttestation, type ReceiptCommitment, type ReceiptIntegrity, type ReceiptSigner, type ReceiptVerdict, type ReceiptVerification, type VendorAttestation, } from './receipt';
 export * from './task';
 export * from './types';
 export * from './validation';

package/dist/index.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.agent = exports.VERSION = exports.logger = exports.configureLogging = exports.verifyCommitmentHash = exports.isCanonicalCommitmentHash = exports.commitmentHash = exports.Auth = void 0;
+exports.agent = exports.VERSION = exports.verifyReceipt = exports.commitmentFromProjection = exports.buildReceipt = exports.RECEIPT_FORMAT = exports.logger = exports.configureLogging = exports.verifyCommitmentHash = exports.isCanonicalCommitmentHash = exports.commitmentHash = exports.Auth = void 0;
 // Auth: export only the public constructors and types. The helpers
 // `validateAuth`, `authSender`, `assertSenderMatchesIdentity`, and
 // `metadataFromAuth` are SDK-internal — importable from the `./auth`
@@ -78,6 +78,13 @@ __exportStar(require("./proposal"), exports);
 __exportStar(require("./proto-registry"), exports);
 __exportStar(require("./retry"), exports);
 __exportStar(require("./quorum"), exports);
+// RFC-MACP-0013 Appendix A decision receipts. Also published as the
+// browser-safe `macp-sdk-typescript/receipt` subpath (no gRPC, no node:crypto).
+var receipt_1 = require("./receipt");
+Object.defineProperty(exports, "RECEIPT_FORMAT", { enumerable: true, get: function () { return receipt_1.RECEIPT_FORMAT; } });
+Object.defineProperty(exports, "buildReceipt", { enumerable: true, get: function () { return receipt_1.buildReceipt; } });
+Object.defineProperty(exports, "commitmentFromProjection", { enumerable: true, get: function () { return receipt_1.commitmentFromProjection; } });
+Object.defineProperty(exports, "verifyReceipt", { enumerable: true, get: function () { return receipt_1.verifyReceipt; } });
 __exportStar(require("./task"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./validation"), exports);

package/dist/receipt.d.ts

@@ -0,0 +1,124 @@
+import type { CommitmentPayload } from './types';
+/** The only receipt format this module issues and verifies. */
+export declare const RECEIPT_FORMAT = "macp-receipt/1";
+/** RFC-MACP-0013 §3 projection of a `CommitmentPayload`, as recorded in a receipt. */
+export interface ReceiptCommitment {
+    commitment_id: string;
+    action: string;
+    authority_scope: string;
+    reason: string;
+    mode_version: string;
+    policy_version: string;
+    configuration_version: string;
+    outcome_positive: boolean;
+    supersedes?: {
+        session_id: string;
+        commitment_hash: string;
+    };
+}
+export interface JwsAttestation {
+    type: 'jws';
+    /** Compact JWS with a detached payload: `<protected header>..<signature>`. */
+    jws: string;
+}
+export interface VendorAttestation {
+    type: 'vendor';
+    format: string;
+    binds: 'commitment_hash' | 'receipt' | 'other';
+    value: string;
+}
+export type ReceiptAttestation = JwsAttestation | VendorAttestation;
+/** A `macp-receipt/1` decision receipt (RFC-MACP-0013 Appendix A.2). */
+export interface DecisionReceipt {
+    receipt_format: typeof RECEIPT_FORMAT;
+    session_id: string;
+    mode: string;
+    commitment: ReceiptCommitment;
+    commitment_hash: string;
+    commitment_wire_b64?: string;
+    semantics_rev?: {
+        implementation: string;
+        rev: number;
+    };
+    transcript?: {
+        digest_alg: string;
+        digest: string;
+        message_count?: number;
+    };
+    issuer: string;
+    issued_at: string;
+    attestations: ReceiptAttestation[];
+}
+/**
+ * Signs a receipt with Ed25519: either a 32-byte private key seed, or a
+ * callback that returns the 64-byte signature over `signingInput` (for a key
+ * held elsewhere, such as an HSM, as long as it signs synchronously).
+ */
+export type ReceiptSigner = {
+    kid: string;
+    privateKey: Uint8Array;
+} | {
+    kid: string;
+    sign: (signingInput: Uint8Array) => Uint8Array;
+};
+export interface BuildReceiptOptions {
+    sessionId: string;
+    mode: string;
+    /** Opaque identifier of the issuer (A.2). Not a trust anchor. */
+    issuer: string;
+    /** RFC 3339 UTC time of issue, recorded verbatim. */
+    issuedAt: string;
+    /** Adds one `jws` attestation. Without it, `attestations` is `[]`. */
+    signer?: ReceiptSigner;
+    /** RFC-MACP-0003 §3.2 semantics revision, scoped to its implementation. */
+    semanticsRev?: {
+        implementation: string;
+        rev: number;
+    };
+    /** Implementation-defined digest of the session history (RFC-MACP-0013 §10). */
+    transcript?: {
+        digestAlg: string;
+        digest: string;
+        messageCount?: number;
+    };
+    /** The payload's Protobuf wire encoding; recorded as `commitment_wire_b64`. */
+    commitmentWire?: Uint8Array;
+}
+/** A.4 step 2. `null` only when the receipt is refused at step 1. */
+export type ReceiptIntegrity = 'match' | 'mismatch' | 'cannot_verify' | null;
+/** A.4 step 3, one per attestation. */
+export type AttestationOutcome = 'valid' | 'invalid' | 'unknown_key' | 'unsupported';
+/** A.4 step 4 (step 1 for `refused`). */
+export type ReceiptVerdict = 'attested' | 'integrity_only' | 'unverified' | 'refused';
+export interface ReceiptVerification {
+    integrity: ReceiptIntegrity;
+    /** One outcome per entry of `attestations`, in order; `[]` unless integrity is `match`. */
+    attestations: AttestationOutcome[];
+    verdict: ReceiptVerdict;
+}
+/**
+ * Converts a snake_case §3 projection (a receipt's `commitment`, or the same
+ * shape from a control plane) into the camelCase `CommitmentPayload` that
+ * {@link buildReceipt} and `commitmentHash` take. Throws `MacpSdkError` when
+ * it is not a complete, well-typed projection.
+ */
+export declare function commitmentFromProjection(projection: ReceiptCommitment): CommitmentPayload;
+/**
+ * Builds a `macp-receipt/1` receipt for `commitment` (RFC-MACP-0013
+ * Appendix A). Computes `commitment_hash`; with a `signer`, adds one
+ * detached-payload EdDSA `jws` attestation over the receipt body. Ed25519 is
+ * deterministic, so the same inputs always give the same receipt.
+ *
+ * Throws `MacpSdkError` on a missing required option, and when
+ * `commitmentWire` does not verify against, or does not decode to,
+ * `commitment`, so no receipt is issued that its own verifier would reject.
+ */
+export declare function buildReceipt(commitment: CommitmentPayload, options: BuildReceiptOptions): DecisionReceipt;
+/**
+ * Verifies a decision receipt (RFC-MACP-0013 Appendix A.4) against the keys
+ * the caller trusts: `trustedKeys` maps a `kid` to an Ed25519 public key as a
+ * JWK `x` (base64url). Returns the integrity outcome, one outcome per
+ * attestation, and the overall verdict, in the spec vectors' vocabulary.
+ * Never throws: malformed input yields an outcome, not an exception.
+ */
+export declare function verifyReceipt(receipt: unknown, trustedKeys: Record<string, string>): ReceiptVerification;

package/dist/receipt.js

@@ -0,0 +1,376 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECEIPT_FORMAT = void 0;
+exports.commitmentFromProjection = commitmentFromProjection;
+exports.buildReceipt = buildReceipt;
+exports.verifyReceipt = verifyReceipt;
+/**
+ * RFC-MACP-0013 Appendix A decision receipts (`macp-receipt/1`).
+ *
+ * A receipt is a portable record of one binding Commitment that a third party
+ * can check offline. Two properties are reported separately (A.1):
+ *
+ * - **integrity**: the recorded `commitment` has the recorded
+ *   `commitment_hash` (and, when `commitment_wire_b64` is present, the wire
+ *   passes §6.1 verification and decodes to `commitment`). Needs no keys.
+ * - **authenticity**: some attestation over the receipt body is valid for a
+ *   key the verifier trusts. Only `jws` attestations with `alg: EdDSA` are
+ *   implemented; `vendor` attestations are always `unsupported`.
+ *
+ * Receipt JSON keeps the schema's snake_case keys
+ * (`schemas/json/macp-decision-receipt.schema.json` in the spec repo); the
+ * functions here take camelCase options, like the rest of the SDK.
+ *
+ * Browser-safe: this module and `./commitment-hash` import no gRPC, no
+ * `node:crypto` and no `Buffer`. It is published as the
+ * `macp-sdk-typescript/receipt` subpath for client bundles.
+ */
+const ed25519_1 = require("@noble/curves/ed25519");
+const commitment_hash_1 = require("./commitment-hash");
+const errors_1 = require("./errors");
+/** The only receipt format this module issues and verifies. */
+exports.RECEIPT_FORMAT = 'macp-receipt/1';
+// --- encodings -------------------------------------------------------------
+const UTF8 = new TextEncoder();
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const B64URL = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const STRICT_B64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+const STRICT_B64URL = /^[A-Za-z0-9_-]+$/;
+function encodeBase64(bytes, alphabet, pad) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const n = (bytes[i] << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+        const chars = Math.min(4, Math.ceil(((bytes.length - i) * 8) / 6));
+        for (let c = 0; c < 4; c++) {
+            if (c < chars)
+                out += alphabet[(n >> (18 - 6 * c)) & 63];
+            else if (pad)
+                out += '=';
+        }
+    }
+    return out;
+}
+/** Decodes unpadded base64 digits; the caller has already checked the alphabet. */
+function decodeDigits(text, alphabet) {
+    if (text.length % 4 === 1)
+        return undefined;
+    const out = new Uint8Array(Math.floor((text.length * 6) / 8));
+    let acc = 0;
+    let bits = 0;
+    let j = 0;
+    for (const ch of text) {
+        acc = (acc << 6) | alphabet.indexOf(ch);
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[j++] = (acc >> bits) & 0xff;
+        }
+    }
+    return out;
+}
+/** Strict standard base64, padding required (Python's `b64decode(validate=True)`). */
+function decodeBase64(text) {
+    if (!STRICT_B64.test(text))
+        return undefined;
+    return decodeDigits(text.replace(/=+$/, ''), B64);
+}
+/** Strict unpadded base64url, non-empty. */
+function decodeBase64Url(text) {
+    if (!STRICT_B64URL.test(text))
+        return undefined;
+    return decodeDigits(text, B64URL);
+}
+const b64url = (bytes) => encodeBase64(bytes, B64URL, false);
+/**
+ * RFC 8785 serialization of a receipt body. Unlike the §3 projection, a body
+ * carries integers (`rev`, `message_count`); `JSON.stringify` of a finite
+ * number is exactly the JCS number form. Keys sort by UTF-16 code units,
+ * which is JavaScript's default string order.
+ */
+function jcs(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'string')
+        return (0, commitment_hash_1.jcsString)(value);
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new errors_1.MacpSdkError('a receipt body cannot contain a non-finite number');
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(jcs).join(',')}]`;
+    if (typeof value === 'object') {
+        const entries = Object.entries(value).filter(([, v]) => v !== undefined);
+        entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, v]) => `${(0, commitment_hash_1.jcsString)(k)}:${jcs(v)}`).join(',')}}`;
+    }
+    throw new errors_1.MacpSdkError(`a receipt body cannot contain a ${typeof value}`);
+}
+/** The receipt body (A.2): the receipt without `attestations`, in JCS. */
+function receiptBody(receipt) {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- removed from the body
+    const { attestations: _omitted, ...body } = receipt;
+    return UTF8.encode(jcs(body));
+}
+// --- projection ------------------------------------------------------------
+const STRING_FIELDS = [
+    'commitment_id',
+    'action',
+    'authority_scope',
+    'reason',
+    'mode_version',
+    'policy_version',
+    'configuration_version',
+];
+const ALLOWED_FIELDS = new Set([...STRING_FIELDS, 'outcome_positive', 'supersedes']);
+/** The §3 projection, with `policy_version`/`outcome_positive` materialized and `supersedes` only when present. */
+function project(payload) {
+    const out = {
+        commitment_id: payload.commitmentId ?? '',
+        action: payload.action ?? '',
+        authority_scope: payload.authorityScope ?? '',
+        reason: payload.reason ?? '',
+        mode_version: payload.modeVersion ?? '',
+        policy_version: payload.policyVersion ?? '',
+        configuration_version: payload.configurationVersion ?? '',
+        outcome_positive: payload.outcomePositive ?? false,
+    };
+    if (payload.supersedes != null) {
+        out.supersedes = {
+            session_id: payload.supersedes.sessionId ?? '',
+            commitment_hash: payload.supersedes.commitmentHash ?? '',
+        };
+    }
+    return out;
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * Reads a receipt's `commitment` back into a `CommitmentPayload`, or
+ * `undefined` when it is not a complete, well-typed §3 projection: an unknown
+ * member at either level, a missing member, or a wrongly typed one. That is
+ * outside what `macp-commitment-hash/1` covers, so it is `cannot_verify`.
+ */
+function readCommitment(value) {
+    if (!isRecord(value) || Object.keys(value).some((k) => !ALLOWED_FIELDS.has(k)))
+        return undefined;
+    if (STRING_FIELDS.some((f) => typeof value[f] !== 'string') || typeof value.outcome_positive !== 'boolean') {
+        return undefined;
+    }
+    const payload = {
+        commitmentId: value.commitment_id,
+        action: value.action,
+        authorityScope: value.authority_scope,
+        reason: value.reason,
+        modeVersion: value.mode_version,
+        policyVersion: value.policy_version,
+        configurationVersion: value.configuration_version,
+        outcomePositive: value.outcome_positive,
+    };
+    if ('supersedes' in value) {
+        const sup = value.supersedes;
+        if (!isRecord(sup) ||
+            Object.keys(sup).some((k) => k !== 'session_id' && k !== 'commitment_hash') ||
+            typeof sup.session_id !== 'string' ||
+            typeof sup.commitment_hash !== 'string') {
+            return undefined;
+        }
+        payload.supersedes = { sessionId: sup.session_id, commitmentHash: sup.commitment_hash };
+    }
+    return payload;
+}
+/**
+ * Converts a snake_case §3 projection (a receipt's `commitment`, or the same
+ * shape from a control plane) into the camelCase `CommitmentPayload` that
+ * {@link buildReceipt} and `commitmentHash` take. Throws `MacpSdkError` when
+ * it is not a complete, well-typed projection.
+ */
+function commitmentFromProjection(projection) {
+    const payload = readCommitment(projection);
+    if (!payload)
+        throw new errors_1.MacpSdkError('commitmentFromProjection: not a complete RFC-MACP-0013 §3 projection');
+    return payload;
+}
+function sameProjection(a, b) {
+    if (STRING_FIELDS.some((f) => a[f] !== b[f]) || a.outcome_positive !== b.outcome_positive)
+        return false;
+    if (!a.supersedes || !b.supersedes)
+        return !a.supersedes && !b.supersedes;
+    return (a.supersedes.session_id === b.supersedes.session_id && a.supersedes.commitment_hash === b.supersedes.commitment_hash);
+}
+// --- build -----------------------------------------------------------------
+function requireText(value, name) {
+    if (typeof value !== 'string' || value === '')
+        throw new errors_1.MacpSdkError(`buildReceipt: ${name} must be a non-empty string`);
+    return value;
+}
+function requireCount(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new errors_1.MacpSdkError(`buildReceipt: ${name} must be a non-negative integer`);
+    }
+    return value;
+}
+/**
+ * Builds a `macp-receipt/1` receipt for `commitment` (RFC-MACP-0013
+ * Appendix A). Computes `commitment_hash`; with a `signer`, adds one
+ * detached-payload EdDSA `jws` attestation over the receipt body. Ed25519 is
+ * deterministic, so the same inputs always give the same receipt.
+ *
+ * Throws `MacpSdkError` on a missing required option, and when
+ * `commitmentWire` does not verify against, or does not decode to,
+ * `commitment`, so no receipt is issued that its own verifier would reject.
+ */
+function buildReceipt(commitment, options) {
+    const projection = project(commitment);
+    const hash = (0, commitment_hash_1.commitmentHash)(commitment);
+    const receipt = {
+        receipt_format: exports.RECEIPT_FORMAT,
+        session_id: requireText(options.sessionId, 'sessionId'),
+        mode: requireText(options.mode, 'mode'),
+        commitment: projection,
+        commitment_hash: hash,
+    };
+    // Key order follows the spec's example and vectors: optional members after issued_at.
+    if (options.semanticsRev !== undefined) {
+        receipt.semantics_rev = {
+            implementation: requireText(options.semanticsRev.implementation, 'semanticsRev.implementation'),
+            rev: requireCount(options.semanticsRev.rev, 'semanticsRev.rev'),
+        };
+    }
+    receipt.issuer = requireText(options.issuer, 'issuer');
+    receipt.issued_at = requireText(options.issuedAt, 'issuedAt');
+    if (options.commitmentWire !== undefined) {
+        const wire = options.commitmentWire;
+        // A §6.1 match means the wire projects to exactly this commitment.
+        if (!(wire instanceof Uint8Array) || (0, commitment_hash_1.verifyCommitmentHash)(wire, hash) !== 'match') {
+            throw new errors_1.MacpSdkError('buildReceipt: commitmentWire is not the wire encoding of commitment');
+        }
+        receipt.commitment_wire_b64 = encodeBase64(wire, B64, true);
+    }
+    if (options.transcript !== undefined) {
+        const t = options.transcript;
+        receipt.transcript = {
+            digest_alg: requireText(t.digestAlg, 'transcript.digestAlg'),
+            digest: requireText(t.digest, 'transcript.digest'),
+        };
+        if (t.messageCount !== undefined)
+            receipt.transcript.message_count = requireCount(t.messageCount, 'transcript.messageCount');
+    }
+    receipt.attestations = [];
+    if (options.signer)
+        receipt.attestations.push(sign(receipt, options.signer));
+    return receipt;
+}
+function sign(receipt, signer) {
+    const kid = requireText(signer.kid, 'signer.kid');
+    // The protected header in JCS form: {"alg":"EdDSA","kid":"..."}.
+    const header = b64url(UTF8.encode(`{"alg":"EdDSA","kid":${(0, commitment_hash_1.jcsString)(kid)}}`));
+    const signingInput = UTF8.encode(`${header}.${b64url(receiptBody(receipt))}`);
+    let signature;
+    if ('privateKey' in signer) {
+        if (!(signer.privateKey instanceof Uint8Array) || signer.privateKey.length !== 32) {
+            throw new errors_1.MacpSdkError('buildReceipt: signer.privateKey must be a 32-byte Ed25519 seed');
+        }
+        signature = ed25519_1.ed25519.sign(signingInput, signer.privateKey);
+    }
+    else {
+        signature = signer.sign(signingInput);
+        if (!(signature instanceof Uint8Array) || signature.length !== 64) {
+            throw new errors_1.MacpSdkError('buildReceipt: signer.sign must return a 64-byte Ed25519 signature');
+        }
+    }
+    return { type: 'jws', jws: `${header}..${b64url(signature)}` };
+}
+// --- verify ----------------------------------------------------------------
+function integrity(receipt) {
+    const payload = readCommitment(receipt.commitment);
+    if (!payload)
+        return 'cannot_verify';
+    const claimed = receipt.commitment_hash;
+    if (typeof claimed !== 'string' || (0, commitment_hash_1.commitmentHash)(payload) !== claimed)
+        return 'mismatch';
+    if ('commitment_wire_b64' in receipt) {
+        const encoded = receipt.commitment_wire_b64;
+        const wire = typeof encoded === 'string' ? decodeBase64(encoded) : undefined;
+        if (!wire)
+            return 'cannot_verify';
+        const outcome = (0, commitment_hash_1.verifyCommitmentHash)(wire, claimed);
+        if (outcome !== 'match')
+            return outcome;
+        const decoded = (0, commitment_hash_1.decodeCommitmentWire)(wire);
+        if (!decoded || !sameProjection(project(decoded), project(payload)))
+            return 'mismatch';
+    }
+    return 'match';
+}
+function attestation(att, body, trustedKeys) {
+    // `vendor` (whatever it binds) and unknown types: no other format is implemented.
+    if (!isRecord(att) || att.type !== 'jws')
+        return 'unsupported';
+    const parts = typeof att.jws === 'string' ? att.jws.split('.') : [];
+    if (parts.length !== 3 || parts[1] !== '')
+        return 'invalid';
+    const headerBytes = decodeBase64Url(parts[0]);
+    const signature = decodeBase64Url(parts[2]);
+    if (!headerBytes || !signature)
+        return 'invalid';
+    let header;
+    try {
+        header = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(headerBytes));
+    }
+    catch {
+        return 'invalid';
+    }
+    if (!isRecord(header) || header.alg !== 'EdDSA')
+        return 'unsupported';
+    const kid = header.kid;
+    const key = typeof kid === 'string' && Object.prototype.hasOwnProperty.call(trustedKeys, kid) ? trustedKeys[kid] : undefined;
+    if (key === undefined)
+        return 'unknown_key';
+    const publicKey = typeof key === 'string' ? decodeBase64Url(key) : undefined;
+    if (!publicKey || publicKey.length !== 32 || signature.length !== 64)
+        return 'invalid';
+    try {
+        // zip215: false is RFC 8032's strict verification (canonical encodings, s < L).
+        return ed25519_1.ed25519.verify(signature, UTF8.encode(`${parts[0]}.${body}`), publicKey, { zip215: false })
+            ? 'valid'
+            : 'invalid';
+    }
+    catch {
+        return 'invalid';
+    }
+}
+/**
+ * Verifies a decision receipt (RFC-MACP-0013 Appendix A.4) against the keys
+ * the caller trusts: `trustedKeys` maps a `kid` to an Ed25519 public key as a
+ * JWK `x` (base64url). Returns the integrity outcome, one outcome per
+ * attestation, and the overall verdict, in the spec vectors' vocabulary.
+ * Never throws: malformed input yields an outcome, not an exception.
+ */
+function verifyReceipt(receipt, trustedKeys) {
+    if (!isRecord(receipt) || receipt.receipt_format !== exports.RECEIPT_FORMAT) {
+        return { integrity: null, attestations: [], verdict: 'refused' };
+    }
+    const result = integrity(receipt);
+    if (result !== 'match')
+        return { integrity: result, attestations: [], verdict: 'unverified' };
+    let body;
+    try {
+        body = b64url(receiptBody(receipt));
+    }
+    catch {
+        body = undefined; // a body with no JCS form: no signature over it can be valid
+    }
+    const keys = isRecord(trustedKeys) ? trustedKeys : {};
+    const outcomes = (Array.isArray(receipt.attestations) ? receipt.attestations : []).map((att) => body === undefined
+        ? isRecord(att) && att.type === 'jws'
+            ? 'invalid'
+            : 'unsupported'
+        : attestation(att, body, keys));
+    return {
+        integrity: 'match',
+        attestations: outcomes,
+        verdict: outcomes.includes('valid') ? 'attested' : 'integrity_only',
+    };
+}

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * Kept in sync with package.json by release-please (see the
  * `x-release-please-version` annotation).
  */
-export declare const VERSION = "0.17.1";
+export declare const VERSION = "0.18.0";

package/dist/version.js

@@ -7,4 +7,4 @@ exports.VERSION = void 0;
  * Kept in sync with package.json by release-please (see the
  * `x-release-please-version` annotation).
  */
-exports.VERSION = '0.17.1'; // x-release-please-version
+exports.VERSION = '0.18.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macp-sdk-typescript",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "TypeScript SDK for the MACP Rust runtime",
   "license": "Apache-2.0",
   "type": "commonjs",
@@ -11,6 +11,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./receipt": {
+      "types": "./dist/receipt.d.ts",
+      "default": "./dist/receipt.js"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -57,6 +61,8 @@
     "@grpc/grpc-js": "^1.14.3",
     "@grpc/proto-loader": "^0.8.0",
     "@multiagentcoordinationprotocol/proto": "^0.1.11",
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.8.0",
     "protobufjs": "^8.6.5"
   },
   "devDependencies": {