@homie-rocks/studio 0.37.1 → 0.37.2

package/worker/purchase-core.mjs

@@ -0,0 +1,140 @@
+/** Provider facts drive orders. Offers and entitlements are immutable purchase inputs. */
+import { canonicalJson } from "./referrals.mjs";
+import { digest } from "./purchase-crypto.mjs";
+
+
+export const states = Object.freeze(['started','paid','fulfilled','refunded','disputed','lapsed','expired','failed','lost']);
+export const transitions = Object.freeze({
+ started: ['paid','refunded','expired','failed','lapsed'],
+ paid: ['fulfilled','refunded','disputed','lapsed','lost'],
+ fulfilled: ['refunded','disputed','lapsed','lost'],
+ refunded: [],
+ disputed: ['paid','fulfilled','refunded','lapsed','lost'],
+ lapsed: ['paid','refunded','disputed'],
+ expired: ['paid','refunded'], failed: ['paid','refunded'], lost: ['paid','refunded'],
+});
+export function transition(from, to, { renewal = false, refundReversal = false } = {}) {
+  if ((renewal || refundReversal) && from === "refunded" && to === "paid") return to;
+  if (
+    !states.includes(from) ||
+    !states.includes(to) ||
+    (from !== to && !transitions[from].includes(to))
+  )
+    throw new Error(`Illegal purchase transition: ${from} -> ${to}`);
+  return to;
+}
+export async function offerVersion(resource, terms) {
+  const offer = { resource, terms };
+  return { ...offer, version: await digest(canonicalJson(offer)) };
+}
+export function entitlement(order, offer) {
+  if (order.offerVersion !== offer.version)
+    throw new Error("Order and offer version differ");
+  return {
+    order: order.id,
+    buyer: order.buyer,
+    resource: offer.resource,
+    terms: structuredClone(offer.terms),
+    active: ["paid", "fulfilled", "disputed"].includes(order.state),
+  };
+}
+
+/** D1 compare-and-swap gives mppx its required shared atomic replay store. */
+export function paymentStore(db, mode) {
+  const keyOf = (key) => `payment:${mode}:${key}`;
+  return {
+    async get(key) {
+      const row = await db
+        .prepare("SELECT value FROM meta WHERE key = ?1")
+        .bind(keyOf(key))
+        .first();
+      return row ? JSON.parse(row.value).value : null;
+    },
+    async put(key, value) {
+      await this.update(key, () => ({ op: "set", value, result: undefined }));
+    },
+    async delete(key) {
+      await this.update(key, () => ({ op: "delete", result: undefined }));
+    },
+    async update(key, fn) {
+      const k = keyOf(key);
+      for (let attempt = 0; attempt < 32; attempt++) {
+        const row = await db
+          .prepare("SELECT value FROM meta WHERE key = ?1")
+          .bind(k)
+          .first();
+        const change = fn(row ? JSON.parse(row.value).value : null);
+        if (change.op === "noop") return change.result;
+        // Tombstones retain a unique revision, avoiding an ABA race on deletion.
+        const value = JSON.stringify({
+          revision: crypto.randomUUID(),
+          value: change.op === "delete" ? null : change.value,
+        });
+        const result = row
+          ? await db
+              .prepare(
+                "UPDATE meta SET value = ?2 WHERE key = ?1 AND value = ?3",
+              )
+              .bind(k, value, row.value)
+              .run()
+          : await db
+              .prepare("INSERT OR IGNORE INTO meta (key,value) VALUES (?1,?2)")
+              .bind(k, value)
+              .run();
+        if (result.meta.changes === 1) return change.result;
+      }
+      throw new Error("Payment state busy; retry the same request");
+    },
+  };
+}
+
+/** The purchase table is the sole lifecycle record. Provider facts use this writer only. */
+export async function orderState(env, id) {
+  const order = await env.DB.prepare("SELECT * FROM purchase_orders WHERE id = ?1").bind(id).first();
+  return order && {...order, offerVersion:order.offer_version, state:order.status};
+}
+const mutable = new Set(['customer','subscription','paid_until','quantity','session','checkout_url','claim_hash','buyer','payment','tax','total','paid_at','refunded_at','refund','dispute','fulfilled_at','note']);
+export function orderFact(env, id, fact, fields = {}, { renewal = false, refundReversal = false } = {}) {
+  const target = fact === 'payment' ? 'paid' : fact;
+  if (fact !== 'details' && !states.includes(target)) throw new Error(`Unknown purchase fact: ${fact}`);
+  const allowed = fact === 'details' ? [] : states.filter((from) => {
+    try { transition(from,target,{renewal,refundReversal}); return true; } catch { return false; }
+  });
+  // Expiry/failure cannot revoke money already accepted. Re-reading the same
+  // payment preserves delivery and disputes; only reconciliation resolves them.
+  const sources = factSources(fact, allowed);
+  const status = fact === 'details' ? 'status' : `CASE ${target === 'paid' ? "WHEN status = 'fulfilled' THEN status " : ''}${target === 'fulfilled' ? "WHEN status = 'disputed' THEN status " : ''}WHEN status IN (${sources.map((v)=>`'${v}'`).join(',')}) THEN '${target}' ELSE status END`;
+  const values = [id, Date.now()];
+  const sets = [`status = ${status}`, 'updated_at = ?2'];
+  if (target === 'paid' && fields.paid_at === undefined) fields = {...fields,paid_at:Date.now()};
+  if (target === 'fulfilled') fields = {...fields,fulfilled_at:Date.now()};
+  if (target === 'refunded' && fields.refunded_at === undefined) fields = {...fields,refunded_at:Date.now()};
+  for (const [key,value] of Object.entries(fields)) {
+    if (!mutable.has(key)) throw new Error(`Immutable purchase field: ${key}`);
+    values.push(value ?? null);
+    const parameter = `?${values.length}`;
+    sets.push(`${key} = ${['paid_at','fulfilled_at'].includes(key) || key === 'payment' && !renewal ? `COALESCE(${key},${parameter})` : parameter}`);
+  }
+  return env.DB.prepare(`UPDATE purchase_orders SET ${sets.join(', ')} WHERE id = ?1`).bind(...values);
+}
+export async function recordOrderState(env, order, fact, fields, options) {
+  await orderFact(env,order.id,fact,fields,options).run();
+  const current = await orderState(env,order.id);
+  return current && { ...current, factResult: { fact, applied: fact === 'details' || current.status === (fact === 'payment' ? 'paid' : fact), state: current.status } };
+}
+
+export function factSources(fact, allowed) {
+  return fact === 'payment' ? ['started','expired','failed'] : ['expired','failed'].includes(fact) ? ['started'] : allowed;
+}
+export function factState(from, fact, options = {}) {
+  if (fact === 'details') return from;
+  const target = fact === 'payment' ? 'paid' : fact;
+  const allowed = states.filter((state) => { try { transition(state, target, options); return true; } catch { return false; } });
+  if (target === 'paid' && from === 'fulfilled' || target === 'fulfilled' && from === 'disputed') return from;
+  return factSources(fact, allowed).includes(from) ? target : from;
+}
+
+export const releaseClaim = (env, id) => env.DB.prepare("UPDATE purchase_orders SET claim_hash = ?2 WHERE id = ?1 AND payment IS NULL AND paid_at IS NULL").bind(id, `released:${id}`);
+
+/** Atomically reserve the first hosted session before processing its payment. */
+export const bindHostedSession = (env,id,session) => env.DB.prepare('UPDATE purchase_orders SET session = ?2 WHERE id = ?1 AND (session IS NULL OR session = ?2)').bind(id,session).run();

package/worker/purchase-crypto.mjs

@@ -0,0 +1,17 @@
+import { canonicalJson } from "./referrals.mjs";
+export const GRANT_TYPE = 'homie-purchase-grant+jwt';
+export const PROOF_TYPE = 'homie-purchase-proof+jwt';
+export const PROOF_AUDIENCE = 'homie-purchase-evidence';
+export const GRANT_AUDIENCE = 'homie-purchases';
+export const digest = async (value) => [...new Uint8Array(await crypto.subtle.digest('SHA-256', typeof value === 'string' ? new TextEncoder().encode(value) : value))].map((b) => b.toString(16).padStart(2, '0')).join('');
+export const manifestHash = (resource) => digest(canonicalJson(resource));
+export async function signGrant(key, claims, proof = false) {
+  const { calculateJwkThumbprint, SignJWT } = await import('jose');
+  return new SignJWT(claims).setProtectedHeader({ alg: 'Ed25519', typ: proof ? PROOF_TYPE : GRANT_TYPE, kid: await calculateJwkThumbprint(key.publicJwk) }).sign(key.privateKey);
+}
+export async function verifyGrant(token, jwk, { issuer, subject, resource, kind, version, proof = false, audience = proof ? PROOF_AUDIENCE : GRANT_AUDIENCE } = {}) {
+  const { calculateJwkThumbprint, importJWK, jwtVerify } = await import('jose');
+  const { payload, protectedHeader } = await jwtVerify(token, await importJWK(jwk, 'Ed25519'), { algorithms: ['Ed25519'], typ: proof ? PROOF_TYPE : GRANT_TYPE, issuer, audience, ...(subject ? { subject } : {}), requiredClaims: ['iss', 'aud', 'sub', 'iat', 'jti', 'resource', 'kind', 'version', ...(proof && audience !== PROOF_AUDIENCE ? [] : ['manifest']), 'mode', ...(proof ? [] : ['exp'])] });
+  if (protectedHeader.kid !== await calculateJwkThumbprint(jwk) || (resource && payload.resource !== resource) || (kind && payload.kind !== kind) || (version && payload.version !== version)) throw new Error('The purchase proof is for another key or release');
+  return payload;
+}

package/worker/purchase-delivery.mjs

@@ -0,0 +1,108 @@
+/** Studio licences use the shop's Stripe, order book, webhook and refund office. */
+import {
+  orderState,
+  recordOrderState,
+  entitlement,
+} from "./purchase-core.mjs";
+
+import { signingKey, publicKeys } from "./purchase-keys.mjs";
+
+import { GRANT_AUDIENCE, PROOF_AUDIENCE, manifestHash, signGrant, verifyGrant } from "./purchase-crypto.mjs";
+import { resourceKind } from "./resource-kinds.mjs";
+
+import {
+  json,
+  fail,
+  byId,
+  bearer,
+  purchasedResource,
+  active,
+  privateRelease,
+  coveredPurchase,
+  deliveryAllowed,
+  resourceAvailable,
+} from "./purchase-store.mjs";
+export async function grantPurchase(env, origin, o, b = {}) {
+  const bought = purchasedResource(o);
+  const version = b.version ?? bought.version;
+  const p =
+    version === bought.version
+      ? JSON.parse(o.manifest)
+      : await privateRelease(env, o.resource_kind, bought.id, version);
+  if (!p)
+    return fail(503, "Release temporarily unavailable; retry this purchase");
+  if (!(await coveredPurchase(env, origin, o, p)))
+    return fail(
+      403,
+      "This version needs a new licence and a fresh price approval",
+    );
+  if (!(await resourceAvailable(env, o.resource_kind, p)))
+    return fail(503, o.payment ? 'Paid file bytes are temporarily unavailable. The seller must restore storage. Do not pay again.' : 'Your chain payment settled but Stripe has not recorded it. Files are temporarily unavailable. Contact the seller for restoration or a manual refund to your original payer address. Do not pay again.');
+  if (!active(o)) return fail(402, `Purchase is ${o.status}; delivery is unavailable`);
+  await env.DB.prepare(
+    "INSERT OR IGNORE INTO purchase_grants (order_id,version,manifest_hash) VALUES (?1,?2,?3)",
+  )
+    .bind(o.id, p.version, await manifestHash(p))
+    .run();
+  const coreOrder = await recordOrderState(env, o, "fulfilled");
+  const offerRow =
+    coreOrder.offerVersion &&
+    (await env.DB.prepare("SELECT value FROM purchase_offers WHERE version = ?1")
+      .bind(coreOrder.offerVersion)
+      .first());
+  const rights = offerRow
+    ? entitlement(coreOrder, JSON.parse(offerRow.value))
+    : null;
+  if (!rights || !rights.active)
+    return fail(402, `Purchase is ${coreOrder.state}; delivery is unavailable`);
+  const key = await signingKey(env);
+  const now = Math.floor(Date.now() / 1000);
+  const claims = {
+    iss: origin,
+    aud: GRANT_AUDIENCE,
+    sub: o.buyer,
+    studio: o.buyer_label,
+    offer: o.offer ? JSON.parse(o.offer) : bought.sale,
+    jti: o.id,
+    iat: now,
+    claimVersion: o.claim_hash,
+    resource: p.id,
+    kind: o.resource_kind,
+    version: p.version,
+    manifest: await manifestHash(p),
+    terms: resourceKind(o.resource_kind).terms(bought),
+    quantity: o.quantity,
+    game: o.game,
+    mode: o.mode,
+    paidUntil: o.paid_until,
+    billing: bought.sale.billing,
+    onRefund: bought.sale.onRefund,
+    onExpiry: bought.sale.onExpiry,
+  };
+  return json({
+    ok: true,
+    entitlement: rights,
+    token: await signGrant(key, { ...claims, exp: now + 300 }),
+    proof: await signGrant(key, { ...claims, aud: PROOF_AUDIENCE }, true),
+    hubProof:
+      b.audience && /^https:\/\/[^/]+$/.test(b.audience)
+        ? await signGrant(
+            key,
+            {
+              iss: claims.iss,
+              aud: b.audience,
+              sub: claims.sub,
+              jti: claims.jti,
+              iat: claims.iat,
+              resource: claims.resource,
+              kind: claims.kind,
+              version: claims.version,
+              mode: claims.mode,
+            },
+            true,
+          )
+        : undefined,
+    manifest: p,
+    paidUntil: o.paid_until,
+  });
+}

package/worker/purchase-discovery.mjs

@@ -0,0 +1,26 @@
+import { machineCapabilities } from './payment-capabilities.mjs';
+import { listOffers } from './resource-kinds.mjs';
+export async function purchaseDiscovery(env, origin, catalogue = {}) {
+  const { generateProxy } = await import('mppx/discovery');
+  const capabilities = await machineCapabilities(env);
+  const routes = [];
+  for (const resource of await listOffers(env,origin)) {
+    const offer = resource.offer;
+    const eligible = (catalogue.shop?.purchasesTill ?? catalogue.shop?.till) !== 'stripe-managed' && offer.amount > 0 && offer.billing === 'one-time' && offer.currency === 'usd' && !offer.automaticTax && offer.taxBehavior !== 'exclusive';
+    const offers = eligible ? Object.entries(capabilities.machine).filter(([, enabled]) => enabled).map(([method]) => ({ method: method === 'card' ? 'stripe' : method === 'base' ? 'evm' : method, intent: 'charge', amount: String(method === 'card' ? offer.amount : offer.amount * 10000), currency: 'usd' })) : [];
+    routes.push({ method: 'POST', path: `/api/purchases/resource/${resource.kind}/${resource.id}/${resource.version}`, summary: `Buy ${resource.name} ${resource.version}. Challenges expire after five minutes. A new purchase requires a fresh private claim.`, payment: offers.length ? { offers } : null,
+      requestBody: { required: true, content: { 'application/json': { schema: {
+        type: 'object', required: ['kind','resource','version','buyer','claim','offerVersion'],
+        properties: {
+          kind: {type:'string',const:resource.kind}, resource: {type:'string',const:resource.id}, version: {type:'string',const:resource.version},
+          buyer:{type:'string',pattern:'^[a-f0-9]{64}$',description:'Private random buyer identifier (32 bytes, hex).'},
+          claim:{type:'string',pattern:'^[a-f0-9]{64}$',description:'Private random secret for this purchase (32 bytes, hex). Keep it for retries and downloads.'},
+          offerVersion:{type:'string',const:resource.offerVersion},quantity:{type:'integer',minimum:1,default:1},game:{type:'string',description:'Game identifier required for a game-scoped offer.'},
+        },
+      } } } },
+    });
+  }
+  const doc=generateProxy({info:{title:'Studio purchases',version:'1'},routes});doc.servers=[{url:origin}];
+  doc.paths['/api/purchases/intent'] = { post: { summary: 'Create a hosted Checkout fallback; open the returned seller URL to accept terms and complete Turnstile.', requestBody: { required: true, content: { 'application/json': { schema: { type: 'object', required: ['kind','resource','version','buyer','claimHash','offerVersion'], properties: { kind: {type:'string'}, resource: {type:'string'}, version: {type:'string'}, buyer: {type:'string',pattern:'^[a-f0-9]{64}$'}, claimHash: {type:'string', description:'SHA-256 of the private random claim, hex'}, offerVersion: {type:'string'}, quantity: {type:'integer',minimum:1}, game: {type:'string'} } } } } }, responses: { '200': {description:'Order and hosted checkout URL'}, '409': {description:'Offer changed'} } } };
+  return Response.json(doc,{headers:{'cache-control':'no-store'}});
+}

package/worker/purchase-hosted-readiness.mjs

@@ -0,0 +1,16 @@
+import { hasStripeKey } from './shop-links.mjs';
+import { purchaseLinks } from './purchase-links.mjs';
+import { KEY_SHAPE, WEBHOOK_SECRET_SHAPE } from './stripe.mjs';
+import { signingKey } from './purchase-keys.mjs';
+import { recurringReady } from './purchase-store.mjs';
+
+/** The hosted route and its office report use the same local configuration checks. */
+export async function hostedReadiness(env, catalogue, recurring = false) {
+  const missing = [];
+  if (!env.DB || env.HOMIE_PREVIEW === '1') missing.push('Studio purchases need the deployed database');
+  if (!env.PURCHASE_RATE_LIMITER) missing.push('Deploy the purchase rate limiting binding');
+  try { await signingKey(env); } catch { missing.push('Create a valid purchase signing key'); }
+  if ((!hasStripeKey(env) && !purchaseLinks(env)) || !WEBHOOK_SECRET_SHAPE.test(env.STRIPE_WEBHOOK_SECRET ?? '') || !['stripe', 'stripe-managed'].includes(catalogue.shop?.purchasesTill ?? catalogue.shop?.till)) missing.push('Connect this studio shop to Stripe first');
+  if (recurring && hasStripeKey(env) && !(await recurringReady(env))) missing.push('Reconnect the shop to verify subscription permissions and webhook events before selling recurring resources');
+  return { ready: missing.length === 0, missing };
+}

package/worker/purchase-keys.mjs

@@ -0,0 +1,20 @@
+/** The licence key ring is a Worker secret, independent of referral statements and D1. */
+
+export async function purchaseKeys(env) {
+  let keys;
+  try { keys = JSON.parse(env.PURCHASE_SIGNING_KEYS); } catch { throw new Error('Configure purchase signing keys before selling'); }
+  if (!Array.isArray(keys) || !keys.length || !keys[0].d) throw new Error('Configure purchase signing keys before selling');
+  return keys;
+}
+export async function signingKey(env) {
+  const { importJWK } = await import('jose');
+  const [jwk] = await purchaseKeys(env);
+  return { privateKey: await importJWK(jwk, 'Ed25519'), publicJwk: { kty: jwk.kty, crv: jwk.crv, x: jwk.x } };
+}
+export async function publicKeys(env) {
+  const { calculateJwkThumbprint } = await import('jose');
+  return Promise.all((await purchaseKeys(env)).map(async ({ kty, crv, x }) => {
+    const jwk = { kty, crv, x };
+    return { ...jwk, kid: await calculateJwkThumbprint(jwk), alg: 'Ed25519', use: 'sig' };
+  }));
+}

package/worker/purchase-links.mjs

@@ -0,0 +1,9 @@
+/** Public Payment Link configuration, installed by the owner's existing CLI authorization. */
+import { paymentLinkURL, linkConfig } from './shop-links.mjs';
+import { canonicalJson } from './referrals.mjs';
+export function purchaseLinks(env) {
+  try { const c = JSON.parse(env.PURCHASE_LINKS ?? 'null'); return c?.v === 1 && c.mode === linkConfig(env)?.mode && Array.isArray(c.offers) ? c : null; } catch { return null; }
+}
+export function purchaseLink(env, o) {
+  return purchaseLinks(env)?.offers.find((link) => (link.quantity ?? 1) === o.quantity && link.kind === o.resource_kind && link.resource === o.resource_id && link.version === JSON.parse(o.manifest).version && link.offer === canonicalJson(JSON.parse(o.offer)) && paymentLinkURL(link.url));
+}

package/worker/purchase-machine.mjs

@@ -0,0 +1,279 @@
+import { definitiveRefusal, blockingJobsSQL } from './payment-policy.mjs';
+import { orderFact, offerVersion, orderState } from './purchase-core.mjs';
+import { problem } from './purchase-problem.mjs';
+import { saveRecording, recordProviderResult, recordingFailure, reconcileRecordings } from './payment-recovery.mjs';
+import { machineCapabilities, notePaymentRefusal } from './payment-capabilities.mjs';
+import { purchaseResponse } from './purchase-response.mjs';
+/** One durable purchase, regardless of transport. No seller browser page is involved. */
+import { Receipt } from 'mppx';
+import { signingKey } from './purchase-keys.mjs';
+import {
+  byClaim,
+  expireUnpaidMachineOrders,
+  byId,
+  createPurchase,
+  currentPurchaseOrder,
+  deliveryAllowed,
+  grantPurchase,
+  listedRelease,
+  limitedText,
+  resourceAvailable,
+} from "./purchases.mjs";
+import { paymentProtocol, stripeClient } from './machine-payments.mjs';
+import { digest, manifestHash } from './purchase-crypto.mjs';
+import { resourceKind, hasResourceKind } from './resource-kinds.mjs';
+import { modeOf } from './stripe.mjs';
+import { newOrderId } from './shop-store.mjs';
+
+export async function machineResource(
+  request,
+  env,
+  url,
+  cat,
+  dependencies = {},
+) {
+  const hostedFallback = (detail) => problem(409, detail, { checkout: { url: `${url.origin}/api/purchases/intent`, method: 'POST', description: 'Hosted Checkout fallback. Submit the published offerVersion, buyer and private claimHash.' } });
+  const mcp = Boolean(dependencies.mcpInput);
+  if (dependencies.dryRun && (mcp || request.headers.has('authorization') || request.headers.has('payment-signature'))) throw new Error('Dry exchanges cannot carry payment credentials');
+  if (request.method !== "POST")
+    return problem(405, "POST the resource, buyer, claim and approved quote");
+  const b = await machineInput(request, dependencies.mcpInput);
+  if (b instanceof Response) return b;
+  if (
+    !b ||
+    !/^[a-f0-9]{64}$/.test(b.claim ?? "") ||
+    !/^[a-f0-9]{64}$/.test(b.buyer ?? "")
+  )
+    return problem(400, "Supply a private random claim and buyer identity");
+  if (!hasResourceKind(b.kind)) return problem(400,"Name a supported resource kind");
+  const adapter = resourceKind(b.kind);
+  const quoteHash = adapter.quote;
+  const claimHash = await digest(b.claim);
+  const resourcePath = `/api/purchases/resource/${encodeURIComponent(b.kind)}/${encodeURIComponent(b.resource)}/${encodeURIComponent(b.version)}/${claimHash}`;
+  if (!mcp && url.pathname !== '/api/purchases/resource' && url.pathname !== resourcePath.slice(0, resourcePath.lastIndexOf('/')) && url.pathname !== resourcePath)
+    return problem(409, "Resource URL differs from this purchase");
+  if (!mcp) request = new Request(new URL(resourcePath, url.origin), request);
+  const approved = async (resource, quantity, game, offer) => b.quote === await quoteHash(resource, quantity, game, offer) || b.offerVersion === (await offerVersion({ kind: b.kind, id: resource.id, release: resource.version, manifest: await manifestHash(resource) }, offer)).version;
+  await expireUnpaidMachineOrders(env);
+  let o = await byClaim(env, claimHash);
+  if (!o) {
+    if ((cat.shop?.purchasesTill ?? cat.shop?.till) === 'stripe-managed') return hostedFallback('This seller uses Stripe Managed Payments.');
+    const listed = await listedRelease(env, url.origin, b.kind, b.resource, b.version);
+    if (!listed) return problem(404, "Offer unavailable");
+    const { resource, offer } = listed;
+    const quantity = b.quantity ?? 1;
+    const game = b.game ?? null;
+    if (offer.billing !== "one-time")
+      return hostedFallback("Recurring purchases use Stripe Checkout");
+    if (offer.amount === 0) return hostedFallback("A zero-price offer uses hosted Checkout.");
+    if (offer.currency !== "usd") return hostedFallback("This currency requires hosted Checkout; machine payments currently support USD.");
+    if (
+      offer.automaticTax ||
+      offer.taxBehavior === "exclusive"
+    )
+      return hostedFallback("This offer needs Checkout to calculate its final total");
+    const validation = adapter.validate({ ...resource, sale: offer }, { quantity, game });
+    if (validation.length) return problem(400, validation.join('; '));
+    if (!(await approved(resource, quantity, game, offer)))
+      return problem(409, "Price or terms changed; approve the fresh quote");
+    // Check readiness and bytes before an agent can spend anything.
+    if (!env.PURCHASE_SIGNING_KEYS || !(await machineCapabilities(env)).ready)
+      return hostedFallback("Seller machine payments are not configured. Use Hosted Checkout.");
+    await signingKey(env);
+    if (!(await resourceAvailable(env, b.kind, resource)))
+      return problem(503, "Paid files unavailable; no payment requested");
+    const pending = {
+      id: newOrderId(),
+      resource_kind: b.kind,
+      item: `${b.kind}:${resource.id}`,
+      game,
+      amount: quantity * offer.amount,
+      currency: offer.currency,
+      till: "stripe",
+      mode: modeOf(env.STRIPE_KEY),
+      claim_hash: claimHash,
+      buyer: b.buyer,
+      buyer_label: "Buyer",
+      quantity,
+      transport: "machine",
+      manifest: JSON.stringify(resource),
+      manifest_hash: await manifestHash(resource),
+      offer: JSON.stringify(offer),
+    };
+    await createPurchase(env, pending);
+    o = await byId(env, pending.id);
+  }
+  const hasCredential = request.headers.has('authorization') || request.headers.has('payment-signature') || Boolean(dependencies.extra?._meta);
+  await reconcileRecordings(env, o.id, { ...(dependencies.chainRpc ? { rpc: dependencies.chainRpc } : {}), facilitator: dependencies.facilitator });
+  o = await byId(env, o.id);
+  const pending = await env.DB.prepare(`SELECT 1 FROM purchase_jobs WHERE order_id = ?1 AND ${blockingJobsSQL} UNION ALL SELECT 1 FROM purchase_settlements WHERE order_id = ?1 AND state NOT IN ('complete','unpaid') LIMIT 1`).bind(o.id).first();
+  if (pending && !['paid','fulfilled','disputed'].includes(o.status)) return problem(503, 'Payment outcome is being reconciled. Retry this purchase; do not pay again.');
+  if (o.status === "started") {
+    const listed = await listedRelease(env, url.origin, b.kind, b.resource, b.version);
+    if (Date.now() >= o.created_at + 300000 || !listed ||
+        await quoteHash(listed.resource, o.quantity, o.game, listed.offer) !== await quoteHash(JSON.parse(o.manifest), o.quantity, o.game, JSON.parse(o.offer))) {
+      await orderFact(env, o.id, 'expired', {}).run();
+      return problem(409, "This five-minute purchase has expired or its offer changed. Start a new purchase with the current offer.");
+    }
+  }
+  const core = await orderState(env, o.id);
+  if (o.status === "started" && core?.transport !== "machine")
+    return problem(
+      409,
+      "This order uses Checkout; do not pay it through a wallet as well",
+    );
+  if (o.payment && hasCredential) o = await currentPurchaseOrder(env, o.id);
+  const resource = JSON.parse(o.manifest);
+  if (
+    o.resource_kind !== b.kind ||
+    o.buyer !== b.buyer ||
+    o.mode !== modeOf(env.STRIPE_KEY) ||
+    resource.id !== b.resource ||
+    resource.version !== b.version ||
+    !(await approved(resource, o.quantity, o.game, JSON.parse(o.offer)))
+  )
+    return problem(409, "Request differs from this purchase");
+  const response = async () => {
+    if (!(await deliveryAllowed(env, o)))
+      throw new Error(
+        "Test downloads need owner approval and never work in live mode",
+      );
+    const grant = await grantPurchase(env, url.origin, o, {
+      version: b.version,
+    });
+    if (!grant.ok) return grant;
+    const result = await grant.json();
+    return { ...result, order: o.id };
+  };
+  if (!dependencies.dryRun && o.mode === 'test' && !(await deliveryAllowed(env, o)))
+    return problem(403, `Test downloads need owner approval for order ${o.id}. No payment requested.`, { order: o.id });
+  const client = recordingClient(env, o, dependencies.client ?? stripeClient(env));
+  const receiptKey = o.id;
+  const stored = await env.DB.prepare("SELECT value FROM purchase_receipts WHERE order_id = ?1")
+    .bind(receiptKey)
+    .first();
+  o = await byId(env, o.id);
+  if (["paid", "fulfilled", "disputed"].includes(o.status)) {
+    const recorded = stored ? null : await env.DB.prepare("SELECT payload FROM purchase_jobs WHERE order_id = ?1 ORDER BY updated_at DESC LIMIT 1").bind(o.id).first();
+    const recording = recorded && JSON.parse(recorded.payload);
+    const challengeId = recording?.params?.metadata?.mpp_challenge_id;
+    if (!stored && !challengeId) return problem(409, "This purchase has no machine-payment challenge receipt. Retrieve the paid files using the purchase grant endpoint.");
+    const receipt = stored ? JSON.parse(stored.value) : {
+      method: recording?.params?.metadata?.mpp_method ?? "stripe", status: "success", reference: recording?.chain?.transaction_hash ?? o.payment,
+      timestamp: new Date(o.paid_at).toISOString(), challengeId,
+    };
+    const result = await response();
+    if (result instanceof Response) return result;
+    if (mcp) return machineMcpDelivery(result, dependencies, receipt);
+    const delivered = purchaseResponse(result, env);
+    if (!mcp) {
+      delivered.headers.set("Payment-Receipt", Receipt.serialize(receipt));
+      const headers = await env.DB.prepare(
+        "SELECT headers AS value FROM purchase_receipts WHERE order_id = ?1 AND headers IS NOT NULL",
+      )
+        .bind(o.id)
+        .first();
+      if (!headers && recording?.chain?.network === 'base') delivered.headers.set('payment-response', btoa(JSON.stringify({ success: true, transaction: recording.chain.transaction_hash, network: o.mode === 'live' ? 'eip155:8453' : 'eip155:84532' })));
+      if (headers)
+        for (const [key, value] of Object.entries(JSON.parse(headers.value)))
+          delivered.headers.set(key, value);
+    }
+    return mcp ? (await delivered.json()).result : delivered;
+  }
+  if (o.status !== "started")
+    return problem(402, `Purchase is ${o.status}; do not pay this order again`);
+  const readiness = await machineCapabilities(env);
+  if (!readiness.ready) return problem(503, Object.values(readiness.reasons).join(' '));
+  const protocol = await paymentProtocol(env, o, {
+    ...dependencies,
+    client,
+    mcp,
+    realm: url.hostname,
+    capabilities: readiness,
+  });
+  protocol.onPaymentSuccess(async ({ receipt, challenge }) => {
+    receipt = { ...receipt, challengeId: challenge.id };
+    await env.DB.prepare(
+      "INSERT INTO purchase_receipts (order_id,value) VALUES (?1,?2) ON CONFLICT(order_id) DO UPDATE SET value = excluded.value",
+    )
+      .bind(receiptKey, JSON.stringify(receipt))
+      .run();
+  });
+  const paid = await protocol.charge({
+    expires: new Date(o.created_at + 300000).toISOString(),
+    amount: (o.amount / 100).toFixed(2),
+    description: `${resource.name} ${resource.version}`,
+    scope: o.id,
+    meta: { order: o.id, quote: await quoteHash(resource, o.quantity, o.game, JSON.parse(o.offer)) },
+    paymentIntentOptions: { metadata: { homie: "purchase-v1", order: o.id } },
+  })(mcp ? dependencies.extra : request);
+  if (paid.status === 402) {
+    const uncertain = await env.DB.prepare(`SELECT 1 FROM purchase_jobs WHERE order_id = ?1 AND ${blockingJobsSQL} UNION ALL SELECT 1 FROM purchase_settlements WHERE order_id = ?1 AND state NOT IN ('complete','unpaid') LIMIT 1`).bind(o.id).first();
+    if (uncertain) return problem(503, 'The payment outcome is being reconciled. Retry this purchase; do not pay again.');
+    if (mcp) throw paid.challenge;
+    return paid.challenge;
+  }
+  if (!mcp) {
+    const receiptResponse = paid.withReceipt(new Response());
+    const headers = Object.fromEntries(
+      ["payment-receipt", "payment-response"]
+        .filter((key) => receiptResponse.headers.has(key))
+        .map((key) => [key, receiptResponse.headers.get(key)]),
+    );
+    await env.DB.prepare(
+      "INSERT INTO purchase_receipts (order_id,headers) VALUES (?1,?2) ON CONFLICT(order_id) DO UPDATE SET headers = excluded.headers",
+    )
+      .bind(o.id, JSON.stringify(headers))
+      .run();
+  }
+  o = await byId(env, o.id);
+  if (!["paid","fulfilled"].includes(o.status))
+    return problem(
+      503,
+      "Settlement is being recorded. Retry this order; do not pay again",
+    );
+  const result = await response();
+  if (result instanceof Response) return result;
+  if (mcp) return paid.withReceipt(machineMcpDelivery(result, dependencies));
+  return paid.withReceipt(purchaseResponse(result, env));
+}
+
+function machineMcpDelivery(result, dependencies, receipt) {
+  dependencies.setDelivery?.(result);
+  return { content: [{ type: 'text', text: JSON.stringify(result) }], ...(receipt ? { _meta: { 'org.paymentauth/receipt': receipt } } : {}) };
+}
+
+async function machineInput(request, mcpInput) {
+  let text;
+  try { text = await limitedText(request.clone()); } catch { return problem(413, 'Purchase request too large'); }
+  if (new TextEncoder().encode(text).length > 16384) return problem(413, 'Purchase request too large');
+  let input;
+  try { input = JSON.parse(text); } catch { return problem(400, 'Invalid JSON request'); }
+  if (!input || typeof input !== 'object') return problem(400, 'Expected a purchase request');
+  return mcpInput ?? input;
+}
+function recordingClient(env, o, providerClient) {
+
+  const create = providerClient.paymentIntents.create.bind(
+    providerClient.paymentIntents,
+  );
+  const client = Object.create(providerClient);
+  client.paymentIntents = Object.create(providerClient.paymentIntents);
+  client.paymentIntents.create = async (params, options) => {
+    params = { ...params, metadata: { ...params.metadata, homie: "purchase-v1", order: o.id } };
+    const id = await saveRecording(env, o, params, options);
+    try {
+      const saved = await env.DB.prepare('SELECT state,payload FROM purchase_jobs WHERE id = ?1').bind(id).first();
+      if (saved.state === 'manual_review') throw new Error('Stripe recording was refused; the seller must handle any refund manually.');
+      const original = JSON.parse(saved.payload);
+      let pi = await create(original.params, original.options);
+      if (pi.status === 'processing') pi = await providerClient.paymentIntents.retrieve(pi.id);
+      if (pi.status === 'requires_action') pi = await providerClient.paymentIntents.cancel(pi.id);
+      await recordProviderResult(env, o, id, pi);
+      return pi;
+    } catch (error) { await recordingFailure(env, id, error);
+      if (((error.statusCode ?? error.status) === 403 || /not available|not enabled|permission|country|eligib/i.test(error.message))) await notePaymentRefusal(env, params.payment_method_options?.crypto ? 'base' : 'card', error);
+      throw error; }
+  };
+  return client;
+}