mtok-bridge 0.3.3 → 0.3.5

package/README.md

@@ -41,10 +41,18 @@ tool, one layer on top.
 (and the workers-ai house seller) run: validate request => verify the on-chain DrawPaid
 (request-hash bound) => bound both legs against the payment => claim => upstream => complete,
 fail-closed. The redemption store is a pluggable interface (`{ state, get, claim, complete,
-retentionMs }`, each method sync or async: the core awaits every call), so a filesystem store and a Workers KV store drive the same code path. If you
+retentionMs }`, each method sync or async: the core awaits every call). The store must make
+claims atomic across every host serving that offer. Independent local files and eventually
+consistent KV read/write pairs do not provide that guarantee. If you
 are just serving a model for a key, you never need it; it is here so every mtok seller host
 shares one money path.
 
+`state(key, { claimKey })` and `get(key, { claimKey })` receive the canonical commitment
+identity even when `key` names a legacy record. `claim(key, markerKey, { paidAtMs })` receives
+the verifier's payment timestamp, so a store migrating old claims can refuse ambiguous
+pre-cutover payments. Existing stores may ignore these additional arguments. The core still
+verifies the payment before reading a completion, and known claims never run upstream again.
+
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtok-bridge",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Serve any model as an OpenAI-compatible API with a key. No payment, no market, runs anywhere node runs. The transport core behind mtok.market's seller relay.",
   "type": "module",
   "bin": {

package/src/serve-core.mjs

@@ -8,7 +8,7 @@
 // payer-screen POLICY stay in the host.
 //
 // The redemption dependency is an INTERFACE the caller passes:
-//   { state(key), get(key), claim(key, markerKey), complete(key, payload), retentionMs }
+//   { state(key, { claimKey }), get(key, { claimKey }), claim(key, markerKey, { paidAtMs }), complete(key, payload), retentionMs }
 // state(key) returns 'pending' | 'complete' | null. claim(key, markerKey) returns false when the
 // draw is already claimed and THROWS when it cannot claim durably (the core then refuses before
 // upstream spend). complete(key, payload) throws when the payload cannot be persisted; the claim
@@ -243,11 +243,6 @@ export function createServeCore({
   maxOutputTokens,
 }) {
   const serve = async (body) => {
-    // #651: feeBps/feeRecipient may be getters so a long-running relay tracks a
-    // platform fee change instead of pinning the boot rate (a fee DECREASE with a
-    // stale higher rate would refuse an already-paid draw as fee_amount_too_low).
-    // Resolve once per serve and use the resolved values everywhere below.
-    const currentFeeBps = typeof feeBps === 'function' ? feeBps() : feeBps;
     const currentFeeRecipient = typeof feeRecipient === 'function' ? feeRecipient() : feeRecipient;
     const { bookingId, n, buyerId, request, requestNonce, drawPaidTxHash } = body;
     const hasRequestNonce = Object.hasOwn(body, 'requestNonce');
@@ -273,6 +268,7 @@ export function createServeCore({
     // Legacy redemption remains only to honor draws already paid by old SDKs.
     const cacheKey = `${requestHashScheme}:${bookingId}:${n}:${requestHash}`;
     const oldLegacyKey = hasRequestNonce ? null : `${bookingId}:${n}:${requestHash}`;
+    const redemptionContext = { claimKey: cacheKey };
 
     // Contract mode is the ONLY mode (#487): the legacy direct-transfer FUND
     // lane and its /api/bookings/:id balance read are gone. If the platform is
@@ -286,18 +282,18 @@ export function createServeCore({
     // The redemption interface may be sync (fs store) or async (a Workers KV
     // store): await normalizes both, and identity-awaits cost nothing under the
     // host's per-booking lock.
-    let redemptionState = await redemption.state(storedKey);
+    let redemptionState = await redemption.state(storedKey, redemptionContext);
     // Preserve an upgrade's pre-scheme redemption log; missing this alias
     // would let a legacy paid draw run upstream again after relay upgrade.
     if (!redemptionState && oldLegacyKey) {
-      const oldLegacyState = await redemption.state(oldLegacyKey);
+      const oldLegacyState = await redemption.state(oldLegacyKey, redemptionContext);
       if (oldLegacyState) {
         storedKey = oldLegacyKey;
         redemptionState = oldLegacyState;
       } else {
         // Checking the legacy marker may have refreshed a prefixed record
         // appended by another upgraded process.
-        redemptionState = await redemption.state(cacheKey);
+        redemptionState = await redemption.state(cacheKey, redemptionContext);
       }
     }
     let paid;
@@ -313,9 +309,9 @@ export function createServeCore({
         requestHash,
         sellerWallet,
         feeRecipient: currentFeeRecipient,
-        // A known completion spends no new inference. New claims need a verified
+        // A known claim spends no new inference. New claims need a verified
         // age because both payload and claim markers expire after retention.
-        maxPaidAgeMs: redemptionState === 'complete' ? undefined : redemption.retentionMs,
+        maxPaidAgeMs: redemptionState === 'complete' || redemptionState === 'pending' ? undefined : redemption.retentionMs,
       });
     } catch (e) {
       if (e.name === 'TimeoutError') return { status: 503, body: { error: 'relay_timeout', _bookingId: bookingId } };
@@ -323,14 +319,6 @@ export function createServeCore({
     }
     if (paid?.reason === 'payment_age_unavailable') return { status: 503, body: { error: 'payment_age_unavailable', detail: 'payment age could not be verified; retry this same paid draw', _bookingId: bookingId } };
     if (!paid?.ok) return { status: 402, body: { error: 'payment_unverified', detail: paid?.reason || 'unknown' } };
-    const expectedFee = configuredFeeAtomic({
-      sellerUsdAtomic: paid.event.sellerUsdAtomic,
-      feeAddress: currentFeeRecipient,
-      feeBps: currentFeeBps,
-    });
-    if (BigInt(paid.event.feeUsdAtomic || 0) < expectedFee) {
-      return { status: 402, body: { error: 'payment_unverified', detail: 'fee_amount_too_low' } };
-    }
     // Screen the verified payer before spending upstream capacity. The
     // payment already settled on-chain (that money is the buyer's loss);
     // this refuses the SERVICE, which is the only refusal an edge can
@@ -345,10 +333,27 @@ export function createServeCore({
         return { status: 403, body: { error: 'payer_denied', detail: 'payer screening failed: ' + e.message } };
       }
     }
-    if (redemptionState === 'complete') return { status: 200, body: await redemption.get(storedKey) };
+    if (redemptionState === 'complete') {
+      const payload = await redemption.get(storedKey, redemptionContext);
+      if (payload == null) return { status: 503, body: { error: 'redemption_unavailable', detail: 'saved completion is no longer readable; retry this same paid draw', _bookingId: bookingId } };
+      return { status: 200, body: payload };
+    }
     if (redemptionState === 'pending') {
       return { status: 409, body: { error: 'draw_pending', detail: 'this paid draw was already claimed; refusing to run upstream again', _bookingId: bookingId } };
     }
+    // Completed/pending claims already crossed the fee gate and cannot spend
+    // again. New claims use the policy at the verified payment time.
+    let currentFeeBps;
+    try {
+      currentFeeBps = typeof feeBps === 'function' ? await feeBps(paid) : feeBps ?? 0;
+      if (!Number.isSafeInteger(currentFeeBps) || currentFeeBps < 0 || currentFeeBps > 10_000) throw new TypeError('invalid fee rate');
+    } catch {
+      return { status: 503, body: { error: 'fee_policy_unavailable', detail: 'fee policy could not be verified; retry this same paid draw', _bookingId: bookingId } };
+    }
+    const expectedFee = configuredFeeAtomic({ sellerUsdAtomic: paid.event.sellerUsdAtomic, feeAddress: currentFeeRecipient, feeBps: currentFeeBps });
+    if (BigInt(paid.event.feeUsdAtomic || 0) < expectedFee) {
+      return { status: 402, body: { error: 'payment_unverified', detail: 'fee_amount_too_low' } };
+    }
     const paidEvent = paid.event;
     const remainingUsd = Number(paid.event.sellerUsdAtomic || 0) / 1e6;
     if (remainingUsd < BALANCE_EPSILON) {
@@ -376,7 +381,7 @@ export function createServeCore({
     try {
       // Legacy uses its old unprefixed identity only for the atomic marker so
       // parallel upgraded stores and an existing log converge on one claim.
-      if (!(await redemption.claim(cacheKey, oldLegacyKey ?? cacheKey))) {
+      if (!(await redemption.claim(cacheKey, oldLegacyKey ?? cacheKey, { paidAtMs: paid.paidAtMs }))) {
         return { status: 409, body: { error: 'draw_pending', detail: 'this paid draw was already claimed; refusing to run upstream again', _bookingId: bookingId } };
       }
     } catch (e) {