@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/personal-access-tokens/feature.ts

@@ -0,0 +1,184 @@
+import {
+  type AuthProviderPlugin,
+  EXT_TOKEN_VERIFIER,
+} from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { PAT_TOKEN_PREFIX } from "@cosmicdrift/kumiko-framework/api";
+import { deriveEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  API_TOKEN_ENTITY_NAME,
+  PAT_DEFAULT_RATE_LIMIT,
+  PAT_FEATURE,
+  type PatRateLimit,
+} from "./constants.js";
+import { buildAvailableScopesQuery } from "./handlers/available-scopes.query.js";
+import { type CreatePatOptions, createPatCreateHandler } from "./handlers/create.write.js";
+import { listPatQuery } from "./handlers/list.query.js";
+import { revokePatWrite } from "./handlers/revoke.write.js";
+import { PAT_FEATURE_I18N, patScopeOptionTranslations } from "./i18n.js";
+import { PAT_REVOKED_EVENT_SHORT, patRevokedSchema } from "./pat-revoked-event.js";
+import { createPatResolver } from "./resolver.js";
+import { apiTokenEntity } from "./schema/api-token.js";
+import type { PatScopeConfig } from "./scopes.js";
+import { createPatMintScreen, patListScreen } from "./screens.js";
+
+// Password-change is the only field-level trigger — see the postSave hook
+// below. MFA-enable/disable is wired separately (auth-mfa's
+// revokeAllPatTokens callback, late-bound at app-composition time) since
+// that's a different entity ("user-mfa") this feature doesn't own or
+// require.
+const PAT_REVOKE_TRIGGERING_FIELDS = ["passwordHash"] as const;
+
+export type BindPatAutoRevokeOnPasswordChange = (
+  revoker: (userId: string) => Promise<number>,
+) => void;
+
+// Reads the late-bind setter off a mounted personal-access-tokens feature's
+// exports — run{Prod,Dev}App call this once a concrete db is available,
+// mirrors sessions' own bindAutoRevokeFromFeature/bindAutoRevokeOnPasswordChange.
+export function bindPatAutoRevokeOnPasswordChangeFromFeature(
+  feature: FeatureDefinition,
+): BindPatAutoRevokeOnPasswordChange | undefined {
+  const exports = feature.exports;
+  if (exports && typeof exports === "object" && "bindAutoRevokeOnPasswordChange" in exports) {
+    const { bindAutoRevokeOnPasswordChange } = exports as {
+      bindAutoRevokeOnPasswordChange: unknown;
+    };
+    if (typeof bindAutoRevokeOnPasswordChange === "function") {
+      // @cast-boundary exports-walk — feature.exports is untyped by design
+      return bindAutoRevokeOnPasswordChange as BindPatAutoRevokeOnPasswordChange;
+    }
+  }
+  return undefined;
+}
+
+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;
+  /** Make the whole feature tier-gatable via the tier-engine. Use
+   *  { default: false } for fail-closed gating (feature off until a tier grants
+   *  it). Omit to keep PAT always-on (default). */
+  readonly toggleable?: { readonly default: boolean };
+  // Opt-in MFA re-auth gate for minting a token — wired via
+  // mfaVerifierFromFeature (auth-mfa/feature.ts) at app-composition time. No
+  // hard dependency on the optional auth-mfa feature.
+  readonly mfaVerifier?: CreatePatOptions["mfaVerifier"];
+  // Password-change revoker — same constructor-option-or-late-bind duality as
+  // sessions' own autoRevokeOnPasswordChange (bindAutoRevokeOnPasswordChange
+  // below wins only if this is unset). Lets tests pass a revoker directly
+  // instead of needing a post-setupTestStack bind call.
+  readonly autoRevokeOnPasswordChange?: (userId: string) => Promise<number>;
+};
+
+export type PatFeatureExports = {
+  readonly rateLimit: PatRateLimit;
+  readonly bindAutoRevokeOnPasswordChange: BindPatAutoRevokeOnPasswordChange;
+};
+
+// 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 / the tokenVerifier extension-point registration below). 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 `store_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) — registered as an auth-foundation tokenVerifier provider, resolved generically by the middleware. Pass { toggleable: { default: false } } to tier-gate the whole feature.",
+    );
+    r.uiHints({ displayLabel: "Personal Access Tokens", category: "identity", recommended: false });
+    // Opt-in tier-gating (mirrors ledger/tags): when set, the feature declares
+    // itself r.toggleable so the dispatcher gate + tier-engine can switch PAT
+    // on/off per tenant. { default: false } = fail-closed until a tier grants it.
+    if (options.toggleable !== undefined) r.toggleable(options.toggleable);
+    // Resolver reads memberships + users on every PAT request to build live
+    // roles — make both boot-time deps so a mis-wiring fails validateBoot.
+    // auth-foundation owns EXT_TOKEN_VERIFIER, which the useExtension below
+    // registers against.
+    r.requires("user", "tenant", "auth-foundation");
+    // Self-registers as a bearer-auth provider instead of the app wiring a
+    // dedicated patResolver callback — the middleware finds it generically
+    // via resolveTokenVerifier(), shape-matched by the PAT token prefix.
+    r.useExtension(EXT_TOKEN_VERIFIER, "pat", {
+      shape: { kind: "prefix", prefix: PAT_TOKEN_PREFIX },
+      build: (deps) => createPatResolver({ db: deps.db, scopes }),
+    } satisfies AuthProviderPlugin);
+    // Direct-write store like store_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.storeTable(
+      deriveEntityTableMeta(API_TOKEN_ENTITY_NAME, apiTokenEntity, { source: "unmanaged" }),
+      {
+        reason: "read_side.api_tokens_direct_write",
+        // create.write encrypts `name` via encryptForDirectWrite (#820).
+        piiEncryptedOnWrite: true,
+      },
+    );
+
+    // Custom domain-event for cross-instance access-invalidation,
+    // mirroring sessions' SESSION_REVOKED_EVENT_SHORT. r.defineEvent
+    // registers the schema so ctx.unsafeAppendEvent (revoke) enforces it at
+    // append time. revoke-for-user.ts appends via the low-level append()
+    // instead (needs to anchor on SYSTEM_TENANT_ID) — same guarantee via a
+    // different path. No projection: the payload IS the read, consumed
+    // directly off the event-store NOTIFY.
+    r.defineEvent(PAT_REVOKED_EVENT_SHORT, patRevokedSchema, { piiFields: "none" });
+
+    // Password-change auto-revoke — mirrors sessions' own
+    // autoRevokeOnPasswordChange postSave hook, including WHY it's a
+    // late-bind callback rather than direct ctx.db use: user:write:user:update
+    // is r.systemScope()'d (the user aggregate is a systemStream, framework
+    // #497), so a postSave hook on "user" gets a poisoned ctx.db here. The
+    // concrete revoker is bound once run{Prod,Dev}App has a real db handle.
+    let autoRevokeOnPasswordChange = options.autoRevokeOnPasswordChange;
+    r.hook("postSave", { allOf: "user" }, async (result) => {
+      // skip: nothing bound — same late-bind pattern as sessions/feature.ts
+      if (!autoRevokeOnPasswordChange) return;
+      // skip: brand-new user, no PATs can exist yet
+      if (result.isNew) return;
+      // skip: handler didn't touch any revoke-triggering field
+      if (!PAT_REVOKE_TRIGGERING_FIELDS.some((field) => result.changes[field] !== undefined)) {
+        return;
+      }
+      await autoRevokeOnPasswordChange(String(result.id));
+    });
+    const bindAutoRevokeOnPasswordChange: BindPatAutoRevokeOnPasswordChange = (revoker) => {
+      // explicit constructor option wins over the runtime binding
+      autoRevokeOnPasswordChange ??= revoker;
+    };
+
+    const handlers = {
+      create: r.writeHandler(createPatCreateHandler({ mfaVerifier: options.mfaVerifier })),
+      revoke: r.writeHandler(revokePatWrite),
+    };
+    const queries = {
+      mine: r.queryHandler(listPatQuery),
+      availableScopes: r.queryHandler(buildAvailableScopesQuery(scopes)),
+    };
+
+    // Declarative screens — list-with-revoke + mint-with-reveal. The app
+    // places `patListScreen` via r.nav in its logged-in settings area.
+    r.screen(patListScreen);
+    r.screen(createPatMintScreen(scopes));
+    r.translations({ keys: { ...PAT_FEATURE_I18N, ...patScopeOptionTranslations(scopes) } });
+
+    // rateLimit flows into feature.exports so run-prod-app builds the
+    // limiter from the same declaration — single source of truth. `scopes`
+    // is closed over directly by the useExtension build() above and by
+    // available-scopes, so it doesn't need to round-trip through exports.
+    return {
+      handlers,
+      queries,
+      bindAutoRevokeOnPasswordChange,
+      rateLimit: options.rateLimit ?? PAT_DEFAULT_RATE_LIMIT,
+    } satisfies { handlers: unknown; queries: unknown } & PatFeatureExports;
+  });
+}

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

@@ -0,0 +1,29 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import type { PatScopeConfig } from "../scopes.js";
+
+// 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: {
+        reason:
+          "any signed-in user may list the deployment-wide PAT scope domains; the data " +
+          "is static configuration, not per-user or per-tenant",
+      },
+    },
+    description:
+      "Lists the API scope domains this deployment declares, each with its display label and whether it offers write access, for choosing what a new personal access token may do.",
+    handler: async () =>
+      Object.entries(scopes).map(([name, def]) => ({
+        name,
+        label: def.label,
+        canWrite: (def.write?.length ?? 0) > 0,
+      })),
+  });
+}

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

@@ -0,0 +1,124 @@
+import { insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createSystemUser,
+  defineWriteHandler,
+  type HandlerContext,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { Temporal } from "temporal-polyfill";
+import * as z from "zod";
+import { encryptForDirectWrite, verifyPassword } from "../../shared/index.js";
+import { UserQueries } from "../../user/index.js";
+import { API_TOKEN_ENTITY_NAME, PAT_DEFAULT_EXPIRES_IN_DAYS, PatErrors } from "../constants.js";
+import { mintPatToken } from "../hash.js";
+import { apiTokenEntity, apiTokenTable } from "../schema/api-token.js";
+
+export type PatMfaVerifyResult = { readonly enrolled: boolean; readonly ok: boolean };
+
+export type CreatePatOptions = {
+  // Opt-in MFA re-auth gate — auth-mfa (if mounted) wires this in at
+  // app-composition time via mfaVerifierFromFeature. Deliberately generic
+  // here, same decoupling as login.write.ts's mfaStatusChecker: this
+  // feature must not import auth-mfa's types, only this shape.
+  readonly mfaVerifier?: (
+    ctx: HandlerContext,
+    userId: string,
+    tenantId: TenantId,
+    code: string | undefined,
+  ) => Promise<PatMfaVerifyResult>;
+};
+
+// @wrapper-known error-helper
+function reauthFailed() {
+  return writeFailure(
+    new UnprocessableError(PatErrors.reauthRequired, {
+      i18nKey: "errors.reauthRequired",
+    }),
+  );
+}
+
+// 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.
+//
+// Minting a long-lived bearer credential re-verifies the caller's password
+// (and MFA code, if enrolled) even though the request is already
+// session-authed — a stolen/leaked session cookie must not be enough to
+// stand up a durable API credential.
+export function createPatCreateHandler(opts: CreatePatOptions = {}) {
+  return 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(),
+      currentPassword: z.string().min(1),
+      mfaCode: z.string().optional(),
+    }),
+    access: {
+      openToAll: {
+        reason:
+          "each signed-in user may mint a personal access token for their own account " +
+          "only, after re-verifying their own password (and MFA code, if enrolled)",
+      },
+    },
+    escapeHatch: {
+      reason:
+        "Reads the caller's own passwordHash (privileged-only field) via ctx.queryAs(SYSTEM, " +
+        "user:findForAuth) to re-verify the current password before minting the token. Also " +
+        "reads the MFA enrollment of the user being re-authenticated via the mfaVerifier callback.",
+    },
+    description:
+      "Mints a personal access token for the calling user after re-verifying their password (and MFA code when enrolled) and returns the plaintext token exactly once; use it when a user needs a long-lived API credential.",
+    // Returns the plaintext token once; an agent turn would archive it in the
+    // LLM transcript, where it stays valid until revoked.
+    agent: { expose: false },
+    handler: async (event, ctx) => {
+      const systemUser = createSystemUser(event.user.tenantId);
+      const me = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+        id: event.user.id,
+      })) as { passwordHash: string | null } | null; // @cast-boundary db-runner
+      if (!me?.passwordHash) return reauthFailed();
+      const passwordOk = await verifyPassword(me.passwordHash, event.payload.currentPassword);
+      if (!passwordOk) return reauthFailed();
+
+      if (opts.mfaVerifier) {
+        const mfa = await opts.mfaVerifier(
+          ctx,
+          event.user.id,
+          event.user.tenantId,
+          event.payload.mfaCode,
+        );
+        if (mfa.enrolled && !mfa.ok) return reauthFailed();
+      }
+
+      const { raw, hash, prefix } = mintPatToken();
+      const now = Temporal.Now.instant();
+      const id = generateId();
+      const row = await encryptForDirectWrite(
+        apiTokenEntity,
+        API_TOKEN_ENTITY_NAME,
+        {
+          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: now.add({
+            hours: 24 * (event.payload.expiresInDays ?? PAT_DEFAULT_EXPIRES_IN_DAYS),
+          }),
+          revokedAt: null,
+        },
+        "pat:create",
+      );
+      await insertOne(ctx.db, apiTokenTable, row);
+      return { isSuccess: true, data: { id, token: raw, prefix } };
+    },
+  });
+}

package/packages/bundled-features/src/personal-access-tokens/handlers/list.query.ts

@@ -0,0 +1,117 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { definePagedQueryHandler, MAX_LIST_LIMIT } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { decryptStoredPii } from "../../shared/index.js";
+import { isExpiredAt } from "../expiry.js";
+import { apiTokenTable } from "../schema/api-token.js";
+
+// `sort` arrives raw from the client's query string. selectMany's orderBy has
+// no column-existence check — an unrecognised field just gets snake_cased and
+// quoted as-is (bun-db/query.ts columnOf) — so this allowlist is what stops a
+// client sorting by tokenHash or any other non-exposed column.
+const SORTABLE_COLUMNS = ["id", "name", "createdAt", "expiresAt", "revokedAt"] as const;
+type SortableColumn = (typeof SORTABLE_COLUMNS)[number];
+
+function isSortableColumn(value: string): value is SortableColumn {
+  return (SORTABLE_COLUMNS as readonly string[]).includes(value);
+}
+
+type PatStatus = "active" | "revoked" | "expired";
+
+function tokenStatus(row: {
+  revokedAt: unknown;
+  expiresAt: { epochMilliseconds: number } | null;
+}): PatStatus {
+  if (row.revokedAt !== null) return "revoked";
+  if (isExpiredAt(row.expiresAt)) return "expired";
+  return "active";
+}
+
+function parseScopeNames(raw: string): string[] {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((s): s is string => typeof s === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+// The caller's own tokens — metadata only, never the hash or plaintext.
+// Includes revoked/expired rows so the UI can show history; `prefix` is the
+// only fragment of the secret ever exposed.
+export const listPatQuery = definePagedQueryHandler({
+  name: "mine",
+  schema: z.object({
+    limit: z.number().int().nonnegative().max(MAX_LIST_LIMIT).optional(),
+    sort: z.string().optional(),
+    sortDirection: z.enum(["asc", "desc"]).optional(),
+  }),
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user lists only their own personal access tokens; the query " +
+        "filters apiTokenTable by the caller's own userId",
+    },
+  },
+  description:
+    "Lists the calling user's personal access tokens with metadata only (name, key prefix, scopes, computed status, created/expiry/revoked timestamps, including revoked ones) and never the token secret.",
+  outputSchema: z.object({
+    rows: z.array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        prefix: z.string(),
+        scopes: z.array(z.string()),
+        status: z.enum(["active", "revoked", "expired"]),
+        createdAt: z.unknown(),
+        expiresAt: z.unknown(),
+        revokedAt: z.unknown(),
+      }),
+    ),
+    nextCursor: z.string().nullable(),
+  }),
+  handler: async (query, ctx) => {
+    const requestedSort = query.payload.sort;
+    const sortColumn: SortableColumn =
+      requestedSort !== undefined && isSortableColumn(requestedSort) ? requestedSort : "createdAt";
+    const rows = await selectMany<{
+      id: string;
+      name: string;
+      prefix: string;
+      scopes: string;
+      createdAt: unknown;
+      expiresAt: { epochMilliseconds: number } | null;
+      revokedAt: unknown;
+    }>(
+      ctx.db,
+      apiTokenTable,
+      { userId: query.user.id },
+      {
+        // `id` as a tie-breaker keeps row order (and, with `limit` set, row
+        // selection) deterministic across identical requests — sortColumn
+        // alone isn't unique (e.g. many NULL revokedAt, or equal timestamps).
+        orderBy:
+          sortColumn === "id"
+            ? { col: "id", direction: query.payload.sortDirection ?? "desc" }
+            : [
+                { col: sortColumn, direction: query.payload.sortDirection ?? "desc" },
+                { col: "id", direction: "asc" },
+              ],
+        ...(query.payload.limit !== undefined && { limit: query.payload.limit }),
+      },
+    );
+    const decryptedRows = await Promise.all(
+      rows.map(async (r) => ({
+        id: r.id,
+        name: await decryptStoredPii(r.name, "name", "pat:list"),
+        prefix: r.prefix,
+        scopes: parseScopeNames(r.scopes),
+        status: tokenStatus(r),
+        createdAt: r.createdAt,
+        expiresAt: r.expiresAt,
+        revokedAt: r.revokedAt,
+      })),
+    );
+    return { rows: decryptedRows, nextCursor: null };
+  },
+});

package/packages/bundled-features/src/personal-access-tokens/handlers/revoke.write.ts

@@ -0,0 +1,62 @@
+import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { Temporal } from "temporal-polyfill";
+import * as z from "zod";
+import { API_TOKEN_ENTITY_NAME, PatErrors } from "../constants.js";
+import { PAT_REVOKED_AGGREGATE_TYPE, PAT_REVOKED_EVENT_QN } from "../pat-revoked-event.js";
+import { apiTokenTable } from "../schema/api-token.js";
+
+// Revoke one of the caller's own tokens. Ownership is enforced in the WHERE
+// (userId = caller), so a caller can't revoke another user's token and a miss
+// is a uniform ownership error with no existence oracle. isNull(revokedAt)
+// keeps a double-revoke from overwriting the original timestamp.
+export const revokePatWrite = defineWriteHandler({
+  name: "revoke",
+  schema: z.object({ id: z.uuid() }),
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user revokes only their own personal access token; ownership " +
+        "is enforced in the WHERE (userId = caller)",
+    },
+  },
+  description:
+    "Permanently revokes one of the caller's own personal access tokens so it stops authenticating; use it when a token leaked or is no longer needed.",
+  agent: { risk: "high" },
+  handler: async (event, ctx) => {
+    const updated = await updateMany(
+      ctx.db,
+      apiTokenTable,
+      { revokedAt: Temporal.Now.instant() },
+      { id: event.payload.id, userId: event.user.id, revokedAt: null },
+    );
+    if (updated.length > 0) {
+      // Lightweight append alongside the direct-write above, mirroring
+      // sessions' revoke.write.ts. NOT a lifecycle event for
+      // store_api_tokens (that table stays an unmanaged direct-write store,
+      // see feature.ts). Without this, the access-invalidation consumer
+      // never hears about the revoke and an already-open SSE stream
+      // authenticated by this exact token survives it.
+      await ctx.unsafeAppendEvent({
+        aggregateId: generateId(),
+        aggregateType: PAT_REVOKED_AGGREGATE_TYPE,
+        type: PAT_REVOKED_EVENT_QN,
+        payload: { userId: event.user.id, tokenIds: [event.payload.id] },
+      });
+      return { isSuccess: true, data: { id: event.payload.id } };
+    }
+    return writeFailure(
+      new UnprocessableError(PatErrors.ownershipDenied, {
+        i18nKey: "errors.ownershipDenied",
+        details: {
+          scope: "entity",
+          entityName: API_TOKEN_ENTITY_NAME,
+          action: "revoke",
+          userId: event.user.id,
+        },
+      }),
+    );
+  },
+});

package/packages/bundled-features/src/personal-access-tokens/hash.ts

@@ -0,0 +1,17 @@
+import { createHash } from "node:crypto";
+import { generateToken, PAT_TOKEN_PREFIX } from "@cosmicdrift/kumiko-framework/api";
+import { PAT_PREFIX_DISPLAY_LENGTH } from "./constants.js";
+
+// A PAT is high-entropy (32 random bytes from generateToken). A single SHA-256
+// is the right hash here: fast on the per-request auth path, and there's no
+// brute-force surface that would justify argon2 (that's for low-entropy
+// passwords). Only the hash is persisted — the plaintext exists once, in the
+// create response.
+export function hashPatToken(rawToken: string): string {
+  return createHash("sha256").update(rawToken).digest("hex");
+}
+
+export function mintPatToken(): { raw: string; hash: string; prefix: string } {
+  const raw = `${PAT_TOKEN_PREFIX}${generateToken()}`;
+  return { raw, hash: hashPatToken(raw), prefix: raw.slice(0, PAT_PREFIX_DISPLAY_LENGTH) };
+}

package/packages/bundled-features/src/personal-access-tokens/i18n.ts

@@ -0,0 +1,64 @@
+import { ACTION_FORM_ENTITY } from "@cosmicdrift/kumiko-framework/ui-types";
+import { fieldLabelKey, fieldOptionLabelKey } from "@cosmicdrift/kumiko-headless";
+import { PAT_FEATURE } from "./constants.js";
+import type { PatScopeConfig } from "./scopes.js";
+
+const mintFieldKey = (field: string): string =>
+  fieldLabelKey(PAT_FEATURE, ACTION_FORM_ENTITY, field);
+const scopeOptionKey = (grant: string): string =>
+  fieldOptionLabelKey(PAT_FEATURE, ACTION_FORM_ENTITY, "scopes", grant);
+
+type LocalizedString = { readonly en: string };
+
+export const PAT_FEATURE_I18N: Readonly<Record<string, LocalizedString>> = {
+  "screen:api-tokens.title": { en: "Personal Access Tokens" },
+  "screen:api-token-create.title": { en: "Create a new token" },
+
+  "pat.list.col.name": { en: "Name" },
+  "pat.list.col.prefix": { en: "Token" },
+  "pat.list.col.scopes": { en: "Scopes" },
+  "pat.list.col.status": { en: "Status" },
+  "pat.list.col.created": { en: "Created" },
+  "pat.list.col.expires": { en: "Expires" },
+  "pat.list.status.active": { en: "Active" },
+  "pat.list.status.revoked": { en: "Revoked" },
+  "pat.list.status.expired": { en: "Expired" },
+  "pat.list.revoke": { en: "Revoke" },
+  "pat.list.revoke.confirm": { en: "Revoke this token? Anything using it will stop working." },
+
+  "pat.create.title": { en: "Create a new token" },
+  "pat.create.submit": { en: "Create token" },
+  "pat.create.reauth": { en: "Confirm your identity" },
+
+  "pat.created.title": { en: "Token created" },
+  "pat.created.token": { en: "Your new token" },
+  "pat.created.hint": { en: "Copy this token now — for security it is shown only this once." },
+  "pat.created.dismiss": { en: "Done" },
+
+  // Field labels for the secretMint's synthesized pseudo-entity
+  // (`__action-form__`, see action-form-shim.ts) — required by the i18n
+  // boot-validator (requiredKeysFromScreen); the declarative renderer
+  // resolves these through the schema payload, not a client component's t().
+  [mintFieldKey("name")]: { en: "Name" },
+  [mintFieldKey("scopes")]: { en: "Per-API access" },
+  [mintFieldKey("expiresInDays")]: { en: "Expires in (days)" },
+  [mintFieldKey("currentPassword")]: { en: "Password (to confirm)" },
+  [mintFieldKey("mfaCode")]: { en: "2FA code (if enabled)" },
+};
+
+// Per-grant-option labels for the mint form's `scopes` multiSelect —
+// "<domain> (read)" / "<domain> (read & write)", matching the wording the
+// former custom screen showed. `def.label` is an app-authored raw display
+// string (not itself an i18n key).
+export function patScopeOptionTranslations(
+  scopes: PatScopeConfig,
+): Readonly<Record<string, LocalizedString>> {
+  const out: Record<string, LocalizedString> = {};
+  for (const [domain, def] of Object.entries(scopes)) {
+    out[scopeOptionKey(`${domain}:read`)] = { en: `${def.label} (read)` };
+    if (def.write && def.write.length > 0) {
+      out[scopeOptionKey(`${domain}:write`)] = { en: `${def.label} (read & write)` };
+    }
+  }
+  return out;
+}

package/packages/bundled-features/src/personal-access-tokens/index.ts

@@ -0,0 +1,43 @@
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { PAT_DEFAULT_RATE_LIMIT, type PatRateLimit } from "./constants.js";
+
+export type { PatRateLimit } from "./constants.js";
+export { PAT_DEFAULT_RATE_LIMIT, PAT_FEATURE, PatHandlers, PatQueries } from "./constants.js";
+export type { BindPatAutoRevokeOnPasswordChange, PersonalAccessTokensOptions } from "./feature.js";
+export {
+  bindPatAutoRevokeOnPasswordChangeFromFeature,
+  createPersonalAccessTokensFeature,
+} from "./feature.js";
+export type { CreatePatOptions, PatMfaVerifyResult } from "./handlers/create.write.js";
+export { hashPatToken, mintPatToken } from "./hash.js";
+export {
+  PAT_REVOKED_AGGREGATE_TYPE,
+  PAT_REVOKED_EVENT_QN,
+  PAT_REVOKED_EVENT_SHORT,
+  type PatRevokedPayload,
+  patRevokedSchema,
+} from "./pat-revoked-event.js";
+export { createPatResolver } from "./resolver.js";
+export { revokeAllPatTokensForUser } from "./revoke-for-user.js";
+export { apiTokenEntity, apiTokenTable } from "./schema/api-token.js";
+export type { PatScopeConfig, PatScopeDef } from "./scopes.js";
+export { expandScopes } from "./scopes.js";
+
+// Reads the per-token rate-limit config off a mounted PAT feature's exports.
+// Falls back to the default when absent. run-prod-app uses this to build the
+// limiter from the same declaration the feature was given.
+export function patRateLimitFromFeature(feature: FeatureDefinition): PatRateLimit {
+  const exports = feature.exports;
+  if (exports && typeof exports === "object" && "rateLimit" in exports) {
+    const { rateLimit } = exports as { rateLimit: unknown };
+    if (
+      rateLimit &&
+      typeof rateLimit === "object" &&
+      "maxRequests" in rateLimit &&
+      "windowMs" in rateLimit
+    ) {
+      return rateLimit as PatRateLimit;
+    }
+  }
+  return PAT_DEFAULT_RATE_LIMIT;
+}

package/packages/bundled-features/src/personal-access-tokens/pat-revoked-event.ts

@@ -0,0 +1,23 @@
+import * as z from "zod";
+
+// Lightweight custom event appended alongside the direct-write updateMany()
+// in revoke.write.ts / revoke-for-user.ts (mirrors sessions'
+// session-revoked-event.ts). apiTokenTable itself stays an unmanaged
+// direct-write store (see feature.ts) — this event is NOT a CRUD/lifecycle
+// event for that table and carries no projection. Its only job is to give
+// the access-invalidation consumer something to LISTEN for, keyed by the
+// affected userId, so a revoked PAT's open SSE stream closes.
+export const PAT_REVOKED_EVENT_SHORT = "pat-revoked" as const;
+export const PAT_REVOKED_EVENT_QN = "personal-access-tokens:event:pat-revoked" as const;
+
+// Own aggregate type, decoupled from apiTokenEntity's implicit
+// "api-token" — each revoke action mints a fresh aggregate id (no
+// predecessor to satisfy, no version_conflict against concurrent revokes).
+export const PAT_REVOKED_AGGREGATE_TYPE = "api-token-revocation" as const;
+
+export const patRevokedSchema = z.object({
+  userId: z.string().min(1),
+  tokenIds: z.array(z.uuid()).min(1),
+});
+
+export type PatRevokedPayload = z.infer<typeof patRevokedSchema>;