firstly 0.9.4 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # firstly
 
+## 0.10.1
+
+### Patch Changes
+
+- [#365](https://github.com/jycouet/firstly/pull/365) [`cf68997`](https://github.com/jycouet/firstly/commit/cf68997ca89672c2026ea502d197a670b942f4c0) Thanks [@jycouet](https://github.com/jycouet)! - Expose `firstly/cron` (`Roles_Cron`, `Cron`) so client code can import them, like `firstly/changeLog` already does.
+
+- [#364](https://github.com/jycouet/firstly/pull/364) [`fcd660e`](https://github.com/jycouet/firstly/commit/fcd660ef5a8677f2dad6d4c8bc1017ae2fe46574) Thanks [@jycouet](https://github.com/jycouet)! - Accept SvelteKit 3 as a peer, prereleases included (`3.0.0-next.x`).
+
+- [#362](https://github.com/jycouet/firstly/pull/362) [`993486d`](https://github.com/jycouet/firstly/commit/993486dd25b5c06def4874a3b3f95440bc79a845) Thanks [@jycouet](https://github.com/jycouet)! - sqlAdmin: failed queries now carry Postgres' HINT (or the closest catalog names) and the SQLSTATE, so `column a.analysisversion does not exist` comes back with `Did you mean "activities"."analysisVersion"?`. New `ff-sql` bin to run token SQL from a terminal (`--origin=`, `--api-path=`, `--json`, stdin, `FF_SQL_TOKEN`/`FF_SQL_ORIGIN`); the mint screen now copies the full command, so there is nothing to set up. Tokens can be named automatically (`swift-otter-3f9`); a dead token can be deleted - one by one, or every one of them via `purgeTokens()` - which takes its call log with it, while a revoke keeps it.
+
+## 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

package/bin/args.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @param {string[]} argv
+ * @returns {{ help: boolean, json: boolean, origin?: string, apiPath?: string, sql: string, error?: string }}
+ */
+export function parseArgs(argv: string[]): {
+    help: boolean;
+    json: boolean;
+    origin?: string;
+    apiPath?: string;
+    sql: string;
+    error?: string;
+};

package/bin/args.js

@@ -0,0 +1,66 @@
+// Pure arg parsing for `ff-sql`, split out so it can be tested without running
+// the cli. Plain JS like its caller: bin/ ships unbuilt.
+
+/** Flags that take no value. */
+const BOOLEAN = ['json', 'help']
+/** Flags that need one, as `--x=y` or `--x y`. */
+const VALUED = ['origin', 'api-path']
+
+const camel = { 'api-path': 'apiPath' }
+
+/** `--name` / `--name=value`. `-- comment` is SQL, not a flag. */
+const FLAG = /^--[a-z][\w-]*(=|$)/
+
+/**
+ * @param {string[]} argv
+ * @returns {{ help: boolean, json: boolean, origin?: string, apiPath?: string, sql: string, error?: string }}
+ */
+export function parseArgs(argv) {
+	/** @type {any} */
+	const out = { help: false, json: false, sql: '' }
+	const positional = []
+	const seen = new Set()
+
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]
+		if (arg === '-h') {
+			out.help = true
+			continue
+		}
+		if (arg === '--') {
+			positional.push(...argv.slice(i + 1))
+			break
+		}
+		// A `-- comment` line is SQL: only a flag-shaped token is read as a flag.
+		if (!FLAG.test(arg)) {
+			positional.push(arg)
+			continue
+		}
+		const eq = arg.indexOf('=')
+		const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq)
+		const inline = eq === -1 ? undefined : arg.slice(eq + 1)
+
+		const key = camel[name] ?? name
+		if (seen.has(key)) return { ...out, error: `--${name} given twice` }
+
+		if (BOOLEAN.includes(name)) {
+			// `--json=false` reading as "json on" is the kind of thing nobody debugs twice.
+			if (inline !== undefined) return { ...out, error: `--${name} takes no value` }
+			seen.add(key)
+			out[key] = true
+			continue
+		}
+		if (VALUED.includes(name)) {
+			const value = inline ?? argv[++i]
+			// Without this, `--origin http://x "select 1"` sends "http://x select 1" as SQL.
+			if (!value || FLAG.test(value)) return { ...out, error: `--${name} needs a value` }
+			seen.add(key)
+			out[key] = value
+			continue
+		}
+		return { ...out, error: `unknown flag --${name}` }
+	}
+
+	out.sql = positional.join(' ').trim()
+	return out
+}

package/bin/ff-sql.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// Run SQL against a running app with a firstly sql token (`sqlAdmin({ tokens })`).
+// Plain JS, shipped as-is: it must run from node_modules/.bin with no build step.
+import { Console } from 'node:console'
+import { text } from 'node:stream/consumers'
+
+import { parseArgs } from './args.js'
+
+const HELP = `ff-sql - run SQL through a firstly sql token
+
+  FF_SQL_TOKEN=ffsql_… ff-sql --origin=https://example.com "select 1"
+  ff-sql --json "select * from users limit 3"
+  ff-sql <<'SQL'
+    select handle from "users" where "createdAt" > now() - interval '7 days'
+  SQL
+
+  --json          raw JSON instead of a table
+  --              end of flags, everything after is SQL
+  --origin=URL    the app to query (or FF_SQL_ORIGIN)
+  --api-path=P    remult api root (default /api)
+  --help, -h      this
+
+The app's <SqlTokens /> page hands you the whole command, token included -
+nothing to configure here. Reads run inside a READ ONLY transaction, one
+statement per call. Identifiers usually come from entity classes, so they are
+camelCase and need double quotes: "createdAt", not created_at. A heredoc avoids
+fighting the shell over single quotes, and keeps the token out of the line.`
+
+const TRAILING_SLASH = /\/$/
+
+const cli = parseArgs(process.argv.slice(2))
+
+if (cli.help) {
+	console.info(HELP)
+	process.exit(0)
+}
+if (cli.error) {
+	console.error(`${cli.error}. ff-sql --help`)
+	process.exit(2)
+}
+
+const token = process.env.FF_SQL_TOKEN
+const origin = cli.origin ?? process.env.FF_SQL_ORIGIN
+const apiPath = cli.apiPath ?? '/api'
+
+if (!token) {
+	console.error('FF_SQL_TOKEN missing - mint one in the app (<SqlTokens />). ff-sql --help')
+	process.exit(2)
+}
+if (!origin) {
+	console.error('origin missing - --origin=https://example.com, or FF_SQL_ORIGIN')
+	process.exit(2)
+}
+
+// Only read stdin when there is nothing else to run: on a tty that would hang.
+let cmd = cli.sql
+if (!cmd && !process.stdin.isTTY) cmd = (await text(process.stdin)).trim()
+if (!cmd) {
+	console.error('no sql given. ff-sql --help')
+	process.exit(2)
+}
+
+let res
+try {
+	res = await fetch(`${origin.replace(TRAILING_SLASH, '')}${apiPath}/ff/sqlAdmin/exec`, {
+		method: 'POST',
+		headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+		body: JSON.stringify({ args: [cmd] }),
+	})
+} catch (err) {
+	console.error(`${origin} unreachable: ${err.message}`)
+	process.exit(1)
+}
+
+const body = await res.json().catch(() => null)
+if (!res.ok) {
+	// 403 here is almost always a dead token: expired, revoked, or minted elsewhere.
+	console.error(`${res.status} ${body?.message ?? res.statusText}`)
+	process.exit(1)
+}
+
+const { rows, rowCount, took } = body.data ?? body
+// Table and rows on stdout, the summary on stderr, so `| jq` and `> file` stay clean.
+const out = new Console(process.stdout)
+if (cli.json) out.log(JSON.stringify(rows, null, 2))
+else if (rowCount) out.table(rows)
+console.error(`${rowCount ?? 0} row(s) · ${Math.round(took ?? 0)} ms`)

package/esm/cron/index.d.ts

@@ -1,4 +1,5 @@
 import { Log } from '@kitql/helpers';
+export { Cron } from './Cron';
 export { Roles_Cron } from './Roles_Cron';
 export declare const key = "cron";
 export declare const log: Log;

package/esm/cron/index.js

@@ -1,4 +1,5 @@
 import { Log } from '@kitql/helpers';
+export { Cron } from './Cron';
 export { Roles_Cron } from './Roles_Cron';
 export const key = 'cron';
 export const log = new Log(key);

package/esm/sqlAdmin/SqlAdminController.d.ts

@@ -1,17 +1,87 @@
-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`, deleting
+     * is a plain delete.
+     *
+     * @param name free text, or empty for an `adjective-animal` one.
+     */
+    static mintToken(name: string, capabilities: SqlCapability[], ttl: SqlTokenTtl): Promise<string>;
+    /**
+     * Deletes every token that can no longer be used (expired or revoked), and
+     * their calls. Returns how many were actually deleted: no transaction spans
+     * the loop, so a failure halfway leaves the rest in place.
+     */
+    static purgeTokens(): Promise<number>;
 }

package/esm/sqlAdmin/SqlAdminController.js

@@ -4,41 +4,173 @@ 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;
+/** Retention is a housekeeping sweep, not something to pay for on every query. */
+const CALL_LOG_SWEEP_EVERY_MS = 3_600_000;
+let lastCallLogSweep = 0;
+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();
+        try {
+            // 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 await readOnlySql(db, SqlAdminController.options.tokens?.pool ?? poolFrom(db), cmd);
+        }
+        catch (err) {
+            const { enrichSqlError } = await import('./server/sqlError');
+            throw await enrichSqlError(db, err, 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);
+            if (Date.now() - lastCallLogSweep > CALL_LOG_SWEEP_EVERY_MS) {
+                lastCallLogSweep = Date.now();
+                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`, deleting
+     * is a plain delete.
+     *
+     * @param name free text, or empty for an `adjective-animal` one.
+     */
+    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 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, randomTokenName } = await import('./server/token');
+        const prefix = o.prefix ?? 'ffsql_';
+        const raw = newRawToken(prefix);
+        await repo(SqlToken).insert({
+            name: name.trim() || randomTokenName(),
+            hint: tokenHint(raw, prefix),
+            tokenHash: hashToken(raw),
+            userId,
+            capabilities: unique,
+            expiresAt: new Date(Date.now() + ttlMs),
+        });
+        return raw;
+    }
+    /**
+     * Deletes every token that can no longer be used (expired or revoked), and
+     * their calls. Returns how many were actually deleted: no transaction spans
+     * the loop, so a failure halfway leaves the rest in place.
      */
-    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 purgeTokens() {
+        const dead = await repo(SqlToken).find({
+            where: { $or: [{ revokedAt: { $ne: null } }, { expiresAt: { $lt: new Date() } }] },
         });
-        const took = performance.now() - start;
-        return { rows, rowCount: rows.length, took };
+        // One by one: the cascade to the call log lives in the entity's hooks.
+        let deleted = 0;
+        for (const t of dead) {
+            await repo(SqlToken).delete(t);
+            deleted++;
+        }
+        return deleted;
     }
 }
 __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);
+__decorate([
+    BackendMethod({
+        allowed: () => !!SqlAdminController.options.tokens && !remult.context.sqlToken && remult.isAllowed(SQL_ADMINS),
+        apiPrefix: 'ff/sqlAdmin',
+    })
+], SqlAdminController, "purgeTokens", 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,
     });
 };