@cosmicdrift/kumiko-framework 0.105.1 → 0.108.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.105.1",
+  "version": "0.108.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>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.105.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.108.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/full-stack.integration.test.ts

@@ -1,7 +1,8 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { updateRows } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
 import { createEventStoreExecutor } from "../db/event-store-executor";
-import { selectMany, updateMany } from "../db/query";
+import { selectMany } from "../db/query";
 import { defineFeature, type EntityId, type HandlerContext, type SaveContext } from "../engine";
 import { UnprocessableError, writeFailure } from "../errors";
 import { eventsTable } from "../event-store";
@@ -715,7 +716,7 @@ describe("full stack: entity cache", () => {
     await stack.http.queryOk("users:query:user:detail", { id }, adminUser);
 
     // Raw DB update — bypasses cache invalidation
-    await updateMany(stack.db, userTable, { firstName: "RawDbChange" }, { id: id });
+    await updateRows(stack.db, userTable, { firstName: "RawDbChange" }, { id: id });
 
     // Detail still returns cached (old) value
     const stale = await stack.http.queryOk<Record<string, unknown>>(

package/src/__tests__/schema-cli.integration.test.ts

@@ -204,6 +204,35 @@ export const FEATURES = [];
     expect(code).toBe(0);
     expect(cap.log.join("\n")).toContain("feature configuration is valid");
   });
+
+  test("FEATURES with a bad nav→screen ref → validateBoot fails, exit 1 (512/1)", async () => {
+    // Absolute file import (not the package name): appCwd is a bare tmpdir
+    // with no node_modules of its own — a real app resolves
+    // "@cosmicdrift/kumiko-framework/engine" via its own install, but this
+    // synthetic fixture needs a resolvable path regardless of cwd.
+    const engineSrc = join(import.meta.dir, "../engine/index.ts");
+    writeFileSync(
+      join(appCwd, "kumiko/schema.ts"),
+      `import { defineFeature } from "${engineSrc}";
+export const ENTITY_METAS = [
+  { tableName: "read_widgets", source: "unmanaged", indexes: [],
+    columns: [{ name: "id", pgType: "uuid", notNull: true, primaryKey: true, defaultSql: "gen_random_uuid()" }] },
+];
+export const FEATURES = [
+  defineFeature("probe", (r) => {
+    r.nav({ id: "nav-ghost", label: "Ghost", screen: "probe:screen:ghost" });
+  }),
+];
+`,
+    );
+    await runSchemaCli(["generate", "init"], appCwd, captureOut().out);
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(1);
+    expect(cap.err.join("\n")).toContain("boot:");
+    expect(cap.err.join("\n")).toContain("probe:screen:ghost");
+    expect(cap.err.join("\n")).toContain("is not registered");
+  });
 });
 
 describe("runSchemaCli — DB-backed paths", () => {

package/src/__tests__/transition-guard.integration.test.ts

@@ -1,7 +1,7 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { updateRows } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
 import { createEventStoreExecutor } from "../db/event-store-executor";
-import { updateMany } from "../db/query";
 import { buildEntityTable } from "../db/table-builder";
 import {
   createBooleanField,
@@ -268,7 +268,7 @@ describe("auto transition guard: per-entity transition map (cache key includes e
     // Raw-DB-mark-deleted — we need a soft-deleted row whose status is a
     // terminal state. If the guard fired, any status write would throw
     // "Invalid transition: closed → <x>". We want it silently skipped.
-    await updateMany(
+    await updateRows(
       stack.db,
       ticketTable,
       { status: "closed", isDeleted: true },

package/src/api/__tests__/batch.integration.test.ts

@@ -1,7 +1,8 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
-import { asRawClient, insertOne, selectMany } from "../../db/query";
+import { asRawClient, selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
 import {
   createEntity,
@@ -217,7 +218,7 @@ describe("POST /api/batch", () => {
 
   test("mid-batch failure: all writes roll back, afterCommit hooks do NOT fire", async () => {
     // Seed with one existing item so we can verify the batch didn't persist anything
-    await insertOne(stack.db, itemTable, {
+    await seedRow(stack.db, itemTable, {
       name: "seed",
       counter: 0,
       tenantId: "00000000-0000-4000-8000-000000000001",

package/src/api/__tests__/dispatcher-live.integration.test.ts

@@ -1,9 +1,10 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { createLiveDispatcher } from "@cosmicdrift/kumiko-dispatcher-live";
+import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
 import { generateToken } from "../../api/tokens";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
-import { asRawClient, insertOne, selectMany } from "../../db/query";
+import { asRawClient, selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
 import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
@@ -159,7 +160,7 @@ describe("dispatcher-live (integration) — full path against Kumiko server", ()
 
   test("query: dispatches GET-style-POST (Kumiko uses POST for query too), returns data", async () => {
     // Seed a row first.
-    await insertOne(stack.db, itemTable, {
+    await seedRow(stack.db, itemTable, {
       id: generateId(),
       tenantId: admin.tenantId,
       name: "seed",

package/src/api/__tests__/jwt.test.ts

@@ -26,6 +26,17 @@ function forge(claims: Record<string, unknown>): Promise<string> {
     .sign(new TextEncoder().encode(SECRET));
 }
 
+// Same as forge(), but never calls .setSubject() — the only way to produce a
+// validly-signed token with no `sub` claim at all (forge() always sets one).
+function forgeNoSub(claims: Record<string, unknown>): Promise<string> {
+  return new jose.SignJWT(claims)
+    .setProtectedHeader({ alg: "HS256" })
+    .setIssuer(ISSUER)
+    .setIssuedAt()
+    .setExpirationTime("1h")
+    .sign(new TextEncoder().encode(SECRET));
+}
+
 describe("createJwtHelper.verify — payload validation (KF-2)", () => {
   const jwt = createJwtHelper(SECRET);
 
@@ -55,4 +66,20 @@ describe("createJwtHelper.verify — payload validation (KF-2)", () => {
     const token = await forge({ tenantId: TENANT, roles: ["ok", 7] });
     await expect(jwt.verify(token)).rejects.toThrow(/roles/);
   });
+
+  it("rejects a validly-signed token with no sub claim", async () => {
+    const token = await forgeNoSub({ tenantId: TENANT, roles: ["TenantAdmin"] });
+    await expect(jwt.verify(token)).rejects.toThrow(/sub/);
+  });
+
+  it("rejects a token whose sub claim is an empty string", async () => {
+    const token = await new jose.SignJWT({ tenantId: TENANT, roles: ["TenantAdmin"] })
+      .setProtectedHeader({ alg: "HS256" })
+      .setSubject("")
+      .setIssuer(ISSUER)
+      .setIssuedAt()
+      .setExpirationTime("1h")
+      .sign(new TextEncoder().encode(SECRET));
+    await expect(jwt.verify(token)).rejects.toThrow(/sub/);
+  });
 });

package/src/api/__tests__/pat-scope.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "bun:test";
+import { patAllows, qnMatches } from "../pat-scope";
+
+describe("qnMatches", () => {
+  it("exact match", () => {
+    expect(qnMatches("credit:query:schedule", "credit:query:schedule")).toBe(true);
+    expect(qnMatches("credit:query:schedule", "credit:query:credit:list")).toBe(false);
+  });
+
+  it("wildcard suffix matches on prefix", () => {
+    expect(qnMatches("credit:write:bauspar:*", "credit:write:bauspar:create")).toBe(true);
+    expect(qnMatches("credit:write:bauspar:*", "credit:write:bauspar:delete")).toBe(true);
+    expect(qnMatches("credit:write:bauspar:*", "credit:write:create")).toBe(false);
+  });
+
+  it("bare wildcard matches everything", () => {
+    expect(qnMatches("*", "anything:at:all")).toBe(true);
+  });
+});
+
+describe("patAllows", () => {
+  const allowed = ["credit:write:create", "credit:write:bauspar:*"];
+
+  it("permits an exact or wildcard-covered type", () => {
+    expect(patAllows(allowed, "credit:write:create")).toBe(true);
+    expect(patAllows(allowed, "credit:write:bauspar:update")).toBe(true);
+  });
+
+  it("denies a type no scope covers", () => {
+    expect(patAllows(allowed, "credit:write:credit:delete")).toBe(false);
+  });
+
+  it("fail-closed on an empty allow-list", () => {
+    expect(patAllows([], "credit:write:create")).toBe(false);
+  });
+});

package/src/api/__tests__/request-id-middleware.test.ts

@@ -70,3 +70,54 @@ describe("requestIdMiddleware — signal propagation", () => {
     expect(captured?.aborted).toBe(true);
   });
 });
+describe("requestIdMiddleware — ip + userAgent capture (603/2)", () => {
+  test("populates ip from x-forwarded-for and userAgent from the User-Agent header", async () => {
+    let captured: { ip: string | undefined; userAgent: string | undefined } = {
+      ip: undefined,
+      userAgent: undefined,
+    };
+
+    const app = new Hono();
+    app.use("/probe", requestIdMiddleware());
+    app.get("/probe", (c) => {
+      const ctx = requestContext.get();
+      captured = { ip: ctx?.ip, userAgent: ctx?.userAgent };
+      return c.text("ok");
+    });
+
+    const res = await app.request(
+      new Request("http://test.local/probe", {
+        method: "GET",
+        headers: {
+          "x-forwarded-for": "203.0.113.7, 10.0.0.1",
+          "user-agent": "Mozilla/5.0 (probe-test)",
+        },
+      }),
+    );
+
+    expect(res.status).toBe(200);
+    expect(captured.ip).toBe("203.0.113.7");
+    expect(captured.userAgent).toBe("Mozilla/5.0 (probe-test)");
+  });
+
+  test("no User-Agent header → userAgent stays undefined, not an empty string", async () => {
+    let captured: string | undefined = "unset";
+
+    const app = new Hono();
+    app.use("/probe", requestIdMiddleware());
+    app.get("/probe", (c) => {
+      captured = requestContext.get()?.userAgent;
+      return c.text("ok");
+    });
+
+    // fetch/undici always add a default User-Agent unless explicitly cleared —
+    // Hono's app.request accepts a raw Request, so an empty-but-present header
+    // simulates a client that sends the header with no value.
+    const res = await app.request(
+      new Request("http://test.local/probe", { method: "GET", headers: {} }),
+    );
+
+    expect(res.status).toBe(200);
+    expect(captured).toBeUndefined();
+  });
+});

package/src/api/auth-middleware.ts

@@ -16,6 +16,12 @@ export const AUTH_COOKIE_NAME = "kumiko_auth";
 export const CSRF_COOKIE_NAME = "kumiko_csrf";
 export const CSRF_HEADER_NAME = "X-CSRF-Token";
 
+// Prefix that marks a bearer token as a long-lived Personal Access Token
+// rather than a JWT session. The PAT feature mints tokens with this prefix;
+// the middleware uses it to route to patResolver instead of jwt.verify. Kept
+// here so both sides import the same literal.
+export const PAT_TOKEN_PREFIX = "kpat_";
+
 // Which wire the current request authenticated over. Downstream
 // csrf-middleware reads this: cookie-auth gets a CSRF-token check, bearer
 // does not (headers aren't set cross-origin by browsers, so there is no
@@ -41,11 +47,23 @@ export type AuthSessionChecker = (
   expectedUserId: string,
 ) => Promise<AuthSessionStatus>;
 
+// Resolves a raw Personal Access Token (bearer, prefixed PAT_TOKEN_PREFIX)
+// into a SessionUser, or null when the token is unknown/revoked/expired. The
+// PAT feature owns the DB-backed implementation: hash the token, look up the
+// row, resolve the user's CURRENT roles live (not a snapshot), and expand the
+// token's granted scopes into `pat.allowedQns`. Middleware just consults it
+// and short-circuits the JWT path on a hit.
+export type PatResolver = (rawToken: string) => Promise<SessionUser | null>;
+
 export type AuthMiddlewareOptions = {
   // Called after JWT-verify when the token carries a sid. If the checker
   // reports anything other than "live", the request is rejected with 401.
   // Omit to run in stateless-JWT mode (any valid JWT is accepted).
   readonly sessionChecker?: AuthSessionChecker;
+  // Called for bearer tokens carrying the PAT prefix, BEFORE jwt.verify. On a
+  // hit the middleware sets the returned SessionUser and skips the JWT path
+  // entirely. Omit to disable PAT auth (bearer PATs then fail jwt.verify → 401).
+  readonly patResolver?: PatResolver;
   // When true, a JWT WITHOUT a sid is rejected. Leave false during rollout
   // so already-issued stateless JWTs keep working until they expire; flip
   // to true once the server has been emitting sid for longer than the JWT
@@ -169,7 +187,7 @@ function extractToken(
 }
 
 export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions = {}) {
-  const { sessionChecker, strictMode = false, anonymousAccess } = options;
+  const { sessionChecker, strictMode = false, anonymousAccess, patResolver } = options;
 
   return async (c: Context, next: Next) => {
     const extracted = extractToken(c);
@@ -212,6 +230,13 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     }
     const { token, transport } = extracted;
 
+    // PAT path: a bearer token carrying the PAT prefix is a long-lived
+    // Personal Access Token, not a JWT. Short-circuit the JWT path entirely.
+    // Cookie transport is never a PAT (the browser holds the JWT).
+    if (patResolver && transport === "bearer" && token.startsWith(PAT_TOKEN_PREFIX)) {
+      return await handlePat(c, patResolver, token, next);
+    }
+
     let payload: Awaited<ReturnType<JwtHelper["verify"]>>;
     try {
       payload = await jwt.verify(token);
@@ -277,6 +302,45 @@ export function getAuthTransport(c: Context): AuthTransport | undefined {
   return c.get(AUTH_TRANSPORT_KEY) as AuthTransport | undefined;
 }
 
+// PAT request flow. Resolve the hashed token → SessionUser (live roles +
+// granted scopes), then apply the same X-Tenant-mismatch guard as the JWT
+// path before continuing. A null resolve is an invalid/revoked/expired token
+// → 401. Structured like handleAnonymous so authMiddleware stays flat.
+async function handlePat(
+  c: Context,
+  patResolver: PatResolver,
+  token: string,
+  next: Next,
+): Promise<Response | undefined> {
+  const patUser = await patResolver(token);
+  if (!patUser) {
+    return middlewareReject(c, {
+      code: "invalid_token",
+      status: 401,
+      message: "personal access token invalid, revoked or expired",
+      i18nKey: "auth.errors.invalidToken",
+    });
+  }
+  // The PAT carries its own tenant; an X-Tenant header pointing elsewhere is a
+  // confused client — reject loudly, same stance as the JWT path.
+  const headerTenant = c.req.header(TENANT_HEADER_NAME);
+  if (headerTenant !== undefined && headerTenant !== patUser.tenantId) {
+    return middlewareReject(c, {
+      code: "tenant_mismatch",
+      status: 400,
+      message: "PAT tenantId and X-Tenant header disagree",
+      i18nKey: "auth.errors.tenantMismatch",
+      details: { patTenantId: patUser.tenantId, headerTenantId: headerTenant },
+    });
+  }
+  c.set(USER_KEY, patUser);
+  c.set(AUTH_TRANSPORT_KEY, "bearer");
+  await next();
+  // skip: PAT path completed — next() ran; explicit return keeps the
+  // Response|undefined union honest (same as handleAnonymous).
+  return;
+}
+
 // Anonymous request flow. Steps:
 //   1. Read raw client-supplied tenant from X-Tenant header / cookie.
 //   2. Validate format (UUID-shape) — junk strings get 400 right here.

package/src/api/auth-routes.ts

@@ -15,6 +15,7 @@ import {
   type AuthSessionStatus,
   CSRF_COOKIE_NAME,
   getUser,
+  type PatResolver,
 } from "./auth-middleware";
 import type { JwtHelper } from "./jwt";
 import { generateToken } from "./tokens";
@@ -232,6 +233,16 @@ export type AuthRoutesConfig = {
   // once all fresh JWTs emit a sid and the legacy stateless tokens are
   // expected to have expired. Default false keeps old tokens working.
   sessionStrictMode?: boolean;
+  // Resolves bearer Personal Access Tokens (PAT_TOKEN_PREFIX) into a
+  // SessionUser, consulted BEFORE jwt.verify. Wired by the
+  // personal-access-tokens feature; unwired = PAT auth disabled.
+  patResolver?: PatResolver;
+  // Per-token request-rate limiter for PAT-authenticated requests, keyed by
+  // the token id (SessionUser.pat.tokenId). Cookie/JWT requests are unaffected.
+  // Reuses the LoginRateLimiter shape (a generic keyed check/reset limiter).
+  // Wired by run-prod-app when the PAT feature is mounted; unwired = no PAT
+  // rate limiting.
+  patRateLimiter?: LoginRateLimiter;
   // Password-reset flow. When wired, POST /auth/request-password-reset and
   // POST /auth/reset-password are mounted as public routes. The framework
   // dispatches to the feature-level handlers (authoring QNs typically come

package/src/api/index.ts

@@ -5,10 +5,11 @@ export type {
   AuthMiddlewareOptions,
   AuthSessionChecker,
   AuthSessionStatus,
+  PatResolver,
   TenantExists,
   TenantResolver,
 } from "./auth-middleware";
-export { authMiddleware, getUser } from "./auth-middleware";
+export { authMiddleware, getUser, PAT_TOKEN_PREFIX } from "./auth-middleware";
 export type {
   AuthRoutesConfig,
   LoginRateLimiter,
@@ -30,6 +31,7 @@ export {
 } from "./http-cache";
 export type { JwtHelper, JwtPayload } from "./jwt";
 export { createJwtHelper } from "./jwt";
+export { patAllows, qnMatches } from "./pat-scope";
 export { type RequestContextData, requestContext } from "./request-context";
 export { requestIdMiddleware } from "./request-id-middleware";
 export { createApiRoutes } from "./routes";

package/src/api/jwt.ts

@@ -50,10 +50,7 @@ export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
     async verify(token) {
       const { payload } = await jose.jwtVerify(token, encodedSecret, { issuer });
 
-      // Defence in depth: a valid signature does not guarantee well-formed claims. A
-      // leaked secret, key confusion, or a hand-crafted token can still carry junk —
-      // validate the claim shape and reject (verify() throws → 401 in auth-middleware)
-      // instead of casting blindly.
+      // defence-in-depth: valid sig ≠ well-formed claims; malformed payload → throw → 401
       const tenantId = parseTenantId(payload["tenantId"]);
       if (tenantId === null) {
         throw new Error("JWT payload validation failed: tenantId claim is missing or malformed");
@@ -69,9 +66,12 @@ export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
         }
         roles.push(role);
       }
+      if (typeof payload.sub !== "string" || payload.sub === "") {
+        throw new Error("JWT payload validation failed: sub claim is missing or malformed");
+      }
 
       const result: JwtPayload = {
-        sub: String(payload.sub),
+        sub: payload.sub,
         tenantId,
         roles,
       };

package/src/api/pat-scope.ts

@@ -0,0 +1,14 @@
+// QN scope-matching for Personal Access Tokens. A token's granted scopes
+// expand (in the PAT feature's resolver) to QN globs like "credit:write:*" or
+// "credit:query:credit:list". A glob ending in "*" matches any dispatch type
+// sharing the prefix; otherwise it is an exact match. Fail-closed: an empty
+// allow-list matches nothing, so a PAT with no scopes can call nothing.
+
+export function qnMatches(pattern: string, type: string): boolean {
+  if (pattern.endsWith("*")) return type.startsWith(pattern.slice(0, -1));
+  return pattern === type;
+}
+
+export function patAllows(allowedQns: readonly string[], type: string): boolean {
+  return allowedQns.some((pattern) => qnMatches(pattern, type));
+}

package/src/api/request-context.ts

@@ -30,6 +30,9 @@ export type RequestContextData = {
   // Populated by requestIdMiddleware from x-forwarded-for or the
   // socket address. Undefined for non-HTTP entry points (jobs, MSP).
   readonly ip?: string;
+  // Raw User-Agent header — audit trails (download tokens, GDPR export
+  // access) want it alongside `ip`. Undefined for non-HTTP entry points.
+  readonly userAgent?: string;
 };
 
 const storage = new AsyncLocalStorage<RequestContextData>();

package/src/api/request-id-middleware.ts

@@ -37,12 +37,14 @@ export function requestIdMiddleware() {
     // than fabricate one.
     const xff = c.req.header("x-forwarded-for");
     const ip = xff?.split(",")[0]?.trim();
+    const userAgent = c.req.header("user-agent");
     await requestContext.run(
       {
         requestId,
         correlationId,
         ...(signal ? { signal } : {}),
         ...(ip && ip.length > 0 ? { ip } : {}),
+        ...(userAgent !== undefined ? { userAgent } : {}),
       },
       () => next(),
     );

package/src/api/routes.ts

@@ -1,6 +1,8 @@
 import { type Context, Hono } from "hono";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { SessionUser } from "../engine/types/handlers";
 import {
+  AccessDeniedError,
   type KumikoError,
   reraiseAsKumikoError,
   serializeError,
@@ -12,6 +14,7 @@ import type { Dispatcher } from "../pipeline/dispatcher";
 import { stringifyJson } from "../utils/safe-json";
 import { Routes } from "./api-constants";
 import { getUser } from "./auth-middleware";
+import { patAllows } from "./pat-scope";
 import { requestContext } from "./request-context";
 
 export function createApiRoutes(dispatcher: Dispatcher) {
@@ -22,6 +25,7 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     const body = await c.req.json<{ type: string; payload: unknown; requestId?: string }>();
 
     try {
+      assertPatAllowed(user, body.type);
       const result = await dispatcher.write(body.type, body.payload, user, body.requestId);
       if (!result.isSuccess) {
         return writeErrorResponse(c, reraiseAsKumikoError(result.error), body.type);
@@ -59,6 +63,9 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     }
 
     try {
+      if (user.pat) {
+        for (const cmd of body.commands) assertPatAllowed(user, cmd.type);
+      }
       const result = await dispatcher.batch(body.commands, user, body.requestId);
       if (!result.isSuccess) {
         const err = reraiseAsKumikoError(result.error);
@@ -92,6 +99,7 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     const body = await c.req.json<{ type: string; payload: unknown }>();
 
     try {
+      assertPatAllowed(user, body.type);
       const result = await dispatcher.query(body.type, body.payload, user);
       return jsonResponse(c, { data: result });
     } catch (e) {
@@ -104,6 +112,7 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     const body = await c.req.json<{ type: string; payload: unknown }>();
 
     try {
+      assertPatAllowed(user, body.type);
       await dispatcher.command(body.type, body.payload, user);
       return c.json({ ok: true }, 202);
     } catch (e) {
@@ -120,6 +129,19 @@ function jsonResponse(c: Context, body: unknown, status: ContentfulStatusCode =
 
 const toKumiko = toKumikoError;
 
+// PAT scope enforcement at the API boundary. No-op for cookie/JWT users
+// (user.pat undefined → unrestricted). For a PAT-authenticated request the
+// dispatch type must match one of the token's granted-scope QN globs, else
+// 403 — fail-closed, thrown so each route's existing catch shapes the body.
+function assertPatAllowed(user: SessionUser, type: string): void {
+  if (user.pat && !patAllows(user.pat.allowedQns, type)) {
+    throw new AccessDeniedError({
+      message: `personal access token scope does not permit ${type}`,
+      details: { handler: type, scopes: user.pat.scopes },
+    });
+  }
+}
+
 // Unexpected server faults (5xx) carry their diagnostic stack only on the
 // in-process error — serializeError strips cause/details from the wire body.
 // Without this a wrapped throw (InternalError{cause}) returns a 500 with zero

package/src/api/server.ts

@@ -46,7 +46,7 @@ import {
 import type { SearchAdapter } from "../search/types";
 import { assertUnreachable, generateId } from "../utils";
 import { PUBLIC_API_PATHS } from "./api-constants";
-import { type AnonymousAccessConfig, authMiddleware } from "./auth-middleware";
+import { type AnonymousAccessConfig, authMiddleware, getUser } from "./auth-middleware";
 import { type AuthRoutesConfig, createAuthRoutes } from "./auth-routes";
 import { csrfMiddleware } from "./csrf-middleware";
 import { createJwtHelper, type JwtHelper } from "./jwt";
@@ -561,6 +561,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
   const jwtGuard = authMiddleware(jwt, {
     ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
     ...(options.auth?.sessionStrictMode ? { strictMode: options.auth.sessionStrictMode } : {}),
+    ...(options.auth?.patResolver ? { patResolver: options.auth.patResolver } : {}),
     ...(options.anonymousAccess ? { anonymousAccess: options.anonymousAccess } : {}),
   });
   app.use("/api/*", async (c, next) => {
@@ -568,6 +569,33 @@ export function buildServer(options: ServerOptions): KumikoServer {
     return jwtGuard(c, next);
   });
 
+  // PAT rate limiting — runs AFTER the auth guard so the resolved principal is
+  // available. Only PAT-authenticated requests are counted (keyed by token id);
+  // cookie/JWT users pass through untouched. In-memory limiter is per-instance
+  // (see run-prod-app) — a multi-node deployment wanting a shared counter swaps
+  // in a Redis-backed LoginRateLimiter.
+  const patRateLimiter = options.auth?.patRateLimiter;
+  if (patRateLimiter) {
+    app.use("/api/*", async (c, next) => {
+      if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+      const pat = getUser(c)?.pat;
+      if (pat && !(await patRateLimiter.check(pat.tokenId))) {
+        return c.json(
+          {
+            error: {
+              code: "pat_rate_limited",
+              httpStatus: 429,
+              message: "personal access token rate limit exceeded",
+              i18nKey: "auth.errors.patRateLimited",
+            },
+          },
+          429,
+        );
+      }
+      return 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

package/src/bun-db/__tests__/batch-methods.test.ts

@@ -1,10 +1,11 @@
 import { describe, expect, test } from "bun:test";
+import type { EntityTableMeta } from "../../db/entity-table-meta";
 import { deleteManyBatched } from "../query";
 
 describe("deleteManyBatched (mock)", () => {
   test("requires non-empty where", async () => {
-    const meta = {
-      source: "unmanaged" as const,
+    const meta: EntityTableMeta = {
+      source: "unmanaged",
       tableName: "read_items",
       indexes: [],
       columns: [

package/src/bun-db/__tests__/query-guards.test.ts

@@ -1,8 +1,9 @@
 import { describe, expect, test } from "bun:test";
+import type { EntityTableMeta } from "../../db/entity-table-meta";
 import { incrementCounter, selectMany } from "../query";
 
-const meta = {
-  source: "unmanaged" as const,
+const meta: EntityTableMeta = {
+  source: "unmanaged",
   tableName: "read_items",
   indexes: [],
   columns: [