@blamejs/blamejs-shop 0.0.44

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

@@ -0,0 +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,
+};

package/lib/vendor/blamejs/lib/db-declare-view.js

@@ -0,0 +1,420 @@
+"use strict";
+/**
+ * b.db.declareView — declarative view + GRANT migration spec.
+ *
+ * Returns a migration-shape object that b.externalDb.migrate(...) applies
+ * against a Postgres backend. The view exposes a deliberately-narrowed
+ * column projection of the source table — sensitive columns are dropped
+ * (redactColumns), sealed columns are auto-omitted (operator declares
+ * via sealedColumns; a future externalDb sealed-fields registry will
+ * make this automatic), and existing derived hash columns can be
+ * exposed in place of their plaintext source via hashColumns.
+ *
+ * Postgres-only: SQLite has no GRANT semantics; MySQL's CREATE VIEW
+ * grammar differs and isn't covered. Apply throws NOT_SUPPORTED at
+ * migration-apply time when the targeted backend's dialect isn't
+ * "postgres" so operators see the failure cause clearly.
+ *
+ * Public API (b.db.declareView):
+ *
+ *   var mig = b.db.declareView({
+ *     schema:         "analytics",          // target schema
+ *     name:           "sessions",           // view name
+ *     source:         "public.sessions",    // schema.table OR ["public","sessions"]
+ *     redactColumns:  ["ssn", "diagnosis"], // dropped from view
+ *     sealedColumns:  ["secrets_jsonb"],    // operator-declared sealed cols (auto-omit)
+ *     hashColumns:    { emailHash: "email" },// hide source plaintext, keep hash
+ *     whereClause:    "deleted_at IS NULL", // optional filter
+ *     grantTo:        ["analytics_user"],   // roles that get SELECT
+ *     backend:        "main",               // optional — defaults to default backend
+ *   });
+ *
+ *   // mig is a migration-shape object: { description, target, backend, up, down }
+ *   // Place it in a migration file:
+ *   //   module.exports = mig;
+ *   // and run b.externalDb.migrate.create({ dir }).up();
+ *
+ * Validation runs at migration apply (not declare) time so source-column
+ * existence and role existence checks query the live database. Operator
+ * typos surface as clear errors at the migrate command, not as silent
+ * empty views or grant-to-nonexistent-role footguns.
+ *
+ * Throw at declareView() call time on:
+ *   - schema, name, source segments → safeSql.validateIdentifier
+ *   - column names in redactColumns / sealedColumns / hashColumns →
+ *     safeSql.validateIdentifier
+ *   - role names in grantTo → safeSql.validateIdentifier
+ *   - whereClause stays operator-supplied SQL (the framework cannot
+ *     validate arbitrary expressions); it interpolates as-is into the
+ *     migration text. Operators wrap any literal values inside
+ *     whereClause via standard SQL quoting.
+ *
+ * Audit metadata emitted on apply:
+ *   {
+ *     view:                "schema.name",
+ *     source:              "schema.table",
+ *     selectedColumns:     [string],
+ *     redactedColumns:     [string],   // intersection of redactColumns & source
+ *     autoExcludedSealed:  [string],   // sealedColumns members found in source
+ *     hashedColumns:       { aliasOrHashCol: srcCol },
+ *     grantedTo:           [string],
+ *   }
+ */
+var safeSql = require("./safe-sql");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var DeclareViewError = defineClass("DeclareViewError", { alwaysPermanent: true });
+
+var ALLOWED_OPTS = [
+  "schema", "name", "source",
+  "redactColumns", "sealedColumns", "hashColumns",
+  "whereClause", "grantTo", "backend",
+];
+
+function _err(code, message) {
+  return new DeclareViewError(code, message);
+}
+
+function _validateIdent(where, value) {
+  try {
+    safeSql.validateIdentifier(value, { allowReserved: true });
+  } catch (e) {
+    throw _err("declare-view/bad-identifier",
+      where + ": invalid identifier '" + value + "': " + ((e && e.message) || String(e)));
+  }
+}
+
+function _validateStringArray(where, arr, optional) {
+  if (arr === undefined || arr === null) {
+    if (optional) return [];
+    throw _err("declare-view/missing-opt", where + " is required");
+  }
+  if (!Array.isArray(arr)) {
+    throw _err("declare-view/bad-type", where + " must be an array of strings");
+  }
+  for (var i = 0; i < arr.length; i++) {
+    if (typeof arr[i] !== "string" || arr[i].length === 0) {
+      throw _err("declare-view/bad-entry",
+        where + "[" + i + "] must be a non-empty string");
+    }
+  }
+  return arr.slice();
+}
+
+function _parseSource(source) {
+  // Accepts "schema.table" or ["schema", "table"] or "table" (defaults to public).
+  var parts;
+  if (typeof source === "string") {
+    if (source.length === 0) {
+      throw _err("declare-view/bad-source", "source must be a non-empty string or array");
+    }
+    parts = source.split(".");
+  } else if (Array.isArray(source)) {
+    parts = source.slice();
+  } else {
+    throw _err("declare-view/bad-source",
+      "source must be a string ('schema.table') or array (['schema','table']), got " + typeof source);
+  }
+  if (parts.length === 1) parts = ["public", parts[0]];
+  if (parts.length !== 2) {
+    throw _err("declare-view/bad-source",
+      "source must resolve to two segments [schema, table]; got " + parts.length + " segment(s)");
+  }
+  for (var i = 0; i < parts.length; i++) _validateIdent("source[" + i + "]", parts[i]);
+  return { schema: parts[0], name: parts[1] };
+}
+
+function _validateOpts(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw _err("declare-view/bad-opts", "declareView requires an opts object");
+  }
+  for (var k in opts) {
+    if (Object.prototype.hasOwnProperty.call(opts, k) && ALLOWED_OPTS.indexOf(k) === -1) {
+      throw _err("declare-view/unknown-opt",
+        "unknown opt '" + k + "'. Allowed: " + ALLOWED_OPTS.join(", "));
+    }
+  }
+
+  validateOpts.requireNonEmptyString(opts.schema, "schema", DeclareViewError, "declare-view/missing-opt");
+  _validateIdent("schema", opts.schema);
+
+  validateOpts.requireNonEmptyString(opts.name, "name", DeclareViewError, "declare-view/missing-opt");
+  _validateIdent("name", opts.name);
+
+  if (opts.source === undefined) {
+    throw _err("declare-view/missing-opt", "source is required");
+  }
+  var src = _parseSource(opts.source);
+
+  var redactColumns = _validateStringArray("redactColumns", opts.redactColumns, true);
+  for (var i = 0; i < redactColumns.length; i++) {
+    _validateIdent("redactColumns[" + i + "]", redactColumns[i]);
+  }
+
+  var sealedColumns = _validateStringArray("sealedColumns", opts.sealedColumns, true);
+  for (var j = 0; j < sealedColumns.length; j++) {
+    _validateIdent("sealedColumns[" + j + "]", sealedColumns[j]);
+  }
+
+  var hashColumns = {};
+  validateOpts.optionalPlainObject(opts.hashColumns, "hashColumns",
+    DeclareViewError, "declare-view/bad-type",
+    "must be an object { aliasOrHashCol: srcCol }");
+  if (opts.hashColumns !== undefined && opts.hashColumns !== null) {
+    for (var hc in opts.hashColumns) {
+      if (!Object.prototype.hasOwnProperty.call(opts.hashColumns, hc)) continue;
+      _validateIdent("hashColumns key '" + hc + "'", hc);
+      var v = opts.hashColumns[hc];
+      if (typeof v !== "string" || v.length === 0) {
+        throw _err("declare-view/bad-entry",
+          "hashColumns['" + hc + "'] must be a non-empty string (the source plaintext column)");
+      }
+      _validateIdent("hashColumns['" + hc + "']", v);
+      hashColumns[hc] = v;
+    }
+  }
+
+  var whereClause = null;
+  if (opts.whereClause !== undefined && opts.whereClause !== null) {
+    if (typeof opts.whereClause !== "string") {
+      throw _err("declare-view/bad-type", "whereClause must be a string");
+    }
+    if (opts.whereClause.indexOf(";") !== -1) {
+      throw _err("declare-view/bad-where",
+        "whereClause must not contain ';' — use a single boolean expression");
+    }
+    whereClause = opts.whereClause;
+  }
+
+  var grantTo = _validateStringArray("grantTo", opts.grantTo, true);
+  for (var g = 0; g < grantTo.length; g++) {
+    _validateIdent("grantTo[" + g + "]", grantTo[g]);
+  }
+
+  if (opts.backend !== undefined && opts.backend !== null) {
+    if (typeof opts.backend !== "string" || opts.backend.length === 0) {
+      throw _err("declare-view/bad-type", "backend must be a non-empty string");
+    }
+  }
+
+  return {
+    schema:         opts.schema,
+    name:           opts.name,
+    source:         src,
+    redactColumns:  redactColumns,
+    sealedColumns:  sealedColumns,
+    hashColumns:    hashColumns,
+    whereClause:    whereClause,
+    grantTo:        grantTo,
+    backend:        opts.backend || null,
+  };
+}
+
+// ---- Apply-time helpers (run inside up()) ----
+
+async function _fetchSourceColumns(xdb, schema, table) {
+  var res = await xdb.query(
+    "SELECT column_name FROM information_schema.columns " +
+    "WHERE table_schema = $1 AND table_name = $2 " +
+    "ORDER BY ordinal_position ASC",
+    [schema, table]
+  );
+  var rows = (res && res.rows) || [];
+  return rows.map(function (r) { return r.column_name; });
+}
+
+async function _fetchExistingRoles(xdb, names) {
+  if (names.length === 0) return new Set();
+  var placeholders = names.map(function (_, i) { return "$" + (i + 1); }).join(", ");
+  var res = await xdb.query(
+    "SELECT rolname FROM pg_roles WHERE rolname IN (" + placeholders + ")",
+    names
+  );
+  var rows = (res && res.rows) || [];
+  return new Set(rows.map(function (r) { return r.rolname; }));
+}
+
+function _missing(required, available) {
+  var miss = [];
+  for (var i = 0; i < required.length; i++) {
+    if (available.indexOf(required[i]) === -1) miss.push(required[i]);
+  }
+  return miss;
+}
+
+function _buildSelectColumnList(sourceCols, spec) {
+  // Drop set: redactColumns ∩ source, sealedColumns ∩ source, hashColumns.values ∩ source.
+  var dropSet = Object.create(null);
+  for (var i = 0; i < spec.redactColumns.length; i++) dropSet[spec.redactColumns[i]] = true;
+  for (var j = 0; j < spec.sealedColumns.length; j++) dropSet[spec.sealedColumns[j]] = true;
+  for (var hc in spec.hashColumns) dropSet[spec.hashColumns[hc]] = true;
+
+  var kept = [];
+  for (var k = 0; k < sourceCols.length; k++) {
+    if (!dropSet[sourceCols[k]]) kept.push(sourceCols[k]);
+  }
+  return kept;
+}
+
+function _intersectInSource(list, sourceCols) {
+  var srcSet = Object.create(null);
+  for (var i = 0; i < sourceCols.length; i++) srcSet[sourceCols[i]] = true;
+  var out = [];
+  for (var j = 0; j < list.length; j++) {
+    if (srcSet[list[j]]) out.push(list[j]);
+  }
+  return out;
+}
+
+function _ensureBackendIsPostgres(externalDb, backendName) {
+  // externalDb.listBackends() returns { name, dialect, ... } per backend.
+  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-view/unknown-backend",
+      "no externalDb backend named '" + backendName + "' — declared backends: " +
+      list.map(function (b) { return b.name; }).join(", "));
+  }
+  if (found.dialect !== "postgres") {
+    throw _err("declare-view/not-supported",
+      "declareView is Postgres-only; backend '" + backendName + "' has dialect='" +
+      found.dialect + "'. Write the view as a hand-rolled migration for this dialect.");
+  }
+}
+
+// ---- The factory ----
+
+function declareView(opts) {
+  var spec = _validateOpts(opts);
+
+  // The migration shape consumed by b.externalDb.migrate. The runner
+  // resolves the backend at apply time (operator may set spec.backend
+  // explicitly OR rely on the migrate runner's default backend).
+  var description = "declareView " + spec.schema + "." + spec.name;
+  var qView   = safeSql.quoteQualified([spec.schema, spec.name], "postgres");
+  var qSource = safeSql.quoteQualified([spec.source.schema, spec.source.name], "postgres");
+
+  async function up(xdb, ctx) {
+    // Boundary throw: confirm we're on Postgres before any DDL leaves the process.
+    if (ctx && ctx.externalDb && ctx.backendName) {
+      _ensureBackendIsPostgres(ctx.externalDb, ctx.backendName);
+    }
+
+    // Live validation — source columns + roles must exist.
+    var sourceCols = await _fetchSourceColumns(xdb, spec.source.schema, spec.source.name);
+    if (sourceCols.length === 0) {
+      throw _err("declare-view/source-not-found",
+        "source table '" + spec.source.schema + "." + spec.source.name +
+        "' has no columns visible (does it exist? does the migration role have SELECT on information_schema.columns?)");
+    }
+
+    var missingRedact = _missing(spec.redactColumns, sourceCols);
+    if (missingRedact.length > 0) {
+      throw _err("declare-view/redact-not-in-source",
+        "redactColumns [" + missingRedact.join(", ") + "] not present on source '" +
+        spec.source.schema + "." + spec.source.name + "'");
+    }
+
+    var missingHashKeys = _missing(Object.keys(spec.hashColumns), sourceCols);
+    if (missingHashKeys.length > 0) {
+      throw _err("declare-view/hash-key-not-in-source",
+        "hashColumns keys [" + missingHashKeys.join(", ") + "] not present on source '" +
+        spec.source.schema + "." + spec.source.name +
+        "' — declare them as derivedHashes on the source schema first");
+    }
+
+    var missingHashSrc = _missing(_objValues(spec.hashColumns), sourceCols);
+    if (missingHashSrc.length > 0) {
+      throw _err("declare-view/hash-source-not-in-source",
+        "hashColumns values [" + missingHashSrc.join(", ") + "] not present on source '" +
+        spec.source.schema + "." + spec.source.name + "'");
+    }
+
+    if (spec.grantTo.length > 0) {
+      var existing = await _fetchExistingRoles(xdb, spec.grantTo);
+      var missingRoles = [];
+      for (var i = 0; i < spec.grantTo.length; i++) {
+        if (!existing.has(spec.grantTo[i])) missingRoles.push(spec.grantTo[i]);
+      }
+      if (missingRoles.length > 0) {
+        throw _err("declare-view/role-not-found",
+          "grantTo roles [" + missingRoles.join(", ") +
+          "] not present in pg_roles — CREATE ROLE them in an earlier migration");
+      }
+    }
+
+    var selectedColumns = _buildSelectColumnList(sourceCols, spec);
+    if (selectedColumns.length === 0) {
+      throw _err("declare-view/empty-select",
+        "view '" + spec.schema + "." + spec.name +
+        "' would have zero columns after redact/sealed/hash exclusions — adjust the spec");
+    }
+
+    // Build CREATE VIEW. Each column is independently quoted so a
+    // reserved-word column name (e.g. "user", "order") resolves correctly.
+    var quotedCols = selectedColumns.map(function (c) {
+      return safeSql.quoteIdentifier(c, "postgres");
+    }).join(", ");
+    var createSql = "CREATE VIEW " + qView + " AS SELECT " + quotedCols +
+                    " FROM " + qSource;
+    if (spec.whereClause) createSql += " WHERE " + spec.whereClause;
+
+    await xdb.query(createSql, []);
+
+    // GRANT SELECT — one statement covers all roles.
+    if (spec.grantTo.length > 0) {
+      var quotedRoles = spec.grantTo.map(function (r) {
+        return safeSql.quoteIdentifier(r, "postgres");
+      }).join(", ");
+      await xdb.query(
+        "GRANT SELECT ON " + qView + " TO " + quotedRoles,
+        []
+      );
+    }
+
+    return {
+      view:                spec.schema + "." + spec.name,
+      source:              spec.source.schema + "." + spec.source.name,
+      selectedColumns:     selectedColumns,
+      redactedColumns:     _intersectInSource(spec.redactColumns, sourceCols),
+      autoExcludedSealed:  _intersectInSource(spec.sealedColumns, sourceCols),
+      hashedColumns:       Object.assign({}, spec.hashColumns),
+      grantedTo:           spec.grantTo.slice(),
+    };
+  }
+
+  async function down(xdb, ctx) {
+    if (ctx && ctx.externalDb && ctx.backendName) {
+      _ensureBackendIsPostgres(ctx.externalDb, ctx.backendName);
+    }
+    await xdb.query("DROP VIEW IF EXISTS " + qView, []);
+  }
+
+  return {
+    description: description,
+    target:      "externalDb",
+    backend:     spec.backend,
+    up:          up,
+    down:        down,
+    // Expose the validated spec for testability — declareView callers
+    // can introspect what the migration will emit without running it.
+    _spec:       spec,
+  };
+}
+
+function _objValues(obj) {
+  var out = [];
+  for (var k in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, k)) out.push(obj[k]);
+  }
+  return out;
+}
+
+module.exports = {
+  declareView:        declareView,
+  DeclareViewError:   DeclareViewError,
+};