@fuzdev/fuz_app 0.107.0 → 0.109.0

package/dist/http/CLAUDE.md

@@ -29,7 +29,7 @@ effects, see ../../../docs/architecture.md.
 - `http/jsonrpc_errors.ts` — `ThrownJsonrpcError`, `jsonrpc_errors` throwers, HTTP-status mappings.
 - `http/jsonrpc_helpers.ts` — message builders, type guards, input/result normalizers.
 - `http/common_routes.ts` — health check + readiness probe (`/ready` schema-drift deploy gate) + authenticated server-status + surface route specs.
-- `http/db_routes.ts` — generic keeper-only table browser route specs (public schema).
+- `http/db_routes.ts` — allowlist-gated keeper-only table browser route specs (`public` schema, minus the `NON_BROWSABLE_TABLES` credential floor).
 - `http/pending_effects.ts` — `emit_after_commit` + `dispatch_with_post_commit_rollback` (the shared rollback-discard wrapper both dispatch sites use) + `flush_pending_effects` + `flush_post_commit_effects` + `EmitAfterCommitContext`.
 
 ## Route Spec System
@@ -210,7 +210,7 @@ confirmation.
 - **Bootstrap**: `ERROR_ALREADY_BOOTSTRAPPED`, `ERROR_TOKEN_FILE_MISSING`
 - **Signup/invites**: `ERROR_NO_MATCHING_INVITE`, `ERROR_SIGNUP_CONFLICT`, `ERROR_INVITE_NOT_FOUND`, `ERROR_INVITE_DUPLICATE`, `ERROR_INVITE_ACCOUNT_EXISTS_USERNAME`, `ERROR_INVITE_ACCOUNT_EXISTS_EMAIL`
 - **Admin**: `ERROR_ROLE_NOT_WEB_GRANTABLE`, `ERROR_ROLE_GRANT_NOT_FOUND`, `ERROR_INVALID_EVENT_TYPE`
-- **DB browser**: `ERROR_FOREIGN_KEY_VIOLATION`, `ERROR_TABLE_NOT_FOUND`, `ERROR_TABLE_NO_PRIMARY_KEY`, `ERROR_ROW_NOT_FOUND`
+- **DB browser**: `ERROR_FOREIGN_KEY_VIOLATION`, `ERROR_TABLE_NOT_FOUND`, `ERROR_TABLE_NO_PRIMARY_KEY`, `ERROR_TABLE_NOT_DELETABLE`, `ERROR_ROW_NOT_FOUND`
 
 ## Schema Helpers
 
@@ -485,36 +485,96 @@ auth-domain dependencies:
 Auth-aware variants (account status, bootstrap status) live in `auth/` —
 `http/common_routes.ts` stays generic.
 
-## DB Routes (Generic Browser)
+## DB Routes (Allowlisted Browser)
 
 `http/db_routes.ts` creates keeper-only route specs for administering the
 `public` schema via `information_schema`. Wired by consumers that want a
-generic table browser; the factory is domain-agnostic.
-
-`create_db_route_specs({db_type, db_name, extra_stats?, log?})`:
-
-- `GET /health` — connected probe + table count + optional `extra_stats(db)`. Returns `{connected: false}` at 503 on failure
-- `GET /tables` — list public tables with row counts
-- `GET /tables/:name` — columns + rows (paginated via `?offset`/`?limit`, limit clamped to `[1, 1000]` with default 100) + total count + primary key
-- `DELETE /tables/:name/rows/:id` — delete by PK. Returns 400 if table has no PK (`ERROR_TABLE_NO_PRIMARY_KEY`), 404 if row missing (`ERROR_ROW_NOT_FOUND`) or table missing (`ERROR_TABLE_NOT_FOUND`), 409 on FK violation (pg error code `23503`)
+table browser; the factory is domain-agnostic.
+
+`create_db_route_specs(deps, {db_type, db_name, browsable_tables, extra_stats?, log?, non_deletable_tables?})` —
+`deps` is `DbRouteDeps`, a structural `audit` slice of `AppDeps` declared in
+`http/db_routes.ts` so this directory stays auth-free (`ctx.deps` satisfies it):
+
+- `GET /health` — connected probe + table count (schema-wide by design — a did-migrations-run diagnostic) + optional `extra_stats(db)`. Returns `{connected: false}` at 503 on failure
+- `GET /tables` — list browsable tables with row counts
+- `GET /tables/:name` — columns + rows (paginated via `?offset`/`?limit`, limit validated to `[1, 1000]` with default 100; bytea values come back as `<N bytes>` placeholders, NULL stays NULL, column metadata untouched) + total count + `primary_key` (the single PK column, or `null` when the table has none or a composite one) + `deletable` (whether the row-`DELETE` will accept this table at all — see below)
+- `DELETE /tables/:name/rows/:id` — delete by PK, compared typed as `"<pk>" = $1` (twinning the Rust spine — the untyped text-format param makes PG coerce the id with the PK type's input function, so the delete index-scans and follows the column type's semantics; an uncoercible id — 22P02/22003 — is the same clean 404 as a typed miss). `RETURNING "<pk>"::text` feeds the audit trail the row's canonical PK rendering. Returns 400 if the table is excluded by policy (`ERROR_TABLE_NOT_DELETABLE`) or has no single-column PK (`ERROR_TABLE_NO_PRIMARY_KEY`), 404 if row missing (`ERROR_ROW_NOT_FOUND`) or table missing/unbrowsable (`ERROR_TABLE_NOT_FOUND`), 409 on a referencing-row refusal (pg error `23503` foreign_key_violation, or `23001` restrict_violation — PG 18+ raises the latter for `ON DELETE RESTRICT`)
+
+**The allowlist gates everything.** `DbRouteOptions.browsable_tables` is
+required with no "all" escape hatch — the table list shows only listed tables,
+and detail/`DELETE` on an unlisted table answer exactly like a table that
+doesn't exist (404 `ERROR_TABLE_NOT_FOUND`, byte-identical masking). The
+credential floor `NON_BROWSABLE_TABLES` (`account` — the argon2 hash corpus,
+`auth_session` / `api_token` — credential digests, `bootstrap_lock`) is
+subtracted from the allowlist even when a consumer names those tables. The
+browse/delete transactions run under `SET LOCAL statement_timeout`
+(`DB_ADMIN_STATEMENT_TIMEOUT_MS`) so no single statement outlives the bound
+(per statement, not per request — the table listing's per-table `COUNT(*)`
+loop can still take several in sequence).
+
+**Single-column primary keys only.** The `DELETE` filters on one column
+(`WHERE "<pk>" = $1`), which is correct only when the primary key _is_
+that one column. `query_primary_key_columns` returns every PK column in
+`ordinal_position` order, and the route proceeds only at length exactly 1 — a
+composite key (a single-column filter would match every row sharing that
+column's value and silently over-delete) and an absent key both refuse with 400
+and delete nothing. `GET /tables/:name` reports `primary_key: null` in the same
+two cases, so the UI (`ui/table_state.svelte.ts`) disables delete without firing
+a request. Twin of the Rust spine's `fuz_db_admin` router.
+
+**Some tables are never row-deletable.** `NON_DELETABLE_TABLES` — `audit_log`,
+`bootstrap_lock`, `app_settings`, `schema_version` — refuses the `DELETE` with
+400 `ERROR_TABLE_NOT_DELETABLE` before the key-shape check, because a generic
+storage endpoint has no business deleting a row whose meaning lives in the
+domain layer. `audit_log` is the sharpest: it is both the trail and, since
+`realtime/sse_auth_guard.ts` and the WS auth guard close live streams by
+listening to audit events, part of how revocation propagates. The three
+singletons each fail differently on deletion — `bootstrap_lock` leaves
+`check_bootstrap_status` advertising a window `bootstrap_account.ts` then always
+refuses, `app_settings` makes every settings read throw, `schema_version` is the
+migration tracker (composite-keyed, so already refused — named here so the
+protection survives a key-shape change). Consumers add their own via
+`DbRouteOptions.non_deletable_tables`, which is unioned with the builtin set and
+never replaces it.
+
+`GET /tables/:name` reports `deletable` = exactly what the `DELETE` will accept
+(single-column PK **and** not excluded), so a client hides the affordance
+instead of discovering the refusal — `ui/table_state.svelte.ts` gates on
+`can_delete`. `primary_key` stays a truthful report of the key shape; a policy
+exclusion must not masquerade as one.
+
+**Every successful row delete is audited.** The `DELETE` handler defers a
+`deps.audit` emit through `emit_after_commit`, so the pool-routed row lands
+iff the delete's transaction commits — the success-only trail can't claim a
+delete that failed at COMMIT (the Rust twin commits before emitting for the
+same reason). Account-grain attribution (the browser's gate is account-grain,
+so no actor is claimed), metadata `{table, pk_column, id}`. Refusals emit
+nothing. The completeness gate covers the event via the
+`db_routes.db.test.ts` emission tests (excluded-with-justification in
+`testing/audit_completeness.ts`). Twinned by `fuz_db_admin`'s emission on the
+Rust spine.
 
 All four routes use the keeper auth shape (`{account: 'required', actor: 'required', roles: ['keeper'], credential_types: ['daemon_token']}`).
 Param schemas use `VALID_SQL_IDENTIFIER` regex, and every table name gets
 `assert_valid_sql_identifier()` before string-interpolating into SQL —
 the identifier validation is the only reason the interpolation is safe.
 
-**Do not widen the auth on these specs.** They serve paginated rows of any
-`public` table — `account.password_hash`, `auth_session`, `api_token` — plus
-row `DELETE`. `credential_types: ['daemon_token']` is what keeps every bearer
-credential out, and it's why the specs need no `auth.required_scope`: a daemon
-token resolves to `full` by construction, so no narrowed token can reach them
-(see ../../../docs/security.md §Token scoping). Re-auth them to a role a bearer
+**Do not widen the auth on these specs.** They serve paginated rows of every
+browsable table plus row `DELETE` — the credential tables sit behind the
+`NON_BROWSABLE_TABLES` floor, but browsable rows can still carry secrets in
+data columns (a consumer's `cell.data` is the live example).
+`credential_types: ['daemon_token']` is what keeps every bearer credential
+out, and it's why the specs need no `auth.required_scope`: a daemon token
+resolves to `full` by construction, so no narrowed token can reach them (see
+../../../docs/security.md §Token scoping). Re-auth them to a role a bearer
 satisfies and both controls are gone at once — the token's scope stops
 applying and the credential gate stops firing. A consumer that does this owns
 the surface census for it.
 
 Interfaces exported for consumer use: `TableInfo`, `TableWithCount`,
-`PrimaryKeyInfo`, `ColumnInfo`, `DbRouteOptions`.
+`PrimaryKeyInfo`, `ColumnInfo`, `DbRouteDeps`, `DbRouteOptions`,
+`NON_DELETABLE_TABLES`, `NON_BROWSABLE_TABLES`, `DB_TABLE_ROWS_DEFAULT_LIMIT`,
+`DB_TABLE_ROWS_LIMIT_MAX`, `DB_ADMIN_STATEMENT_TIMEOUT_MS`.
 
 ## Cross-Module Notes
 

package/dist/http/db_routes.d.ts

@@ -1,12 +1,16 @@
 /**
  * API route specs for database administration.
  *
- * Generic PostgreSQL table browser using `information_schema`.
- * Provides: list tables, view columns/rows (paginated), delete rows by PK, health check.
+ * Allowlist-gated PostgreSQL table browser using `information_schema` —
+ * consumers declare `browsable_tables` and the credential floor
+ * (`NON_BROWSABLE_TABLES`) is always subtracted. Provides: list tables, view
+ * columns/rows (paginated, bytea values placeholdered), delete rows by PK
+ * (audited as `db_admin_row_delete`), health check.
  *
  * @module
  */
 import type { Logger } from '@fuzdev/fuz_util/log.ts';
+import type { Uuid } from '@fuzdev/fuz_util/id.ts';
 import type { Db, DbType } from '../db/db.js';
 import { type RouteSpec } from './route_spec.js';
 /**
@@ -40,19 +44,108 @@ export interface ColumnInfo {
 export declare const DB_TABLE_ROWS_DEFAULT_LIMIT = 100;
 /** Maximum page size for `GET /tables/:name` rows. */
 export declare const DB_TABLE_ROWS_LIMIT_MAX = 1000;
+/**
+ * Per-statement timeout applied (`SET LOCAL statement_timeout`) inside the
+ * table-list, table-detail, and row-`DELETE` transactions — no single
+ * statement outlives it. (Per statement, not per request: the table listing's
+ * one-`COUNT(*)`-per-table loop can still take several in sequence.)
+ * Milliseconds.
+ */
+export declare const DB_ADMIN_STATEMENT_TIMEOUT_MS = 5000;
+/**
+ * Tables the browser can never expose, whatever `browsable_tables` names —
+ * the credential floor, subtracted from the consumer's allowlist and not
+ * overridable:
+ *
+ * - `account` — the one surface that would return the argon2 password-hash
+ *   corpus in bulk (every other read path excludes the hash by projection).
+ * - `auth_session` / `api_token` — credential digests plus per-account
+ *   session/token metadata.
+ * - `bootstrap_lock` — the first-admin gate; its row is load-bearing state,
+ *   not content.
+ *
+ * A table on the floor answers exactly like one that doesn't exist (404
+ * `table_not_found`) so the browser doesn't confirm its presence.
+ */
+export declare const NON_BROWSABLE_TABLES: ReadonlyArray<string>;
+/**
+ * Tables this endpoint refuses to delete rows from, whatever their key shape.
+ *
+ * Two kinds, one rule — a generic storage endpoint has no business deleting a
+ * row whose meaning lives in the domain layer:
+ *
+ * - `audit_log` — the trail and the tamper path would otherwise be the same
+ *   surface. It is also how revocation propagates: `realtime/sse_auth_guard.ts`
+ *   and the WS auth guard close live streams by listening to audit events, so a
+ *   raw row delete here is invisible to them.
+ *   `bootstrap_lock` — deleting the singleton leaves `check_bootstrap_status`
+ *   advertising an open bootstrap window on the next boot that
+ *   `bootstrap_account.ts`'s atomic flip then always refuses.
+ * - `app_settings` — deleting the singleton makes every settings read throw.
+ * - `schema_version` — the migration tracker. Already refused by the
+ *   single-column-primary-key rule (its key is `(namespace, name)`), but that
+ *   is incidental: naming it here keeps the protection if the key shape ever
+ *   changes.
+ *
+ * Consumers extend this with `DbRouteOptions.non_deletable_tables` — the
+ * builtin set is a floor, never replaced.
+ */
+export declare const NON_DELETABLE_TABLES: ReadonlyArray<string>;
+/**
+ * Capabilities the db routes need — a narrow structural slice of `AppDeps`
+ * (`auth/deps.ts`), declared here so `http/` stays auth-free. The bound
+ * `auth/audit_emitter.ts` `AuditEmitter` (and therefore `AppDeps.audit` /
+ * `RouteFactoryDeps.audit`) satisfies `audit` structurally.
+ */
+export interface DbRouteDeps {
+    /**
+     * Pool-routed fire-and-forget audit emit. The row-`DELETE` handler defers
+     * the call via `emit_after_commit`, so the success-only trail row can
+     * never claim a delete whose transaction failed at COMMIT — the pool
+     * routing means the write itself never rides the request transaction.
+     */
+    audit: {
+        emit: (ctx: {
+            pending_effects: Array<Promise<void>>;
+        }, input: {
+            event_type: 'db_admin_row_delete';
+            account_id: Uuid | null;
+            ip: string;
+            metadata: {
+                table: string;
+                pk_column: string;
+                id: string;
+            };
+        }) => void;
+    };
+}
 /**
  * Per-factory configuration for db routes.
  */
 export interface DbRouteOptions {
     db_type: DbType;
     db_name: string;
+    /**
+     * The tables the browser exposes — an explicit allowlist gating the table
+     * list, table detail, and row-`DELETE` alike. Required with no "all"
+     * escape hatch, so a future secret-bearing table stays unlisted until a
+     * consumer names it, and `NON_BROWSABLE_TABLES` is subtracted even when
+     * named. An unlisted table 404s as `table_not_found` — the same answer as
+     * a table that doesn't exist.
+     */
+    browsable_tables: ReadonlyArray<string>;
     /** Optional callback to provide app-specific stats in the health response. */
     extra_stats?: (db: Db) => Promise<Record<string, unknown>>;
     /** Optional logger for server-side diagnostics (e.g. FK violation details). */
     log?: Logger;
+    /**
+     * Consumer tables to exclude from row deletion, unioned with the builtin
+     * `NON_DELETABLE_TABLES` (which this never replaces).
+     */
+    non_deletable_tables?: ReadonlyArray<string>;
 }
 /**
  * Create the db API route specs.
  */
-export declare const create_db_route_specs: (options: DbRouteOptions) => Array<RouteSpec>;
+export declare const create_db_route_specs: (deps: DbRouteDeps, options: DbRouteOptions) => Array<RouteSpec>;
 //# sourceMappingURL=db_routes.d.ts.map

package/dist/http/db_routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/db_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAqC,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAapF;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,sDAAsD;AACtD,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAC/C,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3D,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAI,SAAS,cAAc,KAAG,KAAK,CAAC,SAAS,CAgQ9E,CAAC"}
+{"version":3,"file":"db_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/db_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAqC,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAiBpF;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,sDAAsD;AACtD,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAC/C,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,MAAM,CAKrD,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,MAAM,CAKrD,CAAC;AAEH;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B;;;;;OAKG;IACH,KAAK,EAAE;QACN,IAAI,EAAE,CACL,GAAG,EAAE;YAAE,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;SAAE,EAC9C,KAAK,EAAE;YACN,UAAU,EAAE,qBAAqB,CAAC;YAClC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;YACxB,EAAE,EAAE,MAAM,CAAC;YACX,QAAQ,EAAE;gBAAE,KAAK,EAAE,MAAM,CAAC;gBAAC,SAAS,EAAE,MAAM,CAAC;gBAAC,EAAE,EAAE,MAAM,CAAA;aAAE,CAAC;SAC3D,KACG,IAAI,CAAC;KACV,CAAC;CACF;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,gBAAgB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,8EAA8E;IAC9E,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3D,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC7C;AA2CD;;GAEG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,WAAW,EACjB,SAAS,cAAc,KACrB,KAAK,CAAC,SAAS,CA4XjB,CAAC"}