@cosmicdrift/kumiko-framework 0.48.1 → 0.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.48.1",
+  "version": "0.50.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/api/__tests__/origin-middleware.integration.test.ts

@@ -0,0 +1,132 @@
+// origin-middleware wired into the real buildServer pipeline. Proves that the
+// registration fires when authConfig.allowedOrigins is set, that the guard sits
+// BEFORE the CSRF guard (a disallowed cross-site POST surfaces as
+// `origin_not_allowed`, not `csrf_token_mismatch`), that cookie-vs-bearer
+// transport detection works end-to-end, and that the explicit opt-out disables
+// the guard without breaking boot. Cookie-auth is forged with a minted JWT — no
+// full login flow needed to exercise the guard. Passing requests hit the
+// dispatcher and 404 on the unknown query, which positively proves no guard
+// rejected them (guards return 403).
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { setupTestStack, type TestStack, TestUsers } from "../../stack";
+import { AUTH_COOKIE_NAME, CSRF_COOKIE_NAME, CSRF_HEADER_NAME } from "../auth-middleware";
+
+const ALLOWED = "https://admin.example.eu";
+const DISALLOWED = "https://tenant.example.eu";
+const QUERY_BODY = { type: "noop:query:noop", payload: {} };
+
+async function errorCode(res: Response): Promise<string | undefined> {
+  const body = (await res.json().catch(() => ({}))) as { error?: { code?: string } };
+  return body.error?.code;
+}
+
+describe("origin-middleware (integration)", () => {
+  let stack: TestStack;
+  let authCookie: string;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [],
+      authConfig: {
+        // Never dispatched here — present only so options.auth is wired and the
+        // Origin guard registers. switch-tenant is the only consumer.
+        membershipQuery: "tenant:query:memberships",
+        allowedOrigins: [ALLOWED],
+        cookieDomain: "example.eu",
+      },
+    });
+    const token = await stack.jwt.sign(TestUsers.user);
+    authCookie = `${AUTH_COOKIE_NAME}=${token}`;
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("disallowed origin + simple text/plain POST → 403 origin_not_allowed (before CSRF)", async () => {
+    const res = await stack.http.raw("POST", "/api/query", QUERY_BODY, {
+      Cookie: authCookie,
+      Origin: DISALLOWED,
+      "Content-Type": "text/plain",
+    });
+    expect(res.status).toBe(403);
+    // No CSRF token sent — proves the Origin guard runs FIRST (else this would
+    // be csrf_token_mismatch).
+    expect(await errorCode(res)).toBe("origin_not_allowed");
+  });
+
+  test("allowed origin (no CSRF token) → falls through to the CSRF guard", async () => {
+    const res = await stack.http.raw("POST", "/api/query", QUERY_BODY, {
+      Cookie: authCookie,
+      Origin: ALLOWED,
+    });
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("csrf_token_mismatch");
+  });
+
+  test("no Origin + valid CSRF token → reaches dispatcher (Safari same-origin POST)", async () => {
+    const csrf = "csrf-fixed-integration-token";
+    const res = await stack.http.raw("POST", "/api/query", QUERY_BODY, {
+      Cookie: `${authCookie}; ${CSRF_COOKIE_NAME}=${csrf}`,
+      [CSRF_HEADER_NAME]: csrf,
+    });
+    // Both guards passed → the dispatcher 404s the unknown query. A positive
+    // assertion proves no guard (403) rejected the request.
+    expect(res.status).toBe(404);
+    expect(await errorCode(res)).toBe("not_found");
+  });
+
+  test("no Origin + Sec-Fetch-Site: cross-site → 403 origin_not_allowed", async () => {
+    const res = await stack.http.raw("POST", "/api/query", QUERY_BODY, {
+      Cookie: authCookie,
+      "Sec-Fetch-Site": "cross-site",
+    });
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("origin_not_allowed");
+  });
+
+  test("bearer transport + disallowed origin → skips both guards, reaches dispatcher", async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const res = await stack.http.raw("POST", "/api/query", QUERY_BODY, {
+      Authorization: `Bearer ${token}`,
+      Origin: DISALLOWED,
+    });
+    expect(res.status).toBe(404);
+    expect(await errorCode(res)).toBe("not_found");
+  });
+});
+
+describe("origin-middleware opt-out (unsafeSkipOriginCheck)", () => {
+  let stack: TestStack;
+  let authCookie: string;
+
+  beforeAll(async () => {
+    // cookieDomain set WITHOUT allowedOrigins would normally fail-closed; the
+    // explicit opt-out must let it boot AND leave the guard unregistered.
+    stack = await setupTestStack({
+      features: [],
+      authConfig: {
+        membershipQuery: "tenant:query:memberships",
+        cookieDomain: "example.eu",
+        unsafeSkipOriginCheck: true,
+      },
+    });
+    const token = await stack.jwt.sign(TestUsers.user);
+    authCookie = `${AUTH_COOKIE_NAME}=${token}`;
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("guard not registered → disallowed origin falls through to CSRF, not origin-blocked", async () => {
+    const res = await stack.http.raw("POST", "/api/query", QUERY_BODY, {
+      Cookie: authCookie,
+      Origin: DISALLOWED,
+    });
+    expect(res.status).toBe(403);
+    // CSRF fires (no token) — NOT the origin guard. Proves the opt-out disabled it.
+    expect(await errorCode(res)).toBe("csrf_token_mismatch");
+  });
+});

package/src/api/__tests__/origin-middleware.test.ts

@@ -0,0 +1,191 @@
+// origin-middleware: server-side Origin-allowlist guard layered behind
+// authMiddleware. Covers the production-relevant paths: cookie + state-
+// changing (allowed/disallowed/simple-request/opaque, all four methods),
+// cookie + safe method, bearer transport, the no-Origin Sec-Fetch-Site
+// fallback, and the fail-closed boot check.
+
+import { describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import { TestUsers } from "../../stack";
+import { AUTH_COOKIE_NAME, authMiddleware } from "../auth-middleware";
+import { createJwtHelper } from "../jwt";
+import {
+  assertOriginGuardConfig,
+  isOriginAllowed,
+  normalizeOrigin,
+  originMiddleware,
+} from "../origin-middleware";
+
+const JWT_SECRET = "origin-middleware-test-secret-min-32-characters-long";
+const ALLOWED = "https://admin.example.eu";
+const DISALLOWED = "https://tenant.example.eu";
+
+async function buildApp(): Promise<{ app: Hono; token: string }> {
+  const jwt = createJwtHelper(JWT_SECRET);
+  const token = await jwt.sign(TestUsers.user);
+  const app = new Hono();
+  app.use("/api/*", authMiddleware(jwt));
+  app.use("/api/*", originMiddleware([ALLOWED]));
+  app.get("/api/ping", (c) => c.json({ ok: true }));
+  app.post("/api/write", (c) => c.json({ ok: true }));
+  return { app, token };
+}
+
+describe("normalizeOrigin", () => {
+  test("lowercases and strips trailing slash + whitespace", () => {
+    expect(normalizeOrigin("HTTPS://Admin.Example.EU/")).toBe("https://admin.example.eu");
+    expect(normalizeOrigin("  https://admin.example.eu  ")).toBe("https://admin.example.eu");
+    expect(normalizeOrigin("https://admin.example.eu")).toBe("https://admin.example.eu");
+  });
+});
+
+describe("isOriginAllowed", () => {
+  const allowlist = new Set([normalizeOrigin(ALLOWED)]);
+  test("matches normalized entry regardless of case/trailing slash", () => {
+    expect(isOriginAllowed("https://admin.example.eu", allowlist)).toBe(true);
+    expect(isOriginAllowed("HTTPS://ADMIN.EXAMPLE.EU/", allowlist)).toBe(true);
+  });
+  test("rejects a non-listed origin and the opaque 'null' origin", () => {
+    expect(isOriginAllowed(DISALLOWED, allowlist)).toBe(false);
+    expect(isOriginAllowed("null", allowlist)).toBe(false);
+  });
+});
+
+describe("assertOriginGuardConfig", () => {
+  test("throws when cookieDomain is set without allowedOrigins or opt-out", () => {
+    expect(() => assertOriginGuardConfig({ cookieDomain: "example.eu" })).toThrow(/allowedOrigins/);
+  });
+  test("throws when allowedOrigins is an empty array", () => {
+    expect(() =>
+      assertOriginGuardConfig({ cookieDomain: "example.eu", allowedOrigins: [] }),
+    ).toThrow();
+  });
+  test("passes when allowedOrigins is set", () => {
+    expect(() =>
+      assertOriginGuardConfig({ cookieDomain: "example.eu", allowedOrigins: [ALLOWED] }),
+    ).not.toThrow();
+  });
+  test("passes when explicitly opted out", () => {
+    expect(() =>
+      assertOriginGuardConfig({ cookieDomain: "example.eu", unsafeSkipOriginCheck: true }),
+    ).not.toThrow();
+  });
+  test("passes when no cookieDomain (host-only cookie) or no auth at all", () => {
+    expect(() => assertOriginGuardConfig({})).not.toThrow();
+    expect(() => assertOriginGuardConfig(undefined)).not.toThrow();
+  });
+});
+
+describe("originMiddleware", () => {
+  test("bearer transport skips the check even on a disallowed-origin POST", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/write", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, Origin: DISALLOWED },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("cookie transport + GET → no check (safe method)", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/ping", {
+      headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}`, Origin: DISALLOWED },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("cookie transport + POST + allowed origin → ok", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/write", {
+      method: "POST",
+      headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}`, Origin: ALLOWED },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("cookie transport + POST + disallowed origin → 403 origin_not_allowed", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/write", {
+      method: "POST",
+      headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}`, Origin: DISALLOWED },
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("origin_not_allowed");
+  });
+
+  // The guard runs as /api/* middleware before routing, so a disallowed-origin
+  // request is rejected for every state-changing method even without a route.
+  test.each([
+    "PUT",
+    "PATCH",
+    "DELETE",
+  ])("cookie transport + %s + disallowed origin → 403 (every state-changing method)", async (method) => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/write", {
+      method,
+      headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}`, Origin: DISALLOWED },
+    });
+    expect(res.status).toBe(403);
+    expect(((await res.json()) as { error: { code: string } }).error.code).toBe(
+      "origin_not_allowed",
+    );
+  });
+
+  test("disallowed origin is blocked even as a simple text/plain request", async () => {
+    // The real vector: a `text/plain` POST skips the CORS preflight and reaches
+    // the server, where only the Origin check stands between it and the handler.
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/write", {
+      method: "POST",
+      headers: {
+        Cookie: `${AUTH_COOKIE_NAME}=${token}`,
+        Origin: DISALLOWED,
+        "Content-Type": "text/plain",
+      },
+      body: "type=x",
+    });
+    expect(res.status).toBe(403);
+  });
+
+  test("cookie transport + POST + no Origin → passes (CSRF token is the next layer)", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/write", {
+      method: "POST",
+      headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}` },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("no Origin + Sec-Fetch-Site: same-origin → passes", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/write", {
+      method: "POST",
+      headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}`, "Sec-Fetch-Site": "same-origin" },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  // same-site is passed through by design (the CSRF token is the next layer);
+  // the realistic same-site XSS attack carries an Origin header and is rejected
+  // by the allowlist branch before this fallback is reached.
+  test("no Origin + Sec-Fetch-Site: same-site → passes (intentional, CSRF is next layer)", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/write", {
+      method: "POST",
+      headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}`, "Sec-Fetch-Site": "same-site" },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("no Origin + Sec-Fetch-Site: cross-site → 403", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/write", {
+      method: "POST",
+      headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}`, "Sec-Fetch-Site": "cross-site" },
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("origin_not_allowed");
+  });
+});

package/src/api/anonymous-cookie.ts

@@ -55,6 +55,7 @@ export function setTenantCookie(
 // Removes the kumiko_tenant cookie. Use on switch-tenant flows or when
 // the resolver no longer recognises the visitor's tenant — leaving a
 // stale cookie behind would keep them pointed at a deleted tenant.
+// @wrapper-known semantic-alias
 export function deleteTenantCookie(c: Context): void {
   deleteCookie(c, TENANT_COOKIE_NAME, { path: "/" });
 }

package/src/api/api-constants.ts

@@ -53,6 +53,15 @@ export const PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
   `/api${Routes.version}`,
 ]);
 
+// Methods that can mutate server state. GET/HEAD/OPTIONS are safe under
+// CORS + SameSite-cookie semantics and skip the CSRF / Origin guards entirely.
+export const STATE_CHANGING_METHODS: ReadonlySet<string> = new Set([
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+]);
+
 // Tenant transports for unauthenticated callers on public endpoints. JWT
 // users carry tenantId in the signed token; anonymous callers must declare
 // the tenant out-of-band — header for SPA/mobile, cookie for browser-direct

package/src/api/auth-middleware.ts

@@ -109,6 +109,7 @@ type MiddlewareRejectCode =
   | "tenant_mismatch"
   | "invalid_tenant_format";
 
+// @wrapper-known error-helper
 function middlewareReject(
   c: Context,
   opts: {
@@ -133,6 +134,7 @@ function middlewareReject(
   );
 }
 
+// @wrapper-known error-helper
 function sessionInvalid(c: Context, reason: AuthSessionStatus | "no_sid"): Response {
   return middlewareReject(c, {
     code: "session_invalid",

package/src/api/auth-routes.ts

@@ -257,8 +257,33 @@ export type AuthRoutesConfig = {
   // live on DIFFERENT subdomains (login on apex, app on admin.) — the
   // browser then sends the session to every subdomain. Careful: that
   // includes ALL subdomains (tenant pages, previews); widen the scope
-  // only when the cross-subdomain session is actually required.
+  // only when the cross-subdomain session is actually required — and pair
+  // it with `allowedOrigins` so the server-side Origin guard stays on (a
+  // wide cookie makes the JS-readable csrf cookie reachable from every
+  // subdomain, weakening the double-submit defence).
   cookieDomain?: string;
+  // Origin-allowlist for the server-side CSRF-hardening guard (origin-
+  // middleware). When non-empty, every cookie-authenticated, state-changing
+  // /api request must carry an `Origin` header that exact-matches one of
+  // these entries (scheme+host+optional port, e.g. "https://example.eu", no
+  // trailing slash, no wildcards). Requests without an Origin fall back to
+  // Sec-Fetch-Site and then to the CSRF token — the guard is defense-in-
+  // depth, not a replacement.
+  //
+  // List ONLY the trusted entry hosts: the apex and the admin host. Do NOT
+  // list tenant/public subdomains — with a wide `cookieDomain` they share
+  // the session cookie, so an XSS there is exactly the threat this blocks.
+  // Empty/unset (default) disables the guard; required only when
+  // `cookieDomain` widens the cookie across subdomains.
+  allowedOrigins?: readonly string[];
+  // Explicit opt-out of the fail-closed Origin guard. When `cookieDomain` is
+  // set the framework REFUSES TO BOOT unless `allowedOrigins` is configured — a
+  // wide cookie without an Origin check is the unguarded-subdomain-XSS footgun.
+  // Set this true ONLY for a single-host deployment that shares no untrusted
+  // subdomains and genuinely needs the wide cookie anyway; you accept that any
+  // subdomain can then forge authenticated state-changing requests. Prefer
+  // setting `allowedOrigins`.
+  unsafeSkipOriginCheck?: boolean;
 };
 
 export type PasswordResetConfig = {
@@ -527,7 +552,7 @@ export function createAuthRoutes(
       successKind: "reset-requested",
       appBaseUrl: pr.appResetUrl,
       sendEmail: ({ email, url, expiresAt }) =>
-        pr.sendResetEmail({ email, resetUrl: url, expiresAt }),
+        pr.sendResetEmail({ email, resetUrl: url, expiresAt }), // @wrapper-known semantic-alias
     });
     registerTokenConfirmRoute({
       api,
@@ -549,7 +574,7 @@ export function createAuthRoutes(
       successKind: "verification-requested",
       appBaseUrl: ev.appVerifyUrl,
       sendEmail: ({ email, url, expiresAt }) =>
-        ev.sendVerificationEmail({ email, verificationUrl: url, expiresAt }),
+        ev.sendVerificationEmail({ email, verificationUrl: url, expiresAt }), // @wrapper-known semantic-alias
     });
     registerTokenConfirmRoute({
       api,
@@ -574,7 +599,7 @@ export function createAuthRoutes(
       successKind: "signup-requested",
       appBaseUrl: sg.appActivationUrl,
       sendEmail: ({ email, url, expiresAt }) =>
-        sg.sendActivationEmail({ email, activationUrl: url, expiresAt }),
+        sg.sendActivationEmail({ email, activationUrl: url, expiresAt }), // @wrapper-known semantic-alias
     });
 
     api.post(Routes.authSignupConfirm, async (c) => {

package/src/api/csrf-middleware.ts

@@ -1,12 +1,9 @@
 import { timingSafeEqual } from "node:crypto";
 import type { Context, Next } from "hono";
 import { getCookie } from "hono/cookie";
+import { STATE_CHANGING_METHODS } from "./api-constants";
 import { CSRF_COOKIE_NAME, CSRF_HEADER_NAME, getAuthTransport } from "./auth-middleware";
 
-// Methods that can mutate server state. GET/HEAD/OPTIONS are safe under
-// CORS + SameSite-cookie semantics and skip the CSRF check entirely.
-const STATE_CHANGING_METHODS: ReadonlySet<string> = new Set(["POST", "PUT", "PATCH", "DELETE"]);
-
 // Constant-time byte compare. `a !== b` short-circuits at the first
 // differing byte and leaks the common prefix length to anyone who can
 // time requests — in principle exploitable against sufficiently small

package/src/api/origin-middleware.ts

@@ -0,0 +1,98 @@
+import type { Context, Next } from "hono";
+import { STATE_CHANGING_METHODS } from "./api-constants";
+import { getAuthTransport } from "./auth-middleware";
+
+// Canonical comparable form for an Origin / allowlist entry: lowercased, no
+// trailing slash. Origin headers are scheme+host(+port) without a path, but
+// config entries are hand-written and may carry a stray slash or mixed case.
+export function normalizeOrigin(value: string): string {
+  return value.trim().toLowerCase().replace(/\/+$/, "");
+}
+
+// Exact-match against a pre-normalized allowlist. No wildcards by design:
+// `*.example.eu` would re-admit the tenant subdomains this guard exists to
+// shut out.
+export function isOriginAllowed(origin: string, normalizedAllowlist: ReadonlySet<string>): boolean {
+  return normalizedAllowlist.has(normalizeOrigin(origin));
+}
+
+function rejectOrigin(c: Context): Response {
+  return c.json(
+    {
+      error: {
+        code: "origin_not_allowed",
+        httpStatus: 403,
+        message: "request origin is not allowed",
+        i18nKey: "auth.errors.originNotAllowed",
+      },
+    },
+    403,
+  );
+}
+
+// Server-side Origin-allowlist guard — an additional CSRF-hardening layer on
+// top of the double-submit token (csrf-middleware) for deployments that widen
+// the auth cookie across subdomains via AuthRoutesConfig.cookieDomain. A wide
+// cookie means an XSS on ANY subdomain (e.g. a tenant status page) can read
+// the JS-readable kumiko_csrf cookie and forge an authenticated state-changing
+// request. Pinning the request Origin to the apex + admin host (never tenant
+// subdomains) closes that vector even for "simple requests" (text/plain or
+// form-encoded) that skip the CORS preflight and reach the server.
+//
+// Runs AFTER authMiddleware (reads the authTransport flag) with the same scope
+// as the CSRF guard: only cookie-authenticated, state-changing requests.
+// Bearer-auth requests skip — browsers cannot set Authorization cross-origin,
+// and native clients send no/foreign Origin, so guarding them would be a
+// false-positive with no CSRF vector to defend.
+export function originMiddleware(allowedOrigins: readonly string[]) {
+  const allowlist: ReadonlySet<string> = new Set(allowedOrigins.map(normalizeOrigin));
+  return async (c: Context, next: Next) => {
+    const transport = getAuthTransport(c);
+    if (transport !== "cookie") return next();
+    if (!STATE_CHANGING_METHODS.has(c.req.method)) return next();
+
+    const origin = c.req.header("origin");
+    if (origin !== undefined) {
+      if (isOriginAllowed(origin, allowlist)) return next();
+      return rejectOrigin(c);
+    }
+
+    // No Origin header — older browsers, and some same-origin POSTs in Safari.
+    // Fall back to the Fetch-Metadata Sec-Fetch-Site signal: only an explicit
+    // cross-site marker is blocked here (it's a relation, not an origin, so it
+    // can't be matched against the allowlist). Everything else (same-site,
+    // same-origin, none, absent) falls through to the CSRF token. Note: the
+    // CSRF token alone does NOT stop a same-site subdomain XSS — it can read
+    // the wide cookie — but that attack uses fetch/XHR, which always sends an
+    // Origin header and is already rejected by the allowlist branch above. The
+    // residual is only the no-Origin-yet-Sec-Fetch-Site combo, which no current
+    // browser emits for state-changing requests.
+    if (c.req.header("sec-fetch-site") === "cross-site") return rejectOrigin(c);
+
+    return next();
+  };
+}
+
+// Fail-closed boot check: a wide cookieDomain shares the JS-readable
+// kumiko_csrf cookie across every subdomain, so a subdomain XSS can read it and
+// defeat the double-submit CSRF check. Without an Origin allowlist there is no
+// server-side barrier left — refuse to boot in that configuration unless the
+// operator opts out explicitly. Called once from buildServer.
+export function assertOriginGuardConfig(
+  auth:
+    | { cookieDomain?: string; allowedOrigins?: readonly string[]; unsafeSkipOriginCheck?: boolean }
+    | undefined,
+): void {
+  const widensCookieAcrossSubdomains = Boolean(auth?.cookieDomain);
+  const hasAllowlist = (auth?.allowedOrigins?.length ?? 0) > 0;
+  const optedOut = auth?.unsafeSkipOriginCheck === true;
+  if (widensCookieAcrossSubdomains && !hasAllowlist && !optedOut) {
+    throw new Error(
+      "[kumiko:boot] auth.cookieDomain widens the session cookie across subdomains, but " +
+        "auth.allowedOrigins is empty — the JS-readable kumiko_csrf cookie would be reachable " +
+        "from every subdomain (e.g. tenant pages) with no server-side Origin check, defeating " +
+        "CSRF protection. Set auth.allowedOrigins to the apex + admin host, or set " +
+        "auth.unsafeSkipOriginCheck: true to accept the risk explicitly.",
+    );
+  }
+}

package/src/api/server.ts

@@ -49,6 +49,7 @@ import { type AuthRoutesConfig, createAuthRoutes } from "./auth-routes";
 import { csrfMiddleware } from "./csrf-middleware";
 import { createJwtHelper, type JwtHelper } from "./jwt";
 import { observabilityMiddleware } from "./observability-middleware";
+import { assertOriginGuardConfig, originMiddleware } from "./origin-middleware";
 import { requestIdMiddleware } from "./request-id-middleware";
 import {
   DEFAULT_MAX_REQUEST_BYTES,
@@ -543,6 +544,24 @@ export function buildServer(options: ServerOptions): KumikoServer {
     return jwtGuard(c, next);
   });
 
+  // Origin-allowlist guard — additional CSRF-hardening for deployments that
+  // widen the auth cookie across subdomains (auth.cookieDomain). Registered
+  // only when allowedOrigins is non-empty, with the same /api/* + public-skip
+  // scope as the CSRF guard and BEFORE it, so a disallowed cross-site POST
+  // surfaces as `origin_not_allowed` rather than `csrf_token_mismatch`. Fails
+  // closed (assertOriginGuardConfig throws) when a wide cookieDomain is set
+  // without an allowlist and without an explicit opt-out — that config is the
+  // unguarded-subdomain-XSS footgun, not a warn-and-continue case.
+  assertOriginGuardConfig(options.auth);
+  const allowedOrigins = options.auth?.allowedOrigins;
+  if (allowedOrigins && allowedOrigins.length > 0) {
+    const originGuard = originMiddleware(allowedOrigins);
+    app.use("/api/*", async (c, next) => {
+      if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+      return originGuard(c, next);
+    });
+  }
+
   // Double-submit CSRF guard — runs only on cookie-authenticated,
   // state-changing requests (POST/PUT/PATCH/DELETE). The guard reads the
   // authTransport flag set by authMiddleware, so public paths (no auth)
@@ -584,6 +603,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // Auth-Pfad wie ein echter HTTP-Call).
   for (const feature of options.registry.features.values()) {
     for (const route of Object.values(feature.httpRoutes)) {
+      // @wrapper-known semantic-alias
       const honoHandler = async (c: import("hono").Context): Promise<Response> =>
         route.handler(c, { app });
       switch (route.method) {

package/src/bun-db/__tests__/_helpers.ts

@@ -24,6 +24,7 @@ let dbInstance: { db: unknown; close: () => Promise<void> } | undefined;
 export async function getDb(): Promise<unknown> {
   return ensureDb();
 }
+// @wrapper-known test-helper
 export async function ensureDb(): Promise<unknown> {
   if (!dbInstance) {
     dbInstance = await createConnection(DATABASE_URL, { maxConnections: 4 });

package/src/bun-db/query.ts

@@ -153,6 +153,7 @@ function tenantDbDelegate(db: unknown): TenantDbDelegate | undefined {
 // passing a TenantDb here would silently run unscoped against `.raw`, bypassing
 // the tenant filter. Fail loudly so the caller picks `ctx.db.<method>` (scoped)
 // or `ctx.db.raw` (explicit cross-tenant) on purpose.
+// @wrapper-known semantic-alias
 function assertNotTenantScoped(db: unknown, fnName: string): void {
   if (tenantDbDelegate(db) !== undefined) {
     throw new Error(

package/src/db/__tests__/migrate-generator.test.ts

@@ -29,6 +29,17 @@ describe("snapshotFromMetas", () => {
     expect(snap.tables.map((t) => t.tableName)).toEqual(["apples", "zebras"]);
     expect(snap.version).toBe(1);
   });
+
+  test("sorts by codepoint, not locale — deterministic across ICU locales (#367)", () => {
+    // localeCompare orders case-insensitively ("apple" < "Zebra"); codepoint
+    // puts uppercase (U+005A) before lowercase (U+0061) → "Zebra" < "apple".
+    // The snapshot JSON is byte-compared and the order carries into the
+    // generated migration SQL, so a revert to localeCompare would reorder the
+    // committed bytes depending on the runner's ICU locale. Fails the moment
+    // anyone swaps compareByCodepoint back to localeCompare.
+    const snap = snapshotFromMetas([meta("apple"), meta("Zebra")]);
+    expect(snap.tables.map((t) => t.tableName)).toEqual(["Zebra", "apple"]);
+  });
 });
 
 describe("diffSnapshots", () => {

package/src/db/collect-table-metas.ts

@@ -7,6 +7,7 @@
 // crashte (#255).
 
 import type { FeatureDefinition } from "../engine/types";
+import { compareByCodepoint } from "../utils";
 import {
   assertBackingTableSuperset,
   buildEntityTableMeta,
@@ -21,7 +22,7 @@ function canonicalColumnsKey(meta: EntityTableMeta): string {
   // (buildEntityTable ohne relations) trägt legitim weniger FK-Indexes
   // als das Entity-Meta derselben Tabelle.
   return [...meta.columns]
-    .sort((a, b) => a.name.localeCompare(b.name))
+    .sort((a, b) => compareByCodepoint(a.name, b.name))
     .map(
       (c) =>
         `${c.name}|${c.pgType}|${c.notNull}|${c.defaultSql ?? ""}|${c.primaryKey ?? false}|${c.identity ?? false}|${c.bigintJsMode ?? ""}`,

package/src/db/dialect.ts

@@ -337,10 +337,12 @@ function makeIndex(name: string, unique: boolean): IndexBuilder {
   };
 }
 
+// @wrapper-known semantic-alias
 export function index(name: string): IndexBuilder {
   return makeIndex(name, false);
 }
 
+// @wrapper-known semantic-alias
 export function uniqueIndex(name: string): IndexBuilder {
   return makeIndex(name, true);
 }
@@ -428,7 +430,7 @@ export function table<TCols extends ColumnMap>(
     const handle: ColumnHandle = {
       name: final.sqlName,
       pgType: final.pgType,
-      getSQLType: () => pgTypeToSqlType(final.pgType),
+      getSQLType: () => pgTypeToSqlType(final.pgType), // @wrapper-known semantic-alias
     };
     handles[field] = handle;
     const meta: ColumnMeta = {