@homie-rocks/studio 0.37.1 → 0.38.0

package/starters/gem-rush/tunables.json

@@ -1,13 +1,100 @@
 {
-  "knockRange": { "value": 110, "min": 60, "max": 200, "step": 1, "unit": "px", "group": "Knock", "note": "How near a body must be for a wave to bump it" },
-  "hitStopMs": { "value": 70, "min": 0, "max": 200, "step": 5, "unit": "ms", "group": "Knock", "note": "The hit lands: the bumped body holds, squashed and shaking, before it flies" },
-  "knockDistance": { "value": 185, "min": 40, "max": 400, "step": 5, "unit": "px", "group": "Knock", "note": "How far a bump sends a body, the same at any frame rate" },
-  "knockMs": { "value": 420, "min": 120, "max": 1000, "step": 10, "unit": "ms", "group": "Knock", "note": "How long the slide takes" },
-  "knockEase": { "value": 4, "min": 1, "max": 6, "step": 0.1, "group": "Knock", "note": "1 slides at one speed; higher leaves faster and eases into the stop" },
-  "squash": { "value": 0.35, "min": 0, "max": 0.8, "step": 0.01, "group": "Body", "note": "How much a flying body stretches along the hit, and squashes when it stops" },
-  "settleMs": { "value": 260, "min": 0, "max": 700, "step": 10, "unit": "ms", "group": "Body", "note": "The wobble after the stop (overlap)" },
-  "flashMs": { "value": 110, "min": 0, "max": 300, "step": 5, "unit": "ms", "group": "Hit", "note": "How long the bumped body flashes white" },
-  "shake": { "value": 7, "min": 0, "max": 24, "step": 0.5, "unit": "px", "group": "Hit", "note": "The camera's kick when you bump or are bumped" },
-  "sparks": { "value": 9, "min": 0, "max": 24, "step": 1, "group": "Hit", "note": "Sparks thrown off the hit" },
-  "ringMs": { "value": 900, "min": 200, "max": 2000, "step": 10, "unit": "ms", "group": "Wave", "note": "How long a wave's ring lasts" }
+  "public": {
+    "knockRange": {
+      "value": 2.2,
+      "min": 1.2,
+      "max": 4.0,
+      "step": 0.02,
+      "unit": "m",
+      "group": "Knock",
+      "note": "How near a body must be for a wave to bump it"
+    },
+    "hitStopMs": {
+      "value": 70,
+      "min": 0,
+      "max": 200,
+      "step": 5,
+      "unit": "ms",
+      "group": "Knock",
+      "note": "The hit lands: the bumped body holds, squashed and shaking, before it flies"
+    },
+    "knockDistance": {
+      "value": 3.7,
+      "min": 0.8,
+      "max": 8.0,
+      "step": 0.1,
+      "unit": "m",
+      "group": "Knock",
+      "note": "How far a bump sends a body, the same at any frame rate"
+    },
+    "knockMs": {
+      "value": 420,
+      "min": 120,
+      "max": 1000,
+      "step": 10,
+      "unit": "ms",
+      "group": "Knock",
+      "note": "How long the slide takes"
+    },
+    "knockEase": {
+      "value": 4,
+      "min": 1,
+      "max": 6,
+      "step": 0.1,
+      "group": "Knock",
+      "note": "1 slides at one speed; higher leaves faster and eases into the stop"
+    },
+    "squash": {
+      "value": 0.35,
+      "min": 0,
+      "max": 0.8,
+      "step": 0.01,
+      "group": "Body",
+      "note": "How much a flying body stretches along the hit, and squashes when it stops"
+    },
+    "settleMs": {
+      "value": 260,
+      "min": 0,
+      "max": 700,
+      "step": 10,
+      "unit": "ms",
+      "group": "Body",
+      "note": "The wobble after the stop (overlap)"
+    },
+    "flashMs": {
+      "value": 110,
+      "min": 0,
+      "max": 300,
+      "step": 5,
+      "unit": "ms",
+      "group": "Hit",
+      "note": "How long the bumped body flashes white"
+    },
+    "shake": {
+      "value": 7,
+      "min": 0,
+      "max": 24,
+      "step": 0.5,
+      "unit": "px",
+      "group": "Hit",
+      "note": "The camera's kick when you bump or are bumped"
+    },
+    "sparks": {
+      "value": 9,
+      "min": 0,
+      "max": 24,
+      "step": 1,
+      "group": "Hit",
+      "note": "Sparks thrown off the hit"
+    },
+    "ringMs": {
+      "value": 900,
+      "min": 200,
+      "max": 2000,
+      "step": 10,
+      "unit": "ms",
+      "group": "Wave",
+      "note": "How long a wave's ring lasts"
+    }
+  }
 }

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';
+  },
+});

package/worker/parts-sale.mjs

@@ -0,0 +1,59 @@
+import { amountError } from './shop-rules.mjs';
+import { digest, manifestHash } from "./purchase-crypto.mjs";
+/** Paid-part metadata shared by the builder, buyer and Worker. No payment policy ceilings. */
+import { canonicalJson } from './referrals.mjs';
+
+export const quoteHash = async (part, quantity = 1, game = null, offer = part.sale) => digest(canonicalJson({ manifest: await manifestHash(part), part: part.id, release: part.version, scope: offer.scope, quantity, game, interval: offer.billing, currency: offer.currency, amount: offer.amount * quantity, offer }));
+export const legalTerms = (p) => ({ license: p.license, terms: p.files?.find((f) => f.path === p.licenseTerms)?.sha256, scope: p.sale?.scope, source: p.sale?.source, commercialUse: p.sale?.commercialUse, transferable: p.sale?.transferable, onRefund: p.sale?.onRefund, onExpiry: p.sale?.onExpiry, refund: p.sale?.refund, updates: p.sale?.updates });
+export const sameTerms = (a, b) => canonicalJson(legalTerms(a)) === canonicalJson(legalTerms(b));
+export const publicFiles = (p) => new Set([p.preview?.page, p.preview?.image, p.licenseTerms, ...(p.files ?? []).filter((f) => /^LICENSES\/[^/]+\.txt$/.test(f.path)).map((f) => f.path), ...(p.sale?.publicFiles ?? [])].filter(Boolean));
+export const objectKey = (hash) => `paid-parts/files/${hash}`;
+export const releaseKey = (id, version) => `paid-parts/releases/${id}/${version}.json`;
+
+export function saleProblems(p) {
+  if (p.sale === undefined) return [];
+  const s = p.sale; const errors = [];
+  if (!s || typeof s !== 'object' || Array.isArray(s)) return ['sale must be an object'];
+  const invalidAmount = amountError(s.amount, s.currency);
+  if (invalidAmount) errors.push(invalidAmount);
+  if (!Intl.supportedValuesOf('currency').map((v) => v.toLowerCase()).includes(s.currency) || /^(xau|xag|xpt|xpd|xxx|xts)$/.test(s.currency)) errors.push('currency must be a lower-case ISO currency code');
+  if (s.taxBehavior !== undefined && !['inclusive', 'exclusive', 'unspecified'].includes(s.taxBehavior)) errors.push('taxBehavior must be inclusive, exclusive or unspecified');
+  for (const key of ['immediateDelivery', 'automaticTax', 'adaptivePricing', 'promotionCodes', 'refundEndsSubscription', 'invoiceCreation', 'customerCreation', 'taxIdCollection']) if (s[key] !== undefined && typeof s[key] !== 'boolean') errors.push(`${key} must be true or false`);
+  if (s.refundWindowDays !== undefined && (!Number.isFinite(s.refundWindowDays) || s.refundWindowDays < 0)) errors.push('refundWindowDays must be a non-negative finite number');
+  if (s.renewalGraceMinutes !== undefined && (!Number.isFinite(s.renewalGraceMinutes) || s.renewalGraceMinutes < 0)) errors.push('renewalGraceMinutes must be a non-negative finite number');
+  if (s.intentMinutes !== undefined && (!Number.isFinite(s.intentMinutes) || s.intentMinutes <= 0)) errors.push('intentMinutes must be a positive finite number');
+  for (const [key, values] of Object.entries({ billing: ['one-time', 'day', 'week', 'month', 'year'], updates: ['none', 'major', 'all'], onRefund: ['retain', 'terminate'], onExpiry: ['retain', 'terminate'] })) if (!values.includes(s[key])) errors.push(`${key} must be ${values.join(', ')}`);
+  if (typeof s.scope !== 'string' || !s.scope.trim()) errors.push('scope must describe the licensed use');
+  for (const key of ['source', 'commercialUse', 'transferable']) if (typeof s[key] !== 'boolean') errors.push(`${key} must be true or false`);
+  if (typeof s.refund !== 'string' || !s.refund.trim()) errors.push('refund must state the seller refund terms');
+  if ((s.taxCode !== undefined || s.automaticTax === true) && !/^txcd_\d{8}$/.test(s.taxCode ?? '')) errors.push('taxCode must name the Stripe product tax code');
+  if (!p.licenseTerms || !p.files?.some((f) => f.path === p.licenseTerms)) errors.push('licenseTerms must name a hashed file containing the full licence');
+  if (s.publicFiles !== undefined && (!Array.isArray(s.publicFiles) || s.publicFiles.some((path) => !p.files?.some((f) => f.path === path)))) errors.push('publicFiles must list only hashed files deliberately offered before purchase');
+  return errors;
+}
+
+export function coversRelease(bought, wanted) {
+  if (bought.id !== wanted.id) return false;
+  if (bought.version === wanted.version) return true;
+  if (bought.version.includes('-') || wanted.version.includes('-')) return false;
+  if (compareVersions(wanted.version, bought.version) < 0) return false;
+  return bought.sale.updates === 'all' || (bought.sale.updates === 'major' && wanted.version.split('.')[0] === bought.version.split('.')[0]);
+}
+
+/** Semver precedence, including numeric versus text prerelease identifiers. */
+export function compareVersions(a, b) {
+  const parse = (v) => { const dash = v.indexOf('-'); const core = dash < 0 ? v : v.slice(0, dash); const pre = dash < 0 ? undefined : v.slice(dash + 1); return { core: core.split('.').map(Number), pre: pre?.split('.') }; };
+  const left = parse(a); const right = parse(b);
+  for (let i = 0; i < 3; i++) if (left.core[i] !== right.core[i]) return left.core[i] < right.core[i] ? -1 : 1;
+  if (!left.pre || !right.pre) return left.pre ? -1 : right.pre ? 1 : 0;
+  for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i++) {
+    const x = left.pre[i]; const y = right.pre[i];
+    if (x === y) continue;
+    if (x === undefined || y === undefined) return x === undefined ? -1 : 1;
+    const nx = /^\d+$/.test(x); const ny = /^\d+$/.test(y);
+    if (nx && ny) return Number(x) < Number(y) ? -1 : 1;
+    if (nx !== ny) return nx ? -1 : 1;
+    return x < y ? -1 : 1;
+  }
+  return 0;
+}

package/worker/parts.mjs

@@ -1,3 +1,5 @@
+import { selling } from './extensions.mjs';
+
 /**
  * THE STUDIO'S SHARED GAME PARTS, AS ITS SITE SERVES THEM (parts/PARTS.md section 4).
  *
@@ -17,7 +19,7 @@ const VERSION = /^\d{1,6}\.\d{1,6}\.\d{1,6}(?:-[0-9A-Za-z.-]{1,40})?$/;
 /** A packed part's files: framed by the part's own page and by the hub, so they keep their own frame rule (index.mjs finish). */
 export const PART_FILES = /^\/parts\/[a-z0-9][a-z0-9-]{0,47}\/\d{1,6}\.\d{1,6}\.\d{1,6}[^/]*\//;
 export const PARTS_WELL_KNOWN = '/.well-known/homie-parts.json';
-export const isPartsPath = (path) => path === PARTS_WELL_KNOWN || path === '/parts' || path.startsWith('/parts/');
+export const isPartsPath = (path) => path === '/openapi.json' || path === '/.well-known/api-catalog' || path === '/parts/catalog.json' || path === '/purchases/keys.json' || path === PARTS_WELL_KNOWN || path === '/parts' || path.startsWith('/parts/');
 
 const CORS = { 'access-control-allow-origin': '*', 'x-content-type-options': 'nosniff' };
 const json = (body, status = 200, headers = {}) => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json; charset=utf-8', ...headers } });
@@ -37,25 +39,29 @@ export async function partsIndex(env, origin) {
  * One index entry as the world sees it: how to add it, and the game it came out of with its page and Play address.
  * Only a PUBLIC game is named (a private or invite-only game's parts are still shared, without saying where from).
  */
-function entryOf(p, cat, url) {
+function entryOf(p, cat, url, capabilities = { machine: {} }) {
   const g = (p.from?.game ?? p.from?.app) ? (cat.games ?? []).find((x) => x.id === (p.from.game ?? p.from.app)) : null;
   const { from, ...rest } = p;
   return {
     ...rest,
-    ...(!g && from && (from.music || from.video) ? { from: { ...(from.music ? { music: from.music } : { video: from.video }), name: from.name ?? null, studio: from.studio ?? null } } : {}),
+    ...(!g && from && !from.game && !from.app ? { from } : {}),
     ...(g ? { from: { [g.kind === 'app' ? 'app' : 'game']: g.id, name: g.name ?? g.id, studio: cat.studio?.name ?? from.studio ?? null, page: `${url.origin}/${g.id}/`, [g.kind === 'app' ? 'open' : 'play']: `${url.origin}/${g.id}/${g.kind === 'app' ? 'open' : 'play'}` } } : {}),
     add: `${url.host}/${p.id}`,
+    ...(selling.entryDescription?.(p, cat, url, capabilities) ?? {}),
   };
 }
 
 export async function partsRoutes(request, env, url, { catalogueOf }) {
   const path = url.pathname;
+  if (!selling.enabled && ['/purchases/keys.json','/openapi.json','/.well-known/api-catalog'].includes(path)) return null;
+  if (selling.enabled) { const extra = await selling.discoveryRoutes(request, env, url, { catalogueOf }); if (extra) return extra; }
   const read = request.method === 'GET' || request.method === 'HEAD';
-  if (path === PARTS_WELL_KNOWN) {
+  if (path === PARTS_WELL_KNOWN || path === '/parts/catalog.json') {
     if (request.method === 'OPTIONS') return new Response(null, { status: 204, headers: { ...CORS, 'access-control-allow-methods': 'GET, HEAD' } });
     if (!read) return json({ ok: false, error: 'method' }, 405, { allow: 'GET, HEAD', ...CORS });
     const [index, cat] = await Promise.all([partsIndex(env, url.origin), catalogueOf()]);
-    return json({ v: 1, studio: { name: cat.studio?.name ?? index.studio?.name ?? null, url: url.origin }, parts: index.parts.map((p) => entryOf(p, cat, url)) }, 200, { ...CORS, 'cache-control': 'public, max-age=300' });
+    const capabilities = await selling.machineCapabilities(env);
+    return json({ v: 1, studio: { name: cat.studio?.name ?? index.studio?.name ?? null, url: url.origin }, parts: index.parts.map((p) => entryOf(p, cat, url, capabilities)) }, 200, { ...CORS, 'cache-control': 'public, max-age=300' });
   }
   const segs = path.split('/').filter(Boolean);
   // /parts/<id>/<version>/<file…>: a packed file, only when the index names that part and that version.
@@ -67,6 +73,9 @@ export async function partsRoutes(request, env, url, { catalogueOf }) {
     let file;
     try { file = segs.slice(3).map(decodeURIComponent).join('/'); } catch { file = '..'; }
     const gone = () => new Response('not found', { status: 404, headers: { ...CORS, 'cache-control': 'no-store' } });
+    if (file.split('/').some((s) => !s || s === '..' || s.startsWith('.')) || file.includes('\\')) return gone();
+    const protectedFile = part && !part.sale && !part.releases?.some((r) => r.version === segs[2] && r.sale) ? null : await selling.paidFile(request, env, url, segs[1], segs[2], file, TYPES[file.split('.').pop().toLowerCase()]);
+    if (protectedFile) return protectedFile;
     if (!part || !(part.versions ?? []).includes(segs[2]) || file.split('/').some((s) => !s || s === '..' || s.startsWith('.'))) return gone();
     const res = await env.ASSETS.fetch(new Request(`${url.origin}/parts/${segs[1]}/${segs[2]}/${file.split('/').map(encodeURIComponent).join('/')}`));
     if (!res.ok) return gone();
@@ -104,7 +113,7 @@ export async function partsRoutes(request, env, url, { catalogueOf }) {
 /* ------------------------------------------------------------------ the pages */
 
 const KIND_WORDS = { character: 'Character', rig: 'Rig', clips: 'Animation clips', environment: 'Environment', effect: 'Effect', sound: 'Sound', ui: 'UI', mechanic: 'Mechanic', shader: 'Shader', 'level-generator': 'Level generator', 'bot-brain': 'Bot brain', 'audio-pack': 'Audio pack', 'set-piece': 'Set piece' };
-const kindOf = (p) => KIND_WORDS[p.kind] ?? 'Part';
+const kindOf = (p) => KIND_WORDS[p.kind] ?? p.kind ?? 'Part';
 const CSS = `<style>
 .pgrid{display:grid;grid-template-columns:repeat(auto-fill,minmax(260px,1fr));gap:18px;margin:8px 0 0;padding:0;list-style:none}
 .pcard{display:flex;flex-direction:column;gap:8px;padding:18px;border:1px solid color-mix(in srgb,var(--fg) 14%,transparent);border-radius:16px;text-decoration:none;color:inherit;background:color-mix(in srgb,var(--fg) 3%,transparent)}
@@ -134,12 +143,12 @@ const head = (kicker, title, lead, extra = '') => `<header class="head"><p class
 const studioOf = (cat) => cat.studio?.name ?? 'Studio';
 const fromLine = (p) => ((p.from?.game ?? p.from?.app) ? `From <a href="/${esc((p.from.game ?? p.from.app))}/">${esc(p.from.name ?? (p.from.game ?? p.from.app))}</a>` : '');
 /** What a person says to their AI to get the part, in plain words with its name and reference: no command to type. */
-const sayAdd = (p) => `Add the "${p.name}" part from ${p.add} to my game`;
+const sayAdd = (p) => `Add the "${p.name}" part from ${p.add} to my studio`;
 const sayRow = (label, say) => `<div class="psay"><div><span class="ptag">${esc(label)}</span><code>${esc(say)}</code></div><button class="pcopy" type="button" data-copy="${esc(say)}">${icon('copy')}<span data-copy-word>Copy</span></button></div>`;
 
 function card(p) {
   const img = p.preview?.image ? `<img src="${esc(`${p.url}${p.preview.image}`)}" alt="" loading="lazy">` : '';
-  return `<li><a class="pcard" href="/parts/${esc(p.id)}/">${img}<span class="ptag">${esc(kindOf(p))} · ${esc(p.license ?? '')}</span><h3>${esc(p.name)}</h3><p>${esc(p.summary ?? '')}</p>${(p.from?.game ?? p.from?.app) ? `<p>From ${esc(p.from.name ?? (p.from.game ?? p.from.app))}</p>` : ''}</a></li>`;
+  return `<li><a class="pcard" href="/parts/${esc(p.id)}/">${img}<span class="ptag">${esc(kindOf(p))} · ${esc(p.license ?? '')} · ${esc(selling.priceWords(p.sale))}</span><h3>${esc(p.name)}</h3><p>${esc(p.summary ?? '')}</p>${(p.from?.game ?? p.from?.app) ? `<p>From ${esc(p.from.name ?? (p.from.game ?? p.from.app))}</p>` : ''}</a></li>`;
 }
 
 export function partsPage(cat, parts, url) {
@@ -149,7 +158,7 @@ export function partsPage(cat, parts, url) {
   for (const p of parts) { const k = (p.from?.game ?? p.from?.app) ?? ''; if (!groups.has(k)) groups.set(k, []); groups.get(k).push(p); }
   const body = [...groups].sort(([a], [b]) => (a === '' ? 1 : b === '' ? -1 : a.localeCompare(b))).map(([k, list]) => `<p class="sec"${k ? ` id="from-${esc(k)}"` : ''}>${k ? `From ${esc(list[0].from.name ?? k)}` : 'More parts'}</p><ul class="pgrid">${list.map(card).join('')}</ul>`).join('');
   return layout(cat, {
-    title: `Game parts · ${name}`, description: `Pieces of ${name}'s games that other studios can use in their own: creatures, levels, mechanics, sounds. Each with its licence.`, origin: url.origin, path: '/parts/', page: 'parts', head: CSS,
+    title: `Game parts · ${name}`, description: `Pieces of ${name}'s games that other studios can use in their own: creatures, levels, mechanics, sounds. Each with its licence.`, origin: url.origin, path: '/parts/', page: 'parts', head: CSS + (selling.enabled ? `<script type="application/ld+json">${JSON.stringify({ '@context': 'https://schema.org', '@type': 'ItemList', itemListElement: parts.map((p, i) => ({ '@type': 'ListItem', position: i + 1, item: productDescription(p, url.origin) })) }).replaceAll('<', '\\u003c')}</script>` : ''),
     main: `${head('Game parts', 'Take a piece, make a game', `Pieces of ${name}'s games, shared one by one. Take the creature from one game, the level from another and the bot brain from a third, and make something new. Each part says its licence and who to credit.`)}
 <div class="wrap">${body}</div>`,
   });
@@ -207,6 +216,8 @@ function previewOf(p) {
 <a class="popen" href="${src}" target="_blank" rel="noopener noreferrer">${icon('arrow')}<span>Open the preview in its own tab</span></a>`;
 }
 
+export const productDescription = (p, origin) => selling.productDescription?.(p, origin);
+
 export function partPage(cat, p, url) {
   const name = studioOf(cat);
   const preview = p.preview?.page
@@ -216,6 +227,8 @@ export function partPage(cat, p, url) {
     ['Kind', esc(kindOf(p))],
     p.uses?.length ? ['For', esc(p.uses.join(', '))] : null,
     (p.from?.game ?? p.from?.app) ? [p.from.app ? 'From the app' : 'From the game', `<a href="/${esc((p.from.game ?? p.from.app))}/">${esc(p.from.name ?? (p.from.game ?? p.from.app))}</a> · <a href="/${esc((p.from.game ?? p.from.app))}/${p.from.app ? 'open' : 'play'}">${p.from.app ? 'Open it' : 'Play it'}</a>`] : null,
+    ['Price', esc(selling.priceWords(p.sale))],
+    p.sale ? ['Purchase terms', esc(`${p.sale.refund} Source: ${p.sale.source ? 'included' : 'not included'}. Updates: ${p.sale.updates}.`)] : null,
     ['Licence', `${esc(p.license ?? 'none named')}${p.license && !/^LicenseRef-/.test(p.license) ? ` · <a href="https://spdx.org/licenses/${esc(p.license)}.html" rel="noopener">what it allows</a>` : ''}`],
     p.attribution ? ['Credit', esc(p.attribution)] : null,
     ['Version', `${esc(p.version)}${(p.versions ?? []).length > 1 ? ` (also ${esc(p.versions.filter((v) => v !== p.version).join(', '))})` : ''}`],
@@ -228,7 +241,7 @@ export function partPage(cat, p, url) {
     (p.tags ?? []).length ? ['Tags', esc(p.tags.join(', '))] : null,
   ].filter(Boolean);
   return layout(cat, {
-    title: `${p.name} · a game part from ${name}`, description: `${p.summary ?? ''} A ${kindOf(p).toLowerCase()} from ${name}${p.from?.name ? `'s ${p.from.name}` : ''}, shared under ${p.license ?? 'its own terms'}.`.trim(), origin: url.origin, path: `/parts/${p.id}/`, page: 'part', head: CSS,
+    title: `${p.name} · a game part from ${name}`, description: `${p.summary ?? ''} A ${kindOf(p).toLowerCase()} from ${name}${p.from?.name ? `'s ${p.from.name}` : ''}, shared under ${p.license ?? 'its own terms'}.`.trim(), origin: url.origin, path: `/parts/${p.id}/`, page: 'part', head: CSS + (selling.enabled ? `<script type="application/ld+json">${JSON.stringify(productDescription(p, url.origin)).replaceAll('<', '\\u003c')}</script>` : ''),
     image: p.preview?.image ? `${p.url}${p.preview.image}` : null,
     main: `${head(`${kindOf(p)} · shared part`, p.name, p.summary ?? '', `<div class="keys"><a class="ghost" href="/parts/">${icon('arrow')}<span>All parts</span></a>${(p.from?.game ?? p.from?.app) ? `<a class="ghost" href="/${esc((p.from.game ?? p.from.app))}/${p.from.app ? 'open' : 'play'}">${icon('games')}<span>${p.from.app ? 'Open' : 'Play'} ${esc(p.from.name ?? (p.from.game ?? p.from.app))}</span></a>` : ''}</div>`)}
 <div class="wrap">
@@ -236,7 +249,7 @@ ${preview ? `<p class="sec">Try it</p>${preview}` : ''}
 <p class="sec">Use it in your game</p>
 <p class="plead">In a chat with your Homie studio open, ask for it by name:</p>
 ${sayRow('Say', sayAdd(p))}
-<p class="plead">Your AI fetches the files, checks every one, copies them into your studio and credits ${esc(name)} in your game. They are yours to tune from there.</p>
+<p class="plead">${p.sale ? 'Your AI shows the price and asks first. After your wallet pays, it receives the files,' : 'Your AI fetches the files,'} checks every one, copies them into your studio and credits ${esc(name)} in your game. They are yours to tune from there.</p>
 <p class="sec">About this part</p>
 <dl class="pfacts">${facts.map(([k, v]) => `<dt>${esc(k)}</dt><dd>${v}</dd>`).join('')}</dl>
 </div>`,