@stratum-hq/lib 1.6.0 → 1.8.0

package/dist/migrate.js

@@ -3,14 +3,42 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertRoleSubjectToRls = assertRoleSubjectToRls;
 exports.migrate = migrate;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const migration_sql_js_1 = require("./migration-sql.js");
+const pinned_query_js_1 = require("./pinned-query.js");
+/**
+ * Throws when the connecting role has BYPASSRLS, so row-level security would
+ * not apply to it. Used by every enforceRls entry point, so the check does not
+ * depend on migration 001 running.
+ */
+async function assertRoleSubjectToRls(pool) {
+    const { rows } = await pool.query("SELECT current_user AS role, rolbypassrls AS bypass FROM pg_catalog.pg_roles WHERE rolname = current_user");
+    if (rows[0]?.bypass) {
+        throw new Error(`SECURITY: Application role "${rows[0].role}" has BYPASSRLS privilege. ` +
+            "Connect as a dedicated role without BYPASSRLS, or turn enforceRls off for development.");
+    }
+}
 async function migrate(options) {
-    const { pool, enforceRls } = options;
+    const { pool, enforceRls, controlRole, applyControlRole } = options;
+    if (controlRole !== undefined)
+        (0, migration_sql_js_1.assertRoleName)(controlRole, "control role");
+    if (enforceRls) {
+        await assertRoleSubjectToRls(pool);
+    }
+    // The migrations create their objects in the first schema of the search
+    // path; the tracking table lives there too, named with that schema.
+    const current = await pool.query("SELECT pg_catalog.current_schema() AS schema");
+    const schema = current.rows[0]?.schema;
+    if (!schema) {
+        throw new Error("[stratum] migrate: no schema on the search path of the migrating login to create the Stratum tables in");
+    }
+    const migrationsTable = `${(0, pinned_query_js_1.quoteIdentifier)(schema)}._migrations`;
     // Create migrations tracking table
     await pool.query(`
-    CREATE TABLE IF NOT EXISTS _migrations (
+    CREATE TABLE IF NOT EXISTS ${migrationsTable} (
       id SERIAL PRIMARY KEY,
       name TEXT NOT NULL UNIQUE,
       applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
@@ -25,14 +53,22 @@ async function migrate(options) {
         .readdirSync(migrationsDir)
         .filter((f) => f.endsWith(".sql"))
         .sort();
+    // Migrations 029 and 031 created helper functions with `SET app.*` clauses,
+    // which PostgreSQL accepts only from a superuser (or a role granted SET on
+    // the parameter). For any other migrating role, migrationSql() drops those
+    // clause lines from these two files only; migration 032 then re-creates
+    // both functions without them when it applies the control role. Until it
+    // does, they see only what their caller sees, which can only narrow what
+    // they return. See migration-sql.ts.
+    const superuser = await (0, migration_sql_js_1.isSuperuser)(pool);
     for (const file of files) {
         const client = await pool.connect();
         try {
             await client.query("BEGIN");
             // Acquire advisory lock to prevent concurrent migrations
-            await client.query("SELECT pg_advisory_xact_lock(8675309)");
+            await client.query("SELECT pg_catalog.pg_advisory_xact_lock(8675309::pg_catalog.int8)");
             // Re-check if already applied (after lock, to prevent TOCTOU race)
-            const { rows } = await client.query("SELECT 1 FROM _migrations WHERE name = $1", [file]);
+            const { rows } = await client.query(`SELECT 1 FROM ${migrationsTable} WHERE name = $1`, [file]);
             if (rows.length > 0) {
                 await client.query("COMMIT");
                 continue;
@@ -41,9 +77,11 @@ async function migrate(options) {
             if (enforceRls) {
                 await client.query("SET LOCAL stratum.enforce_rls = 'on'");
             }
-            const sql = node_fs_1.default.readFileSync(node_path_1.default.join(migrationsDir, file), "utf-8");
+            await (0, migration_sql_js_1.setControlRole)(client, controlRole);
+            await (0, migration_sql_js_1.setApplyControlRole)(client, applyControlRole);
+            const sql = (0, migration_sql_js_1.migrationSql)(file, node_fs_1.default.readFileSync(node_path_1.default.join(migrationsDir, file), "utf-8"), superuser);
             await client.query(sql);
-            await client.query("INSERT INTO _migrations (name) VALUES ($1)", [file]);
+            await client.query(`INSERT INTO ${migrationsTable} (name) VALUES ($1)`, [file]);
             await client.query("COMMIT");
         }
         catch (err) {

package/dist/migrate.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":";;;;;AAUA,0BA2DC;AArED,sDAAyB;AACzB,0DAA6B;AAStB,KAAK,UAAU,OAAO,CAAC,OAAuB;IACnD,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAErC,mCAAmC;IACnC,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;GAMhB,CAAC,CAAC;IAEH,sBAAsB;IACtB,MAAM,aAAa,GAAG,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAC5D,IAAI,CAAC,iBAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,gCAAgC,aAAa,sDAAsD,CACpG,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,iBAAE;SACb,WAAW,CAAC,aAAa,CAAC;SAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;SACjC,IAAI,EAAE,CAAC;IAEV,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAE5B,yDAAyD;YACzD,MAAM,MAAM,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;YAE5D,mEAAmE;YACnE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,KAAK,CACjC,2CAA2C,EAC3C,CAAC,IAAI,CAAC,CACP,CAAC;YACF,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpB,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAC7B,SAAS;YACX,CAAC;YAED,wCAAwC;YACxC,IAAI,UAAU,EAAE,CAAC;gBACf,MAAM,MAAM,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;YAC7D,CAAC;YAED,MAAM,GAAG,GAAG,iBAAE,CAAC,YAAY,CAAC,mBAAI,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;YACrE,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACxB,MAAM,MAAM,CAAC,KAAK,CAAC,4CAA4C,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;YACzE,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC;gBAAC,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,6BAA6B,CAAC,CAAC;YAC/E,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":";;;;;AAmCA,wDAUC;AAED,0BAoFC;AAnID,sDAAyB;AACzB,0DAA6B;AAE7B,yDAAoH;AACpH,uDAAoD;AA0BpD;;;;GAIG;AACI,KAAK,UAAU,sBAAsB,CAAC,IAAa;IACxD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAC/B,2GAA2G,CAC5G,CAAC;IACF,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,+BAA+B,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,6BAA6B;YACtE,wFAAwF,CAC3F,CAAC;IACJ,CAAC;AACH,CAAC;AAEM,KAAK,UAAU,OAAO,CAAC,OAAuB;IACnD,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC;IACpE,IAAI,WAAW,KAAK,SAAS;QAAE,IAAA,iCAAc,EAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IAE3E,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,sBAAsB,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,wEAAwE;IACxE,oEAAoE;IACpE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,CAA4B,8CAA8C,CAAC,CAAC;IAC5G,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IACvC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,wGAAwG,CAAC,CAAC;IAC5H,CAAC;IACD,MAAM,eAAe,GAAG,GAAG,IAAA,iCAAe,EAAC,MAAM,CAAC,cAAc,CAAC;IAEjE,mCAAmC;IACnC,MAAM,IAAI,CAAC,KAAK,CAAC;iCACc,eAAe;;;;;GAK7C,CAAC,CAAC;IAEH,sBAAsB;IACtB,MAAM,aAAa,GAAG,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAC5D,IAAI,CAAC,iBAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,gCAAgC,aAAa,sDAAsD,CACpG,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,iBAAE;SACb,WAAW,CAAC,aAAa,CAAC;SAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;SACjC,IAAI,EAAE,CAAC;IAEV,4EAA4E;IAC5E,2EAA2E;IAC3E,2EAA2E;IAC3E,wEAAwE;IACxE,yEAAyE;IACzE,yEAAyE;IACzE,qCAAqC;IACrC,MAAM,SAAS,GAAG,MAAM,IAAA,8BAAW,EAAC,IAAI,CAAC,CAAC;IAE1C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAE5B,yDAAyD;YACzD,MAAM,MAAM,CAAC,KAAK,CAAC,mEAAmE,CAAC,CAAC;YAExF,mEAAmE;YACnE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,KAAK,CACjC,iBAAiB,eAAe,kBAAkB,EAClD,CAAC,IAAI,CAAC,CACP,CAAC;YACF,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpB,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAC7B,SAAS;YACX,CAAC;YAED,wCAAwC;YACxC,IAAI,UAAU,EAAE,CAAC;gBACf,MAAM,MAAM,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;YAC7D,CAAC;YACD,MAAM,IAAA,iCAAc,EAAC,MAAM,EAAE,WAAW,CAAC,CAAC;YAC1C,MAAM,IAAA,sCAAmB,EAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;YAEpD,MAAM,GAAG,GAAG,IAAA,+BAAY,EAAC,IAAI,EAAE,iBAAE,CAAC,YAAY,CAAC,mBAAI,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC;YACpG,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACxB,MAAM,MAAM,CAAC,KAAK,CAAC,eAAe,eAAe,qBAAqB,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;YAChF,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC;gBAAC,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,6BAA6B,CAAC,CAAC;YAC/E,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/migration-sql.d.ts

@@ -0,0 +1,25 @@
+import type pg from "pg";
+/** The default name of the NOLOGIN control role (migration 032). */
+export declare const STRATUM_CONTROL_ROLE = "stratum_control";
+/** A role name Stratum accepts: a plain lowercase identifier. */
+export declare const ROLE_NAME: RegExp;
+/** Throws when `role` is not a plain lowercase identifier. */
+export declare function assertRoleName(role: string, what: string): void;
+/** The SQL to run for one migration file. */
+export declare function migrationSql(name: string, sql: string, superuser: boolean): string;
+/** Whether the role of `client` is a superuser. */
+export declare function isSuperuser(client: pg.PoolClient | pg.Pool): Promise<boolean>;
+/**
+ * Sets stratum.control_role for the current transaction, which migration 032
+ * reads. Without a name the setting stays as the session has it.
+ */
+export declare function setControlRole(client: pg.PoolClient, controlRole: string | undefined): Promise<void>;
+/**
+ * Sets stratum.apply_control_role = 'on' for the current transaction when
+ * `apply` is true. Migration 032 grants the control role to the migrating
+ * login only with this opt-in (or when the login is a superuser or already a
+ * member), because that login must be the library's admin login and never
+ * the application's.
+ */
+export declare function setApplyControlRole(client: pg.PoolClient, apply: boolean | undefined): Promise<void>;
+//# sourceMappingURL=migration-sql.d.ts.map

package/dist/migration-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-sql.d.ts","sourceRoot":"","sources":["../src/migration-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAEzB,oEAAoE;AACpE,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD,iEAAiE;AACjE,eAAO,MAAM,SAAS,QAA4B,CAAC;AAEnD,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAI/D;AAgBD,6CAA6C;AAC7C,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAGlF;AAED,mDAAmD;AACnD,wBAAsB,WAAW,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,GAAG,EAAE,CAAC,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAKnF;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1G;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1G"}

package/dist/migration-sql.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLE_NAME = exports.STRATUM_CONTROL_ROLE = void 0;
+exports.assertRoleName = assertRoleName;
+exports.migrationSql = migrationSql;
+exports.isSuperuser = isSuperuser;
+exports.setControlRole = setControlRole;
+exports.setApplyControlRole = setApplyControlRole;
+/** The default name of the NOLOGIN control role (migration 032). */
+exports.STRATUM_CONTROL_ROLE = "stratum_control";
+/** A role name Stratum accepts: a plain lowercase identifier. */
+exports.ROLE_NAME = /^[a-z_][a-z0-9_]{0,62}$/;
+/** Throws when `role` is not a plain lowercase identifier. */
+function assertRoleName(role, what) {
+    if (!exports.ROLE_NAME.test(role)) {
+        throw new Error(`[stratum] Invalid ${what} '${role}': use lowercase letters, digits and underscores`);
+    }
+}
+// Migrations 029 and 031 created their helper functions with
+// `SET app.bypass_rls = 'on'` (and `SET app.tenant_scope = ''`) clauses.
+// PostgreSQL lets only a superuser, or a role granted SET on the parameter,
+// put a custom setting in a function, so a fresh install by a role that is
+// not a superuser stopped at 029. For such a role the runner drops the
+// clauses from these two files. Migration 032 re-creates both functions
+// without them (SECURITY DEFINER, owned by the control role) when it applies
+// the control role, in the same run or later through
+// stratum_apply_control_role(). Until then the functions see what their
+// caller sees, which can only narrow what they return. A superuser runs the
+// files as they are.
+const SUPERSEDED_SET_CLAUSES = new Set(["029_tenant_parent_cycle_guard.sql", "031_subtree_read_scope.sql"]);
+const APP_SET_CLAUSE = /^SET app\.[a-z_]+ = '[^']*'\n/gm;
+/** The SQL to run for one migration file. */
+function migrationSql(name, sql, superuser) {
+    if (superuser || !SUPERSEDED_SET_CLAUSES.has(name))
+        return sql;
+    return sql.replace(APP_SET_CLAUSE, "");
+}
+/** Whether the role of `client` is a superuser. */
+async function isSuperuser(client) {
+    const res = await client.query("SELECT rolsuper FROM pg_catalog.pg_roles WHERE rolname = current_user");
+    return res.rows[0]?.rolsuper === true;
+}
+/**
+ * Sets stratum.control_role for the current transaction, which migration 032
+ * reads. Without a name the setting stays as the session has it.
+ */
+async function setControlRole(client, controlRole) {
+    if (controlRole === undefined)
+        return;
+    await client.query("SELECT pg_catalog.set_config('stratum.control_role', $1, true)", [controlRole]);
+}
+/**
+ * Sets stratum.apply_control_role = 'on' for the current transaction when
+ * `apply` is true. Migration 032 grants the control role to the migrating
+ * login only with this opt-in (or when the login is a superuser or already a
+ * member), because that login must be the library's admin login and never
+ * the application's.
+ */
+async function setApplyControlRole(client, apply) {
+    if (!apply)
+        return;
+    await client.query("SELECT pg_catalog.set_config('stratum.apply_control_role', 'on', true)");
+}
+//# sourceMappingURL=migration-sql.js.map

package/dist/migration-sql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-sql.js","sourceRoot":"","sources":["../src/migration-sql.ts"],"names":[],"mappings":";;;AASA,wCAIC;AAiBD,oCAGC;AAGD,kCAKC;AAMD,wCAGC;AASD,kDAGC;AA5DD,oEAAoE;AACvD,QAAA,oBAAoB,GAAG,iBAAiB,CAAC;AAEtD,iEAAiE;AACpD,QAAA,SAAS,GAAG,yBAAyB,CAAC;AAEnD,8DAA8D;AAC9D,SAAgB,cAAc,CAAC,IAAY,EAAE,IAAY;IACvD,IAAI,CAAC,iBAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,KAAK,IAAI,kDAAkD,CAAC,CAAC;IACxG,CAAC;AACH,CAAC;AAED,6DAA6D;AAC7D,yEAAyE;AACzE,4EAA4E;AAC5E,2EAA2E;AAC3E,uEAAuE;AACvE,wEAAwE;AACxE,6EAA6E;AAC7E,qDAAqD;AACrD,wEAAwE;AACxE,4EAA4E;AAC5E,qBAAqB;AACrB,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC,CAAC,mCAAmC,EAAE,4BAA4B,CAAC,CAAC,CAAC;AAC5G,MAAM,cAAc,GAAG,iCAAiC,CAAC;AAEzD,6CAA6C;AAC7C,SAAgB,YAAY,CAAC,IAAY,EAAE,GAAW,EAAE,SAAkB;IACxE,IAAI,SAAS,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC;IAC/D,OAAO,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,mDAAmD;AAC5C,KAAK,UAAU,WAAW,CAAC,MAA+B;IAC/D,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAC5B,uEAAuE,CACxE,CAAC;IACF,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,CAAC;AACxC,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,cAAc,CAAC,MAAqB,EAAE,WAA+B;IACzF,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO;IACtC,MAAM,MAAM,CAAC,KAAK,CAAC,gEAAgE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;AACtG,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,mBAAmB,CAAC,MAAqB,EAAE,KAA0B;IACzF,IAAI,CAAC,KAAK;QAAE,OAAO;IACnB,MAAM,MAAM,CAAC,KAAK,CAAC,wEAAwE,CAAC,CAAC;AAC/F,CAAC"}

package/dist/migrations/001_init.sql

@@ -2,13 +2,13 @@
 DO $$ BEGIN
   CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
 EXCEPTION WHEN insufficient_privilege THEN
-  RAISE WARNING 'Cannot create uuid-ossp extension — insufficient privileges. Ask a database administrator to run: CREATE EXTENSION IF NOT EXISTS "uuid-ossp";';
+  RAISE WARNING 'Cannot create uuid-ossp extension: insufficient privileges. Ask a database administrator to run: CREATE EXTENSION IF NOT EXISTS "uuid-ossp";';
 END $$;
 
 DO $$ BEGIN
   CREATE EXTENSION IF NOT EXISTS "ltree";
 EXCEPTION WHEN insufficient_privilege THEN
-  RAISE WARNING 'Cannot create ltree extension — insufficient privileges. Ask a database administrator to run: CREATE EXTENSION IF NOT EXISTS "ltree";';
+  RAISE WARNING 'Cannot create ltree extension: insufficient privileges. Ask a database administrator to run: CREATE EXTENSION IF NOT EXISTS "ltree";';
 END $$;
 
 -- Warn if application role has BYPASSRLS privilege.
@@ -127,7 +127,7 @@ CREATE TRIGGER update_config_entries_updated_at
   FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
 
 -- Config entries uses ON DELETE CASCADE (unlike permission_policies which uses RESTRICT)
--- because config values are safe to delete with a tenant — they carry no semantic guarantees
+-- because config values are safe to delete with a tenant; they carry no semantic guarantees
 -- like PERMANENT revocation mode. If soft-delete is used (v1 default), CASCADE never fires.
 
 -- API keys table (for control plane auth)

package/dist/migrations/029_tenant_parent_cycle_guard.sql

@@ -48,9 +48,9 @@ END;
 $$ language 'plpgsql';
 
 DO $pin$ BEGIN
-  EXECUTE format(
+  EXECUTE pg_catalog.format(
     'ALTER FUNCTION refuse_tenant_parent_cycle() SET search_path = pg_catalog, %I',
-    current_schema()
+    pg_catalog.current_schema()
   );
 END $pin$;
 

package/dist/migrations/031_subtree_read_scope.sql

@@ -0,0 +1,307 @@
+-- Migration 031: Opt-in subtree read scope for row-level security.
+--
+-- A session scoped to tenant T can opt in to read the rows of T and of every
+-- descendant of T. The default stays exact-tenant isolation (019, 020).
+--
+-- Context model, in addition to 019:
+--   * Subtree scope: SET LOCAL app.tenant_scope = 'subtree' (transaction
+--     scoped). Only the exact value 'subtree' widens reads. The library sets it
+--     only through its context helpers (db-adapters setTenantContext and
+--     withTenantContext with { scope: 'subtree' }).
+--
+-- Reads only. Each table below gets a second permissive policy, tenant_subtree_read,
+-- FOR SELECT. PostgreSQL ORs it with tenant_isolation for reads. INSERT,
+-- UPDATE and DELETE must also pass the policies for their own command, and
+-- tenant_isolation is the only one. Writes therefore stay limited to the exact
+-- tenant: an insert for a descendant fails WITH CHECK, and UPDATE and DELETE
+-- do not reach a descendant's rows. SELECT ... FOR UPDATE and FOR SHARE also
+-- need the UPDATE policy, so in subtree scope they return the exact tenant's
+-- rows only. The 019 and 020 policies do not change.
+--
+-- Tables with a subtree read policy:
+--   tenants (on id), config_entries (rows with sensitive = false only),
+--   permission_policies, audit_logs, webhook_events, consent_records,
+--   abac_policies, roles, usage_events, and, through their parent row,
+--   webhook_deliveries (via webhook_events) and principal_roles (via roles).
+--
+-- Credential-bearing rows stay exact-tenant. api_keys and webhooks get no
+-- subtree policy, and the config_entries policy admits no row with
+-- sensitive = true. A key row holds a key hash, a webhook row holds a signing
+-- secret hash and a URL that can carry credentials, and a sensitive config
+-- row holds a secret value. Their 019 policies stay the only ones that admit
+-- a tenant session, so only the exact tenant reads them. webhook_deliveries
+-- is scoped through webhook_events, not webhooks, so it gives no subtree path
+-- to a webhook row.
+--
+-- Tenant status does not affect the scope. Suspended, archived and pending
+-- descendants are in the subtree, as exact-tenant RLS ignores status too.
+-- Applications filter by status when they need to.
+--
+-- The bypass (app.bypass_rls = 'on') does not change: it sees every row.
+--
+-- The scope follows the tree as it is when the statement runs: a move through
+-- moveTenant changes the subtree at once. The tree columns of tenants change
+-- only under the bypass (see guard_tenant_tree_columns below), so a tenant
+-- session cannot change its own position in the tree.
+--
+-- Cost: the function runs once per policy reference in a statement, and its
+-- result grows with the size of the subtree. Each table then matches tenant_id
+-- against that array, so it needs an index on tenant_id.
+
+-- ---------------------------------------------------------------------------
+-- stratum_subtree_tenant_ids(): the current tenant and all its descendants.
+--
+-- The subtree is selected by the ID-based ancestry_path, not by the
+-- slug-derived ancestry_ltree, for the reason getDescendants gives in
+-- tenant-service.ts: an isolation boundary must not follow slugs. A
+-- descendant's ancestry_path is the subtree path itself or starts with it
+-- plus '/'. The ~>=~ / ~<~ range lets idx_tenant_ancestry_path_prefix (028)
+-- serve the lookup with a value known only at run time ('0' is the character
+-- after '/'). The LIKE then drops what the range admits but is not a path
+-- segment boundary.
+--
+-- The policies call the function in a scalar subquery, so PostgreSQL runs it
+-- once per policy reference in a statement as an InitPlan and then matches
+-- tenant_id against the array with the table's own index on tenant_id.
+--
+-- The function must read the whole subtree while the caller sees only its own
+-- tenants row (019). It does what 029 does: SECURITY DEFINER would not help,
+-- because FORCE ROW LEVEL SECURITY applies to the owner too, so a SET clause
+-- turns on the 019 bypass for the function's own duration. A SET clause is
+-- restored when the function exits, on error too. The second SET clause clears
+-- app.tenant_scope inside the function, so the tenant_subtree_read policy on
+-- tenants cannot call the function again while it runs.
+--
+-- The function returns only ids in the subtree of app.current_tenant_id. A
+-- session that can call it can already set both settings, so it gives no new
+-- access. With no current tenant it returns an empty array.
+--
+-- search_path is pinned below to pg_catalog, the schema this migration runs
+-- in (where 001 created tenants), and pg_temp last, so that a table a session
+-- creates cannot stand in for tenants.
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION stratum_subtree_tenant_ids()
+RETURNS uuid[]
+LANGUAGE sql
+STABLE
+SET app.bypass_rls = 'on'
+SET app.tenant_scope = ''
+AS $$
+  WITH cur AS (
+    SELECT t.id, rtrim(t.ancestry_path, '/') || '/' || t.id::text AS sub
+    FROM tenants t
+    WHERE t.id = NULLIF(current_setting('app.current_tenant_id', true), '')::uuid
+  )
+  SELECT coalesce(array_agg(s.id), '{}'::uuid[])
+  FROM (
+    SELECT cur.id FROM cur
+    UNION ALL
+    SELECT d.id
+    FROM cur
+    JOIN tenants d
+      ON d.ancestry_path ~>=~ cur.sub
+     AND d.ancestry_path ~<~ (cur.sub || '0')
+     AND (d.ancestry_path = cur.sub OR d.ancestry_path LIKE cur.sub || '/%')
+  ) s
+$$;
+
+DO $pin$ BEGIN
+  EXECUTE pg_catalog.format(
+    'ALTER FUNCTION stratum_subtree_tenant_ids() SET search_path = pg_catalog, %I, pg_temp',
+    pg_catalog.current_schema()
+  );
+END $pin$;
+
+-- Reusable predicate (inlined per policy below, as in 019):
+--   current_setting('app.tenant_scope', true) = 'subtree'
+--   AND tenant_id = ANY ((SELECT stratum_subtree_tenant_ids())::uuid[])
+-- The scope check comes first. With any other scope the AND stops there, so
+-- the default path never runs the function.
+
+-- ---------------------------------------------------------------------------
+-- Direct tenant_id tables.
+-- ---------------------------------------------------------------------------
+
+-- config_entries: non-sensitive rows only. A sensitive row holds a secret
+-- value, so only the exact tenant reads it (019).
+DROP POLICY IF EXISTS tenant_subtree_read ON config_entries;
+CREATE POLICY tenant_subtree_read ON config_entries FOR SELECT
+  USING (
+    current_setting('app.tenant_scope', true) = 'subtree'
+    AND tenant_id = ANY ((SELECT stratum_subtree_tenant_ids())::uuid[])
+    AND NOT sensitive
+  );
+
+DROP POLICY IF EXISTS tenant_subtree_read ON permission_policies;
+CREATE POLICY tenant_subtree_read ON permission_policies FOR SELECT
+  USING (
+    current_setting('app.tenant_scope', true) = 'subtree'
+    AND tenant_id = ANY ((SELECT stratum_subtree_tenant_ids())::uuid[])
+  );
+
+DROP POLICY IF EXISTS tenant_subtree_read ON audit_logs;
+CREATE POLICY tenant_subtree_read ON audit_logs FOR SELECT
+  USING (
+    current_setting('app.tenant_scope', true) = 'subtree'
+    AND tenant_id = ANY ((SELECT stratum_subtree_tenant_ids())::uuid[])
+  );
+
+DROP POLICY IF EXISTS tenant_subtree_read ON webhook_events;
+CREATE POLICY tenant_subtree_read ON webhook_events FOR SELECT
+  USING (
+    current_setting('app.tenant_scope', true) = 'subtree'
+    AND tenant_id = ANY ((SELECT stratum_subtree_tenant_ids())::uuid[])
+  );
+
+-- webhooks: no subtree policy. A webhook row holds credential material, so
+-- only the exact tenant reads it (019).
+DROP POLICY IF EXISTS tenant_subtree_read ON webhooks;
+
+DROP POLICY IF EXISTS tenant_subtree_read ON consent_records;
+CREATE POLICY tenant_subtree_read ON consent_records FOR SELECT
+  USING (
+    current_setting('app.tenant_scope', true) = 'subtree'
+    AND tenant_id = ANY ((SELECT stratum_subtree_tenant_ids())::uuid[])
+  );
+
+DROP POLICY IF EXISTS tenant_subtree_read ON abac_policies;
+CREATE POLICY tenant_subtree_read ON abac_policies FOR SELECT
+  USING (
+    current_setting('app.tenant_scope', true) = 'subtree'
+    AND tenant_id = ANY ((SELECT stratum_subtree_tenant_ids())::uuid[])
+  );
+
+DROP POLICY IF EXISTS tenant_subtree_read ON roles;
+CREATE POLICY tenant_subtree_read ON roles FOR SELECT
+  USING (
+    current_setting('app.tenant_scope', true) = 'subtree'
+    AND tenant_id = ANY ((SELECT stratum_subtree_tenant_ids())::uuid[])
+  );
+
+DROP POLICY IF EXISTS tenant_subtree_read ON usage_events;
+CREATE POLICY tenant_subtree_read ON usage_events FOR SELECT
+  USING (
+    current_setting('app.tenant_scope', true) = 'subtree'
+    AND tenant_id = ANY ((SELECT stratum_subtree_tenant_ids())::uuid[])
+  );
+
+-- ---------------------------------------------------------------------------
+-- tenants registry: the subtree's own registry rows, on id.
+-- ---------------------------------------------------------------------------
+DROP POLICY IF EXISTS tenant_subtree_read ON tenants;
+CREATE POLICY tenant_subtree_read ON tenants FOR SELECT
+  USING (
+    current_setting('app.tenant_scope', true) = 'subtree'
+    AND id = ANY ((SELECT stratum_subtree_tenant_ids())::uuid[])
+  );
+
+-- ---------------------------------------------------------------------------
+-- Indirect tables: scoped through their tenant-bearing parent, as in 019.
+-- ---------------------------------------------------------------------------
+
+DROP POLICY IF EXISTS tenant_subtree_read ON webhook_deliveries;
+CREATE POLICY tenant_subtree_read ON webhook_deliveries FOR SELECT
+  USING (
+    current_setting('app.tenant_scope', true) = 'subtree'
+    AND EXISTS (
+      SELECT 1 FROM webhook_events we
+      WHERE we.id = webhook_deliveries.event_id
+        AND we.tenant_id = ANY ((SELECT stratum_subtree_tenant_ids())::uuid[])
+    )
+  );
+
+DROP POLICY IF EXISTS tenant_subtree_read ON principal_roles;
+CREATE POLICY tenant_subtree_read ON principal_roles FOR SELECT
+  USING (
+    current_setting('app.tenant_scope', true) = 'subtree'
+    AND EXISTS (
+      SELECT 1 FROM roles r
+      WHERE r.id = principal_roles.role_id
+        AND r.tenant_id = ANY ((SELECT stratum_subtree_tenant_ids())::uuid[])
+    )
+  );
+
+-- ---------------------------------------------------------------------------
+-- Tree columns change only under the bypass.
+--
+-- A tenant session may update its own tenants row (019), and the subtree read
+-- above follows parent_id and ancestry_path. This BEFORE trigger refuses any
+-- change to parent_id, ancestry_path, depth or ancestry_ltree unless
+-- app.bypass_rls = 'on'. The library changes these columns only in
+-- createTenant, moveTenant and the other tree operations, which all run under
+-- the bypass (pool-helpers.ts), and so do the migrations. A role that skips
+-- RLS must also set the bypass to change them.
+--
+-- A slug rename stays allowed: the trigger is named to run before
+-- maintain_tenant_ancestry_ltree (BEFORE triggers run in name order), so it
+-- compares the ancestry_ltree the statement wrote, not the one that trigger
+-- recomputes from the new slug.
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION refuse_tenant_tree_column_change()
+RETURNS TRIGGER
+AS $$
+BEGIN
+  IF current_setting('app.bypass_rls', true) IS DISTINCT FROM 'on' AND (
+       NEW.parent_id IS DISTINCT FROM OLD.parent_id
+    OR NEW.ancestry_path IS DISTINCT FROM OLD.ancestry_path
+    OR NEW.depth IS DISTINCT FROM OLD.depth
+    OR NEW.ancestry_ltree IS DISTINCT FROM OLD.ancestry_ltree
+  ) THEN
+    RAISE EXCEPTION 'tenant % tree columns (parent_id, ancestry_path, depth, ancestry_ltree) change only under app.bypass_rls', OLD.id
+      USING ERRCODE = 'insufficient_privilege';
+  END IF;
+  RETURN NEW;
+END;
+$$ language 'plpgsql';
+
+DO $pin$ BEGIN
+  EXECUTE pg_catalog.format(
+    'ALTER FUNCTION refuse_tenant_tree_column_change() SET search_path = pg_catalog, %I, pg_temp',
+    pg_catalog.current_schema()
+  );
+END $pin$;
+
+DROP TRIGGER IF EXISTS guard_tenant_tree_columns ON tenants;
+CREATE TRIGGER guard_tenant_tree_columns
+  BEFORE UPDATE OF parent_id, ancestry_path, depth, ancestry_ltree ON tenants
+  FOR EACH ROW
+  EXECUTE FUNCTION refuse_tenant_tree_column_change();
+
+-- ---------------------------------------------------------------------------
+-- refuse_tenant_parent_cycle() (029), with pg_temp last on its search_path.
+--
+-- The body is the one 029 created, unchanged. 029 pinned search_path to
+-- pg_catalog and the migration schema; this adds pg_temp at the end, so the
+-- cycle walk always reads the tenants table of that schema.
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION refuse_tenant_parent_cycle()
+RETURNS TRIGGER
+SET app.bypass_rls = 'on'
+AS $$
+BEGIN
+  IF NEW.parent_id = NEW.id OR EXISTS (
+    WITH RECURSIVE up(id, parent_id, seen) AS (
+      SELECT t.id, t.parent_id, ARRAY[t.id]
+      FROM tenants t
+      WHERE t.id = NEW.parent_id
+      UNION ALL
+      SELECT t.id, t.parent_id, up.seen || t.id
+      FROM tenants t
+      JOIN up ON t.id = up.parent_id
+      WHERE t.id <> ALL (up.seen)
+    )
+    SELECT 1 FROM up WHERE up.id = NEW.id
+  ) THEN
+    RAISE EXCEPTION 'tenant % cannot be its own ancestor (parent_id cycle)', NEW.id
+      USING ERRCODE = 'check_violation';
+  END IF;
+  RETURN NEW;
+END;
+$$ language 'plpgsql';
+
+DO $pin$ BEGIN
+  EXECUTE pg_catalog.format(
+    'ALTER FUNCTION refuse_tenant_parent_cycle() SET search_path = pg_catalog, %I, pg_temp',
+    pg_catalog.current_schema()
+  );
+END $pin$;