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

package/apps/storefront/src/lib/publish/stageBundleUpload.ts

@@ -0,0 +1,215 @@
+/**
+ * Authenticated static-bundle STAGING upload — the Worker-side write surface that
+ * lets CI stage a materialized bundle's objects into the `STATIC_BUNDLES` R2
+ * binding WITHOUT a static R2 S3-compatible key pair (`R2_ACCESS_KEY_ID`/
+ * `R2_SECRET_ACCESS_KEY`). CI proves identity with the SAME OIDC→AWS→SSM→
+ * `private_key_jwt` chain it already uses to authenticate to MCP
+ * (`scripts/publish/ci-mcp-read-remote.mjs`): it mints a short-lived RS256
+ * `client_assertion` under its dedicated confidential client
+ * (`storefront-ci.tokenoftrust.com` / kid `storefront-ci-publish-1`, the key held
+ * only in SSM), audience-bound to THIS upload endpoint, and the Worker verifies
+ * the signature against that client's PUBLISHED public JWKS.
+ *
+ * This is a WRITE path to a production-serving bucket, so the auth boundary is
+ * deliberately as strong as the MCP leg:
+ *   - RS256 signature over the CI client's JWKS (no shared static secret).
+ *   - `iss == sub == <expected CI client id>` (RFC 7523 §3).
+ *   - `aud == <this exact upload endpoint>` (RFC 8707 resource binding) — an
+ *     assertion minted for MCP's token endpoint can never be replayed here, and
+ *     vice versa.
+ *   - `exp`/`iat` freshness (jose enforces `exp`; assertions live ~60s).
+ *   - `jti` one-time-use replay rejection (KV-backed), mirroring MCP's replay
+ *     store — so a captured assertion can't be replayed inside its TTL window.
+ *   - Object key confined to `versions/<digest>/…`: a valid CI credential can
+ *     only write immutable version archives, never the `live/` pointer or any
+ *     other bucket key.
+ *
+ * The KEY SCHEME (`versions/<digest>/<rel>`) MUST byte-match the read side
+ * (`@tot/public-runtime` `staticBundleObjectKey`/`staticBundleManifestKey`) and
+ * the CI writer (`scripts/publish/lib/r2-publish.mjs` `r2ObjectKey`) — the same
+ * lockstep those two already keep. MANIFEST-LAST ordering (the manifest is the
+ * "fully staged" signal) is the CALLER's responsibility (CI writes it last, the
+ * same as `writeBundleToR2`); this surface writes exactly the one object it is
+ * handed per request.
+ */
+import { createLocalJWKSet, jwtVerify, type JSONWebKeySet, type JWTPayload } from "jose";
+
+/** The only signature algorithm accepted (matches the CI minter). */
+export const STAGE_BUNDLE_UPLOAD_ALG = "RS256";
+
+/** The route this surface is mounted at — the canonical `aud`/resource identifier. */
+export const STAGE_BUNDLE_UPLOAD_PATH = "/api/publish/stage-bundle";
+
+/** Default CI confidential-client id (`iss == sub`), overridable per env. */
+export const DEFAULT_STAGE_BUNDLE_UPLOAD_ISSUER = "storefront-ci.tokenoftrust.com";
+
+/** How long a used `jti` is remembered — the assertion TTL (~60s) plus clock skew. */
+export const STAGE_BUNDLE_JTI_TTL_SECONDS = 120;
+
+/** Clock skew tolerated on `exp`/`iat`, in seconds. */
+const CLOCK_TOLERANCE_SECONDS = 5;
+
+/**
+ * The `versions/<digest>/<rel>` keys a CI credential is allowed to write. The
+ * digest is a lowercase hex tree digest; `rel` is a bundle-relative POSIX path
+ * with no traversal. Anything else (a bare key, `live/…`, an absolute path, a
+ * `..` segment) is refused with 400 — the write authority is bounded to
+ * immutable version archives regardless of a valid signature.
+ */
+const VERSION_KEY_RE = /^versions\/[a-f0-9]{8,}\/.+$/;
+
+/** Minimal R2 surface this module needs — structural, so tests pass a fake. */
+export interface StageBundleUploadBucket {
+  head(key: string): Promise<{ key: string } | null>;
+  put(
+    key: string,
+    value: ArrayBuffer | ArrayBufferView,
+    options?: { httpMetadata?: { contentType?: string } },
+  ): Promise<unknown>;
+}
+
+/**
+ * One-time-use `jti` store. `checkAndRemember` returns `true` when the `jti` was
+ * unseen (and records it), `false` when it was already used (a replay). Backed by
+ * KV in the deployed Worker; omitted in dev/tests where no KV is bound (replay
+ * protection then relies on the ~60s `aud`-bound `exp` window alone).
+ */
+export interface JtiReplayStore {
+  checkAndRemember(jti: string, ttlSeconds: number): Promise<boolean>;
+}
+
+export interface StageBundleUploadConfig {
+  /** The CI client's published PUBLIC JWKS (verifies the assertion signature). */
+  jwks: JSONWebKeySet;
+  /** Expected `iss == sub` (the CI confidential-client id). */
+  issuer: string;
+  /** Expected `aud` — this exact upload endpoint URL (RFC 8707 resource). */
+  audience: string;
+}
+
+/** A KV-namespace-shaped store (`get`/`put`) — the deployed jti replay backing. */
+export interface JtiKvLike {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+}
+
+/** Build a KV-backed {@link JtiReplayStore}. Keyed under a dedicated prefix. */
+export function kvJtiReplayStore(kv: JtiKvLike): JtiReplayStore {
+  return {
+    async checkAndRemember(jti, ttlSeconds) {
+      const key = `stage-bundle-jti:${jti}`;
+      if (await kv.get(key)) return false;
+      // KV's minimum expirationTtl is 60s; the TTL default already exceeds it.
+      await kv.put(key, "1", { expirationTtl: Math.max(60, ttlSeconds) });
+      return true;
+    },
+  };
+}
+
+function json(status: number, body: Record<string, unknown>): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+/** Extract the bearer assertion from the Authorization header, or null. */
+function bearer(request: Request): string | null {
+  const h = request.headers.get("authorization");
+  if (!h) return null;
+  const m = /^Bearer (.+)$/.exec(h.trim());
+  return m ? m[1]!.trim() : null;
+}
+
+/**
+ * Verify the CI `client_assertion`: RS256 signature over the configured JWKS,
+ * `iss`/`sub`/`aud` exact match, `exp` freshness, and one-time `jti`. Returns the
+ * verified payload, or a `Response` (401) to return verbatim on any failure — no
+ * failure detail beyond a stable machine reason is leaked.
+ */
+export async function verifyUploadAssertion(
+  token: string,
+  config: StageBundleUploadConfig,
+  jtiStore?: JtiReplayStore,
+): Promise<{ payload: JWTPayload } | { reject: Response }> {
+  let payload: JWTPayload;
+  try {
+    const keys = createLocalJWKSet(config.jwks);
+    ({ payload } = await jwtVerify(token, keys, {
+      algorithms: [STAGE_BUNDLE_UPLOAD_ALG],
+      issuer: config.issuer,
+      audience: config.audience,
+      clockTolerance: CLOCK_TOLERANCE_SECONDS,
+    }));
+  } catch {
+    // Signature, iss/aud mismatch, or expiry — one opaque 401 (never which).
+    return { reject: json(401, { error: "invalid_assertion" }) };
+  }
+  // RFC 7523 §3: sub must equal the client id (iss). jose verifies iss but not
+  // that sub matches it, so assert it explicitly.
+  if (payload.sub !== config.issuer) {
+    return { reject: json(401, { error: "invalid_assertion" }) };
+  }
+  const jti = typeof payload.jti === "string" ? payload.jti : "";
+  if (!jti) {
+    return { reject: json(401, { error: "invalid_assertion" }) };
+  }
+  if (jtiStore) {
+    const fresh = await jtiStore.checkAndRemember(jti, STAGE_BUNDLE_JTI_TTL_SECONDS);
+    if (!fresh) return { reject: json(401, { error: "assertion_replayed" }) };
+  }
+  return { payload };
+}
+
+/** True iff `key` is a well-formed, traversal-free `versions/<digest>/<rel>` key. */
+export function isSafeVersionKey(key: string): boolean {
+  if (!VERSION_KEY_RE.test(key)) return false;
+  return !key.split("/").some((seg) => seg === ".." || seg === "." || seg === "");
+}
+
+/**
+ * Handle one authenticated staging request against `bucket`:
+ *   - `PUT  ?key=versions/<digest>/<rel>` — write the request body as that object.
+ *   - `HEAD ?key=versions/<digest>/<rel>` — 200 if present, 404 if not (the CI
+ *     idempotency probe, mirroring `r2ObjectExists`).
+ * Both require a valid CI assertion; the key is confined to `versions/<digest>/`.
+ */
+export async function handleStageBundleUpload(opts: {
+  request: Request;
+  bucket: StageBundleUploadBucket;
+  config: StageBundleUploadConfig;
+  jtiStore?: JtiReplayStore;
+}): Promise<Response> {
+  const { request, bucket, config, jtiStore } = opts;
+  const method = request.method.toUpperCase();
+  if (method !== "PUT" && method !== "HEAD") {
+    return json(405, { error: "method_not_allowed" });
+  }
+
+  const token = bearer(request);
+  if (!token) return json(401, { error: "missing_bearer" });
+
+  // HEAD is a read/probe and must NOT consume the one-time jti (a PUT retry after
+  // a probe would then falsely 401 as a replay). Only PUT records the jti.
+  const verified = await verifyUploadAssertion(
+    token,
+    config,
+    method === "PUT" ? jtiStore : undefined,
+  );
+  if ("reject" in verified) return verified.reject;
+
+  const key = new URL(request.url).searchParams.get("key") ?? "";
+  if (!isSafeVersionKey(key)) {
+    return json(400, { error: "invalid_key" });
+  }
+
+  if (method === "HEAD") {
+    const obj = await bucket.head(key);
+    return new Response(null, { status: obj ? 200 : 404 });
+  }
+
+  const body = await request.arrayBuffer();
+  const contentType = request.headers.get("content-type") ?? undefined;
+  await bucket.put(key, body, contentType ? { httpMetadata: { contentType } } : undefined);
+  return json(200, { key, staged: true });
+}

package/apps/storefront/src/lib/rate/kvWindow.ts

@@ -0,0 +1,53 @@
+/**
+ * Fixed-window KV rate limiter — the storefront's first throttle, built small
+ * and generic so any public POST can share it (reactions today; blog comments
+ * and other reader writes next).
+ *
+ * A request is counted into the bucket for the current fixed window
+ * (`floor(now / windowSeconds)`), keyed `<key>:<bucket>`. The counter TTLs out a
+ * window after it is first written, so old buckets self-expire — no sweep.
+ *
+ * Best-effort by construction: a KV read/write hiccup FAILS OPEN (returns
+ * `allowed: true`) and never throws. A rate limiter must never turn a KV blip
+ * into a rejected legitimate request; the abuse it guards against is low-stakes
+ * (mirrors the "never throws" discipline of `blog/viewCounts.ts`).
+ */
+
+export interface RateLimitOptions {
+  /** Window length in seconds; the counter resets each window. */
+  windowSeconds: number;
+  /** Max requests permitted per key per window before rejecting. */
+  maxRequests: number;
+}
+
+/** The current fixed-window bucket index for `now` (ms epoch). */
+function windowBucket(windowSeconds: number, nowMs: number): number {
+  return Math.floor(nowMs / 1000 / windowSeconds);
+}
+
+/**
+ * Count one request against `key` and report whether it is within the cap for
+ * the current window. Increment is a read-modify-write, so under concurrency a
+ * few increments can be lost to KV's last-write-wins — acceptable for a soft
+ * abuse throttle, not a hard quota. Fails OPEN on any KV error.
+ */
+export async function checkRateLimit(
+  kv: KVNamespace | undefined,
+  key: string,
+  opts: RateLimitOptions,
+  nowMs: number = Date.now(),
+): Promise<{ allowed: boolean }> {
+  if (!kv) return { allowed: true };
+  try {
+    const bucket = windowBucket(opts.windowSeconds, nowMs);
+    const bucketKey = `${key}:${bucket}`;
+    const raw = await kv.get(bucketKey);
+    const current = raw == null ? 0 : Number.parseInt(raw, 10);
+    const count = Number.isFinite(current) && current >= 0 ? current : 0;
+    if (count >= opts.maxRequests) return { allowed: false };
+    await kv.put(bucketKey, String(count + 1), { expirationTtl: opts.windowSeconds });
+    return { allowed: true };
+  } catch {
+    return { allowed: true };
+  }
+}

package/apps/storefront/src/lib/search/index.ts

@@ -3,8 +3,8 @@
  *
  * Used by FixtureToTClient.search (no D1 binding): typo-tolerant, relevance-ranked
  * search over the bundled catalog snapshot, zero infra. When a D1 binding is wired
- * (D1ToTClient), search instead goes through FTS5 — see lib/d1/catalog.ts and
- * epics/edge-read-replica.md. This module is the portable floor an extracted
+ * (D1ToTClient), search instead goes through FTS5 — see lib/d1/catalog.ts.
+ * This module is the portable floor an extracted
  * merchant gets out of the box (docs/extraction-runbook.md).
  */
 import Fuse, { type IFuseOptions } from "fuse.js";

package/apps/storefront/src/lib/seo/alternates.ts

@@ -0,0 +1,42 @@
+/**
+ * hreflang alternates for a translated article (I2). Two pure helpers so the
+ * article route and <Seo> stay thin and the "singleton emits nothing" guard is
+ * unit-testable without an Astro render harness.
+ */
+export interface Alternate {
+  hreflang: string;
+  href: string;
+}
+
+/**
+ * Build the per-variant alternate set for an article's translation group. Returns
+ * `[]` for a singleton (≤1 variant) so a non-translated post emits no `hreflang`
+ * links and renders byte-identically to today. Each variant maps to its own
+ * localized canonical via `hrefForSlug`; `inLanguage` is the per-variant language
+ * key (defaulting "en", matching the field's repo-wide default).
+ */
+export function buildAlternates(
+  variants: { slug: string; inLanguage?: string }[],
+  hrefForSlug: (slug: string) => string,
+): Alternate[] {
+  if (variants.length <= 1) return [];
+  return variants.map((v) => ({
+    hreflang: v.inLanguage ?? "en",
+    href: hrefForSlug(v.slug),
+  }));
+}
+
+/**
+ * Append the `x-default` entry to a per-variant alternate set. It points at the
+ * English variant (`en` or an `en-*` region variant); with no English variant it
+ * falls back to the first entry — a deterministic primary rather than none, so
+ * search engines always have a language-agnostic default. Returns `[]` unchanged
+ * for an empty input (nothing to default to).
+ */
+export function withXDefault(alternates: Alternate[]): Alternate[] {
+  if (alternates.length === 0) return [];
+  const primary =
+    alternates.find((a) => a.hreflang === "en" || a.hreflang.startsWith("en-")) ??
+    alternates[0]!;
+  return [...alternates, { hreflang: "x-default", href: primary.href }];
+}

package/apps/storefront/src/lib/seo/meta.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure builders for the extra <meta> tags `<Seo>` emits on article pages
+ * (B1.6). Kept as a pure function so the "no article meta leaks onto
+ * website/product pages" invariant is unit-testable without rendering Astro.
+ */
+
+/** Open Graph `article:*` fields — only meaningful when `ogType === "article"`. */
+export interface ArticleMeta {
+  publishedTime?: string;
+  modifiedTime?: string;
+  /** Author name or author-page URL → article:author. */
+  author?: string;
+  /** The category/pillar → article:section. */
+  section?: string;
+  /** One <meta property="article:tag"> per entry. */
+  tags?: string[];
+}
+
+/** A meta tag is keyed by either `property` (OG) or `name` (Twitter/std). */
+export interface MetaTag {
+  property?: string;
+  name?: string;
+  content: string;
+}
+
+export interface ArticleSeoInput {
+  ogType?: "website" | "product" | "article";
+  article?: ArticleMeta;
+  /** og:image:alt — the accessible description of the OG image. */
+  imageAlt?: string;
+  imageWidth?: number;
+  imageHeight?: number;
+  twitterSite?: string;
+  twitterCreator?: string;
+}
+
+/**
+ * The article-only OG/Twitter meta tags. Returns `[]` for any non-article page
+ * so `article:*`, `og:image:alt`, and `twitter:site`/`creator` can never leak
+ * onto website/product pages (guarded here, asserted in meta.test.ts).
+ */
+export function articleSeoMetaTags(input: ArticleSeoInput): MetaTag[] {
+  if (input.ogType !== "article") return [];
+  const tags: MetaTag[] = [];
+  const a = input.article;
+  if (a?.publishedTime)
+    tags.push({ property: "article:published_time", content: a.publishedTime });
+  if (a?.modifiedTime)
+    tags.push({ property: "article:modified_time", content: a.modifiedTime });
+  if (a?.author) tags.push({ property: "article:author", content: a.author });
+  if (a?.section) tags.push({ property: "article:section", content: a.section });
+  for (const tag of a?.tags ?? [])
+    tags.push({ property: "article:tag", content: tag });
+  if (input.imageAlt)
+    tags.push({ property: "og:image:alt", content: input.imageAlt });
+  if (input.imageWidth)
+    tags.push({ property: "og:image:width", content: String(input.imageWidth) });
+  if (input.imageHeight)
+    tags.push({ property: "og:image:height", content: String(input.imageHeight) });
+  if (input.twitterSite)
+    tags.push({ name: "twitter:site", content: input.twitterSite });
+  if (input.twitterCreator)
+    tags.push({ name: "twitter:creator", content: input.twitterCreator });
+  return tags;
+}

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

@@ -0,0 +1,212 @@
+/**
+ * S1 — the social go-live hook + idempotency.
+ *
+ * WHERE IT FIRES: at the true go-live edge — after `AggregateShipOrchestrator`
+ * flips a tenant's `live` channel to a freshly-shipped version and records the
+ * release ledger. NOT on `POST /api/admin/blog`'s `publish` (which only opens a
+ * candidate PR a human still promotes) and NOT on accept-to-preview
+ * (`/api/changes/accept` → `integrate`, which only advances the `preview`
+ * aggregate). Go-live is where a post's file actually becomes public, so it is the
+ * only truthful "it went live" edge.
+ *
+ * WHAT IT DETECTS: a blog post that transitioned INTO a live-visible status — was
+ * absent or not-live in the version live before this ship (`fromVersionId`), and
+ * is live-visible in the version just promoted (`toVersionId`). Visibility is the
+ * ONE chokepoint `isVisibleOnLive` (published / unlisted / due-scheduled), reused
+ * so this never drifts from the render path.
+ *
+ * DISCIPLINE (mirrors `webhooks/emit.ts`): BEST-EFFORT and fire-and-forget — every
+ * failure is logged and swallowed. A social outage must NEVER fail or roll back a
+ * completed go-live.
+ *
+ * IDEMPOTENCY: a check-and-set posted-state key per `(tenant, collection, slug,
+ * network)` fires each post AT MOST ONCE, so a re-ship / re-run never re-posts. The
+ * transition guard also marks already-live posts as "primed" (key set, not fired)
+ * so the first ship after this hook deploys does NOT retro-announce the tenant's
+ * whole back-catalog.
+ */
+import { isVisibleOnLive } from "../blog/collection.js";
+import type { BlogPost, PostStatus } from "../blog/types.js";
+import { notifyPostPublished } from "./notify.js";
+
+/**
+ * The minimal version-read surface this hook needs — a structural subset of the
+ * control-plane `SiteVersionStore`. Declared locally (not imported) so `lib/social`
+ * stays inside the source-available renderer carve and never edges onto
+ * `@tot/private-controlplane`; the caller (the control-plane-cluster orchestrator)
+ * passes its real store in.
+ */
+export interface VersionReadStore {
+  getSiteVersion(
+    tenantId: string,
+    versionId: string,
+  ): Promise<{ artifacts: Record<string, string> } | null>;
+  getVersionContent(
+    tenantId: string,
+    path: string,
+    versionId: string,
+  ): Promise<string | Uint8Array | null>;
+}
+
+/**
+ * The v1 idempotency network token — a single whole-post gate. S3/S4 replace this
+ * with the real per-network id (`x` / `linkedin` / …) and iterate networks; the key
+ * shape is ALREADY per-network so that extension needs no rework here.
+ */
+export const SOCIAL_NETWORK = "social";
+
+/** The posted-once key for one post on one network. */
+export function socialPostedKey(
+  tenantId: string,
+  collection: string,
+  slug: string,
+  network: string,
+): string {
+  return `social:posted:${tenantId}:${collection}:${slug}:${network}`;
+}
+
+/** The minimal KV surface the idempotency store needs (TENANT_CACHE in prod). */
+export interface SocialIdempotencyKv {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string): Promise<void>;
+}
+
+// `.../content/<collection>/posts/<slug>.json` — capture collection + slug from a
+// version-manifest artifact path (robust to the leading `tenants/<id>/` prefix).
+const POST_PATH_RE = /(?:^|\/)content\/([a-z0-9][a-z0-9._-]*)\/posts\/([a-z0-9][a-z0-9-]*)\.json$/;
+
+function logDiag(fields: Record<string, unknown>): void {
+  try {
+    console.warn("[diag:social:golive]", JSON.stringify(fields));
+  } catch {
+    /* diagnostics must never break the caller */
+  }
+}
+
+// Legacy/seeded post JSON may omit `status`; default it to "published" on load, the
+// same normalization `blog/collection.ts` applies so visibility matches the render path.
+function normalizeStatus(raw: unknown): PostStatus {
+  return raw === "draft" || raw === "unlisted" || raw === "published" || raw === "scheduled"
+    ? raw
+    : "published";
+}
+
+// `contentVersionId` is the artifact's content hash (`manifest.artifacts[path]`) —
+// the version store keys blob content by that hash, not by the site version id.
+async function readPost(
+  store: VersionReadStore,
+  tenantId: string,
+  artifactPath: string,
+  contentVersionId: string,
+): Promise<BlogPost | null> {
+  const raw = await store.getVersionContent(tenantId, artifactPath, contentVersionId);
+  if (typeof raw !== "string") return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== "object") return null;
+  const post = parsed as BlogPost;
+  return { ...post, status: normalizeStatus((post as { status?: unknown }).status) };
+}
+
+export interface NotifyPostsWentLiveDeps {
+  /** The version store the shipped tenant publishes to (a control-plane `SiteVersionStore`). */
+  store: VersionReadStore;
+  /** Idempotency store — TENANT_CACHE in prod. */
+  kv: SocialIdempotencyKv;
+  now?: () => string;
+  /** Override the publish seam (tests + S3/S4 injection). Defaults to {@link notifyPostPublished}. */
+  notify?: (tenantId: string, collection: string, slug: string, post: BlogPost) => Promise<void>;
+}
+
+export interface NotifyPostsWentLiveInput {
+  tenantId: string;
+  /** The version just promoted to `live`. */
+  toVersionId: string;
+  /** The version live immediately BEFORE this ship, or null on the first-ever ship. */
+  fromVersionId: string | null;
+}
+
+/**
+ * For each blog post that went live in `toVersionId`, fire {@link notifyPostPublished}
+ * at most once. NEVER throws — the whole body is guarded so a completed go-live is
+ * never failed or rolled back by this hook.
+ */
+export async function notifyPostsWentLive(
+  deps: NotifyPostsWentLiveDeps,
+  input: NotifyPostsWentLiveInput,
+): Promise<void> {
+  try {
+    const { store, kv } = deps;
+    const now = (deps.now ?? (() => new Date().toISOString()))();
+    const notify = deps.notify ?? notifyPostPublished;
+
+    const toManifest = await store.getSiteVersion(input.tenantId, input.toVersionId);
+    if (!toManifest) return;
+    const fromManifest = input.fromVersionId
+      ? await store.getSiteVersion(input.tenantId, input.fromVersionId)
+      : null;
+
+    for (const [artifactPath, contentHash] of Object.entries(toManifest.artifacts)) {
+      const match = POST_PATH_RE.exec(artifactPath);
+      if (!match) continue;
+      const collection = match[1]!;
+      const slug = match[2]!;
+      const key = socialPostedKey(input.tenantId, collection, slug, SOCIAL_NETWORK);
+
+      // Already posted (or primed) — skip before any content read (cheap steady state).
+      let already: string | null = null;
+      try {
+        already = await kv.get(key);
+      } catch {
+        already = null;
+      }
+      if (already) continue;
+
+      const post = await readPost(store, input.tenantId, artifactPath, contentHash);
+      // Not live now (draft / not-yet-due scheduled) — do NOT set the key, so it is
+      // re-checked on the ship that eventually takes it live.
+      if (!post || !isVisibleOnLive(post, now)) continue;
+
+      // Transition guard: if the post was ALREADY live in the prior version, this ship
+      // did not take it live — PRIME the key (so we never re-read it) but do NOT notify.
+      const prevHash = fromManifest?.artifacts[artifactPath];
+      if (prevHash) {
+        const prev = await readPost(store, input.tenantId, artifactPath, prevHash);
+        if (prev && isVisibleOnLive(prev, now)) {
+          try {
+            await kv.put(key, now);
+          } catch {
+            /* best-effort prime */
+          }
+          continue;
+        }
+      }
+
+      // Genuine went-live transition — fire once, THEN set the posted key. If notify
+      // throws, the key is left unset so the next ship retries (at-least-check, at-most-post).
+      try {
+        await notify(input.tenantId, collection, slug, post);
+        await kv.put(key, now);
+      } catch (err) {
+        logDiag({
+          event: "notify_failed",
+          tenantId: input.tenantId,
+          collection,
+          slug,
+          error: (err as Error).message,
+        });
+      }
+    }
+  } catch (err) {
+    logDiag({
+      event: "hook_failed",
+      tenantId: input.tenantId,
+      toVersionId: input.toVersionId,
+      error: (err as Error).message,
+    });
+  }
+}

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

@@ -0,0 +1,32 @@
+import type { BlogPost } from "../blog/types.js";
+
+/** Swallow-and-log a soft failure — logging itself must never throw (mirrors `webhooks/emit.ts`). */
+function logDiag(fields: Record<string, unknown>): void {
+  try {
+    console.warn("[diag:social:notify]", JSON.stringify(fields));
+  } catch {
+    /* diagnostics must never break the caller */
+  }
+}
+
+/**
+ * The S3/S4 SEAM — the single call the go-live hook makes when a blog post
+ * transitions INTO a live-visible state (see {@link notifyPostsWentLive}). This
+ * unit (S1) ships the HOOK + the at-most-once idempotency key, NOT the network
+ * last-mile: v1 is a no-op announcement (logs only).
+ *
+ * S3 (the `SocialPublisher` interface + X adapter) and S4 (per-`(tenant,network)`
+ * config + encrypted token store) replace THIS body to compose a per-network
+ * payload — title, canonical URL, excerpt, featured image, `categories[0]` →
+ * hashtags — and POST it to each configured network's publish API. The signature
+ * is deliberately per-POST; per-network fan-out and the per-network idempotency
+ * key live one layer up in the hook, so extending to X + LinkedIn is additive.
+ */
+export async function notifyPostPublished(
+  tenantId: string,
+  collection: string,
+  slug: string,
+  post: BlogPost,
+): Promise<void> {
+  logDiag({ event: "post_published", tenantId, collection, slug, title: post.title });
+}