@tokenoftrust/storefront-runner 2.0.15 → 2.0.17

package/apps/storefront/src/lib/fixtures/ws3-readonly-clone-preflight/index.ts

@@ -0,0 +1,495 @@
+/**
+ * Fixture-only WS3 clone-read preflight.
+ *
+ * This is a pure conformance boundary over caller-supplied synthetic metadata.
+ * It intentionally has no imports and no execution seam: it cannot resolve,
+ * create, update, reconcile, or otherwise operate a clone. WS3 remains the owner
+ * of clone execution and public contract publication.
+ */
+
+export const WS3_CLONE_READ_PREFLIGHT_SCHEMA = "ws3-clone-read-preflight.v1" as const;
+
+const READ_CAPABILITIES = ["read:metadata", "read:manifest", "read:invariants"] as const;
+type ReadCapability = (typeof READ_CAPABILITIES)[number];
+
+export interface SyntheticCloneReadMetadata {
+  schemaVersion: typeof WS3_CLONE_READ_PREFLIGHT_SCHEMA;
+  fixtureId: string;
+  synthetic: true;
+  tenant: {
+    tenantId: string;
+    tenantTier: "regulated-commerce";
+  };
+  clone: {
+    cloneId: string;
+    snapshotReference: string;
+    sourceRevision: string;
+    capturedAt: string;
+  };
+  requestedCapabilities: ReadCapability[];
+  readFacts: {
+    manifestPresent: boolean;
+    catalogRecordCount: number;
+    orderRecordCount: number;
+    integrationReferenceCount: number;
+  };
+}
+
+export type CloneReadPreflightBlockerCode =
+  | "invalid-shape"
+  | "not-explicitly-synthetic"
+  | "live-looking-identity"
+  | "unsafe-field"
+  | "live-endpoint"
+  | "mutation-capability-refused"
+  | "unsupported-capability"
+  | "manifest-missing";
+
+export interface CloneReadPreflightBlocker {
+  code: CloneReadPreflightBlockerCode;
+  path: string;
+  message: string;
+}
+
+export interface CloneReadPreflightInvariant {
+  id:
+    | "synthetic-identities-only"
+    | "read-capabilities-only"
+    | "sanitized-offline-snapshot"
+    | "manifest-observed";
+  passed: boolean;
+}
+
+export interface CloneReadPreflightResult {
+  schemaVersion: typeof WS3_CLONE_READ_PREFLIGHT_SCHEMA;
+  ready: boolean;
+  blockers: CloneReadPreflightBlocker[];
+  invariants: CloneReadPreflightInvariant[];
+  observed: {
+    fixtureId: string | null;
+    tenantId: string | null;
+    cloneId: string | null;
+    snapshotReference: string | null;
+    requestedCapabilities: ReadCapability[];
+    readFacts: SyntheticCloneReadMetadata["readFacts"] | null;
+  };
+}
+
+const MUTATION_CAPABILITY = /(^|:)(create|update|execute|write|delete|mutate|reconcile|promote|deploy)(:|$)/i;
+const UNSAFE_KEY = /(authorization|credential|secret|password|api[-_]?key|access[-_]?token|refresh[-_]?token|private[-_]?key|email|phone|address|(?:^|[-_])name(?:$|[-_]))/i;
+const CREDENTIAL_VALUE = /(-----BEGIN [A-Z ]*PRIVATE KEY-----|\bBearer\s+[A-Za-z0-9._~-]+|\bAKIA[0-9A-Z]{16}\b)/;
+const EMAIL_VALUE = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i;
+const PHONE_VALUE = /\b(?:\+?\d{1,3}[-. ]?)?(?:\(\d{3}\)|\d{3})[-. ]\d{3}[-. ]\d{4}\b/;
+const PAYMENT_VALUE = /(?:^|[^0-9])(?:\d{4}[- ]?){3}\d{4}(?:$|[^0-9])|(?:^|[^0-9])\d{13,19}(?:$|[^0-9])/;
+const GOVERNMENT_ID_VALUE = /(?:^|[^0-9])(?:\d{3}-\d{2}-\d{4}|\d{2}-\d{7}|\d{9})(?:$|[^0-9])/;
+const ADDRESS_VALUE = /\b\d{1,6}(?:[- ]+[A-Za-z][A-Za-z0-9.']*){1,5}[- ]+(?:street|st|avenue|ave|road|rd|boulevard|blvd|lane|ln|drive|dr|court|ct|way)\b/i;
+const PERSON_NAME_VALUE = /\b(?:[A-Z][a-z]{1,30}\s+[A-Z][a-z]{1,30}|(?:jane|john)[-_ ]doe)\b/i;
+const LIVE_ENDPOINT = /\b(?:https?|wss?):\/\//i;
+const CODE_VALUE = /(?:<\/?script\b|javascript:|\{\{|=>|\bfunction\s*\(|\b(?:window|document)\.|\bdataLayer\b|\bGTM-[A-Z0-9-]+\b)/i;
+const SHA = /^[a-f0-9]{40}$/;
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+// Local fixture identities stay deliberately closed until WS3 publishes a public read contract.
+const FIXTURE_ID = /^synthetic-ws3-regulated-clone-read-v1$/;
+const TENANT_ID = /^synthetic-regulated-source\.test$/;
+const CLONE_LABEL = /^synthetic-risk-read-\d{3}$/;
+const SNAPSHOT_REFERENCE = /^fixture:\/\/synthetic-ws3-clone\/snapshot-\d{3}$/;
+const MAX_SYNTHETIC_READ_COUNT = 999_999;
+
+function record(value: unknown): Record<string, unknown> | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function ownDataValue(value: Record<string, unknown> | null, key: string): unknown {
+  if (!value) return undefined;
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  return descriptor && descriptor.enumerable && Object.hasOwn(descriptor, "value")
+    ? descriptor.value
+    : undefined;
+}
+
+function text(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function isSanitizedText(value: string): boolean {
+  return !(
+    CREDENTIAL_VALUE.test(value) ||
+    EMAIL_VALUE.test(value) ||
+    PHONE_VALUE.test(value) ||
+    PAYMENT_VALUE.test(value) ||
+    GOVERNMENT_ID_VALUE.test(value) ||
+    ADDRESS_VALUE.test(value) ||
+    PERSON_NAME_VALUE.test(value) ||
+    LIVE_ENDPOINT.test(value) ||
+    CODE_VALUE.test(value)
+  );
+}
+
+function exactKeys(
+  value: Record<string, unknown>,
+  expected: readonly string[],
+  path: string,
+  block: (code: CloneReadPreflightBlockerCode, path: string, message: string) => void,
+): void {
+  const allowed = new Set(expected);
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string" || !allowed.has(key)) {
+      block("invalid-shape", path, "contains an unexpected field");
+      continue;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, "value")) {
+      block("invalid-shape", `${path}.${key}`, "must be an enumerable data field");
+    }
+  }
+  for (const key of expected) {
+    if (ownDataValue(value, key) === undefined) {
+      block("invalid-shape", `${path}.${key}`, "required data field is missing");
+    }
+  }
+}
+
+function arrayDataValues(
+  value: unknown,
+  path: string,
+  block: (code: CloneReadPreflightBlockerCode, path: string, message: string) => void,
+): unknown[] | null {
+  if (!Array.isArray(value)) return null;
+  const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+  const length = lengthDescriptor && Object.hasOwn(lengthDescriptor, "value")
+    ? lengthDescriptor.value
+    : -1;
+  if (!Number.isSafeInteger(length) || (length as number) < 0) {
+    block("invalid-shape", path, "array length is invalid");
+    return [];
+  }
+  const result: unknown[] = [];
+  for (let index = 0; index < (length as number); index += 1) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, "value")) {
+      block("invalid-shape", `${path}[${index}]`, "must be an enumerable data item");
+      result.push(undefined);
+    } else {
+      result.push(descriptor.value);
+    }
+  }
+  for (const key of Reflect.ownKeys(value)) {
+    if (key === "length") continue;
+    if (typeof key !== "string" || !/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= (length as number)) {
+      block("invalid-shape", path, "array contains unexpected metadata");
+    }
+  }
+  return result;
+}
+
+function findUnsafeData(
+  value: unknown,
+  block: (code: CloneReadPreflightBlockerCode, path: string, message: string) => void,
+  path = "metadata",
+): void {
+  if (typeof value === "string") {
+    if (CREDENTIAL_VALUE.test(value)) block("unsafe-field", path, "credential-shaped value is forbidden");
+    if (
+      EMAIL_VALUE.test(value) ||
+      PHONE_VALUE.test(value) ||
+      PAYMENT_VALUE.test(value) ||
+      GOVERNMENT_ID_VALUE.test(value) ||
+      ADDRESS_VALUE.test(value) ||
+      PERSON_NAME_VALUE.test(value)
+    ) {
+      block("unsafe-field", path, "PII-shaped value is forbidden");
+    }
+    if (LIVE_ENDPOINT.test(value)) block("live-endpoint", path, "network endpoint values are forbidden");
+    if (CODE_VALUE.test(value)) block("unsafe-field", path, "code-bearing value is forbidden");
+    return;
+  }
+  if (Array.isArray(value)) {
+    const entries = arrayDataValues(value, path, block) ?? [];
+    entries.forEach((entry, index) => findUnsafeData(entry, block, `${path}[${index}]`));
+    return;
+  }
+  const object = record(value);
+  if (!object) {
+    if (value !== null && typeof value === "object") {
+      block("invalid-shape", path, "must be a plain own-data object");
+    }
+    return;
+  }
+  for (const key of Reflect.ownKeys(object)) {
+    if (typeof key !== "string") {
+      block("invalid-shape", path, "contains a non-JSON field");
+      continue;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(object, key);
+    if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, "value")) {
+      block("invalid-shape", path, "contains a non-data field");
+      continue;
+    }
+    if (UNSAFE_KEY.test(key)) block("unsafe-field", path, "contains a PII/secret-shaped field");
+    // Caller-controlled keys never become blocker paths or messages.
+    findUnsafeData(descriptor.value, block, path);
+  }
+}
+
+function syntheticReadCount(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) >= 0 && (value as number) <= MAX_SYNTHETIC_READ_COUNT;
+}
+
+function deepFreeze<T>(value: T): T {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}
+
+/**
+ * Assess synthetic clone-read metadata without invoking any clone or I/O seam.
+ * Invalid input is represented as blockers so callers get a complete, stable
+ * conformance report rather than a partial execution attempt.
+ */
+function assessSyntheticCloneRead(metadata: unknown): Readonly<CloneReadPreflightResult> {
+  const blockers: CloneReadPreflightBlocker[] = [];
+  const seen = new Set<string>();
+  const block = (code: CloneReadPreflightBlockerCode, path: string, message: string): void => {
+    const key = `${code}:${path}:${message}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      blockers.push({ code, path, message });
+    }
+  };
+
+  findUnsafeData(metadata, block);
+  const root = record(metadata);
+  if (!root) {
+    block("invalid-shape", "metadata", "expected an object");
+  } else {
+    exactKeys(
+      root,
+      ["schemaVersion", "fixtureId", "synthetic", "tenant", "clone", "requestedCapabilities", "readFacts"],
+      "metadata",
+      block,
+    );
+  }
+
+  const schemaVersion = ownDataValue(root, "schemaVersion");
+  const synthetic = ownDataValue(root, "synthetic");
+  const fixtureIdCandidate = text(ownDataValue(root, "fixtureId"));
+  const fixtureId =
+    synthetic === true &&
+    fixtureIdCandidate &&
+    FIXTURE_ID.test(fixtureIdCandidate) &&
+    isSanitizedText(fixtureIdCandidate)
+      ? fixtureIdCandidate
+      : null;
+  if (schemaVersion !== WS3_CLONE_READ_PREFLIGHT_SCHEMA) {
+    block("invalid-shape", "metadata.schemaVersion", `expected ${WS3_CLONE_READ_PREFLIGHT_SCHEMA}`);
+  }
+  if (!fixtureId) {
+    block("not-explicitly-synthetic", "metadata", "explicit synthetic metadata and a closed fixture-id format are required");
+  }
+
+  const tenant = record(ownDataValue(root, "tenant"));
+  if (!tenant) {
+    block("invalid-shape", "metadata.tenant", "expected an object");
+  } else {
+    exactKeys(tenant, ["tenantId", "tenantTier"], "metadata.tenant", block);
+  }
+  const tenantIdCandidate = text(ownDataValue(tenant, "tenantId"));
+  const tenantId =
+    tenantIdCandidate && TENANT_ID.test(tenantIdCandidate) && isSanitizedText(tenantIdCandidate)
+      ? tenantIdCandidate
+      : null;
+  if (!tenantId) {
+    block("live-looking-identity", "metadata.tenant.tenantId", "tenantId must use the closed synthetic format");
+  }
+  if (ownDataValue(tenant, "tenantTier") !== "regulated-commerce") {
+    block("invalid-shape", "metadata.tenant.tenantTier", "expected regulated-commerce");
+  }
+
+  const clone = record(ownDataValue(root, "clone"));
+  if (!clone) {
+    block("invalid-shape", "metadata.clone", "expected an object");
+  } else {
+    exactKeys(clone, ["cloneId", "snapshotReference", "sourceRevision", "capturedAt"], "metadata.clone", block);
+  }
+  const cloneIdCandidate = text(ownDataValue(clone, "cloneId"));
+  const cloneParts = cloneIdCandidate?.split("~clone~") ?? [];
+  const cloneLabel = cloneParts.length === 2 ? cloneParts[1] : null;
+  const cloneId =
+    tenantId &&
+    cloneIdCandidate &&
+    cloneParts[0] === tenantId &&
+    cloneLabel &&
+    cloneLabel.length <= 72 &&
+    CLONE_LABEL.test(cloneLabel) &&
+    isSanitizedText(cloneIdCandidate)
+      ? cloneIdCandidate
+      : null;
+  if (!cloneId) {
+    block(
+      "live-looking-identity",
+      "metadata.clone.cloneId",
+      "cloneId must belong to the synthetic tenant and use a synthetic- clone label",
+    );
+  }
+  const snapshotCandidate = text(ownDataValue(clone, "snapshotReference"));
+  const snapshotReference =
+    snapshotCandidate && SNAPSHOT_REFERENCE.test(snapshotCandidate) && isSanitizedText(snapshotCandidate)
+      ? snapshotCandidate
+      : null;
+  if (!snapshotReference) {
+    block("live-endpoint", "metadata.clone.snapshotReference", "only the closed offline fixture-reference format is allowed");
+  }
+  if (!text(ownDataValue(clone, "sourceRevision"))?.match(SHA)) {
+    block("invalid-shape", "metadata.clone.sourceRevision", "expected a fixed 40-character revision");
+  }
+  const capturedAt = text(ownDataValue(clone, "capturedAt"));
+  if (!capturedAt?.match(ISO_UTC) || Number.isNaN(Date.parse(capturedAt))) {
+    block("invalid-shape", "metadata.clone.capturedAt", "expected a canonical UTC timestamp");
+  }
+
+  const requestedCapabilityInput = ownDataValue(root, "requestedCapabilities");
+  const capabilityData = arrayDataValues(requestedCapabilityInput, "metadata.requestedCapabilities", block);
+  const capabilities = capabilityData ?? [];
+  if (!capabilityData) {
+    block("invalid-shape", "metadata.requestedCapabilities", "expected an array");
+  }
+  if (capabilities.length === 0) {
+    block("invalid-shape", "metadata.requestedCapabilities", "at least one read capability is required");
+  }
+  const requestedCapabilities: ReadCapability[] = [];
+  capabilities.forEach((capability, index) => {
+    const path = `metadata.requestedCapabilities[${index}]`;
+    if (typeof capability !== "string") {
+      block("invalid-shape", path, "expected a string");
+      return;
+    }
+    if (MUTATION_CAPABILITY.test(capability)) {
+      block("mutation-capability-refused", path, "mutation capability is not read-only");
+    } else if (!READ_CAPABILITIES.includes(capability as ReadCapability)) {
+      block("unsupported-capability", path, "capability is outside the local fixture contract");
+    } else {
+      requestedCapabilities.push(capability as ReadCapability);
+    }
+  });
+
+  const facts = record(ownDataValue(root, "readFacts"));
+  if (!facts) {
+    block("invalid-shape", "metadata.readFacts", "expected an object");
+  } else {
+    exactKeys(
+      facts,
+      ["manifestPresent", "catalogRecordCount", "orderRecordCount", "integrationReferenceCount"],
+      "metadata.readFacts",
+      block,
+    );
+  }
+  const manifestPresent = ownDataValue(facts, "manifestPresent");
+  const catalogRecordCount = ownDataValue(facts, "catalogRecordCount");
+  const orderRecordCount = ownDataValue(facts, "orderRecordCount");
+  const integrationReferenceCount = ownDataValue(facts, "integrationReferenceCount");
+  if (typeof manifestPresent !== "boolean") {
+    block("invalid-shape", "metadata.readFacts.manifestPresent", "expected a boolean");
+  } else if (!manifestPresent) {
+    block("manifest-missing", "metadata.readFacts.manifestPresent", "read snapshot has no manifest");
+  }
+  if (!syntheticReadCount(catalogRecordCount)) {
+    block("invalid-shape", "metadata.readFacts.catalogRecordCount", "expected an integer from 0 through 999999");
+  }
+  if (!syntheticReadCount(orderRecordCount)) {
+    block("invalid-shape", "metadata.readFacts.orderRecordCount", "expected an integer from 0 through 999999");
+  }
+  if (!syntheticReadCount(integrationReferenceCount)) {
+    block("invalid-shape", "metadata.readFacts.integrationReferenceCount", "expected an integer from 0 through 999999");
+  }
+
+  const hasBlocker = (...codes: CloneReadPreflightBlockerCode[]): boolean =>
+    blockers.some(({ code }) => codes.includes(code));
+  // A skipped accessor, sparse array item, or other malformed data surface means
+  // none of the cross-field security claims can be proven from the whole input.
+  const shapeInspectable = !hasBlocker("invalid-shape");
+  const invariants: CloneReadPreflightInvariant[] = [
+    {
+      id: "synthetic-identities-only",
+      passed: shapeInspectable && !hasBlocker("not-explicitly-synthetic", "live-looking-identity"),
+    },
+    {
+      id: "read-capabilities-only",
+      passed: shapeInspectable && !hasBlocker("mutation-capability-refused", "unsupported-capability"),
+    },
+    {
+      id: "sanitized-offline-snapshot",
+      passed: shapeInspectable && !hasBlocker("unsafe-field", "live-endpoint"),
+    },
+    {
+      id: "manifest-observed",
+      passed: shapeInspectable && !hasBlocker("manifest-missing") && manifestPresent === true,
+    },
+  ];
+
+  const readFacts =
+    facts &&
+    typeof manifestPresent === "boolean" &&
+    syntheticReadCount(catalogRecordCount) &&
+    syntheticReadCount(orderRecordCount) &&
+    syntheticReadCount(integrationReferenceCount)
+      ? {
+          manifestPresent,
+          catalogRecordCount,
+          orderRecordCount,
+          integrationReferenceCount,
+        }
+      : null;
+
+  return deepFreeze({
+    schemaVersion: WS3_CLONE_READ_PREFLIGHT_SCHEMA,
+    ready: blockers.length === 0 && invariants.every(({ passed }) => passed),
+    blockers,
+    invariants,
+    observed: {
+      fixtureId,
+      tenantId,
+      cloneId,
+      snapshotReference,
+      requestedCapabilities,
+      readFacts,
+    },
+  });
+}
+
+function inspectionFailure(): Readonly<CloneReadPreflightResult> {
+  return deepFreeze({
+    schemaVersion: WS3_CLONE_READ_PREFLIGHT_SCHEMA,
+    ready: false,
+    blockers: [{ code: "invalid-shape", path: "metadata", message: "input could not be safely inspected" }],
+    invariants: [
+      { id: "synthetic-identities-only", passed: false },
+      { id: "read-capabilities-only", passed: false },
+      { id: "sanitized-offline-snapshot", passed: false },
+      { id: "manifest-observed", passed: false },
+    ],
+    observed: {
+      fixtureId: null,
+      tenantId: null,
+      cloneId: null,
+      snapshotReference: null,
+      requestedCapabilities: [],
+      readFacts: null,
+    },
+  });
+}
+
+export function preflightSyntheticCloneRead(metadata: unknown): Readonly<CloneReadPreflightResult> {
+  try {
+    return assessSyntheticCloneRead(metadata);
+  } catch {
+    // Proxy traps and other caller-controlled inspection failures are contained;
+    // their thrown text is never copied into the stable conformance result.
+    return inspectionFailure();
+  }
+}

package/apps/storefront/src/pages/blog/index.astro

@@ -5,7 +5,16 @@ import { listBlogPosts } from "@/lib/blog/provider.js";
 
 const { tenant, basePath, canonicalBase, content } = Astro.locals;
 const posts = await listBlogPosts(tenant.tenant_id, content);
-if (posts.length === 0) return new Response(null, { status: 404 });
+// A tenant with no blog content has no blog index, so this is still a 404 — but
+// it is a DIFFERENT 404 from "no such route", and telling them apart from the
+// outside used to be impossible (both were bare and byte-identical). The header
+// says which one this is; a nonexistent route never carries it.
+if (posts.length === 0) {
+  return new Response(null, {
+    status: 404,
+    headers: { "x-tot-blog-collection": "empty" },
+  });
+}
 
 const href = (path: string) => `${basePath}${path}` || "/";
 const tags = [...new Set(posts.flatMap((post) => post.tags))].sort((a, b) => a.localeCompare(b));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.0.15",
+  "version": "2.0.17",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",