@homie-rocks/studio 0.37.1 → 0.37.2

package/parts/PARTS.md

@@ -1,14 +1,10 @@
 # Studio parts
 
-Studios build on each other by sharing **parts**: a reusable piece of a game, app, music or video that its studio chooses to share, so somebody
-making another game can use it. A creature from one game, a level from another, a bot brain from a third. That is
-the whole idea. Without parts, a creator's AI has to come up with everything on its own.
-
-Mashing up is not a command: it is making a game with parts from several games.
+Studios share **parts**: reusable files another studio can find, license and install. A part may be a game mechanic, an app's quiz, menu board or waitlist screen, a music loop or complete track, or video. It can be free or priced. The licence says where it may be used, including a venue when the seller chooses that use.
 
 ## The rules
 
-1. **A part is a reusable piece, never a whole game or app.** Remix, which handed over an entire game, is retired;
+1. **The lifting command extracts a piece, never a whole game or app.** Music, video and app assets can be authored directly in a part folder. Remix, which handed over an entire game, is retired;
    parts are what replaces it.
 2. **A part can take any form** that suits the piece: code, assets, data, a JSON description, a tuned config, or a
    mix. Form is not restricted.
@@ -89,11 +85,12 @@ named after it):
 | Field | What it is |
 | --- | --- |
 | `id`, `name`, `kind`, `version`, `summary` | `version` is three numbers; a shared version never changes, so a change is a new version. `summary` is one sentence. |
-| `kind` | `character`, `rig`, `clips`, `environment`, `effect`, `sound`, `ui`, `mechanic`, `shader`, `level-generator`, `bot-brain`, `audio-pack`, `set-piece`. `quiz`, `menu-board`, `waitlist`, `live-total`, `loop`, `stem`, `track`, `video-intro`, `video-template` also name parts. There is no kind for a whole game or app. |
+| `kind` | `character`, `rig`, `clips`, `environment`, `effect`, `sound`, `ui`, `mechanic`, `shader`, `level-generator`, `bot-brain`, `audio-pack`, `set-piece`. These are suggestions, not a whitelist. `app`, `music` and `video` are also suggested; any lowercase label of letters, digits and hyphens is accepted. |
 | `license`, `attribution` | Needed to share: an SPDX identifier, and who a game using the part credits. |
 | `share` | **Default `false`.** The part's own switch, and the only thing that decides whether it is shared. |
-| `uses` | Optional intended uses: `game`, `app`, `venue`, `cause`, `music`, `video`. Describe the purpose, independently of licence and any future pricing. |
-| `from` | The source and studio: `game`, `app`, `music` or `video` with its id. Written when a part is lifted out of a game. |
+| `from` | The source and studio: existing `{game, studio}` stays valid; non-game work may use `{kind, id, studio}`. Written when a part is lifted out of a game. |
+| `uses` | Optional intended uses: `game`, `app`, `venue`, `cause`, `music`, `video`; the licence governs permission. |
+| App/media provenance | The source and studio: `game`, `app`, `music` or `video` with its id. Written when a part is lifted out of a game. |
 | `entry` | For a part with code: the module a game imports. A part of assets or data has none. |
 | `files` | Every file with its SHA-256 and size, **written by the tool, never by hand**. A file may carry `"rights"` (below). |
 | `preview` | `page`: a self-contained HTML page shown in a sandboxed frame. `image`: a still. `aspect`: the frame's shape as `"W:H"` (whole numbers 1 to 32, no flatter than 3:1, no taller than 1:2; default `"16:9"`). `phoneAspect`: the shape when the frame is narrower than 600 px. |
@@ -169,6 +166,237 @@ build, whether or not the add named the game.
   alone.
 - The plumbing behind the tools is `homie-studio parts find | new | add | share | unshare | check`.
 
-App parts use the same lift/import/credit paths as game parts. Music and video parts can start empty with the corresponding kind; add their selected files, licence and provenance before sharing. `uses` describes what they are for, not permission to use them: the licence controls that. No price or checkout behavior is introduced; future commercial metadata can be added separately without changing the meaning of `share`.
+App parts use the same lift/import/credit paths as game parts. Music and video parts can start empty with the corresponding kind; add their selected files, licence and provenance before sharing. `uses` describes what they are for, not permission to use them: the licence controls that. Optional `sale` metadata adds pricing without changing the meaning of `share`.
 
 For example: `homie-studio parts new welcome-queue --kind waitlist --uses app,venue`, or `parts new gala-loop --kind loop --uses venue,cause`. A source app is selected by the existing `--from <id>` and `--game <id>` options.
+
+## Selling a part to another studio
+
+A part can be free or have `sale` in its `part.json`. The seller chooses its price,
+licence and refund terms. Homie takes no cut and sets no price or spending ceiling
+for studio purchases. Existing player shop rules apply to players, not these licences.
+
+```json
+{
+  "license": "LicenseRef-Studio-Commercial",
+  "licenseTerms": "LICENSE.txt",
+  "sale": {
+    "amount": 2500,
+    "currency": "usd",
+    "billing": "one-time",
+    "scope": "studio",
+    "source": true,
+    "updates": "major",
+    "taxCode": "txcd_10000000",
+    "refund": "Contact the studio for the refund terms written in LICENSE.txt.",
+    "onRefund": "terminate",
+    "onExpiry": "retain",
+    "commercialUse": true,
+    "transferable": false,
+    "publicFiles": ["preview/demo.js"]
+  }
+}
+```
+
+This fragment is added to a complete part; choose the tax code for the actual goods.
+`LICENSE.txt` must contain the complete seller-chosen licence and refund terms and
+identify each custom licence. `license` also accepts SPDX expressions (`MIT OR
+Apache-2.0`, for example); the toolkit never chooses an alternative for the buyer.
+`LicenseRef-…` identifies a custom commercial licence, not an SPDX listed licence.
+The structured summary and licence text must agree; the text is what the parties read.
+
+- `amount` is a positive integer in Stripe's currency minor units (JPY has no cents).
+  There is no toolkit price ceiling; Stripe's own supported amounts still apply.
+- `billing`: `one-time`, `day`, `week`, `month`, `year` (the recurring intervals Stripe supports). Recurring sales use Stripe Billing, with
+  paid-through periods from paid invoices. Cancellation uses Stripe's customer portal.
+- `scope` is the seller’s label for licensed use (for example `studio`, `game`, `seat`, `venue` or `app`). A game licence names the buyer's game. A seat
+  licence has a quantity; seat assignment and transfer follow the written terms.
+- `source`, `commercialUse`, `transferable` are explicit booleans. Package only the
+  files being sold. `source: false` does not strip or obfuscate files automatically.
+- `updates`: `none`, `major`, `all`. Existing purchases use their original update
+  promise. Later list prices and new-buyer terms never remove the purchased promise. Included updates remain licensed under the purchased terms.
+- `refund` is the seller's policy in plain words; `onRefund` and `onExpiry` choose
+  `retain` or `terminate` for rights to already downloaded copies. Full refunds and
+  lost disputes stop new downloads. Partial refunds leave the licence active.
+- `publicFiles` explicitly names preview dependencies that may be downloaded without
+  buying. The preview page, image and licence text are public automatically. A browser
+  demo exposes whatever code and assets it uses. Keep private source out of previews.
+
+On an already deployed studio, ask the AI to connect the shop and sell the part. The AI runs `shop init` if needed, `shop connect`, configures private storage and shares the release. **One browser approval** connects Stripe when its CLI session is not already authorized; an existing session needs **zero** new approvals. Account onboarding and Cloudflare authorization are separate provider requirements. Products, Prices, Payment Links and the webhook are created through Stripe's official CLI. The webhook signing secret and an automatically generated purchase signing key go privately into the Worker. No person finds, copies or pastes either secret.
+
+The default hosted fallback uses these Payment Links with **no Stripe API key in the Worker**. The hosted review records the accepted terms, then redirects to Stripe with an opaque order reference. A verified signed event binds the exact link, revision, currency, amount and mode before granting files. Lost events wait for Stripe redelivery; the owner's AI can resend them through Stripe's CLI. Refund in Stripe or ask that connected AI. Keyless retirement returns the subscriptions for that AI to cancel through Stripe; signed cancellation events let retirement finish without revoking paid-period downloads. The shop's signed refund snapshots update access; the Worker makes no Stripe API request. The AI can preconfigure any positive quantities in `parts/offers.json`, for example `{"camera":{"quantities":[1,5,20]}}`, then run `shop connect`; it creates a fixed link for each chosen quantity. The default is one unit. A quantity without a matching link needs that setup sync or the fuller Session connection, so the paid quantity always matches the approved quote. Signed paid invoices supply recurring access periods; invoice-payment events associate their refunds. A later billing period never removes the rights the seller promised for earlier downloads.
+
+Paid releases use a **separate private R2 bucket and `PURCHASE_MEDIA` binding**. Never enable a public R2 domain for it. Deploy verifies the selling Worker before uploading private files and reads every uploaded hash back. No paid payload is copied into public static assets; the normal Worker cannot read this bucket. Technical file and request limits are security/resource safeguards, not spending limits.
+
+### Which payment paths need credentials
+
+| Path | Stripe API key in Worker? | Other requirements |
+| --- | --- | --- |
+| Hosted Payment Link fallback | **No** | CLI browser approval at setup; signed webhook; private signing key and storage |
+| MPP Stripe shared payment tokens | **Yes** | Authenticated PaymentIntent creation, account profile and SPT eligibility |
+| MPP over MCP | **Yes** | The same Stripe shared-token charge, carried by MCP |
+| x402 Base recorded into Stripe | **Yes** | Authenticated transaction-verification PaymentIntent; live CDP facilitator credentials; Stripe-approved deposit address |
+| Dynamic Checkout Sessions, direct refunds, provider-read recovery | **Yes** | Stripe API access for those operations |
+
+Stripe's [MPP guide](https://docs.stripe.com/payments/machine/mpp) initializes the Stripe client with a secret credential. Its [x402 guide](https://docs.stripe.com/payments/machine/x402) separates the on-chain facilitator settlement from authenticated PaymentIntent recording. **x402 itself does not require a Stripe API key**; this supported path records money into the seller's Stripe books as Stripe documents. The keyless Payment Link path uses [signed webhooks](https://docs.stripe.com/webhooks) instead of provider reads. CLI OAuth is not exported as a Worker REST credential; see [the setup research](../../../docs/stripe-connect-research.md).
+
+For a fuller connection, the AI operates Stripe's [key-creation page](https://docs.stripe.com/keys), selects the necessary permissions and clicks Copy, then runs `shop connect --from-clipboard` (`--live` for live mode). The local command privately reads the clipboard, verifies the key, makes the webhook and writes secrets to Wrangler stdin, then clears the clipboard. **The human only handles provider sign-in, verification or approval prompts**; their count is controlled by Stripe. Never ask the person to find or paste a key when browser control is available. No supported public API to mint a persistent Stripe REST credential from the CLI approval was established. On macOS this uses `pbpaste`/`pbcopy`, Windows its clipboard commands, and Linux Wayland `wl-paste`/`wl-copy`; other desktops require an equivalent private credential transport. The manual local form remains an explicit fallback, not the default instruction. Live CDP credentials likewise belong to the seller and should be transferred privately by the AI from the provider's setup; no Homie account is involved.
+
+Turnstile is optional. If the studio configures it, the fallback verifies its hostname and action. The per-address Worker rate limiter remains configurable flood protection. Machine payment proofs are verified by the protocol libraries.
+
+A release's bytes never change. `parts/offers.json` holds only price overrides and
+availability choices. Other terms come from the release being offered. Each accepted
+offer version stores the complete terms and price together. Earlier free copies cannot be recalled. `share: false` stops discovery
+and new checkout after deploy; R2 keeps paid releases for existing buyers. Do not
+remove purchased releases. Keep the packed files, D1 purchase records and signing key
+in the seller's backups. Run shop connect again after adding paid parts to register the additional
+subscription webhook events and permissions. Stripe's Dashboard must have its customer
+portal enabled for subscription management; refunds and cancellation are separate.
+
+## Buying and keeping the proof
+
+Requires studio **0.36.0**. Discovery uses `/.well-known/api-catalog`, linking
+`/parts/catalog.json`, `/purchases/keys.json`, the HTTP resource and MCP endpoints.
+The seller's public page and catalogue contain schema.org Product and Offer descriptions.
+
+The buyer sees the full offer and exact quote before approving payment. Set
+`HOMIE_PARTS_WALLET` to the person's installed `link-cli` or `purl` client.
+The tool calls the wallet, which owns all spending authority and limits. Link card spends
+currently require approval in the Link app. Retry the same purchase after that approval.
+A compatible funded crypto wallet can use its existing authority. No seller checkout
+page is involved in a successful protocol exchange.
+
+MPP uses Stripe shared payment tokens. Tempo is disabled. x402 exact uses Base
+payments to the studio's Stripe deposit address. Both return files, a payment receipt
+and signed purchase proof. MCP uses MPP's JSON-RPC challenge and receipt binding.
+Checkout remains the human fallback, and handles subscriptions, non-USD prices and final
+tax calculation. Managed Payments is a Checkout option; machine charges use the studio
+as seller. In fallback Checkout the person accepts the licence and presses Pay; an
+assistant must not submit acceptance with a browser tool.
+
+`shop connect` obtains the profile and stablecoin deposit addresses from Stripe and writes
+`PURCHASE_MACHINE_PAYMENTS` and a mode/key-bound `PURCHASE_PAYMENT_CAPABILITIES` record. It needs
+**PaymentIntents Write**, Business Profiles access, Payment Method Configurations reads and
+Crypto Deposit Addresses access, as well as the existing Checkout and webhook permissions.
+The fuller connection reports Stripe readiness errors. Connect and scheduled checks read the
+profile, enabled methods and existing deposit addresses. They create no provider objects.
+These reads establish configuration, not PaymentIntents Write permission, funded settlement
+or SPT eligibility. Real purchase outcomes update readiness. The scheduled check retries
+failures with backoff and rechecks successful configuration every six hours.
+Stablecoins still require Stripe approval; the office reports unavailable methods and the
+catalogue lists the available paths. Live Base additionally needs the studio's own
+`CDP_API_KEY_ID` and `CDP_API_KEY_SECRET`. The toolkit does not invent those credentials.
+
+At the documentation check on 2026-10-08, the Link wallet supports US and Canadian wallet accounts and a $500 spend-request
+limit. An x402 client's default spend control can be $1 per payment; the wallet owner decides
+whether to change it. These are provider/client constraints, not studio pricing limits.
+`part_add` also accepts a `wallet` argument. A failed token clears pending wallet approval. Explicit wallet refusals, missing wallet software,
+unsupported methods and unavailable machine paths offer a clearly labelled hosted Checkout fallback. An uncertain settlement must be reconciled before paying again.
+
+`/openapi.json`, linked as `service-desc` from the API catalogue, publishes each offer's
+request schema and `x-payment-info`. Buyers can submit the published `offerVersion`.
+Challenges bind to the server hostname and an individual purchase resource URL. Unpaid
+machine orders and challenges last five minutes; reprice, withdrawal and retirement close
+old unpaid offers. The limiter applies before protected R2 file reads too.
+
+Verified stablecoin settlements grant access even while Stripe recording is unavailable.
+`purchase_jobs` retains the recording parameters and transaction reference. A five-minute
+cron and on-demand order refresh retry recordings and re-read processing PaymentIntents.
+If paid files cannot be restored, the owner must refund the order manually. Maintenance never
+refunds for a storage outage. Every five minutes it reads unresolved Stripe objects and retries
+delivery availability. The owner can run the same recovery with
+`POST /_studio/api/shop/reconcile-payments` and an optional `order` identifier; buyers retrying
+their purchase also trigger this read. Existing payment facts and order identifiers are retained
+for late webhooks. Authentication, permission and idempotency errors are not charge refusals.
+After 23 hours, no charge is replayed. Reads continue: a paid object is recorded; a canceled or
+unpaid object releases the claim. An exhausted complete list after the deadline also releases
+the claim while keeping its order. If Stripe remains unreadable, the office shows the order,
+request key, recorded PaymentIntent (if known), age and last error. Reconnect the key and use
+Reconcile payments now. If you have the exact PaymentIntent id, use Read this payment beside
+the recovery row (or pass `payment` and `order` to the same endpoint). Its order metadata must
+match. Use the normal refund action once Stripe confirms payment; an unpaid canceled object
+releases the claim. Never infer no charge from an API error.
+
+An explicit sandbox readiness check is available through
+`POST /_studio/api/shop/readiness`. It reads current configuration without creating any provider object, order, entitlement or refund. Failures expire after five minutes;
+success expires after six hours. The report records the check time and its limited scope.
+Scheduled capability checks are read-only, at most four successful checks per day, with
+backoff after failure. No extra permissions or checks apply to a shop without paid releases.
+
+Paid objects live under `paid-parts/` in the private `PURCHASE_MEDIA` bucket, separate from
+public `MEDIA`. Deployment creates that bucket, deploys the guarded Worker, then uploads and
+verifies the files. Failure before deployment uploads nothing. An older public Worker has no
+binding to those objects. Public routes also refuse the prefix if it is bound accidentally.
+
+The studio can tune `PURCHASE_RATE_LIMITER` in its Wrangler configuration; deployment keeps
+that binding’s chosen limit and period. It is an abuse control, not a spending allowance.
+
+Stripe can initiate Managed Payments refunds within 60 days in certain cases, including
+support escalations left unanswered for 48 hours, and can accept disputes. A customer’s
+data-deletion request cancels their Managed Payments subscriptions. These are Stripe’s
+rules, described in its [Managed Payments guide](https://docs.stripe.com/payments/managed-payments/how-it-works).
+Provider reconciliation observes refunds and cancellation regardless of who requested them.
+
+## Seller settings and recovery
+
+`part.json.sale` supplies terms for each immutable release. `parts offer <id> --amount`
+sets only a persistent price override. Other terms change with a new release. Offers are
+versioned from all terms, resource and price; a buyer keeps the version they purchased.
+The build does not write `parts/offers.json`. Only the newest release sells by default;
+`--release <version> --keep-on-sale` retains an older release. Release settings merge,
+so adding an included upgrade does not silently withdraw an older release.
+
+`--withdraw` closes new sales; `--on-sale` explicitly reopens an offer. Deployment expires
+obsolete open Checkout sessions. A completed payment is honored even if its webhook
+arrives after withdrawal or another release. `parts retire` closes sales and cancels
+future subscription billing, preserving already-paid periods. `--upgrade included` may
+add rights; changing it back cannot revoke promised or already-granted releases.
+
+`intentMinutes` is 30–1440 and controls the approval intent before Checkout. Stripe chooses
+the Checkout Session's default expiration, keeping retry parameters stable. Download
+credentials last five minutes. Reconciliation happens once per grant rather than per file.
+The studio can configure its abuse rate limit; it is not a spending cap.
+
+`refundWindowDays` enables buyer self-service refunds when present and positive. It counts
+from the current payment's paid timestamp, including renewals. Otherwise ask the seller.
+`refundEndsSubscription` cancels future billing only after a successful full refund.
+Pending or failed refunds keep billing intact. Credit-only invoices have no charge to refund.
+`immediateDelivery: true` adds the consumer immediate-delivery acknowledgement beside Pay;
+the seller chooses it to match its full licence and obligations.
+
+A public test-card payment gets no protected files until the owner identifies the order
+and runs `parts test-access <order>`. This authorizes that claim only while the shop remains
+in test mode. Reissue needs new approval. Never approve an unknown test buyer. Use a second
+studio for tests: one Worker has one Stripe key/mode, and switching a live shop to test
+interrupts its live buyers. A grant or proof from test never becomes a live purchase.
+
+Claims, download tokens and pristine backups live in `.homie/paid-parts`, outside public
+source. Back them up privately. A long-lived Ed25519 proof cannot download; a short-lived
+grant can. Updates derive from the purchased licence. A verified backup restores offline;
+new delivery and updates require the seller to remain reachable. There is no project escrow.
+
+If a claim is lost, `parts recover <seller>/<part> --order <order>` generates a new private
+claim and public claim hash. Give the hash and Stripe receipt to the seller. The seller
+matches the payer/receipt in Stripe and runs `parts reissue <order> --claim-hash <hash>
+--receipt-verified`. Never pass `--receipt-verified` on the assistant's own word. Reissue
+revokes the former claim and downloads. An order ID alone proves nothing. A healthy local
+claim cannot be overwritten by recovery. Transfer requires the purchased terms to allow it.
+
+`parts manage` creates a fresh Stripe portal session. Without a local record, a seller's
+configured `purchasesPortalLogin` lets Stripe authenticate the buyer and provide billing and
+receipt access for assisted recovery. Run refunds only when requested by the person.
+
+Paid resource setup uses the `shop connect` page for `TURNSTILE_SITE_KEY` and
+`TURNSTILE_SECRET` (hosted fallback), and `CDP_API_KEY_ID` and `CDP_API_KEY_SECRET`
+(live Base). Machine and fallback readiness are independent. Base is an explicit choice
+with manual refund responsibility; Tempo is disabled. If Stripe cannot record a settled
+Base transfer, the office names the payer, token, atomic amount and transaction. Send any
+owed refund from the studio's own wallet and use `shop refund <order> --manual-transaction
+<hash>` to verify and record it after owner confirmation. Missing storage never authorizes
+an automatic refund. Configure the studio's own Base RPC in purchase settings for recovery.
+
+The recovery status `fulfilled` means the purchased files are available and the entitlement
+has been issued; it is not proof that the buyer downloaded them. An unpaid challenge retains
+a five-minute quote row so a retry uses the same terms and the owner can grant test access.
+It creates no provider object. Cleanup removes that row only if no provider or settlement job
+was ever attached. A paid order whose files cannot be restored needs an owner's manual refund.

package/worker/extensions.mjs

@@ -0,0 +1,13 @@
+/** Optional selling integration. Only the selling entry installs provider adapters. */
+export const selling = {
+  enabled: false,
+  machineCapabilities: () => ({ machine: {} }),
+  priceWords: () => 'Free',
+  purchaseRoutes: () => null,
+  purchasePaymentEvent: () => null,
+  resourceOrder: () => null,
+  listOffers: () => [],
+  paidFile: () => new Response('not found', { status: 404 }),
+  jobsSQL: () => '0',
+};
+export function useSelling(adapters) { Object.assign(selling, adapters); }

package/worker/index.mjs

@@ -346,6 +346,7 @@ function etagMatches(header, etag) {
  * object stored without one.
  */
 async function mediaObject(request, env, key, { cache = 'public, max-age=3600', type = null } = {}) {
+  if (key.startsWith('paid-parts/')) return new Response('not found', { status: 404 });
   const range = request.headers.get('range');
   const inm = request.headers.get('if-none-match');
   const headOnly = request.method === 'HEAD';
@@ -399,7 +400,7 @@ async function heldInR2(env, getCat, path) {
   try { want = decodeURIComponent(path); } catch { return null; }
   for (const e of [...(cat.songs ?? []), ...(cat.videos ?? [])]) {
     for (const f of e.files ?? []) {
-      if (typeof f.r2 !== 'string' || !f.r2 || f.r2.startsWith('players/') || typeof f.url !== 'string') continue;
+      if (typeof f.r2 !== 'string' || !f.r2 || (f.r2.startsWith('players/') || f.r2.startsWith('paid-parts/')) || typeof f.url !== 'string') continue;
       let at;
       try { at = decodeURIComponent(f.url); } catch { continue; }
       if (at === want) return f;
@@ -749,7 +750,7 @@ async function route(request, env, ctx) {
     if (!env.MEDIA) return new Response('this studio keeps no media in R2 yet', { status: 404 });
     const key = decodeURIComponent(path.slice('/media/'.length));
     // A player's large saves live under players/ in the same bucket: never served here (saves/SAVES.md).
-    if (!key || key.includes('..') || key.startsWith('players/')) return new Response('not found', { status: 404 });
+    if (!key || key.includes('..') || (key.startsWith('players/') || key.startsWith('paid-parts/'))) return new Response('not found', { status: 404 });
     return mediaObject(request, env, key);
   }
   if (path === '/posts/feed.xml' || path === '/posts/feed.json') {

package/worker/machine-payments.mjs

@@ -0,0 +1,72 @@
+import { journalFacilitator, rpcFor } from './settlement-journal.mjs';
+import { machineCapabilities } from './payment-capabilities.mjs';
+/** Standards adapters: the libraries own challenges, credentials and settlement. */
+import Stripe from "stripe";
+import { Mppx, stripe, Transport } from "mppx/server";
+import { HTTPFacilitatorClient } from "@x402/core/server";
+import { createFacilitatorConfig } from "@coinbase/x402";
+import { paymentStore } from "./purchase-core.mjs";
+import { digest } from "./purchase-crypto.mjs";
+
+import { modeOf, apiBase } from "./stripe.mjs";
+
+export function stripeClient(env) {
+  const base = new URL(apiBase(env));
+  return new Stripe(env.STRIPE_KEY, {
+    httpClient: Stripe.createFetchHttpClient(),
+    host: base.hostname,
+    port: base.port ? Number(base.port) : undefined,
+    protocol: base.protocol.slice(0, -1),
+  });
+}
+
+export async function paymentProtocol(
+  env,
+  order,
+  { mcp = false, client, facilitator, realm, capabilities, chainRpc } = {},
+) {
+  const mode = modeOf(env.STRIPE_KEY);
+  const config = JSON.parse(env.PURCHASE_MACHINE_PAYMENTS ?? "{}")[mode];
+  if (!config?.profile)
+    throw new Error("Configure the studio Stripe profile for machine payments");
+  client ??= stripeClient(env);
+  const payments = stripe.create({
+    client,
+    networkId: config.profile,
+    livemode: mode === "live",
+    metadata: { homie: "purchase-v1", order: order.id },
+    store: paymentStore(env.DB, mode),
+  });
+  capabilities ??= await machineCapabilities(env);
+  let methods = capabilities.machine.card ? [payments.spt.charge()] : [];
+  if (config.base && capabilities.machine.base && !mcp) {
+    facilitator ??= new HTTPFacilitatorClient(
+      mode === "live"
+        ? createFacilitatorConfig(env.CDP_API_KEY_ID, env.CDP_API_KEY_SECRET)
+        : { url: "https://x402.org/facilitator" },
+    );
+    methods = [
+      ...methods,
+      payments.base.charge({
+        recipient: config.base,
+        x402: { facilitator: journalFacilitator(env, order, facilitator, chainRpc ?? rpcFor(env, 'base', mode)), routeBinding: "resource" },
+      }),
+    ];
+  }
+  methods = methods.map((method) => {
+    // mppx's two-phase methods call broadcast after validate; card methods use
+    // verify. Capture the bound challenge before either terminal operation.
+    const operation = method.broadcast ? 'broadcast' : 'verify';
+    return { ...method, async [operation](context) {
+      order.challengeId = context.credential.challenge.id;
+      return method[operation](context);
+    } };
+  });
+  const protocol = Mppx.create({
+    methods,
+    realm,
+    secretKey: await digest(`${env.STRIPE_KEY}:purchase-payment-challenges`),
+    ...(mcp ? { transport: Transport.mcpSdk() } : {}),
+  });
+  return protocol;
+}

package/worker/office.mjs

@@ -1,3 +1,5 @@
+import { selling } from './extensions.mjs';
+import { purchaseOrderIfPresent } from './shop.mjs';
 /**
  * THE STUDIO'S BACK OFFICE (@homie-rocks/studio 0.13.0): the studio's owner, and the owner's AI, see and run the
  * studio's live games. Everything lives in the studio's own Worker and D1; homie.rocks stores none of it.
@@ -1255,6 +1257,7 @@ async function api(request, env, url, cat) {
     return lounge ? json({ ok: true, lounge }) : json({ ok: false, error: 'no-lounge', message: 'This studio has no Lounge: add "lounge": true to studio.json and deploy.' }, 404);
   }
   // The shop (0.24.0): the owner's view, the accountant's CSV, the referral statements.
+  if (selling.enabled) { const result = await selling.officeRoutes(request, env, path, body); if (result) return result; }
   if (path === '/_studio/api/shop' && request.method === 'GET') return json(await shopOffice(env, cat, url.origin, url.searchParams.get('cursor') ?? '', /^\d+$/.test(url.searchParams.get('itemCursor') ?? '') ? Number(url.searchParams.get('itemCursor')) : 0, /^\d+$/.test(url.searchParams.get('orderCursor') ?? '') ? Math.min(Number(url.searchParams.get('orderCursor')), Number.MAX_SAFE_INTEGER) : 0));
   if (path === '/_studio/api/shop/orders.csv' && request.method === 'GET') {
     try {
@@ -1283,7 +1286,7 @@ async function api(request, env, url, cat) {
   if (op === 'server-create' || op === 'pass' || op === 'lounge-night') action.origin = url.origin;
   if (op === 'refund') {
     // The ask and the confirm page say what the order is (its item and price), read from the books now.
-    const o = await orderById(env, action.order);
+    const o = await orderById(env, action.order) ?? await purchaseOrderIfPresent(env, action.order);
     if (!o) return json({ ok: false, error: 'order', message: 'No such order (homie-studio shop orders lists them).' }, 404);
     Object.assign(action, { item: o.item, amount: Number(o.amount), currency: o.currency });
   }

package/worker/parts-protected.mjs

@@ -0,0 +1,111 @@
+import { hasStripeKey, shopMode } from './shop-links.mjs';
+/** 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 { legalTerms, objectKey, publicFiles } from "./parts-sale.mjs";
+
+import {
+  json,
+  fail,
+  byId,
+  bearer,
+  purchasedResource,
+  active,
+  privateRelease,
+  coveredPurchase,
+  deliveryAllowed,
+} from "./purchase-store.mjs";
+/** Protected content is never in ASSETS; withdrawn releases remain reachable by their buyer. */
+export async function paidFile(...args) {
+  try {
+    return await servePaidFile(...args);
+  } catch {
+    return fail(
+      503,
+      "Purchase service temporarily unavailable. Retry with the same download credential.",
+    );
+  }
+}
+async function servePaidFile(
+  request,
+  env,
+  url,
+  id,
+  version,
+  path,
+  type = "application/octet-stream",
+) {
+  if (!env.PURCHASE_MEDIA) return null;
+  if (!env.PURCHASE_RATE_LIMITER) return fail(503, 'Deploy the purchase rate limiter');
+  if (!(await env.PURCHASE_RATE_LIMITER.limit({ key: `files:${request.headers.get('cf-connecting-ip') ?? 'unknown'}` })).success) return fail(429, 'Too many file requests; retry shortly');
+  const p = await privateRelease(env, 'part', id, version);
+  if (!p?.sale) return null;
+  const f = p.files.find((f) => f.path === path);
+  if (path !== "part.json" && !f) return fail(404, "No such file");
+  if (path === "part.json" || publicFiles(p).has(path)) {
+    if (path === "part.json") return json(p);
+    const obj = await env.PURCHASE_MEDIA.get(objectKey(f.sha256));
+    return obj
+      ? new Response(request.method === "HEAD" ? null : obj.body, {
+          headers: {
+            "content-type": type,
+            "access-control-allow-origin": "*",
+            "content-security-policy":
+              "sandbox allow-scripts allow-pointer-lock",
+            "cache-control": "public, max-age=31536000, immutable",
+            "x-content-type-options": "nosniff",
+          },
+        })
+      : fail(503, "File missing from storage");
+  }
+  let claims;
+  try {
+    for (const key of await publicKeys(env)) {
+      try {
+        claims = await verifyGrant(bearer(request), key, {
+          issuer: url.origin,
+          resource: id,
+          kind: 'part',
+          version,
+        });
+        break;
+      } catch {
+        /* retained verification key */
+      }
+    }
+  } catch {
+    return fail(503, "Seller signing keys unavailable");
+  }
+  if (!claims) return fail(402, "Buy this part before downloading its files");
+  const o = await byId(env, claims.jti);
+  const core = o && (await orderState(env, o.id));
+  if (
+    !o || o.resource_kind !== 'part' ||
+    !(await deliveryAllowed(env, o)) ||
+    !active(o) ||
+    (core && !["paid", "fulfilled", "disputed"].includes(core.state)) ||
+    o.buyer !== claims.sub ||
+    o.claim_hash !== claims.claimVersion ||
+    o.mode !== claims.mode ||
+    !(await coveredPurchase(env, url.origin, o, p)) ||
+    claims.manifest !== (await manifestHash(p))
+  )
+    return fail(403, "This purchase does not permit this download");
+  const obj = await env.PURCHASE_MEDIA.get(objectKey(f.sha256));
+  if (!obj) return fail(503, "File missing from storage");
+  return new Response(request.method === "HEAD" ? null : obj.body, {
+    headers: {
+      "content-type": "application/octet-stream",
+      "cache-control": "no-store, private",
+      "x-content-type-options": "nosniff",
+      "content-security-policy": "sandbox",
+    },
+  });
+}

package/worker/parts-purchase-catalogue.mjs

@@ -0,0 +1,34 @@
+import { selling } from './extensions.mjs';
+import { partsIndex } from './parts.mjs';
+const CORS = { 'access-control-allow-origin': '*', 'x-content-type-options': 'nosniff' };
+export function productDescription(p, origin) {
+  const sale = p.sale;
+  const digits = sale ? new Intl.NumberFormat('en', { style: 'currency', currency: sale.currency }).resolvedOptions().maximumFractionDigits : 2;
+  return { '@context': 'https://schema.org', '@type': 'Product', name: p.name, description: p.summary, url: `${origin}/parts/${p.id}/`, ...(p.preview?.image ? { image: new URL(`${p.url}${p.preview.image}`, origin).href } : {}), ...(sale ? { offers: { '@type': 'Offer', price: (sale.amount / 10 ** digits).toFixed(digits), priceCurrency: sale.currency.toUpperCase(), url: `${origin}/parts/${p.id}/`, availability: p.releases?.some((r) => r.onSale) ? 'https://schema.org/InStock' : 'https://schema.org/Discontinued', ...(sale.billing !== 'one-time' ? { priceSpecification: { '@type': 'UnitPriceSpecification', price: (sale.amount / 10 ** digits).toFixed(digits), priceCurrency: sale.currency.toUpperCase(), billingDuration: ({day:'P1D',week:'P1W',month:'P1M',year:'P1Y'})[sale.billing], unitText: sale.scope } } : {}), description: `${sale.billing}; per ${sale.scope}; ${sale.refund}` } } : { offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD', availability: 'https://schema.org/InStock', url: `${origin}/parts/${p.id}/` } }) };
+}
+
+export function entryDescription(p,cat,url,capabilities) { return {
+    product: productDescription(p, url.origin),
+    purchase: { methods: (cat.shop?.purchasesTill ?? cat.shop?.till) !== 'stripe-managed' && p.sale?.amount > 0 && p.sale?.billing === 'one-time' && p.sale?.currency === 'usd' && !p.sale?.automaticTax && p.sale?.taxBehavior !== 'exclusive' ? Object.entries(capabilities.machine).filter(([, enabled]) => enabled).map(([method]) => method) : [], hostedCheckout: { url: `${url.origin}/api/purchases/intent`, label: 'Hosted Checkout fallback' }, http: `${url.origin}/api/purchases/resource`, mcp: `${url.origin}/api/purchases/mcp`, keys: `${url.origin}/purchases/keys.json` },
+}; }
+export async function discoveryRoutes(request, env, url, { catalogueOf }) {
+const path=url.pathname;
+  if (path === '/purchases/keys.json') return selling.purchaseRoutes(request, env, url, {});
+  if (path === '/openapi.json') {
+
+    return selling.purchaseDiscovery(env, url.origin, await catalogueOf());
+  }
+  const read = request.method === 'GET' || request.method === 'HEAD';
+  if (path === '/.well-known/api-catalog') {
+    if (!read) return new Response(null, { status: 405, headers: { allow: 'GET, HEAD' } });
+    const headers = { 'content-type': 'application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"', link: `<${url.origin}/.well-known/api-catalog>; rel="api-catalog"`, ...CORS };
+    const index = await partsIndex(env, url.origin);
+    const item = [{ href: `${url.origin}/parts/catalog.json`, type: 'application/json', title: 'Resources' }];
+    if (index.parts.some((p) => p.releases?.some((r) => r.onSale))) {
+      item.push({ href: `${url.origin}/api/purchases/mcp`, title: 'Purchases over MCP' });
+      if (env.PURCHASE_SIGNING_KEYS) item.push({ href: `${url.origin}/purchases/keys.json`, type: 'application/jwk-set+json', title: 'Purchase verification keys' });
+    }
+    return new Response(request.method === 'HEAD' ? null : JSON.stringify({ linkset: [{ anchor: `${url.origin}/.well-known/api-catalog`, 'service-desc': [{ href: `${url.origin}/openapi.json`, type: 'application/vnd.oai.openapi+json' }], item }] }), { headers });
+  }
+return null;
+}

package/worker/parts-resource.mjs

@@ -0,0 +1,32 @@
+/** A published part release is one purchasable resource kind. */
+import { quoteHash, legalTerms, coversRelease, compareVersions, saleProblems, objectKey, releaseKey } from "./parts-sale.mjs";
+export const partResource = Object.freeze({
+  async list(env, origin) {
+    const response = await env.ASSETS.fetch(new Request(`${origin}/parts/index.json`));
+    if (!response.ok) return [];
+    return ((await response.json()).parts ?? []).flatMap((p) => (p.releases ?? []).filter((r) => r.onSale && r.offer).map((r) => ({ id:p.id, name:p.name, version:r.version, offer:r.offer, offerVersion:r.offerVersion })));
+  },
+  async get(env, id, version) {
+    const object = await env.PURCHASE_MEDIA?.get(releaseKey(id,version));
+    return object ? object.json() : null;
+  },
+  quote: quoteHash,
+  terms: legalTerms,
+  validate(resource, selection) {
+    const errors = saleProblems(resource);
+    if (!selection) return errors;
+    const { quantity, game } = selection;
+    if (!Number.isSafeInteger(quantity) || quantity < 1 || !Number.isSafeInteger(quantity * resource.sale.amount)) errors.push('Invalid quantity');
+    if ((resource.sale.scope === 'game' && !/^[a-z0-9][a-z0-9-]{0,47}$/.test(game ?? '')) || (resource.sale.scope !== 'game' && game != null)) errors.push('Invalid game scope');
+    return errors;
+  },
+  termsUrl: (resource) => `/parts/${encodeURIComponent(resource.id)}/${encodeURIComponent(resource.version)}/${resource.licenseTerms.split('/').map(encodeURIComponent).join('/')}`,
+  readFile: (env,file,{head=false}={}) => head && env.PURCHASE_MEDIA?.head ? env.PURCHASE_MEDIA.head(objectKey(file.sha256)) : env.PURCHASE_MEDIA?.get(objectKey(file.sha256)),
+  async covers(env,origin,bought,wanted) {
+    if (coversRelease(bought,wanted)) return true;
+    const response = await env.ASSETS.fetch(new Request(`${origin}/parts/index.json`));
+    if (!response.ok) return false;
+    const release = (await response.json()).parts?.find((p)=>p.id===wanted.id)?.releases?.find((r)=>r.version===wanted.version);
+    return compareVersions(wanted.version,bought.version)>=0 && release?.upgrade==='included';
+  },
+});