@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/secrets/__tests__/rotate.integration.test.ts

@@ -5,11 +5,13 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import { deleteMany, insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { deleteMany, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { AppContext } from "@cosmicdrift/kumiko-framework/engine";
+import { rebuildProjection } from "@cosmicdrift/kumiko-framework/pipeline";
 import {
   createEnvMasterKeyProvider,
-  encryptValue,
+  decodeStoredEnvelope,
+  decryptValue,
   type MasterKeyProvider,
 } from "@cosmicdrift/kumiko-framework/secrets";
 import {
@@ -21,7 +23,7 @@ import {
 import { createSecretsFeature } from "../feature";
 import { rotateJob } from "../handlers/rotate.job";
 import { createSecretsContext } from "../secrets-context";
-import { tenantSecretsTable } from "../table";
+import { type StoredEnvelope, tenantSecretsTable } from "../table";
 
 const admin = createTestUser({
   id: "00000000-0000-4000-8000-000000000010",
@@ -29,6 +31,15 @@ const admin = createTestUser({
   roles: ["TenantAdmin"],
 });
 
+// Captured so the happy-path rotation test can build a provider whose V1
+// key matches the seeded rows exactly — a fresh random V1 would fail the
+// GCM auth tag on every unwrap.
+const SEED_V1_KEY = randomBytes(32).toString("base64");
+// Shared with the happy-path test's rotator AND its verifier — the verifier
+// must decrypt with ONLY this key so a rewrap that bumps kek_version but
+// leaves the envelope V1-wrapped fails loud instead of silently passing.
+const ROTATED_V2_KEY = randomBytes(32).toString("base64");
+
 // A provider that encrypts happily on wrapDek but always rejects
 // unwrapDek. Simulates "KEK is unreachable / corrupt" — the failure mode
 // the circuit-breaker exists to contain. The returned object carries a
@@ -64,7 +75,7 @@ beforeAll(async () => {
   // Seeding the table uses a sane V1-only provider so writes land on V1.
   const seedProvider = createEnvMasterKeyProvider({
     env: {
-      KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+      KUMIKO_SECRETS_MASTER_KEY_V1: SEED_V1_KEY,
       KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
     },
   });
@@ -80,21 +91,12 @@ beforeAll(async () => {
     tenant_secrets: tenantSecretsTable,
   });
 
-  // Seed 20 V1 rows directly — too many for any maxFailures default.
+  // Seed 20 V1 rows through the real write path (executor.create) instead
+  // of a raw insertOne — the rotate job's executor.update needs an actual
+  // event stream to update against, which a headless projection row lacks.
+  const seedSecrets = createSecretsContext({ db: stack.db, masterKeyProvider: seedProvider });
   for (let i = 0; i < 20; i++) {
-    const envelope = await encryptValue(`secret-${i}`, seedProvider);
-    await insertOne(stack.db, tenantSecretsTable, {
-      tenantId: admin.tenantId,
-      key: `test:secret:k-${i}`,
-      envelope: {
-        ciphertext: envelope.ciphertext.toString("base64"),
-        iv: envelope.iv.toString("base64"),
-        authTag: envelope.authTag.toString("base64"),
-        encryptedDek: envelope.encryptedDek.toString("base64"),
-        kekVersion: envelope.kekVersion,
-      },
-      kekVersion: envelope.kekVersion,
-    });
+    await seedSecrets.set(admin.tenantId, `test:secret:k-${i}`, `secret-${i}`);
   }
 });
 
@@ -170,4 +172,99 @@ describe("rotate-job circuit-breaker", () => {
     expect(await countV1Rows()).toBe(20);
     expect(broken.calls()).toBe(25);
   });
+
+  // Happy-path counterpart to the failure tests above: a working provider
+  // that actually rewraps. Run last — it's the only test that mutates the
+  // shared 20-row fixture, so the earlier "stays at 20" assertions must
+  // see it before this runs. Enforced below, not just documented: a
+  // precondition check fails loud (not silently-wrong) if a test inserted
+  // between this and the circuit-breaker tests already touched the
+  // fixture — rotateJob's batch scan has no per-row exclusion/ordering
+  // to fall back on, so isolating this test onto a second tenant doesn't
+  // help (rotator would just exhaust maxFailures on the other tenant's
+  // still-V1 rows before ever reaching its own).
+  test("successful rotation rewraps the DEK, bumps kekVersion, and preserves plaintext", async () => {
+    expect(await countV1Rows()).toBe(20);
+
+    const rotator = createEnvMasterKeyProvider({
+      env: {
+        KUMIKO_SECRETS_MASTER_KEY_V1: SEED_V1_KEY,
+        KUMIKO_SECRETS_MASTER_KEY_V2: ROTATED_V2_KEY,
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "2",
+      },
+    });
+
+    // Snapshot pre-rotation ciphertext — rotate.job.ts's header comment
+    // claims "the ciphertext itself never changes, only the DEK wrapper".
+    // Assert that invariant below instead of only checking kekVersion/
+    // plaintext, which a rewrap-that-re-encrypts would also satisfy.
+    const preRotation = await selectMany<{ key: string; envelope: StoredEnvelope }>(
+      stack.db,
+      tenantSecretsTable,
+      { tenantId: admin.tenantId },
+    );
+    const ciphertextByKey = new Map(preRotation.map((row) => [row.key, row.envelope.ciphertext]));
+
+    await rotateJob({ batchSize: 10, maxFailures: 5 }, jobCtx(rotator));
+
+    expect(await countV1Rows()).toBe(0);
+
+    // Decrypt with a V2-ONLY provider — no V1 key available. A rewrap
+    // that only bumped the kek_version column but left the envelope
+    // wrapped under V1 would throw "no KEK for version 1" here instead
+    // of silently passing, which a decrypt via `rotator` (V1+V2) can't
+    // catch since it still holds V1.
+    const verifier = createEnvMasterKeyProvider({
+      env: {
+        KUMIKO_SECRETS_MASTER_KEY_V2: ROTATED_V2_KEY,
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "2",
+      },
+    });
+
+    const rows = await selectMany<{ key: string; envelope: StoredEnvelope; kekVersion: number }>(
+      stack.db,
+      tenantSecretsTable,
+      { tenantId: admin.tenantId },
+    );
+    expect(rows).toHaveLength(20);
+    for (const row of rows) {
+      expect(row.kekVersion).toBe(2);
+      const expectedCiphertext = ciphertextByKey.get(row.key);
+      expect(expectedCiphertext).toBeDefined();
+      expect(row.envelope.ciphertext).toBe(expectedCiphertext as string);
+      const expectedIndex = row.key.split("-").at(-1);
+      const plaintext = await decryptValue(decodeStoredEnvelope(row.envelope), verifier);
+      expect(plaintext).toBe(`secret-${expectedIndex}`);
+    }
+
+    // Regression guard (kumiko-framework#1189): rotate.job.ts's
+    // executor.update() call carries no options, so it deliberately
+    // never sets skipUnchanged — every rotation writes a real .updated
+    // event, not a raw UPDATE. A full projection rebuild replays those
+    // events; if a future refactor added skipUnchanged (or swapped the
+    // event write for a raw column update) the rebuild would resurrect
+    // the pre-rotation V1 envelopes instead of landing on V2, exactly
+    // the #464 failure class config/auth-mfa already guard against.
+    //
+    // Vacuous-rebuild guard: confirm the projection name actually exists
+    // and the rebuild really replayed events, so a wrong projection name
+    // can't silently no-op the assertion below into a false pass.
+    const projectionName = "secrets:projection:tenant-secret-entity";
+    expect(stack.registry.getAllProjections().has(projectionName)).toBe(true);
+    const rebuildResult = await rebuildProjection(projectionName, {
+      db: stack.db,
+      registry: stack.registry,
+    });
+    expect(rebuildResult.eventsProcessed).toBeGreaterThan(0);
+
+    const rowsAfterRebuild = await selectMany<{ key: string; kekVersion: number }>(
+      stack.db,
+      tenantSecretsTable,
+      { tenantId: admin.tenantId },
+    );
+    expect(rowsAfterRebuild).toHaveLength(20);
+    for (const row of rowsAfterRebuild) {
+      expect(row.kekVersion).toBe(2);
+    }
+  });
 });

package/src/secrets/handlers/rotate.job.ts

@@ -26,7 +26,12 @@ import {
 } from "@cosmicdrift/kumiko-framework/db";
 import type { JobHandlerFn, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
-import { rewrapDek } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  decodeStoredEnvelope,
+  encodeStoredEnvelope,
+  rewrapDek,
+} from "@cosmicdrift/kumiko-framework/secrets";
+import { type ChunkedMigrationStopReason, runChunkedMigration } from "../../shared";
 import { type StoredEnvelope, tenantSecretEntity, tenantSecretsTable } from "../table";
 
 const DEFAULT_BATCH_SIZE = 100;
@@ -47,7 +52,7 @@ export type RotateJobResult = {
   readonly migrated: number;
   readonly failed: number;
   readonly batchesProcessed: number;
-  readonly stoppedReason: "empty" | "timeout" | "signal" | "too_many_failures";
+  readonly stoppedReason: ChunkedMigrationStopReason;
 };
 
 export const rotateJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
@@ -71,11 +76,6 @@ export const rotateJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> =>
     ? Date.now() + payload.maxDurationMs
     : Number.POSITIVE_INFINITY;
 
-  let migrated = 0;
-  let failed = 0;
-  let batchesProcessed = 0;
-  let stoppedReason: RotateJobResult["stoppedReason"] = "empty";
-
   // Reuse a TenantDb-per-tenant map so we don't rebuild the wrapper for
   // each row in the same tenant. Rotation typically hits one tenant in a
   // batch; the map trims an allocation without adding complexity.
@@ -89,101 +89,80 @@ export const rotateJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> =>
     return existing;
   }
 
-  while (true) {
-    if (ctx.signal?.aborted) {
-      stoppedReason = "signal";
-      break;
-    }
-    if (Date.now() >= deadline) {
-      stoppedReason = "timeout";
-      break;
-    }
-
-    const targetVersion = provider.currentVersion();
-    const batch = await selectMany<{
-      id: string;
-      tenantId: string;
-      version: number;
-      envelope: StoredEnvelope;
-      kekVersion: number;
-    }>(db, tenantSecretsTable, { kekVersion: { ne: targetVersion } }, { limit: batchSize });
-
-    if (batch.length === 0) break;
-
-    batchesProcessed++;
-
-    if (failed >= maxFailures) {
-      stoppedReason = "too_many_failures";
-      break;
-    }
-
-    for (const row of batch) {
-      if (failed >= maxFailures) {
-        stoppedReason = "too_many_failures";
-        break;
-      }
-      try {
-        const oldEnvelope = {
-          ciphertext: Buffer.from(row.envelope.ciphertext, "base64"),
-          iv: Buffer.from(row.envelope.iv, "base64"),
-          authTag: Buffer.from(row.envelope.authTag, "base64"),
-          encryptedDek: Buffer.from(row.envelope.encryptedDek, "base64"),
-          kekVersion: row.envelope.kekVersion,
-        };
-        const rotated = await rewrapDek(oldEnvelope, provider);
-
-        if (rotated.kekVersion === row.kekVersion) continue;
+  type SecretRow = {
+    id: string;
+    tenantId: string;
+    version: number;
+    envelope: StoredEnvelope;
+    kekVersion: number;
+  };
+
+  // A partial batch means the ne-filter is exhausted — the next re-query
+  // would only re-serve rows that failed above; end the run instead.
+  let sawPartialBatch = false;
+  async function nextBatch(): Promise<readonly SecretRow[]> {
+    if (sawPartialBatch) return [];
+    const batch = await selectMany<SecretRow>(
+      db,
+      tenantSecretsTable,
+      { kekVersion: { ne: provider.currentVersion() } },
+      { limit: batchSize },
+    );
+    if (batch.length < batchSize) sawPartialBatch = true;
+    return batch;
+  }
 
-        const newEnvelope: StoredEnvelope = {
-          ciphertext: rotated.ciphertext.toString("base64"),
-          iv: rotated.iv.toString("base64"),
-          authTag: rotated.authTag.toString("base64"),
-          encryptedDek: rotated.encryptedDek.toString("base64"),
+  async function migrateRow(row: SecretRow): Promise<"migrated" | "skipped" | "failed"> {
+    const rotated = await rewrapDek(decodeStoredEnvelope(row.envelope), provider);
+    if (rotated.kekVersion === row.kekVersion) return "skipped";
+
+    const actor: SessionUser = {
+      id: "system",
+      tenantId: row.tenantId as TenantId,
+      roles: SYSTEM_ROLES,
+    };
+    const result = await executor.update(
+      {
+        id: row.id,
+        version: row.version,
+        changes: {
+          envelope: encodeStoredEnvelope(rotated),
           kekVersion: rotated.kekVersion,
-        };
-
-        const actor: SessionUser = {
-          id: "system",
-          tenantId: row.tenantId as TenantId,
-          roles: SYSTEM_ROLES,
-        };
-
-        const result = await executor.update(
-          {
-            id: row.id,
-            version: row.version,
-            changes: {
-              envelope: newEnvelope,
-              kekVersion: rotated.kekVersion,
-            },
-          },
-          actor,
-          tdbFor(row.tenantId as TenantId),
-        );
-
-        // version_conflict == another writer (secrets.set or a parallel
-        // rotation worker) beat us. Count as "skipped" and move on — the
-        // row is already in a valid state, potentially even past target.
-        if (!result.isSuccess) {
-          if (result.error.code === "version_conflict") continue;
-          failed++;
-          ctx.log?.warn?.(`[secrets:rotate] executor rejected row ${row.id}`, {
-            code: result.error.code,
-          });
-          continue;
-        }
-      } catch (err) {
-        failed++;
-        ctx.log?.warn?.(`[secrets:rotate] failed to rotate row ${row.id}`, { err });
-        continue;
-      }
-      migrated++;
+        },
+      },
+      actor,
+      tdbFor(row.tenantId as TenantId),
+    );
+
+    // version_conflict == another writer (secrets.set or a parallel
+    // rotation worker) beat us — the row is already in a valid state,
+    // potentially even past target.
+    if (!result.isSuccess) {
+      if (result.error.code === "version_conflict") return "skipped";
+      ctx.log?.warn?.(`[secrets:rotate] executor rejected row ${row.id}`, {
+        code: result.error.code,
+      });
+      return "failed";
     }
-
-    if (stoppedReason === "too_many_failures") break;
-    if (batch.length < batchSize) break;
+    return "migrated";
   }
 
-  const result: RotateJobResult = { migrated, failed, batchesProcessed, stoppedReason };
+  const outcome = await runChunkedMigration<SecretRow>({
+    nextBatch,
+    migrateRow,
+    maxFailures,
+    deadlineAt: deadline,
+    signal: ctx.signal,
+    onRowError: (row, err) => {
+      ctx.log?.warn?.(`[secrets:rotate] failed to rotate row ${row.id}`, { err });
+    },
+  });
+
+  const result: RotateJobResult = {
+    migrated: outcome.migrated,
+    failed: outcome.failed,
+    batchesProcessed: outcome.batchesProcessed,
+    stoppedReason: outcome.stoppedReason,
+  };
   ctx.log?.info?.(`[secrets:rotate] complete: ${JSON.stringify(result)}`);
 };

package/src/secrets/secrets-context.ts

@@ -25,10 +25,13 @@ import {
   createDekCache,
   createSecret,
   type DekCache,
+  decodeStoredEnvelope,
   decryptValue,
+  encodeStoredEnvelope,
   encryptValue,
   type MasterKeyProvider,
   type SecretsContext,
+  withDekCache,
 } from "@cosmicdrift/kumiko-framework/secrets";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { z } from "zod";
@@ -79,37 +82,9 @@ function resolveKey(keyOrHandle: string | { readonly name: string }): string {
   return typeof keyOrHandle === "string" ? keyOrHandle : keyOrHandle.name;
 }
 
-// Wrap a provider so its unwrapDek goes through the cache. Lets decryptValue
-// use the full provider contract without knowing about caching — separation
-// of concerns: decryptValue handles crypto, cache handles cost.
-function cachedProvider(provider: MasterKeyProvider, cache: DekCache): MasterKeyProvider {
-  return {
-    wrapDek: provider.wrapDek.bind(provider),
-    unwrapDek: (encryptedDek, version) => cache.unwrapDek(encryptedDek, version, provider),
-    currentVersion: provider.currentVersion.bind(provider),
-    isAvailable: provider.isAvailable.bind(provider),
-  };
-}
-
-function decodeEnvelope(stored: StoredEnvelope): {
-  ciphertext: Buffer;
-  iv: Buffer;
-  authTag: Buffer;
-  encryptedDek: Buffer;
-  kekVersion: number;
-} {
-  return {
-    ciphertext: Buffer.from(stored.ciphertext, "base64"),
-    iv: Buffer.from(stored.iv, "base64"),
-    authTag: Buffer.from(stored.authTag, "base64"),
-    encryptedDek: Buffer.from(stored.encryptedDek, "base64"),
-    kekVersion: stored.kekVersion,
-  };
-}
-
 export function createSecretsContext(opts: SecretsContextOptions): SecretsContext {
   const { db, masterKeyProvider } = opts;
-  const provider = cachedProvider(masterKeyProvider, opts.dekCache ?? createDekCache());
+  const provider = withDekCache(masterKeyProvider, opts.dekCache ?? createDekCache());
 
   type SecretLookupRow = {
     readonly id: string;
@@ -133,7 +108,7 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
       if (!auditCtx) {
         const existing = await lookup(tenantId, key);
         if (!existing) return undefined;
-        const plaintext = await decryptValue(decodeEnvelope(existing.envelope), provider);
+        const plaintext = await decryptValue(decodeStoredEnvelope(existing.envelope), provider);
         return createSecret(plaintext);
       }
 
@@ -142,7 +117,7 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
         // type doesn't widen to the transaction object cleanly.
         const envelope = await selectTenantSecretEnvelope(tx, tenantId, key);
         if (!envelope) return undefined;
-        const pt = await decryptValue(decodeEnvelope(envelope), provider);
+        const pt = await decryptValue(decodeStoredEnvelope(envelope), provider);
 
         // One event per read on its own aggregate-stream (fresh UUID as
         // aggregateId). Avoids version-conflicts between parallel reads —
@@ -190,13 +165,7 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
     async set(tenantId, keyOrHandle, value, setOpts = {}) {
       const key = resolveKey(keyOrHandle);
       const envelope = await encryptValue(value, masterKeyProvider);
-      const stored: StoredEnvelope = {
-        ciphertext: envelope.ciphertext.toString("base64"),
-        iv: envelope.iv.toString("base64"),
-        authTag: envelope.authTag.toString("base64"),
-        encryptedDek: envelope.encryptedDek.toString("base64"),
-        kekVersion: envelope.kekVersion,
-      };
+      const stored: StoredEnvelope = encodeStoredEnvelope(envelope);
       const metadata: StoredMetadata = {
         ...(setOpts.redact ? { redactedPreview: setOpts.redact(value) } : {}),
         ...(setOpts.hint ? { hint: setOpts.hint } : {}),

package/src/secrets/table.ts

@@ -13,6 +13,7 @@ import {
   createNumberField,
   createTextField,
 } from "@cosmicdrift/kumiko-framework/engine";
+import type { StoredEnvelope } from "@cosmicdrift/kumiko-framework/secrets";
 
 // Envelope stored as a single jsonb blob. All ops are upsert-by-(tenantId, key)
 // so there's no value in decomposing the envelope into separate columns —
@@ -22,13 +23,11 @@ import {
 // `WHERE kek_version != currentVersion()` with an index on just that column
 // without deserializing the jsonb. Duplicated inside envelope too — the two
 // always stay in sync via the write path.
-export type StoredEnvelope = {
-  readonly ciphertext: string; // base64
-  readonly iv: string; // base64
-  readonly authTag: string; // base64
-  readonly encryptedDek: string; // base64
-  readonly kekVersion: number;
-};
+//
+// StoredEnvelope itself is canonical in @cosmicdrift/kumiko-framework/secrets
+// (shared with EnvelopeCipher for TEXT-column stores) — re-exported here so
+// existing consumers keep their import path.
+export type { StoredEnvelope } from "@cosmicdrift/kumiko-framework/secrets";
 
 export type StoredMetadata = {
   readonly redactedPreview?: string;
@@ -50,7 +49,7 @@ export const tenantSecretEntity = createEntity({
   table: "read_tenant_secrets",
   fields: {
     key: createTextField({ required: true }),
-    kekVersion: createNumberField({ required: true }),
+    kekVersion: createNumberField({ required: true, integer: true }),
   },
 });
 

package/src/seo/__tests__/llms-txt.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { buildLlmsTxt } from "../llms-txt";
+
+describe("buildLlmsTxt", () => {
+  test("emits H1 title + blockquote summary", () => {
+    const text = buildLlmsTxt({ title: "Acme", summary: "Acme does things." });
+    expect(text).toStartWith("# Acme\n\n> Acme does things.");
+  });
+
+  test("emits ## sections with markdown links", () => {
+    const text = buildLlmsTxt({
+      title: "Acme",
+      summary: "s",
+      sections: [
+        {
+          heading: "Pages",
+          links: [{ title: "About", url: "https://acme.test/about", desc: "About us" }],
+        },
+      ],
+    });
+    expect(text).toContain("## Pages");
+    expect(text).toContain("- [About](https://acme.test/about): About us");
+  });
+
+  test("empty sections are omitted, no trailing section markers", () => {
+    const text = buildLlmsTxt({
+      title: "Acme",
+      summary: "s",
+      sections: [{ heading: "Empty", links: [] }],
+    });
+    expect(text).not.toContain("## Empty");
+  });
+
+  test("no summary → no blockquote line", () => {
+    const text = buildLlmsTxt({ title: "Acme", summary: "" });
+    expect(text).toBe("# Acme\n");
+  });
+});

package/src/seo/__tests__/robots-txt.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test";
+import { buildRobotsTxt } from "../robots-txt";
+
+describe("buildRobotsTxt", () => {
+  test("allow: true → no Disallow rule", () => {
+    expect(buildRobotsTxt({ allow: true })).toBe("User-agent: *\nDisallow:\n");
+  });
+
+  test("allow: false → Disallow: /", () => {
+    expect(buildRobotsTxt({ allow: false })).toBe("User-agent: *\nDisallow: /\n");
+  });
+
+  test("sitemapUrl appends a Sitemap line", () => {
+    expect(buildRobotsTxt({ allow: true, sitemapUrl: "https://acme.test/sitemap.xml" })).toBe(
+      "User-agent: *\nDisallow:\nSitemap: https://acme.test/sitemap.xml\n",
+    );
+  });
+});

package/src/seo/__tests__/schema-builders.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import { faqPageSchema, organizationSchema, webPageSchema } from "../schema-builders";
+
+describe("organizationSchema", () => {
+  test("minimal input", () => {
+    expect(organizationSchema({ name: "Acme" })).toEqual({
+      "@context": "https://schema.org",
+      "@type": "Organization",
+      name: "Acme",
+    });
+  });
+
+  test("full input", () => {
+    expect(
+      organizationSchema({
+        name: "Acme",
+        url: "https://acme.test",
+        logoUrl: "https://acme.test/logo.png",
+        sameAs: ["https://x.com/acme"],
+      }),
+    ).toEqual({
+      "@context": "https://schema.org",
+      "@type": "Organization",
+      name: "Acme",
+      url: "https://acme.test",
+      logo: "https://acme.test/logo.png",
+      sameAs: ["https://x.com/acme"],
+    });
+  });
+});
+
+describe("webPageSchema", () => {
+  test("emits WebPage type", () => {
+    expect(webPageSchema({ name: "About", url: "https://acme.test/about" })).toMatchObject({
+      "@type": "WebPage",
+      name: "About",
+      url: "https://acme.test/about",
+    });
+  });
+});
+
+describe("faqPageSchema", () => {
+  test("maps question/answer pairs to mainEntity", () => {
+    const schema = faqPageSchema([{ question: "Q1?", answer: "A1." }]);
+    expect(schema).toEqual({
+      "@context": "https://schema.org",
+      "@type": "FAQPage",
+      mainEntity: [
+        {
+          "@type": "Question",
+          name: "Q1?",
+          acceptedAnswer: { "@type": "Answer", text: "A1." },
+        },
+      ],
+    });
+  });
+});