@cosmicdrift/kumiko-bundled-features 0.105.2 → 0.109.0

package/src/ledger/handlers/confirm-schedule-period.write.ts

@@ -13,7 +13,7 @@ import {
   transactionExecutor,
   transactionTable,
 } from "../executor";
-import { scheduleReference } from "../recurring";
+import { findReversedIds, isoMonth, scheduleReference } from "../recurring";
 import { type ConfirmSchedulePeriodPayload, confirmSchedulePeriodPayloadSchema } from "../schemas";
 
 // confirm-schedule-period — turn ONE projected period of a schedule into a posted,
@@ -42,6 +42,13 @@ export function createConfirmSchedulePeriodHandler(
       );
       if (!schedule) return writeFailure(new NotFoundError("schedule", payload.scheduleId));
 
+      if (
+        payload.period < isoMonth(String(schedule["startDate"])) ||
+        (schedule["endDate"] != null && payload.period > isoMonth(String(schedule["endDate"])))
+      ) {
+        return writeFailure(new NotFoundError("schedule-period", payload.period));
+      }
+
       const debitAccountId = String(schedule["debitAccountId"]);
       const creditAccountId = String(schedule["creditAccountId"]);
       for (const accountId of [debitAccountId, creditAccountId]) {
@@ -51,24 +58,33 @@ export function createConfirmSchedulePeriodHandler(
 
       const reference = scheduleReference(payload.scheduleId, payload.period);
 
-      // Scan this tenant's transactions (same full-tenant read the reports do) to
-      // find an active booking for this reference. A tx is reversed when another
-      // tx's reference names its id (the Storno mirror).
+      // Two targeted reads instead of a full-tenant transaction scan: (1) any
+      // booking that already carries this exact schedule-period reference —
+      // normally 0 or 1 row, never O(tenant's-full-history); (2) any Storno
+      // that mirrors one of those candidates (a tx is reversed when ANOTHER
+      // tx's `reference` names its id).
       // ponytail: read-then-write, so two confirms racing the same period could
       // double-book; add a unique index on (tenantId, reference) when concurrent
       // confirms become real.
-      const txRows = await selectMany(ctx.db.raw, transactionTable, {
+      const candidates = await selectMany(ctx.db.raw, transactionTable, {
         tenantId: event.user.tenantId,
+        reference,
       });
-      const txIds = new Set(txRows.map((r) => String(r["id"])));
-      const reversedTxIds = new Set(
-        txRows
-          .filter((r) => r["reference"] != null && txIds.has(String(r["reference"])))
-          .map((r) => String(r["reference"])),
-      );
-      const active = txRows.find(
-        (r) => r["reference"] === reference && !reversedTxIds.has(String(r["id"])),
+      const candidateIds = candidates.map((r) => String(r["id"]));
+      const stornos =
+        candidateIds.length > 0
+          ? await selectMany(ctx.db.raw, transactionTable, {
+              tenantId: event.user.tenantId,
+              reference: { in: candidateIds },
+            })
+          : [];
+      const reversedIds = findReversedIds(
+        [...candidates, ...stornos].map((r) => ({
+          id: String(r["id"]),
+          reference: r["reference"] === null ? null : String(r["reference"]),
+        })),
       );
+      const active = candidates.find((r) => !reversedIds.has(String(r["id"])));
       if (active) {
         const ok: WriteResult<{ id: string; alreadyBooked: true }> = {
           isSuccess: true,

package/src/ledger/handlers/reverse-transaction.write.ts

@@ -1,9 +1,15 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
-import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  ConflictError,
+  NotFoundError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { DEFAULT_LEDGER_ACCESS } from "../constants";
-import { transactionExecutor } from "../executor";
-import type { Posting } from "../schemas";
+import { transactionExecutor, transactionTable } from "../executor";
+import { normalizeLines } from "../reports";
 import { type ReverseTransactionPayload, reverseTransactionPayloadSchema } from "../schemas";
 
 // reverse-transaction (Storno) — the ONLY correction path for a posted entry.
@@ -24,8 +30,41 @@ export function createReverseTransactionHandler(
       const original = await transactionExecutor.detail({ id: payload.id }, event.user, ctx.db);
       if (!original) return writeFailure(new NotFoundError("transaction", payload.id));
 
-      const originalLines = original["lines"] as readonly Posting[]; // @cast-boundary db-row
-      const lines = originalLines.map((l) => ({ accountId: l.accountId, amount: -l.amount }));
+      // Only a posted entry contributes to the books (rawBalances skips
+      // anything else) — reversing a draft would book a real, balanced
+      // Storno entry against a booking that was never counted, creating a
+      // phantom balance with no corresponding original.
+      if (original["status"] !== "posted") {
+        return writeFailure(
+          new UnprocessableError("transaction_not_posted", {
+            details: { transactionId: payload.id, status: original["status"] },
+          }),
+        );
+      }
+
+      // Dedup guard: two reverse() calls on the same original would each book
+      // an independently-balanced Storno (the global trial balance stays 0
+      // either way, masking the bug), doubling the per-account effect. The
+      // reference column ties a Storno back to its original 1:1.
+      const alreadyReversed = await selectMany(ctx.db.raw, transactionTable, {
+        tenantId: event.user.tenantId,
+        reference: payload.id,
+      });
+      if (alreadyReversed.length > 0) {
+        return writeFailure(
+          new ConflictError({
+            message: "transaction already reversed",
+            details: { transactionId: payload.id },
+          }),
+        );
+      }
+
+      // jsonb `lines` may surface as a parsed array or a JSON string depending
+      // on the driver path — normalizeLines handles both (see reports.ts).
+      const lines = normalizeLines(original["lines"]).map((l) => ({
+        accountId: l.accountId,
+        amount: -l.amount,
+      }));
 
       return transactionExecutor.create(
         {

package/src/ledger/recurring.ts

@@ -53,10 +53,26 @@ export function scheduleReference(scheduleId: string, period: string): string {
   return `schedule:${scheduleId}:${period}`;
 }
 
+// A Storno mirror carries reference = the reversed tx's id, so any tx whose
+// reference names another tx in the set marks that other tx reversed. Shared
+// by mergeScheduleActuals (below) and confirm-schedule-period.write.ts's
+// idempotency check (684/4) — same detection, kept in one place so a fix
+// can't land in one call-site and drift from the other.
+export function findReversedIds(
+  rows: readonly { readonly id: string; readonly reference: string | null }[],
+): Set<string> {
+  const ids = new Set(rows.map((r) => r.id));
+  return new Set(
+    rows
+      .filter((r) => r.reference !== null && ids.has(r.reference))
+      .map((r) => r.reference as string),
+  );
+}
+
 // "YYYY-MM" ⇄ a month index (year*12 + monthOfYear), so window math is pure
 // integer arithmetic — no Date object (no-date-api guard) and no DST/timezone
 // drift. isoMonth tolerates a full ISO date ("2026-01-15" → "2026-01").
-function isoMonth(iso: string): string {
+export function isoMonth(iso: string): string {
   return iso.slice(0, 7);
 }
 
@@ -105,14 +121,7 @@ export function mergeScheduleActuals(
   transactions: readonly LedgerTxRow[],
   asOf: string,
 ): ScheduleMonth[] {
-  const txIds = new Set(transactions.map((t) => t.id));
-  // A Storno mirror carries reference = the reversed tx's id, so any tx whose
-  // reference names another tx marks that other tx reversed.
-  const reversedTxIds = new Set(
-    transactions
-      .filter((t) => t.reference != null && txIds.has(t.reference))
-      .map((t) => t.reference as string),
-  );
+  const reversedTxIds = findReversedIds(transactions);
   const asOfIndex = monthIndex(isoMonth(asOf));
 
   return projection.map((projected) => {

package/src/ledger/schemas.ts

@@ -57,7 +57,10 @@ export const confirmSchedulePeriodPayloadSchema = z.object({
   scheduleId: z.string().min(1).max(64),
   period: z.string().regex(/^\d{4}-\d{2}$/, "period must be YYYY-MM"),
   amount: z.number().int().positive().optional(),
-  date: z.string().min(1).max(32).optional(),
+  date: z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, "date must be YYYY-MM-DD")
+    .optional(),
 });
 export type ConfirmSchedulePeriodPayload = z.infer<typeof confirmSchedulePeriodPayloadSchema>;
 

package/src/ledger/web/index.ts

@@ -1,6 +1,7 @@
 // @runtime client
-// Client-safe ledger surface: QN constants + the pure recurring helpers
-// (projection + Soll/Ist merge), nothing else. The full `../ledger` entry
+// Client-safe ledger surface: QN constants, the pure recurring helpers
+// (projection + Soll/Ist merge), and the Zod payload schemas (for client-side
+// pre-validation before dispatch) — nothing else. The full `../ledger` entry
 // re-exports the feature/handlers/executor, which pull bun-db/postgres — a
 // browser bundle that imports from there fails on Node builtins. A client screen
 // (e.g. a rent-cashflow view) imports the dispatch QNs + the pure forecast/merge

package/src/managed-pages/__tests__/branding-coerce.test.ts

@@ -2,12 +2,8 @@ import { describe, expect, test } from "bun:test";
 import { type BrandingTokens, EMPTY_BRANDING } from "../../page-render";
 import { coerceBranding } from "../branding";
 
-// coerceBranding is the IO boundary for the branding query's wire response:
-// untrusted `unknown` → BrandingTokens with no `as` cast. Every missing or
-// non-string field must collapse to "" so a malformed/empty response renders
-// the unbranded default rather than throwing — and an attacker-controlled
-// non-string (e.g. a logoUrl object) can never leak through as a live render
-// token. Exercised only indirectly by the integration path before this.
+// IO-boundary coercion: untrusted `unknown` → BrandingTokens, no `as` cast —
+// every missing/non-string field collapses to "" instead of throwing.
 
 describe("coerceBranding", () => {
   const FULL: BrandingTokens = {

package/src/personal-access-tokens/__tests__/pat.integration.test.ts

@@ -0,0 +1,205 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import {
+  createInMemoryLoginRateLimiter,
+  type PatResolver,
+} from "@cosmicdrift/kumiko-framework/api";
+import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { deleteRows } from "@cosmicdrift/kumiko-framework/testing";
+import { Temporal } from "temporal-polyfill";
+import { AuthHandlers } from "../../auth-email-password/constants";
+import { createAuthEmailPasswordFeature } from "../../auth-email-password/feature";
+import { createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { makeSessionHelpers } from "../../sessions/__tests__/test-helpers";
+import { SessionQueries } from "../../sessions/constants";
+import { createSessionsFeature } from "../../sessions/feature";
+import { userSessionEntity } from "../../sessions/schema/user-session";
+import { createTenantFeature } from "../../tenant";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { createUserFeature } from "../../user/feature";
+import { userEntity } from "../../user/schema/user";
+import { PatHandlers, PatQueries } from "../constants";
+import { createPersonalAccessTokensFeature } from "../feature";
+import { createPatResolver } from "../resolver";
+import { apiTokenEntity, apiTokenTable } from "../schema/api-token";
+import type { PatScopeConfig } from "../scopes";
+
+// Full loop, no mocks: mint a PAT via the create handler → use it as a bearer
+// token over real HTTP. The resolver hashes it, resolves live roles, and the
+// API boundary enforces the granted scopes. Proves the security matrix:
+// allowed → 200, out-of-scope → 403 (while a JWT user could call it),
+// revoked/expired/unknown/membership-removed → 401.
+
+let stack: TestStack;
+let h: ReturnType<typeof makeSessionHelpers>;
+let patResolver: PatResolver | undefined;
+
+const encryptionKey = randomBytes(32).toString("base64");
+const TENANT: TenantId = testTenantId(1);
+
+// One domain "tokens" whose read set is exactly the two PAT queries —
+// deliberately NOT sessions:query:user-session:mine, so that QN is the
+// out-of-scope probe. Granted as "tokens:read".
+const SCOPES: PatScopeConfig = {
+  tokens: { label: "Tokens", read: [PatQueries.mine, PatQueries.availableScopes] },
+};
+
+async function mintToken(
+  actor: SessionUser,
+  opts?: { scopes?: string[]; expiresInDays?: number },
+): Promise<string> {
+  const res = await stack.http.writeOk<{ id: string; token: string }>(
+    PatHandlers.create,
+    {
+      name: "test",
+      scopes: opts?.scopes ?? ["tokens:read"],
+      ...(opts?.expiresInDays ? { expiresInDays: opts.expiresInDays } : {}),
+    },
+    actor,
+  );
+  return res.token;
+}
+
+beforeAll(async () => {
+  const encryption = createEncryptionProvider(encryptionKey);
+  const resolver = createConfigResolver({ encryption });
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      createAuthEmailPasswordFeature(),
+      createSessionsFeature(),
+      createPersonalAccessTokensFeature({ scopes: SCOPES }),
+    ],
+    extraContext: { configResolver: resolver, configEncryption: encryption },
+    authConfig: {
+      membershipQuery: "tenant:query:memberships",
+      loginHandler: AuthHandlers.login,
+      patResolver: (raw: string) => {
+        if (!patResolver) throw new Error("resolver not set");
+        return patResolver(raw);
+      },
+      // Low per-token cap so the rate-limit test can exhaust it. Other tests do
+      // ≤2 requests per (distinct) token, so this ceiling never trips them.
+      patRateLimiter: createInMemoryLoginRateLimiter(3, 60_000),
+    },
+  });
+  patResolver = createPatResolver({ db: stack.db, scopes: SCOPES });
+  h = makeSessionHelpers(stack, TENANT);
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafeCreateEntityTable(stack.db, userSessionEntity);
+  await unsafeCreateEntityTable(stack.db, apiTokenEntity);
+  await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function actorFor(email: string): Promise<SessionUser> {
+  const { userId } = await h.seedUser(email, "pw");
+  return { id: userId, tenantId: TENANT, roles: ["User"] };
+}
+
+// Raw login → JWT (no sid: session callbacks aren't wired here, and the PAT
+// path doesn't need them). Used only to prove a non-PAT bearer skips the gate.
+async function loginToken(email: string): Promise<string> {
+  const res = await stack.http.raw("POST", "/api/auth/login", { email, password: "pw" });
+  expect(res.status).toBe(200);
+  return ((await res.json()) as { token: string }).token;
+}
+
+describe("PAT auth", () => {
+  test("granted scope → 200", async () => {
+    const actor = await actorFor("granted@example.com");
+    const token = await mintToken(actor);
+    const res = await h.authedPost("/api/query", token, { type: PatQueries.mine, payload: {} });
+    expect(res.status).toBe(200);
+  });
+
+  test("out-of-scope QN → 403 (but a JWT user may call it)", async () => {
+    const actor = await actorFor("scope@example.com");
+    const token = await mintToken(actor);
+    const denied = await h.authedPost("/api/query", token, {
+      type: SessionQueries.mine,
+      payload: {},
+    });
+    expect(denied.status).toBe(403);
+
+    const jwt = await loginToken("scope@example.com");
+    const allowed = await h.authedPost("/api/query", jwt, {
+      type: SessionQueries.mine,
+      payload: {},
+    });
+    expect(allowed.status).toBe(200);
+  });
+
+  test("unknown token → 401", async () => {
+    const res = await h.authedPost("/api/query", "kpat_deadbeef", {
+      type: PatQueries.mine,
+      payload: {},
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test("revoked token → 401", async () => {
+    const actor = await actorFor("revoked@example.com");
+    const token = await mintToken(actor);
+    const rows = await stack.http.queryOk<Array<{ id: string }>>(PatQueries.mine, {}, actor);
+    const id = rows[0]?.id;
+    expect(id).toBeDefined();
+    await stack.http.writeOk(PatHandlers.revoke, { id }, actor);
+    const res = await h.authedPost("/api/query", token, { type: PatQueries.mine, payload: {} });
+    expect(res.status).toBe(401);
+  });
+
+  test("expired token → 401", async () => {
+    const actor = await actorFor("expired@example.com");
+    const token = await mintToken(actor);
+    const past = Temporal.Now.instant().subtract({ hours: 1 });
+    const rows =
+      (await stack.http.queryOk<Array<{ id: string }>>(PatQueries.mine, {}, actor)) ?? [];
+    await updateMany(stack.db, apiTokenTable, { expiresAt: past }, { id: rows[0]?.id });
+    const res = await h.authedPost("/api/query", token, { type: PatQueries.mine, payload: {} });
+    expect(res.status).toBe(401);
+  });
+
+  test("per-token rate limit → 429 once the cap is exceeded", async () => {
+    const actor = await actorFor("ratelimit@example.com");
+    const token = await mintToken(actor);
+    for (let i = 0; i < 3; i++) {
+      const ok = await h.authedPost("/api/query", token, { type: PatQueries.mine, payload: {} });
+      expect(ok.status).toBe(200);
+    }
+    const limited = await h.authedPost("/api/query", token, { type: PatQueries.mine, payload: {} });
+    expect(limited.status).toBe(429);
+  });
+
+  test("membership removed → 401 (live roles, no snapshot)", async () => {
+    const actor = await actorFor("removed@example.com");
+    const token = await mintToken(actor);
+    const ok = await h.authedPost("/api/query", token, { type: PatQueries.mine, payload: {} });
+    expect(ok.status).toBe(200);
+    // tenantMembershipsTable is ES-managed (executor-only branded); deleteRows
+    // is the test-side escape for out-of-band row removal.
+    await deleteRows(stack.db, tenantMembershipsTable, { userId: actor.id });
+    const res = await h.authedPost("/api/query", token, { type: PatQueries.mine, payload: {} });
+    expect(res.status).toBe(401);
+  });
+});

package/src/personal-access-tokens/__tests__/scopes.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "bun:test";
+import { expandScopes, type PatScopeConfig, parseGrant } from "../scopes";
+
+const CONFIG: PatScopeConfig = {
+  credit: { label: "Kredite", read: ["credit:query:*"], write: ["credit:write:*"] },
+  miete: { label: "Mieten", read: ["ledger:query:*"] }, // read-only domain
+};
+
+describe("parseGrant", () => {
+  it("splits domain:level on the last colon", () => {
+    expect(parseGrant("credit:write")).toEqual({ domain: "credit", level: "write" });
+  });
+  it("rejects a bare token", () => {
+    expect(parseGrant("credit")).toBeNull();
+  });
+});
+
+describe("expandScopes", () => {
+  it("read grants only the read QNs", () => {
+    expect(expandScopes(CONFIG, ["credit:read"])).toEqual(["credit:query:*"]);
+  });
+
+  it("write grants read + write QNs", () => {
+    expect(expandScopes(CONFIG, ["credit:write"]).sort()).toEqual(
+      ["credit:query:*", "credit:write:*"].sort(),
+    );
+  });
+
+  it("read-only domain ignores a write grant's missing write set", () => {
+    expect(expandScopes(CONFIG, ["miete:write"])).toEqual(["ledger:query:*"]);
+  });
+
+  it("unknown domain contributes nothing (fail-closed)", () => {
+    expect(expandScopes(CONFIG, ["ghost:write"])).toEqual([]);
+  });
+
+  it("unions across multiple grants without duplicates", () => {
+    expect(expandScopes(CONFIG, ["credit:read", "miete:read"]).sort()).toEqual(
+      ["credit:query:*", "ledger:query:*"].sort(),
+    );
+  });
+});

package/src/personal-access-tokens/constants.ts

@@ -0,0 +1,33 @@
+// @runtime client
+// Pure constants — client-marked so the web screen (web/) may import screen-id
+// and QN names without pulling the feature's server runtime barrel.
+export const PAT_FEATURE = "personal-access-tokens";
+
+// Snake_case reason strings (Error-Reasons guard: no colons/dashes).
+export const PatErrors = {
+  ownershipDenied: "ownership_denied",
+} as const;
+
+// Dormant custom-screen id (r.screen) — the app places it via r.nav. The client
+// maps it to the PatTokensScreen component.
+export const PAT_SCREEN_ID = "api-tokens";
+
+export const PatHandlers = {
+  create: "personal-access-tokens:write:create",
+  revoke: "personal-access-tokens:write:revoke",
+} as const;
+
+export const PatQueries = {
+  mine: "personal-access-tokens:query:mine",
+  availableScopes: "personal-access-tokens:query:available-scopes",
+} as const;
+
+// Only the first chars of a minted token are stored (alongside the hash) so the
+// UI can show "kpat_ab12…" for recognition without ever holding the secret.
+export const PAT_PREFIX_DISPLAY_LENGTH = 12;
+
+export type PatRateLimit = { readonly maxRequests: number; readonly windowMs: number };
+
+// Default per-token request rate for PAT-authenticated calls. Generous enough
+// for normal automation, low enough to blunt a leaked-token abuse spike.
+export const PAT_DEFAULT_RATE_LIMIT: PatRateLimit = { maxRequests: 120, windowMs: 60_000 };

package/src/personal-access-tokens/feature.ts

@@ -0,0 +1,78 @@
+import { buildEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { PAT_DEFAULT_RATE_LIMIT, PAT_FEATURE, PAT_SCREEN_ID, type PatRateLimit } from "./constants";
+import { buildAvailableScopesQuery } from "./handlers/available-scopes.query";
+import { createPatWrite } from "./handlers/create.write";
+import { listPatQuery } from "./handlers/list.query";
+import { revokePatWrite } from "./handlers/revoke.write";
+import { apiTokenEntity } from "./schema/api-token";
+import type { PatScopeConfig } from "./scopes";
+
+export type PersonalAccessTokensOptions = {
+  // The scopes this deployment offers. Each is a named bundle of QN globs a PAT
+  // may be granted (a scope can span features). Closed over by available-scopes
+  // (UI list) and exported so run-prod-app can build the resolver from the same
+  // single source.
+  readonly scopes: PatScopeConfig;
+  // Per-token request rate limit for PAT-authenticated calls. Defaults to
+  // PAT_DEFAULT_RATE_LIMIT (120/60s). run-prod-app builds the limiter from this.
+  readonly rateLimit?: PatRateLimit;
+};
+
+export type PatFeatureExports = {
+  readonly scopes: PatScopeConfig;
+  readonly rateLimit: PatRateLimit;
+};
+
+// Personal Access Tokens — long-lived, revocable bearer credentials for the
+// HTTP API. Like `sessions`, the hot-path resolver is NOT a handler: it runs on
+// every PAT-authenticated request and does a direct-DB point-read (see
+// createPatResolver / run-prod-app wiring). The dispatcher-side handlers here
+// only mint/list/revoke tokens and expose the scope catalog.
+export function createPersonalAccessTokensFeature(
+  options: PersonalAccessTokensOptions,
+): FeatureDefinition {
+  const { scopes } = options;
+  return defineFeature(PAT_FEATURE, (r) => {
+    r.describe(
+      "Long-lived, revocable Personal Access Tokens for headless HTTP-API access. Stores SHA-256 token hashes in the `read_api_tokens` direct-write table; the plaintext is returned once at creation. `create`/`revoke`/`mine` manage a user's own tokens and `available-scopes` lists the app-declared scope catalog. Bearer tokens carrying the PAT prefix are resolved before jwt.verify (roles resolved live, granted scopes enforced fail-closed at the API boundary) — the resolver is wired via run-prod-app, not the dispatcher.",
+    );
+    r.uiHints({ displayLabel: "Personal Access Tokens", category: "identity", recommended: false });
+    // Resolver reads memberships + users on every PAT request to build live
+    // roles — make both boot-time deps so a mis-wiring fails validateBoot.
+    r.requires("user", "tenant");
+    // Direct-write store like read_user_sessions: create/revoke write it, the
+    // resolver point-reads it. r.entity would make it a rebuildable projection
+    // whose replay (no token events) would wipe every live token (#498/#494).
+    r.unmanagedTable(buildEntityTableMeta("api-token", apiTokenEntity), {
+      reason: "read_side.api_tokens_direct_write",
+    });
+
+    const handlers = {
+      create: r.writeHandler(createPatWrite),
+      revoke: r.writeHandler(revokePatWrite),
+    };
+    const queries = {
+      mine: r.queryHandler(listPatQuery),
+      availableScopes: r.queryHandler(buildAvailableScopesQuery(scopes)),
+    };
+
+    // Dormant custom-screen — the client maps PAT_SCREEN_ID to PatTokensScreen;
+    // the app places it via r.nav in its logged-in settings area.
+    r.screen({
+      id: PAT_SCREEN_ID,
+      type: "custom",
+      renderer: { react: { __component: "PatTokensScreen" } },
+      access: { openToAll: true },
+    });
+
+    // scopes + rateLimit flow into feature.exports so run-prod-app builds the
+    // resolver + limiter from the same declaration — single source of truth.
+    return {
+      handlers,
+      queries,
+      scopes,
+      rateLimit: options.rateLimit ?? PAT_DEFAULT_RATE_LIMIT,
+    } satisfies { handlers: unknown; queries: unknown } & PatFeatureExports;
+  });
+}

package/src/personal-access-tokens/handlers/available-scopes.query.ts

@@ -0,0 +1,21 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import type { PatScopeConfig } from "../scopes";
+
+// Returns the app-declared scope domains ({name, label, canWrite}) so the mint
+// UI can render a per-domain level picker (no access / read / read & write).
+// canWrite is false for read-only domains → the UI hides the write option.
+// Static per deployment, not per user.
+export function buildAvailableScopesQuery(scopes: PatScopeConfig) {
+  return defineQueryHandler({
+    name: "available-scopes",
+    schema: z.object({}),
+    access: { openToAll: true },
+    handler: async () =>
+      Object.entries(scopes).map(([name, def]) => ({
+        name,
+        label: def.label,
+        canWrite: (def.write?.length ?? 0) > 0,
+      })),
+  });
+}

package/src/personal-access-tokens/handlers/create.write.ts

@@ -0,0 +1,41 @@
+import { insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { Temporal } from "temporal-polyfill";
+import { z } from "zod";
+import { mintPatToken } from "../hash";
+import { apiTokenTable } from "../schema/api-token";
+
+// Mint a PAT for the calling user in their active tenant. The plaintext token
+// is returned ONCE (data.token) and never again — only the hash is stored.
+// `scopes` are granted scope names; unknown names simply grant nothing at
+// resolve time (fail-closed), so no cross-check against the app config here.
+export const createPatWrite = defineWriteHandler({
+  name: "create",
+  schema: z.object({
+    name: z.string().min(1).max(120),
+    scopes: z.array(z.string().min(1)).min(1),
+    expiresInDays: z.number().int().positive().max(3650).optional(),
+  }),
+  access: { openToAll: true },
+  handler: async (event, ctx) => {
+    const { raw, hash, prefix } = mintPatToken();
+    const now = Temporal.Now.instant();
+    const id = generateId();
+    await insertOne(ctx.db, apiTokenTable, {
+      id,
+      userId: event.user.id,
+      tenantId: event.user.tenantId,
+      name: event.payload.name,
+      tokenHash: hash,
+      prefix,
+      scopes: JSON.stringify(event.payload.scopes),
+      createdAt: now,
+      expiresAt: event.payload.expiresInDays
+        ? now.add({ hours: 24 * event.payload.expiresInDays })
+        : null,
+      revokedAt: null,
+    });
+    return { isSuccess: true, data: { id, token: raw, prefix } };
+  },
+});