@tokenoftrust/storefront-runner 1.4.0 → 1.4.2-rc.0

package/apps/storefront/src/lib/social/tokenStore.ts

@@ -0,0 +1,171 @@
+/**
+ * Encrypted per-`(tenant, network)` outbound social OAuth token store
+ * (social-autopost epic, S2). The one RETRIEVABLE secret store in the
+ * storefront: unlike `app_credentials` (one-way `sha256Hex` for INBOUND auth),
+ * these are access/refresh tokens we must REPLAY to X/LinkedIn, so they are
+ * encrypted-at-rest and decrypted at post time — never hashed.
+ *
+ * Envelope encryption, Workers-native Web Crypto `AES-GCM` (no Node `crypto`):
+ *   - The data-encrypting step runs per write with a fresh random 96-bit IV.
+ *   - The key-encrypting key (KEK) is a Worker env binding (`SOCIAL_TOKEN_KEK`,
+ *     a base64-encoded 256-bit key), imported to a non-extractable `CryptoKey`.
+ *     It is NEVER a column — mirroring how every other real secret here is an
+ *     env binding, not row data (see the `social_tokens` note in schema-apps.ts).
+ *
+ * PURE over injected seams (a `Queryable` for D1, a `CryptoKey` for the KEK) so
+ * the same code serves the real Worker bindings and an in-memory test — the
+ * activity/store.ts convention. `resolveSocialTokenStore()` is the composition
+ * root that wires the real bindings (mirrors `getDispatcher()`); it returns
+ * `null` when either binding is absent so callers degrade rather than throw.
+ */
+import type { Queryable } from "../d1/catalog.js";
+import { readD1, readEnv } from "../env.js";
+
+/** The decrypted token material we persist as one JSON blob under AES-GCM. */
+export interface SocialTokenPayload {
+  accessToken: string;
+  /** OAuth refresh token, when the network issues one (X app-passwords don't). */
+  refreshToken?: string;
+  /** Token expiry, ISO-8601. Absent for long-lived manual creds. */
+  expiresAt?: string;
+}
+
+/** Injected seams a store operation runs over. */
+export interface SocialTokenStoreDeps {
+  db: Queryable;
+  /** AES-GCM key imported from the `SOCIAL_TOKEN_KEK` binding via {@link importKek}. */
+  kek: CryptoKey;
+  /** Clock seam (ISO-8601), overridable in tests. Defaults to `Date.now`. */
+  now?: () => string;
+}
+
+const IV_BYTES = 12; // AES-GCM standard 96-bit nonce.
+
+function nowIso(deps: SocialTokenStoreDeps): string {
+  return (deps.now ?? (() => new Date().toISOString()))();
+}
+
+function toBase64(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s);
+}
+
+function fromBase64(b64: string): Uint8Array<ArrayBuffer> {
+  const s = atob(b64);
+  const bytes = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) bytes[i] = s.charCodeAt(i);
+  return bytes;
+}
+
+/**
+ * Import the raw `SOCIAL_TOKEN_KEK` secret (base64 of a 256-bit key) into a
+ * non-extractable AES-GCM `CryptoKey`. Throws if the decoded key isn't 32 bytes
+ * — a misprovisioned KEK must fail loudly at the composition root, not silently
+ * produce unopenable ciphertext.
+ */
+export async function importKek(rawBase64Key: string): Promise<CryptoKey> {
+  const raw = fromBase64(rawBase64Key.trim());
+  if (raw.length !== 32) {
+    throw new Error(`SOCIAL_TOKEN_KEK must decode to 32 bytes (got ${raw.length})`);
+  }
+  return crypto.subtle.importKey("raw", raw, { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
+}
+
+/** Encrypt a token payload → `{ ciphertext, iv }` (both base64). Fresh IV each call. */
+export async function encryptTokenPayload(
+  kek: CryptoKey,
+  payload: SocialTokenPayload,
+): Promise<{ ciphertext: string; iv: string }> {
+  const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+  const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+  const ct = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, kek, plaintext);
+  return { ciphertext: toBase64(new Uint8Array(ct)), iv: toBase64(iv) };
+}
+
+/** Decrypt a stored `{ ciphertext, iv }` back to the token payload. */
+export async function decryptTokenPayload(
+  kek: CryptoKey,
+  ciphertext: string,
+  iv: string,
+): Promise<SocialTokenPayload> {
+  const pt = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: fromBase64(iv) },
+    kek,
+    fromBase64(ciphertext),
+  );
+  return JSON.parse(new TextDecoder().decode(pt)) as SocialTokenPayload;
+}
+
+/**
+ * Store (or overwrite) the token for `(tenantId, network)`. `INSERT OR REPLACE`
+ * on the composite PK, so this is an idempotent upsert; `created_at` follows the
+ * row's replacement (the natural key is the identity, not a birth timestamp).
+ */
+export async function putSocialToken(
+  deps: SocialTokenStoreDeps,
+  tenantId: string,
+  network: string,
+  payload: SocialTokenPayload,
+): Promise<void> {
+  const { ciphertext, iv } = await encryptTokenPayload(deps.kek, payload);
+  const at = nowIso(deps);
+  await deps.db.run(
+    `INSERT OR REPLACE INTO social_tokens
+       (tenant_id, network, ciphertext, iv, expires_at, created_at, updated_at)
+     VALUES (?,?,?,?,?,?,?)`,
+    tenantId,
+    network,
+    ciphertext,
+    iv,
+    payload.expiresAt ?? null,
+    at,
+    at,
+  );
+}
+
+/** Decrypt and return the token for `(tenantId, network)`, or `null` if none stored. */
+export async function getSocialToken(
+  deps: SocialTokenStoreDeps,
+  tenantId: string,
+  network: string,
+): Promise<SocialTokenPayload | null> {
+  const row = await deps.db.first<{ ciphertext: string; iv: string }>(
+    `SELECT ciphertext, iv FROM social_tokens WHERE tenant_id = ? AND network = ?`,
+    tenantId,
+    network,
+  );
+  if (!row) return null;
+  return decryptTokenPayload(deps.kek, row.ciphertext, row.iv);
+}
+
+/**
+ * Overwrite the token for `(tenantId, network)` with rotated material — the
+ * explicit name for the refresh-token-rotation path. Same write as
+ * {@link putSocialToken}; distinct export so a caller's intent reads at the seam.
+ */
+export async function rotateSocialToken(
+  deps: SocialTokenStoreDeps,
+  tenantId: string,
+  network: string,
+  newPayload: SocialTokenPayload,
+): Promise<void> {
+  await putSocialToken(deps, tenantId, network, newPayload);
+}
+
+/**
+ * Composition root: wire the real Worker bindings into a `SocialTokenStoreDeps`.
+ * Returns `null` when the D1 binding or the `SOCIAL_TOKEN_KEK` secret is absent
+ * (unprovisioned runtime / dev), so a caller degrades to "social posting
+ * unavailable" rather than throwing — the KEK is a runtime secret that must be
+ * provisioned out of band (`wrangler secret put SOCIAL_TOKEN_KEK`).
+ */
+export async function resolveSocialTokenStore(): Promise<SocialTokenStoreDeps | null> {
+  const [{ fromD1 }, d1, rawKek] = await Promise.all([
+    import("../d1/catalog.js"),
+    readD1("STOREFRONT_APPS_DB"),
+    readEnv("SOCIAL_TOKEN_KEK"),
+  ]);
+  if (!d1 || !rawKek) return null;
+  return { db: fromD1(d1), kek: await importKek(rawKek) };
+}

package/apps/storefront/src/lib/the-build/provider.ts

@@ -0,0 +1,27 @@
+// Thin wrapper binding the generic blog engine to the "the-build" collection.
+// The engine (src/lib/blog/collection.ts) is the single implementation; this
+// module only fixes the collection id so existing/downstream callers can import
+// collection-bound helpers.
+import { getPost, listPosts, resolveRedirect, type Collection } from "../blog/collection.js";
+import type { BlogPost, BlogPostSummary } from "../blog/types.js";
+
+export const THE_BUILD: Collection = { id: "the-build", base: "/the-build" };
+
+export function listBuildPosts(
+  tenantId: string,
+  opts?: { includeUnpublished?: boolean; now?: string },
+): Promise<BlogPostSummary[]> {
+  return listPosts(tenantId, THE_BUILD.id, opts);
+}
+
+export function getBuildPost(
+  tenantId: string,
+  slug: string,
+  opts?: { includeUnpublished?: boolean; now?: string },
+): Promise<BlogPost | null> {
+  return getPost(tenantId, THE_BUILD.id, slug, opts);
+}
+
+export function resolveBuildRedirect(tenantId: string, slug: string): Promise<string | null> {
+  return resolveRedirect(tenantId, THE_BUILD.id, slug);
+}

package/apps/storefront/src/lib/the-build/readingTime.ts

@@ -0,0 +1,35 @@
+// Estimated reading time for a post's rendered HTML (B1.5). Pure + Node-free
+// (parse5 is Workers-safe), so it's unit-testable and usable on any render path.
+import { parseFragment } from "parse5";
+
+/** Minimal structural view of a parse5 node (duck-typed, as scripts/dev/locate.mjs does). */
+interface P5Node {
+  nodeName: string;
+  tagName?: string;
+  value?: string;
+  childNodes?: P5Node[];
+}
+
+const WORDS_PER_MINUTE = 225;
+
+function collectText(node: P5Node, out: string[]): void {
+  if (node.nodeName === "#text") {
+    if (node.value) out.push(node.value);
+    return;
+  }
+  // Non-visible/text-irrelevant subtrees never count toward reading time.
+  if (node.tagName === "script" || node.tagName === "style") return;
+  for (const child of node.childNodes ?? []) collectText(child, out);
+}
+
+/**
+ * Reading time in whole minutes: visible word count / 225 wpm, rounded up, min 1.
+ * Ignores markup, script, and style content.
+ */
+export function readingTime(html: string): number {
+  const frag = parseFragment(html ?? "") as unknown as P5Node;
+  const parts: string[] = [];
+  collectText(frag, parts);
+  const words = parts.join(" ").trim().split(/\s+/).filter(Boolean);
+  return Math.max(1, Math.ceil(words.length / WORDS_PER_MINUTE));
+}

package/apps/storefront/src/lib/the-build/toc.ts

@@ -0,0 +1,95 @@
+// Table of contents for a post's rendered HTML (B1.5): parse h2/h3 headings and
+// derive stable anchor ids. Pure + Node-free (parse5 is Workers-safe).
+//
+// `toc()` and `htmlWithHeadingIds()` derive ids from the SAME deterministic pass
+// (`annotate`), so a render path can feed `htmlWithHeadingIds(post.contentHtml)`
+// to `set:html` and `toc(post.contentHtml)` to the aside and the anchors line up.
+import { parseFragment, serialize } from "parse5";
+import { slugifyHeading } from "../content/prose.js";
+
+/** Minimal structural view of a parse5 node (duck-typed, as scripts/dev/locate.mjs does). */
+interface P5Node {
+  nodeName: string;
+  tagName?: string;
+  value?: string;
+  attrs?: { name: string; value: string }[];
+  childNodes?: P5Node[];
+}
+
+export interface TocEntry {
+  id: string;
+  text: string;
+  level: 2 | 3;
+}
+
+function textOf(node: P5Node): string {
+  if (node.nodeName === "#text") return node.value ?? "";
+  return (node.childNodes ?? []).map(textOf).join("");
+}
+
+function getId(node: P5Node): string | undefined {
+  return node.attrs?.find((a) => a.name === "id")?.value?.trim() || undefined;
+}
+
+function* headings(node: P5Node): Generator<P5Node> {
+  for (const child of node.childNodes ?? []) {
+    if (child.tagName === "h2" || child.tagName === "h3") yield child;
+    yield* headings(child);
+  }
+}
+
+interface AnnotatedHeading {
+  node: P5Node;
+  id: string;
+  text: string;
+  level: 2 | 3;
+}
+
+/**
+ * Walk headings in document order, assigning each a unique anchor id: an
+ * author-supplied `id` is kept as-is; otherwise the slugified text, de-duped
+ * with a numeric suffix on collision. Empty headings are skipped.
+ */
+function* annotate(root: P5Node): Generator<AnnotatedHeading> {
+  const seen = new Map<string, number>();
+  for (const node of headings(root)) {
+    const text = textOf(node).replace(/\s+/g, " ").trim();
+    if (!text) continue;
+    const level: 2 | 3 = node.tagName === "h2" ? 2 : 3;
+    const explicit = getId(node);
+    let id: string;
+    if (explicit) {
+      id = explicit;
+      seen.set(id, (seen.get(id) ?? 0) + 1);
+    } else {
+      const base = slugifyHeading(text) || "section";
+      const n = seen.get(base) ?? 0;
+      seen.set(base, n + 1);
+      id = n === 0 ? base : `${base}-${n + 1}`;
+    }
+    yield { node, id, text, level };
+  }
+}
+
+/** TOC entries (one per h2/h3) with stable anchor ids, in document order. */
+export function toc(html: string): TocEntry[] {
+  const frag = parseFragment(html ?? "") as unknown as P5Node;
+  return [...annotate(frag)].map(({ id, text, level }) => ({ id, text, level }));
+}
+
+/**
+ * The same HTML with anchor ids added to any h2/h3 that lacks one (author ids
+ * untouched). Returns the input unchanged when every heading already has an id,
+ * so posts without generated anchors are byte-for-byte preserved.
+ */
+export function htmlWithHeadingIds(html: string): string {
+  const frag = parseFragment(html ?? "") as unknown as P5Node;
+  let changed = false;
+  for (const { node, id } of annotate(frag)) {
+    if (!getId(node)) {
+      node.attrs = [...(node.attrs ?? []), { name: "id", value: id }];
+      changed = true;
+    }
+  }
+  return changed ? serialize(frag as never) : (html ?? "");
+}

package/apps/storefront/src/lib/tot/ToTClient.ts

@@ -166,7 +166,7 @@ export async function createToTClient(
   tenant: TenantConfig,
   d1?: D1Like,
 ): Promise<ToTClient> {
-  // Edge read replica (epics/edge-read-replica.md): when a D1 binding is wired,
+  // Edge read replica: when a D1 binding is wired,
   // serve reads from it (FTS5 search + SQL facets). Otherwise the bundled fixture
   // snapshot renders the site offline. The tot20 HTTP catalog API has been retired,
   // so the read path is fully edge-native.

package/apps/storefront/src/lib/tot/d1Client.ts

@@ -1,5 +1,5 @@
 /**
- * D1-backed ToTClient — the edge read-replica path (epics/edge-read-replica.md).
+ * D1-backed ToTClient — the edge read-replica path.
  *
  * Implements the same ToTClient interface as Fixture/Http, but every read is a D1
  * query (FTS5 search, SQL faceted listing, row-blob retrieval) instead of an
@@ -56,7 +56,7 @@ export class D1ToTClient implements ToTClient {
   }
 
   async getReviews(_handle: string): Promise<Review[]> {
-    // Phase 1 reviews are display-via-metafields; D1 carries none yet.
+    // Reviews are display-via-metafields; the D1 catalog carries none.
     return [];
   }
 }

package/apps/storefront/src/lib/tot/totClientInterface.ts

@@ -1,11 +1,10 @@
 /**
  * The ToTClient interface — the storefront's single product-truth contract.
  *
- * Extracted from ToTClient.ts so the concrete backends (FixtureToTClient here,
+ * Lives in its own module so the concrete backends (FixtureToTClient here,
  * D1ToTClient in d1Client.ts) can both `implements ToTClient` without a circular
  * module edge: d1Client imports only this contract, while ToTClient.ts imports
- * D1ToTClient for its factory. ToTClient.ts re-exports this type, so existing
- * `import type { ToTClient } from "./ToTClient"` call sites are unchanged.
+ * D1ToTClient for its factory. ToTClient.ts re-exports this type.
  */
 import type {
   CatalogCollection,
@@ -25,6 +24,6 @@ export interface ToTClient {
   getFeatured(limit?: number): Promise<CatalogProduct[]>;
   /** Full active catalog — used to build the per-tenant search index. */
   getAllActiveProducts(): Promise<CatalogProduct[]>;
-  /** Full review content for a product (migrated from the store's reviews app). */
+  /** Full review content for a product. */
   getReviews(handle: string): Promise<Review[]>;
 }

package/apps/storefront/src/lib/webhooks/deliveryStore.ts

@@ -1,10 +1,9 @@
 /**
- * Webhook event/delivery storage — PrivateApps epic, D4 (Chunk A: Storage
- * only). Owns the `webhook_events` / `webhook_deliveries` /
+ * Webhook event/delivery storage. Owns the `webhook_events` / `webhook_deliveries` /
  * `webhook_delivery_attempts` / `webhook_install_health` rows described in
- * `../d1/schema.ts`. Signing (Chunk B), the retry/backoff dispatcher
- * (Chunk C), event emission/targeting (Chunk D), and the `/webhooks/*`
- * routes (Chunk E) all build on this store; none of that policy lives here.
+ * `../d1/schema.ts`. Signing, the retry/backoff dispatcher, event
+ * emission/targeting, and the `/webhooks/*` routes all build on this store; none
+ * of that policy lives here.
  *
  * Pure over the `Queryable` seam (see `../d1/catalog.ts`) — the same shape
  * `AppRegistryService` uses, so this runs unchanged against real D1 in the
@@ -16,12 +15,12 @@
  *   - `deliveryId` (`webhook_deliveries.delivery_id`) — the CloudEvents
  *     envelope `id` for one (event × target install) delivery. This is what
  *     goes on the wire and is what receivers dedupe on; it stays stable
- *     across that delivery's own retries AND across a manual replay (Chunk
- *     E's `requeueForReplay` resets state/attempts on the SAME row rather
+ *     across that delivery's own retries AND across a manual replay
+ *     (`requeueForReplay` resets state/attempts on the SAME row rather
  *     than minting a new one — a receiver that already acked a delivered
  *     delivery must still dedupe a replayed resend of it).
  *
- * Responsibility split for the two mutating paths a dispatcher (Chunk C)
+ * Responsibility split for the two mutating paths a dispatcher
  * drives per attempt:
  *   - `recordAttempt` is dumb bookkeeping of ONE HTTP attempt's outcome: it
  *     appends to `webhook_delivery_attempts`, bumps the delivery's
@@ -117,7 +116,7 @@ export interface CreateEventResult {
 
 export interface ListDeliveriesOptions {
   state?: DeliveryState;
-  /** Cap the result, newest first. Used internally by {@link WebhookDeliveryStore.getInstallHealth} to bound its p95 sample; unset means unbounded (the historical behavior). */
+  /** Cap the result, newest first. Used internally by {@link WebhookDeliveryStore.getInstallHealth} to bound its p95 sample; unset means unbounded. */
   limit?: number;
 }
 
@@ -165,8 +164,8 @@ const MAX_RECENT_TRACE_IDS = 10;
 const P95_SAMPLE_SIZE = 50;
 
 // A delivery only ever moves forward via `transitionState`; `delivered`/
-// `dead-lettered` are terminal THERE. A manual replay (Chunk E's
-// `requeueForReplay`) is the one deliberate exception: it resets a delivery
+// `dead-lettered` are terminal THERE. A manual replay (`requeueForReplay`)
+// is the one deliberate exception: it resets a delivery
 // out of a terminal state back to `pending` on the SAME row, bypassing this
 // table entirely — see that method's own doc comment for why.
 const ALLOWED_TRANSITIONS: Record<DeliveryState, readonly DeliveryState[]> = {
@@ -287,7 +286,7 @@ export class WebhookDeliveryStore {
   /**
    * Write one immutable event, then fan it out to one `pending` delivery per
    * target install. Targeting (which installs get the event) is the caller's
-   * job (Chunk D) — this just persists whatever target list it's handed.
+   * job — this just persists whatever target list it's handed.
    */
   async createEvent(input: CreateEventInput, targets: readonly DeliveryTarget[]): Promise<CreateEventResult> {
     const eventId = input.eventId ?? crypto.randomUUID();
@@ -345,8 +344,8 @@ export class WebhookDeliveryStore {
   }
 
   /**
-   * Read one event by id, or `null` if it doesn't exist. Added for the
-   * dispatcher/delivery engine (Chunk C): `attemptDelivery` resolves a
+   * Read one event by id, or `null` if it doesn't exist. The dispatcher/delivery
+   * engine uses it: `attemptDelivery` resolves a
    * delivery's `eventId` via `getDelivery`, then needs this to fetch the
    * `payload`/`dataschemaVersion` that only `webhook_events` (not
    * `webhook_deliveries`) carries, in order to build the CloudEvents
@@ -381,7 +380,7 @@ export class WebhookDeliveryStore {
    * All deliveries for a tenant, across every install (the ops/support admin
    * view — an install only ever sees its OWN deliveries via
    * {@link listDeliveriesByInstall}; this is the tenant-wide superset), newest
-   * first. Added for D4 Chunk E's admin route; Chunk A/B/C never call this.
+   * first.
    */
   async listDeliveriesByTenant(
     tenantId: string,
@@ -443,7 +442,7 @@ export class WebhookDeliveryStore {
 
   /**
    * Move a delivery's `state` forward per `ALLOWED_TRANSITIONS`. The
-   * caller (Chunk C's dispatcher) decides WHEN to retry vs. give up; this
+   * caller (the dispatcher) decides WHEN to retry vs. give up; this
    * only records that decision. Dead-lettering bumps the install's
    * `dlqCount` — the one rollup field {@link recordAttempt} doesn't own.
    */
@@ -478,7 +477,7 @@ export class WebhookDeliveryStore {
   }
 
   /**
-   * D4 Chunk E's replay support: force a delivery back to `pending` with a
+   * Replay support: force a delivery back to `pending` with a
    * fresh attempt budget — from ANY current state, INCLUDING the terminal
    * `delivered`/`dead-lettered` states `transitionState`/`ALLOWED_TRANSITIONS`
    * refuse to leave. This is deliberately a separate write path, not a call