@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/seo/feature.ts

@@ -0,0 +1,316 @@
+import { computeRevisionEtag } from "@cosmicdrift/kumiko-framework/api";
+import {
+  defineFeature,
+  type FeatureDefinition,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { LEGAL_ROUTES } from "../legal-pages";
+import { cachedSecurePageResponse } from "../page-render";
+import type { SystemQueryFn } from "../shared";
+import { SEO_CONFIG_KEYS, SEO_DEFAULT_PATHS } from "./constants";
+import { seoConfigQuery } from "./handlers/seo-config.query";
+import { buildLlmsTxt } from "./llms-txt";
+import { buildRobotsTxt, type RobotsPolicy } from "./robots-txt";
+import { buildSitemapXml, type SitemapEntry } from "./sitemap";
+
+// 300s-shared-cache: sitemap/llms.txt change rarely (new page publish, not
+// per-request), longer than legal-pages/managed-pages' 60s content cache.
+const SEO_CACHE = { kind: "revalidate", maxAgeSeconds: 300 } as const;
+
+const MANAGED_PAGES_BY_TENANT_PUBLISHED_QN = "managed-pages:query:by-tenant-published";
+const SEO_CONFIG_QUERY_QN = "seo:query:config";
+
+export type ManagedPagesDiscoveryOptions = {
+  /** Same per-host tenant resolver the app already passes to
+   *  createManagedPagesFeature — needed to X-Tenant-scope the anonymous
+   *  by-tenant-published query. */
+  readonly resolveApexTenant: (host: string) => Promise<string | null> | string | null;
+  /** Must match the basePath passed to createManagedPagesFeature. Default "/p". */
+  readonly basePath?: string;
+};
+
+export type SeoOptions = {
+  /** Primary page inventory for sitemap.xml/llms.txt. App-authored, trusted
+   *  (same trust boundary as ApexCta.href) — return fully-qualified absolute
+   *  URLs. Called once per request with the resolved request Host. */
+  readonly sitemapEntries: (
+    host: string,
+  ) => Promise<readonly SitemapEntry[]> | readonly SitemapEntry[];
+  /** Merge legal-pages' 4 fixed routes into sitemap.xml/llms.txt. Set true
+   *  only when the app ALSO mounts createLegalPagesFeature() — this does not
+   *  detect it automatically (no such feature-presence hook exists at the
+   *  httpRoute layer). Default false. */
+  readonly includeLegalPages?: boolean;
+  /** Merge managed-pages' published slugs (via its anonymous
+   *  by-tenant-published query) into sitemap.xml/llms.txt. Omit if the app
+   *  doesn't mount managed-pages, or already includes those URLs in
+   *  `sitemapEntries` itself. */
+  readonly managedPages?: ManagedPagesDiscoveryOptions;
+  /** Serves GET /robots.txt with per-host policy. Default: no route — the
+   *  static `public/robots.txt` dev-server already ships covers the common
+   *  case (no per-host logic needed). Only opt in for staging/preview hosts
+   *  that need a different (e.g. Disallow: /) policy at runtime. */
+  readonly robotsPolicy?: (host: string) => Promise<RobotsPolicy> | RobotsPolicy;
+  /** Override the 3 mount paths. Default: /sitemap.xml, /llms.txt, /robots.txt. */
+  readonly basePaths?: Partial<typeof SEO_DEFAULT_PATHS>;
+};
+
+type SeoConfigValues = {
+  readonly organizationName: string;
+  readonly organizationLogoUrl: string;
+  readonly twitterSite: string;
+  readonly llmsSummary: string;
+  readonly defaultOgImage: string;
+};
+
+const EMPTY_SEO_CONFIG: SeoConfigValues = {
+  organizationName: "",
+  organizationLogoUrl: "",
+  twitterSite: "",
+  llmsSummary: "",
+  defaultOgImage: "",
+};
+
+// Config is decoration, not a hard dependency — a failed/unreachable read
+// degrades to empty strings (same posture as managed-pages' readBrandingResponse).
+// systemQuery forces tenantId in-process — no internal X-Tenant self-fetch,
+// which a host-based anonymousAccess resolver in "authoritative" mode would
+// reject as a forged client override.
+async function readSeoConfig(
+  systemQuery: SystemQueryFn,
+  tenantId: string,
+): Promise<SeoConfigValues> {
+  try {
+    const data = (await systemQuery(SEO_CONFIG_QUERY_QN, {}, tenantId)) as Partial<SeoConfigValues>;
+    return { ...EMPTY_SEO_CONFIG, ...data };
+  } catch {
+    return EMPTY_SEO_CONFIG;
+  }
+}
+
+// Merges the app callback with the optional legal-pages/managed-pages
+// sources. legal-pages routes are static (no per-tenant data) — merged
+// directly from the public LEGAL_ROUTES constant. managed-pages entries need
+// a live query (per-tenant published slugs) — merged via systemQuery, same
+// cross-feature decoupling as legal-pages' own text-content calls; a
+// failed/unreachable read degrades to "no managed-pages entries" rather than
+// failing the whole route.
+async function gatherEntries(
+  opts: SeoOptions,
+  systemQuery: SystemQueryFn,
+  origin: string,
+  host: string,
+): Promise<SitemapEntry[]> {
+  const entries: SitemapEntry[] = [...(await opts.sitemapEntries(host))];
+
+  if (opts.includeLegalPages) {
+    for (const route of LEGAL_ROUTES) {
+      entries.push({ loc: `${origin}${route.path}` });
+    }
+  }
+
+  if (opts.managedPages) {
+    const tenantId = await opts.managedPages.resolveApexTenant(host);
+    if (tenantId) {
+      try {
+        const data = (await systemQuery(MANAGED_PAGES_BY_TENANT_PUBLISHED_QN, {}, tenantId)) as {
+          pages?: readonly { slug: string; title: string; updatedAt: string }[];
+        };
+        const basePath = opts.managedPages.basePath ?? "/p";
+        for (const page of data.pages ?? []) {
+          entries.push({
+            loc: `${origin}${basePath}/${page.slug}`,
+            title: page.title,
+            lastmod: page.updatedAt,
+          });
+        }
+      } catch {
+        // managed-pages unreachable/not mounted — degrade to callback-only entries.
+      }
+    }
+  }
+
+  return entries;
+}
+
+// TLS-terminating reverse proxies (ingress-nginx et al.) forward the
+// original request over plain HTTP internally, so `c.req.url`'s scheme
+// reflects the proxy hop, not what the client actually used — trusting it
+// downgraded every legal-pages/managed-pages URL in sitemap.xml/llms.txt to
+// http:// in production. `x-forwarded-proto` carries the real scheme;
+// fall back to the raw URL only when the header is absent (plain local dev).
+function requestHost(c: { req: { header: (name: string) => string | undefined; url: string } }): {
+  origin: string;
+  host: string;
+} {
+  const url = new URL(c.req.url);
+  const host = c.req.header("host") ?? url.host;
+  const forwardedProto = c.req.header("x-forwarded-proto")?.split(",")[0]?.trim();
+  const protocol =
+    forwardedProto === "https" || forwardedProto === "http"
+      ? forwardedProto
+      : url.protocol.replace(":", "");
+  return { origin: `${protocol}://${host}`, host };
+}
+
+// seo — site-discovery routes (sitemap.xml/llms.txt/robots.txt) plus the
+// wrapInLayout OG/JSON-LD extension (page-render/layout.ts's `seo` opt) and
+// the organizationSchema/webPageSchema/faqPageSchema JSON-LD builders
+// (schema-builders.ts, imported directly by apps — not wired into this
+// feature's own routes). Complements the apex ApexHead/renderApexPage
+// renderer, which already ships full OG/JSON-LD/canonical head handling —
+// this feature only fills the site-discovery + CMS-page-head gaps.
+export function createSeoFeature(opts: SeoOptions): FeatureDefinition {
+  const paths = { ...SEO_DEFAULT_PATHS, ...opts.basePaths };
+
+  return defineFeature("seo", (r) => {
+    r.describe(
+      `Site-discovery + SEO/AEO/GEO surface for apex/content pages. Serves GET ${paths.sitemap} and GET ${paths.llmsTxt} (both anonymous, revalidate-cached), merging the app-supplied sitemapEntries() callback with legal-pages' fixed routes (includeLegalPages) and/or managed-pages' published slugs (managedPages.resolveApexTenant) when opted in. Serves GET ${paths.robots} only when robotsPolicy is supplied (default off — the static public/robots.txt already covers the common case). Tenant-scoped config keys (seo:config:seo-organization-{name,logo-url}, seo:config:seo-twitter-site, seo:config:seo-llms-summary, seo:config:seo-default-og-image) feed the Organization JSON-LD helper + llms.txt summary. Also exports pure schema.org JSON-LD builders (organizationSchema/webPageSchema/faqPageSchema) for apps to pass into ApexHead.schemaJson or wrapInLayout({ seo: { schemaJson } }) directly — this feature does not inject JSON-LD on its own routes.`,
+    );
+    r.uiHints({
+      displayLabel: "SEO / Site Discovery",
+      category: "content",
+      recommended: false,
+    });
+    // config keys need the config feature's write/read machinery to actually
+    // function (same hard dependency managed-pages has) — only legal-pages/
+    // managed-pages are genuinely optional (merged only when opted in).
+    r.requires("config");
+    r.optionalRequires("legal-pages", "managed-pages");
+
+    r.config({ keys: SEO_CONFIG_KEYS });
+    r.queryHandler(seoConfigQuery);
+
+    r.httpRoute({
+      method: "GET",
+      path: paths.sitemap,
+      anonymous: true,
+      handler: async (c, { systemQuery }) => {
+        const { origin, host } = requestHost(c);
+        const entries = await gatherEntries(opts, systemQuery, origin, host);
+        const xml = buildSitemapXml(entries);
+        const etag = computeRevisionEtag([host, xml]);
+        return cachedSecurePageResponse(c.req.raw, {
+          body: xml,
+          etag,
+          cache: SEO_CACHE,
+          extra: { "content-type": "application/xml; charset=utf-8" },
+        });
+      },
+    });
+
+    r.httpRoute({
+      method: "GET",
+      path: paths.llmsTxt,
+      anonymous: true,
+      handler: async (c, { systemQuery }) => {
+        const { origin, host } = requestHost(c);
+        const tenantId = opts.managedPages
+          ? ((await opts.managedPages.resolveApexTenant(host)) ?? SYSTEM_TENANT_ID)
+          : SYSTEM_TENANT_ID;
+        const [entries, seoConfig] = await Promise.all([
+          gatherEntries(opts, systemQuery, origin, host),
+          readSeoConfig(systemQuery, tenantId),
+        ]);
+        const sections =
+          entries.length > 0
+            ? [
+                {
+                  heading: "Pages",
+                  links: entries.map((e) => ({ title: e.title ?? e.loc, url: e.loc })),
+                },
+              ]
+            : [];
+        const text = buildLlmsTxt({
+          title: seoConfig.organizationName || host,
+          summary: seoConfig.llmsSummary,
+          sections,
+        });
+        const etag = computeRevisionEtag([host, text]);
+        return cachedSecurePageResponse(c.req.raw, {
+          body: text,
+          etag,
+          cache: SEO_CACHE,
+          extra: { "content-type": "text/plain; charset=utf-8" },
+        });
+      },
+    });
+
+    if (opts.robotsPolicy) {
+      const robotsPolicy = opts.robotsPolicy;
+      r.httpRoute({
+        method: "GET",
+        path: paths.robots,
+        anonymous: true,
+        handler: async (c) => {
+          const { host } = requestHost(c);
+          const policy = await robotsPolicy(host);
+          const text = buildRobotsTxt(policy);
+          const etag = computeRevisionEtag([host, text]);
+          return cachedSecurePageResponse(c.req.raw, {
+            body: text,
+            etag,
+            cache: SEO_CACHE,
+            extra: { "content-type": "text/plain; charset=utf-8" },
+          });
+        },
+      });
+    }
+
+    // Boot-Check body als named function extrahiert — direkt unit-testbar,
+    // gleiches "thin job-shell ruft testable function"-Pattern wie
+    // legal-pages' runLegalPagesBootCheck.
+    r.job(
+      "seo-boot-check",
+      { trigger: { manual: true }, runOnBoot: true, runIn: "api" },
+      async (_payload, ctx) =>
+        runSeoBootCheck({
+          sitemapEntries: opts.sitemapEntries,
+          includeLegalPages: opts.includeLegalPages ?? false,
+          hasManagedPages: opts.managedPages !== undefined,
+          log: ctx.log,
+        }),
+    );
+
+    return {};
+  });
+}
+
+export type SeoBootCheckCtx = {
+  readonly sitemapEntries: (
+    host: string,
+  ) => Promise<readonly SitemapEntry[]> | readonly SitemapEntry[];
+  readonly includeLegalPages: boolean;
+  /** managedPages entries are only resolvable per-request (need a live
+   *  tenant + query) — the boot-check can't probe them, so their mere
+   *  presence counts as "has a source" rather than sampling actual rows. */
+  readonly hasManagedPages: boolean;
+  readonly log?: {
+    readonly info?: (msg: string) => void;
+    readonly warn?: (msg: string) => void;
+  };
+};
+
+// Exported for direct tests. Throws in NODE_ENV=production when NONE of the
+// three entry sources (sitemapEntries() probe, includeLegalPages,
+// managedPages) can supply anything — the routes would otherwise serve a
+// permanently empty document. Otherwise log.warn. Logs log.info when at
+// least one source is present.
+export async function runSeoBootCheck(ctx: SeoBootCheckCtx): Promise<void> {
+  const sample = await ctx.sitemapEntries("boot-check.invalid");
+  const hasSource = sample.length > 0 || ctx.includeLegalPages || ctx.hasManagedPages;
+
+  if (hasSource) {
+    ctx.log?.info?.("seo boot-check: sitemap/llms.txt have at least one entry source");
+  } else {
+    const message =
+      "seo: sitemapEntries() returned no entries and neither includeLegalPages " +
+      "nor managedPages is set — sitemap.xml/llms.txt will serve an empty " +
+      "document. Wire real entries, set includeLegalPages:true, or pass managedPages.";
+
+    if (process.env["NODE_ENV"] === "production") {
+      throw new Error(`Boot-Validation failed: ${message}`);
+    }
+    ctx.log?.warn?.(message);
+  }
+}

package/src/seo/handlers/seo-config.query.ts

@@ -0,0 +1,35 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { SEO_CONFIG_QN } from "../constants";
+
+// Public read of the seo feature's own tenant-config values, for the
+// anonymous sitemap.xml/llms.txt routes (a Response is per-request; those
+// routes only get `{ app }`, not `ctx.config` directly, so they reach this
+// the same way managed-pages' render route reaches its branding query — an
+// internal app.fetch with X-Tenant set to the resolved tenant).
+//
+// config:query:values (the generic config feature query) is NOT usable here:
+// it requires an authenticated caller (any role) even though its per-key
+// access defaults to read:all — a genuinely anonymous visitor gets 403 before
+// per-key filtering ever runs. This mirrors managed-pages' branding query
+// instead (`access: { roles: ["anonymous", ...] }`), the pattern actually
+// proven to work for anonymous-served pages.
+export const seoConfigQuery = defineQueryHandler({
+  name: "config",
+  schema: z.object({}),
+  access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  handler: async (_query, ctx) => {
+    const read = async (qualifiedKey: string): Promise<string> => {
+      if (!ctx.config) return "";
+      const value = await ctx.config(qualifiedKey);
+      return typeof value === "string" ? value : "";
+    };
+    return {
+      organizationName: await read(SEO_CONFIG_QN.organizationName),
+      organizationLogoUrl: await read(SEO_CONFIG_QN.organizationLogoUrl),
+      twitterSite: await read(SEO_CONFIG_QN.twitterSite),
+      llmsSummary: await read(SEO_CONFIG_QN.llmsSummary),
+      defaultOgImage: await read(SEO_CONFIG_QN.defaultOgImage),
+    };
+  },
+});

package/src/seo/index.ts

@@ -0,0 +1,19 @@
+export { SEO_CONFIG_KEYS, SEO_CONFIG_QN, SEO_DEFAULT_PATHS, SEO_FEATURE } from "./constants";
+export {
+  createSeoFeature,
+  type ManagedPagesDiscoveryOptions,
+  runSeoBootCheck,
+  type SeoBootCheckCtx,
+  type SeoOptions,
+} from "./feature";
+export { buildLlmsTxt, type LlmsTxtInput, type LlmsTxtLink, type LlmsTxtSection } from "./llms-txt";
+export { buildRobotsTxt, type RobotsPolicy } from "./robots-txt";
+export {
+  type FaqItem,
+  faqPageSchema,
+  type OrganizationSchemaInput,
+  organizationSchema,
+  type WebPageSchemaInput,
+  webPageSchema,
+} from "./schema-builders";
+export { buildSitemapXml, type SitemapEntry } from "./sitemap";

package/src/seo/llms-txt.ts

@@ -0,0 +1,33 @@
+export type LlmsTxtLink = {
+  readonly title: string;
+  readonly url: string;
+  readonly desc?: string;
+};
+
+export type LlmsTxtSection = {
+  readonly heading: string;
+  readonly links: readonly LlmsTxtLink[];
+};
+
+export type LlmsTxtInput = {
+  readonly title: string;
+  readonly summary: string;
+  readonly sections?: readonly LlmsTxtSection[];
+};
+
+// Plain-text builder for the community llms.txt convention (H1 title,
+// blockquote summary, `## `-headed link lists). No HTML escaping needed —
+// Markdown link syntax, plain-text output.
+export function buildLlmsTxt(input: LlmsTxtInput): string {
+  const sections = (input.sections ?? [])
+    .filter((s) => s.links.length > 0)
+    .map((s) => {
+      const links = s.links
+        .map((l) => `- [${l.title}](${l.url})${l.desc ? `: ${l.desc}` : ""}`)
+        .join("\n");
+      return `## ${s.heading}\n\n${links}`;
+    })
+    .join("\n\n");
+  const summary = input.summary ? `\n\n> ${input.summary}` : "";
+  return `# ${input.title}${summary}${sections ? `\n\n${sections}` : ""}\n`;
+}

package/src/seo/robots-txt.ts

@@ -0,0 +1,13 @@
+export type RobotsPolicy = {
+  readonly allow: boolean;
+  readonly sitemapUrl?: string;
+};
+
+// Only used when an app opts into GET /robots.txt (SeoOptions.robotsPolicy) —
+// the common case (no per-host logic) is already covered by dev-server's
+// static public/robots.txt passthrough.
+export function buildRobotsTxt(policy: RobotsPolicy): string {
+  const rule = policy.allow ? "Disallow:" : "Disallow: /";
+  const sitemap = policy.sitemapUrl ? `\nSitemap: ${policy.sitemapUrl}` : "";
+  return `User-agent: *\n${rule}${sitemap}\n`;
+}

package/src/seo/schema-builders.ts

@@ -0,0 +1,57 @@
+// Pure schema.org JSON-LD builders — plain data, no HTML/escaping (the
+// serialization boundary is `renderApexHeadTags`'s `scriptSafeJsonHtml`,
+// which already escapes `<` so a value can't break out of the
+// `<script type="application/ld+json">` block). Feed the result into
+// `ApexHead.schemaJson` (renderApexPage) or `wrapInLayout({ seo: { schemaJson
+// } })` (CMS pages) — this feature does not inject JSON-LD on its own routes.
+
+export type OrganizationSchemaInput = {
+  readonly name: string;
+  readonly url?: string;
+  readonly logoUrl?: string;
+  readonly sameAs?: readonly string[];
+};
+
+export function organizationSchema(input: OrganizationSchemaInput): Record<string, unknown> {
+  return {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    name: input.name,
+    ...(input.url ? { url: input.url } : {}),
+    ...(input.logoUrl ? { logo: input.logoUrl } : {}),
+    ...(input.sameAs && input.sameAs.length > 0 ? { sameAs: input.sameAs } : {}),
+  };
+}
+
+export type WebPageSchemaInput = {
+  readonly name: string;
+  readonly url: string;
+  readonly description?: string;
+};
+
+export function webPageSchema(input: WebPageSchemaInput): Record<string, unknown> {
+  return {
+    "@context": "https://schema.org",
+    "@type": "WebPage",
+    name: input.name,
+    url: input.url,
+    ...(input.description ? { description: input.description } : {}),
+  };
+}
+
+export type FaqItem = { readonly question: string; readonly answer: string };
+
+// Feeds Google's FAQ rich-result + is the most directly LLM-answer-engine-
+// legible JSON-LD shape (question/answer pairs) — the "AEO/GEO" half of the
+// schema-builder set, same emission path as organizationSchema/webPageSchema.
+export function faqPageSchema(items: readonly FaqItem[]): Record<string, unknown> {
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: items.map((item) => ({
+      "@type": "Question",
+      name: item.question,
+      acceptedAnswer: { "@type": "Answer", text: item.answer },
+    })),
+  };
+}

package/src/seo/sitemap.ts

@@ -0,0 +1,33 @@
+import { escapeXml } from "@cosmicdrift/kumiko-headless";
+
+export type SitemapEntry = {
+  readonly loc: string;
+  /** ISO-8601 date/datetime. */
+  readonly lastmod?: string;
+  readonly changefreq?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+  /** hreflang alternates for the same logical page (multilingual sitemaps). */
+  readonly alternates?: readonly { readonly hreflang: string; readonly href: string }[];
+  /** Human-/LLM-readable page title, used by llms.txt link lines. Falls back
+   *  to `loc` when absent (callback-only entries rarely set this). */
+  readonly title?: string;
+};
+
+// Pure XML builder — sitemaps.org urlset + xhtml:link alternates. No
+// dedup/sort: callers control ordering, entries are trusted app/feature data
+// (see feature.ts's trust boundary — same posture as ApexCta.href).
+export function buildSitemapXml(entries: readonly SitemapEntry[]): string {
+  const urls = entries
+    .map((e) => {
+      const lastmod = e.lastmod ? `\n    <lastmod>${escapeXml(e.lastmod)}</lastmod>` : "";
+      const changefreq = e.changefreq ? `\n    <changefreq>${e.changefreq}</changefreq>` : "";
+      const alternates = (e.alternates ?? [])
+        .map(
+          (a) =>
+            `\n    <xhtml:link rel="alternate" hreflang="${escapeXml(a.hreflang)}" href="${escapeXml(a.href)}" />`,
+        )
+        .join("");
+      return `  <url>\n    <loc>${escapeXml(e.loc)}</loc>${lastmod}${changefreq}${alternates}\n  </url>`;
+    })
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">\n${urls}\n</urlset>\n`;
+}

package/src/sessions/__tests__/auto-revoke-binding.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, mock, test } from "bun:test";
+import type { AppContext, SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import { bindAutoRevokeFromFeature, createSessionsFeature } from "../feature";
+
+// The postSave hook is registered unconditionally; the revoker arrives either
+// as the explicit constructor option or late-bound by run{Prod,Dev}App via
+// bindAutoRevokeOnPasswordChange. These tests pin the binding + precedence
+// semantics at the hook level — the full DB sweep is covered by
+// password-auto-revoke.integration.test.ts.
+
+const passwordChange: SaveContext = {
+  kind: "save",
+  id: "user-1",
+  data: {},
+  changes: { passwordHash: "new-hash" },
+  previous: {},
+  isNew: false,
+};
+
+// @cast-boundary test fixture — the hook never touches AppContext
+const appContext = {} as unknown as AppContext;
+
+function userPostSaveHook(feature: ReturnType<typeof createSessionsFeature>) {
+  const hook = feature.entityHooks?.postSave?.["user"]?.[0];
+  if (!hook) throw new Error("sessions feature did not register the user postSave hook");
+  return (ctx: SaveContext) => hook.fn(ctx, appContext);
+}
+
+describe("sessions auto-revoke binding", () => {
+  test("late-bound revoker fires on password change", async () => {
+    const revoker = mock(async (_userId: string) => 1);
+    const feature = createSessionsFeature();
+
+    const bind = bindAutoRevokeFromFeature(feature);
+    expect(bind).toBeDefined();
+    bind?.(revoker);
+
+    await userPostSaveHook(feature)(passwordChange);
+    expect(revoker).toHaveBeenCalledTimes(1);
+    expect(revoker).toHaveBeenCalledWith("user-1");
+  });
+
+  test("unbound hook is a silent no-op", async () => {
+    const feature = createSessionsFeature();
+    // must resolve without throwing — stateless-JWT deployments have no revoker
+    const result = await userPostSaveHook(feature)(passwordChange);
+    expect(result).toBeUndefined();
+  });
+
+  test("skips isNew and non-passwordHash changes", async () => {
+    const revoker = mock(async (_userId: string) => 1);
+    const feature = createSessionsFeature();
+    bindAutoRevokeFromFeature(feature)?.(revoker);
+
+    await userPostSaveHook(feature)({ ...passwordChange, isNew: true });
+    await userPostSaveHook(feature)({ ...passwordChange, changes: { displayName: "x" } });
+    expect(revoker).not.toHaveBeenCalled();
+  });
+
+  test("explicit constructor option wins over the runtime binding", async () => {
+    const explicit = mock(async (_userId: string) => 1);
+    const lateBound = mock(async (_userId: string) => 1);
+    const feature = createSessionsFeature({ autoRevokeOnPasswordChange: explicit });
+
+    bindAutoRevokeFromFeature(feature)?.(lateBound);
+    await userPostSaveHook(feature)(passwordChange);
+
+    expect(explicit).toHaveBeenCalledWith("user-1");
+    expect(lateBound).not.toHaveBeenCalled();
+  });
+});

package/src/sessions/__tests__/cleanup.integration.test.ts

@@ -5,6 +5,7 @@
 // expired/revoked rows go, live rows stay, batching + signal work.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { sql } from "@cosmicdrift/kumiko-framework/db";
 import type { AppContext } from "@cosmicdrift/kumiko-framework/engine";
@@ -40,7 +41,7 @@ let stack: TestStack;
 
 beforeAll(async () => {
   stack = await setupTestStack({
-    features: [createSessionsFeature(), createUserFeature()],
+    features: [authFoundationFeature, createSessionsFeature(), createUserFeature()],
   });
   await unsafeCreateEntityTable(stack.db, userSessionEntity);
   await unsafeCreateEntityTable(stack.db, userEntity);

package/src/sessions/__tests__/password-auto-revoke.integration.test.ts

@@ -1,7 +1,7 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
 import { randomBytes } from "node:crypto";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -10,7 +10,10 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { createLateBoundHolder } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  createLateBoundHolder,
+  createTestEnvelopeCipher,
+} from "@cosmicdrift/kumiko-framework/testing";
 import { AuthHandlers } from "../../auth-email-password/constants";
 import { createAuthEmailPasswordFeature } from "../../auth-email-password/feature";
 import { createConfigFeature } from "../../config";
@@ -49,8 +52,8 @@ const encryptionKey = randomBytes(32).toString("base64");
 const TENANT: TenantId = testTenantId(1);
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(encryptionKey);
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
   const bound = sessionCallbacksFromLateBound(callbacks);
   const baseRevoker = bound.asMassRevoker();
 
@@ -64,6 +67,7 @@ beforeAll(async () => {
       createUserFeature(),
       createTenantFeature(),
       createAuthEmailPasswordFeature(),
+      authFoundationFeature,
       createSessionsFeature({
         autoRevokeOnPasswordChange: massRevokeSpy,
       }),
@@ -76,7 +80,7 @@ beforeAll(async () => {
     },
   });
   callbacks.set(createSessionCallbacks({ db: stack.db }));
-  h = makeSessionHelpers(stack, TENANT);
+  h = makeSessionHelpers(stack, TENANT, bound.asAuthConfig().sessionCreator);
 
   await unsafeCreateEntityTable(stack.db, userEntity);
   await unsafeCreateEntityTable(stack.db, tenantEntity);
@@ -97,7 +101,7 @@ beforeEach(async () => {
 
 describe("password change mass-revokes every live session", () => {
   test("changing the password revokes ALL sessions including the caller's", async () => {
-    await h.seedUser("rotate@example.com", "first-password");
+    const { userId } = await h.seedUser("rotate@example.com", "first-password");
 
     const a = await h.login("rotate@example.com", "first-password");
     const b = await h.login("rotate@example.com", "first-password");
@@ -145,7 +149,7 @@ describe("password change mass-revokes every live session", () => {
 
     // DB state confirms: zero live rows for this user
     const liveRows = await selectMany(stack.db, userSessionTable);
-    const stillLive = liveRows.filter((r) => r["revokedAt"] === null);
+    const stillLive = liveRows.filter((r) => r["userId"] === userId && r["revokedAt"] === null);
     expect(stillLive).toHaveLength(0);
 
     // And logging in again with the NEW password works