@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

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

@@ -0,0 +1,239 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { createInMemoryLoginRateLimiter } from "@cosmicdrift/kumiko-framework/api";
+import { selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher, 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 { authFoundationFeature, resolveTokenVerifier } from "../../auth-foundation";
+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 { 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>;
+
+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 = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      createAuthEmailPasswordFeature(),
+      createSessionsFeature(),
+      createPersonalAccessTokensFeature({ scopes: SCOPES }),
+      authFoundationFeature,
+    ],
+    extraContext: { configResolver: resolver, configEncryption: encryption },
+    authConfig: {
+      membershipQuery: "tenant:query:memberships",
+      loginHandler: AuthHandlers.login,
+      // PAT registers itself as a tokenVerifier provider (auth-foundation)
+      // instead of the app wiring a dedicated patResolver — resolved
+      // generically here, same as run-prod-app/run-dev-app do.
+      tokenVerifier: (raw: string) =>
+        resolveTokenVerifier({ db: stack.db, registry: stack.registry }, 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),
+    },
+  });
+  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);
+  });
+});
+
+describe("PAT with active KMS (#820): token name is userOwned PII", () => {
+  test("create stores ciphertext at rest, list returns the plaintext name", async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    configureBlindIndexKey(Buffer.alloc(32, 7).toString("base64"));
+    try {
+      const actor = await actorFor("kms-pat@example.com");
+      const token = await mintToken(actor);
+
+      const rows = await stack.http.queryOk<Array<{ id: string; name: string }>>(
+        PatQueries.mine,
+        {},
+        actor,
+      );
+      expect(rows[0]?.name).toBe("test");
+
+      const stored = await selectMany<{ name: string }>(stack.db, apiTokenTable, {
+        id: rows[0]?.id,
+      });
+      expect(isPiiCiphertext(stored[0]?.name)).toBe(true);
+
+      // Der Token selbst funktioniert weiter (resolver liest tokenHash, nie name).
+      const res = await h.authedPost("/api/query", token, { type: PatQueries.mine, payload: {} });
+      expect(res.status).toBe(200);
+    } finally {
+      resetPiiSubjectKmsForTests();
+      resetBlindIndexKeyForTests();
+    }
+  });
+});

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,105 @@
+import {
+  type AuthProviderPlugin,
+  EXT_TOKEN_VERIFIER,
+} from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { PAT_TOKEN_PREFIX } from "@cosmicdrift/kumiko-framework/api";
+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 { PAT_FEATURE_I18N } from "./i18n";
+import { createPatResolver } from "./resolver";
+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;
+  /** 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 };
+};
+
+export type PatFeatureExports = {
+  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 / 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(buildEntityTableMeta("api-token", apiTokenEntity, { source: "unmanaged" }), {
+      reason: "read_side.api_tokens_direct_write",
+      // create.write encrypts `name` via encryptForDirectWrite (#820).
+      piiEncryptedOnWrite: true,
+    });
+
+    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 },
+    });
+    r.translations({ keys: PAT_FEATURE_I18N });
+
+    // 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,
+      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,47 @@
+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 { encryptForDirectWrite } from "../../shared";
+import { mintPatToken } from "../hash";
+import { apiTokenEntity, 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();
+    const row = await encryptForDirectWrite(
+      apiTokenEntity,
+      {
+        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,
+      },
+      "pat:create",
+    );
+    await insertOne(ctx.db, apiTokenTable, row);
+    return { isSuccess: true, data: { id, token: raw, prefix } };
+  },
+});

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

@@ -0,0 +1,50 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { decryptStoredPii } from "../../shared";
+import { apiTokenTable } from "../schema/api-token";
+
+// 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 = defineQueryHandler({
+  name: "mine",
+  schema: z.object({}),
+  access: { openToAll: true },
+  handler: async (query, ctx) => {
+    const rows = await selectMany<{
+      id: string;
+      name: string;
+      prefix: string;
+      scopes: string;
+      createdAt: unknown;
+      expiresAt: unknown;
+      revokedAt: unknown;
+    }>(
+      ctx.db,
+      apiTokenTable,
+      { userId: query.user.id },
+      { orderBy: { col: "createdAt", direction: "desc" } },
+    );
+    return Promise.all(
+      rows.map(async (r) => ({
+        id: r.id,
+        name: await decryptStoredPii(r.name, "name", "pat:list"),
+        prefix: r.prefix,
+        scopes: parseScopeNames(r.scopes),
+        createdAt: r.createdAt,
+        expiresAt: r.expiresAt,
+        revokedAt: r.revokedAt,
+      })),
+    );
+  },
+});
+
+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 [];
+  }
+}

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

@@ -0,0 +1,37 @@
+import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { Temporal } from "temporal-polyfill";
+import { z } from "zod";
+import { PatErrors } from "../constants";
+import { apiTokenTable } from "../schema/api-token";
+
+// 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: true },
+  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) return { isSuccess: true, data: { id: event.payload.id } };
+    return writeFailure(
+      new UnprocessableError(PatErrors.ownershipDenied, {
+        i18nKey: "errors.ownershipDenied",
+        details: {
+          scope: "entity",
+          entityName: "api-token",
+          action: "revoke",
+          userId: event.user.id,
+        },
+      }),
+    );
+  },
+});

package/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";
+
+// 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/src/personal-access-tokens/i18n.ts

@@ -0,0 +1,5 @@
+type LocalizedString = { readonly de: string; readonly en: string };
+
+export const PAT_FEATURE_I18N: Readonly<Record<string, LocalizedString>> = {
+  "screen:api-tokens.title": { de: "Personal Access Tokens", en: "Personal Access Tokens" },
+};

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

@@ -0,0 +1,31 @@
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { PAT_DEFAULT_RATE_LIMIT, type PatRateLimit } from "./constants";
+
+export type { PatRateLimit } from "./constants";
+export { PAT_DEFAULT_RATE_LIMIT, PAT_FEATURE, PatHandlers, PatQueries } from "./constants";
+export type { PersonalAccessTokensOptions } from "./feature";
+export { createPersonalAccessTokensFeature } from "./feature";
+export { hashPatToken, mintPatToken } from "./hash";
+export { createPatResolver } from "./resolver";
+export { apiTokenEntity, apiTokenTable } from "./schema/api-token";
+export type { PatScopeConfig, PatScopeDef } from "./scopes";
+export { expandScopes } from "./scopes";
+
+// 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;
+}