@cosmicdrift/kumiko-framework 0.304.0 → 0.306.0

package/src/pipeline/dispatch-query.ts

@@ -4,7 +4,7 @@ import { filterReadFields } from "../engine/field-access";
 import type { QueryHandlerDef, SessionUser } from "../engine/types";
 import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors";
 import { assertNoSecretLeak } from "../secrets";
-import type { DispatchContext } from "./dispatch-shared";
+import type { DispatchContext, WriteOrigin } from "./dispatch-shared";
 import {
   buildHandlerContext,
   enforceRateLimit,
@@ -21,10 +21,11 @@ export async function executeQuery(
   type: string,
   payload: unknown,
   user: SessionUser,
+  origin: WriteOrigin,
   tx?: DbTx,
 ): Promise<unknown> {
   return runHandlerInstrumented(ctx, type, "query", user, () =>
-    executeQueryInner(ctx, type, payload, user, tx),
+    executeQueryInner(ctx, type, payload, user, origin, tx),
   );
 }
 
@@ -33,6 +34,7 @@ async function executeQueryInner(
   type: string,
   payload: unknown,
   user: SessionUser,
+  origin: WriteOrigin,
   tx?: DbTx,
 ): Promise<unknown> {
   const { registry } = ctx;
@@ -83,9 +85,9 @@ async function executeQueryInner(
   // A resolved member (ctx.queryAsMember) runs in a Postgres READ ONLY transaction, not just the ctx surface below.
   return user.origin === "member-resolution"
     ? runInMemberReadOnlyTransaction(ctx, tx, (readOnlyTx) =>
-        runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, readOnlyTx),
+        runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, readOnlyTx),
       )
-    : runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, tx);
+    : runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, tx);
 }
 
 async function runQueryHandler(
@@ -95,10 +97,19 @@ async function runQueryHandler(
   payload: unknown,
   includeDeleted: boolean,
   user: SessionUser,
+  origin: WriteOrigin,
   tx: DbTx | undefined,
 ): Promise<unknown> {
   const { registry } = ctx;
-  const handlerContext = await buildHandlerContext(ctx, type, user, tx, undefined, includeDeleted);
+  const handlerContext = await buildHandlerContext(
+    ctx,
+    type,
+    user,
+    origin,
+    tx,
+    undefined,
+    includeDeleted,
+  );
   let result = await handler.handler({ type, payload, user }, handlerContext);
 
   // postQuery-Hooks: fire BEFORE field-access-filter so hooks see raw data

package/src/pipeline/dispatch-shared.ts

@@ -100,6 +100,9 @@ import {
   systemIdentitySwitchDenied,
 } from "./system-identity-switch";
 import type { TenantTimezoneCache } from "./tenant-timezone-cache";
+import { buildPersonalDataGate, rootWriteOrigin, type WriteOrigin } from "./write-origin";
+
+export type { WriteOrigin } from "./write-origin";
 
 // Framework/pipeline stays bundled-features-free, so this can't import the
 // `tenant` feature — the literal below IS the coupling to its `timezone`
@@ -277,6 +280,7 @@ export async function buildHandlerContext(
   ctx: DispatchContext,
   type: string,
   user: SessionUser,
+  origin: WriteOrigin,
   tx?: DbTx,
   afterCommitHooks?: AfterCommitHook[],
   includeDeleted?: boolean,
@@ -320,6 +324,7 @@ export async function buildHandlerContext(
         unsafeRaw: handlerEscapeHatch,
         report: reportEscapeHatch,
         memberReadOnly: isMemberResolutionPrincipal(user),
+        personalDataGate: buildPersonalDataGate(registry, origin),
       },
     );
   // Propagate the request's AbortSignal so every TenantDb query throws when
@@ -421,10 +426,11 @@ export async function buildHandlerContext(
     user,
     hasIdentitySwitchGrant,
     {
+      // Inherits the caller's origin, so switching to SYSTEM cannot shed an anonymous root.
       queryAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
-        executeQuery(ctx, targetType, payload, asUser, tx), // @wrapper-known semantic-alias
+        executeQuery(ctx, targetType, payload, asUser, origin, tx), // @wrapper-known semantic-alias
       writeAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
-        executeWrite(ctx, targetType, payload, asUser, tx, bridgeSink),
+        executeWrite(ctx, targetType, payload, asUser, origin, tx, bridgeSink),
     },
     identitySwitchAudit,
   );
@@ -483,10 +489,10 @@ export async function buildHandlerContext(
   );
   const bridge = {
     query: (targetType: string, payload: unknown) =>
-      executeQuery(ctx, targetType, payload, user, tx), // @wrapper-known semantic-alias
+      executeQuery(ctx, targetType, payload, user, origin, tx), // @wrapper-known semantic-alias
     queryAs: identitySwitch.queryAs,
     write: async (targetType: string, payload: unknown) => {
-      const res = await executeWrite(ctx, targetType, payload, user, tx, bridgeSink);
+      const res = await executeWrite(ctx, targetType, payload, user, origin, tx, bridgeSink);
       return res;
     },
     writeAs: identitySwitch.writeAs,
@@ -1175,8 +1181,9 @@ function buildAuthClaimsContext(ctx: DispatchContext, user: SessionUser): AuthCl
       })
     : undefined;
   const identitySwitch = createGatedIdentitySwitch("r.authClaims hook", user, false, {
+    // Login is itself the root operation; the hook context is read-only.
     queryAs: (asUser: SessionUser, qn: string, payload: unknown) =>
-      executeQuery(ctx, qn, payload, asUser), // @wrapper-known semantic-alias
+      executeQuery(ctx, qn, payload, asUser, rootWriteOrigin(ctx.registry, qn, asUser)), // @wrapper-known semantic-alias
     writeAs: async () => {
       throw new InternalError({
         message: "r.authClaims hook context has no writeAs — auth-claims hooks are read-only.",

package/src/pipeline/dispatch-stream.ts

@@ -14,6 +14,7 @@ import {
   ensureFeatureEnabled,
   isMemberResolutionPrincipal,
   runStreamInstrumented,
+  type WriteOrigin,
 } from "./dispatch-shared";
 
 // Standalone stream execution — used by the public dispatcher.stream().
@@ -27,8 +28,11 @@ export async function* executeStream(
   type: string,
   payload: unknown,
   user: SessionUser,
+  origin: WriteOrigin,
 ): AsyncGenerator<unknown> {
-  yield* runStreamInstrumented(ctx, type, user, () => executeStreamInner(ctx, type, payload, user));
+  yield* runStreamInstrumented(ctx, type, user, () =>
+    executeStreamInner(ctx, type, payload, user, origin),
+  );
 }
 
 async function* executeStreamInner(
@@ -36,6 +40,7 @@ async function* executeStreamInner(
   type: string,
   payload: unknown,
   user: SessionUser,
+  origin: WriteOrigin,
 ): AsyncGenerator<unknown> {
   const { registry } = ctx;
   const handler = registry.getStreamHandler(type);
@@ -80,7 +85,7 @@ async function* executeStreamInner(
   // await; close is fire-and-forget instead (#1563).
   let abandonedForInvalidation = false;
   try {
-    const handlerContext = await buildHandlerContext(ctx, type, user);
+    const handlerContext = await buildHandlerContext(ctx, type, user, origin);
     const chunks = handler.handler({ type, payload: parsed.data, user }, handlerContext);
     iterator = chunks[Symbol.asyncIterator]();
 

package/src/pipeline/dispatch-write.ts

@@ -22,7 +22,7 @@ import {
   writeFailure,
 } from "../errors";
 import { assertNoSecretLeak } from "../secrets";
-import type { DispatchContext } from "./dispatch-shared";
+import type { DispatchContext, WriteOrigin } from "./dispatch-shared";
 import {
   buildHandlerContext,
   CONFIG_WRITE_RESET_TYPE,
@@ -129,6 +129,7 @@ async function runLifecycle(
   data: unknown,
   handlerContext: HandlerContext,
   user: SessionUser,
+  origin: WriteOrigin,
   afterCommitHooks: AfterCommitHook[],
   runner: DbRunner | undefined,
 ): Promise<void> {
@@ -156,6 +157,7 @@ async function runLifecycle(
         ctx,
         type,
         user,
+        origin,
         undefined,
         afterCommitHooks,
       );
@@ -169,6 +171,7 @@ async function runLifecycle(
         ctx,
         type,
         user,
+        origin,
         undefined,
         afterCommitHooks,
       );
@@ -192,11 +195,12 @@ export async function executeWrite(
   type: string,
   payload: unknown,
   user: SessionUser,
+  origin: WriteOrigin,
   tx: DbTx | undefined,
   afterCommitHooks: AfterCommitHook[],
 ): Promise<WriteResult> {
   return runHandlerInstrumented(ctx, type, "write", user, () =>
-    executeWriteInner(ctx, type, payload, user, tx, afterCommitHooks),
+    executeWriteInner(ctx, type, payload, user, origin, tx, afterCommitHooks),
   );
 }
 
@@ -227,12 +231,13 @@ export async function executeNestedWrite(
   type: string,
   payload: unknown,
   user: SessionUser,
+  origin: WriteOrigin,
   tx: DbTx | undefined,
   afterCommitHooks: AfterCommitHook[],
 ): Promise<WriteResult> {
   const { registry } = ctx;
   const nested = extractNestedSpecs(type, payload, registry);
-  if (!nested) return executeWrite(ctx, type, payload, user, tx, afterCommitHooks);
+  if (!nested) return executeWrite(ctx, type, payload, user, origin, tx, afterCommitHooks);
 
   // Pre-flight client-shape checks. Merge non-array issues (collected up
   // front by extractNestedSpecs) with fk-injection issues into one error
@@ -264,6 +269,7 @@ export async function executeNestedWrite(
     type,
     nested.cleanPayload,
     user,
+    origin,
     tx,
     afterCommitHooks,
   );
@@ -339,6 +345,7 @@ export async function executeNestedWrite(
         spec.subType,
         subPayload,
         user,
+        origin,
         tx,
         afterCommitHooks,
       );
@@ -363,6 +370,7 @@ async function executeWriteInner(
   type: string,
   payload: unknown,
   user: SessionUser,
+  origin: WriteOrigin,
   tx: DbTx | undefined,
   afterCommitHooks: AfterCommitHook[],
 ): Promise<WriteResult> {
@@ -461,7 +469,7 @@ async function executeWriteInner(
     }
   }
 
-  const handlerContext = await buildHandlerContext(ctx, type, user, tx, afterCommitHooks);
+  const handlerContext = await buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks);
 
   // Auto transition guard: if entity has transitions and handler doesn't skip it.
   // Reads via the guard's own db handle — for r.systemScope() handlers
@@ -553,7 +561,16 @@ async function executeWriteInner(
   if (result.isSuccess) {
     try {
       const runner = resolveDbSource(ctx, tx);
-      await runLifecycle(ctx, type, result.data, handlerContext, user, afterCommitHooks, runner);
+      await runLifecycle(
+        ctx,
+        type,
+        result.data,
+        handlerContext,
+        user,
+        origin,
+        afterCommitHooks,
+        runner,
+      );
     } catch (e) {
       return writeFailure(wrapToKumiko(e));
     }

package/src/pipeline/dispatcher.ts

@@ -32,6 +32,7 @@ import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
 import { createMemberReaderFn } from "./member-reader";
 import { createTenantTimezoneCache } from "./tenant-timezone-cache";
+import { rootWriteOrigin } from "./write-origin";
 
 // Re-export for callers that reach for dispatcher-adjacent types (tests,
 // HTTP-layer stubs) — dispatch consumes these, grouping the type-surface
@@ -182,9 +183,15 @@ export function createDispatcher(
 
     batch: (commands, user, requestId?) => runBatch(ctx, commands, user, requestId),
 
-    query: (typeOrRef, payload, user) => executeQuery(ctx, resolveType(typeOrRef), payload, user),
+    query: (typeOrRef, payload, user) => {
+      const type = resolveType(typeOrRef);
+      return executeQuery(ctx, type, payload, user, rootWriteOrigin(registry, type, user));
+    },
 
-    stream: (typeOrRef, payload, user) => executeStream(ctx, resolveType(typeOrRef), payload, user),
+    stream: (typeOrRef, payload, user) => {
+      const type = resolveType(typeOrRef);
+      return executeStream(ctx, type, payload, user, rootWriteOrigin(registry, type, user));
+    },
 
     async command(typeOrRef, payload, user) {
       const type = resolveType(typeOrRef);

package/src/pipeline/idempotency.ts

@@ -19,6 +19,7 @@ export type IdempotencyGuard = {
     token: string,
     result: unknown,
   ): Promise<void>;
+  release(tenantId: string, userId: string, requestId: string, token: string): Promise<void>;
 };
 
 // Sentinel prefix stored under the key while the handler is running. Each
@@ -64,6 +65,16 @@ export function createIdempotencyGuard(
     end
   `;
 
+  // Same CAS guard as storeScript: only clear the lock if we still own it.
+  // A stale token (lock already reclaimed by a new owner) is a no-op.
+  const releaseScript = `
+    if redis.call("get", KEYS[1]) == ARGV[1] then
+      return redis.call("del", KEYS[1])
+    else
+      return 0
+    end
+  `;
+
   async function tryAcquire(key: string): Promise<string | null> {
     const token = `${PENDING_PREFIX}${generateId()}`;
     const acquired = await redis.set(key, token, "EX", pendingTtl, "NX");
@@ -138,5 +149,10 @@ export function createIdempotencyGuard(
       // SET and could stomp that fresher result with our stale one.
       void written;
     },
+
+    async release(tenantId, userId, requestId, token) {
+      const key = `${prefix}${tenantId}:${userId}:${requestId}`;
+      await redis.eval(releaseScript, 1, key, token);
+    },
   };
 }

package/src/pipeline/member-reader.ts

@@ -15,6 +15,7 @@ import {
 import { executeQuery } from "./dispatch-query";
 import { type DispatchContext, resolveAuthClaimsFn, resolveDbSource } from "./dispatch-shared";
 import { isSystemIdentity } from "./system-identity-switch";
+import { rootWriteOrigin } from "./write-origin";
 
 // Stricter than interactive sign-in: an unknown principal or a tenant
 // mid-teardown must not resolve — there is no user-facing flow to recover.
@@ -103,6 +104,7 @@ export function createMemberReaderFn(
 
   return async (userId, qn, payload) => {
     const user = await resolve(userId);
-    return executeQuery(ctx, qn, payload, user, tx);
+    // A resolved member is never anonymous and read-only, so it may start its own root.
+    return executeQuery(ctx, qn, payload, user, rootWriteOrigin(ctx.registry, qn, user), tx);
   };
 }

package/src/pipeline/system-identity-switch.ts

@@ -1,4 +1,9 @@
-import { type TenantDb, withUnsafeRawGrant } from "../db/tenant-db";
+import {
+  type TenantDb,
+  type UncheckedSystemDb,
+  withSystemDbUnsafeRawGrant,
+  withUnsafeRawGrant,
+} from "../db/tenant-db";
 import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user";
 import type {
   ActiveMembershipResult,
@@ -214,7 +219,10 @@ function readIdentitySwitchFn<
 }
 
 // context's own keys only — never touch a property of the resolved value, which may be a Proxy that throws on any get.
-function readDbLikeValue(context: object, key: "db" | "dbOutsideTransaction"): object | undefined {
+function readDbLikeValue(
+  context: object,
+  key: "db" | "dbOutsideTransaction" | "systemDb",
+): object | undefined {
   if (!(key in context)) return undefined;
   const value = (context as Record<string, unknown>)[key];
   return typeof value === "object" && value !== null ? value : undefined;
@@ -340,6 +348,7 @@ export function withHookEscapeHatchGrant<TContext extends object>(
   const ctxQueryProjection = readIdentitySwitchFn<ProjectionReader>(context, "queryProjection");
   const ctxDb = readDbLikeValue(context, "db");
   const ctxDbOutsideTransaction = readDbLikeValue(context, "dbOutsideTransaction");
+  const ctxSystemDb = readDbLikeValue(context, "systemDb");
   if (
     !ctxQueryAs &&
     !ctxWriteAs &&
@@ -347,7 +356,8 @@ export function withHookEscapeHatchGrant<TContext extends object>(
     !ctxQueryAsMember &&
     !ctxQueryProjection &&
     !ctxDb &&
-    !ctxDbOutsideTransaction
+    !ctxDbOutsideTransaction &&
+    !ctxSystemDb
   ) {
     return context;
   }
@@ -366,10 +376,18 @@ export function withHookEscapeHatchGrant<TContext extends object>(
     ...(ctxDbOutsideTransaction && {
       dbOutsideTransaction: withUnsafeRawGrant(ctxDbOutsideTransaction as TenantDb, escapeHatch),
     }),
+    // @cast-boundary engine-bridge — withSystemDbUnsafeRawGrant passes non-UncheckedSystemDb values through unchanged.
+    ...(ctxSystemDb && {
+      systemDb: withSystemDbUnsafeRawGrant(
+        ctxSystemDb as UncheckedSystemDb,
+        escapeHatch,
+        callerLabel,
+      ),
+    }),
   };
 }
 
-// Re-gates a hook's own ctx.queryAs/ctx.writeAs/ctx.queryProjection/ctx.db/ctx.dbOutsideTransaction instead of inheriting the handler's grant.
+// Re-gates a hook's own ctx.queryAs/ctx.writeAs/ctx.queryProjection/ctx.db/ctx.dbOutsideTransaction/ctx.systemDb instead of inheriting the handler's grant.
 export function bindHookEscapeHatchGrant(
   fn: LifecycleHookFn,
   label: string,

package/src/pipeline/write-origin.ts

@@ -0,0 +1,107 @@
+// The static check in boot-validator/access-declarations.ts only sees a handler's own
+// input schema; writes reached via ctx.write/writeAs/queryAs, hooks or foreign-feature
+// tables are only visible at the actual write, so the gate runs there at runtime.
+import { buildEntityTable } from "../db/table-builder";
+import { type PersonalDataGate, tableNameOf } from "../db/tenant-db";
+import {
+  accessAllowsAnonymous,
+  declaredPersonalData,
+  personalFieldNames,
+} from "../engine/personal-data-fields";
+import { ANONYMOUS_ROLE } from "../engine/system-user";
+import type { AccessRule, Registry, SessionUser } from "../engine/types";
+import type { EntityDefinition } from "../engine/types/fields";
+import { AccessDeniedError } from "../errors";
+import { FrameworkReasons } from "../errors/reasons";
+import { toSnakeCase } from "../utils/case";
+
+export type WriteOrigin = {
+  readonly rootHandler: string;
+  readonly anonymousRoot: boolean;
+  // Only a write-handler root can declare public-intake; a query/stream root never does.
+  readonly publicIntake: boolean;
+};
+
+function declaresPublicIntake(access: AccessRule): boolean {
+  return accessAllowsAnonymous(access) && declaredPersonalData(access) === "public-intake";
+}
+
+// Only the public dispatcher entry points compute a root; every nested call inherits
+// it, so switching identity via ctx.writeAs(SYSTEM, ...) cannot shed an anonymous root.
+export function rootWriteOrigin(registry: Registry, type: string, user: SessionUser): WriteOrigin {
+  const writeHandler = registry.getWriteHandler(type);
+  return {
+    rootHandler: type,
+    anonymousRoot: user.roles.includes(ANONYMOUS_ROLE),
+    publicIntake: writeHandler !== undefined && declaresPublicIntake(writeHandler.access),
+  };
+}
+
+// Owner binding is ignored (honorOwnerBinding=false): all anonymous callers share one
+// user id, so from("user:id", ...) vouches for nobody.
+const personalDataTableMaps = new WeakMap<Registry, ReadonlyMap<string, ReadonlySet<string>>>();
+
+function personalColumnNames(entity: EntityDefinition): ReadonlySet<string> {
+  return new Set([...personalFieldNames(entity, false)].map(toSnakeCase));
+}
+
+function buildPersonalDataTableMap(registry: Registry): ReadonlyMap<string, ReadonlySet<string>> {
+  const map = new Map<string, ReadonlySet<string>>();
+  for (const [entityName, entity] of registry.getAllEntities()) {
+    const columns = personalColumnNames(entity);
+    if (columns.size === 0) continue;
+    const table = buildEntityTable(entityName, entity, {
+      relations: registry.getRelations(entityName),
+    });
+    map.set(tableNameOf(table), columns);
+  }
+  return map;
+}
+
+function personalDataTableMap(registry: Registry): ReadonlyMap<string, ReadonlySet<string>> {
+  const cached = personalDataTableMaps.get(registry);
+  if (cached) return cached;
+  const built = buildPersonalDataTableMap(registry);
+  personalDataTableMaps.set(registry, built);
+  return built;
+}
+
+// Names fields only, never values: the error reaches the anonymous HTTP caller.
+function publicIntakeRequiredError(
+  origin: WriteOrigin,
+  target: string,
+  fields: readonly string[],
+): AccessDeniedError {
+  return new AccessDeniedError({
+    message:
+      `Anonymous root handler "${origin.rootHandler}" wrote personal-data field(s) ` +
+      `${fields.map((f) => `"${f}"`).join(", ")} on "${target}". Declare ` +
+      'access: { roles: [..., "anonymous"], personalData: "public-intake" } on ' +
+      `"${origin.rootHandler}" to allow anonymous callers to write personal data.`,
+    details: {
+      reason: FrameworkReasons.publicIntakeRequired,
+      rootHandler: origin.rootHandler,
+      target,
+      fields,
+    },
+  });
+}
+
+// Without an entity the table name is looked up in the registry map; tables outside it
+// (unmanaged stores, hand-built tables) carry no personal-data annotations and pass.
+export function buildPersonalDataGate(
+  registry: Registry,
+  origin: WriteOrigin,
+): PersonalDataGate | undefined {
+  if (!origin.anonymousRoot || origin.publicIntake) return undefined;
+  const map = personalDataTableMap(registry);
+  return (tableName, keys, entity) => {
+    const personalFields = entity ? personalColumnNames(entity) : map.get(tableName);
+    // skip: table carries no personal-data annotations
+    if (!personalFields) return;
+    const offending = [...new Set(keys.map(toSnakeCase))].filter((k) => personalFields.has(k));
+    // skip: write touches no personal-data field
+    if (offending.length === 0) return;
+    throw publicIntakeRequiredError(origin, tableName, offending);
+  };
+}

package/src/rate-limit/__tests__/middleware.integration.test.ts

@@ -186,4 +186,44 @@ describe("authEndpointRateLimit (L2)", () => {
     const otherAcc = await reqA("user-b");
     expect(otherAcc.status).toBe(200);
   });
+
+  test("GET /api/auth/tenants is exempt (session read), but POST on the same path is not", async () => {
+    const app = new Hono();
+    app.use(
+      "/api/auth/*",
+      authEndpointRateLimit({ resolver, limit: 2, windowSeconds: 60, onFailClosed: () => {} }),
+    );
+    app.get("/api/auth/tenants", (c) => c.text("ok"));
+    app.post("/api/auth/tenants", (c) => c.text("ok"));
+    app.post("/api/auth/login", (c) => c.text("ok"));
+
+    const ipHeader = { "x-forwarded-for": "10.0.2.1" };
+
+    // 10 GETs — none consume the l2:ip:/api/auth/tenants bucket.
+    for (let i = 0; i < 10; i++) {
+      const res = await app.request("/api/auth/tenants", { headers: ipHeader });
+      expect(res.status).toBe(200);
+      // Exempt requests skip the resolver entirely — no rate-limit headers.
+      expect(res.headers.get("X-RateLimit-Limit")).toBeNull();
+    }
+
+    // A separate credential-endpoint bucket is untouched by the above.
+    await app.request("/api/auth/login", { method: "POST", headers: ipHeader });
+    await app.request("/api/auth/login", { method: "POST", headers: ipHeader });
+    const loginBlocked = await app.request("/api/auth/login", {
+      method: "POST",
+      headers: ipHeader,
+    });
+    expect(loginBlocked.status).toBe(429);
+
+    // POST on the exempt path is method-exact, not path-exact — it still
+    // shares the ordinary ip+path bucket and trips at the same limit.
+    await app.request("/api/auth/tenants", { method: "POST", headers: ipHeader });
+    await app.request("/api/auth/tenants", { method: "POST", headers: ipHeader });
+    const postTenantsBlocked = await app.request("/api/auth/tenants", {
+      method: "POST",
+      headers: ipHeader,
+    });
+    expect(postTenantsBlocked.status).toBe(429);
+  });
 });

package/src/rate-limit/middleware.ts

@@ -1,4 +1,5 @@
 import type { Context, MiddlewareHandler } from "hono";
+import { isAuthRateLimitExempt } from "../api/api-constants";
 import { requestContext } from "../api/request-context";
 import { RateLimitError, serializeError } from "../errors";
 import type { RateLimitDecision, RateLimitResolver } from "./resolver";
@@ -84,6 +85,8 @@ export function authEndpointRateLimit(opts: AuthEndpointRateLimitOptions): Middl
   const onFailClosed = opts.onFailClosed ?? defaultOnFailClosed("l2-auth-endpoints");
 
   return async (c, next) => {
+    if (isAuthRateLimitExempt(c.req.method, c.req.path)) return next();
+
     const ip = extractIp(c);
     if (!ip) return next();
 

package/src/stack/__tests__/setup-test-stack-metrics.integration.test.ts

@@ -0,0 +1,79 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../../engine";
+import { resolveObservabilityWiring } from "../../observability/metrics-wiring";
+import { setupTestStack, type TestStack } from "../test-stack";
+import { TestUsers } from "../test-users";
+
+const METRICS_TOKEN = "setup-test-stack-metrics-token-minimum-32-chars!!";
+
+const pingFeature = defineFeature("stmetrics", (r) => {
+  r.writeHandler(
+    "ping",
+    z.object({}),
+    async () => ({ isSuccess: true as const, data: { ok: true } }),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
+});
+
+let stack: TestStack | undefined;
+
+afterEach(async () => {
+  await stack?.cleanup();
+  stack = undefined;
+});
+
+describe("setupTestStack metrics option (integration)", () => {
+  test("mirrors runProdApp wiring: /metrics scrapes after a real request, token-gated", async () => {
+    stack = await setupTestStack({
+      features: [pingFeature],
+      ...resolveObservabilityWiring(METRICS_TOKEN),
+    });
+
+    // kumiko_http_requests_total is only recorded by the http middleware, so scrape after a real request.
+    await stack.http.command("stmetrics:write:ping", {}, TestUsers.admin);
+
+    const noAuth = await stack.app.request("/metrics");
+    expect(noAuth.status).toBe(401);
+
+    const wrongToken = await stack.app.request("/metrics", {
+      headers: { Authorization: "Bearer wrong-token" },
+    });
+    expect(wrongToken.status).toBe(401);
+
+    const scraped = await stack.app.request("/metrics", {
+      headers: { Authorization: `Bearer ${METRICS_TOKEN}` },
+    });
+    expect(scraped.status).toBe(200);
+    expect(scraped.headers.get("Content-Type")).toMatch(/openmetrics-text/);
+    const body = await scraped.text();
+    expect(body).toMatch(/kumiko_http_requests_total\{[^}]*route="\/api\/command"[^}]*\} 1/);
+  });
+
+  test("no metrics option: /metrics is unmounted (404)", async () => {
+    stack = await setupTestStack({ features: [pingFeature] });
+
+    const res = await stack.app.request("/metrics");
+    expect(res.status).toBe(404);
+  });
+
+  test("custom path override: mounts only at the overridden path", async () => {
+    const wiring = resolveObservabilityWiring(METRICS_TOKEN);
+    if (!("metrics" in wiring)) throw new Error("resolveObservabilityWiring did not wire metrics");
+
+    stack = await setupTestStack({
+      features: [pingFeature],
+      ...wiring,
+      metrics: { ...wiring.metrics, path: "/internal/metrics" },
+    });
+
+    const atDefault = await stack.app.request("/metrics");
+    expect(atDefault.status).toBe(404);
+
+    const atCustom = await stack.app.request("/internal/metrics", {
+      headers: { Authorization: `Bearer ${METRICS_TOKEN}` },
+    });
+    expect(atCustom.status).toBe(200);
+    expect(atCustom.headers.get("Content-Type")).toMatch(/openmetrics-text/);
+  });
+});