@blamejs/core 0.7.18 → 0.7.19

package/lib/db-declare-row-policy.js

@@ -1,267 +1,267 @@
-"use strict";
-/**
- * b.db.declareRowPolicy — declarative Postgres ROW LEVEL SECURITY policy
- * migration spec.
- *
- * Returns a migration-shape object that b.externalDb.migrate(...) applies
- * against a Postgres backend. Generates:
- *
- *   ALTER TABLE <schema>.<table> ENABLE ROW LEVEL SECURITY;     -- idempotent
- *   CREATE POLICY <name> ON <schema>.<table>
- *     [AS PERMISSIVE | RESTRICTIVE]
- *     FOR <command>
- *     [TO <role>]
- *     USING (<expr>)
- *     [WITH CHECK (<expr>)];
- *
- * Pairs with b.externalDb.transaction({ sessionGucs: { 'app.tenant_id': uuid } })
- * for the per-request `SET LOCAL` plumbing. The recommended tenant-per-row
- * shape:
- *
- *   b.db.declareRowPolicy({
- *     schema:    "public",
- *     table:     "sessions",
- *     name:      "tenant_isolation",
- *     role:      "app_user",
- *     using:     "tenant_id = current_setting('app.tenant_id')::uuid",
- *     withCheck: "tenant_id = current_setting('app.tenant_id')::uuid",
- *     command:   "ALL",
- *   });
- *
- *   await b.externalDb.transaction(async function (tx) {
- *     return await tx.query("SELECT * FROM sessions WHERE _id = $1", [sid]);
- *   }, { sessionGucs: { "app.tenant_id": req.user.tenantId } });
- *
- * Postgres-only: SQLite + MySQL have no equivalent grammar. Apply throws
- * NOT_SUPPORTED at migration-apply time when the targeted backend's
- * dialect isn't "postgres".
- *
- * Validation at declareRowPolicy() call time — bad shape throws here, not
- * at apply time:
- *   - schema, table, name, role → safeSql.validateIdentifier
- *   - command ∈ {ALL, SELECT, INSERT, UPDATE, DELETE}
- *   - permissive boolean
- *   - using / withCheck operator-supplied SQL strings; semicolons rejected
- *
- * Audit metadata emitted on apply:
- *   {
- *     policy:    "schema.table.name",
- *     table:     "schema.table",
- *     role:      "...",
- *     command:   "ALL"|...,
- *     permissive: true|false,
- *     hasWithCheck: bool,
- *   }
- */
-var safeSql = require("./safe-sql");
-var validateOpts = require("./validate-opts");
-var { defineClass } = require("./framework-error");
-
-var DeclareRowPolicyError = defineClass("DeclareRowPolicyError", { alwaysPermanent: true });
-
-var ALLOWED_OPTS = [
-  "schema", "table", "name", "role",
-  "using", "withCheck", "command", "permissive", "backend",
-];
-
-var ALLOWED_COMMANDS = ["ALL", "SELECT", "INSERT", "UPDATE", "DELETE"];
-
-function _err(code, message) {
-  return new DeclareRowPolicyError(code, message);
-}
-
-function _validateIdent(where, value) {
-  try {
-    safeSql.validateIdentifier(value, { allowReserved: true });
-  } catch (e) {
-    throw _err("declare-row-policy/bad-identifier",
-      where + ": invalid identifier '" + value + "': " + ((e && e.message) || String(e)));
-  }
-}
-
-function _validateExpression(where, value) {
-  if (typeof value !== "string") {
-    throw _err("declare-row-policy/bad-type", where + " must be a string");
-  }
-  if (value.length === 0) {
-    throw _err("declare-row-policy/empty-expression", where + " must be a non-empty boolean expression");
-  }
-  if (value.indexOf(";") !== -1) {
-    throw _err("declare-row-policy/bad-expression",
-      where + " must not contain ';' — use a single boolean expression");
-  }
-  return value;
-}
-
-function _validateOpts(opts) {
-  if (!opts || typeof opts !== "object") {
-    throw _err("declare-row-policy/bad-opts", "declareRowPolicy requires an opts object");
-  }
-  for (var k in opts) {
-    if (Object.prototype.hasOwnProperty.call(opts, k) && ALLOWED_OPTS.indexOf(k) === -1) {
-      throw _err("declare-row-policy/unknown-opt",
-        "unknown opt '" + k + "'. Allowed: " + ALLOWED_OPTS.join(", "));
-    }
-  }
-
-  validateOpts.requireNonEmptyString(opts.schema, "schema", DeclareRowPolicyError, "declare-row-policy/missing-opt");
-  _validateIdent("schema", opts.schema);
-
-  validateOpts.requireNonEmptyString(opts.table, "table", DeclareRowPolicyError, "declare-row-policy/missing-opt");
-  _validateIdent("table", opts.table);
-
-  validateOpts.requireNonEmptyString(opts.name, "name", DeclareRowPolicyError, "declare-row-policy/missing-opt");
-  _validateIdent("name", opts.name);
-
-  var role = null;
-  if (opts.role !== undefined && opts.role !== null) {
-    if (typeof opts.role !== "string" || opts.role.length === 0) {
-      throw _err("declare-row-policy/bad-type", "role must be a non-empty string");
-    }
-    _validateIdent("role", opts.role);
-    role = opts.role;
-  }
-
-  if (opts.using === undefined || opts.using === null) {
-    throw _err("declare-row-policy/missing-opt", "using is required (USING expression)");
-  }
-  var using = _validateExpression("using", opts.using);
-
-  var withCheck = null;
-  if (opts.withCheck !== undefined && opts.withCheck !== null) {
-    withCheck = _validateExpression("withCheck", opts.withCheck);
-  }
-
-  var command = "ALL";
-  if (opts.command !== undefined && opts.command !== null) {
-    if (typeof opts.command !== "string") {
-      throw _err("declare-row-policy/bad-type", "command must be a string");
-    }
-    var upper = opts.command.toUpperCase();
-    if (ALLOWED_COMMANDS.indexOf(upper) === -1) {
-      throw _err("declare-row-policy/bad-command",
-        "command must be one of " + ALLOWED_COMMANDS.join(", ") + ", got '" + opts.command + "'");
-    }
-    command = upper;
-  }
-
-  var permissive = true;
-  if (opts.permissive !== undefined && opts.permissive !== null) {
-    if (typeof opts.permissive !== "boolean") {
-      throw _err("declare-row-policy/bad-type", "permissive must be a boolean");
-    }
-    permissive = opts.permissive;
-  }
-
-  if (opts.backend !== undefined && opts.backend !== null) {
-    if (typeof opts.backend !== "string" || opts.backend.length === 0) {
-      throw _err("declare-row-policy/bad-type", "backend must be a non-empty string");
-    }
-  }
-
-  return {
-    schema:     opts.schema,
-    table:      opts.table,
-    name:       opts.name,
-    role:       role,
-    using:      using,
-    withCheck:  withCheck,
-    command:    command,
-    permissive: permissive,
-    backend:    opts.backend || null,
-  };
-}
-
-function _ensureBackendIsPostgres(externalDb, backendName) {
-  var list = externalDb.listBackends();
-  var found = null;
-  for (var i = 0; i < list.length; i++) {
-    if (list[i].name === backendName) { found = list[i]; break; }
-  }
-  if (!found) {
-    throw _err("declare-row-policy/unknown-backend",
-      "no externalDb backend named '" + backendName + "' — declared backends: " +
-      list.map(function (b) { return b.name; }).join(", "));
-  }
-  if (found.dialect !== "postgres") {
-    throw _err("declare-row-policy/not-supported",
-      "declareRowPolicy is Postgres-only; backend '" + backendName + "' has dialect='" +
-      found.dialect + "'. Write the policy as a hand-rolled migration for this dialect.");
-  }
-}
-
-function declareRowPolicy(opts) {
-  var spec = _validateOpts(opts);
-  var qTable  = safeSql.quoteQualified([spec.schema, spec.table], "postgres");
-  var qPolicy = safeSql.quoteIdentifier(spec.name, "postgres");
-  var qRole   = spec.role ? safeSql.quoteIdentifier(spec.role, "postgres") : null;
-
-  var description = "declareRowPolicy " + spec.schema + "." + spec.table + "." + spec.name;
-
-  async function up(xdb, ctx) {
-    if (ctx && ctx.externalDb && ctx.backendName) {
-      _ensureBackendIsPostgres(ctx.externalDb, ctx.backendName);
-    }
-
-    // Idempotent ENABLE — Postgres has no IF NOT EXISTS for this. Read
-    // the current setting from pg_class and skip the ALTER when already
-    // on, so re-running a migration set in a partially-applied state
-    // doesn't fail with a no-op error from the lock acquisition.
-    var rlsCheck = await xdb.query(
-      "SELECT relrowsecurity FROM pg_class c " +
-      "JOIN pg_namespace n ON n.oid = c.relnamespace " +
-      "WHERE n.nspname = $1 AND c.relname = $2",
-      [spec.schema, spec.table]
-    );
-    var rows = (rlsCheck && rlsCheck.rows) || [];
-    if (rows.length === 0) {
-      throw _err("declare-row-policy/table-not-found",
-        "source table '" + spec.schema + "." + spec.table +
-        "' not found (does it exist? does the migration role have visibility?)");
-    }
-    if (!rows[0].relrowsecurity) {
-      await xdb.query("ALTER TABLE " + qTable + " ENABLE ROW LEVEL SECURITY", []);
-    }
-
-    // CREATE POLICY assembled in canonical order: name → table → AS
-    // PERMISSIVE/RESTRICTIVE → FOR command → TO role → USING → WITH CHECK.
-    var sql = "CREATE POLICY " + qPolicy + " ON " + qTable;
-    sql += " AS " + (spec.permissive ? "PERMISSIVE" : "RESTRICTIVE");
-    sql += " FOR " + spec.command;
-    if (qRole) sql += " TO " + qRole;
-    sql += " USING (" + spec.using + ")";
-    if (spec.withCheck) sql += " WITH CHECK (" + spec.withCheck + ")";
-
-    await xdb.query(sql, []);
-
-    return {
-      policy:       spec.schema + "." + spec.table + "." + spec.name,
-      table:        spec.schema + "." + spec.table,
-      role:         spec.role,
-      command:      spec.command,
-      permissive:   spec.permissive,
-      hasWithCheck: !!spec.withCheck,
-    };
-  }
-
-  async function down(xdb, ctx) {
-    if (ctx && ctx.externalDb && ctx.backendName) {
-      _ensureBackendIsPostgres(ctx.externalDb, ctx.backendName);
-    }
-    await xdb.query("DROP POLICY IF EXISTS " + qPolicy + " ON " + qTable, []);
-  }
-
-  return {
-    description: description,
-    target:      "externalDb",
-    backend:     spec.backend,
-    up:          up,
-    down:        down,
-    _spec:       spec,
-  };
-}
-
-module.exports = {
-  declareRowPolicy:        declareRowPolicy,
-  DeclareRowPolicyError:   DeclareRowPolicyError,
-};
+"use strict";
+/**
+ * b.db.declareRowPolicy — declarative Postgres ROW LEVEL SECURITY policy
+ * migration spec.
+ *
+ * Returns a migration-shape object that b.externalDb.migrate(...) applies
+ * against a Postgres backend. Generates:
+ *
+ *   ALTER TABLE <schema>.<table> ENABLE ROW LEVEL SECURITY;     -- idempotent
+ *   CREATE POLICY <name> ON <schema>.<table>
+ *     [AS PERMISSIVE | RESTRICTIVE]
+ *     FOR <command>
+ *     [TO <role>]
+ *     USING (<expr>)
+ *     [WITH CHECK (<expr>)];
+ *
+ * Pairs with b.externalDb.transaction({ sessionGucs: { 'app.tenant_id': uuid } })
+ * for the per-request `SET LOCAL` plumbing. The recommended tenant-per-row
+ * shape:
+ *
+ *   b.db.declareRowPolicy({
+ *     schema:    "public",
+ *     table:     "sessions",
+ *     name:      "tenant_isolation",
+ *     role:      "app_user",
+ *     using:     "tenant_id = current_setting('app.tenant_id')::uuid",
+ *     withCheck: "tenant_id = current_setting('app.tenant_id')::uuid",
+ *     command:   "ALL",
+ *   });
+ *
+ *   await b.externalDb.transaction(async function (tx) {
+ *     return await tx.query("SELECT * FROM sessions WHERE _id = $1", [sid]);
+ *   }, { sessionGucs: { "app.tenant_id": req.user.tenantId } });
+ *
+ * Postgres-only: SQLite + MySQL have no equivalent grammar. Apply throws
+ * NOT_SUPPORTED at migration-apply time when the targeted backend's
+ * dialect isn't "postgres".
+ *
+ * Validation at declareRowPolicy() call time — bad shape throws here, not
+ * at apply time:
+ *   - schema, table, name, role → safeSql.validateIdentifier
+ *   - command ∈ {ALL, SELECT, INSERT, UPDATE, DELETE}
+ *   - permissive boolean
+ *   - using / withCheck operator-supplied SQL strings; semicolons rejected
+ *
+ * Audit metadata emitted on apply:
+ *   {
+ *     policy:    "schema.table.name",
+ *     table:     "schema.table",
+ *     role:      "...",
+ *     command:   "ALL"|...,
+ *     permissive: true|false,
+ *     hasWithCheck: bool,
+ *   }
+ */
+var safeSql = require("./safe-sql");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var DeclareRowPolicyError = defineClass("DeclareRowPolicyError", { alwaysPermanent: true });
+
+var ALLOWED_OPTS = [
+  "schema", "table", "name", "role",
+  "using", "withCheck", "command", "permissive", "backend",
+];
+
+var ALLOWED_COMMANDS = ["ALL", "SELECT", "INSERT", "UPDATE", "DELETE"];
+
+function _err(code, message) {
+  return new DeclareRowPolicyError(code, message);
+}
+
+function _validateIdent(where, value) {
+  try {
+    safeSql.validateIdentifier(value, { allowReserved: true });
+  } catch (e) {
+    throw _err("declare-row-policy/bad-identifier",
+      where + ": invalid identifier '" + value + "': " + ((e && e.message) || String(e)));
+  }
+}
+
+function _validateExpression(where, value) {
+  if (typeof value !== "string") {
+    throw _err("declare-row-policy/bad-type", where + " must be a string");
+  }
+  if (value.length === 0) {
+    throw _err("declare-row-policy/empty-expression", where + " must be a non-empty boolean expression");
+  }
+  if (value.indexOf(";") !== -1) {
+    throw _err("declare-row-policy/bad-expression",
+      where + " must not contain ';' — use a single boolean expression");
+  }
+  return value;
+}
+
+function _validateOpts(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw _err("declare-row-policy/bad-opts", "declareRowPolicy requires an opts object");
+  }
+  for (var k in opts) {
+    if (Object.prototype.hasOwnProperty.call(opts, k) && ALLOWED_OPTS.indexOf(k) === -1) {
+      throw _err("declare-row-policy/unknown-opt",
+        "unknown opt '" + k + "'. Allowed: " + ALLOWED_OPTS.join(", "));
+    }
+  }
+
+  validateOpts.requireNonEmptyString(opts.schema, "schema", DeclareRowPolicyError, "declare-row-policy/missing-opt");
+  _validateIdent("schema", opts.schema);
+
+  validateOpts.requireNonEmptyString(opts.table, "table", DeclareRowPolicyError, "declare-row-policy/missing-opt");
+  _validateIdent("table", opts.table);
+
+  validateOpts.requireNonEmptyString(opts.name, "name", DeclareRowPolicyError, "declare-row-policy/missing-opt");
+  _validateIdent("name", opts.name);
+
+  var role = null;
+  if (opts.role !== undefined && opts.role !== null) {
+    if (typeof opts.role !== "string" || opts.role.length === 0) {
+      throw _err("declare-row-policy/bad-type", "role must be a non-empty string");
+    }
+    _validateIdent("role", opts.role);
+    role = opts.role;
+  }
+
+  if (opts.using === undefined || opts.using === null) {
+    throw _err("declare-row-policy/missing-opt", "using is required (USING expression)");
+  }
+  var using = _validateExpression("using", opts.using);
+
+  var withCheck = null;
+  if (opts.withCheck !== undefined && opts.withCheck !== null) {
+    withCheck = _validateExpression("withCheck", opts.withCheck);
+  }
+
+  var command = "ALL";
+  if (opts.command !== undefined && opts.command !== null) {
+    if (typeof opts.command !== "string") {
+      throw _err("declare-row-policy/bad-type", "command must be a string");
+    }
+    var upper = opts.command.toUpperCase();
+    if (ALLOWED_COMMANDS.indexOf(upper) === -1) {
+      throw _err("declare-row-policy/bad-command",
+        "command must be one of " + ALLOWED_COMMANDS.join(", ") + ", got '" + opts.command + "'");
+    }
+    command = upper;
+  }
+
+  var permissive = true;
+  if (opts.permissive !== undefined && opts.permissive !== null) {
+    if (typeof opts.permissive !== "boolean") {
+      throw _err("declare-row-policy/bad-type", "permissive must be a boolean");
+    }
+    permissive = opts.permissive;
+  }
+
+  if (opts.backend !== undefined && opts.backend !== null) {
+    if (typeof opts.backend !== "string" || opts.backend.length === 0) {
+      throw _err("declare-row-policy/bad-type", "backend must be a non-empty string");
+    }
+  }
+
+  return {
+    schema:     opts.schema,
+    table:      opts.table,
+    name:       opts.name,
+    role:       role,
+    using:      using,
+    withCheck:  withCheck,
+    command:    command,
+    permissive: permissive,
+    backend:    opts.backend || null,
+  };
+}
+
+function _ensureBackendIsPostgres(externalDb, backendName) {
+  var list = externalDb.listBackends();
+  var found = null;
+  for (var i = 0; i < list.length; i++) {
+    if (list[i].name === backendName) { found = list[i]; break; }
+  }
+  if (!found) {
+    throw _err("declare-row-policy/unknown-backend",
+      "no externalDb backend named '" + backendName + "' — declared backends: " +
+      list.map(function (b) { return b.name; }).join(", "));
+  }
+  if (found.dialect !== "postgres") {
+    throw _err("declare-row-policy/not-supported",
+      "declareRowPolicy is Postgres-only; backend '" + backendName + "' has dialect='" +
+      found.dialect + "'. Write the policy as a hand-rolled migration for this dialect.");
+  }
+}
+
+function declareRowPolicy(opts) {
+  var spec = _validateOpts(opts);
+  var qTable  = safeSql.quoteQualified([spec.schema, spec.table], "postgres");
+  var qPolicy = safeSql.quoteIdentifier(spec.name, "postgres");
+  var qRole   = spec.role ? safeSql.quoteIdentifier(spec.role, "postgres") : null;
+
+  var description = "declareRowPolicy " + spec.schema + "." + spec.table + "." + spec.name;
+
+  async function up(xdb, ctx) {
+    if (ctx && ctx.externalDb && ctx.backendName) {
+      _ensureBackendIsPostgres(ctx.externalDb, ctx.backendName);
+    }
+
+    // Idempotent ENABLE — Postgres has no IF NOT EXISTS for this. Read
+    // the current setting from pg_class and skip the ALTER when already
+    // on, so re-running a migration set in a partially-applied state
+    // doesn't fail with a no-op error from the lock acquisition.
+    var rlsCheck = await xdb.query(
+      "SELECT relrowsecurity FROM pg_class c " +
+      "JOIN pg_namespace n ON n.oid = c.relnamespace " +
+      "WHERE n.nspname = $1 AND c.relname = $2",
+      [spec.schema, spec.table]
+    );
+    var rows = (rlsCheck && rlsCheck.rows) || [];
+    if (rows.length === 0) {
+      throw _err("declare-row-policy/table-not-found",
+        "source table '" + spec.schema + "." + spec.table +
+        "' not found (does it exist? does the migration role have visibility?)");
+    }
+    if (!rows[0].relrowsecurity) {
+      await xdb.query("ALTER TABLE " + qTable + " ENABLE ROW LEVEL SECURITY", []);
+    }
+
+    // CREATE POLICY assembled in canonical order: name → table → AS
+    // PERMISSIVE/RESTRICTIVE → FOR command → TO role → USING → WITH CHECK.
+    var sql = "CREATE POLICY " + qPolicy + " ON " + qTable;
+    sql += " AS " + (spec.permissive ? "PERMISSIVE" : "RESTRICTIVE");
+    sql += " FOR " + spec.command;
+    if (qRole) sql += " TO " + qRole;
+    sql += " USING (" + spec.using + ")";
+    if (spec.withCheck) sql += " WITH CHECK (" + spec.withCheck + ")";
+
+    await xdb.query(sql, []);
+
+    return {
+      policy:       spec.schema + "." + spec.table + "." + spec.name,
+      table:        spec.schema + "." + spec.table,
+      role:         spec.role,
+      command:      spec.command,
+      permissive:   spec.permissive,
+      hasWithCheck: !!spec.withCheck,
+    };
+  }
+
+  async function down(xdb, ctx) {
+    if (ctx && ctx.externalDb && ctx.backendName) {
+      _ensureBackendIsPostgres(ctx.externalDb, ctx.backendName);
+    }
+    await xdb.query("DROP POLICY IF EXISTS " + qPolicy + " ON " + qTable, []);
+  }
+
+  return {
+    description: description,
+    target:      "externalDb",
+    backend:     spec.backend,
+    up:          up,
+    down:        down,
+    _spec:       spec,
+  };
+}
+
+module.exports = {
+  declareRowPolicy:        declareRowPolicy,
+  DeclareRowPolicyError:   DeclareRowPolicyError,
+};