@fuzdev/fuz_app 0.108.0 → 0.110.0

package/dist/http/db_routes.js

@@ -1,25 +1,155 @@
 /**
  * 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 { z } from 'zod';
 import { get_route_params, get_route_query } from './route_spec.js';
 import { ActingActor } from './auth_shape.js';
-import { ForeignKeyError, ERROR_TABLE_NOT_FOUND, ERROR_TABLE_NO_PRIMARY_KEY, ERROR_ROW_NOT_FOUND, ERROR_FOREIGN_KEY_VIOLATION, ERROR_INVALID_ROUTE_PARAMS, ERROR_DATABASE_CONNECTION_FAILED } from './error_schemas.js';
+import { ForeignKeyError, ERROR_TABLE_NOT_FOUND, ERROR_TABLE_NO_PRIMARY_KEY, ERROR_TABLE_NOT_DELETABLE, ERROR_ROW_NOT_FOUND, ERROR_FOREIGN_KEY_VIOLATION, ERROR_INVALID_ROUTE_PARAMS, ERROR_DATABASE_CONNECTION_FAILED } from './error_schemas.js';
 import { assert_valid_sql_identifier, VALID_SQL_IDENTIFIER } from '../db/sql_identifier.js';
+import { pg_error_code } from '../db/pg_error.js';
+import { get_client_ip } from './client_ip.js';
+import { emit_after_commit } from './pending_effects.js';
 /** Default page size for `GET /tables/:name` rows. */
 export const DB_TABLE_ROWS_DEFAULT_LIMIT = 100;
 /** Maximum page size for `GET /tables/:name` rows. */
 export 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 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 const NON_BROWSABLE_TABLES = Object.freeze([
+    'account',
+    'auth_session',
+    'api_token',
+    'bootstrap_lock'
+]);
+/**
+ * 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 const NON_DELETABLE_TABLES = Object.freeze([
+    'audit_log',
+    'bootstrap_lock',
+    'app_settings',
+    'schema_version'
+]);
+/**
+ * Resolve a table's primary-key column names in key order
+ * (`key_column_usage.ordinal_position`). Empty for a table with no primary key;
+ * length `> 1` for a composite primary key.
+ *
+ * Every column is returned (no `LIMIT`) so callers see the full key shape: the
+ * row-`DELETE` route acts only on a single-column primary key, and an earlier
+ * `LIMIT 1` (no `ORDER BY`) hid a composite PK behind one arbitrary column,
+ * causing single-column deletes to over-match.
+ */
+const query_primary_key_columns = async (db, name) => {
+    const pk_rows = await db.query(`SELECT kcu.column_name
+		 FROM information_schema.table_constraints tc
+		 JOIN information_schema.key_column_usage kcu
+		   ON tc.constraint_name = kcu.constraint_name
+		   AND tc.table_schema = kcu.table_schema
+		   AND tc.table_name = kcu.table_name
+		 WHERE tc.constraint_type = 'PRIMARY KEY'
+		   AND tc.table_schema = 'public'
+		   AND tc.table_name = $1
+		 ORDER BY kcu.ordinal_position`, [name]);
+    return pk_rows.map((row) => row.column_name);
+};
+/**
+ * Whether `name` is a table in the `public` schema. Both the detail and
+ * row-`DELETE` routes gate on this before interpolating the name into SQL, so
+ * an unknown table is a 404 rather than a raw PG error.
+ */
+const query_table_exists = async (db, name) => {
+    const row = await db.query_one(`SELECT table_name FROM information_schema.tables
+		 WHERE table_schema = 'public' AND table_name = $1`, [name]);
+    return row !== undefined;
+};
 /**
  * Create the db API route specs.
  */
-export const create_db_route_specs = (options) => {
-    const { db_type, db_name, extra_stats, log } = options;
+export const create_db_route_specs = (deps, options) => {
+    const { db_type, db_name, browsable_tables, extra_stats, log, non_deletable_tables } = options;
+    const non_deletable = new Set([
+        ...NON_DELETABLE_TABLES,
+        ...(non_deletable_tables ?? [])
+    ]);
+    // The credential floor is subtracted, not merely documented — a consumer
+    // naming `account` in its allowlist still gets no `account` browsing.
+    const browsable = new Set(browsable_tables.filter((name) => !NON_BROWSABLE_TABLES.includes(name)));
+    // `SET` can't be parameterized; the value is a module constant, never input.
+    const set_statement_timeout = async (db) => {
+        await db.query(`SET LOCAL statement_timeout = ${DB_ADMIN_STATEMENT_TIMEOUT_MS}`);
+    };
+    /**
+     * The shared masked gate prologue for the detail and row-`DELETE`
+     * handlers: allowlist check (before any catalog read), then the statement
+     * timeout, then existence — an unbrowsable table and a missing one get
+     * the same 404 from the same place, so the masking invariant has one
+     * home. Returns whether the table is browsable AND exists.
+     */
+    const gate_browsable_table = async (db, name) => {
+        if (!browsable.has(name))
+            return false;
+        await set_statement_timeout(db);
+        return query_table_exists(db, name);
+    };
+    /**
+     * Strict integer query param — accepts exactly what the Rust twin's
+     * `str::parse::<i64>` does (`[+-]?digits`), so the twins refuse the same
+     * spellings (`z.coerce` alone admits `""`, `" 5"`, `"1e2"`, `"5.0"`).
+     */
+    const query_int = (bounds, fallback) => z.preprocess((v) => v === undefined
+        ? undefined
+        : typeof v === 'string' && /^[+-]?\d+$/.test(v)
+            ? Number(v)
+            : Number.NaN, bounds.default(fallback));
     return [
         {
             method: 'GET',
@@ -40,6 +170,9 @@ export const create_db_route_specs = (options) => {
             handler: async (c, route) => {
                 try {
                     await route.db.query('SELECT 1');
+                    // Deliberately schema-wide (not allowlist-filtered): the count
+                    // is a did-migrations-run diagnostic, and a bare number leaks
+                    // no table contents or names.
                     const table_result = await route.db.query(`SELECT COUNT(*) as count FROM information_schema.tables WHERE table_schema = 'public'`);
                     const table_count = table_result[0] ? parseInt(table_result[0].count, 10) : 0;
                     const stats = extra_stats ? await extra_stats(route.db) : {};
@@ -70,18 +203,24 @@ export const create_db_route_specs = (options) => {
                 roles: ['keeper'],
                 credential_types: ['daemon_token']
             },
-            description: 'List public tables with row counts',
+            description: 'List browsable tables with row counts',
             query: z.strictObject({ acting: ActingActor }),
             input: z.null(),
             output: z.looseObject({
                 tables: z.array(z.strictObject({ name: z.string(), row_count: z.number() }))
             }),
+            transaction: true,
             handler: async (c, route) => {
+                await set_statement_timeout(route.db);
+                // Existence still comes from `information_schema` — a listed table
+                // that hasn't migrated in yet is silently absent, not a 500.
                 const table_names = await route.db.query(`SELECT table_name FROM information_schema.tables
 					 WHERE table_schema = 'public'
 					 ORDER BY table_name`);
                 const tables = [];
                 for (const { table_name } of table_names) {
+                    if (!browsable.has(table_name))
+                        continue;
                     const result = await route.db.query_one(`SELECT COUNT(*) as count FROM "${assert_valid_sql_identifier(table_name)}"`);
                     tables.push({
                         name: table_name,
@@ -104,13 +243,8 @@ export const create_db_route_specs = (options) => {
             params: z.strictObject({ name: z.string().regex(VALID_SQL_IDENTIFIER) }),
             query: z.strictObject({
                 acting: ActingActor,
-                offset: z.coerce.number().int().min(0).default(0),
-                limit: z.coerce
-                    .number()
-                    .int()
-                    .min(1)
-                    .max(DB_TABLE_ROWS_LIMIT_MAX)
-                    .default(DB_TABLE_ROWS_DEFAULT_LIMIT)
+                offset: query_int(z.number().int().min(0), 0),
+                limit: query_int(z.number().int().min(1).max(DB_TABLE_ROWS_LIMIT_MAX), DB_TABLE_ROWS_DEFAULT_LIMIT)
             }),
             input: z.null(),
             errors: {
@@ -127,34 +261,59 @@ export const create_db_route_specs = (options) => {
                 total: z.number(),
                 offset: z.number(),
                 limit: z.number(),
-                primary_key: z.string().nullable()
+                primary_key: z.string().nullable(),
+                deletable: z.boolean()
             }),
+            transaction: true,
             handler: async (c, route) => {
                 const { name } = get_route_params(c);
                 const { offset, limit } = get_route_query(c);
-                const exists = await route.db.query_one(`SELECT table_name FROM information_schema.tables
-					 WHERE table_schema = 'public' AND table_name = $1`, [name]);
-                if (!exists) {
+                // Allowlist gate, masked: an unlisted (or floor) table answers
+                // exactly like one that doesn't exist.
+                if (!(await gate_browsable_table(route.db, name))) {
                     return c.json({ error: ERROR_TABLE_NOT_FOUND }, 404);
                 }
-                const columns = await route.db.query(`SELECT column_name, data_type, is_nullable
+                // `udt_name` is internal (drives the byte-value placeholder;
+                // `data_type` reports only `ARRAY` for array columns) — it is
+                // stripped from the response so the wire shape twins Rust's.
+                const column_rows = await route.db.query(`SELECT column_name, data_type, is_nullable, udt_name
 					 FROM information_schema.columns
 					 WHERE table_schema = 'public' AND table_name = $1
 					 ORDER BY ordinal_position`, [name]);
+                const columns = column_rows.map(({ column_name, data_type, is_nullable }) => ({ column_name, data_type, is_nullable }));
                 const count_result = await route.db.query_one(`SELECT COUNT(*) as count FROM "${assert_valid_sql_identifier(name)}"`);
                 const total = count_result ? parseInt(count_result.count, 10) : 0;
-                const pk_info = await route.db.query_one(`SELECT kcu.column_name
-					 FROM information_schema.table_constraints tc
-					 JOIN information_schema.key_column_usage kcu
-					   ON tc.constraint_name = kcu.constraint_name
-					   AND tc.table_schema = kcu.table_schema
-					 WHERE tc.constraint_type = 'PRIMARY KEY'
-					   AND tc.table_schema = 'public'
-					   AND tc.table_name = $1
-					 LIMIT 1`, [name]);
-                const primary_key = pk_info?.column_name ?? null;
-                const rows = await route.db.query(`SELECT * FROM "${assert_valid_sql_identifier(name)}" LIMIT $1 OFFSET $2`, [limit, offset]);
-                return c.json({ columns, rows, total, offset, limit, primary_key });
+                // Surface a single-column PK for the delete affordance; a
+                // composite (or absent) PK has no single deletable column, so
+                // report null — twinning the row-DELETE's single-column rule.
+                const pk_columns = await query_primary_key_columns(route.db, name);
+                const primary_key = pk_columns.length === 1 ? pk_columns[0] : null;
+                // `deletable` is exactly what the row-DELETE will accept, so a
+                // client can hide the affordance rather than discover the refusal.
+                // `primary_key` stays a truthful report of the key shape — a policy
+                // exclusion must not masquerade as one.
+                const deletable = primary_key !== null && !non_deletable.has(name);
+                // byte values never leave the server — a full page of e.g.
+                // `fact.bytes` would otherwise materialize GiBs in one response.
+                // The column stays in the result with a `<N bytes>` placeholder
+                // per cell (NULL stays NULL); `columns` metadata is untouched.
+                // Keyed on `udt_name` so `bytea[]` (`data_type: 'ARRAY'`,
+                // `udt_name: '_bytea'`) is covered too — `octet_length` doesn't
+                // take arrays, so those report the stored `pg_column_size`.
+                const select_list = column_rows.length === 0 // zero-column tables are legal PG
+                    ? '*'
+                    : column_rows
+                        .map(({ column_name, udt_name }) => {
+                        const ident = assert_valid_sql_identifier(column_name);
+                        if (udt_name === 'bytea')
+                            return `('<' || octet_length("${ident}") || ' bytes>') AS "${ident}"`;
+                        if (udt_name === '_bytea')
+                            return `('<' || pg_column_size("${ident}") || ' bytes>') AS "${ident}"`;
+                        return `"${ident}"`;
+                    })
+                        .join(', ');
+                const rows = await route.db.query(`SELECT ${select_list} FROM "${assert_valid_sql_identifier(name)}" LIMIT $1 OFFSET $2`, [limit, offset]);
+                return c.json({ columns, rows, total, offset, limit, primary_key, deletable });
             }
         },
         {
@@ -176,7 +335,11 @@ export const create_db_route_specs = (options) => {
             output: z.looseObject({ success: z.boolean() }),
             errors: {
                 400: z.looseObject({
-                    error: z.enum([ERROR_INVALID_ROUTE_PARAMS, ERROR_TABLE_NO_PRIMARY_KEY])
+                    error: z.enum([
+                        ERROR_INVALID_ROUTE_PARAMS,
+                        ERROR_TABLE_NO_PRIMARY_KEY,
+                        ERROR_TABLE_NOT_DELETABLE
+                    ])
                 }),
                 404: z.looseObject({
                     error: z.enum([ERROR_TABLE_NOT_FOUND, ERROR_ROW_NOT_FOUND])
@@ -185,32 +348,86 @@ export const create_db_route_specs = (options) => {
             },
             handler: async (c, route) => {
                 const { name, id } = get_route_params(c);
-                const exists = await route.db.query_one(`SELECT table_name FROM information_schema.tables
-					 WHERE table_schema = 'public' AND table_name = $1`, [name]);
-                if (!exists) {
+                // Same allowlist gate and masking as the detail route — an
+                // unbrowsable table exposes no rows to delete either.
+                if (!(await gate_browsable_table(route.db, name))) {
                     return c.json({ error: ERROR_TABLE_NOT_FOUND }, 404);
                 }
-                const pk_info = await route.db.query_one(`SELECT kcu.column_name
-					 FROM information_schema.table_constraints tc
-					 JOIN information_schema.key_column_usage kcu
-					   ON tc.constraint_name = kcu.constraint_name
-					   AND tc.table_schema = kcu.table_schema
-					 WHERE tc.constraint_type = 'PRIMARY KEY'
-					   AND tc.table_schema = 'public'
-					   AND tc.table_name = $1
-					 LIMIT 1`, [name]);
-                if (!pk_info) {
+                // Policy exclusion, checked before the key shape: the trail and the
+                // framework's singleton bookkeeping rows are never row-deletable through
+                // a generic storage endpoint (see `NON_DELETABLE_TABLES`). 400 rather
+                // than 403 — this says nothing about the caller's authority, and it sits
+                // beside the structural refusal below as the same kind of answer: this
+                // table exposes no deletable row here. A 403 would also have to be
+                // declared as a union with whatever the route's `auth` derives, which a
+                // consumer rewriting `auth` (as fuz_forge does) would silently invalidate.
+                if (non_deletable.has(name)) {
+                    return c.json({ error: ERROR_TABLE_NOT_DELETABLE }, 400);
+                }
+                // Single-column primary keys only. Deleting by a single
+                // `WHERE "<col>" = $1` is safe only when the PK is exactly one
+                // column: on a composite PK that filter matches every row sharing
+                // the column's value and silently over-deletes (deleting one
+                // cell_field row would wipe every field of that name on every
+                // cell); an absent PK has nothing to target. Refuse both.
+                const pk_columns = await query_primary_key_columns(route.db, name);
+                if (pk_columns.length !== 1) {
                     return c.json({ error: ERROR_TABLE_NO_PRIMARY_KEY }, 400);
                 }
+                const pk_column = pk_columns[0];
                 try {
-                    const result = await route.db.query(`DELETE FROM "${assert_valid_sql_identifier(name)}" WHERE "${assert_valid_sql_identifier(pk_info.column_name)}" = $1 RETURNING *`, [id]);
+                    // Typed PK compare, twinning the Rust spine: `$1` travels as an
+                    // untyped text-format parameter, so PG infers the PK column's
+                    // type and coerces the id with that type's input function —
+                    // index-scan deletes and canonical per-type semantics (citext
+                    // case-insensitivity, char(n) padding, any valid uuid spelling).
+                    // An id that cannot be a value of the PK type errors at bind
+                    // (22P02/22003), mapped below to the same 404 as a typed miss.
+                    // `RETURNING "<pk>"::text` reads back only the PK cell — the
+                    // deleted row's other values (e.g. a bytea column) are never
+                    // materialized — so the audit trail records the row's canonical
+                    // PK rendering rather than whatever spelling the URL supplied.
+                    const pk_ident = assert_valid_sql_identifier(pk_column);
+                    const result = await route.db.query(`DELETE FROM "${assert_valid_sql_identifier(name)}" WHERE "${pk_ident}" = $1 RETURNING "${pk_ident}"::text AS pk_text`, [id]);
                     if (result.length === 0) {
                         return c.json({ error: ERROR_ROW_NOT_FOUND }, 404);
                     }
+                    const deleted_id = result[0].pk_text;
+                    // The trail for the trail-adjacent surface: every successful row
+                    // delete through this endpoint is audited. Deferred via
+                    // `emit_after_commit` so the pool-routed row can never claim a
+                    // delete whose transaction failed at COMMIT — the Rust twin
+                    // commits before emitting for the same reason. Account-grain
+                    // attribution — the browser is a raw storage surface, so no actor
+                    // is claimed.
+                    const account_id = c.var.request_context?.account.id ?? null;
+                    const ip = get_client_ip(c);
+                    emit_after_commit(route, () => {
+                        deps.audit.emit(route, {
+                            event_type: 'db_admin_row_delete',
+                            account_id,
+                            ip,
+                            metadata: { table: name, pk_column, id: deleted_id }
+                        });
+                    });
                     return c.json({ success: true });
                 }
                 catch (err) {
-                    if (err instanceof Error && 'code' in err && err.code === '23503') {
+                    const code = pg_error_code(err);
+                    // 22P02 invalid_text_representation / 22003 numeric_value_out_of_range
+                    // / 22021 character_not_in_repertoire: the id cannot be coerced
+                    // to the PK column's type — or cannot even be a text value (a
+                    // NUL byte, rejected by the server encoding whatever the PK
+                    // type) — so no row can match; answer with the same masked 404
+                    // as a typed miss.
+                    if (code === '22P02' || code === '22003' || code === '22021') {
+                        return c.json({ error: ERROR_ROW_NOT_FOUND }, 404);
+                    }
+                    // 23503 foreign_key_violation / 23001 restrict_violation — the
+                    // same referencing-row refusal: PG 18+ raises 23001 for `ON
+                    // DELETE RESTRICT` constraints where PG ≤17 (PGlite today)
+                    // raises 23503 for both.
+                    if (code === '23503' || code === '23001') {
                         const pg_err = err;
                         log?.warn('Foreign key violation:', pg_err.detail, pg_err.constraint);
                         return c.json({ error: ERROR_FOREIGN_KEY_VIOLATION }, 409);

package/dist/http/error_schemas.d.ts

@@ -120,8 +120,19 @@ export declare const ERROR_INVALID_EVENT_TYPE: "invalid_event_type";
 export declare const ERROR_FOREIGN_KEY_VIOLATION: "foreign_key_violation";
 /** Table name not found in `information_schema`. */
 export declare const ERROR_TABLE_NOT_FOUND: "table_not_found";
-/** Table has no primary key constraint (cannot delete by PK). */
+/**
+ * Table has no single-column primary key, so there is no column the row-`DELETE`
+ * can target: either no primary key at all, or a composite one (a single-column
+ * `WHERE` on one member of a composite key over-matches).
+ */
 export declare const ERROR_TABLE_NO_PRIMARY_KEY: "table_no_primary_key";
+/**
+ * Table is excluded from row deletion by policy — the audit trail and the
+ * framework's singleton bookkeeping rows (`bootstrap_lock`, `app_settings`,
+ * `schema_version`), whose invariants live in the domain layer rather than in
+ * a generic storage endpoint. See `http/db_routes.ts`'s `NON_DELETABLE_TABLES`.
+ */
+export declare const ERROR_TABLE_NOT_DELETABLE: "table_not_deletable";
 /** Row with the given PK value not found. */
 export declare const ERROR_ROW_NOT_FOUND: "row_not_found";
 /** Database health-check query failed (connectivity or query error). */

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

@@ -1 +1 @@
-{"version":3,"file":"error_schemas.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/error_schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"error_schemas.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/error_schemas.ts"],"names":[],"mappings":"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"}

package/dist/http/error_schemas.js

@@ -128,8 +128,19 @@ export const ERROR_INVALID_EVENT_TYPE = 'invalid_event_type';
 export const ERROR_FOREIGN_KEY_VIOLATION = 'foreign_key_violation';
 /** Table name not found in `information_schema`. */
 export const ERROR_TABLE_NOT_FOUND = 'table_not_found';
-/** Table has no primary key constraint (cannot delete by PK). */
+/**
+ * Table has no single-column primary key, so there is no column the row-`DELETE`
+ * can target: either no primary key at all, or a composite one (a single-column
+ * `WHERE` on one member of a composite key over-matches).
+ */
 export const ERROR_TABLE_NO_PRIMARY_KEY = 'table_no_primary_key';
+/**
+ * Table is excluded from row deletion by policy — the audit trail and the
+ * framework's singleton bookkeeping rows (`bootstrap_lock`, `app_settings`,
+ * `schema_version`), whose invariants live in the domain layer rather than in
+ * a generic storage endpoint. See `http/db_routes.ts`'s `NON_DELETABLE_TABLES`.
+ */
+export const ERROR_TABLE_NOT_DELETABLE = 'table_not_deletable';
 /** Row with the given PK value not found. */
 export const ERROR_ROW_NOT_FOUND = 'row_not_found';
 /** Database health-check query failed (connectivity or query error). */

package/dist/http/pending_effects.d.ts

@@ -41,12 +41,12 @@
  */
 import type { Logger } from '@fuzdev/fuz_util/log.ts';
 /**
- * Minimal structural context required by `emit_after_commit`. Both
- * `RouteContext` and `ActionContext` satisfy this — they each carry
- * `log` and `post_commit_effects`.
+ * Minimal structural context required by `emit_after_commit` — just the
+ * deferred queue. Both `RouteContext` and `ActionContext` satisfy this.
+ * (No `log` here: the flush middleware owns the per-thunk `try/catch` +
+ * `log.error`, with a logger of its own.)
  */
 export interface EmitAfterCommitContext {
-    log: Logger;
     post_commit_effects: Array<() => void | Promise<void>>;
 }
 /**
@@ -71,7 +71,7 @@ export interface EmitAfterCommitContext {
  * land even when the handler fails) belong on the eager `pending_effects` queue
  * instead.
  *
- * @param ctx - context carrying `log` and the `post_commit_effects` queue
+ * @param ctx - context carrying the `post_commit_effects` queue
  * @param fn - side effect to run after commit; may return `void` or `Promise<void>`
  * @mutates `ctx.post_commit_effects` - appends `fn` verbatim
  */

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

@@ -1 +1 @@
-{"version":3,"file":"pending_effects.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/pending_effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,mBAAmB,EAAE,KAAK,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,iBAAiB,GAC7B,KAAK,sBAAsB,EAC3B,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAC5B,IAEF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,kCAAkC,GAAU,CAAC,EACzD,qBAAqB,KAAK,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EAClE,UAAU,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAC5B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAQpB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GACjC,SAAS,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EACrC,KAAK,MAAM,EACX,eAAe,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,KACtC,OAAO,CAAC,IAAI,CASd,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GACrC,SAAS,aAAa,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAClD,KAAK,MAAM,KACT,OAAO,CAAC,IAAI,CAiBd,CAAC"}
+{"version":3,"file":"pending_effects.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/pending_effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACtC,mBAAmB,EAAE,KAAK,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,iBAAiB,GAC7B,KAAK,sBAAsB,EAC3B,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAC5B,IAEF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,kCAAkC,GAAU,CAAC,EACzD,qBAAqB,KAAK,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EAClE,UAAU,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAC5B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAQpB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GACjC,SAAS,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EACrC,KAAK,MAAM,EACX,eAAe,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,KACtC,OAAO,CAAC,IAAI,CASd,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GACrC,SAAS,aAAa,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAClD,KAAK,MAAM,KACT,OAAO,CAAC,IAAI,CAiBd,CAAC"}

package/dist/http/pending_effects.js

@@ -61,7 +61,7 @@
  * land even when the handler fails) belong on the eager `pending_effects` queue
  * instead.
  *
- * @param ctx - context carrying `log` and the `post_commit_effects` queue
+ * @param ctx - context carrying the `post_commit_effects` queue
  * @param fn - side effect to run after commit; may return `void` or `Promise<void>`
  * @mutates `ctx.post_commit_effects` - appends `fn` verbatim
  */

package/dist/runtime/deno.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deno.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/deno.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,WAAW,EAA6B,MAAM,WAAW,CAAC;AA6DxE;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,aAAa,CAAC,MAAM,CAAC,KAAG,WAgJhE,CAAC"}
+{"version":3,"file":"deno.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/deno.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,WAAW,EAA6B,MAAM,WAAW,CAAC;AAoExE;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,aAAa,CAAC,MAAM,CAAC,KAAG,WAuKhE,CAAC"}

package/dist/runtime/deno.js

@@ -8,6 +8,7 @@
  * @module
  */
 import { to_error_message } from '@fuzdev/fuz_util/error.ts';
+import { assert_secure_mode, assert_secure_size, read_secure_bounded } from './secure_file.js';
 /**
  * Create a runtime backed by Deno APIs.
  *
@@ -44,6 +45,28 @@ export const create_deno_runtime = (args) => ({
     mkdir: (path, options) => Deno.mkdir(path, options),
     read_text_file: (path) => Deno.readTextFile(path),
     read_file: (path) => Deno.readFile(path),
+    read_secure_file: async (path) => {
+        // Deno exposes no O_NOFOLLOW, so the symlink check is a pre-open lstat
+        // (a TOCTOU window the Node impl doesn't have — the mode check below
+        // still runs on the open descriptor, so a post-open swap can't defeat
+        // it). The checks themselves are the shared `runtime/secure_file.ts`
+        // helpers, same as `load_secure_file_node`.
+        const l = await Deno.lstat(path);
+        if (l.isSymlink)
+            throw new Error(`secure file is a symlink: ${path}`);
+        const file = await Deno.open(path, { read: true });
+        try {
+            const s = await file.stat();
+            // `mode` is null where POSIX modes don't apply (Windows).
+            if (s.mode !== null)
+                assert_secure_mode(path, s.mode);
+            assert_secure_size(path, s.size);
+            return await read_secure_bounded(path, (target) => file.read(target));
+        }
+        finally {
+            file.close();
+        }
+    },
     read_file_stream: async (path) => (await Deno.open(path, { read: true })).readable,
     write_file_stream: async (path, data) => {
         const file = await Deno.open(path, { write: true, create: true, truncate: true });
@@ -78,7 +101,10 @@ export const create_deno_runtime = (args) => ({
             names.push(entry.name);
         return names;
     },
-    write_text_file: (path, content) => Deno.writeTextFile(path, content),
+    write_text_file: (path, content, options) => Deno.writeTextFile(path, content, {
+        mode: options?.mode,
+        createNew: options?.exclusive
+    }),
     write_file: (path, data) => Deno.writeFile(path, data),
     rename: (old_path, new_path) => Deno.rename(old_path, new_path),
     fsync: async (path) => {

package/dist/runtime/deps.d.ts

@@ -79,6 +79,39 @@ export interface ReadTextFromOffsetResult {
     /** Total file size at the time of the read (for truncation detection). */
     file_size: number;
 }
+/**
+ * Options for `FsWriteDeps.write_text_file`.
+ */
+export interface WriteFileOptions {
+    /**
+     * POSIX mode applied at creation (e.g. `0o600`). Creation-time only — an
+     * existing file keeps its mode (pair with `exclusive` when the mode must
+     * hold). No-op where modes don't apply (mock runtime, Windows).
+     */
+    mode?: number;
+    /**
+     * Fail if the path already exists (`O_EXCL`). Load-bearing for secret
+     * files: without it a crash-leftover temp file is reopened `O_TRUNC` and
+     * keeps its old (possibly permissive) mode, since `mode` only applies at
+     * creation.
+     */
+    exclusive?: boolean;
+}
+/**
+ * Hardened read for secret files (bootstrap tokens, keys) — the TS twin of
+ * the Rust spine's `fuz_sys::secure_file::load_secure_file`.
+ */
+export interface FsSecureReadDeps {
+    /**
+     * Read a small secret file with fail-loud checks: rejects symlinks, any
+     * group/other-accessible mode (must be `0600`/`0400`; skipped where POSIX
+     * modes don't apply), and files over a 4 KiB cap. Permission checks run on
+     * the open descriptor where the platform allows, so the file can't be
+     * swapped between check and read. Throws on any refusal — a refused secret
+     * must never degrade to an empty read.
+     */
+    read_secure_file: (path: string) => Promise<Uint8Array>;
+}
 /**
  * File system read operations.
  */
@@ -104,12 +137,13 @@ export interface FsReadDeps {
  * File system write operations.
  */
 export interface FsWriteDeps {
-    /** Create a directory. */
+    /** Create a directory. `mode` applies at creation (no-op where modes don't apply). */
     mkdir: (path: string, options?: {
         recursive?: boolean;
+        mode?: number;
     }) => Promise<void>;
-    /** Write text to a file. */
-    write_text_file: (path: string, content: string) => Promise<void>;
+    /** Write text to a file. See `WriteFileOptions` for `mode` / `exclusive`. */
+    write_text_file: (path: string, content: string, options?: WriteFileOptions) => Promise<void>;
     /** Write bytes to a file. */
     write_file: (path: string, data: Uint8Array) => Promise<void>;
     /** Rename (move) a file. */
@@ -213,7 +247,7 @@ export interface ProcessDeps {
  * Functions should accept narrow `*Deps` interfaces, not this full type —
  * this type is for the wiring layer that creates and passes the runtime.
  */
-export interface RuntimeDeps extends EnvDeps, FsReadDeps, FsWriteDeps, FsStreamDeps, FsRemoveDeps, CommandDeps, FetchDeps, TerminalDeps, ProcessDeps, LogDeps {
+export interface RuntimeDeps extends EnvDeps, FsReadDeps, FsSecureReadDeps, FsWriteDeps, FsStreamDeps, FsRemoveDeps, CommandDeps, FetchDeps, TerminalDeps, ProcessDeps, LogDeps {
     /** Get all environment variables. */
     env_all: () => Record<string, string>;
     /** CLI arguments passed to the program. */