@tokenoftrust/cli 1.3.4-rc.3 → 1.3.4-rc.5

package/src/validate.mjs

@@ -7,8 +7,10 @@
  * mirror the reconcile pipeline's own gate (@tot/private-controlplane
  * customization-reconcile.ts `mapToArtifact` / `validateRawHtml`). Kept in step
  * with the in-repo source of truth `scripts/tenant/validate.mjs` (which the CI
- * regression test imports). FOLLOW-UP: collapse the two onto this module as the
- * single source once the package is the install surface.
+ * regression test imports) — including its platform-route awareness (commerce
+ * tenants own /collections, /products/<handle>, /search, /saved, /account, /cart,
+ * so links into those are not false `link-dangling` warnings). FOLLOW-UP: collapse
+ * the two onto this module as the single source once the package is the install surface.
  *
  * Pure + dependency-free (readFileSync only). `validateTenant(dir)` is the entry
  * point; `validateConfigShape` is exported for focused testing.
@@ -333,10 +335,72 @@ const HREF_RE = /\bhref\s*=\s*"([^"]*)"/gi;
 const SRC_RE = /\b(?:src|srcset)\s*=\s*"([^"]*)"/gi;
 const STYLE_OPEN_WITH_ATTRS_RE = /<style\s+[^>]*>/i;
 
+// --- platform-owned routes (framework surfaces, NOT tenant pages) ------------
+/**
+ * When the tenant is served BY this ToT storefront platform, the platform itself
+ * owns a set of framework routes — catalog (`/collections`, `/collections/<handle>`,
+ * `/products/<handle>`), `/search`, `/saved`, the auth/account route (`/account`),
+ * and `/cart` when cart/checkout is on. A COMMERCE tenant that links into those is
+ * linking to a live platform surface, so such links must NOT be flagged
+ * `link-dangling` — only genuinely-missing tenant pages/assets should warn.
+ *
+ * MARKETING tenants get none of these (their commerce affordances are off), so they
+ * stay strict. Standalone / unresolved hosts also stay conservative — they can't
+ * assume the eventual host is this platform — UNLESS the config resolves the host
+ * (`"hostPlatform": "tot-storefront"`).
+ *
+ * The route→feature mapping mirrors `resolveTenantFeatures` in
+ * `@tot/public-runtime` tenant.ts (catalog / productSearch / savedItems) — keep in step.
+ */
+const COMMERCE_ROUTE_FEATURES = { catalog: true, productSearch: true, savedItems: true };
+
+/**
+ * @param {any} config parsed `.tot/config.json` (or null)
+ * @param {boolean} hostIsPlatform is the serving host this ToT storefront platform?
+ * @returns {{active:boolean, owns:(path:string)=>boolean}}
+ */
+function resolvePlatformRouteOwnership(config, hostIsPlatform) {
+  const inert = { active: false, owns: () => false };
+  if (!hostIsPlatform) return inert; // standalone / unresolved host → conservative
+  const siteType = config?.siteType ?? "commerce"; // unset == commerce (platform default)
+  if (siteType === "marketing") return inert; // marketing owns no commerce routes
+  // commerce feature defaults, with any explicit per-flag overrides layered on
+  const features = { ...COMMERCE_ROUTE_FEATURES };
+  const overrides = config?.features;
+  if (overrides && typeof overrides === "object") {
+    for (const [k, v] of Object.entries(overrides)) if (v !== undefined && k in features) features[k] = v;
+  }
+  const cartEnabled = config?.capabilities?.cartCheckout?.enabled ?? true; // commerce default: on
+
+  const exact = new Set(["/account"]); // the auth/account route the platform currently serves
+  const prefixes = ["/account/"];
+  if (features.catalog) {
+    exact.add("/collections");
+    prefixes.push("/collections/", "/products/");
+  }
+  if (features.productSearch) exact.add("/search");
+  if (features.savedItems) exact.add("/saved");
+  if (cartEnabled) {
+    exact.add("/cart");
+    prefixes.push("/cart/");
+  }
+  return {
+    active: true,
+    owns(path) {
+      const norm = path.replace(/\/+$/, "") || "/";
+      if (exact.has(norm)) return true;
+      return prefixes.some((p) => path.startsWith(p));
+    },
+  };
+}
+
 /**
  * Full static validation of a tenant directory (content/ public/ theme.json [.tot/]).
  * @param {string} tenantDir absolute path to the tenant dir
- * @param {{tenantId?:string, scope?:string}} [opts]
+ * @param {{tenantId?:string, scope?:string, mode?:"monorepo"|"workspace"}} [opts]
+ *   `mode` — "monorepo" (default): served by this platform, so commerce tenants own
+ *   the framework routes. "workspace": a standalone checkout, conservative about
+ *   platform-route ownership unless the config resolves the host (`hostPlatform`).
  * @returns {{ok:boolean, findings:Finding[]}}
  */
 export function validateTenant(tenantDir, opts = {}) {
@@ -370,6 +434,10 @@ export function validateTenant(tenantDir, opts = {}) {
     );
   }
   const scope = opts.scope || config?.scope;
+  // platform-route awareness: which framework routes the host platform owns for this tenant
+  const mode = opts.mode === "workspace" ? "workspace" : "monorepo";
+  const hostIsPlatform = mode === "monorepo" || config?.hostPlatform === "tot-storefront";
+  const platformRoutes = resolvePlatformRouteOwnership(config, hostIsPlatform);
   if (config?.capabilities) {
     findings.push(...validateCapabilitiesDoc(config.capabilities, ".tot/config.json capabilities", config));
   }
@@ -456,7 +524,7 @@ export function validateTenant(tenantDir, opts = {}) {
     }
 
     for (const m of html.matchAll(HREF_RE)) {
-      findings.push(...checkLink(m[1].trim(), r, scope, pageTargets));
+      findings.push(...checkLink(m[1].trim(), r, scope, pageTargets, platformRoutes.owns));
     }
     for (const m of html.matchAll(SRC_RE)) {
       const f = checkAsset(m[1].trim(), r, publicDir, opts.tenantId || config?.tenant);
@@ -480,7 +548,7 @@ function buildPageTargetSet(contentDir, pagesDir) {
   return set;
 }
 
-function checkLink(href, file, scope, pageTargets) {
+function checkLink(href, file, scope, pageTargets, ownsPlatformRoute = () => false) {
   const out = [];
   if (!href || href.startsWith("#") || href.startsWith("mailto:") || href.startsWith("tel:")) return out;
   if (/^https?:\/\/localhost(?::\d+)?/i.test(href)) {
@@ -501,9 +569,10 @@ function checkLink(href, file, scope, pageTargets) {
     if (href.startsWith("/tenants/")) return out;
     const path = href.split(/[?#]/)[0];
     const norm = path.replace(/\/+$/, "") || "/";
-    if (!pageTargets.has(path) && !pageTargets.has(norm) && !pageTargets.has(norm + "/")) {
-      out.push(mk(WARN, "link-dangling", file, `internal link ${path} does not resolve to a known page (would 404)`));
-    }
+    if (pageTargets.has(path) || pageTargets.has(norm) || pageTargets.has(norm + "/")) return out;
+    // a framework route the host platform owns (e.g. /collections, /account) is not a dangling tenant page
+    if (ownsPlatformRoute(path)) return out;
+    out.push(mk(WARN, "link-dangling", file, `internal link ${path} does not resolve to a known page (would 404)`));
     return out;
   }
   out.push(mk(WARN, "link-relative", file, `relative link "${href}" — internal links should be root-absolute (/foo/)`));

package/src/vendor/private-apps-devkit.mjs

@@ -0,0 +1,490 @@
+/**
+ * Vendored subset of `@tokenoftrust/private-apps-devkit` (PrivateApps epic D6
+ * Chunk B, `packages/private-apps-devkit/src/{signing,jwt,manifest}.ts`) — for
+ * `tot app` (D6 Chunk C+D) to sign/verify webhook deliveries, mint dev JWTs,
+ * and validate `tot-app.json` manifests WITHOUT a package.json dependency on
+ * that package.
+ *
+ * WHY THIS IS A COPY, NOT AN IMPORT (the devkit's own module doc explicitly
+ * hoped for the opposite — "without forking security-critical crypto into a
+ * second, drifting copy"): the devkit is `"private": true` and ships ONLY
+ * TypeScript source (`main`/`exports` both point at `src/index.ts`, no build
+ * output committed). That's fine for its other consumer
+ * (`apps/storefront`, an Astro/Vite app that transpiles TS at build time) but
+ * `@tokenoftrust/cli` is a *published, dependency-free* npm package
+ * (`.github/workflows/publish-cli.yml` runs `node --test` then a bare
+ * `npm publish` — no install step, no bundler, Node 20 — and the CLI's own
+ * `engines` promises `>=20`, well below the Node 22.6+/23.6-default needed to
+ * import `.ts` sources directly). A `workspace:*` dependency would publish
+ * literally as the string `"workspace:*"` in the tarball's package.json —
+ * unresolvable by any installer outside this pnpm workspace. So the two
+ * packages cannot share one import today; this file is the deliberate,
+ * clearly-labeled fork until the devkit ships a plain-JS build people outside
+ * the monorepo can install.
+ *
+ * Kept honest three ways:
+ *   1. Every export below is line-for-line the same logic as its `.ts`
+ *      source (types erased, nothing behaviorally changed) — diff against
+ *      `packages/private-apps-devkit/src/{signing,jwt,manifest}.ts` to audit.
+ *   2. `test/app-devkit-parity.test.mjs` cross-verifies interop with the REAL
+ *      devkit (signs with one, verifies with the other) whenever the sibling
+ *      package is resolvable (i.e. inside this pnpm workspace); it skips
+ *      cleanly otherwise, so it never breaks the no-install CI path above.
+ *   3. Web Crypto (`crypto.subtle`) + `Buffer` only, same as the source —
+ *      zero new runtime dependencies.
+ */
+
+// ── signing (RFC 9421 HTTP Message Signatures + RFC 9530 Content-Digest) ───
+
+export const SIGNATURE_LABEL = "sig1";
+
+export const WEBHOOK_SIGNATURE_COVERED_COMPONENTS = ["@method", "@target-uri", "content-digest"];
+
+export const WEBHOOK_SIGNING_HTTPSIG_ALG = "rsa-v1_5-sha256";
+
+/** RFC 9530 `Content-Digest: sha-256=:<base64(SHA-256(body))>:`, via Web Crypto. */
+export async function computeContentDigestSha256(body) {
+  const bytes = new TextEncoder().encode(body);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return `sha-256=:${Buffer.from(digest).toString("base64")}:`;
+}
+
+export function buildSignatureParamsValue(componentIds, params) {
+  const list = componentIds.map((id) => `"${id}"`).join(" ");
+  return `(${list});created=${params.created};keyid="${params.keyid}";alg="${params.alg}"`;
+}
+
+export function buildSignatureBase(covered, signatureParamsValue) {
+  const lines = covered.map(([id, value]) => `"${id}": ${value}`);
+  lines.push(`"@signature-params": ${signatureParamsValue}`);
+  return lines.join("\n");
+}
+
+function coveredComponents(method, url, contentDigest) {
+  return [
+    ["@method", method.toUpperCase()],
+    ["@target-uri", url],
+    ["content-digest", contentDigest],
+  ];
+}
+
+/** Sign one webhook delivery request. The private key never leaves the caller. */
+export async function signWebhookRequest(input) {
+  const created = input.created ?? Math.floor(Date.now() / 1000);
+  const contentDigest = await computeContentDigestSha256(input.body);
+  const paramsValue = buildSignatureParamsValue(WEBHOOK_SIGNATURE_COVERED_COMPONENTS, {
+    created,
+    keyid: input.kid,
+    alg: WEBHOOK_SIGNING_HTTPSIG_ALG,
+  });
+  const base = buildSignatureBase(coveredComponents(input.method, input.url, contentDigest), paramsValue);
+  const signature = await crypto.subtle.sign("RSASSA-PKCS1-v1_5", input.key, new TextEncoder().encode(base));
+  return {
+    headers: {
+      "content-digest": contentDigest,
+      "signature-input": `${SIGNATURE_LABEL}=${paramsValue}`,
+      signature: `${SIGNATURE_LABEL}=:${Buffer.from(signature).toString("base64")}:`,
+    },
+  };
+}
+
+const EXPECTED_COMPONENT_LIST = WEBHOOK_SIGNATURE_COVERED_COMPONENTS.map((id) => `"${id}"`).join(" ");
+const SIGNATURE_INPUT_RE = new RegExp(
+  `^${SIGNATURE_LABEL}=\\(${EXPECTED_COMPONENT_LIST.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\);created=(\\d+);keyid="([^"]*)";alg="([^"]*)"$`,
+);
+const SIGNATURE_RE = new RegExp(`^${SIGNATURE_LABEL}=:([A-Za-z0-9+/=]+):$`);
+
+/** Verify one delivered webhook request against the sender's public key. */
+export async function verifyWebhookSignature(input) {
+  const contentDigestHeader = input.headers["content-digest"];
+  const signatureInputHeader = input.headers["signature-input"];
+  const signatureHeader = input.headers.signature;
+  if (!contentDigestHeader || !signatureInputHeader || !signatureHeader) {
+    return { ok: false, code: "malformed_headers", reason: "missing Content-Digest/Signature-Input/Signature" };
+  }
+
+  const inputMatch = SIGNATURE_INPUT_RE.exec(signatureInputHeader);
+  if (!inputMatch) {
+    return { ok: false, code: "malformed_headers", reason: "Signature-Input does not match the expected shape" };
+  }
+  const sigMatch = SIGNATURE_RE.exec(signatureHeader);
+  if (!sigMatch) {
+    return { ok: false, code: "malformed_headers", reason: "Signature does not match the expected shape" };
+  }
+  const [, createdStr, keyid, alg] = inputMatch;
+  if (alg !== WEBHOOK_SIGNING_HTTPSIG_ALG) {
+    return { ok: false, code: "malformed_headers", reason: `unexpected alg "${alg}"` };
+  }
+
+  const expectedDigest = await computeContentDigestSha256(input.body);
+  if (expectedDigest !== contentDigestHeader) {
+    return { ok: false, code: "content_digest_mismatch", reason: "body does not match Content-Digest header" };
+  }
+
+  const created = Number(createdStr);
+  const paramsValue = buildSignatureParamsValue(WEBHOOK_SIGNATURE_COVERED_COMPONENTS, { created, keyid, alg });
+  const base = buildSignatureBase(coveredComponents(input.method, input.url, contentDigestHeader), paramsValue);
+  const signatureBytes = Buffer.from(sigMatch[1], "base64");
+  const valid = await crypto.subtle.verify(
+    "RSASSA-PKCS1-v1_5",
+    input.publicKey,
+    signatureBytes,
+    new TextEncoder().encode(base),
+  );
+  if (!valid) {
+    return { ok: false, code: "bad_signature", reason: "signature does not verify against the public key" };
+  }
+  return { ok: true, keyid, created };
+}
+
+// ── jwt (minimal hand-rolled RS256 JWS mint/verify, dev-only) ──────────────
+
+export const DEV_JWT_ALG = "RS256";
+
+function base64urlEncodeJson(value) {
+  return Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+}
+
+function base64urlDecodeJson(value) {
+  const decoded = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+  if (typeof decoded !== "object" || decoded === null || Array.isArray(decoded)) {
+    throw new Error("decoded segment is not a JSON object");
+  }
+  return decoded;
+}
+
+/** Mint a compact RS256 JWS. The private key never leaves the caller. */
+export async function mintJwt(input) {
+  const iat = input.issuedAt ?? Math.floor(Date.now() / 1000);
+  const header = { alg: DEV_JWT_ALG, typ: "JWT" };
+  if (input.kid !== undefined) header.kid = input.kid;
+  const payload = {
+    iat,
+    ...(input.expiresAt !== undefined ? { exp: input.expiresAt } : {}),
+    ...input.claims,
+  };
+  const signingInput = `${base64urlEncodeJson(header)}.${base64urlEncodeJson(payload)}`;
+  const signature = await crypto.subtle.sign(
+    "RSASSA-PKCS1-v1_5",
+    input.privateKey,
+    new TextEncoder().encode(signingInput),
+  );
+  return `${signingInput}.${Buffer.from(signature).toString("base64url")}`;
+}
+
+/** Verify a compact RS256 JWS minted by {@link mintJwt} (or any RS256 JWS with this exact 3-part shape). */
+export async function verifyJwt(input) {
+  const parts = input.token.split(".");
+  if (parts.length !== 3) {
+    return { ok: false, code: "malformed", reason: "token is not a 3-part compact JWS" };
+  }
+  const [headerB64, payloadB64, signatureB64] = parts;
+
+  let header;
+  let payload;
+  try {
+    header = base64urlDecodeJson(headerB64);
+    payload = base64urlDecodeJson(payloadB64);
+  } catch (cause) {
+    return {
+      ok: false,
+      code: "malformed",
+      reason: `header/payload is not valid base64url JSON: ${cause instanceof Error ? cause.message : String(cause)}`,
+    };
+  }
+
+  if (header.alg !== DEV_JWT_ALG) {
+    return { ok: false, code: "bad_alg", reason: `unexpected alg "${String(header.alg)}"` };
+  }
+
+  const signingInput = `${headerB64}.${payloadB64}`;
+  const valid = await crypto.subtle.verify(
+    "RSASSA-PKCS1-v1_5",
+    input.publicKey,
+    Buffer.from(signatureB64, "base64url"),
+    new TextEncoder().encode(signingInput),
+  );
+  if (!valid) {
+    return { ok: false, code: "bad_signature", reason: "signature does not verify against the public key" };
+  }
+
+  const now = input.now ?? Math.floor(Date.now() / 1000);
+  if (typeof payload.exp === "number" && payload.exp < now) {
+    return { ok: false, code: "expired", reason: `token expired at ${payload.exp}` };
+  }
+  return { ok: true, header, payload };
+}
+
+/** Generate an ephemeral RS256 keypair for dev/test minting — never a real gateway key. */
+export function generateDevRs256KeyPair() {
+  return crypto.subtle.generateKey(
+    { name: "RSASSA-PKCS1-v1_5", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" },
+    /* extractable */ true,
+    ["sign", "verify"],
+  );
+}
+
+// ── manifest (tot-app.json validator) ──────────────────────────────────────
+
+export const MANIFEST_CONTRACT_VERSION = "1";
+
+export const MANIFEST_SCOPES = [
+  "catalog:read",
+  "orders:read:minimal",
+  "orders:webhook",
+  "customers:read:minimal",
+  "inventory:read",
+  "reports:read",
+  "attribution:write",
+  "widgets:launch",
+];
+
+export const MANIFEST_WEBHOOK_TOPICS = [
+  "app.installed",
+  "app.uninstalled",
+  "catalog.product.updated",
+  "inventory.changed",
+  "order.created",
+  "order.fulfilled",
+  "customer.marketing_consent.updated",
+  "attribution.finalized",
+];
+
+export const MANIFEST_WIDGET_PLACEMENTS = ["product.aside", "home.section", "global.footer"];
+
+export const MANIFEST_INSTALL_MODES = ["external", "hosted"];
+
+export const MANIFEST_TELEMETRY_MODES = ["errors-only", "sampled", "full"];
+
+export const MANIFEST_PII_REDACTIONS = ["default", "strict"];
+
+const ID_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const HTTPS_URI_PATTERN = /^https:\/\/\S+$/;
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const HOSTNAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+
+const TOP_LEVEL_KEYS = [
+  "contractVersion", "id", "name", "version", "owner", "description", "installMode",
+  "scopes", "webhooks", "widgets", "adminLinks", "telemetryMode", "retention", "hosting",
+];
+const OWNER_KEYS = ["name", "email", "url"];
+const WEBHOOKS_KEYS = ["endpoint", "topics", "signatureKeyId"];
+const WIDGET_KEYS = ["placement", "endpoint", "title"];
+const ADMIN_LINK_KEYS = ["label", "href"];
+const RETENTION_KEYS = ["eventLogDays", "piiRedaction"];
+const HOSTING_KEYS = ["image", "allowedHosts"];
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function field(at, key) {
+  return at ? `${at}.${key}` : key;
+}
+
+function rejectUnknownKeys(obj, allowed, at, errors) {
+  const label = at || "manifest";
+  for (const key of Object.keys(obj)) {
+    if (!allowed.includes(key)) errors.push(`${label}: unknown property "${key}"`);
+  }
+}
+
+function requireString(obj, key, at, errors) {
+  const value = obj[key];
+  if (typeof value !== "string" || value.length === 0) {
+    errors.push(`${field(at, key)}: required string is missing`);
+    return undefined;
+  }
+  return value;
+}
+
+function checkEnum(value, allowed, at, errors) {
+  if (typeof value !== "string" || !allowed.includes(value)) {
+    errors.push(`${at}: "${String(value)}" is not one of ${JSON.stringify(allowed)}`);
+  }
+}
+
+function checkPattern(value, pattern, at, errors) {
+  if (typeof value !== "string" || !pattern.test(value)) {
+    errors.push(`${at}: "${String(value)}" does not match the required pattern`);
+  }
+}
+
+function checkUniqueStringArray(value, allowed, at, errors) {
+  if (!Array.isArray(value) || value.length === 0) {
+    errors.push(`${at}: must be a non-empty array`);
+    return [];
+  }
+  const items = value;
+  if (new Set(items).size !== items.length) errors.push(`${at}: items must be unique`);
+  if (allowed) {
+    for (const item of items) checkEnum(item, allowed, `${at}[]`, errors);
+  }
+  return items.filter((item) => typeof item === "string");
+}
+
+function validateOwner(owner, errors) {
+  if (!isPlainObject(owner)) {
+    errors.push("owner: required object is missing");
+    return;
+  }
+  rejectUnknownKeys(owner, OWNER_KEYS, "owner", errors);
+  requireString(owner, "name", "owner", errors);
+  const email = requireString(owner, "email", "owner", errors);
+  if (email !== undefined) checkPattern(email, EMAIL_PATTERN, "owner.email", errors);
+  if (owner.url !== undefined) checkPattern(owner.url, HTTPS_URI_PATTERN, "owner.url", errors);
+}
+
+function validateWebhooks(webhooks, errors) {
+  if (webhooks === undefined) return;
+  if (!isPlainObject(webhooks)) {
+    errors.push("webhooks: must be an object");
+    return;
+  }
+  rejectUnknownKeys(webhooks, WEBHOOKS_KEYS, "webhooks", errors);
+  const endpoint = requireString(webhooks, "endpoint", "webhooks", errors);
+  if (endpoint !== undefined) checkPattern(endpoint, HTTPS_URI_PATTERN, "webhooks.endpoint", errors);
+  if (webhooks.topics === undefined) {
+    errors.push("webhooks.topics: required array is missing");
+  } else {
+    checkUniqueStringArray(webhooks.topics, MANIFEST_WEBHOOK_TOPICS, "webhooks.topics", errors);
+  }
+  if (webhooks.signatureKeyId !== undefined && typeof webhooks.signatureKeyId !== "string") {
+    errors.push("webhooks.signatureKeyId: must be a string");
+  }
+}
+
+function validateWidgets(widgets, errors) {
+  if (widgets === undefined) return;
+  if (!Array.isArray(widgets)) {
+    errors.push("widgets: must be an array");
+    return;
+  }
+  widgets.forEach((widget, index) => {
+    const at = `widgets[${index}]`;
+    if (!isPlainObject(widget)) {
+      errors.push(`${at}: must be an object`);
+      return;
+    }
+    rejectUnknownKeys(widget, WIDGET_KEYS, at, errors);
+    if (widget.placement === undefined) {
+      errors.push(`${at}.placement: required property is missing`);
+    } else {
+      checkEnum(widget.placement, MANIFEST_WIDGET_PLACEMENTS, `${at}.placement`, errors);
+    }
+    // endpoint is required + https (schema: widgets[].endpoint, ^https://), the
+    // origin Storefront frames + allowlists in CSP for this widget.
+    const widgetEndpoint = requireString(widget, "endpoint", at, errors);
+    if (widgetEndpoint !== undefined) {
+      checkPattern(widgetEndpoint, HTTPS_URI_PATTERN, `${at}.endpoint`, errors);
+    }
+    if (widget.title !== undefined && typeof widget.title !== "string") {
+      errors.push(`${at}.title: must be a string`);
+    }
+  });
+}
+
+function validateAdminLinks(adminLinks, errors) {
+  if (adminLinks === undefined) return;
+  if (!Array.isArray(adminLinks)) {
+    errors.push("adminLinks: must be an array");
+    return;
+  }
+  adminLinks.forEach((link, index) => {
+    const at = `adminLinks[${index}]`;
+    if (!isPlainObject(link)) {
+      errors.push(`${at}: must be an object`);
+      return;
+    }
+    rejectUnknownKeys(link, ADMIN_LINK_KEYS, at, errors);
+    requireString(link, "label", at, errors);
+    const href = requireString(link, "href", at, errors);
+    if (href !== undefined) checkPattern(href, HTTPS_URI_PATTERN, `${at}.href`, errors);
+  });
+}
+
+function validateRetention(retention, errors) {
+  if (retention === undefined) return;
+  if (!isPlainObject(retention)) {
+    errors.push("retention: must be an object");
+    return;
+  }
+  rejectUnknownKeys(retention, RETENTION_KEYS, "retention", errors);
+  const eventLogDays = retention.eventLogDays;
+  if (eventLogDays !== undefined) {
+    if (typeof eventLogDays !== "number" || !Number.isInteger(eventLogDays) || eventLogDays < 1 || eventLogDays > 365) {
+      errors.push("retention.eventLogDays: must be an integer between 1 and 365");
+    }
+  }
+  if (retention.piiRedaction !== undefined) {
+    checkEnum(retention.piiRedaction, MANIFEST_PII_REDACTIONS, "retention.piiRedaction", errors);
+  }
+}
+
+function validateHosting(hosting, errors) {
+  if (hosting === undefined) return;
+  if (!isPlainObject(hosting)) {
+    errors.push("hosting: must be an object");
+    return;
+  }
+  rejectUnknownKeys(hosting, HOSTING_KEYS, "hosting", errors);
+  if (hosting.image !== undefined && typeof hosting.image !== "string") {
+    errors.push("hosting.image: must be a string");
+  }
+  if (hosting.allowedHosts !== undefined) {
+    checkUniqueStringArray(hosting.allowedHosts, undefined, "hosting.allowedHosts", errors);
+    if (Array.isArray(hosting.allowedHosts)) {
+      hosting.allowedHosts.forEach((host, index) => {
+        checkPattern(host, HOSTNAME_PATTERN, `hosting.allowedHosts[${index}]`, errors);
+      });
+    }
+  }
+}
+
+/**
+ * Validate a parsed `tot-app.json` manifest against the V1 contract. Returns
+ * every violation found (not just the first).
+ */
+export function validateManifest(input) {
+  const errors = [];
+  if (!isPlainObject(input)) {
+    return { ok: false, errors: ["manifest must be a JSON object"] };
+  }
+
+  rejectUnknownKeys(input, TOP_LEVEL_KEYS, "", errors);
+
+  if (input.contractVersion !== MANIFEST_CONTRACT_VERSION) {
+    errors.push(`contractVersion: must be "${MANIFEST_CONTRACT_VERSION}"`);
+  }
+  const id = requireString(input, "id", "", errors);
+  if (id !== undefined) checkPattern(id, ID_PATTERN, "id", errors);
+  requireString(input, "name", "", errors);
+  const version = requireString(input, "version", "", errors);
+  if (version !== undefined) checkPattern(version, VERSION_PATTERN, "version", errors);
+  validateOwner(input.owner, errors);
+  if (input.description !== undefined && typeof input.description !== "string") {
+    errors.push("description: must be a string");
+  }
+  if (input.installMode === undefined) {
+    errors.push("installMode: required property is missing");
+  } else {
+    checkEnum(input.installMode, MANIFEST_INSTALL_MODES, "installMode", errors);
+  }
+  if (input.scopes === undefined) {
+    errors.push("scopes: required array is missing");
+  } else {
+    checkUniqueStringArray(input.scopes, MANIFEST_SCOPES, "scopes", errors);
+  }
+  validateWebhooks(input.webhooks, errors);
+  validateWidgets(input.widgets, errors);
+  validateAdminLinks(input.adminLinks, errors);
+  if (input.telemetryMode !== undefined) {
+    checkEnum(input.telemetryMode, MANIFEST_TELEMETRY_MODES, "telemetryMode", errors);
+  }
+  validateRetention(input.retention, errors);
+  validateHosting(input.hosting, errors);
+
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, manifest: input };
+}

package/template/private-app/.env.example

@@ -0,0 +1,10 @@
+# Copy to .env and fill in for your own deployment. No real values are checked
+# in here — this file only documents the shape.
+
+# Port the stub webhook receiver (server.js) listens on.
+PORT=8787
+
+# Must match tot-app.json's webhooks.signatureKeyId. `tot app dev` writes the
+# matching public key alongside this app at .tot/dev-keys.json for local runs
+# — you don't need to set anything here to exercise the receiver locally.
+SIGNATURE_KEY_ID=dev-key-1

package/template/private-app/Dockerfile

@@ -0,0 +1,12 @@
+# Placeholder for the optional ToT-hosted runtime (installMode: "hosted",
+# see tot-app.json + docs/private-apps/contract/tot-app.schema.json#hosting).
+# The SAME manifest works for "external" (self-hosted, this Dockerfile is
+# informational only) and "hosted" (ToT runs this image; egress is deny-all
+# except tot-app.json's hosting.allowedHosts).
+FROM node:20-slim
+WORKDIR /app
+COPY package*.json ./
+RUN [ -f package.json ] && npm install --omit=dev || true
+COPY . .
+EXPOSE 8787
+CMD ["node", "server.js"]