@stratum-hq/lib 1.7.0 → 1.8.0

package/dist/migrations/033_api_keys_tenant_index.sql

@@ -0,0 +1,14 @@
+-- Migration 033: Index api_keys.tenant_id.
+--
+-- Listing, revoking and purging a tenant's API keys select by tenant_id, and
+-- `stratum doctor` warns about every tenant_id column without an index. The
+-- column is nullable (global keys), and a plain btree serves both.
+--
+-- Safe to re-run, and safe in every tenant schema of migrateAllSchemas: the
+-- table name is unqualified, so the index is created next to the api_keys
+-- table that the search_path resolves.
+--
+-- This statement blocks writes to api_keys until the index is built. On a
+-- large table, an operator can build it first with CREATE INDEX CONCURRENTLY
+-- and the same name and definition. IF NOT EXISTS then skips this statement.
+CREATE INDEX IF NOT EXISTS idx_api_keys_tenant_id ON api_keys (tenant_id);

package/dist/pinned-query.d.ts

@@ -0,0 +1,29 @@
+import type pg from "pg";
+/**
+ * The search path of the catalog queries that Stratum runs as a privileged
+ * login: a superuser, the admin login of adminPool, or the login that runs
+ * the migrations. PostgreSQL never looks up functions or operators in
+ * pg_temp, so with this path every unqualified function, operator and type
+ * resolves in pg_catalog only, and nothing another role created in a schema
+ * of the caller's search path is chosen in place of a built-in. Queries that
+ * run under it name Stratum objects with their schema.
+ */
+export declare const PINNED_SEARCH_PATH = "pg_catalog, pg_temp";
+/**
+ * Runs `fn` in a transaction on one connection of `pool` whose search_path is
+ * {@link PINNED_SEARCH_PATH} for that transaction. It commits when `fn`
+ * resolves and rolls back when it throws.
+ */
+export declare function withPinnedSearchPath<T>(pool: pg.Pool, fn: (client: pg.PoolClient) => Promise<T>): Promise<T>;
+/** Runs one query with the search path pinned; see {@link withPinnedSearchPath}. */
+export declare function pinnedQuery<R extends pg.QueryResultRow = pg.QueryResultRow>(pool: pg.Pool, text: string, values?: unknown[]): Promise<pg.QueryResult<R>>;
+/**
+ * The schema in which the search path of `db` finds the table `table`
+ * (default tenants), or null when it finds none. Call it on the caller's
+ * search path, before pinning it. Its query names every function, operator
+ * and type with pg_catalog, so it resolves nothing else through that path.
+ */
+export declare function schemaOfTable(db: pg.Pool | pg.PoolClient, table?: string): Promise<string | null>;
+/** A SQL identifier, quoted. */
+export declare function quoteIdentifier(name: string): string;
+//# sourceMappingURL=pinned-query.d.ts.map

package/dist/pinned-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-query.d.ts","sourceRoot":"","sources":["../src/pinned-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAEzB;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AAExD;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAclH;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,CAAC,SAAS,EAAE,CAAC,cAAc,GAAG,EAAE,CAAC,cAAc,EACzE,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAE5B;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,UAAU,EAAE,KAAK,SAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQ1G;AAED,gCAAgC;AAChC,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/pinned-query.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PINNED_SEARCH_PATH = void 0;
+exports.withPinnedSearchPath = withPinnedSearchPath;
+exports.pinnedQuery = pinnedQuery;
+exports.schemaOfTable = schemaOfTable;
+exports.quoteIdentifier = quoteIdentifier;
+/**
+ * The search path of the catalog queries that Stratum runs as a privileged
+ * login: a superuser, the admin login of adminPool, or the login that runs
+ * the migrations. PostgreSQL never looks up functions or operators in
+ * pg_temp, so with this path every unqualified function, operator and type
+ * resolves in pg_catalog only, and nothing another role created in a schema
+ * of the caller's search path is chosen in place of a built-in. Queries that
+ * run under it name Stratum objects with their schema.
+ */
+exports.PINNED_SEARCH_PATH = "pg_catalog, pg_temp";
+/**
+ * Runs `fn` in a transaction on one connection of `pool` whose search_path is
+ * {@link PINNED_SEARCH_PATH} for that transaction. It commits when `fn`
+ * resolves and rolls back when it throws.
+ */
+async function withPinnedSearchPath(pool, fn) {
+    const client = await pool.connect();
+    try {
+        await client.query("BEGIN");
+        await client.query(`SET LOCAL search_path = ${exports.PINNED_SEARCH_PATH}`);
+        const result = await fn(client);
+        await client.query("COMMIT");
+        return result;
+    }
+    catch (err) {
+        await client.query("ROLLBACK").catch(() => undefined);
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
+/** Runs one query with the search path pinned; see {@link withPinnedSearchPath}. */
+function pinnedQuery(pool, text, values) {
+    return withPinnedSearchPath(pool, (client) => client.query(text, values));
+}
+/**
+ * The schema in which the search path of `db` finds the table `table`
+ * (default tenants), or null when it finds none. Call it on the caller's
+ * search path, before pinning it. Its query names every function, operator
+ * and type with pg_catalog, so it resolves nothing else through that path.
+ */
+async function schemaOfTable(db, table = "tenants") {
+    const res = await db.query(`SELECT n.nspname::pg_catalog.text AS nsp
+       FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid OPERATOR(pg_catalog.=) c.relnamespace
+      WHERE c.oid OPERATOR(pg_catalog.=) pg_catalog.to_regclass($1::pg_catalog.text)::pg_catalog.oid`, [table]);
+    return res.rows[0]?.nsp ?? null;
+}
+/** A SQL identifier, quoted. */
+function quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+//# sourceMappingURL=pinned-query.js.map

package/dist/pinned-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-query.js","sourceRoot":"","sources":["../src/pinned-query.ts"],"names":[],"mappings":";;;AAkBA,oDAcC;AAGD,kCAMC;AAQD,sCAQC;AAGD,0CAEC;AA5DD;;;;;;;;GAQG;AACU,QAAA,kBAAkB,GAAG,qBAAqB,CAAC;AAExD;;;;GAIG;AACI,KAAK,UAAU,oBAAoB,CAAI,IAAa,EAAE,EAAyC;IACpG,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,MAAM,CAAC,KAAK,CAAC,2BAA2B,0BAAkB,EAAE,CAAC,CAAC;QACpE,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;QAChC,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACtD,MAAM,GAAG,CAAC;IACZ,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,SAAgB,WAAW,CACzB,IAAa,EACb,IAAY,EACZ,MAAkB;IAElB,OAAO,oBAAoB,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAI,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,aAAa,CAAC,EAA2B,EAAE,KAAK,GAAG,SAAS;IAChF,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,KAAK,CACxB;;qGAEiG,EACjG,CAAC,KAAK,CAAC,CACR,CAAC;IACF,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC;AAClC,CAAC;AAED,gCAAgC;AAChC,SAAgB,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;AACzC,CAAC"}

package/dist/pool-helpers.d.ts

@@ -1,4 +1,6 @@
 import pg from "pg";
+/** Marks `pool` as an admin pool: the helpers do not set app.bypass_rls on it. */
+export declare function markAdminPool(pool: pg.Pool): void;
 export declare function withClient<T>(pool: pg.Pool, fn: (client: pg.PoolClient) => Promise<T>): Promise<T>;
 export declare function withTransaction<T>(pool: pg.Pool, fn: (client: pg.PoolClient) => Promise<T>): Promise<T>;
 //# sourceMappingURL=pool-helpers.d.ts.map

package/dist/pool-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pool-helpers.d.ts","sourceRoot":"","sources":["../src/pool-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AAuCpB,wBAAsB,UAAU,CAAC,CAAC,EAChC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GACxC,OAAO,CAAC,CAAC,CAAC,CAeZ;AAED,wBAAsB,eAAe,CAAC,CAAC,EACrC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GACxC,OAAO,CAAC,CAAC,CAAC,CAeZ"}
+{"version":3,"file":"pool-helpers.d.ts","sourceRoot":"","sources":["../src/pool-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AA0BpB,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,IAAI,CAEjD;AAwBD,wBAAsB,UAAU,CAAC,CAAC,EAChC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GACxC,OAAO,CAAC,CAAC,CAAC,CAeZ;AAED,wBAAsB,eAAe,CAAC,CAAC,EACrC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GACxC,OAAO,CAAC,CAAC,CAAC,CAeZ"}

package/dist/pool-helpers.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.markAdminPool = markAdminPool;
 exports.withClient = withClient;
 exports.withTransaction = withTransaction;
 // The Stratum library is the trusted CONTROL PLANE: it manages the whole tenant
@@ -17,7 +18,20 @@ exports.withTransaction = withTransaction;
 //
 // This is the single chokepoint for all lib database access: every service goes
 // through withClient / withTransaction, so no service function needs to change.
-async function enterBypass(client) {
+//
+// A pool given to Stratum as `adminPool` logs in as a member of the control
+// role (migration 032), whose stratum_control_plane policies admit every row.
+// Such a pool needs no bypass setting, so the helpers do not set it there. A
+// misconfigured admin login then fails closed instead of falling back on the
+// legacy setting.
+const adminPools = new WeakSet();
+/** Marks `pool` as an admin pool: the helpers do not set app.bypass_rls on it. */
+function markAdminPool(pool) {
+    adminPools.add(pool);
+}
+async function enterBypass(pool, client) {
+    if (adminPools.has(pool))
+        return;
     // SET LOCAL (not session SET) so the flag is transaction scoped and cannot
     // leak across pooled connections. Equivalent to
     // set_config('app.bypass_rls', 'on', true).
@@ -42,7 +56,7 @@ async function withClient(pool, fn) {
     let rollbackErr;
     try {
         await client.query("BEGIN");
-        await enterBypass(client);
+        await enterBypass(pool, client);
         const result = await fn(client);
         await client.query("COMMIT");
         return result;
@@ -60,7 +74,7 @@ async function withTransaction(pool, fn) {
     let rollbackErr;
     try {
         await client.query("BEGIN");
-        await enterBypass(client);
+        await enterBypass(pool, client);
         const result = await fn(client);
         await client.query("COMMIT");
         return result;

package/dist/pool-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"pool-helpers.js","sourceRoot":"","sources":["../src/pool-helpers.ts"],"names":[],"mappings":";;AAuCA,gCAkBC;AAED,0CAkBC;AA3ED,gFAAgF;AAChF,4EAA4E;AAC5E,8EAA8E;AAC9E,iFAAiF;AACjF,wBAAwB;AACxB,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,+EAA+E;AAC/E,gFAAgF;AAChF,iEAAiE;AACjE,kDAAkD;AAClD,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAEhF,KAAK,UAAU,WAAW,CAAC,MAAqB;IAC9C,2EAA2E;IAC3E,gDAAgD;IAChD,4CAA4C;IAC5C,MAAM,MAAM,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;AACxD,CAAC;AAED,2EAA2E;AAC3E,4EAA4E;AAC5E,yEAAyE;AACzE,6EAA6E;AAC7E,6BAA6B;AAC7B,KAAK,UAAU,QAAQ,CAAC,MAAqB;IAC3C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAC/B,OAAO,SAAS,CAAC;IACnB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC;AAEM,KAAK,UAAU,UAAU,CAC9B,IAAa,EACb,EAAyC;IAEzC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACpC,IAAI,WAA8B,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;QAC1B,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;QAChC,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,WAAW,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC;QACrC,MAAM,GAAG,CAAC;IACZ,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC;AAEM,KAAK,UAAU,eAAe,CACnC,IAAa,EACb,EAAyC;IAEzC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACpC,IAAI,WAA8B,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;QAC1B,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;QAChC,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,WAAW,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC;QACrC,MAAM,GAAG,CAAC;IACZ,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC"}
+{"version":3,"file":"pool-helpers.js","sourceRoot":"","sources":["../src/pool-helpers.ts"],"names":[],"mappings":"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"}

package/dist/role-model.d.ts

@@ -0,0 +1,178 @@
+import type pg from "pg";
+import type { StratumLogger } from "./logger.js";
+/**
+ * The role model of migration 032.
+ *
+ * - The control role (default stratum_control) is NOLOGIN. Every Stratum
+ *   table has a stratum_control_plane policy for it, and it owns the
+ *   SECURITY DEFINER helpers.
+ * - The admin login backs the library's adminPool. It is a member of the
+ *   control role (INHERIT), owns the Stratum objects and runs the migrations.
+ *   It needs neither SUPERUSER nor BYPASSRLS.
+ * - The application login is not a member of the control role, owns nothing
+ *   of Stratum's, and may read only the tables in APP_READ_TABLES.
+ */
+/** The Stratum tables the application role may read; it may write none. */
+export declare const APP_READ_TABLES: readonly string[];
+/**
+ * The md5 of the body (pg_proc.prosrc) of each Stratum function that
+ * stratum_apply_control_role() does not re-create, as the migrations define
+ * it last. A unit test derives them from the migration files.
+ */
+export declare const STRATUM_FUNCTION_BODY_MD5: Readonly<Record<string, string>>;
+export interface BootstrapRolesOptions {
+    /** The admin login to make a member of the control role. Omit to skip that grant. */
+    adminRole?: string;
+    /** The application login to limit to the recommended grants. Omit to skip that section. */
+    appRole?: string;
+    /** The control role. Default `stratum_control`. */
+    controlRole?: string;
+    /** The schema of the Stratum tables. Default `public`. */
+    schema?: string;
+}
+/**
+ * The SQL a database administrator runs to set up the role model, as a
+ * superuser, or a role with CREATEROLE that owns the Stratum tables. It is
+ * idempotent.
+ *
+ * - Creates the NOLOGIN control role when it does not exist, and lets it use
+ *   and create objects in the schema (it owns the 032 helpers).
+ * - With `adminRole`: makes the admin login a member of the control role
+ *   (WITH INHERIT TRUE, SET TRUE on PostgreSQL 16 and later), and moves the
+ *   Stratum tables and functions that `appRole` owns to it.
+ * - Applies the control role to the Stratum objects through
+ *   stratum_apply_control_role() of migration 032, when it exists. This is
+ *   what activates the hardening when the migration could not (its migrating
+ *   role could neither create nor join the control role). It needs a
+ *   superuser or the owner of the Stratum tables.
+ * - Revokes CREATE on the schema from PUBLIC, and with `appRole` from the
+ *   application login, so that only roles granted CREATE by name can add
+ *   objects to the schema of the Stratum tables.
+ * - With `appRole`: removes the application login from the control role,
+ *   revokes its privileges on every Stratum table, and grants it SELECT on
+ *   the read-list tables only. This part acts on the tables that exist, so
+ *   run it again after a migration that adds a table.
+ *
+ * The login roles themselves, with their passwords, are yours to create.
+ *
+ * @throws Error when a name is not a plain lowercase identifier.
+ */
+export declare function bootstrapRolesSql(options?: BootstrapRolesOptions): string;
+/**
+ * The PL/pgSQL statements of the integrity check: they collect, in
+ * v_problems (text[]), the objects of the schema v_ns (oid) that the Stratum
+ * migrations did not put there. Whoever owned the Stratum tables before
+ * (often the application login) could have attached them, and they would run
+ * with the rights of whoever writes to the tables later: the admin login, the
+ * migrating role, or a superuser. They check, in that schema:
+ *
+ * - every Stratum relation (STRATUM_TABLES, _migrations included) is a table;
+ * - no rule is attached to one of them;
+ * - every trigger calls a Stratum function;
+ * - policies, column defaults, constraints, triggers and indexes of them
+ *   call only functions and operators of pg_catalog, of an extension, or of
+ *   Stratum;
+ * - every column has a type of pg_catalog or of an extension;
+ * - the schema holds no operator, and no function or aggregate named like a
+ *   function of pg_catalog or of an extension, other than those of
+ *   extensions and of Stratum. Such an object can be chosen in place of the
+ *   built-in one by a query that has the schema on its search path;
+ * - the Stratum functions that stratum_apply_control_role() does not
+ *   re-create have the bodies the migrations give them, and
+ *   stratum_apply_control_role() itself is SECURITY INVOKER with its pinned
+ *   search_path.
+ *
+ * They expect the variables v_ns oid, v_tables text[], v_functions text[],
+ * v_problems text[] and r record, and run with search_path = pg_catalog,
+ * pg_temp. bootstrapRolesSql() raises when they find anything; migration 032
+ * renders the same statements (a unit test keeps them identical) and then
+ * warns and leaves the control role unapplied.
+ */
+export declare function integrityChecksPlpgsql(): string;
+/** The login of `pool`. */
+export declare function currentLogin(pool: pg.Pool): Promise<string>;
+export interface RoleModelCheckOptions {
+    /** The library's admin pool, or undefined in the legacy single-pool mode. */
+    adminPool?: pg.Pool;
+    appPool: pg.Pool;
+    /** The configured control role, or undefined to use the database's. */
+    controlRole?: string;
+    /** Throw, instead of warn, when the application role is misconfigured. */
+    strict: boolean;
+    logger: StratumLogger;
+}
+/**
+ * Reports whether the control-role hardening of migration 032 is active and,
+ * with an adminPool, checks the admin and application logins against the
+ * role model, warning about each problem. With `strict`, a misconfigured
+ * application login throws instead. In every mode it reports an
+ * application login that can create objects in the schema of the Stratum
+ * tables; with an adminPool and `strict` that is an error too. With an
+ * adminPool it also warns when a schema the application login can create
+ * would come first on the admin login's search path.
+ */
+export declare function checkRoleModel(options: RoleModelCheckOptions): Promise<void>;
+/** What {@link inspectRoleModel} found. */
+export interface RoleModelReport {
+    /** Whether migration 032 ran (the stratum_security table exists). */
+    migrated: boolean;
+    /** Whether the control role is applied: stratum_control_plane policies exist. */
+    hardeningActive: boolean;
+    /** The control role checked against: the option, else the database's, else the default. */
+    controlRole: string;
+    /** Problems with the admin login, or null when no adminPool was given. */
+    adminIssues: string[] | null;
+    /** Problems with the application login, or null when no appPool was given. */
+    appIssues: string[] | null;
+    /**
+     * Whether the legacy app.bypass_rls switch is on. Null when it cannot be
+     * read: before 032, without an adminPool, or when the admin login cannot
+     * see the stratum_security row.
+     */
+    legacyBypass: boolean | null;
+    /**
+     * The roles, other than superusers, that are members of the control role,
+     * directly or through another role. Only the library's admin login (and
+     * roles you chose to give the control plane's rights) should be listed.
+     */
+    controlMembers: {
+        role: string;
+        login: boolean;
+    }[];
+    /** The admin login that was checked, or null when none was given. */
+    adminLogin: string | null;
+    /**
+     * Why a schema the application login can create would come first on the
+     * admin login's search path ("$user"), or null when it would not or when
+     * either login was not given.
+     */
+    searchPathIssue: string | null;
+}
+export interface InspectRoleModelOptions {
+    /** A pool that logs in as the application login, which is checked. */
+    appPool?: pg.Pool;
+    /** A pool that logs in as the admin login, which is checked. */
+    adminPool?: pg.Pool;
+    /**
+     * A pool to read the catalog through when the logins are given by name
+     * (`appRole`, `adminRole`), for example a superuser's.
+     */
+    pool?: pg.Pool;
+    /** Check this application role by name, through `pool`, instead of the login of `appPool`. */
+    appRole?: string;
+    /** Check this admin role by name, through `pool`, instead of the login of `adminPool`. */
+    adminRole?: string;
+    /** The control role. Default: the database's, else `stratum_control`. */
+    controlRole?: string;
+}
+/**
+ * Checks the logins of a database against the role model of migration 032,
+ * without logging or throwing. `stratum health`, `stratum doctor` and
+ * `stratum db roles` use it; Stratum.initialize() applies the same checks.
+ */
+export declare function inspectRoleModel(options: InspectRoleModelOptions): Promise<RoleModelReport>;
+/** Warns once per process that Stratum runs without an adminPool. */
+export declare function warnNoAdminPool(logger: StratumLogger): void;
+/** Warns once per process that an API key with a legacy SHA-256 hash authenticated. */
+export declare function warnLegacyKeyHash(logger: StratumLogger): void;
+//# sourceMappingURL=role-model.d.ts.map

package/dist/role-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-model.d.ts","sourceRoot":"","sources":["../src/role-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAKjD;;;;;;;;;;;GAWG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAY3C,CAAC;AAiBH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKrE,CAAC;AAEH,MAAM,WAAW,qBAAqB;IACpC,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAkG7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAwG/C;AA2MD,2BAA2B;AAC3B,wBAAsB,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAGjE;AA8FD,MAAM,WAAW,qBAAqB;IACpC,6EAA6E;IAC7E,SAAS,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;IACpB,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC;IACjB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4DlF;AAED,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,QAAQ,EAAE,OAAO,CAAC;IAClB,iFAAiF;IACjF,eAAe,EAAE,OAAO,CAAC;IACzB,2FAA2F;IAC3F,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC7B,8EAA8E;IAC9E,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3B;;;;OAIG;IACH,YAAY,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,cAAc,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IACnD,qEAAqE;IACrE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;OAIG;IACH,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,uBAAuB;IACtC,sEAAsE;IACtE,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;IAClB,gEAAgE;IAChE,SAAS,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;IACf,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,eAAe,CAAC,CA0BjG;AAID,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAQ3D;AAID,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAQ7D"}