firstly 0.9.3 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # firstly
 
+## 0.10.0
+
+### Minor Changes
+
+- [#358](https://github.com/jycouet/firstly/pull/358) [`f34be07`](https://github.com/jycouet/firstly/commit/f34be07119855025e9384ddff92f7a40dd46d8bb) Thanks [@jycouet](https://github.com/jycouet)! - sqlAdmin: `exec(sql, capabilities = ['read'])` replaces the `notReadOnly` flag - reads run in a READ ONLY transaction over the extended protocol (one statement). Opt-in `tokens` (bearer tokens to run SQL from a script or an AI through the same `exec` endpoint; acts as the minter, logged) + `<SqlTokens />`; `sqlAdmin: false` registers no controller (throws when combined with `tokens`).
+
+## 0.9.4
+
+### Patch Changes
+
+- [#352](https://github.com/jycouet/firstly/pull/352) [`53ec5e1`](https://github.com/jycouet/firstly/commit/53ec5e12f744ed207b9fce6fa80f3bc9b4918a92) Thanks [@jycouet](https://github.com/jycouet)! - feedback: `getIssues` returned nothing when `milestones.labels_filters` was unset (GitHub treats `labels: []` as "match nothing"); the filter is now omitted in that case.
+
 ## 0.9.3
 
 ### Patch Changes

package/esm/feedback/FeedbackController.js

@@ -138,7 +138,10 @@ export class FeedbackController {
             owner: remult.context.feedbackOptions.repo.owner,
             milestoneNumber,
             filters: {
-                labels: remult.context.feedbackOptions.milestones?.labels_filters ?? [],
+                // GitHub treats `labels: []` as "match nothing", so omit the key when unset.
+                labels: remult.context.feedbackOptions.milestones?.labels_filters?.length
+                    ? remult.context.feedbackOptions.milestones.labels_filters
+                    : undefined,
                 states: [issueState],
             },
             issueOrder,

package/esm/sqlAdmin/SqlAdminController.d.ts

@@ -1,17 +1,78 @@
-import { SqlDatabase } from 'remult';
+import { SqlDatabase, type UserInfo } from 'remult';
+import { type SqlCapability, type SqlTokenTtl } from './sqlTokenEntities';
+declare module 'remult' {
+    interface RemultContext {
+        /** Set when the request authenticated with a live sql token aimed at the exec path. */
+        sqlToken?: {
+            id: string;
+            userId: string;
+            capabilities: SqlCapability[];
+        };
+        /** A sql-token bearer was sent (valid or not): apps may refuse cookie fallback on it. */
+        sqlTokenBearer?: boolean;
+    }
+}
+export type SqlResult = {
+    rows: any[];
+    rowCount: number;
+    took: number;
+};
+/** Just enough of `pg.Pool` for the read-only path - no dependency on pg. */
+export type SqlTokenPool = {
+    connect(): Promise<{
+        query(q: string | {
+            text: string;
+            values: unknown[];
+            queryMode: 'extended';
+        }): Promise<{
+            rows?: any[];
+        }>;
+        release(err?: Error | boolean): void;
+        on(event: 'error', fn: (err: Error) => void): unknown;
+        off(event: 'error', fn: (err: Error) => void): unknown;
+    }>;
+};
+export type SqlTokensOptions = {
+    /** Which capabilities may be minted. `write` runs SQL as is - keep it out until you need it. */
+    capabilities: SqlCapability[];
+    /**
+     * Turns the minter's id back into the request user, so the token acts as them
+     * with their live roles (lose admin, tokens die). Without it the token is its
+     * own authority and `remult.user` stays empty.
+     */
+    userFromId?: (userId: string) => Promise<UserInfo | undefined>;
+    /** Raw tokens start with this; it is also how the bearer is recognized. @default 'ffsql_' */
+    prefix?: string;
+    /** Remult's api root, for the path gate. @default '/api' */
+    apiPath?: string;
+    /** @default 30 */
+    callLogRetentionDays?: number;
+    /** Override the pool used by `read` tokens. Defaults to the Postgres pool behind the data provider. */
+    pool?: SqlTokenPool;
+};
+export declare const SQL_ADMINS: ("FF_Role.Admin" | "SqlAdmin.Admin")[];
 export declare class SqlAdminController {
     /** Optional override set by the `sqlAdmin()` module's `initApi`. Falls back to `SqlDatabase.getDb()`. */
     static dp?: SqlDatabase;
+    /** Set by the `sqlAdmin()` module's `initApi`. */
+    static options: {
+        tokens?: SqlTokensOptions;
+    };
     /**
      * @param cmd SQL to run.
-     * @param notReadOnly When `false` (default) the query runs inside a
-     *   `READ ONLY` transaction so the database itself rejects any write
-     *   (INSERT/UPDATE/DELETE/DDL). Set `true` only when you deliberately want
-     *   to mutate - the UI gates this behind an explicit checkbox.
+     * @param capabilities `['read']` (default) runs inside a `READ ONLY`
+     *   transaction, one statement at a time, so the database itself rejects any
+     *   write (INSERT/UPDATE/DELETE/DDL). Add `'write'` only when you deliberately
+     *   want to mutate - the UI gates this behind an explicit checkbox.
+     *
+     * With a sql token the token decides, not the caller.
      */
-    static exec(cmd: string, notReadOnly?: boolean): Promise<{
-        rows: any[];
-        rowCount: number;
-        took: number;
-    }>;
+    static exec(cmd: string, capabilities?: SqlCapability[]): Promise<SqlResult>;
+    private static run;
+    private static execAsToken;
+    /**
+     * Returns the raw token exactly once. Needs a live session: a token can never
+     * mint a token. Revoking is a plain update of `SqlToken.revokedAt`.
+     */
+    static mintToken(name: string, capabilities: SqlCapability[], ttl: SqlTokenTtl): Promise<string>;
 }

package/esm/sqlAdmin/SqlAdminController.js

@@ -4,41 +4,138 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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 { BackendMethod, SqlDatabase } from 'remult';
+import { BackendMethod, remult, repo, SqlDatabase } from 'remult';
 import { FF_Role } from '../core/common';
 import { Roles_SqlAdmin } from './Roles_SqlAdmin';
+import { SQL_CAPABILITIES, SQL_TOKEN_TTLS, SqlToken, SqlTokenCall, } from './sqlTokenEntities';
+export const SQL_ADMINS = [Roles_SqlAdmin.SqlAdmin_Admin, FF_Role.FF_Role_Admin];
+const CALL_LOG_CMD_MAX = 4000;
+function getDb() {
+    return SqlAdminController.dp ?? SqlDatabase.getDb();
+}
+/** The pg pool remult wraps, if any. `_getSourceSql` is internal but has been stable since remult 1. */
+function poolFrom(db) {
+    const pool = db._getSourceSql?.()?.pool;
+    return typeof pool?.connect === 'function' ? pool : undefined;
+}
 export class SqlAdminController {
     /** Optional override set by the `sqlAdmin()` module's `initApi`. Falls back to `SqlDatabase.getDb()`. */
     static dp;
+    /** Set by the `sqlAdmin()` module's `initApi`. */
+    static options = {};
     /**
      * @param cmd SQL to run.
-     * @param notReadOnly When `false` (default) the query runs inside a
-     *   `READ ONLY` transaction so the database itself rejects any write
-     *   (INSERT/UPDATE/DELETE/DDL). Set `true` only when you deliberately want
-     *   to mutate - the UI gates this behind an explicit checkbox.
+     * @param capabilities `['read']` (default) runs inside a `READ ONLY`
+     *   transaction, one statement at a time, so the database itself rejects any
+     *   write (INSERT/UPDATE/DELETE/DDL). Add `'write'` only when you deliberately
+     *   want to mutate - the UI gates this behind an explicit checkbox.
+     *
+     * With a sql token the token decides, not the caller.
+     */
+    static async exec(cmd, capabilities = ['read']) {
+        const token = remult.context.sqlToken;
+        if (token)
+            return SqlAdminController.execAsToken(token, cmd);
+        return SqlAdminController.run(cmd, capabilities);
+    }
+    static async run(cmd, capabilities) {
+        const db = getDb();
+        // Anything that is not an explicit list (null, a stray boolean) is a read.
+        if (Array.isArray(capabilities) && capabilities.includes('write')) {
+            const start = performance.now();
+            const rows = (await db.execute(cmd)).rows;
+            return { rows, rowCount: rows.length, took: performance.now() - start };
+        }
+        const { readOnlySql } = await import('./server/readOnlySql');
+        return readOnlySql(db, SqlAdminController.options.tokens?.pool ?? poolFrom(db), cmd);
+    }
+    static async execAsToken(token, cmd) {
+        const o = SqlAdminController.options.tokens;
+        if (!o)
+            throw new Error('sql tokens not enabled');
+        const capability = token.capabilities.includes('write') ? 'write' : 'read';
+        const call = repo(SqlTokenCall).create({
+            tokenId: token.id,
+            capability,
+            cmd: cmd.slice(0, CALL_LOG_CMD_MAX),
+        });
+        try {
+            const res = await SqlAdminController.run(cmd, [capability]);
+            call.rowCount = res.rowCount;
+            call.tookMs = Math.round(res.took);
+            return res;
+        }
+        catch (err) {
+            call.error = err instanceof Error ? err.message : String(err);
+            throw err;
+        }
+        finally {
+            await repo(SqlTokenCall).insert(call);
+            const days = o.callLogRetentionDays ?? 30;
+            await repo(SqlTokenCall).deleteMany({
+                where: { ts: { $lt: new Date(Date.now() - days * 86_400_000) } },
+            });
+        }
+    }
+    /**
+     * Returns the raw token exactly once. Needs a live session: a token can never
+     * mint a token. Revoking is a plain update of `SqlToken.revokedAt`.
      */
-    static async exec(cmd, notReadOnly = false) {
-        const db = SqlAdminController.dp ?? SqlDatabase.getDb();
-        const start = performance.now();
-        let rows = [];
-        // One transaction either way: a failing multi-statement script leaves nothing behind.
-        await db.transaction(async (tx) => {
-            const txDb = SqlDatabase.getDb(tx);
-            // Postgres: makes the whole transaction reject writes at the DB level.
-            if (!notReadOnly)
-                await txDb.execute('SET TRANSACTION READ ONLY');
-            rows = (await txDb.execute(cmd)).rows;
+    static async mintToken(name, capabilities, ttl) {
+        const o = SqlAdminController.options.tokens;
+        if (!o)
+            throw new Error('sql tokens not enabled (sqlAdmin({ tokens }))');
+        const userId = remult.user?.id;
+        if (!userId)
+            throw new Error('Forbidden');
+        const clean = name.trim();
+        if (!clean)
+            throw new Error('Name is required');
+        const ttlMs = SQL_TOKEN_TTLS[ttl];
+        if (!ttlMs)
+            throw new Error('Unknown ttl');
+        const unique = [...new Set(capabilities)];
+        if (unique.length === 0)
+            throw new Error('Pick at least one capability');
+        for (const c of unique) {
+            if (!SQL_CAPABILITIES.includes(c))
+                throw new Error(`Unknown capability ${c}`);
+            if (!o.capabilities.includes(c))
+                throw new Error(`${c} is not enabled`);
+        }
+        const { newRawToken, hashToken, tokenHint } = await import('./server/token');
+        const prefix = o.prefix ?? 'ffsql_';
+        const raw = newRawToken(prefix);
+        await repo(SqlToken).insert({
+            name: clean,
+            hint: tokenHint(raw, prefix),
+            tokenHash: hashToken(raw),
+            userId,
+            capabilities: unique,
+            expiresAt: new Date(Date.now() + ttlMs),
         });
-        const took = performance.now() - start;
-        return { rows, rowCount: rows.length, took };
+        return raw;
     }
 }
 __decorate([
     BackendMethod({
-        allowed: [Roles_SqlAdmin.SqlAdmin_Admin, FF_Role.FF_Role_Admin],
+        // Console: an admin session. Token: the bearer, and with `userFromId` the
+        // minter's live roles must still allow it.
+        allowed: () => {
+            const o = SqlAdminController.options;
+            if (remult.context.sqlToken)
+                return o.tokens?.userFromId ? remult.isAllowed(SQL_ADMINS) : true;
+            return remult.isAllowed(SQL_ADMINS);
+        },
         apiPrefix: 'ff/sqlAdmin',
         // Remult wraps BackendMethods in a transaction by default; ours would then be
-        // nested, which Postgres rejects. We open our own below instead.
+        // nested ("nested transactions not allowed"). We own the transaction here.
         transactional: false,
     })
 ], SqlAdminController, "exec", null);
+__decorate([
+    BackendMethod({
+        allowed: () => !!SqlAdminController.options.tokens && !remult.context.sqlToken && remult.isAllowed(SQL_ADMINS),
+        apiPrefix: 'ff/sqlAdmin',
+    })
+], SqlAdminController, "mintToken", null);

package/esm/sqlAdmin/index.d.ts

@@ -1,6 +1,8 @@
 import { Log } from '@kitql/helpers';
 export { Roles_SqlAdmin } from './Roles_SqlAdmin';
-export { SqlAdminController } from './SqlAdminController';
+export { SqlAdminController, type SqlResult, type SqlTokensOptions } from './SqlAdminController';
+export { SQL_CAPABILITIES, SQL_TOKEN_TTLS, SqlToken, SqlTokenCall, type SqlCapability, type SqlTokenTtl, } from './sqlTokenEntities';
 export { default as SqlAdmin } from './ui/SqlAdmin.svelte';
+export { default as SqlTokens } from './ui/SqlTokens.svelte';
 export declare const key = "sqlAdmin";
 export declare const log: Log;

package/esm/sqlAdmin/index.js

@@ -1,6 +1,8 @@
 import { Log } from '@kitql/helpers';
 export { Roles_SqlAdmin } from './Roles_SqlAdmin';
 export { SqlAdminController } from './SqlAdminController';
+export { SQL_CAPABILITIES, SQL_TOKEN_TTLS, SqlToken, SqlTokenCall, } from './sqlTokenEntities';
 export { default as SqlAdmin } from './ui/SqlAdmin.svelte';
+export { default as SqlTokens } from './ui/SqlTokens.svelte';
 export const key = 'sqlAdmin';
 export const log = new Log(key);

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

@@ -1,5 +1,7 @@
-import type { SqlDatabase } from 'remult';
+import { type SqlDatabase } from 'remult';
 import { Module } from 'remult/server';
+import { type SqlTokensOptions } from '../SqlAdminController';
+export type { SqlTokensOptions, SqlTokenPool } from '../SqlAdminController';
 export type SqlAdminOptions = {
     /**
      * Override the SqlDatabase used to execute queries.
@@ -13,6 +15,20 @@ export type SqlAdminOptions = {
      * @default '/sql/admin'
      */
     path?: string;
+    /**
+     * Register the `SqlAdminController` (the `exec` endpoint behind `<SqlAdmin />`).
+     * `false` registers nothing - and is an error combined with `tokens`, which
+     * run through that same endpoint.
+     *
+     * @default true
+     */
+    sqlAdmin?: boolean;
+    /**
+     * Bearer tokens that can run SQL from outside a browser session (a script,
+     * an AI on a dev machine). Nothing is registered unless set - no entities,
+     * no mint endpoint, no request hook. Needs `sqlAdmin: true`. See `<SqlTokens />`.
+     */
+    tokens?: SqlTokensOptions | false;
 };
 /**
  * Drop-in SQL admin endpoint + companion `<SqlAdmin />` component (`firstly/sqlAdmin`).
@@ -25,16 +41,17 @@ export type SqlAdminOptions = {
  * import { sqlAdmin } from './'
  *
  * export const api = remultApi({
- *   modules: [sqlAdmin()],
+ *   modules: [sqlAdmin({ tokens: { capabilities: ['read'] } })],
  * })
  * ```
  *
  * Then on any admin route:
  * ```svelte
  * <script>
- *   import { SqlAdmin } from '..'
+ *   import { SqlAdmin, SqlTokens } from '..'
  * </script>
  * <SqlAdmin />
+ * <SqlTokens />
  * ```
  */
 export declare const sqlAdmin: (opts?: SqlAdminOptions) => Module<unknown>;

package/esm/sqlAdmin/server/index.js

@@ -1,7 +1,31 @@
+import { remult, repo } from 'remult';
 import { Module } from 'remult/server';
 import { yellow } from '@kitql/helpers';
 import { log } from '..';
 import { SqlAdminController } from '../SqlAdminController';
+import { isSqlTokenLive, SqlToken, sqlTokenEntities } from '../sqlTokenEntities';
+import { hashToken } from './token';
+// Framework-agnostic: remult hands initRequest the native request (SvelteKit
+// RequestEvent, express req, a fetch Request...).
+function readAuthorization(req) {
+    const h = req?.request?.headers ?? req?.headers;
+    if (!h)
+        return '';
+    if (typeof h.get === 'function')
+        return h.get('authorization') ?? '';
+    return h.authorization ?? h.Authorization ?? '';
+}
+function readPathname(req) {
+    if (typeof req?.url?.pathname === 'string')
+        return req.url.pathname;
+    const u = req?.request?.url ?? req?.originalUrl ?? req?.url ?? req?.path ?? '';
+    try {
+        return new URL(u, 'http://localhost').pathname;
+    }
+    catch {
+        return '';
+    }
+}
 /**
  * Drop-in SQL admin endpoint + companion `<SqlAdmin />` component (`firstly/sqlAdmin`).
  *
@@ -13,28 +37,66 @@ import { SqlAdminController } from '../SqlAdminController';
  * import { sqlAdmin } from './'
  *
  * export const api = remultApi({
- *   modules: [sqlAdmin()],
+ *   modules: [sqlAdmin({ tokens: { capabilities: ['read'] } })],
  * })
  * ```
  *
  * Then on any admin route:
  * ```svelte
  * <script>
- *   import { SqlAdmin } from '..'
+ *   import { SqlAdmin, SqlTokens } from '..'
  * </script>
  * <SqlAdmin />
+ * <SqlTokens />
  * ```
  */
 export const sqlAdmin = (opts) => {
     const path = opts?.path ?? '/sql/admin';
+    const enabled = opts?.sqlAdmin ?? true;
+    const tokens = opts?.tokens || undefined;
+    if (tokens && !enabled) {
+        throw new Error('sqlAdmin({ sqlAdmin: false, tokens }): tokens run through the exec endpoint');
+    }
+    const prefix = tokens?.prefix ?? 'ffsql_';
+    const execPath = `${tokens?.apiPath ?? '/api'}/ff/sqlAdmin/exec`;
     return new Module({
         key: 'sqlAdmin',
-        controllers: [SqlAdminController],
+        // Before the app's own initRequest, so a bearer is resolved before cookies would be.
+        priority: -900,
+        entities: tokens ? Object.values(sqlTokenEntities) : [],
+        controllers: enabled ? [SqlAdminController] : [],
         initApi: async () => {
             if (opts?.dp) {
                 SqlAdminController.dp = await opts.dp();
             }
-            log.info(`AI Hint: visit ${yellow(path)} to query raw SQL.`);
+            SqlAdminController.options = { tokens };
+            if (enabled)
+                log.info(`AI Hint: visit ${yellow(path)} to query raw SQL.`);
         },
+        initRequest: tokens
+            ? async (req) => {
+                const auth = readAuthorization(req);
+                if (!auth.toLowerCase().startsWith('bearer '))
+                    return;
+                const raw = auth.slice(7).trim();
+                if (!raw.startsWith(prefix))
+                    return;
+                remult.context.sqlTokenBearer = true;
+                // A dead token, or one aimed anywhere but exec, authenticates nobody:
+                // the request stays anonymous and the target's own `allowed` rejects it.
+                if (readPathname(req) !== execPath)
+                    return;
+                const row = await repo(SqlToken).findFirst({ tokenHash: hashToken(raw) });
+                if (!row || !isSqlTokenLive(row))
+                    return;
+                // Throttled: this runs on every token request.
+                if (!row.lastUsedAt || Date.now() - row.lastUsedAt.getTime() > 60_000) {
+                    await repo(SqlToken).update(row, { lastUsedAt: new Date() });
+                }
+                remult.context.sqlToken = { id: row.id, userId: row.userId, capabilities: row.capabilities };
+                if (tokens.userFromId)
+                    remult.user = await tokens.userFromId(row.userId);
+            }
+            : undefined,
     });
 };

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/token.d.ts

@@ -0,0 +1,3 @@
+export declare function newRawToken(prefix: string): string;
+export declare function hashToken(raw: string): string;
+export declare function tokenHint(raw: string, prefix: string): string;

package/esm/sqlAdmin/server/token.js

@@ -0,0 +1,10 @@
+import { createHash, randomBytes } 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);
+}

package/esm/sqlAdmin/sqlTokenEntities.d.ts

@@ -0,0 +1,41 @@
+/** 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 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,120 @@
+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 } 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.
+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',
+        allowApiRead: admins,
+        allowApiUpdate: admins,
+        defaultOrderBy: { createdAt: 'desc' },
+        saving: (t, e) => {
+            if (!e.isNew && e.fields.revokedAt.valueChanged() && !t.revokedAt) {
+                throw new Error('A revoked token stays revoked');
+            }
+        },
+    })
+], 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

package/esm/sqlAdmin/ui/SqlTokens.svelte

@@ -0,0 +1,268 @@
+<script lang="ts">
+	/**
+	 * Sql tokens UI: mint, list/revoke, last calls. Styled against the semantic
+	 * theme tokens like `<SqlAdmin />`. Server side: `sqlAdmin({ tokens })`.
+	 * Revoking is a plain entity update; only `revokedAt` is writable.
+	 */
+	import { repo } from 'remult'
+
+	import { log } from '../index'
+	import { SqlAdminController } from '../SqlAdminController'
+	import {
+		SQL_CAPABILITIES,
+		SQL_TOKEN_TTLS,
+		SqlToken,
+		SqlTokenCall,
+		type SqlCapability,
+		type SqlTokenTtl,
+	} from '../sqlTokenEntities'
+
+	type Props = {
+		/** Capabilities offered in the form. Others render disabled. @default ['read'] */
+		capabilities?: SqlCapability[]
+		/** Command shown once a token is minted (what the user pastes). Defaults to a curl line. */
+		command?: (token: string) => string
+	}
+	let { capabilities: enabled = ['read'], command }: Props = $props()
+
+	const TTLS = Object.keys(SQL_TOKEN_TTLS) as SqlTokenTtl[]
+	const defaultCommand = (token: string) =>
+		`curl -X POST ${location.origin}/api/ff/sqlAdmin/exec -H "authorization: Bearer ${token}" -H "content-type: application/json" -d '{"args":["select 1"]}'`
+
+	let name = $state('')
+	let picked = $state<SqlCapability[]>(['read'])
+	let ttl = $state<SqlTokenTtl>('1h')
+	let minted = $state<string | null>(null)
+	let busy = $state(false)
+	let error = $state('')
+	let copied = $state(false)
+
+	let tokens = $state<SqlToken[]>([])
+	let calls = $state<SqlTokenCall[]>([])
+
+	async function refresh() {
+		;[tokens, calls] = await Promise.all([
+			repo(SqlToken).find({ limit: 100 }),
+			repo(SqlTokenCall).find({ limit: 50 }),
+		])
+	}
+
+	$effect(() => {
+		refresh()
+	})
+
+	async function mint(e: SubmitEvent) {
+		e.preventDefault()
+		busy = true
+		error = ''
+		try {
+			minted = await SqlAdminController.mintToken(name, picked, ttl)
+			name = ''
+			await refresh()
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err)
+		} finally {
+			busy = false
+		}
+	}
+
+	async function revoke(t: SqlToken) {
+		error = ''
+		try {
+			await repo(SqlToken).update(t.id, { revokedAt: new Date() })
+			await refresh()
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err)
+		}
+	}
+
+	function toggle(c: SqlCapability, on: boolean) {
+		picked = on ? [...new Set([...picked, c])] : picked.filter((x) => x !== c)
+	}
+
+	async function copy(text: string) {
+		try {
+			await navigator.clipboard.writeText(text)
+			copied = true
+			setTimeout(() => (copied = false), 1500)
+		} catch (e) {
+			log.error('copy failed', e)
+		}
+	}
+
+	const fmt = (d: Date | null) =>
+		d
+			? d.toLocaleString(undefined, {
+					day: '2-digit',
+					month: 'short',
+					hour: '2-digit',
+					minute: '2-digit',
+				})
+			: '—'
+
+	const status = (t: SqlToken) =>
+		t.revokedAt ? 'revoked' : t.expiresAt.getTime() < Date.now() ? 'expired' : 'live'
+
+	const th = 'px-4 py-2 text-left text-xs font-medium tracking-wide text-muted-foreground uppercase'
+	const td = 'px-4 py-2 align-top'
+	const btn =
+		'border border-border bg-secondary px-3 py-1.5 text-sm font-medium text-secondary-foreground hover:bg-accent hover:text-accent-foreground disabled:opacity-50'
+</script>
+
+<div class="border border-border bg-card text-card-foreground">
+	<header class="border-b border-border px-5 py-4">
+		<h2 class="text-lg font-semibold text-foreground">SQL Tokens</h2>
+		<p class="mt-1 text-sm text-muted-foreground">
+			A token is a bag of capabilities that acts as you, for a short while. Minting needs a live
+			session - a token can never mint or revoke a token. <code>read</code> runs inside a
+			<code>READ ONLY</code> transaction, one statement at a time. Every call is logged below (SQL text,
+			rows, ms, error - never the rows themselves). Revoking is immediate.
+		</p>
+	</header>
+
+	<div class="flex flex-col gap-6 p-5">
+		<form onsubmit={mint} class="flex flex-wrap items-end gap-4 text-sm">
+			<label class="flex flex-col gap-1">
+				<span class="text-xs text-muted-foreground">Name</span>
+				<input
+					bind:value={name}
+					required
+					placeholder="laptop · claude"
+					class="w-56 border border-input bg-background px-2 py-1.5 text-foreground focus:border-ring focus:outline-none"
+				/>
+			</label>
+			<fieldset class="flex flex-col gap-1">
+				<legend class="text-xs text-muted-foreground">Capabilities</legend>
+				<div class="flex gap-4 py-1.5">
+					{#each SQL_CAPABILITIES as c (c)}
+						{@const disabled = !enabled.includes(c)}
+						<label
+							class="inline-flex items-center gap-2 select-none"
+							class:text-muted-foreground={disabled}
+							class:text-destructive={c === 'write' && picked.includes('write')}
+						>
+							<input
+								type="checkbox"
+								checked={picked.includes(c)}
+								{disabled}
+								onchange={(e) => toggle(c, e.currentTarget.checked)}
+								class={c === 'write' ? 'accent-destructive' : ''}
+							/>
+							{c}{disabled ? ' (off)' : ''}
+						</label>
+					{/each}
+				</div>
+			</fieldset>
+			<label class="flex flex-col gap-1">
+				<span class="text-xs text-muted-foreground">Lifetime</span>
+				<select
+					bind:value={ttl}
+					class="border border-input bg-background px-2 py-1.5 text-foreground focus:border-ring focus:outline-none"
+				>
+					{#each TTLS as t (t)}
+						<option value={t}>{t}</option>
+					{/each}
+				</select>
+			</label>
+			<button
+				type="submit"
+				disabled={busy}
+				class="bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:opacity-90 disabled:opacity-50"
+			>
+				Mint
+			</button>
+		</form>
+
+		{#if error}
+			<pre
+				class="border border-destructive bg-destructive/10 p-3 text-sm text-destructive">{error}</pre>
+		{/if}
+
+		{#if minted}
+			{@const line = (command ?? defaultCommand)(minted)}
+			<div class="border border-primary bg-muted p-4 text-sm">
+				<p class="text-xs font-medium tracking-wide text-primary uppercase">Shown once - copy it now</p>
+				<code class="mt-2 block font-mono break-all select-all">{line}</code>
+				<div class="mt-3 flex gap-2">
+					<button type="button" class={btn} onclick={() => copy(line)}>
+						{copied ? 'Copied' : 'Copy'}
+					</button>
+					<button type="button" class={btn} onclick={() => (minted = null)}>Dismiss</button>
+				</div>
+			</div>
+		{/if}
+
+		<section>
+			<h3 class="mb-2 text-sm font-semibold text-foreground">Tokens</h3>
+			<div class="overflow-x-auto border border-border">
+				<table class="w-full text-sm">
+					<thead class="border-b border-border bg-muted">
+						<tr>
+							<th class={th}>Name</th>
+							<th class={th}>Hint</th>
+							<th class={th}>Capabilities</th>
+							<th class={th}>Created</th>
+							<th class={th}>Expires</th>
+							<th class={th}>Last used</th>
+							<th class={th}>Status</th>
+							<th class={th}></th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each tokens as t (t.id)}
+							{@const s = status(t)}
+							<tr class="border-b border-border" class:text-muted-foreground={s !== 'live'}>
+								<td class={td}>{t.name}</td>
+								<td class="{td} font-mono">{t.hint}…</td>
+								<td class="{td} font-mono">{t.capabilities.join(' ')}</td>
+								<td class={td}>{fmt(t.createdAt)}</td>
+								<td class={td}>{fmt(t.expiresAt)}</td>
+								<td class={td}>{fmt(t.lastUsedAt)}</td>
+								<td class={td} class:text-primary={s === 'live'}>{s}</td>
+								<td class="{td} text-right">
+									{#if s === 'live'}
+										<button type="button" class={btn} onclick={() => revoke(t)}>Revoke</button>
+									{/if}
+								</td>
+							</tr>
+						{:else}
+							<tr><td colspan="8" class="px-4 py-6 text-muted-foreground">No token yet.</td></tr>
+						{/each}
+					</tbody>
+				</table>
+			</div>
+		</section>
+
+		<section>
+			<h3 class="mb-2 text-sm font-semibold text-foreground">Last calls</h3>
+			<div class="overflow-x-auto border border-border">
+				<table class="w-full text-sm">
+					<thead class="border-b border-border bg-muted">
+						<tr>
+							<th class={th}>When</th>
+							<th class={th}>Capability</th>
+							<th class={th}>SQL</th>
+							<th class={th}>Rows</th>
+							<th class={th}>ms</th>
+							<th class={th}>Error</th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each calls as c (c.id)}
+							<tr class="border-b border-border">
+								<td class="{td} whitespace-nowrap">{fmt(c.ts)}</td>
+								<td class="{td} font-mono">{c.capability}</td>
+								<td class={td}><pre class="max-w-2xl font-mono whitespace-pre-wrap">{c.cmd}</pre></td>
+								<td class={td}>{c.rowCount}</td>
+								<td class={td}>{c.tookMs}</td>
+								<td class="{td} text-destructive">{c.error ?? ''}</td>
+							</tr>
+						{:else}
+							<tr><td colspan="6" class="px-4 py-6 text-muted-foreground">No call yet.</td></tr>
+						{/each}
+					</tbody>
+				</table>
+			</div>
+		</section>
+	</div>
+</div>

package/esm/sqlAdmin/ui/SqlTokens.svelte.d.ts

@@ -0,0 +1,10 @@
+import { type SqlCapability } from '../sqlTokenEntities';
+type Props = {
+    /** Capabilities offered in the form. Others render disabled. @default ['read'] */
+    capabilities?: SqlCapability[];
+    /** Command shown once a token is minted (what the user pastes). Defaults to a curl line. */
+    command?: (token: string) => string;
+};
+declare const SqlTokens: import("svelte").Component<Props, {}, "">;
+type SqlTokens = ReturnType<typeof SqlTokens>;
+export default SqlTokens;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firstly",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "type": "module",
   "description": "Firstly, an opinionated Remult setup!",
   "funding": "https://github.com/sponsors/jycouet",