@homie-rocks/studio 0.37.1 → 0.38.0

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;
+}

package/worker/purchase-mcp.mjs

@@ -0,0 +1,42 @@
+import { purchaseResponse } from './purchase-response.mjs';
+import { machineCapabilities } from './payment-capabilities.mjs';
+/** The SDK owns protocol negotiation, JSON-RPC errors and stateless HTTP transport. */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { machineResource } from './purchase-machine.mjs';
+export const purchaseSchema = {
+  type: 'object', required: ['kind', 'resource', 'version', 'buyer', 'claim', 'offerVersion'],
+  properties: {
+    kind: { type: 'string' }, resource: { type: 'string' }, version: { type: 'string' },
+    buyer: { type: 'string', pattern: '^[a-f0-9]{64}$', description: 'A random private buyer identifier.' },
+    claim: { type: 'string', pattern: '^[a-f0-9]{64}$', description: 'A new private random 32-byte hex secret for this purchase. Keep it to retrieve this order.' },
+    offerVersion: { type: 'string', description: 'The published immutable offer version.' },
+    quantity: { type: 'integer', minimum: 1, default: 1 }, game: { type: 'string' },
+  },
+};
+export async function purchaseMcp(request, env, url, cat) {
+  let delivery;
+  const capability = await machineCapabilities(env);
+  const methods = Object.fromEntries([...(capability.machine.card ? ['stripe'] : []), ...(capability.machine.tempo ? ['tempo'] : [])].map((method) => [method, { intents: ['charge'] }]));
+  const server = new Server({ name: 'Studio purchases', version: '1' }, {
+    capabilities: { tools: {}, experimental: { payment: { methods } } },
+  });
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [{
+    name: 'purchase', description: 'Pay for the published offer and receive files, receipt and proof. Unpaid challenges expire after five minutes.', inputSchema: purchaseSchema,
+  }] }));
+  server.setRequestHandler(CallToolRequestSchema, async (input, extra) => {
+    if (input.params.name !== 'purchase') return { isError: true, content: [{ type: 'text', text: 'Unknown tool' }] };
+    const result = await machineResource(new Request(request.url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input.params.arguments) }), env, url, cat, {
+      mcpInput: input.params.arguments, setDelivery: (data) => { delivery = data; }, extra: { ...extra, _meta: input.params._meta },
+    });
+    if (result instanceof Response) return { isError: true, content: [{ type: 'text', text: await result.text() }] };
+    return result;
+  });
+  const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+  await server.connect(transport);
+  const response = await transport.handleRequest(request);
+  if (!delivery) return response;
+  const envelope = await response.json();
+  return purchaseResponse(delivery, env, { mcp: true, envelope });
+}

package/worker/purchase-office-routes.mjs

@@ -0,0 +1,17 @@
+import { selling } from './extensions.mjs';
+const json = (v,status=200) => Response.json(v,{status});
+export async function officeRoutes(request, env, path, body) {
+  if (path === '/_studio/api/shop/readiness' && request.method === 'POST') return json(await selling.testPaymentExchange(env));
+  if (['/_studio/api/shop/retire', '/_studio/api/shop/reissue', '/_studio/api/shop/test-access', '/_studio/api/shop/sync-offers', '/_studio/api/shop/reconcile-payments'].includes(path) && request.method === 'POST') {
+    try { if (path.endsWith('/reconcile-payments')) { return json({ ok: true, ...await selling.reconcileRecordings(env, body.order ?? null, { payment: body.payment ?? null, cancel: body.cancel === true }) }); }
+      if (path.endsWith('/test-access')) return json(await selling.authorizePurchaseTest(env, body.order));
+      if (path.endsWith('/sync-offers')) return json(await selling.expirePurchaseCheckouts(env));
+      return json(path.endsWith('/retire') ? await selling.retireResource(env, body.kind, body.resource) : await selling.reissuePurchaseClaim(env, body)); }
+    catch (error) {
+      if (error.status === 403 || error.status === 401) return json({ ok: false, message: 'Reconnect the shop with Checkout Sessions and Subscriptions Write permissions, then retry. New sales remain closed if retirement began.' }, 503);
+      if (/no such table/.test(error.message)) return json({ ok: false, message: 'Deploy the purchase migrations first' }, 503);
+      throw error;
+    }
+  }
+  return null;
+}

package/worker/purchase-office-script.mjs

@@ -0,0 +1,38 @@
+export const officeScript = String.raw`      if (s.purchases) {
+        top.appendChild(el('h3', null, 'Machine payment readiness'));
+        (s.purchases.missing || []).forEach(function (reason) { top.appendChild(el('p', null, reason)); });
+        var exchange = s.purchases.exchange;
+        if (exchange) top.appendChild(el('p', null, exchange.verified ? exchange.scope : exchange.reason));
+      }
+      var recoveries = (s.settlementRecovery || []).concat(s.paymentRecovery || []);
+      if (recoveries.length) {
+        top.appendChild(el('h3', null, 'Payment recovery'));
+        recoveries.forEach(function (job) {
+          top.appendChild(el('p', null, job.order_id + ' · ' + (job.network || 'Stripe') + ' · ' + job.state + (job.request_key ? ' · request ' + job.request_key : '') + (job.payment ? ' · payment ' + job.payment : '') + (job.started_at ? ' · since ' + new Date(job.started_at).toISOString() : '') + (job.error ? ' · ' + job.error : '')));
+          if (job.request_key && job.payment) {
+            var cancel = el('button', { type: 'button' }, 'Cancel if unpaid');
+            cancel.addEventListener('click', function () {
+              if (!confirm('Read this payment from Stripe and cancel it only if it has not succeeded? A paid order stays paid and can be refunded separately.')) return;
+              cancel.disabled = true;
+              api('POST', '/_studio/api/shop/reconcile-payments', { order: job.order_id, cancel: true }).then(function (result) { if (!result.ok) throw new Error(result.message || 'Reconciliation failed'); load(); }).catch(function (error) { cancel.disabled = false; toast(error.message); });
+            });
+            top.appendChild(cancel);
+          }
+          if (job.request_key && !job.payment) {
+            var payment = el('input', { placeholder: 'Existing Stripe PaymentIntent id', 'aria-label': 'Existing Stripe PaymentIntent id' });
+            var read = el('button', { type: 'button' }, 'Read this payment');
+            read.addEventListener('click', function () {
+              read.disabled = true;
+              api('POST', '/_studio/api/shop/reconcile-payments', { order: job.order_id, payment: payment.value.trim() }).then(function (result) { if (!result.ok) throw new Error(result.message || 'Read failed'); load(); }).catch(function (error) { read.disabled = false; toast(error.message); });
+            });
+            top.appendChild(payment); top.appendChild(read);
+          }
+        });
+        var reconcile = el('button', { type: 'button' }, 'Reconcile payments now');
+        reconcile.addEventListener('click', function () {
+          reconcile.disabled = true;
+          api('POST', '/_studio/api/shop/reconcile-payments', {}).then(function (result) { if (!result.ok) throw new Error(result.message || 'Reconciliation failed'); load(); }).catch(function (error) { reconcile.disabled = false; toast(error.message); });
+        });
+        top.appendChild(reconcile);
+      }
+`;

package/worker/purchase-office.mjs

@@ -0,0 +1,35 @@
+/** Optional resource rows in the existing shop office. */
+import { hasStripeKey, shopMode } from './shop-links.mjs';
+import { dashboardLink, refundPayment, cancelSubscription, redactStripe } from './stripe.mjs';
+import { currentPurchaseOrder, purchaseReadiness } from './purchase-owner.mjs';
+import { reconcileOrder } from './purchase-reconciliation.mjs';
+import { termsOf, byId } from './purchase-store.mjs';
+import { manualRefundDetails } from './payment-manual-refund.mjs';
+import { jobsSQL } from './payment-policy.mjs';
+import { money } from './shop-rules.mjs';
+export async function refundOrder(env, order, { reason = 'requested_by_customer', by = 'owner' } = {}) {
+  if (order.mode !== shopMode(env)) return { ok: false, error: 'mode', message: 'Reconnect the payment mode of this order.' };
+  if (!hasStripeKey(env)) return { ok: false, error: 'stripe-dashboard', message: 'Refund in Stripe or ask your connected AI. Its signed refund event updates this purchase.', url: dashboardLink(order.mode, 'payment', order.payment) };
+  let o;
+  try { o = await currentPurchaseOrder(env, order.id) ?? order; } catch (error) { return {ok:false,error:'stripe-retry',message:redactStripe(error.message,env)}; }
+  if (o.status === 'refunded') return { ok: true, order: o.id, status: 'succeeded', already: true };
+  if (!['paid','fulfilled'].includes(o.status)) return { ok: false, error: 'state', message: `This order is ${o.status}.` };
+  if (!o.payment) { const manual = await manualRefundDetails(env, o); return { ok: false, error: manual ? 'manual-refund-required' : 'no-payment', ...manual }; }
+  try {
+    const refund = await refundPayment(env, o.payment, { reason, metadata: { order: o.id, by } });
+    await reconcileOrder(env, o);
+    if (refund.status !== 'succeeded') return { ok: true, pending: true, order: o.id, status: refund.status };
+    if (o.subscription && termsOf(o).refundEndsSubscription === true) await cancelSubscription(env, o.subscription);
+    return { ok: true, order: o.id, refund: refund.id, status: refund.status, amount: refund.amount ?? o.amount, currency: o.currency };
+  } catch (error) { return { ok: false, error: 'stripe', message: redactStripe(error.message, env) }; }
+}
+export async function extendOffice(env, cat, origin, out) {
+  try {
+    out.purchases = await purchaseReadiness(env, origin, cat);
+    const rows = (await env.DB.prepare('SELECT o.*, r.manifest AS manifest FROM purchase_orders o JOIN resource_snapshots r ON r.hash=o.manifest_hash ORDER BY o.created_at DESC LIMIT 100').all()).results ?? [];
+    for (const r of rows) out.orders.push({ id: r.id, status: r.status, resourceKind: r.resource_kind, resource: r.resource_id, name: JSON.parse(r.manifest).name, shown: money(r.amount,r.currency), amount:r.amount, currency:r.currency, createdAt:r.created_at, mode:r.mode, player:{name:r.buyer_label}, stripe:r.payment ? dashboardLink(r.mode,'payment',r.payment):null, refundable:hasStripeKey(env) && ['paid','fulfilled'].includes(r.status), manualRefund:await manualRefundDetails(env,r) });
+    out.orders.sort((a,b)=>b.createdAt-a.createdAt);
+    out.paymentRecovery = (await env.DB.prepare(`SELECT id AS request_key, order_id, state, payment, error, attempts, updated_at FROM purchase_jobs WHERE ${jobsSQL('visible')} ORDER BY updated_at`).all()).results ?? [];
+    out.settlementRecovery = (await env.DB.prepare('SELECT order_id, network, state, reference, error, created_at, updated_at FROM purchase_settlements ORDER BY created_at').all()).results ?? [];
+  } catch (error) { if (!/no such table/.test(error.message)) throw error; out.purchases = {ready:false,missing:['Deploy the purchase migrations']}; }
+}