@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/seo/feature.ts

@@ -0,0 +1,317 @@
+// kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312 (feature.ts > 300 lines)
+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/index.js";
+import { cachedSecurePageResponse } from "../page-render/index.js";
+import type { SystemQueryFn } from "../shared/index.js";
+import { SEO_CONFIG_KEYS, SEO_DEFAULT_PATHS } from "./constants.js";
+import { seoConfigQuery } from "./handlers/seo-config.query.js";
+import { buildLlmsTxt } from "./llms-txt.js";
+import { buildRobotsTxt, type RobotsPolicy } from "./robots-txt.js";
+import { buildSitemapXml, type SitemapEntry } from "./sitemap.js";
+
+// 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/packages/bundled-features/src/seo/handlers/seo-config.query.ts

@@ -0,0 +1,38 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { SEO_CONFIG_QN } from "../constants.js";
+
+// 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"] },
+  rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
+  description:
+    "Reads the tenant's SEO metadata settings — organization name and logo URL, Twitter site handle, LLMs summary and default OG image — as plain strings; use it to inspect what the sitemap, llms.txt and page meta tags will publish.",
+  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/packages/bundled-features/src/seo/index.ts

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

package/packages/bundled-features/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/packages/bundled-features/src/seo/robots-txt.ts

@@ -0,0 +1,33 @@
+export type RobotsPolicy = {
+  readonly allow: boolean;
+  readonly sitemapUrl?: string;
+  /** Emit explicit Allow rules for known AI crawlers (GPTBot, ClaudeBot,
+   *  anthropic-ai, PerplexityBot, Google-Extended). No-op when allow:false —
+   *  a blanket Disallow already covers every bot. */
+  readonly aiCrawlers?: boolean;
+  /** Raw value for the Content-Signal directive (contentsignals.org), e.g.
+   *  "ai-train=no, search=yes, ai-input=yes". Emitted verbatim. */
+  readonly contentSignal?: string;
+};
+
+const AI_CRAWLER_USER_AGENTS = [
+  "GPTBot",
+  "ClaudeBot",
+  "anthropic-ai",
+  "PerplexityBot",
+  "Google-Extended",
+] as const;
+
+// 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 aiCrawlerBlocks =
+    policy.aiCrawlers && policy.allow
+      ? AI_CRAWLER_USER_AGENTS.map((ua) => `\nUser-agent: ${ua}\nAllow: /`).join("")
+      : "";
+  const contentSignal = policy.contentSignal ? `\nContent-Signal: ${policy.contentSignal}` : "";
+  const sitemap = policy.sitemapUrl ? `\nSitemap: ${policy.sitemapUrl}` : "";
+  return `User-agent: *\n${rule}${aiCrawlerBlocks}${contentSignal}${sitemap}\n`;
+}

package/packages/bundled-features/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/packages/bundled-features/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/packages/bundled-features/src/sessions/changes.json

@@ -0,0 +1,45 @@
+[
+  {
+    "version": "0.336.0",
+    "type": "fix",
+    "title": "Session revoke (single, mass, all-others) and its revoked-event commit atomically",
+    "detail": "Session logout, password-change/MFA mass revoke, revoke-all-others and PAT revoke now commit the revoke and its revoked-event in one transaction, so a failed append no longer leaves a revoked token whose SSE streams stay open. GDPR delete hooks now try every row of the subject and report all failures at once instead of stopping at the first. The notes mention-forget hook loads the mentioned notes with one query and resolves each host entity's retention policy once."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Session list loads one max-size page and renders no pager"
+  },
+  {
+    "version": "0.330.0",
+    "type": "improvement",
+    "title": "store_user_sessions gets an index on (tenant_id, last_seen_at) (fw#3396)",
+    "detail": "Active-user dashboard aggregates (metrics feature) filter on tenant_id and last_seen_at.",
+    "migration": "Run `kumiko migrate generate` and apply the migration: it adds an index on `store_user_sessions (tenant_id, last_seen_at)`."
+  },
+  {
+    "version": "0.259.0",
+    "type": "breaking",
+    "title": "sessions:query:user-session:mine returns the paged envelope { rows, nextCursor }; new self-service my-sessions screen (fw#2844).",
+    "detail": "The query backs the new `my-sessions` projectionList (open to every signed-in user): the caller's live sessions with a per-row revoke (hidden on the current session) and \"sign out all other devices\". Exported id SESSION_MINE_SCREEN_ID. Server-side scoping to the caller is unchanged.",
+    "migration": "Breaking for direct callers of `sessions:query:user-session:mine`: read `data.rows` instead of treating `data` as the array (`nextCursor` is always null). Account-security custom screens built on this query can be replaced by a dashboard with `kind: \"screen\"` panels on `sessions:screen:my-sessions` and the auth-mfa screens (money-horse#477, publicstatus#435, kumiko-studio#283)."
+  },
+  {
+    "version": "0.208.2",
+    "type": "improvement",
+    "title": "Session rows track lastSeenAt, refreshed hourly",
+    "detail": "userSession now carries a lastSeenAt timestamp, set on session creation and refreshed by sessionChecker at most once per hour (LAST_SEEN_REFRESH_MS). A refresh failure is swallowed and the check still returns \"live\" — this is a coarse activity marker, not a per-request write."
+  },
+  {
+    "version": "0.165.1",
+    "type": "fix",
+    "title": "Mid-stream access revocation aborts idle SSE pulls; sseHeartbeatMs is a real buildServer option (fw#1587).",
+    "detail": "A revoked session used to keep an idle SSE stream alive until the client disconnected. clientIpOf now falls back to x-real-ip before the shared \"unknown\" bucket, so per-IP rate limits stop collapsing into one bucket behind proxies that only set that header."
+  },
+  {
+    "version": "0.165.0",
+    "type": "improvement",
+    "title": "Revoke handlers emit session-revoked event",
+    "detail": "Session revocation now appends a session-revoked event to the aggregate stream — other features can react to it (e.g. cache invalidation)."
+  }
+]

package/packages/bundled-features/src/sessions/constants.ts

@@ -0,0 +1,58 @@
+export const SESSIONS_FEATURE = "sessions" as const;
+export const USER_SESSION_ENTITY_NAME = "user-session" as const;
+
+// Qualified write handler names — entity prefix is "userSession", snake_case
+// "user_session" on the wire.
+export const SessionHandlers = {
+  revoke: "sessions:write:user-session:revoke",
+  revokeAllOthers: "sessions:write:user-session:revoke-all-others",
+  /** Privileged: System-Caller (cross-feature) revokes ALL live sessions
+   *  fuer einen User. Genutzt von user-data-rights:restrict-account
+   *  (DSGVO Art. 18 Account-Freeze). */
+  revokeAllForUser: "sessions:write:user-session:revoke-all-for-user",
+} as const;
+
+export const SessionQueries = {
+  // User-scoped: "my live sessions" (other devices/browsers)
+  mine: "sessions:query:user-session:mine",
+  // Admin-scoped: all sessions in the caller's tenant (live + revoked).
+  // Tenant isolation comes from ctx.db; access-gate is admin-or-higher.
+  list: "sessions:query:user-session:list",
+  // Admin-scoped single-session inspector, backs the session-detail screen.
+  detail: "sessions:query:user-session:detail",
+} as const;
+
+export const SessionErrors = {
+  // Returned by session:revoke when the sid is already revoked. Distinct
+  // from ownership_denied so the UI can say "this session was already
+  // logged out at <time>" instead of a generic access error. Revealing an
+  // already-revoked sid's state to its owner is not a leak (they already
+  // know it was their session).
+  alreadyRevoked: "session_already_revoked",
+  // "sign out everywhere else" called without a current session on the JWT.
+  // Stateless-JWT deployments can't express "everywhere else", so we refuse
+  // rather than interpret the request as "nuke everything including me".
+  sessionRequired: "session_required",
+  // Handler reuses the framework-wide ownership_denied reason (kept here as
+  // a constant so the handler's constructor-arg and the test's assertion
+  // read from the same source).
+  ownershipDenied: "ownership_denied",
+} as const;
+
+// Default cache TTL in milliseconds. 60s keeps DB load down while still
+// surfacing revocations within a minute. Tests override to 0 for determinism.
+export const DEFAULT_SESSION_CACHE_TTL_MS = 60_000;
+
+// Default session lifetime — 30 days. Mirrors typical "remember me" windows
+// and matches the JWT 24h refresh story (JWT expires sooner, session lives
+// longer so refresh can rotate the token without requiring a new password).
+// MVP ships a single window; per-app overrides can come later.
+export const DEFAULT_SESSION_EXPIRY_MS = 30 * 24 * 60 * 60 * 1000;
+
+// Minimum gap between lastSeenAt writes — coarse activity tracking without a
+// write on every authenticated request.
+export const LAST_SEEN_REFRESH_MS = 3_600_000;
+
+export const SESSION_LIST_SCREEN_ID = "session-list" as const;
+export const SESSION_DETAIL_SCREEN_ID = "session-detail" as const;
+export const SESSION_MINE_SCREEN_ID = "my-sessions" as const;

package/packages/bundled-features/src/sessions/db/queries/cleanup.ts

@@ -0,0 +1,21 @@
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+
+export async function deleteStaleSessionsBatch(
+  db: DbConnection,
+  olderThanDays: number,
+  batchSize: number,
+): Promise<number> {
+  const rows = (await asRawClient(db).unsafe(
+    `DELETE FROM "store_user_sessions"
+     WHERE "id" IN (
+       SELECT "id" FROM "store_user_sessions"
+       WHERE "expires_at" < now() - ($1::int * interval '1 day')
+          OR "revoked_at" < now() - ($1::int * interval '1 day')
+       LIMIT $2
+     )
+     RETURNING "id"`,
+    [olderThanDays, batchSize],
+  )) as readonly { id: string }[];
+  return rows.length;
+}