@cosmicdrift/kumiko-bundled-features 0.105.2 → 0.109.0

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

@@ -0,0 +1,47 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+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 rows.map((r) => ({
+      id: r.id,
+      name: r.name,
+      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/index.ts

@@ -0,0 +1,45 @@
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { PAT_DEFAULT_RATE_LIMIT, type PatRateLimit } from "./constants";
+import type { PatScopeConfig } from "./scopes";
+
+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 scope catalog off a mounted PAT feature's exports (set from the
+// setup-callback return). run-prod-app uses this to build the resolver from the
+// same config the handlers were given. Returns {} for a non-PAT / malformed
+// definition — the caller has already matched on feature.name.
+export function patScopesFromFeature(feature: FeatureDefinition): PatScopeConfig {
+  const exports = feature.exports;
+  if (exports && typeof exports === "object" && "scopes" in exports) {
+    const { scopes } = exports as { scopes: unknown };
+    if (scopes && typeof scopes === "object") return scopes as PatScopeConfig;
+  }
+  return {};
+}
+
+// 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/src/personal-access-tokens/resolver.ts

@@ -0,0 +1,58 @@
+import type { PatResolver } from "@cosmicdrift/kumiko-framework/api";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "temporal-polyfill";
+import { hashPatToken } from "./hash";
+import { resolvePatRoles } from "./roles";
+import { apiTokenTable } from "./schema/api-token";
+import { expandScopes, type PatScopeConfig } from "./scopes";
+
+// Hot-path resolver — raw-DB like session-callbacks (a dispatcher roundtrip on
+// every request buys nothing here). Hash the bearer token, point-read the row,
+// reject revoked/expired, resolve LIVE roles, expand granted scopes into
+// allowedQns. Any failure returns null so the middleware answers a uniform 401
+// with no oracle about which check failed.
+export function createPatResolver(opts: {
+  readonly db: DbConnection;
+  readonly scopes: PatScopeConfig;
+}): PatResolver {
+  const { db, scopes } = opts;
+  return async (rawToken: string): Promise<SessionUser | null> => {
+    const row = await fetchOne<{
+      id: string;
+      userId: string;
+      tenantId: string;
+      scopes: string;
+      revokedAt: unknown;
+      expiresAt: { epochMilliseconds: number } | null;
+    }>(db, apiTokenTable, { tokenHash: hashPatToken(rawToken) });
+    if (!row) return null;
+    if (row.revokedAt !== null) return null;
+    if (
+      row.expiresAt &&
+      row.expiresAt.epochMilliseconds <= Temporal.Now.instant().epochMilliseconds
+    ) {
+      return null;
+    }
+    const roles = await resolvePatRoles(db, row.userId, row.tenantId);
+    if (!roles) return null;
+    const granted = parseScopeNames(row.scopes);
+    return {
+      id: row.userId,
+      // @cast-boundary db-row → branded id: stored from a valid SessionUser.tenantId at create
+      tenantId: row.tenantId as TenantId,
+      roles,
+      pat: { tokenId: row.id, scopes: granted, allowedQns: expandScopes(scopes, granted) },
+    };
+  };
+}
+
+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/roles.ts

@@ -0,0 +1,29 @@
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { stripForbiddenMembershipRoles } from "@cosmicdrift/kumiko-framework/engine";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+import { tenantMembershipsTable } from "../tenant";
+import { userTable } from "../user";
+
+// Live role resolution for a (userId, tenantId), mirroring login.write.ts:
+// global roles (users.roles) ∪ tenant-membership roles (forbidden roles
+// stripped). Resolved fresh on every PAT request — a snapshot baked at mint
+// time would keep a since-revoked admin role for the token's whole (months-long)
+// life. Returns null when the user has no membership in that tenant: removed
+// from the tenant → the PAT stops authenticating there.
+export async function resolvePatRoles(
+  db: DbConnection,
+  userId: string,
+  tenantId: string,
+): Promise<readonly string[] | null> {
+  const memberships = await selectMany<{ roles: string }>(db, tenantMembershipsTable, {
+    userId,
+    tenantId,
+  });
+  const membership = memberships[0];
+  if (!membership) return null;
+  const userRow = await fetchOne<{ roles: string | null }>(db, userTable, { id: userId });
+  const globalRoles = parseRoles(userRow?.roles ?? null);
+  const membershipRoles = stripForbiddenMembershipRoles(parseRoles(membership.roles));
+  return [...new Set([...globalRoles, ...membershipRoles])];
+}

package/src/personal-access-tokens/schema/api-token.ts

@@ -0,0 +1,56 @@
+import { buildEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createEntity,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// One row per Personal Access Token. Like read_user_sessions this is a
+// direct-write store (r.unmanagedTable): the create/revoke handlers write it and
+// the resolver point-reads it on the hot auth path. `tokenHash` is the SHA-256
+// of the plaintext (never the plaintext); the unique index on it makes the
+// resolver a single point-read. All columns are privileged-write so no user
+// request can forge ownership/scope/hash by poking a field directly — the
+// handlers mutate them via ctx.db inside the pipeline.
+export const apiTokenEntity = createEntity({
+  table: "read_api_tokens",
+  // No softDelete: revocation is its own lifecycle (revokedAt timestamp), and
+  // we keep revoked rows for the "your tokens" audit list.
+  softDelete: false,
+  fields: {
+    userId: createTextField({
+      required: true,
+      maxLength: 36,
+      access: { write: access.privileged },
+    }),
+    tenantId: createTextField({
+      required: true,
+      maxLength: 36,
+      access: { write: access.privileged },
+    }),
+    name: createTextField({ required: true, maxLength: 120, access: { write: access.privileged } }),
+    tokenHash: createTextField({
+      required: true,
+      maxLength: 64,
+      access: { write: access.privileged },
+    }),
+    prefix: createTextField({
+      required: true,
+      maxLength: 16,
+      access: { write: access.privileged },
+    }),
+    // JSON-encoded string[] of granted scope names — mirrors the roles-column
+    // convention (parseRoles-style text); the resolver JSON.parses it.
+    scopes: createTextField({ required: true, access: { write: access.privileged } }),
+    createdAt: createTimestampField({ required: true, access: { write: access.privileged } }),
+    expiresAt: createTimestampField({ access: { write: access.privileged } }),
+    revokedAt: createTimestampField({ access: { write: access.privileged } }),
+  },
+  indexes: [{ unique: true, columns: ["tokenHash"], name: "read_api_tokens_hash_unique" }],
+});
+
+// buildEntityTableMeta (not buildEntityTable): this is a direct-write store, so
+// the table must be a WritableTable (post ES-write-brand #742) — same as
+// sessions' userSessionTable. buildEntityTable is branded executor-only.
+export const apiTokenTable = buildEntityTableMeta("api-token", apiTokenEntity);

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

@@ -0,0 +1,43 @@
+// @runtime client
+// Pure scope helpers + types — client-marked so the web screen (web/) may import
+// parseGrant without pulling the feature's server runtime barrel.
+//
+// App-declared scopes — two axes, like GitHub fine-grained PATs: WHICH API
+// (the domain, keyed here) × the permission LEVEL (read vs read+write). Each
+// domain declares its read-QN globs and (optionally) its write-QN globs. A
+// domain may span features (e.g. a "miete" domain granting ledger + folders).
+export type PatScopeDef = {
+  readonly label: string;
+  readonly read: readonly string[];
+  // Omit for a read-only domain — the UI then offers only "no access" / "read".
+  readonly write?: readonly string[];
+};
+
+export type PatScopeConfig = Readonly<Record<string, PatScopeDef>>;
+
+export type PatLevel = "read" | "write";
+
+// A granted scope is the string "<domain>:<level>" (e.g. "credit:write"). The
+// domain key never contains a colon, so split on the LAST one.
+export function parseGrant(grant: string): { domain: string; level: string } | null {
+  const idx = grant.lastIndexOf(":");
+  if (idx <= 0) return null;
+  return { domain: grant.slice(0, idx), level: grant.slice(idx + 1) };
+}
+
+// Expand granted "<domain>:<level>" entries into the union of QN globs: read
+// always grants the read QNs; write additionally grants the write QNs. Unknown
+// domains contribute nothing (fail-closed — a scope dropped from config after a
+// token was minted silently loses that capability).
+export function expandScopes(config: PatScopeConfig, granted: readonly string[]): string[] {
+  const out = new Set<string>();
+  for (const grant of granted) {
+    const parsed = parseGrant(grant);
+    if (!parsed) continue;
+    const def = config[parsed.domain];
+    if (!def) continue;
+    for (const q of def.read) out.add(q);
+    if (parsed.level === "write") for (const q of def.write ?? []) out.add(q);
+  }
+  return [...out];
+}

package/src/personal-access-tokens/web/client-plugin.tsx

@@ -0,0 +1,29 @@
+// @runtime client
+// Client-feature factory for personal-access-tokens. Ships the PatTokensScreen
+// (mapped to the "api-tokens" screen id) + default translations. Apps mount it
+// in createKumikoApp({ clientFeatures: [personalAccessTokensClient()] }); the
+// server registers the screen dormant (r.screen) and the app places it via
+// r.nav.
+
+import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { PAT_FEATURE, PAT_SCREEN_ID } from "../constants";
+import { defaultTranslations } from "./i18n";
+import { PatTokensScreen } from "./pat-tokens-screen";
+
+export type PersonalAccessTokensClientOptions = {
+  /** Key-wise overrides over the default bundles (de/en). */
+  readonly translations?: TranslationsByLocale;
+};
+
+export function personalAccessTokensClient(
+  options?: PersonalAccessTokensClientOptions,
+): ClientFeatureDefinition {
+  return {
+    name: PAT_FEATURE,
+    translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
+    components: {
+      [PAT_SCREEN_ID]: PatTokensScreen,
+    },
+  };
+}

package/src/personal-access-tokens/web/i18n.ts

@@ -0,0 +1,69 @@
+// @runtime client
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const defaultTranslations: TranslationsByLocale = {
+  de: {
+    "pat.title": "Personal Access Tokens",
+    "pat.create.title": "Neuen Token erstellen",
+    "pat.create.subtitle":
+      "Wähle Berechtigungen und eine Gültigkeit. Der Token wird nur einmal angezeigt.",
+    "pat.create.name": "Name",
+    "pat.create.namePlaceholder": "z. B. CLI-Automatisierung",
+    "pat.create.scopes": "Zugriff pro Bereich",
+    "pat.level.none": "Kein Zugriff",
+    "pat.level.read": "Lesen",
+    "pat.level.write": "Lesen & Schreiben",
+    "pat.create.expiry": "Gültig bis",
+    "pat.create.submit": "Token erstellen",
+    "pat.create.needName": "Bitte einen Namen vergeben.",
+    "pat.create.needScope": "Bitte mindestens eine Berechtigung wählen.",
+    "pat.expiry.30d": "30 Tage",
+    "pat.expiry.90d": "90 Tage",
+    "pat.expiry.1y": "1 Jahr",
+    "pat.expiry.never": "Unbegrenzt",
+    "pat.created.hint":
+      "Kopiere diesen Token jetzt — er wird aus Sicherheitsgründen nur dieses eine Mal angezeigt.",
+    "pat.created.copy": "Kopieren",
+    "pat.created.copied": "Kopiert ✓",
+    "pat.created.dismiss": "Fertig",
+    "pat.list.title": "Deine Tokens",
+    "pat.list.empty": "Noch keine Tokens.",
+    "pat.list.revoke": "Widerrufen",
+    "pat.list.revoked": "Widerrufen",
+    "pat.list.validUntil": "Gültig bis {date}",
+    "pat.list.neverExpires": "Unbegrenzt gültig",
+    "pat.list.created": "Erstellt {date}",
+    "pat.error.generic": "Aktion fehlgeschlagen.",
+  },
+  en: {
+    "pat.title": "Personal Access Tokens",
+    "pat.create.title": "Create a new token",
+    "pat.create.subtitle": "Pick permissions and an expiration. The token is shown only once.",
+    "pat.create.name": "Name",
+    "pat.create.namePlaceholder": "e.g. CLI automation",
+    "pat.create.scopes": "Per-API access",
+    "pat.level.none": "No access",
+    "pat.level.read": "Read",
+    "pat.level.write": "Read & write",
+    "pat.create.expiry": "Expiration",
+    "pat.create.submit": "Create token",
+    "pat.create.needName": "Please enter a name.",
+    "pat.create.needScope": "Please select at least one permission.",
+    "pat.expiry.30d": "30 days",
+    "pat.expiry.90d": "90 days",
+    "pat.expiry.1y": "1 year",
+    "pat.expiry.never": "No expiration",
+    "pat.created.hint": "Copy this token now — for security it is shown only this once.",
+    "pat.created.copy": "Copy",
+    "pat.created.copied": "Copied ✓",
+    "pat.created.dismiss": "Done",
+    "pat.list.title": "Your tokens",
+    "pat.list.empty": "No tokens yet.",
+    "pat.list.revoke": "Revoke",
+    "pat.list.revoked": "Revoked",
+    "pat.list.validUntil": "Valid until {date}",
+    "pat.list.neverExpires": "Never expires",
+    "pat.list.created": "Created {date}",
+    "pat.error.generic": "Action failed.",
+  },
+};

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

@@ -0,0 +1,7 @@
+// @runtime client
+export {
+  type PersonalAccessTokensClientOptions,
+  personalAccessTokensClient,
+} from "./client-plugin";
+export { defaultTranslations } from "./i18n";
+export { PatTokensScreen } from "./pat-tokens-screen";