firstly 0.9.4 → 0.10.1

package/esm/sqlAdmin/server/readOnlySql.d.ts

@@ -0,0 +1,18 @@
+import { SqlDatabase } from 'remult';
+import type { SqlResult, SqlTokenPool } from '../SqlAdminController';
+/**
+ * READ ONLY is only as strong as "one statement": over the simple protocol a
+ * caller can send `commit; insert ...` and the second statement runs
+ * autocommitted, outside the read-only transaction. The extended protocol
+ * (`queryMode: 'extended'`) makes Postgres itself reject multi-statement
+ * strings, so the transaction the client started is the one the query runs in.
+ *
+ * The client goes back to the pool with DISCARD ALL: session state a SELECT can
+ * still leave behind (advisory locks, set_config) must not leak to the app.
+ * A connection the query killed (pg_terminate_backend) is destroyed, not
+ * returned, and its error is swallowed here rather than crashing the process.
+ *
+ * Without a pg pool (custom `dp`, another database) it falls back to remult's
+ * transaction + `SET TRANSACTION READ ONLY`: same intent, simple protocol.
+ */
+export declare function readOnlySql(db: SqlDatabase, pool: SqlTokenPool | undefined, cmd: string): Promise<SqlResult>;

package/esm/sqlAdmin/server/readOnlySql.js

@@ -0,0 +1,51 @@
+import { SqlDatabase } from 'remult';
+/**
+ * READ ONLY is only as strong as "one statement": over the simple protocol a
+ * caller can send `commit; insert ...` and the second statement runs
+ * autocommitted, outside the read-only transaction. The extended protocol
+ * (`queryMode: 'extended'`) makes Postgres itself reject multi-statement
+ * strings, so the transaction the client started is the one the query runs in.
+ *
+ * The client goes back to the pool with DISCARD ALL: session state a SELECT can
+ * still leave behind (advisory locks, set_config) must not leak to the app.
+ * A connection the query killed (pg_terminate_backend) is destroyed, not
+ * returned, and its error is swallowed here rather than crashing the process.
+ *
+ * Without a pg pool (custom `dp`, another database) it falls back to remult's
+ * transaction + `SET TRANSACTION READ ONLY`: same intent, simple protocol.
+ */
+export async function readOnlySql(db, pool, cmd) {
+    if (!pool)
+        return readOnlyViaTransaction(db, cmd);
+    const client = await pool.connect();
+    let died;
+    const onError = (err) => {
+        died = err;
+    };
+    client.on('error', onError);
+    const start = performance.now();
+    try {
+        await client.query('BEGIN READ ONLY');
+        const res = await client.query({ text: cmd, values: [], queryMode: 'extended' });
+        const rows = res.rows ?? [];
+        return { rows, rowCount: rows.length, took: performance.now() - start };
+    }
+    finally {
+        if (!died) {
+            await client.query('ROLLBACK').catch(() => { });
+            await client.query('DISCARD ALL').catch(() => { });
+        }
+        client.off('error', onError);
+        client.release(died);
+    }
+}
+async function readOnlyViaTransaction(db, cmd) {
+    const start = performance.now();
+    let rows = [];
+    await db.transaction(async (tx) => {
+        const txDb = SqlDatabase.getDb(tx);
+        await txDb.execute('SET TRANSACTION READ ONLY');
+        rows = (await txDb.execute(cmd)).rows;
+    });
+    return { rows, rowCount: rows.length, took: performance.now() - start };
+}

package/esm/sqlAdmin/server/sqlError.d.ts

@@ -0,0 +1,6 @@
+import type { SqlDatabase } from 'remult';
+/**
+ * Never throws and never hides the original message - the returned error is the
+ * one to rethrow, with the code and any hint appended.
+ */
+export declare function enrichSqlError(db: SqlDatabase, err: unknown, cmd?: string): Promise<unknown>;

package/esm/sqlAdmin/server/sqlError.js

@@ -0,0 +1,132 @@
+/**
+ * Turns "column X does not exist" into something a caller can act on without a
+ * second round trip: Postgres' own HINT when it has one, otherwise the closest
+ * names taken from the catalog.
+ *
+ * Why it matters here more than in an app: the callers of `exec` are scripts
+ * and AIs writing SQL against a schema they cannot see, and every case observed
+ * in the call log was a misremembered identifier - quoted camelCase read as
+ * snake_case, a table named in the singular. Postgres already knows the answer
+ * (`Perhaps you meant "athleteEraEstimates.estMaxBpm"`) and the raw message
+ * throws it away.
+ */
+const RELATION_MISSING = /relation "([^"]+)" does not exist/;
+const COLUMN_MISSING = /column "?([\w$.]+)"? does not exist/;
+const NON_ALPHANUM = /[^a-z0-9]/g;
+const SQLSTATE = /^[0-9A-Z]{5}$/;
+const UNDEFINED_TABLE = '42P01';
+const UNDEFINED_COLUMN = '42703';
+/** SQLSTATE class 08: the connection is gone, so asking it about its catalog only adds a timeout. */
+const CONNECTION_CLASS = '08';
+const MAX_CANDIDATES = 3;
+const MIN_MATCH_LENGTH = 3;
+/** A caller looping on bad SQL must not turn each failure into a catalog scan. */
+const CATALOG_TTL_MS = 10_000;
+/** Comparison key: an unquoted identifier is folded to lowercase, and `_` is how the same name is spelled in snake_case. */
+const norm = (s) => s.toLowerCase().replace(NON_ALPHANUM, '');
+/** `a.analysisversion` and `public.users` are about their last part. */
+const lastPart = (s) => s.split('.').at(-1);
+/**
+ * Same name modulo case and underscores, then one name being the start of the
+ * other - which is what a singular/plural or a truncated guess looks like
+ * (`key_value` for `keyValues`). Deliberately not a typo distance: real misses
+ * are spellings of the right word, and Postgres already suggests actual typos
+ * through its own HINT.
+ */
+function closest(wanted, candidates) {
+    const target = norm(wanted);
+    if (target.length < MIN_MATCH_LENGTH)
+        return [];
+    const exact = candidates.filter((c) => norm(c.name) === target);
+    if (exact.length)
+        return exact.slice(0, MAX_CANDIDATES);
+    return candidates
+        .filter((c) => {
+        const n = norm(c.name);
+        return n.length >= MIN_MATCH_LENGTH && (n.startsWith(target) || target.startsWith(n));
+    })
+        .slice(0, MAX_CANDIDATES);
+}
+/** A column suggestion from a table the query never mentions is noise; keep those last. */
+function preferMentioned(candidates, cmd) {
+    const haystack = norm(cmd);
+    const mentioned = candidates.filter((c) => c.table && haystack.includes(norm(c.table)));
+    return mentioned.length ? mentioned : candidates;
+}
+const catalogCache = new WeakMap();
+async function catalog(db, sql) {
+    let perDb = catalogCache.get(db);
+    if (!perDb)
+        catalogCache.set(db, (perDb = new Map()));
+    const hit = perDb.get(sql);
+    if (hit && Date.now() - hit.at < CATALOG_TTL_MS)
+        return hit.rows;
+    let rows = [];
+    try {
+        rows = (await db.execute(sql)).rows ?? [];
+    }
+    catch {
+        // Not Postgres, no catalog access, connection gone: the plain error is still useful.
+    }
+    perDb.set(sql, { at: Date.now(), rows });
+    return rows;
+}
+async function suggest(db, err, cmd) {
+    const message = err.message ?? '';
+    if (err.code === UNDEFINED_TABLE) {
+        const wanted = RELATION_MISSING.exec(message)?.[1];
+        if (!wanted)
+            return [];
+        const rows = await catalog(db, `select table_name from information_schema.tables where table_schema not in ('pg_catalog', 'information_schema')`);
+        const found = closest(lastPart(wanted), rows.map((r) => ({ label: `"${r.table_name}"`, name: r.table_name })));
+        return found.map((c) => c.label);
+    }
+    if (err.code === UNDEFINED_COLUMN) {
+        const wanted = COLUMN_MISSING.exec(message)?.[1];
+        if (!wanted)
+            return [];
+        const rows = await catalog(db, `select table_name, column_name from information_schema.columns where table_schema not in ('pg_catalog', 'information_schema')`);
+        const found = closest(lastPart(wanted), rows.map((r) => ({
+            label: `"${r.table_name}"."${r.column_name}"`,
+            name: r.column_name,
+            table: r.table_name,
+        })));
+        return preferMentioned(found, cmd).map((c) => c.label);
+    }
+    return [];
+}
+/**
+ * Never throws and never hides the original message - the returned error is the
+ * one to rethrow, with the code and any hint appended.
+ */
+export async function enrichSqlError(db, err, cmd = '') {
+    if (!(err instanceof Error))
+        return err;
+    const pg = err;
+    // A SQLSTATE, not any error that happens to carry a `code`: ENOTFOUND is too
+    // long to match, but EPIPE and EBUSY have the exact same shape.
+    if (!pg.code || !SQLSTATE.test(pg.code) || pg.code.startsWith(CONNECTION_CLASS))
+        return err;
+    if (pg.errno !== undefined || pg.syscall !== undefined)
+        return err;
+    const parts = [pg.message];
+    if (pg.hint)
+        parts.push(pg.hint);
+    else {
+        const found = await suggest(db, pg, cmd);
+        if (found.length)
+            parts.push(`Did you mean ${found.join(' or ')}?`);
+    }
+    if (pg.detail)
+        parts.push(pg.detail);
+    parts.push(`[${pg.code}${pg.position ? ` at ${pg.position}` : ''}]`);
+    const out = new Error(parts.join(' · '));
+    Object.assign(out, {
+        code: pg.code,
+        hint: pg.hint,
+        detail: pg.detail,
+        position: pg.position,
+        cause: err,
+    });
+    return out;
+}

package/esm/sqlAdmin/server/token.d.ts

@@ -0,0 +1,5 @@
+export declare function newRawToken(prefix: string): string;
+export declare function hashToken(raw: string): string;
+export declare function tokenHint(raw: string, prefix: string): string;
+/** `swift-otter-3f9`: a name you can say out loud when asking "who is running this query?". */
+export declare function randomTokenName(): string;

package/esm/sqlAdmin/server/token.js

@@ -0,0 +1,17 @@
+import { createHash, randomBytes, randomInt } from 'node:crypto';
+export function newRawToken(prefix) {
+    return prefix + randomBytes(32).toString('base64url');
+}
+export function hashToken(raw) {
+    return createHash('sha256').update(raw).digest('hex');
+}
+export function tokenHint(raw, prefix) {
+    return raw.slice(0, prefix.length + 8);
+}
+const ADJECTIVES = 'amber bold brave calm clever cosmic crisp eager fuzzy gentle happy jolly keen lucky mellow neat nimble plucky quiet rapid rusty shiny silent sly snappy sunny swift tidy vivid witty zesty'.split(' ');
+const ANIMALS = 'otter badger falcon heron ibex lynx marmot narwhal ocelot panda quokka raven seal tapir urchin viper walrus yak zebu gecko koala llama mantis newt puffin stoat toucan vole wombat'.split(' ');
+/** `swift-otter-3f9`: a name you can say out loud when asking "who is running this query?". */
+export function randomTokenName() {
+    const pick = (xs) => xs[randomInt(xs.length)];
+    return `${pick(ADJECTIVES)}-${pick(ANIMALS)}-${randomBytes(2).toString('hex').slice(0, 3)}`;
+}

package/esm/sqlAdmin/sqlTokenEntities.d.ts

@@ -0,0 +1,42 @@
+/** What a call may do: `read` runs inside a READ ONLY transaction (one statement), `write` runs SQL as is. */
+export declare const SQL_CAPABILITIES: readonly ["read", "write"];
+export type SqlCapability = (typeof SQL_CAPABILITIES)[number];
+export declare const SQL_TOKEN_TTLS: {
+    readonly '1h': 3600000;
+    readonly '24h': 86400000;
+    readonly '7d': 604800000;
+};
+export type SqlTokenTtl = keyof typeof SQL_TOKEN_TTLS;
+export declare const SQL_TOKEN_DELETE_LIVE = "Revoke a live token before deleting it";
+export declare class SqlToken {
+    id: string;
+    name: string;
+    /** First chars of the raw token, so a leaked value can be matched to its row. */
+    hint: string;
+    tokenHash: string;
+    /** Minter (`remult.user.id`). The token acts as this user when `userFromId` is configured. */
+    userId: string;
+    capabilities: SqlCapability[];
+    createdAt: Date;
+    expiresAt: Date;
+    lastUsedAt: Date | null;
+    revokedAt: Date | null;
+}
+export declare class SqlTokenCall {
+    id: string;
+    tokenId: string;
+    capability: string;
+    cmd: string;
+    rowCount: number;
+    tookMs: number;
+    error: string | null;
+    ts: Date;
+}
+export declare const sqlTokenEntities: {
+    SqlToken: typeof SqlToken;
+    SqlTokenCall: typeof SqlTokenCall;
+};
+export declare function isSqlTokenLive(t: {
+    expiresAt: Date;
+    revokedAt: Date | null;
+}, now?: number): boolean;

package/esm/sqlAdmin/sqlTokenEntities.js

@@ -0,0 +1,138 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Entity, Fields, repo } from 'remult';
+import { FF_Role } from '../core/common';
+import { Roles_SqlAdmin } from './Roles_SqlAdmin';
+/** What a call may do: `read` runs inside a READ ONLY transaction (one statement), `write` runs SQL as is. */
+export const SQL_CAPABILITIES = ['read', 'write'];
+export const SQL_TOKEN_TTLS = { '1h': 3_600_000, '24h': 86_400_000, '7d': 604_800_000 };
+const admins = [Roles_SqlAdmin.SqlAdmin_Admin, FF_Role.FF_Role_Admin];
+// Minting is `SqlAdminController.mintToken` (the raw value is generated
+// server-side, shown once, never stored). Revoking is the one update the API
+// allows: set `revokedAt`; nothing else is writable and a revoke is final.
+//
+// Revoke and delete are not the same gesture: revoking is the kill switch and
+// keeps the row plus its call log, which is the audit trail; deleting is
+// cleanup and takes the calls with it - a call log pointing at a token nobody
+// can name is noise, not history. So only a dead token can be deleted: killing
+// a live one is always a revoke.
+export const SQL_TOKEN_DELETE_LIVE = 'Revoke a live token before deleting it';
+let SqlToken = class SqlToken {
+    id = '';
+    name = '';
+    /** First chars of the raw token, so a leaked value can be matched to its row. */
+    hint = '';
+    tokenHash = '';
+    /** Minter (`remult.user.id`). The token acts as this user when `userFromId` is configured. */
+    userId = '';
+    capabilities = [];
+    createdAt = new Date();
+    expiresAt = new Date();
+    lastUsedAt = null;
+    revokedAt = null;
+};
+__decorate([
+    Fields.id()
+], SqlToken.prototype, "id", void 0);
+__decorate([
+    Fields.string({ allowApiUpdate: false })
+], SqlToken.prototype, "name", void 0);
+__decorate([
+    Fields.string({ allowApiUpdate: false })
+], SqlToken.prototype, "hint", void 0);
+__decorate([
+    Fields.string({ includeInApi: false })
+], SqlToken.prototype, "tokenHash", void 0);
+__decorate([
+    Fields.string({ allowApiUpdate: false })
+], SqlToken.prototype, "userId", void 0);
+__decorate([
+    Fields.json({ allowApiUpdate: false })
+], SqlToken.prototype, "capabilities", void 0);
+__decorate([
+    Fields.createdAt()
+], SqlToken.prototype, "createdAt", void 0);
+__decorate([
+    Fields.date({ allowApiUpdate: false })
+], SqlToken.prototype, "expiresAt", void 0);
+__decorate([
+    Fields.date({ allowNull: true, allowApiUpdate: false })
+], SqlToken.prototype, "lastUsedAt", void 0);
+__decorate([
+    Fields.date({ allowNull: true })
+], SqlToken.prototype, "revokedAt", void 0);
+SqlToken = __decorate([
+    Entity('_ff_sql_tokens', {
+        caption: 'FF Sql Tokens',
+        // Admins means a session: a bearer is only ever resolved for the exec path
+        // (`server/index.ts`), so a token reaching this entity is an anonymous request.
+        allowApiRead: admins,
+        allowApiUpdate: admins,
+        allowApiDelete: admins,
+        defaultOrderBy: { createdAt: 'desc' },
+        saving: (t, e) => {
+            if (!e.isNew && e.fields.revokedAt.valueChanged() && !t.revokedAt) {
+                throw new Error('A revoked token stays revoked');
+            }
+        },
+        deleting: (t) => {
+            if (isSqlTokenLive(t))
+                throw new Error(SQL_TOKEN_DELETE_LIVE);
+        },
+        // After, not before: a failed row delete must not have dropped the calls already.
+        deleted: async (t) => {
+            await repo(SqlTokenCall).deleteMany({ where: { tokenId: t.id } });
+        },
+    })
+], SqlToken);
+export { SqlToken };
+let SqlTokenCall = class SqlTokenCall {
+    id = '';
+    tokenId = '';
+    capability = '';
+    cmd = '';
+    rowCount = 0;
+    tookMs = 0;
+    error = null;
+    ts = new Date();
+};
+__decorate([
+    Fields.id()
+], SqlTokenCall.prototype, "id", void 0);
+__decorate([
+    Fields.string()
+], SqlTokenCall.prototype, "tokenId", void 0);
+__decorate([
+    Fields.string()
+], SqlTokenCall.prototype, "capability", void 0);
+__decorate([
+    Fields.string()
+], SqlTokenCall.prototype, "cmd", void 0);
+__decorate([
+    Fields.integer()
+], SqlTokenCall.prototype, "rowCount", void 0);
+__decorate([
+    Fields.integer()
+], SqlTokenCall.prototype, "tookMs", void 0);
+__decorate([
+    Fields.string({ allowNull: true })
+], SqlTokenCall.prototype, "error", void 0);
+__decorate([
+    Fields.createdAt()
+], SqlTokenCall.prototype, "ts", void 0);
+SqlTokenCall = __decorate([
+    Entity('_ff_sql_token_calls', {
+        caption: 'FF Sql Token Calls',
+        allowApiRead: admins,
+        defaultOrderBy: { ts: 'desc' },
+    })
+], SqlTokenCall);
+export { SqlTokenCall };
+export const sqlTokenEntities = { SqlToken, SqlTokenCall };
+export function isSqlTokenLive(t, now = Date.now()) {
+    return !t.revokedAt && t.expiresAt.getTime() > now;
+}

package/esm/sqlAdmin/ui/SqlAdmin.svelte

@@ -64,7 +64,7 @@ ORDER BY tablename, indexname`,
 		try {
 			error = ''
 			isLoading = true
-			result = await SqlAdminController.exec(sqlInput, allowWrites)
+			result = await SqlAdminController.exec(sqlInput, allowWrites ? ['read', 'write'] : ['read'])
 			log.info('for AI:', JSON.stringify(result.rows))
 			log.info('for humans:', result)
 		} catch (e) {
@@ -165,7 +165,7 @@ ORDER BY tablename, indexname`,
 					class="inline-flex items-center gap-2 text-sm font-medium select-none"
 					class:text-destructive={allowWrites}
 					class:text-muted-foreground={!allowWrites}
-					title="Unchecked: the query runs in a READ ONLY transaction, so the database rejects any write. Tick only when you know what you are doing."
+					title="Unchecked: the query runs in a READ ONLY transaction, one statement at a time, so the database rejects any write. Tick only when you know what you are doing."
 				>
 					<input type="checkbox" bind:checked={allowWrites} class="accent-destructive" />
 					Allow writes