@reapp-sdk/express-middleware 0.1.0 → 0.2.0

package/README.md

@@ -1,206 +1,168 @@
-# @reapp-sdk/express-middleware 0.1.0
+# @reapp-sdk/express-middleware 0.2.0
 
-Fail-closed Express middleware for REAPP payment-gated APIs on Stellar.
+Fail-closed Express 4/5 paid JSON routes for REAPP on Stellar.
 
-The middleware issues an x402-style `402` challenge, accepts an `X-PAYMENT`
-settlement proof, and independently verifies the successful Stellar transaction
-before a protected handler runs. The transaction must contain one unambiguous
-payment event from the configured MandateRegistry and one matching SEP-41
-transfer from the mandate user to the configured merchant. Header claims never
-replace contract evidence.
-
-Supports Express 4 and Express 5. Ships as ESM with TypeScript declarations.
+The package authenticates an exact-origin GET challenge, verifies the on-chain
+settlement independently, atomically claims fulfillment, stores the exact JSON
+result before sending it, and replays those bytes on recovery. A settlement can
+never re-run arbitrary fulfillment work.
 
 ## Install
 
 ```bash
-npm install @reapp-sdk/express-middleware express
+npm install @reapp-sdk/express-middleware@0.2.0 express@5.2.1
 ```
 
-## Quick start
+The exact T2 compatibility name `@reapp/express-middleware` exposes the same
+typed ESM API.
+
+## Safe paid route
 
 ```ts
 import express from "express";
 import {
-  InMemoryRedemptionStore,
-  createReappPaymentMiddleware,
-  getVerifiedPayment,
+  InMemoryBoundRedemptionStore,
+  createBoundReappPaidJsonRoute,
 } from "@reapp-sdk/express-middleware";
 
 const app = express();
 
-const requirePayment = createReappPaymentMiddleware({
+const paidResearch = createBoundReappPaidJsonRoute({
   merchant: process.env.REAPP_MERCHANT_ADDRESS!,
   sourceAccount: process.env.REAPP_READ_SOURCE_ADDRESS!,
+  audience: "https://api.example", // exact public origin; never Host-derived
+  challengeSecret: process.env.REAPP_CHALLENGE_SECRET!, // at least 32 bytes
   amount: "1.00",
-  resource: "/source/market",
-  // Local development and one-process demos only. See Production replay safety.
-  redemptionStore: new InMemoryRedemptionStore(),
-});
-
-app.get("/source/market", requirePayment, (_request, response) => {
-  const payment = getVerifiedPayment(response);
-  response.json({
-    source: "verified research data",
-    settlement: payment?.txHash,
-    mandate: payment?.mandateId,
-  });
-});
-
+  resource: (request) => request.originalUrl,
+  // One-process demo only. Production needs a shared linearizable store.
+  redemptionStore: new InMemoryBoundRedemptionStore(),
+}, async ({ request, payment }) => ({
+  body: {
+    ok: true,
+    resource: request.params.id,
+    data: await loadResearchOnce(request.params.id),
+    settledTx: payment.txHash,
+  },
+}));
+
+app.get("/source/:id", paidResearch);
 app.listen(4021);
 ```
 
-`sourceAccount` is a funded Stellar `G...` address used only to simulate the
-read-only `get_mandate` call. The verifier never signs or submits a transaction.
+The fulfillment callback receives no Express `Response` and cannot stream. Its
+JSON result is bounded, hashed, and committed to the same redemption store
+before any bytes are written to the client.
 
-## What is verified
+## Bound-v2 authorization
 
-For each paid retry, the default verifier requires all of the following:
+Before fulfillment is claimed, the package requires:
 
-1. The configured RPC reports the exact configured network passphrase.
-2. The transaction hash is valid, successful, and inside the configured ledger
-   freshness window.
-3. Exactly one contract event is emitted by the configured MandateRegistry with
-   topics `payment` and the configured merchant, plus a 32-byte mandate id and
-   an amount meeting the request price.
-4. The event-derived mandate currently stored by the contract names the same
-   merchant and SEP-41 asset and supplies the user and agent identities.
-5. The same transaction contains exactly one matching transfer emitted by that
-   asset, from the mandate user to the merchant, for the exact event amount.
-6. A shared redemption store atomically consumes the network + registry +
-   transaction key before the protected handler runs.
+1. `REAPP-PAYMENT-CAPABILITIES: reapp-bound-v2`; older clients receive `426`
+   before payment.
+2. An HMAC-authenticated challenge binding the exact public origin, GET method,
+   path and query, network identity, registry, merchant, asset, amount, decimals,
+   random id, and first-redemption deadline.
+3. A canonical proof whose Stellar Ed25519 signature binds that challenge,
+   transaction hash, and mandate id to the chain-derived mandate agent.
+4. The configured RPC's exact network passphrase and a successful fresh
+   transaction.
+5. One unambiguous payment event from the configured MandateRegistry.
+6. Current mandate user, agent, merchant, and asset identities.
+7. One matching same-transaction SEP-41 transfer from user to merchant.
 
-Only the transaction hash crosses from the HTTP adapter into the verifier.
-Caller-supplied `amount` and `mandateId` fields remain wire-format hints; the
-verified values placed in `response.locals` come from Stellar and the contract.
+A copied public transaction hash cannot unlock data. Relaying a genuine quote
+through another origin fails before the client pays because the signed audience
+must equal the requested URL origin.
 
-## Production replay safety
+## Atomic fulfillment state
 
-`InMemoryRedemptionStore` is intentionally limited to one Node.js process. A
-production deployment must provide a durable `RedemptionStore` whose
-`consumeOnce` operation is linearizable across every worker and host:
+`BoundRedemptionStore` owns settlement binding and immutable response bytes in
+one linearizable state machine:
 
-```ts
-import type {
-  RedemptionRecord,
-  RedemptionStore,
-} from "@reapp-sdk/express-middleware";
-
-class SharedRedemptionStore implements RedemptionStore {
-  async consumeOnce(
-    record: Readonly<RedemptionRecord>,
-  ): Promise<"consumed" | "duplicate"> {
-    // Perform one atomic set-if-absent in your durable database.
-    // Never delete a consumed key merely because downstream delivery failed.
-    return atomicInsert(record.key, record) ? "consumed" : "duplicate";
-  }
-}
+```text
+missing -> executing -> completed(exact JSON bytes)
 ```
 
-Only the caller that receives `consumed` reaches the protected handler. A store
-error returns `503` and never serves the resource.
+- First valid proof: chain verification, atomic claim, one callback execution.
+- Same proof while executing: `503`; the callback is never started again.
+- Same proof after completion: exact stored bytes are replayed; no verifier or
+  callback runs.
+- Same transaction with another proof: `409`.
+- Store/RPC outage: `503`; no protected result is sent.
+- Callback exception: one sanitized terminal JSON result is stored and replayed.
+- Completion-store failure: no result bytes are sent and the claim remains
+  executing; recovery cannot re-run it automatically. After confirming the
+  execution owner is dead, trusted operator/outbox code calls
+  `resolveBoundReappInterruptedDelivery` to store one terminal result.
+
+The first-redemption deadline does not prevent later replay of an already
+completed exact result. That replay is delivery recovery, not fresh payment
+authorization.
+
+## Store deployment boundary
+
+`InMemoryBoundRedemptionStore` is only for one-process demos and tests.
+`FileBoundRedemptionStore` in the reference fulfillment app is restart-safe for
+one Node.js process; instances targeting the same normalized path share one
+in-process queue and use fsynced atomic replacement. It is not multi-process or
+multi-host storage.
+
+A production deployment must implement `BoundRedemptionStore.lookup`, `claim`,
+and `complete` in one shared durable linearizable database. Never add a lease
+that silently turns an executing claim back into runnable work. Side effects
+must be transactionally coordinated with the claim through a durable job/outbox.
 
 ## Response behavior
 
-| Condition | Status | Behavior |
-|---|---:|---|
-| No proof or malformed/invalid settlement | `402` | Returns a fresh payment requirement. |
-| Settlement already consumed | `409` | Does not invite a second payment. |
-| RPC, mandate lookup, or redemption store unavailable | `503` | Fails closed with `Retry-After`; retry the same proof. |
-| Verified and atomically consumed | next handler | Stores chain-derived evidence in `response.locals.reappPayment`. |
+| Condition | Status |
+|---|---:|
+| Missing/wrong bound-v2 capability | `426` before payment |
+| Method other than GET | `405` |
+| Missing, malformed, expired-first-use, mismatched, or unverified proof | `402` |
+| Same settlement with a different proof | `409` |
+| Existing execution or infrastructure/store outage | `503`, retry exact proof |
+| New completed fulfillment | stored 2xx JSON |
+| Exact completed recovery | byte-identical stored 2xx JSON |
 
-Challenges and successful responses receive `Cache-Control: private, no-store`
-and `Vary: X-PAYMENT` so a shared cache cannot bypass the payment boundary.
+All responses are private/no-store. Proof and stored result material are
+sensitive and must not be logged or exposed.
 
-## Request-specific prices
+## Primary API
 
-`amount` and `resource` may be resolver functions. The middleware snapshots the
-resolved requirement before any asynchronous verification:
+### `createBoundReappPaidJsonRoute(options, fulfill)`
 
-```ts
-const requirePayment = createReappPaymentMiddleware({
-  merchant: MERCHANT,
-  sourceAccount: READ_SOURCE,
-  amount: (request) => priceFor(request.params.id),
-  resource: (request) => `/source/${request.params.id}`,
-  redemptionStore,
-});
-```
+Required options:
 
-Amounts are decimal strings and are converted to integer stroops. Floating-point
-amounts, scientific notation, over-precision, zero, and values outside i128 fail
-closed.
-
-## API
-
-### `createReappPaymentMiddleware(options)`
-
-Creates an Express 4/5 `RequestHandler`.
-
-| Option | Type | Meaning |
-|---|---|---|
-| `merchant` | `string` | Required Stellar address that must receive the transfer. |
-| `amount` | `string \| (request) => string` | Required decimal price. |
-| `redemptionStore` | `RedemptionStore` | Required atomic consume-once store. |
-| `sourceAccount` | `string?` | Funded `G...` address for read-only simulations; required by the default verifier. |
-| `resource` | `string \| (request) => string` | Challenge resource id; defaults to `request.originalUrl`. |
-| `asset` | `string?` | Required SEP-41 emitter; defaults to the configured network's native SAC. |
-| `networkConfig` | `NetworkConfig?` | RPC, passphrase, registry, and native SAC; defaults to REAPP testnet. |
-| `scheme` | `string?` | Wire scheme; defaults to `reapp-soroban`. |
-| `network` | `string?` | Wire network label; defaults to `stellar-testnet`. |
-| `decimals` | `number?` | Asset decimals; defaults to `7`. |
-| `maxProofAgeLedgers` | `number?` | Settlement freshness window; defaults to `120`. |
-| `pollAttempts` | `number?` | `NOT_FOUND` retries; defaults to `15`. |
-| `pollIntervalMs` | `number?` | Retry delay; defaults to `1000`. |
-| `maxHeaderBytes` | `number?` | Strict `X-PAYMENT` size limit; defaults to `8192`. |
-| `allowHttpRpc` | `boolean?` | Development-only plaintext RPC escape hatch; defaults to `false`. |
-| `verifier` | `PaymentVerifier?` | Explicit trusted verifier injection for tests or alternate RPC infrastructure. |
-
-### Runtime exports
-
-| Export | Purpose |
+| Option | Meaning |
 |---|---|
-| `createReappPaymentMiddleware` | Build the payment boundary. |
-| `getVerifiedPayment(response)` | Read the chain-derived `VerifiedPayment` after the gate. |
-| `InMemoryRedemptionStore` | One-process development/test store. |
-| `createStellarPaymentVerifier` | Build the independent Stellar verifier. |
-| `buildChallenge` | Build the isolated x402-style response object. |
-| `createRedemptionKey` | Create the normalized cross-network replay key. |
-| `extractContractEvents`, `interpretEvents` | Strict V3/V4 Stellar event decoding helpers. |
-| `selectPayment`, `selectTransfer` | Pure fail-closed event selection helpers. |
-
-The package also exports TypeScript types for requirements, verified payments,
-verifiers, redemption records and stores, middleware options, and decoded event
-evidence.
+| `merchant` | Stellar address that must receive the verified transfer. |
+| `amount` | Decimal price or request-specific resolver. |
+| `audience` | Exact configured public HTTP(S) origin or safe resolver. |
+| `challengeSecret` | Stable private 32–4096 byte challenge key. |
+| `redemptionStore` | Atomic claim/result store shared by all serving workers. |
 
-## Wire-format isolation
+Optional controls include `resource`, `asset`, `networkConfig`, `network`,
+`decimals`, `sourceAccount`, verifier/polling/freshness/header limits,
+`challengeTtlSeconds`, development-only HTTP RPC, and `maxResponseBytes`.
+
+Runtime exports include `createBoundReappPaidJsonRoute`,
+`resolveBoundReappInterruptedDelivery`, `InMemoryBoundRedemptionStore`,
+`createStellarPaymentVerifier`, strict event
+selection helpers, and all TypeScript store/evidence/result types.
 
-x402 is evolving. REAPP keeps the HTTP challenge/proof shape in the isolated
-adapter inside `@reapp-sdk/core`; MandateRegistry does not depend on that shape.
-An x402 version change can replace the adapter while the same contract methods,
-storage, and verifier invariants remain intact.
+Legacy proof-v1 middleware remains available only through the legacy API. The
+low-level bound authorization middleware is intentionally not exported from the
+package root; public paid endpoints use the result-storing route wrapper.
 
-## Current protocol limits
+## Wire-format isolation
 
-- The settlement proof is bearer data. Atomic consumption prevents two
-  successful redemptions, but a copied proof can race the legitimate requester.
-- The challenge resource is not committed into the current contract event.
-  Exact requester/resource binding requires an authenticated nonce/signature or
-  a future contract/event commitment; this package does not claim that property.
-- `get_mandate` reads current contract state, not a historical state snapshot.
-  Same-transaction registry and token events prove settlement, while current
-  state binds the mandate identities and asset.
+x402 and AP2 evolve outside the MandateRegistry. HTTP/profile adapters may
+change without changing contract storage or weakening `execute_payment`.
 
 ## Current contract evidence
 
-The testnet default is the upgradeable simple MandateRegistry:
-
-- Contract: [`CC6JMPDHRPBR2HBLJKRCIKV54HXDV2RFXDKW6MALQKWM6JEAJQHICRWE`](https://stellar.expert/explorer/testnet/contract/CC6JMPDHRPBR2HBLJKRCIKV54HXDV2RFXDKW6MALQKWM6JEAJQHICRWE)
+- Testnet contract: [`CC6JMPDH…CRWE`](https://stellar.expert/explorer/testnet/contract/CC6JMPDHRPBR2HBLJKRCIKV54HXDV2RFXDKW6MALQKWM6JEAJQHICRWE)
 - WASM SHA-256: `13f7023d4a361b6e49d3d39f61f55c5eeece51a602013a3cddae420d2ce8552b`
-- Reproducible release: [`simple-v0.2.0`](https://github.com/reapp-protocol/reapp-protocol-contracts/releases/tag/simple-v0.2.0_contracts_simple_mandate_registry_mandate-registry_pkg0.2.0_cli25.1.0)
-
-The contract checks and consumes authorization inside `execute_payment` before
-the token transfer. Testnet operations include pause, authority rotation, and a
-24-hour timelocked same-address upgrade path.
+- Release: [`simple-v0.2.0`](https://github.com/reapp-protocol/reapp-protocol-contracts/releases/tag/simple-v0.2.0_contracts_simple_mandate_registry_mandate-registry_pkg0.2.0_cli25.1.0)
 
 Apache-2.0.

package/dist/bound-route.d.ts

@@ -0,0 +1,36 @@
+import type { Request, RequestHandler } from "express";
+import { type BoundReappPaymentMiddlewareOptions } from "./bound.js";
+import type { BoundDeliveryRecord, BoundRedemptionStore } from "./bound-store.js";
+import type { VerifiedPayment } from "./types.js";
+export interface BoundJsonResult {
+    /** Successful paid responses only. Defaults to 200. */
+    status?: number;
+    body: unknown;
+}
+export interface BoundJsonFulfillmentContext {
+    request: Request;
+    payment: Readonly<VerifiedPayment>;
+}
+export type BoundJsonFulfillment = (context: BoundJsonFulfillmentContext) => BoundJsonResult | Promise<BoundJsonResult>;
+export interface BoundReappPaidJsonRouteOptions extends BoundReappPaymentMiddlewareOptions {
+    /** Maximum stored UTF-8 JSON response size. Defaults to 1 MiB. */
+    maxResponseBytes?: number;
+}
+/**
+ * Resolve an orphaned at-most-once execution without invoking fulfillment
+ * again. Call this only from trusted operator/outbox code after confirming the
+ * original execution owner is dead. The exact terminal bytes become immutable
+ * and subsequent receipt recovery replays them.
+ */
+export declare function resolveBoundReappInterruptedDelivery(options: {
+    redemptionStore: BoundRedemptionStore;
+    record: Readonly<BoundDeliveryRecord>;
+    maxResponseBytes?: number;
+}): Promise<Readonly<BoundDeliveryRecord>>;
+/**
+ * Safe paid JSON route. Fulfillment executes once after an atomic claim; its
+ * exact bytes are stored before they are sent. Recovery replays those bytes and
+ * never invokes the fulfillment callback again.
+ */
+export declare function createBoundReappPaidJsonRoute(options: BoundReappPaidJsonRouteOptions, fulfill: BoundJsonFulfillment): RequestHandler;
+//# sourceMappingURL=bound-route.d.ts.map

package/dist/bound-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bound-route.d.ts","sourceRoot":"","sources":["../src/bound-route.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAgB,OAAO,EAAE,cAAc,EAAY,MAAM,SAAS,CAAC;AAC/E,OAAO,EAGL,KAAK,kCAAkC,EACxC,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EAErB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;CACpC;AAED,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,EAAE,2BAA2B,KACjC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;AAEhD,MAAM,WAAW,8BAA+B,SAAQ,kCAAkC;IACxF,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AA6BD;;;;;GAKG;AACH,wBAAsB,oCAAoC,CAAC,OAAO,EAAE;IAClE,eAAe,EAAE,oBAAoB,CAAC;IACtC,MAAM,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IACtC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC,CAkBzC;AAgDD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,8BAA8B,EACvC,OAAO,EAAE,oBAAoB,GAC5B,cAAc,CAuDhB"}

package/dist/bound-route.js

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+import { Buffer } from "buffer";
+import { createBoundReappPaymentMiddleware, getBoundDeliveryContext, } from "./bound.js";
+const CONTENT_TYPE = "application/json; charset=utf-8";
+const DEFAULT_MAX_RESPONSE_BYTES = 1_048_576;
+function storedResponse(status, body, maxBytes) {
+    if (!Number.isInteger(status) || status < 200 || status > 299) {
+        throw new Error("paid JSON fulfillment status must be an integer from 200 through 299");
+    }
+    const json = JSON.stringify(body);
+    if (json === undefined)
+        throw new Error("paid JSON fulfillment body must be JSON-serializable");
+    const bytes = Buffer.from(json, "utf8");
+    if (bytes.length > maxBytes)
+        throw new Error("paid JSON fulfillment body exceeds maxResponseBytes");
+    return Object.freeze({
+        status,
+        contentType: CONTENT_TYPE,
+        bodyBase64: bytes.toString("base64"),
+        bodySha256: createHash("sha256").update(bytes).digest("hex"),
+    });
+}
+function terminalFailure(maxBytes) {
+    return storedResponse(200, {
+        ok: false,
+        error: "paid fulfillment failed after settlement",
+        deliveryState: "terminal",
+    }, maxBytes);
+}
+/**
+ * Resolve an orphaned at-most-once execution without invoking fulfillment
+ * again. Call this only from trusted operator/outbox code after confirming the
+ * original execution owner is dead. The exact terminal bytes become immutable
+ * and subsequent receipt recovery replays them.
+ */
+export async function resolveBoundReappInterruptedDelivery(options) {
+    if (options.record.state !== "executing") {
+        throw new Error("only an executing paid delivery can be resolved as interrupted");
+    }
+    const maxBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > 16_777_216) {
+        throw new Error("maxResponseBytes must be an integer from 1 through 16777216");
+    }
+    const completed = await options.redemptionStore.complete({
+        key: options.record.key,
+        proofDigest: options.record.proofDigest,
+        executionId: options.record.executionId,
+        response: terminalFailure(maxBytes),
+    });
+    if (completed.kind !== "completed" || completed.record.state !== "completed") {
+        throw new Error("interrupted paid delivery could not be resolved atomically");
+    }
+    return completed.record;
+}
+function decodeStoredResponse(stored, maxBytes) {
+    if (!Number.isInteger(stored.status)
+        || stored.status < 200
+        || stored.status > 299
+        || stored.contentType !== CONTENT_TYPE
+        || !/^[0-9a-f]{64}$/.test(stored.bodySha256)
+        || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(stored.bodyBase64)) {
+        throw new Error("stored paid response schema is invalid");
+    }
+    const bytes = Buffer.from(stored.bodyBase64, "base64");
+    if (bytes.length > maxBytes
+        || bytes.toString("base64") !== stored.bodyBase64
+        || createHash("sha256").update(bytes).digest("hex") !== stored.bodySha256) {
+        throw new Error("stored paid response integrity check failed");
+    }
+    return bytes;
+}
+function sendStored(response, stored, maxBytes) {
+    const bytes = decodeStoredResponse(stored, maxBytes);
+    response.status(stored.status);
+    response.set("content-type", stored.contentType);
+    response.set("content-length", String(bytes.length));
+    response.set("cache-control", "private, no-store");
+    response.set("x-content-type-options", "nosniff");
+    response.end(bytes);
+}
+function unavailable(response, message) {
+    response.status(503);
+    response.set("retry-after", "1");
+    response.set("cache-control", "private, no-store");
+    response.json({ error: message, retryable: true });
+}
+/**
+ * Safe paid JSON route. Fulfillment executes once after an atomic claim; its
+ * exact bytes are stored before they are sent. Recovery replays those bytes and
+ * never invokes the fulfillment callback again.
+ */
+export function createBoundReappPaidJsonRoute(options, fulfill) {
+    if (typeof fulfill !== "function")
+        throw new Error("paid JSON fulfillment callback is required");
+    const maxBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > 16_777_216) {
+        throw new Error("maxResponseBytes must be an integer from 1 through 16777216");
+    }
+    const authorize = createBoundReappPaymentMiddleware(options);
+    return (request, response, next) => {
+        authorize(request, response, (authorizationError) => {
+            if (authorizationError) {
+                next(authorizationError);
+                return;
+            }
+            void (async () => {
+                const context = getBoundDeliveryContext(response);
+                if (!context)
+                    throw new Error("bound delivery context was unavailable");
+                if (context.kind === "completed") {
+                    if (context.record.state !== "completed")
+                        throw new Error("completed delivery record is inconsistent");
+                    sendStored(response, context.record.response, maxBytes);
+                    return;
+                }
+                if (context.record.state !== "executing") {
+                    throw new Error("claimed delivery record is inconsistent");
+                }
+                let result;
+                try {
+                    const provided = await fulfill({ request, payment: context.record.payment });
+                    result = storedResponse(provided.status ?? 200, provided.body, maxBytes);
+                }
+                catch {
+                    // Store one immutable terminal result. Never re-run arbitrary paid work.
+                    result = terminalFailure(maxBytes);
+                }
+                let completed;
+                try {
+                    completed = await options.redemptionStore.complete({
+                        key: context.record.key,
+                        proofDigest: context.record.proofDigest,
+                        executionId: context.record.executionId,
+                        response: result,
+                    });
+                }
+                catch {
+                    unavailable(response, "paid fulfillment result store is unavailable; retry the same proof");
+                    return;
+                }
+                if (completed.kind !== "completed" || completed.record.state !== "completed") {
+                    unavailable(response, "paid fulfillment result could not be committed");
+                    return;
+                }
+                sendStored(response, completed.record.response, maxBytes);
+            })().catch(next);
+        });
+    };
+}
+//# sourceMappingURL=bound-route.js.map

package/dist/bound-route.js.map

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

package/dist/bound-store.d.ts

@@ -0,0 +1,79 @@
+import type { VerifiedPayment } from "./types.js";
+export interface BoundRedemptionRecord {
+    /** Network-passphrase hash, registry id, and normalized transaction hash. */
+    key: string;
+    /** SHA-256 of the strict decoded bound proof. */
+    proofDigest: string;
+    /** Chain-derived evidence captured when this exact proof was first accepted. */
+    payment: Readonly<VerifiedPayment>;
+}
+export interface StoredBoundJsonResponse {
+    status: number;
+    contentType: "application/json; charset=utf-8";
+    bodyBase64: string;
+    bodySha256: string;
+}
+export type BoundDeliveryRecord = Readonly<BoundRedemptionRecord> & Readonly<{
+    executionId: string;
+    startedAt: number;
+}> & ({
+    state: "executing";
+    response?: never;
+} | {
+    state: "completed";
+    response: Readonly<StoredBoundJsonResponse>;
+});
+export type BoundRedemptionLookup = {
+    kind: "missing";
+} | {
+    kind: "executing";
+    record: Readonly<BoundDeliveryRecord>;
+} | {
+    kind: "completed";
+    record: Readonly<BoundDeliveryRecord>;
+} | {
+    kind: "conflict";
+};
+export type BoundRedemptionClaim = {
+    kind: "claimed";
+    record: Readonly<BoundDeliveryRecord>;
+} | {
+    kind: "executing";
+    record: Readonly<BoundDeliveryRecord>;
+} | {
+    kind: "completed";
+    record: Readonly<BoundDeliveryRecord>;
+} | {
+    kind: "conflict";
+};
+export interface BoundRedemptionCompletion {
+    key: string;
+    proofDigest: string;
+    executionId: string;
+    response: Readonly<StoredBoundJsonResponse>;
+}
+export type BoundRedemptionComplete = {
+    kind: "completed";
+    record: Readonly<BoundDeliveryRecord>;
+} | {
+    kind: "conflict";
+};
+/**
+ * One linearizable store owns both settlement binding and immutable delivery
+ * bytes. A proof is claimed at most once; recovery either waits for that claim
+ * or replays its completed result without re-running fulfillment.
+ */
+export interface BoundRedemptionStore {
+    lookup(key: string, proofDigest: string): BoundRedemptionLookup | Promise<BoundRedemptionLookup>;
+    claim(record: Readonly<BoundRedemptionRecord>, executionId: string, startedAt: number): BoundRedemptionClaim | Promise<BoundRedemptionClaim>;
+    complete(completion: Readonly<BoundRedemptionCompletion>): BoundRedemptionComplete | Promise<BoundRedemptionComplete>;
+}
+/** Process-local reference store. Production and restart drills need a durable shared store. */
+export declare class InMemoryBoundRedemptionStore implements BoundRedemptionStore {
+    private readonly records;
+    lookup(key: string, proofDigest: string): BoundRedemptionLookup;
+    claim(record: Readonly<BoundRedemptionRecord>, executionId: string, startedAt: number): BoundRedemptionClaim;
+    complete(completion: Readonly<BoundRedemptionCompletion>): BoundRedemptionComplete;
+    get(key: string): Readonly<BoundDeliveryRecord> | undefined;
+}
+//# sourceMappingURL=bound-store.d.ts.map

package/dist/bound-store.d.ts.map

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