@snowcone-app/mockup-resolver 1.0.8 → 1.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # @snowcone-app/mockup-resolver
2
2
 
3
+ ## 1.0.9
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [[`b2eb755`](https://github.com/snowcone-app/snowcone-monorepo/commit/b2eb755023a99cf0b68b45485b33b9e187a93d2e)]:
8
+ - @snowcone-app/mockup-url@0.4.0
9
+
3
10
  ## 1.0.8
4
11
 
5
12
  ### Patch Changes
package/package.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "@snowcone-app/mockup-resolver",
3
- "version": "1.0.8",
3
+ "version": "1.0.9",
4
4
  "description": "URL signing and verification Cloudflare Worker",
5
5
  "main": "dist/index.js",
6
6
  "author": "",
7
7
  "license": "ISC",
8
8
  "dependencies": {
9
- "@snowcone-app/mockup-url": "0.3.4"
9
+ "@snowcone-app/mockup-url": "0.4.0"
10
10
  },
11
11
  "devDependencies": {
12
12
  "@cloudflare/workers-types": "^4.20250303.0",
@@ -0,0 +1,61 @@
1
+ /**
2
+ * Per-POP record cache with explicit invalidation (ADR-0097, completed).
3
+ *
4
+ * KV is the source of truth for resolver records (product + account) and is
5
+ * overwritten on every publish — but KV is a CENTRAL store: each edge server
6
+ * keeps a read-through memo for only 60 s, so with ~10k products nearly every
7
+ * read went to the central store (rsv_product 129-160 ms cold vs 3-8 warm,
8
+ * measured 2026-09-02). This layer puts each record in the POP's Cache API
9
+ * under a synthetic URL and keeps it for a year; the backend's publish step
10
+ * purges that URL globally the moment the record changes (Cache Purge by URL,
11
+ * seconds). Hot reads become a local cache hit; after an edit each POP refills
12
+ * once from KV. "Cache forever, invalidate on change" — no TTL policy anywhere.
13
+ *
14
+ * The synthetic URL MUST be on a hostname in the snowcone.app zone so the
15
+ * zone purge API can name it. Keep `EDGE_RECORD_URL` byte-identical to
16
+ * apps/backend/catalog/src/edge-purge.ts.
17
+ */
18
+
19
+ export type EdgeRecordKind = "product" | "account";
20
+
21
+ export const EDGE_RECORD_HOST = "https://img.snowcone.app";
22
+ export function edgeRecordUrl(kind: EdgeRecordKind, id: string): string {
23
+ return `${EDGE_RECORD_HOST}/_edge/${kind}/${encodeURIComponent(id)}`;
24
+ }
25
+
26
+ const YEAR = 31_536_000;
27
+
28
+ /**
29
+ * Read `kind:id` from the POP cache; on a miss run `load` (the KV read) and
30
+ * store a non-null result. Null results are NOT cached: a product that gets
31
+ * published must be visible immediately, and a hot 404 is cheap anyway.
32
+ * `ctx.waitUntil` keeps the put off the response path; without a ctx the put
33
+ * is fired and forgotten (still correct, may be cancelled).
34
+ */
35
+ export async function edgeCachedRecord<T>(
36
+ kind: EdgeRecordKind,
37
+ id: string,
38
+ load: () => Promise<T | null>,
39
+ ctx?: { waitUntil(p: Promise<unknown>): void },
40
+ ): Promise<{ value: T | null; source: "edge" | "kv" }> {
41
+ const url = edgeRecordUrl(kind, id);
42
+ let cache: Cache | null = null;
43
+ try {
44
+ cache = caches.default;
45
+ const hit = await cache.match(url);
46
+ if (hit) return { value: (await hit.json()) as T, source: "edge" };
47
+ } catch {
48
+ // Cache API unavailable (local dev / tests): fall through to KV.
49
+ }
50
+ const value = await load();
51
+ if (value !== null && cache) {
52
+ const put = cache.put(
53
+ url,
54
+ new Response(JSON.stringify(value), {
55
+ headers: { "content-type": "application/json", "cache-control": `public, max-age=${YEAR}` },
56
+ }),
57
+ ).catch(() => {});
58
+ if (ctx) ctx.waitUntil(put);
59
+ }
60
+ return { value, source: "kv" };
61
+ }
package/src/index.ts CHANGED
@@ -2,6 +2,8 @@
2
2
  // Web Crypto API is available globally in Cloudflare Workers
3
3
 
4
4
  // Import Cloudflare-specific modules
5
+ import { isLoadtestExempt } from "./loadtest-exempt";
6
+ import { edgeCachedRecord } from "./edge-record-cache";
5
7
  import { DurableObject } from "cloudflare:workers";
6
8
 
7
9
  // Add Cloudflare Workers types
@@ -46,6 +48,15 @@ interface RateLimiterStub extends DurableObjectStub {
46
48
  // Interface for environment bindings
47
49
  interface Env {
48
50
  URL_SIGNING_SECRET: string;
51
+ /** Comma-separated client IPs exempt from the per-IP public caps (our 9 metro relays running the load generator). Exact match only; change via PR. */
52
+ LOADTEST_EXEMPT_IPS?: string;
53
+ /**
54
+ * rc#262 — Ed25519 seal signing key (PKCS#8 DER, base64). When SET, every
55
+ * seal this worker mints is a v2 Ed25519 signature instead of a shared-secret
56
+ * HMAC. Presence IS the intent; there is no separate toggle to forget.
57
+ * Distribute RENDER_SEAL_PUBKEY to every box BEFORE setting this.
58
+ */
59
+ RENDER_SEAL_PRIVATE_KEY?: string;
49
60
  /** ADR-0096: service binding to the render edge (mockup-edge-cache) — the
50
61
  * resolver calls it in-process after sealing and streams bytes back.
51
62
  * One client leg; the 302 hop is retired. */
@@ -355,6 +366,11 @@ function addCorsHeaders(response: Response, request: Request): Response {
355
366
 
356
367
  // Clone the response and add CORS headers
357
368
  const corsResponse = new Response(response.body, response);
369
+ // AI-use opt-out on every render response: noai/noimageai crawler
370
+ // convention + EU DSM Art.4 TDM reservation. Render output is the
371
+ // platform's crown-jewel training data (AUP bars AI training/reference use).
372
+ corsResponse.headers.set("X-Robots-Tag", "noai, noimageai");
373
+ corsResponse.headers.set("tdm-reservation", "1");
358
374
  corsResponse.headers.set("Access-Control-Allow-Origin", origin);
359
375
  corsResponse.headers.set(
360
376
  "Access-Control-Allow-Methods",
@@ -362,7 +378,7 @@ function addCorsHeaders(response: Response, request: Request): Response {
362
378
  );
363
379
  corsResponse.headers.set(
364
380
  "Access-Control-Allow-Headers",
365
- "Content-Type, X-API-Key, X-Client-ID"
381
+ "Content-Type, X-API-Key, X-Client-ID, X-Render-Pin"
366
382
  );
367
383
  // This reflects the request Origin into ACAO, so shared caches MUST key on
368
384
  // Origin — otherwise a cached entry for origin A (or a no-Origin request) is
@@ -416,19 +432,56 @@ async function hashApiKey(apiKey: string): Promise<string> {
416
432
  * invalidation, this only delays the resolver's view). Both flatten the
417
433
  * per-isolate warm path to ~0ms; a cold isolate still pays first-fetch.
418
434
  */
419
- const ACCT_CACHE_TTL_MS = 60_000;
420
- const PRODUCT_CACHE_TTL_MS = 30_000;
421
- const ttlCache = new Map<string, { until: number; value: unknown }>();
435
+ // Kevin-approved (2026-08-15): long TTL + EXPLICIT invalidation, mirroring the
436
+ // render fleet's product cache (rc#167 — "explicit invalidation, no age
437
+ // expiry"; the 60s-bound version there caused staleness bugs). Isolate memory
438
+ // can't be cleared remotely, so the clear mechanism is a GENERATION STAMP in
439
+ // the ACCOUNTS KV: each isolate refreshes its view of the stamp at most every
440
+ // 30s (async — never awaited on the hot path), and entries written under an
441
+ // older generation read as misses. CLEAR TOOLING: bump the stamp —
442
+ // wrangler kv key put resolver:cache-gen "$(date +%s)" --namespace-id <ACCOUNTS>
443
+ // (or any backend write to that key, e.g. from account-config saves / the
444
+ // catalog-edit fan-out) — and every isolate drops its cache within ~30s. No
445
+ // HTTP bump endpoint on purpose: a public cache-clear lever is a cheap DoS.
446
+ const ACCT_CACHE_TTL_MS = 24 * 3600_000;
447
+ const GEN_KEY = "resolver:cache-gen";
448
+ const GEN_CHECK_INTERVAL_MS = 30_000;
449
+ let cacheGen = "";
450
+ let cacheGenCheckedAt = 0;
451
+ let cacheGenRefreshing = false;
452
+
453
+ function refreshCacheGen(env: { ACCOUNTS: KVNamespace }): void {
454
+ const now = Date.now();
455
+ if (cacheGenRefreshing || now - cacheGenCheckedAt < GEN_CHECK_INTERVAL_MS) return;
456
+ cacheGenRefreshing = true;
457
+ void env.ACCOUNTS.get(GEN_KEY)
458
+ .then((g) => {
459
+ cacheGenCheckedAt = Date.now();
460
+ const next = g ?? "";
461
+ if (next !== cacheGen) {
462
+ cacheGen = next;
463
+ ttlCache.clear();
464
+ }
465
+ })
466
+ .catch(() => {
467
+ cacheGenCheckedAt = Date.now();
468
+ })
469
+ .finally(() => {
470
+ cacheGenRefreshing = false;
471
+ });
472
+ }
473
+
474
+ const ttlCache = new Map<string, { until: number; gen: string; value: unknown }>();
422
475
 
423
476
  function ttlGet<T>(key: string): T | undefined {
424
477
  const e = ttlCache.get(key);
425
- if (!e || Date.now() >= e.until) return undefined;
478
+ if (!e || Date.now() >= e.until || e.gen !== cacheGen) return undefined;
426
479
  return e.value as T;
427
480
  }
428
481
 
429
482
  function ttlSet(key: string, value: unknown, ttlMs: number): void {
430
483
  if (ttlCache.size > 5_000) ttlCache.clear();
431
- ttlCache.set(key, { until: Date.now() + ttlMs, value });
484
+ ttlCache.set(key, { until: Date.now() + ttlMs, gen: cacheGen, value });
432
485
  }
433
486
 
434
487
  const publicLimitBurstCache = new Map<
@@ -940,8 +993,8 @@ async function authenticate(
940
993
  // in the default test glob) along with the L2 check; the asset-source
941
994
  // allowlist (L2) still uses it.
942
995
 
943
- export { signUrl, verifyUrl } from "./signing";
944
- import { signUrl, verifyUrl } from "./signing";
996
+ export { signUrl, verifyUrl, signUrlV2, mintSeal } from "./signing";
997
+ import { verifyUrl, mintSeal } from "./signing";
945
998
  import { checkAssetUrls } from "./asset-allowlist";
946
999
  import { fetchDesign } from "./design-ref";
947
1000
  import {
@@ -950,6 +1003,9 @@ import {
950
1003
  normalizeBgColor,
951
1004
  signDevSig,
952
1005
  parsePublicUrl,
1006
+ renderUrlLengthError,
1007
+ E_RENDER_URL_TOO_LONG,
1008
+ MAX_DESIGN_ELEMENTS,
953
1009
  PARAMS,
954
1010
  type DesignElement,
955
1011
  } from "@snowcone-app/mockup-url";
@@ -960,6 +1016,7 @@ import {
960
1016
  resolveAlbumPagePlacement,
961
1017
  resolveDefaults,
962
1018
  resolveVariant,
1019
+ unknownOptionPick,
963
1020
  type ResolvedPlacement,
964
1021
  } from "./resolve";
965
1022
  import { rejectUnknownPublicParams } from "./public-params";
@@ -1049,11 +1106,7 @@ async function handleMockupUrl(request: Request, env: Env): Promise<Response> {
1049
1106
  }
1050
1107
 
1051
1108
  // Resolve catalog defaults (Meilisearch, KV-cached).
1052
- const product = await fetchProduct(productCode, {
1053
- host: meiliHost,
1054
- apiKey: meiliKey,
1055
- index: meiliIndex,
1056
- }, env.ACCOUNTS);
1109
+ const product = await fetchProduct(productCode, env.ACCOUNTS);
1057
1110
  if (!product) {
1058
1111
  return err(404, "product_not_found", `Product not found: ${productCode}`);
1059
1112
  }
@@ -1105,7 +1158,11 @@ async function handleMockupUrl(request: Request, env: Env): Promise<Response> {
1105
1158
  // signature" at the box.
1106
1159
  sigParams.delete("debug");
1107
1160
  const relative = `${urlObj.pathname}?${sigParams.toString()}`;
1108
- const sig = await signUrl(relative, signingSecret);
1161
+ const tooLong = renderUrlLengthError(relative, 1);
1162
+ if (tooLong) {
1163
+ return err(414, "render_url_too_long", tooLong);
1164
+ }
1165
+ const sig = await mintSeal(relative, signingSecret, env.RENDER_SEAL_PRIVATE_KEY);
1109
1166
  urlObj.searchParams.append("seal", sig);
1110
1167
 
1111
1168
  return json({ url: urlObj.toString() });
@@ -1132,9 +1189,13 @@ async function handleMockupUrl(request: Request, env: Env): Promise<Response> {
1132
1189
  */
1133
1190
  async function loadAccountByKey(
1134
1191
  key: string,
1135
- env: Env
1192
+ env: Env,
1193
+ ctx?: { waitUntil(p: Promise<unknown>): void }
1136
1194
  ): Promise<AccountData | null> {
1137
- let accountDataStr = await env.ACCOUNTS.get(key);
1195
+ // POP cache first (edge-record-cache.ts); the backend purges
1196
+ // /_edge/account/<shopId> on every account config write.
1197
+ const cached = await edgeCachedRecord<string>("account", key, () => env.ACCOUNTS.get(key), ctx);
1198
+ let accountDataStr = cached.value;
1138
1199
  if (accountDataStr) {
1139
1200
  try {
1140
1201
  const parsed = JSON.parse(accountDataStr) as AccountData;
@@ -1255,7 +1316,9 @@ function houseAssetUrl(request: Request): string {
1255
1316
  async function handlePublicResolve(
1256
1317
  request: Request,
1257
1318
  env: Env,
1258
- productCode: string
1319
+ productCode: string,
1320
+ ctx?: { waitUntil(p: Promise<unknown>): void },
1321
+ tEntry?: number
1259
1322
  ): Promise<Response> {
1260
1323
  // All resolver responses are uncacheable — the resolver must stay in the loop
1261
1324
  // for invalidation + per-request auth/rate (ADR-0076 §7). 4xx must never be
@@ -1274,6 +1337,8 @@ async function handlePublicResolve(
1274
1337
  );
1275
1338
 
1276
1339
  const t0 = Date.now(); // Server-Timing base — emitted on the success 302
1340
+ let sigMs = 0; // L3 developer-signature check (HMAC), when required
1341
+ let sealMs = 0; // Ed25519 seal mint
1277
1342
  const reqUrl = new URL(request.url);
1278
1343
  const q = reqUrl.searchParams;
1279
1344
 
@@ -1365,9 +1430,10 @@ async function handlePublicResolve(
1365
1430
 
1366
1431
  // 1. Shop ID lookup → AccountData (404 unknown, 403 revoked).
1367
1432
  const tAcct = Date.now();
1433
+ refreshCacheGen(env);
1368
1434
  let account = ttlGet<AccountData | null>(`acct:${key}`);
1369
1435
  if (account === undefined) {
1370
- account = await loadAccountByKey(key, env);
1436
+ account = await loadAccountByKey(key, env, ctx);
1371
1437
  ttlSet(`acct:${key}`, account, ACCT_CACHE_TTL_MS);
1372
1438
  }
1373
1439
  const acctMs = Date.now() - tAcct;
@@ -1417,7 +1483,9 @@ async function handlePublicResolve(
1417
1483
  if (!provided) return errResp(403, "Missing required signature");
1418
1484
  // canonicalForSig reads the RAW query verbatim — use the original URL string.
1419
1485
  const canonical = canonicalForSig(request.url);
1486
+ const tSig = Date.now();
1420
1487
  const expected = await signDevSig(canonical, account.l3Secret);
1488
+ sigMs = Date.now() - tSig;
1421
1489
  let ok = expected.length === provided.length;
1422
1490
  if (ok) {
1423
1491
  let r = 0;
@@ -1451,18 +1519,11 @@ async function handlePublicResolve(
1451
1519
  return errResp(500, "Resolver not configured");
1452
1520
  }
1453
1521
 
1522
+ const limitsExempt = isLoadtestExempt(clientIp, env.LOADTEST_EXEMPT_IPS);
1454
1523
  const tLimits = Date.now();
1455
- const cachedProduct = ttlGet<Awaited<ReturnType<typeof fetchProduct>>>(`prod:${productCode}`);
1456
- const productPromise = cachedProduct !== undefined
1457
- ? Promise.resolve(cachedProduct)
1458
- : fetchProduct(
1459
- productCode,
1460
- { host: meiliHost, apiKey: meiliKey, index: meiliIndex },
1461
- env.ACCOUNTS
1462
- ).then((p) => {
1463
- ttlSet(`prod:${productCode}`, p, PRODUCT_CACHE_TTL_MS);
1464
- return p;
1465
- });
1524
+ // ADR-0097: one KV read of the PUBLISHED record — no in-isolate product
1525
+ // cache, no TTL. The only staleness on this path is KV's own propagation.
1526
+ const productPromise = fetchProduct(productCode, env.ACCOUNTS, ctx);
1466
1527
  // Detached guard: when a limit blocks below, this promise is never awaited —
1467
1528
  // without a no-op catch, a fetch failure there would surface as an unhandled
1468
1529
  // rejection. The real `await productPromise` further down still rethrows.
@@ -1474,6 +1535,7 @@ async function handlePublicResolve(
1474
1535
  retryAfter?: number;
1475
1536
  };
1476
1537
  const globalCheck: Promise<LimitVerdict> = (async () => {
1538
+ if (limitsExempt) return { allowed: true };
1477
1539
  try {
1478
1540
  // Kevin-approved optimistic limiting (2026-08-15): a cold per-IP DO
1479
1541
  // wake measured 565ms synchronously on a visitor's first render, and
@@ -1504,7 +1566,7 @@ async function handlePublicResolve(
1504
1566
  }
1505
1567
  })();
1506
1568
  const acctCheck: Promise<LimitVerdict> = (async () => {
1507
- if (!account.public?.rateLimit) return { allowed: true };
1569
+ if (limitsExempt || !account.public?.rateLimit) return { allowed: true };
1508
1570
  try {
1509
1571
  // Same optimistic pattern as the global check above.
1510
1572
  const burstKey = `${accountId}:${clientIp}`;
@@ -1624,6 +1686,29 @@ async function handlePublicResolve(
1624
1686
  // 4a. Resolve the variant from option picks (both catalog shapes) + the
1625
1687
  // render-only optionSelections rendercenter needs. resolveDefaults then supplies
1626
1688
  // the mockup scene and a default placement (for the bare-asset case).
1689
+ // Strict: every `opt.<attr>=<choice>` must name a catalog attribute and one
1690
+ // of its choices. An unknown render-only choice used to ride through to the
1691
+ // box and render with no underlay; an unknown combination choice fell back
1692
+ // to the default variant — both silently (ADR-0099 lab product probe,
1693
+ // 2026-09-06). Named, with the valid values, like unknown placement keys.
1694
+ const badPick = unknownOptionPick(product, optionPicks);
1695
+ if (badPick) {
1696
+ return badPick.validChoices
1697
+ ? errResp(
1698
+ 400,
1699
+ `Unknown choice "${badPick.choice}" for option "${badPick.attribute}" on ${productCode}. ` +
1700
+ `Valid choices: ${badPick.validChoices.join(", ")}.`,
1701
+ "E_OPTION_CHOICE_NOT_FOUND"
1702
+ )
1703
+ : errResp(
1704
+ 400,
1705
+ `Unknown option "${badPick.attribute}" on ${productCode}. ` +
1706
+ (badPick.validAttributes.length
1707
+ ? `Valid options: ${badPick.validAttributes.join(", ")}.`
1708
+ : `This product has no options.`),
1709
+ "E_OPTION_NOT_FOUND"
1710
+ );
1711
+ }
1627
1712
  const vr = resolveVariant(product, optionPicks, variantOverride);
1628
1713
  if (!vr) {
1629
1714
  return errResp(422, `Product ${productCode} has no renderable combination`);
@@ -1707,9 +1792,15 @@ async function handlePublicResolve(
1707
1792
  if (designElements.length === 0) {
1708
1793
  return errResp(400, "Missing artwork: provide asset= or asset.<placement>=");
1709
1794
  }
1710
- const MAX_ELEMENTS = 10; // mirrors rendercenter's shared MAX_ELEMENTS
1711
- if (designElements.length > MAX_ELEMENTS) {
1712
- return errResp(400, `Too many placements (max ${MAX_ELEMENTS})`);
1795
+ // One cap, three enforcers (resolver, buy worker, render box) — the number
1796
+ // lives in @snowcone-app/mockup-url; the box pins the same literal.
1797
+ if (designElements.length > MAX_DESIGN_ELEMENTS) {
1798
+ return errResp(
1799
+ 400,
1800
+ `Too many placements: ${designElements.length} (max ${MAX_DESIGN_ELEMENTS}). ` +
1801
+ `Reference a saved design with design=<reference> for more surfaces.`,
1802
+ "E_TOO_MANY_PLACEMENTS"
1803
+ );
1713
1804
  }
1714
1805
 
1715
1806
  // 5. Build the render URL FRESH — never forward the incoming query string, so
@@ -1745,6 +1836,15 @@ async function handlePublicResolve(
1745
1836
  if (catalogDesign) {
1746
1837
  urlObj.searchParams.append("catalog", catalogDesign.pairingId);
1747
1838
  }
1839
+ // Catalog render version (resolve.ts renderVersion), UNDER the seal: keys
1840
+ // the box Redis cache, the edge R2/POP cache and the browser ETag, so a
1841
+ // catalog fix re-keys every tier at once — the public URL stays the same
1842
+ // and the next revalidation (private, max-age=300) fetches the fixed
1843
+ // pixels instead of a 304. Empty only for records published before the
1844
+ // field existed; those keep legacy keys until their next publish.
1845
+ if (product.renderVersion) {
1846
+ urlObj.searchParams.append("pv", product.renderVersion);
1847
+ }
1748
1848
  // Operator debug passthrough (ADR-0096): with the 302 retired, the client
1749
1849
  // never learns the sealed URL, so the lab's full-waterfall replay re-fetches
1750
1850
  // the PUBLIC url with debug=<RENDER_DEBUG_SECRET>. Forward it onto the
@@ -1764,7 +1864,16 @@ async function handlePublicResolve(
1764
1864
  // signature" at the box.
1765
1865
  sigParams.delete("debug");
1766
1866
  const relative = `${urlObj.pathname}?${sigParams.toString()}`;
1767
- const sig = await signUrl(relative, signingSecret);
1867
+ // Whole-URL ceiling, checked BEFORE the seal: past ~16 KiB the render box's
1868
+ // HTTP parser answers a bare 431 with no code and no hint (prod probe
1869
+ // 2026-09-06, 7 placements × 1.9 KB asset URLs). Typed here, with the fix.
1870
+ const tooLong = renderUrlLengthError(relative, designElements.length);
1871
+ if (tooLong) {
1872
+ return errResp(414, tooLong, E_RENDER_URL_TOO_LONG);
1873
+ }
1874
+ const tSeal = Date.now();
1875
+ const sig = await mintSeal(relative, signingSecret, env.RENDER_SEAL_PRIVATE_KEY);
1876
+ sealMs = Date.now() - tSeal;
1768
1877
  urlObj.searchParams.append("seal", sig);
1769
1878
 
1770
1879
  // 7. Single-leg render (ADR-0096, retired the 302): call the render edge
@@ -1787,31 +1896,79 @@ async function handlePublicResolve(
1787
1896
  // overlapping totals make waterfalls unreadable (browser wait then reads:
1788
1897
  // transit + rsv_total + edge_total, no envelope arithmetic needed).
1789
1898
  const resolverMs = Date.now() - t0;
1899
+ // Forward the CLIENT's cf blob through the service binding: a fresh
1900
+ // Request has NO cf, so without this the render router downstream sees a
1901
+ // geo-less request and can't do proximity routing — which, on the
1902
+ // single-leg path, is EVERY public render (pre-fix they all landed on
1903
+ // whatever box sat first in the RENDER_BOXES KV array; observed as a US
1904
+ // user's renders consistently served from the EU box). The redirect-era
1905
+ // flow never had this problem because the browser hit the edge directly.
1906
+ const tEdge = Date.now();
1790
1907
  const edgeRes = await env.RENDER_EDGE.fetch(
1791
1908
  new Request(urlObj.toString(), {
1792
1909
  method: "GET",
1793
1910
  headers: request.headers,
1794
- })
1911
+ cf: (request as unknown as { cf?: RequestInitCfProperties }).cf,
1912
+ } as RequestInit)
1795
1913
  );
1914
+ // rsv_hop = the service-binding round trip minus the edge's own edge_total:
1915
+ // pure worker-to-worker cost. Measured ~10-15 ms (2026-09-02); merging the
1916
+ // two workers did not remove it (reverted, #2063).
1917
+ const edgeWallMs = Date.now() - tEdge;
1918
+ const edgeTotalMs = Number((/(?:^|[ ,])edge_total;dur=([0-9.]+)/.exec(edgeRes.headers.get("Server-Timing") || "") || [])[1] ?? NaN);
1919
+ const hopMs = Number.isFinite(edgeTotalMs) ? Math.max(0, Math.round(edgeWallMs - edgeTotalMs)) : edgeWallMs;
1796
1920
  const headers = new Headers(edgeRes.headers);
1797
- headers.set("Cache-Control", edgeRes.ok ? "private, max-age=300" : "no-store");
1921
+ // Revalidation (ADR-0096 amendment, 2026-09-04): the edge stamps the render
1922
+ // key as a strong ETag and answers If-None-Match with a 304 — the browser's
1923
+ // header rides through on `request.headers` above. A 304 is a SUCCESS here:
1924
+ // it must carry the same `private, max-age=300` so the browser extends its
1925
+ // copy's freshness for another five minutes (a `no-store` on a 304 would
1926
+ // poison the stored entry instead). So after the window a page refresh
1927
+ // costs one header-only round trip per image, not a re-download — while
1928
+ // every control point (auth, limits, catalog, DMCA at the edge) still ran.
1929
+ // stale-while-revalidate: past the 5-minute window the browser paints its
1930
+ // cached copy immediately and revalidates in the background, so a
1931
+ // returning visitor never waits on our round trip. The trade, stated: a
1932
+ // catalog fix reaches that visitor on the load AFTER the revalidation, not
1933
+ // the one that triggered it (Kevin 2026-09-04, accepted for instant paint).
1934
+ const edgeOk = edgeRes.ok || edgeRes.status === 304;
1935
+ headers.set("Cache-Control", edgeOk ? "private, max-age=300, stale-while-revalidate=86400" : "no-store");
1798
1936
  headers.set("Access-Control-Allow-Origin", "*");
1799
1937
  headers.set("Timing-Allow-Origin", "*");
1938
+ // Let browser tooling (the render-speed lab) read box attribution + the
1939
+ // encoder choice off cross-origin responses.
1940
+ headers.set(
1941
+ "Access-Control-Expose-Headers",
1942
+ "ETag, Server-Timing, X-Render-Box, X-Render-Pinned, X-Render-Overflow, X-Encoder"
1943
+ );
1800
1944
  headers.append(
1801
1945
  "Server-Timing",
1802
- `rsv_acct;dur=${acctMs}, rsv_limits;dur=${limitsMs}, ` +
1803
- `rsv_product;dur=${productMs}, rsv_total;dur=${resolverMs}`
1946
+ `rsv_pre;dur=${tEntry ? t0 - tEntry : 0}, rsv_acct;dur=${acctMs}, rsv_sig;dur=${sigMs}, rsv_limits;dur=${limitsMs}${limitsExempt ? ';desc="exempt"' : ""}, ` +
1947
+ `rsv_product;dur=${productMs}, rsv_seal;dur=${sealMs}, rsv_total;dur=${resolverMs}, rsv_hop;dur=${hopMs}, ` +
1948
+ // desc-only: the isolate AGE is not a duration of this request (a dur= here drew a 30-minute bar in the lab)
1949
+ `rsv_iso;desc="${(rsvIsoBorn || (rsvIsoBorn = tEdge, rsvIsoId = crypto.randomUUID().slice(0, 8)), rsvIsoId)} age=${((tEdge - rsvIsoBorn) / 1000).toFixed(1)}s n=${++rsvIsoReqCount}"`
1804
1950
  );
1805
- return new Response(edgeRes.body, {
1951
+ // A 304 has no body by definition; the Response constructor rejects a
1952
+ // stream on a null-body status, so pass null explicitly.
1953
+ return new Response(edgeRes.status === 304 ? null : edgeRes.body, {
1806
1954
  status: edgeRes.status,
1807
1955
  statusText: edgeRes.statusText,
1808
1956
  headers,
1809
1957
  });
1810
1958
  }
1811
1959
 
1960
+ // Per-isolate identity for rsv_iso (pairs with the edge's edge_iso: a hop
1961
+ // spike on a young edge isolate is a cold start; on an old one it is the
1962
+ // service-binding dispatch itself).
1963
+ // Initialised on first use: random values/clocks are disallowed in the global scope.
1964
+ let rsvIsoId = ''
1965
+ let rsvIsoBorn = 0
1966
+ let rsvIsoReqCount = 0
1967
+
1812
1968
  // Cloudflare Worker entry point
1813
1969
  export default {
1814
1970
  async fetch(request: Request, env: Env, ctx: any): Promise<Response> {
1971
+ const tEntry = Date.now(); // Server-Timing rsv_pre = worker entry → resolve handler
1815
1972
  // SECURITY: the former unauthenticated `/test-kv` debug endpoint was removed.
1816
1973
  // It dumped/enumerated/wrote the ACCOUNTS KV (account configs, key hashes,
1817
1974
  // L3 secrets) with no auth, live in production. Nothing depends on it; do
@@ -1824,7 +1981,11 @@ export default {
1824
1981
  "Access-Control-Allow-Origin": request.headers.get("Origin") || "*",
1825
1982
  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
1826
1983
  "Access-Control-Allow-Headers":
1827
- "Content-Type, X-API-Key, X-Client-ID",
1984
+ "Content-Type, X-API-Key, X-Client-ID, X-Render-Pin",
1985
+ // Let the browser reuse this preflight verdict for a day: a client
1986
+ // that sends custom headers (X-Client-ID, X-Render-Pin) otherwise
1987
+ // pays an OPTIONS round trip through this worker per render.
1988
+ "Access-Control-Max-Age": "86400",
1828
1989
  // Reflected Origin → cache must vary by Origin (see CORS notes above).
1829
1990
  Vary: "Origin",
1830
1991
  },
@@ -1876,7 +2037,7 @@ export default {
1876
2037
  url.pathname.split("/").filter(Boolean)[0]
1877
2038
  );
1878
2039
  return addCorsHeaders(
1879
- await handlePublicResolve(request, env, productCode),
2040
+ await handlePublicResolve(request, env, productCode, ctx, tEntry),
1880
2041
  request
1881
2042
  );
1882
2043
  }
@@ -2016,7 +2177,7 @@ export default {
2016
2177
  ? urlObj.pathname + urlObj.search
2017
2178
  : urlObj.toString();
2018
2179
 
2019
- const signature = await signUrl(finalUrlToSign, secretKey);
2180
+ const signature = await mintSeal(finalUrlToSign, secretKey, env.RENDER_SEAL_PRIVATE_KEY);
2020
2181
 
2021
2182
  // Construct the signed URL by adding the signature parameter
2022
2183
  urlObj.searchParams.append("seal", signature);
@@ -0,0 +1,6 @@
1
+ /** Per-IP public rate-limit exemption for our own load generators (the metro relays).
2
+ * Exact-IP match only: no CIDR, no wildcards. The list is a plain wrangler var. */
3
+ export function isLoadtestExempt(clientIp: string, list: string | undefined): boolean {
4
+ if (!list || !clientIp || clientIp === "unknown-ip") return false;
5
+ return list.split(",").map((s) => s.trim()).filter(Boolean).includes(clientIp);
6
+ }
package/src/resolve.ts CHANGED
@@ -4,6 +4,7 @@
4
4
  // logic in `apps/www/app/api/harness/mockup/route.ts` (the prototype) and the
5
5
  // SDK's `getProduct`. Edge-safe: plain fetch + JSON. (ADR-0073 §10.)
6
6
 
7
+ import { edgeCachedRecord } from "./edge-record-cache";
7
8
  import {
8
9
  PARAMS,
9
10
  type DesignElement,
@@ -35,7 +36,12 @@ export function looksLikeResolveRequest(
35
36
  host: string,
36
37
  url: URL
37
38
  ): boolean {
38
- if (method !== "GET") return false;
39
+ // HEAD mirrors GET: uptime checks and agents that verify a mockup URL with
40
+ // `curl -I` used to fall through to the "Mockup Resolver API" JSON default
41
+ // route (200 + application/json) and conclude the image was broken
42
+ // (growth/0013 F3, eng/0049). The runtime drops the body on HEAD, so the
43
+ // same 302 → image redirect is returned with the real headers.
44
+ if (method !== "GET" && method !== "HEAD") return false;
39
45
 
40
46
  const segments = url.pathname.split("/").filter(Boolean);
41
47
  if (segments.length !== 1) return false;
@@ -108,6 +114,15 @@ export interface ResolvedPlacement {
108
114
  }
109
115
 
110
116
  export interface ResolvedProduct {
117
+ /** Content version of the published record (ADR-0097). */
118
+ version: string;
119
+ /** Render version: hash of the product's pixel-affecting config (full
120
+ * mockups/masks, placements, variants, options), minted by the backend
121
+ * (catalog/src/resolver-record.ts). Sealed onto every render URL as
122
+ * `pv=` so box, edge and browser caches all key on it — a catalog fix
123
+ * changes it and pre-fix pixels stop being served everywhere at once.
124
+ * Falls back to `version` for records published before it existed. */
125
+ renderVersion: string;
111
126
  id: string;
112
127
  variants: { gvid: string }[];
113
128
  mockups: { id: string; gvids: string[] }[];
@@ -135,9 +150,15 @@ export interface VariantResolution {
135
150
  optionSelections: Record<string, string>;
136
151
  }
137
152
 
138
- const CACHE_TTL_SECONDS = 300; // 5 min — see ADR-0073 open question #1 (TTL vs event-driven)
139
- // Bump when ResolvedProduct's shape changes, so stale-shape cache entries are skipped.
140
- const CACHE_VERSION = "v3";
153
+ /**
154
+ * ADR-0097: the product record is PUBLISHED to KV by the backend in the same
155
+ * step that writes Meilisearch — no TTL, no Meili fetch here. `prod:<code>`
156
+ * holds `{ version, publishedAt, raw }`; a missing key means "not published"
157
+ * and resolves to 404 exactly as a Meili miss did. Concurrent requests for
158
+ * the same product share one in-flight read.
159
+ */
160
+ const RESOLVER_PRODUCT_KEY = (code: string) => `prod:${code}`;
161
+ const inflightProducts = new Map<string, Promise<ResolvedProduct | null>>();
141
162
 
142
163
  /** Lowercase + collapse non-alphanumerics to `_` — the fallback slug for a
143
164
  * placement that has no catalog `key` yet (pre-P1). */
@@ -342,23 +363,38 @@ export function assembleArtwork(
342
363
  return { ok: true, elements: [...byKey.values()] };
343
364
  }
344
365
 
345
- /** Fetch a product from Meilisearch (KV-cached). Returns null if not found. */
366
+ /** Read a product's published record from KV (ADR-0097). Returns null if not published. */
346
367
  export async function fetchProduct(
347
368
  productCode: string,
348
- meili: MeiliConfig,
349
- kv: KVNamespace
369
+ kv: KVNamespace,
370
+ ctx?: { waitUntil(p: Promise<unknown>): void }
350
371
  ): Promise<ResolvedProduct | null> {
351
- const cacheKey = `prod:${CACHE_VERSION}:${productCode}`;
352
- const cached = await kv.get(cacheKey, "json");
353
- if (cached) return cached as ResolvedProduct;
354
-
355
- const url = `${meili.host}/indexes/${meili.index}/documents/${encodeURIComponent(productCode)}`;
356
- const res = await fetch(url, {
357
- headers: { Authorization: `Bearer ${meili.apiKey}` },
358
- });
359
- if (!res.ok) return null;
372
+ const key = RESOLVER_PRODUCT_KEY(productCode);
373
+ const pending = inflightProducts.get(key);
374
+ if (pending) return pending;
375
+ const p = (async () => {
376
+ // POP cache first (edge-record-cache.ts): a year-long entry the backend
377
+ // purges by URL on every publish. Miss → the KV read, then fill.
378
+ const { value: rec } = await edgeCachedRecord<{ version?: string; renderVersion?: string; raw?: RawProduct }>(
379
+ "product",
380
+ productCode,
381
+ async () => (await kv.get(key, "json")) as { version?: string; renderVersion?: string; raw?: RawProduct } | null,
382
+ ctx,
383
+ );
384
+ if (!rec || !rec.raw) return null;
385
+ const version = typeof rec.version === "string" ? rec.version : "";
386
+ const renderVersion = typeof rec.renderVersion === "string" && rec.renderVersion ? rec.renderVersion : version;
387
+ return toResolvedProduct(rec.raw, version, renderVersion);
388
+ })();
389
+ inflightProducts.set(key, p);
390
+ try {
391
+ return await p;
392
+ } finally {
393
+ inflightProducts.delete(key);
394
+ }
395
+ }
360
396
 
361
- const raw = (await res.json()) as RawProduct;
397
+ function toResolvedProduct(raw: RawProduct, version: string, renderVersion: string = version): ResolvedProduct {
362
398
 
363
399
  const rawAttrs = raw.options?.attributes ?? {};
364
400
  const attributes: ResolvedProduct["attributes"] = {};
@@ -386,6 +422,8 @@ export async function fetchProduct(
386
422
  }
387
423
 
388
424
  const resolved: ResolvedProduct = {
425
+ version,
426
+ renderVersion,
389
427
  id: raw.id,
390
428
  variants: (raw.variants ?? [])
391
429
  .map((v) => ({ gvid: v.gvid ?? v.id ?? "" }))
@@ -404,9 +442,6 @@ export async function fetchProduct(
404
442
  album: normalizeAlbum(raw.album),
405
443
  };
406
444
 
407
- await kv.put(cacheKey, JSON.stringify(resolved), {
408
- expirationTtl: CACHE_TTL_SECONDS,
409
- });
410
445
  return resolved;
411
446
  }
412
447
 
@@ -440,6 +475,46 @@ export function resolveDefaults(
440
475
  return { variantId, mockupId: mockup.id, placement };
441
476
  }
442
477
 
478
+ export interface UnknownOptionPick {
479
+ /** The attribute as the caller wrote it (unknown attribute) or the catalog's name (unknown choice). */
480
+ attribute: string;
481
+ choice: string;
482
+ validAttributes: string[];
483
+ /** null when the ATTRIBUTE is unknown; the attribute's choices when the CHOICE is. */
484
+ validChoices: string[] | null;
485
+ }
486
+
487
+ /**
488
+ * The first `opt.<attr>=<choice>` pick that names no catalog attribute, or a
489
+ * choice the attribute does not list (both case-insensitive), or null when
490
+ * every pick is valid. An attribute with no listed choices accepts any value
491
+ * (nothing to validate against).
492
+ *
493
+ * Without this, a wrong pick was SILENT: an unknown render-only choice rode
494
+ * `optionSelections` to the render box, which found no choice and rendered
495
+ * the product with no underlay; an unknown combination choice matched no
496
+ * SKU row and fell through to the default variant. Same policy as placement
497
+ * keys — fail loudly, name the valid values (ADR-0089 house style).
498
+ */
499
+ export function unknownOptionPick(
500
+ product: ResolvedProduct,
501
+ picks: Record<string, string>
502
+ ): UnknownOptionPick | null {
503
+ const attrs = product.attributes ?? {};
504
+ const validAttributes = Object.keys(attrs);
505
+ const byLower = new Map(validAttributes.map((n) => [n.toLowerCase(), n]));
506
+ for (const [rawAttr, rawChoice] of Object.entries(picks)) {
507
+ const name = byLower.get(rawAttr.toLowerCase());
508
+ if (!name) return { attribute: rawAttr, choice: rawChoice, validAttributes, validChoices: null };
509
+ const choices = attrs[name]?.choices ?? [];
510
+ if (choices.length === 0) continue;
511
+ if (!choices.some((c) => c.toLowerCase() === rawChoice.toLowerCase())) {
512
+ return { attribute: name, choice: rawChoice, validAttributes, validChoices: choices };
513
+ }
514
+ }
515
+ return null;
516
+ }
517
+
443
518
  /**
444
519
  * Resolve public option picks (`opt.<attr>=<choice>`, matched case-insensitively)
445
520
  * to a variant gvid + the render-only `optionSelections` rendercenter consumes.
package/src/signing.ts CHANGED
@@ -40,3 +40,63 @@ export async function verifyUrl(
40
40
  }
41
41
  return result === 0;
42
42
  }
43
+
44
+ /**
45
+ * rc#262 — Ed25519 (v2) seal minting.
46
+ *
47
+ * The private key never leaves the edge/backend. Boxes hold only the 32-byte
48
+ * public half, so a compromised box can no longer forge seals for itself OR
49
+ * the fleet — which is the whole point of the migration away from the shared
50
+ * `URL_SIGNING_SECRET`.
51
+ *
52
+ * Wire format: `v2.<base64url(64-byte signature)>`. The signed canonical
53
+ * string is IDENTICAL to the v1 HMAC one, so callers need no other change.
54
+ */
55
+ export const SEAL_V2_PREFIX = "v2.";
56
+
57
+ /**
58
+ * @param url Canonical string to sign (`path?query`, seal+debug removed)
59
+ * @param pkcs8B64 Ed25519 private key, PKCS#8 DER, base64 (NOT base64url)
60
+ */
61
+ export async function signUrlV2(url: string, pkcs8B64: string): Promise<string> {
62
+ const der = Uint8Array.from(atob(pkcs8B64), (c) => c.charCodeAt(0));
63
+
64
+ let key: CryptoKey;
65
+ try {
66
+ key = await crypto.subtle.importKey("pkcs8", der, { name: "Ed25519" }, false, ["sign"]);
67
+ } catch (cause) {
68
+ // An unusable signing key is an operator error, not a request error. Throw
69
+ // with the fix named rather than silently falling back to a v1 HMAC seal —
70
+ // a silent downgrade would quietly un-do the security migration.
71
+ throw new Error(
72
+ "E_SEAL_PRIVATE_KEY_INVALID: RENDER_SEAL_PRIVATE_KEY is not an importable " +
73
+ "Ed25519 PKCS#8 key. Expect base64 of the PKCS#8 DER (64 chars for Ed25519). " +
74
+ "Regenerate with `openssl genpkey -algorithm ed25519` and re-set the secret.",
75
+ { cause },
76
+ );
77
+ }
78
+
79
+ const sig = new Uint8Array(await crypto.subtle.sign("Ed25519", key, new TextEncoder().encode(url)));
80
+
81
+ // base64url, no padding — safe to drop straight into a query string.
82
+ let bin = "";
83
+ for (const b of sig) bin += String.fromCharCode(b);
84
+ return SEAL_V2_PREFIX + btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
85
+ }
86
+
87
+ /**
88
+ * Mint the correct seal for the current rollout stage.
89
+ *
90
+ * Presence of the Ed25519 key IS the intent — there is no separate boolean to
91
+ * forget. Distribute the public key to every box FIRST; the box throws
92
+ * E_SEAL_PUBKEY_MISSING (loudly, never a silent 401) if that order is broken.
93
+ */
94
+ export async function mintSeal(
95
+ url: string,
96
+ hmacSecret: string,
97
+ ed25519PrivateKeyB64?: string,
98
+ ): Promise<string> {
99
+ return ed25519PrivateKeyB64
100
+ ? signUrlV2(url, ed25519PrivateKeyB64)
101
+ : signUrl(url, hmacSecret);
102
+ }
@@ -0,0 +1,11 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { isLoadtestExempt } from "../src/loadtest-exempt";
3
+ describe("isLoadtestExempt", () => {
4
+ const list = "172.236.245.89, 50.116.2.79";
5
+ it("exact listed IPs only", () => {
6
+ expect(isLoadtestExempt("50.116.2.79", list)).toBe(true);
7
+ expect(isLoadtestExempt("50.116.2.7", list)).toBe(false);
8
+ expect(isLoadtestExempt("unknown-ip", "unknown-ip")).toBe(false);
9
+ expect(isLoadtestExempt("172.236.245.89", undefined)).toBe(false);
10
+ });
11
+ });
@@ -0,0 +1,73 @@
1
+ import { existsSync, readFileSync } from 'node:fs'
2
+ import { resolve } from 'node:path'
3
+ import { describe, expect, it } from 'vitest'
4
+
5
+ import {
6
+ E_RENDER_URL_TOO_LONG,
7
+ MAX_DESIGN_ELEMENTS,
8
+ MAX_RENDER_URL_LENGTH,
9
+ renderUrlLengthError,
10
+ } from '@snowcone-app/mockup-url'
11
+
12
+ /**
13
+ * The design-element cap is ONE number enforced in three places: this
14
+ * resolver, the buy worker (both import MAX_DESIGN_ELEMENTS) and the render
15
+ * box (`services/rendercenter/shared/src/types.ts` CACHE_LIMITS.MAX_ELEMENTS,
16
+ * a separate repo that cannot import this package). Each side pins the
17
+ * literal and names the other; when the submodule is checked out (local dev)
18
+ * the two files are ALSO compared directly. CI checks out the monorepo
19
+ * without the submodule, so there the literal pin is the whole assertion —
20
+ * stated here so nobody reads a green run as "cross-checked".
21
+ */
22
+ describe('MAX_DESIGN_ELEMENTS drift pin (resolver ↔ buy ↔ render box)', () => {
23
+ it('pins the literal the render box enforces (rendercenter shared CACHE_LIMITS.MAX_ELEMENTS = 10)', () => {
24
+ expect(MAX_DESIGN_ELEMENTS).toBe(10)
25
+ })
26
+
27
+ it('matches the submodule copy when services/rendercenter is checked out (literal-only in CI)', () => {
28
+ const typesTs = resolve(__dirname, '../../../services/rendercenter/shared/src/types.ts')
29
+ if (!existsSync(typesTs)) {
30
+ // Submodule absent (CI): the literal pin above is the assertion.
31
+ expect(MAX_DESIGN_ELEMENTS).toBe(10)
32
+ return
33
+ }
34
+ const m = /MAX_ELEMENTS:\s*(\d+)/.exec(readFileSync(typesTs, 'utf8'))
35
+ expect(m, 'CACHE_LIMITS.MAX_ELEMENTS not found in rendercenter shared/src/types.ts').not.toBeNull()
36
+ expect(Number(m![1])).toBe(MAX_DESIGN_ELEMENTS)
37
+ })
38
+ })
39
+
40
+ describe('renderUrlLengthError (E_RENDER_URL_TOO_LONG)', () => {
41
+ const path = '/5J6AQA?shop=dqMwU8Jct3&width=800&assets='
42
+ it('accepts a URL at the ceiling and refuses one character past it', () => {
43
+ expect(MAX_RENDER_URL_LENGTH).toBe(12 * 1024)
44
+ expect(renderUrlLengthError(path + 'a'.repeat(MAX_RENDER_URL_LENGTH - path.length))).toBeNull()
45
+ const msg = renderUrlLengthError(path + 'a'.repeat(MAX_RENDER_URL_LENGTH - path.length + 1), 7)
46
+ expect(msg).not.toBeNull()
47
+ expect(msg).toContain(`${MAX_RENDER_URL_LENGTH + 1} characters`)
48
+ expect(msg).toContain('7 placements')
49
+ expect(msg).toContain(String(MAX_RENDER_URL_LENGTH))
50
+ })
51
+
52
+ it('names the fix: design=<reference> or fewer/shorter asset URLs', () => {
53
+ const msg = renderUrlLengthError('x'.repeat(MAX_RENDER_URL_LENGTH * 2), 10)!
54
+ expect(msg).toContain('design=<reference>')
55
+ expect(msg).toMatch(/fewer placements \/ shorter asset URLs/)
56
+ expect(E_RENDER_URL_TOO_LONG).toBe('E_RENDER_URL_TOO_LONG')
57
+ })
58
+
59
+ it('a realistic oversize request (7 placements × 1.9 KB asset URLs, the prod 431 repro) is refused before the seal', () => {
60
+ // The resolver base64-encodes the design array into `assets=`: 7 × ~1.9 KB
61
+ // → ~18 KB, which the render box's 16 KiB header limit answered with a
62
+ // bare 431 (2026-09-06). Model the expansion the way buildMockupUrl does.
63
+ const asset = 'https://dqMwU8Jct3.storage.snowcone.app/demo/demo-001.jpg?pad=' + 'x'.repeat(1850)
64
+ const design = ['front', 'placket', 'back', 'left_sleeve', 'right_sleeve', 'inner_collar', 'outer_collar'].map(
65
+ (placement) => ({ imageUrl: asset, placement }),
66
+ )
67
+ const assets = Buffer.from(JSON.stringify(design)).toString('base64')
68
+ expect(renderUrlLengthError(path + encodeURIComponent(assets), design.length)).not.toBeNull()
69
+ // …while the single-placement shape of the same asset URL fits comfortably.
70
+ const one = Buffer.from(JSON.stringify(design.slice(0, 1))).toString('base64')
71
+ expect(renderUrlLengthError(path + encodeURIComponent(one), 1)).toBeNull()
72
+ })
73
+ })
@@ -5,9 +5,11 @@ import {
5
5
  normalizeAlbum,
6
6
  resolveAlbumPagePlacement,
7
7
  resolveVariant,
8
+ unknownOptionPick,
8
9
  slugify,
9
10
  type ResolvedPlacement,
10
11
  type ResolvedProduct,
12
+ fetchProduct,
11
13
  } from "../src/resolve";
12
14
 
13
15
  // A size×color-style product WITH combinations (picks select the SKU).
@@ -83,6 +85,13 @@ describe("looksLikeResolveRequest", () => {
83
85
  const u = (path: string, host = "img.snowcone.app") =>
84
86
  new URL(`https://${host}${path}`);
85
87
 
88
+ // eng/0049 F3: HEAD must take the same path as GET so `curl -I` on an
89
+ // img.snowcone.app URL never lands on the JSON default route.
90
+ it("treats HEAD like GET on the img host (F3)", () => {
91
+ expect(looksLikeResolveRequest("HEAD", "img.snowcone.app", u("/JFBH0Q"))).toBe(true);
92
+ expect(looksLikeResolveRequest("POST", "img.snowcone.app", u("/JFBH0Q"))).toBe(false);
93
+ });
94
+
86
95
  it("resolves on the prod img host (leading label)", () => {
87
96
  expect(
88
97
  looksLikeResolveRequest("GET", "img.snowcone.app", u("/JFBH0Q"))
@@ -436,3 +445,53 @@ describe("assembleArtwork (base + override, ADR-0089)", () => {
436
445
  expect(r.elements).toHaveLength(0);
437
446
  });
438
447
  });
448
+
449
+ describe("fetchProduct render version (pv=)", () => {
450
+ const rawTee = {
451
+ id: "T",
452
+ variants: [{ gvid: "g1" }],
453
+ mockups: [{ id: "m1", gvids: ["g1"] }],
454
+ placements: [{ key: "front", label: "Front", type: "image", width: 12, height: 16 }],
455
+ defaultGvid: "g1",
456
+ options: { attributes: {}, combinations: [] },
457
+ album: null,
458
+ };
459
+ const kvWith = (record: unknown) =>
460
+ ({ get: async () => record }) as unknown as KVNamespace;
461
+
462
+ it("surfaces the backend's renderVersion", async () => {
463
+ const p = await fetchProduct("T", kvWith({ version: "v1", renderVersion: "r1", raw: rawTee }));
464
+ expect(p?.version).toBe("v1");
465
+ expect(p?.renderVersion).toBe("r1");
466
+ });
467
+
468
+ it("falls back to version for records published before renderVersion existed", async () => {
469
+ const p = await fetchProduct("T", kvWith({ version: "v1", raw: rawTee }));
470
+ expect(p?.renderVersion).toBe("v1");
471
+ });
472
+ });
473
+
474
+ describe("unknownOptionPick (E_OPTION_NOT_FOUND / E_OPTION_CHOICE_NOT_FOUND)", () => {
475
+ it("accepts valid picks case-insensitively and no picks at all", () => {
476
+ expect(unknownOptionPick(tee, {})).toBeNull();
477
+ expect(unknownOptionPick(tee, { size: "m" })).toBeNull();
478
+ expect(unknownOptionPick(cap, { pocket: "left chest" })).toBeNull();
479
+ });
480
+
481
+ it("names an unknown attribute with the valid ones", () => {
482
+ expect(unknownOptionPick(tee, { Colour: "Red" })).toEqual({
483
+ attribute: "Colour", choice: "Red", validAttributes: ["Size"], validChoices: null,
484
+ });
485
+ });
486
+
487
+ it("names an unknown choice with the attribute's choices (a render-only underlay pick that would otherwise render with no underlay)", () => {
488
+ expect(unknownOptionPick(cap, { Pocket: "Right chest" })).toEqual({
489
+ attribute: "Pocket", choice: "Right chest", validAttributes: ["Crown", "Pocket"], validChoices: ["None", "Left chest"],
490
+ });
491
+ expect(unknownOptionPick(tee, { Size: "XXL" })?.validChoices).toEqual(["S", "M", "L"]);
492
+ });
493
+
494
+ it("an attribute with no listed choices accepts any value (nothing to validate against)", () => {
495
+ expect(unknownOptionPick(cap, { Crown: "anything" })).toBeNull();
496
+ });
497
+ });
@@ -0,0 +1,84 @@
1
+ import crypto from "node:crypto";
2
+
3
+ import { describe, expect, it } from "vitest";
4
+
5
+ import { signUrl, signUrlV2, mintSeal, SEAL_V2_PREFIX } from "../src/signing";
6
+
7
+ /**
8
+ * rc#262 — the edge signs, the box only verifies.
9
+ *
10
+ * These tests pin the exact contract the rendercenter verifier
11
+ * (api/src/utils/seal-ed25519.ts) implements, using an INDEPENDENT
12
+ * implementation (node:crypto) to verify what WebCrypto produced. If the two
13
+ * runtimes ever disagree, that is precisely the failure this catches — a
14
+ * seal that mints fine at the edge and 401s on every box.
15
+ */
16
+
17
+ const kp = crypto.generateKeyPairSync("ed25519");
18
+ const PKCS8_B64 = kp.privateKey.export({ type: "pkcs8", format: "der" }).toString("base64");
19
+ const RAW_PUB = kp.publicKey.export({ type: "spki", format: "der" }).subarray(12);
20
+
21
+ /** Verify exactly the way a box does: raw 32-byte pubkey, SPKI-wrapped. */
22
+ function boxVerifies(canonical: string, seal: string): boolean {
23
+ const sig = Buffer.from(seal.slice(SEAL_V2_PREFIX.length), "base64url");
24
+ const pub = crypto.createPublicKey({
25
+ key: Buffer.concat([Buffer.from("302a300506032b6570032100", "hex"), RAW_PUB]),
26
+ format: "der",
27
+ type: "spki",
28
+ });
29
+ return crypto.verify(null, Buffer.from(canonical), pub, sig);
30
+ }
31
+
32
+ describe("signUrlV2", () => {
33
+ const canonical = "/mockup?product=tee&width=800";
34
+
35
+ it("mints a seal a box can verify with only the public key", async () => {
36
+ const seal = await signUrlV2(canonical, PKCS8_B64);
37
+ expect(seal.startsWith(SEAL_V2_PREFIX)).toBe(true);
38
+ expect(boxVerifies(canonical, seal)).toBe(true);
39
+ });
40
+
41
+ it("produces a 64-byte signature (86 base64url chars)", async () => {
42
+ const seal = await signUrlV2(canonical, PKCS8_B64);
43
+ expect(seal.slice(SEAL_V2_PREFIX.length)).toHaveLength(86);
44
+ });
45
+
46
+ it("is URL-safe — no +, / or = to escape", async () => {
47
+ const seal = await signUrlV2(canonical, PKCS8_B64);
48
+ expect(seal).toMatch(/^v2\.[A-Za-z0-9_-]+$/);
49
+ });
50
+
51
+ it("does not verify against a different canonical string", async () => {
52
+ const seal = await signUrlV2(canonical, PKCS8_B64);
53
+ expect(boxVerifies("/mockup?product=tee&width=4000", seal)).toBe(false);
54
+ });
55
+
56
+ it("throws a named error on an unusable key rather than downgrading", async () => {
57
+ // A silent fall back to a v1 HMAC seal would quietly undo the migration.
58
+ await expect(signUrlV2(canonical, "bm90LWEta2V5")).rejects.toThrow(
59
+ /E_SEAL_PRIVATE_KEY_INVALID/,
60
+ );
61
+ });
62
+ });
63
+
64
+ describe("mintSeal rollout gate", () => {
65
+ const canonical = "/mockup?product=tee&width=800";
66
+
67
+ it("mints a legacy HMAC seal when no Ed25519 key is configured", async () => {
68
+ const seal = await mintSeal(canonical, "hmac-secret", undefined);
69
+ expect(seal).toBe(await signUrl(canonical, "hmac-secret"));
70
+ expect(seal).toMatch(/^[0-9a-f]{16}$/);
71
+ });
72
+
73
+ it("mints v2 as soon as the Ed25519 key is present — presence IS the intent", async () => {
74
+ const seal = await mintSeal(canonical, "hmac-secret", PKCS8_B64);
75
+ expect(boxVerifies(canonical, seal)).toBe(true);
76
+ });
77
+
78
+ it("v1 and v2 seals are never confusable", async () => {
79
+ const v1 = await mintSeal(canonical, "hmac-secret", undefined);
80
+ const v2 = await mintSeal(canonical, "hmac-secret", PKCS8_B64);
81
+ expect(v1.includes(".")).toBe(false);
82
+ expect(v2.startsWith("v2.")).toBe(true);
83
+ });
84
+ });
package/wrangler.jsonc CHANGED
@@ -30,6 +30,8 @@
30
30
  // to override these prod defaults. For standalone `pnpm dev`, copy
31
31
  // .dev.vars.example -> .dev.vars.
32
32
  "vars": {
33
+ // Our nine metro relays (relay-<metro>-1): the production-shape load generator. Exact IPs; change via PR.
34
+ "LOADTEST_EXEMPT_IPS": "172.236.245.89,139.144.31.189,45.79.3.111,172.104.24.94,172.234.136.102,172.235.133.146,172.237.142.112,172.234.252.106,50.116.2.79",
33
35
  "TTL_DEFAULT": "86400",
34
36
  "LOG_LEVEL": "info",
35
37
  // MEILISEARCH_API_KEY is the public read-only search key (same as apps/www);