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

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"]

package/template/private-app/README.md

@@ -0,0 +1,45 @@
+# my-app
+
+A Storefront Private App, scaffolded by `tot app scaffold`. See
+[the Private Apps devbook](https://github.com/tokenoftrust/storefront/blob/main/docs/private-apps/devbook/private-apps-devbook.md)
+for the full contract this manifest and receiver implement.
+
+## What's here
+
+- **`tot-app.json`** — your app's manifest: identity, scopes, webhook
+  subscriptions, widgets. Validated against
+  [`tot-app.schema.json`](https://github.com/tokenoftrust/storefront/blob/main/docs/private-apps/contract/tot-app.schema.json).
+  Everything here is a PLACEHOLDER — edit `id`, `owner`, `webhooks.endpoint`,
+  and `scopes` for your real app before you install it anywhere.
+- **`fixtures/`** — sample CloudEvents (from `docs/private-apps/contract/examples/`)
+  you can sign and deliver to your own receiver locally, before you have a
+  real install. Add one fixture per topic you subscribe to.
+- **`server.js`** — a minimal Node HTTP receiver for `webhooks.endpoint`. It
+  verifies the RFC 9421 HTTP Message Signature + RFC 9530 Content-Digest on
+  every inbound request before trusting the body — replace the handler logic,
+  keep the verification.
+- **`Dockerfile`** — only relevant if you set `installMode: "hosted"`; ignored
+  for `"external"` apps (the default here).
+- **`.env.example`** — copy to `.env`; no real values are included.
+
+## Local loop (no network, no real ToT account needed)
+
+```
+tot app dev validate            # lint tot-app.json against the contract
+node server.js &                # start the stub receiver
+tot app dev emit order.created  # sign a fixture CloudEvent and POST it in
+tot app dev mint                 # mint a dev widget-launch JWT against an ephemeral key
+```
+
+`tot app dev` generates its own throwaway RS256 keypair per app directory
+(`.tot/dev-keys.json`, gitignored) so signing and verifying works fully
+offline — nothing here is a real ToT-issued credential. Run `tot app dev --help`
+for the full command surface.
+
+## Going live
+
+1. Point `webhooks.endpoint` at your real, publicly reachable HTTPS receiver.
+2. Get your manifest installed for a real `(tenant, env)` — this issues your
+   real client credentials; nothing above touches them.
+3. Swap the dev-only signature verification for the real gateway's published
+   JWKS/signing-key metadata (see the devbook's Signature Verification section).

package/template/private-app/fixtures/order.created.cloudevent.json

@@ -0,0 +1,36 @@
+{
+  "specversion": "1.0",
+  "id": "evt_01J9Z3Q7M2K8V6C4B0N5X7Y2A1",
+  "source": "/tenants/acme/storefront",
+  "type": "com.tokenoftrust.storefront.order.created",
+  "time": "2026-07-21T18:42:07.512Z",
+  "datacontenttype": "application/json",
+  "dataschemaversion": "1",
+  "tenantid": "acme",
+  "appinstallid": "inst_01J9Z2R4H5T3W1P8D6F0K9M2C7",
+  "retrycount": 0,
+  "totrequestid": "req_7f3c9a1e2b4d",
+  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+  "data": {
+    "id": "ord_10482",
+    "status": "created",
+    "currency": "USD",
+    "customerHash": "cus_h_9a7f2c4e8b1d6033",
+    "subtotal": 84.0,
+    "total": 91.35,
+    "lineItems": [
+      {
+        "sku": "VAPE-KIT-STARTER",
+        "handle": "starter-kit",
+        "quantity": 1,
+        "lineTotal": 49.0
+      },
+      {
+        "sku": "PODS-MENTHOL-4PK",
+        "handle": "menthol-pods-4pk",
+        "quantity": 1,
+        "lineTotal": 35.0
+      }
+    ]
+  }
+}

package/template/private-app/server.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * Minimal webhook receiver stub for a Storefront Private App. Verifies the
+ * RFC 9421 HTTP Message Signature + RFC 9530 Content-Digest on every inbound
+ * request BEFORE trusting the body — replace the "handle the event" bit
+ * below, keep the verification.
+ *
+ * Trusts the public key `tot app dev` wrote to .tot/dev-keys.json (re-read on
+ * every request, so it always sees the harness's current key). That file is
+ * dev-only scaffolding: your real receiver checks against the platform's
+ * published JWKS/signing-key metadata instead — see the devbook's Signature
+ * Verification section.
+ */
+import { createServer } from "node:http";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { verifyWebhookSignature } from "./lib/private-apps-devkit.mjs";
+
+const PORT = Number(process.env.PORT || 8787);
+const DEV_KEYS_PATH = join(process.cwd(), ".tot", "dev-keys.json");
+
+function loadDevPublicKey() {
+  if (!existsSync(DEV_KEYS_PATH)) return null;
+  const { publicKeyJwk } = JSON.parse(readFileSync(DEV_KEYS_PATH, "utf8"));
+  return crypto.subtle.importKey("jwk", publicKeyJwk, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["verify"]);
+}
+
+function readBody(req) {
+  return new Promise((resolvePromise, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolvePromise(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+
+const server = createServer(async (req, res) => {
+  const requestId = req.headers["tot-request-id"] || "(none)";
+  if (req.method !== "POST") {
+    res.writeHead(405).end();
+    return;
+  }
+
+  const body = await readBody(req);
+  const publicKey = await loadDevPublicKey();
+  if (!publicKey) {
+    console.error(`[${requestId}] no .tot/dev-keys.json — run \`tot app dev emit\` first`);
+    res.writeHead(401, { "content-type": "application/json" }).end(JSON.stringify({ error: "no trusted key on file" }));
+    return;
+  }
+
+  const result = await verifyWebhookSignature({
+    method: req.method,
+    url: `http://${req.headers.host}${req.url}`,
+    body,
+    headers: {
+      "content-digest": req.headers["content-digest"],
+      "signature-input": req.headers["signature-input"],
+      signature: req.headers["signature"],
+    },
+    publicKey,
+  });
+
+  if (!result.ok) {
+    console.error(`[${requestId}] signature verification FAILED: ${result.code} — ${result.reason}`);
+    res.writeHead(401, { "content-type": "application/json" }).end(JSON.stringify(result));
+    return;
+  }
+
+  console.log(`[${requestId}] verified delivery (keyid=${result.keyid}, created=${result.created})`);
+  // ── Handle the event ────────────────────────────────────────────────────
+  const event = JSON.parse(body);
+  console.log(`[${requestId}] ${event.type} for tenant ${event.tenantid}`);
+  // ─────────────────────────────────────────────────────────────────────────
+
+  res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ ok: true }));
+});
+
+server.listen(PORT, () => {
+  console.log(`webhook receiver listening on http://localhost:${PORT} (POST here — see tot-app.json webhooks.endpoint)`);
+});