db-firewall 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dragus Enterprises
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# db-firewall (CLI)
+
+Install, scan and verify DB Firewall's tenant isolation on PostgreSQL, from Node. No Python needed.
+
+```bash
+export DB_FIREWALL_TENANT_KEY=$(openssl rand -hex 32)          # the app uses the same key
+npx db-firewall migrate --url "$ADMIN_URL"                     # install the RLS policies and the key
+npx db-firewall scan    --url "$DATABASE_URL" --strict         # CI gate: exit 1 if a table is unprotected
+npx db-firewall verify  --url "$APP_URL" --tenant acme         # test isolation as your app's own role
+npx db-firewall key     --url "$ADMIN_URL"                     # print the database's key
+```
+
+## migrate
+
+Runs `migrations/001_postgresql.sql` (shipped unchanged in this package) as an admin role. It protects every table in the schema that has the tenant column, and is safe to re-run after you add tables.
+
+- `--column tenant_id`: the tenant column.
+- `--schema public`: the schema.
+- `--mode permissive|restrictive`: use `restrictive` when your app has RLS policies of its own (Supabase, Drizzle `pgPolicy`). The tenant policies are then AND-ed with them. See the main README, "Run the migration".
+- `--harden-signals`: revoke `pg_terminate_backend` and `pg_cancel_backend` from `PUBLIC` in this database, so tenants sharing the app role cannot end or cancel each other's requests. It covers every app and role in the database, so it is off by default and needs a superuser.
+- `--harden --app-role <role>`: also revoke what `verify` fails on that the migration can remove, from `PUBLIC` and the app role, whoever granted it: `CREATE` on the database and on every schema, `TRIGGER` and `TRUNCATE` on every table and in default privileges (so tables created later do not get them), `pg_stat_activity` with `pg_stat_get_activity` and `pg_stat_get_backend_activity` (all tenants share one role, so its sessions see each other's SQL text), and the backend signals (as `--harden-signals`), and `pg_notify()` (any session can send any payload to every listener in the database; the `NOTIFY` statement needs no grant, and roles that call `pg_notify` need `GRANT EXECUTE` again). `SELECT`, `INSERT`, `UPDATE` and `DELETE` stay. It covers the whole database, so it is off by default and needs a superuser. It refuses, and changes nothing, when the app role can act as the owner of the database or of any object in it (an owner can grant itself everything back: give them to another role first), or still has one of these privileges through a role it is a member of. `CASCADE` also removes what the app role passed on with a grant option. Roles that only have `pg_monitor` lose `pg_stat_activity` too: grant it to them again. Default privileges granted to a group role the app is in are not changed; `verify` fails on what they grant. Give the bare role name, without quotes. Run it again after granting new privileges (`GRANT ALL` includes `TRIGGER` and `TRUNCATE`).
+- `--ddl-guard`: install the DDL guard, two event triggers in this database that run at the end of every DDL command. Aft A table with the tenant column that has no firewall policies (created, renamed, given the column later, a new partition or child, or a typed table changed by `ALTER TYPE ... CASCADE`) is protected at the end of the command, the way the migration would, so it is never open until the next run. A table with a permissive policy of its own, in permissive mode, is refused instead. A command that weakens a protected table (one with firewall policies) fails: RLS turned off or not forced, a firewall policy dropped, renamed or altered (also by dropping the tenant column with `CASCADE`), another permissive policy in permissive mode (it ORs with the tenant policies), the table taken out of what the migration protects (moved to another schema, renamed to a name the migration skips, its tenant column renamed, its schema renamed), or given a parent, child or partition that is not protected, either way round (`INHERIT`, `ATTACH PARTITION`, `PARTITION OF` in another schema or as a foreign table: reading the parent shows the child's rows, and a partition gets the rows written to the parent). A rule on a protected table fails. Policy names `fw_<hash>_*` are the firewall's: no command may create one, rename a policy to one, or alter one. `TRIGGER` and `TRUNCATE` granted to another role are revoked again. A renamed table gets the policies of its new name. PostgreSQL fires no event trigger for `EXPLAIN ANALYZE CREATE TABLE AS` or `EXPLAIN ANALYZE SELECT INTO`: a table made that way stays open until the next DDL command in the database (any command protects it), and `verify` fails on it until then. With default privileges that grant the app role access to new tables, the app can read and write such a table until then. So the guard is a safety net for migrations, not a boundary against a role that holds `CREATE` on a protected schema and means harm: keep `CREATE` there to the roles that run migrations. The guard refuses an object of another role in schema `db_firewall`, or named `public._firewall_*`. Not stopped: code the table's owner attaches to it (a trigger, a CHECK constraint, a default, a generated column, an index expression, a domain constraint) runs on every tenant's writes, and can copy them out. Dropping the table is fine. It binds every role, table owners included, but a superuser and the role that owns the migration's objects: only they can skip it with `SET dbfw.ddl_guard_skip = 'on'` (the migration sets it for itself), and only a superuser can remove it (`DROP EVENT TRIGGER _firewall_ddl_guard, _firewall_ddl_drop_guard`). A later run without the flag leaves it in place. It needs a superuser. `verify` reports whether it is on.
+- `--context signed|plain`: `signed` (default) makes the policies accept a tenant only with a signature made with the key for the current transaction, so SQL the app runs cannot switch tenants. `DB_FIREWALL_TENANT_KEY`, when set, is installed (or rotated to); otherwise the database keeps its key, or generates one on the first run (`db-firewall key` prints it). See the main README, "PostgreSQL tenant context".
+
+After the migration it prints the scan.
+
+## scan
+
+Lists every table in the schema that has the tenant column, and reports whether it is protected. Protected means all of these:
+
+- RLS is enabled and forced.
+- All four firewall policies exist.
+- Each policy applies to `PUBLIC`, covers its own command, and uses exactly the migration's predicate, read with `search_path = pg_catalog`, so an operator planted in another schema shows. The CLI asks PostgreSQL to deparse that predicate on a temporary copy of the table, which is rolled back.
+- In permissive mode, no other permissive policy exists on the table.
+- The firewall functions match the migration, schema `db_firewall` and every object in it have one owner, and no `public._firewall_*` object is left (see verify, 2).
+- The policies use the expected tenant context, `--context signed` (the default) or `plain`. `tenant_context` in the report names the one they use.
+
+`--strict` exits 1 when a table is unprotected or no table is found (a wrong `--column` or `--schema`). `--json` prints `{ tables, excluded }`. Each table report has the Python scanner's fields (`hooks/scanner.py`) plus `schema` and `owner`. When the predicate check cannot run (a read-only transaction, no `TEMP` privilege, or no `SELECT` on the table), the report says why in `predicate_check`, and the table counts as unprotected.
+
+`--schema` is repeatable. `--exclude <glob>` (repeatable, `*`, `?`, `[abc]`) replaces the default exclusions, which are exactly the tables the migration skips: `_firewall_*` and the migration-history tables (`schema_migrations`, `alembic_version`, `knex_migrations`, `prisma_migrations`, `__diesel_schema_migrations`, `flyway_schema_history`). Excluded tables are always listed in the output.
+
+## verify
+
+The checks are the shared queries in `checks/postgresql.sql` (shipped as `sql/checks_postgresql.sql`); `python -m hooks.verify` in the repository runs the same file, with the same results.
+
+Connect with your app's own URL and role, not an admin's, with `DB_FIREWALL_TENANT_KEY` set to the key the app uses (exit 2 without it). `verify` tests behaviour, not only the policies. It is read-only by default: each check runs in a transaction that is rolled back.
+
+1. **The role:** RLS applies to it and to every role it is a member of. None is a superuser, has `BYPASSRLS`, is in `_firewall_bypass_roles`, or is a member of `pg_read_all_data`, `pg_write_all_data`, `pg_execute_server_program`, `pg_read_server_files` or `pg_write_server_files`. The last three run programs or read and write files as the server.
+2. **Firewall objects:** the functions the policies, the signing and the session reset use (`_firewall_is_bypass_role`, `_firewall_tenant`, `_firewall_sign`, `_firewall_nonce`, `_firewall_reset_session`, `_firewall_session_settings`) match the migration (body, `SECURITY DEFINER`, settings, volatility), and every `db_firewall._firewall_*` object has one owner. `scan` checks this too. Every function the migration creates is checked, and an extra `db_firewall._firewall_*` function fails. No role the app can use can `CREATE` in any schema or owns one, or the database (it could plant objects or operators, and reach them through a `search_path` it sets for itself with `ALTER ROLE ... SET`), or has `TRIGGER` on a table or owns one (a deferred trigger runs at COMMIT). No role the app can use can read `_firewall_keys` or execute `_firewall_sign` or `_firewall_set_tenant`. The role, and every role it can `SET ROLE` to, cannot write `_firewall_bypass_roles` or `_firewall_tenant_map`, column grants included (else it could add itself as a bypass role). It cannot act as the owner of schema `public` or of any `_firewall_*` object (else it could drop and replace the bypass list), nor of the database or any object in it, temporary objects and large objects aside (an owner can change a domain constraint or a function body that runs in other tenants' sessions, or grant itself its rights back). On PostgreSQL 15 and later the database owner owns `public`, so do not make the app role the database owner.
+3. **Tables found:** at least one table has the tenant column.
+4. **Per table:**
+   - the scan above passes;
+   - the role does not own the table (an owner can turn RLS off);
+   - the role has no `TRUNCATE` (RLS does not apply to it);
+   - with no tenant, the role sees no rows;
+   - with the tenant set but not signed, as SQL the app runs could set it, the role sees no rows (this fails on a plain context);
+   - as `--tenant`, signed with the key, every visible row belongs to that tenant.
+5. **Tenant has rows:** `--tenant` sees at least one row somewhere. A tenant with no rows proves nothing, so this fails.
+6. **Read paths RLS does not guard,** in any schema, for the role and every role it can `SET ROLE` to: no foreign table (RLS does not reach remote data). No materialized view with the tenant column or built over a function. No view or materialized view the role can read (a column grant is enough) whose chain down to a tenant table holds a materialized view or a view that runs as an owner who skips RLS (use `security_invoker = true`). No `SECURITY DEFINER` function owned by such a role that the app can execute, or that PostgreSQL runs without checking `EXECUTE`: a trigger or event trigger function, an aggregate's or range type's support function, index support (an operator family's operators too), a selectivity estimator, planner support, type I/O, an encoding conversion, a transform, a text search parser or template, or a foreign-data wrapper's or language's handler or validator. A function body is not inspected, so every such function counts, except the firewall's own. No `LEAKPROOF` function outside `pg_catalog` (it runs before the RLS filter and can leak the rows it sees). No rule other than a view's own, on any table or view (a rule's actions run as the table owner, and a write reaches a table through a view, a column grant or a cascade): use a trigger instead.
+7. **Other schemas:** no table with the tenant column that the role can read (a column grant is enough) outside `--schema`.
+
+A table no usable role can `SELECT` (such as a partition read through its parent) gets no row checks: there are no direct reads, and the other checks cover the rest. A table readable only after `SET ROLE` is inconclusive: run `verify` as that role. So is a row check whose query fails. A global check whose query fails counts as failed.
+
+`--write-probe` also tries, per table, to insert a row for another tenant, which RLS must refuse. It is rolled back, but it fires `BEFORE INSERT` triggers and uses up a sequence value, so it is off by default. A refusal by anything other than RLS is inconclusive.
+
+### Strict mode (`--strict`)
+
+The checks above look for known leak paths. `--strict` turns that into an allowlist, so unknown paths fail too. Everything a role the app can use can read must be protected tenant data:
+
+- a table the migration protects;
+- a `security_invoker` view that reads at least one table, calls no function outside `pg_catalog`, and whose chain reaches only protected tables (no materialized view, foreign table or definer view on the way). Constants in a view body (`VALUES`, literals) cannot be seen;
+- a sequence a protected table owns (`serial`, identity). Its value is shared: `nextval` shows how many rows all tenants have inserted.
+
+Anything else the app can read fails: a table without the tenant column (an audit log, a history table, a reference table), an invoker view over one or over constants, a standalone sequence, a foreign table. Also:
+
+- no large object may be readable (they are one store for the whole database, with no tenant);
+- the role may not read other sessions' SQL in `pg_stat_activity` or `pg_stat_statements` (literal values in another tenant's queries). `migrate --harden` revokes it. On managed PostgreSQL only the provider's superuser can, so `--allow-query-text` turns this check into an information line: send values as parameters. Without `--strict` it is an information line. With `--allow-query-text`, `pg_stat_statements`' own views (`pg_stat_statements`, `pg_stat_statements_info`) are accepted as readable too;
+- no `SECURITY DEFINER` function outside the firewall's own may exist, executable or not, because it runs as its owner, whatever it reads, and PostgreSQL runs some functions (triggers, aggregate, range and index support, type I/O) without checking `EXECUTE`.
+
+`--allow-global` (repeatable, `*`, `?` and `[abc]` globs; it needs `--strict`) marks data every tenant may share, such as a list of countries: `schema.name` for a table, view or sequence, `schema.name(argtypes)` for a function, as verify prints it (`app.f(*)` for every overload, and for array types; `app.*` never clears a function). In the bypass-objects check it clears only functions, such as a platform's own definer functions, and foreign tables without the tenant column; never a view over a tenant table or a rule. Allowlist deliberately: an allowlisted table that holds tenant data is a leak.
+
+Strict mode closes most of what "What a pass means" lists below: tenant data in tables without the tenant column, and copies into readable tables, now fail unless you allowlist them.
+
+### What a pass means
+
+A pass means `verify` found no known leak path. It does not prove isolation. It does not see:
+
+- **Tenant data in tables without the tenant column,** such as child tables, audit logs or history tables. Give every table that holds tenant data the tenant column, so the migration protects it. `--strict` fails on such tables unless you allowlist them.
+- **Copies made by triggers, rules or jobs** into a table the app can read, even a plain (not `SECURITY DEFINER`) trigger. `--strict` fails on the readable target unless it is protected or allowlisted.
+- **Side channels** that RLS leaves open: a `UNIQUE` or foreign-key error, or timing, can show that another tenant has a value. `verify` lists the keys on protected tables that leave out the tenant column (an information line; `--strict` fails on them): a unique key or primary key, an expression index included, and a foreign key from any table to a protected one. A single-column key on a generated value (an identity column, or a default from a sequence, `gen_random_uuid()` or `uuid_generate_v1`/`v4`) is not listed: a duplicate only shows that an id is taken. An exclusion constraint counts as a unique key, and its tenant column counts only with `=`. A foreign key passes only when the referencing table is protected and its own tenant column fills the referenced tenant column, so a plain `doc_id REFERENCES docs (id)` fails `--strict` (the app can link to, and probe for, another tenant's row). Put the tenant column in the key, as `UNIQUE (tenant_id, email)` and `FOREIGN KEY (tenant_id, doc_id) REFERENCES docs (tenant_id, id)`. Timing is not checked.
+- **Your app setting `app.current_tenant` itself.** `verify` assumes only the middleware (`withTenant`) sets it, from the authenticated session.
+- **What one role shares.** All tenants use one database role, so its sessions can read each other's current query text (`pg_stat_activity`: `migrate --harden` stops that, `--strict` fails on it), which can hold another tenant's literal values, and end each other's backends (`migrate --harden-signals` stops that). The role can also change its own defaults (`ALTER ROLE CURRENT_USER SET ...`) so its later connections fail; that is availability only. Information lines in `verify` report whether the role can signal other sessions or read their SQL, and which role-level defaults are set; they never fail.
+- **Privileges granted later.** `verify` checks the database as it is when it runs. Run it in CI and after every change to grants.
+
+Run it in CI and after schema changes, and review triggers, rules and jobs that copy tenant rows.
+
+Exit codes: 0 all checks passed; 1 a check failed; 2 usage or connection error; 3 no failure, but a check was inconclusive (not a pass).
+
+## Tests
+
+```bash
+cd packages/cli && npm ci
+DBFW_PG_URL="postgres://postgres@localhost:5432/dbfw_test" npm test
+```
+
+The tests run the CLI against a live PostgreSQL (CI: 14, 15, 16 and 17). `test/attacks.test.mjs` runs the attack corpus, `tests/attacks/postgresql.sql` in the repository: for each attack, `verify` must fail the named check, and its leak query, when it has one, must show data tenant A must not see; safe patterns must pass. The parser rejects an unknown or repeated directive, and the test pins the number of cases. Cases that need a newer server (`security_invoker` views need 15, `GRANT ... WITH INHERIT FALSE` needs 16) are skipped on older ones. They cover protected, unprotected, widened and altered tables, both policy modes, and each verify failure: a bypass role it is a member of, ownership of the table, of `public` or of a firewall function, column grants, `TRUNCATE`, a writable bypass list, definer views (also as a chain, or in another schema), materialized views, `SECURITY DEFINER` functions, other schemas, no tables, a tenant with no rows, partitions and an inconclusive probe.

package/dist/checks.d.ts

@@ -0,0 +1,19 @@
+export declare const CHECKS_FILE: URL;
+export interface GlobalCheck {
+    name: string;
+    info: boolean;
+    sql: string;
+}
+export interface Checks {
+    /** The tables the migration skips. */
+    excluded: string[];
+    /** @check and @info blocks, in file order. */
+    checks: GlobalCheck[];
+    queries: Record<string, string>;
+}
+/** Parse the file: "-- @excluded", "-- @check", "-- @info" and "-- @query"
+ *  lines start a block, which runs to the next "-- @" line. */
+export declare function parseChecks(text: string): Checks;
+export declare const CHECKS: () => Checks;
+/** A named query from the file. */
+export declare function q(name: string): string;

package/dist/checks.js

@@ -0,0 +1,55 @@
+// The shared PostgreSQL checks (checks/postgresql.sql in the repository,
+// shipped as sql/checks_postgresql.sql): the Python tools run the same file.
+import { readFileSync } from "node:fs";
+export const CHECKS_FILE = new URL("../sql/checks_postgresql.sql", import.meta.url);
+/** Parse the file: "-- @excluded", "-- @check", "-- @info" and "-- @query"
+ *  lines start a block, which runs to the next "-- @" line. */
+export function parseChecks(text) {
+    const out = { excluded: [], checks: [], queries: {} };
+    let cur = null;
+    const flush = () => {
+        if (!cur)
+            return;
+        const sql = cur.lines.join("\n").trim();
+        if (!sql)
+            throw new Error(`checks: ${cur.name} has no SQL`);
+        if (cur.kind === "query") {
+            if (out.queries[cur.name])
+                throw new Error(`checks: a second @query ${cur.name}`);
+            out.queries[cur.name] = sql;
+        }
+        else {
+            if (out.checks.some((c) => c.name === cur.name))
+                throw new Error(`checks: a second check ${cur.name}`);
+            out.checks.push({ name: cur.name, info: cur.kind === "info", sql });
+        }
+    };
+    for (const line of text.replace(/\r\n/g, "\n").split("\n")) {
+        // Comment lines stay out of the SQL: a "$1" in one is no parameter.
+        if (!line.startsWith("-- @")) {
+            if (!line.trimStart().startsWith("--"))
+                cur?.lines.push(line);
+            continue;
+        }
+        const m = line.match(/^-- @(excluded|check|info|query) (\S.*)$/);
+        if (!m)
+            throw new Error(`checks: unknown line ${line}`);
+        flush();
+        cur = null;
+        if (m[1] === "excluded")
+            out.excluded.push(...m[2].trim().split(/\s+/));
+        else
+            cur = { kind: m[1], name: m[2].trim(), lines: [] };
+    }
+    flush();
+    return out;
+}
+let cached;
+export const CHECKS = () => (cached ??= parseChecks(readFileSync(CHECKS_FILE, "utf8")));
+/** A named query from the file. */
+export function q(name) {
+    const sql = CHECKS().queries[name];
+    if (!sql)
+        throw new Error(`checks: no @query ${name}`);
+    return sql;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// db-firewall: migrate | scan | verify, for PostgreSQL.
+import { parseArgs } from "node:util";
+import pg from "pg";
+import { TENANT_KEY_ENV, tenantKey } from "./key.js";
+import { migrate } from "./migrate.js";
+import { scan } from "./scan.js";
+import { verify } from "./verify.js";
+const USAGE = `Usage: db-firewall <command> [options]
+
+Commands:
+  migrate   Install the tenant RLS policies (run as an admin role)
+  scan      Report which tables with the tenant column are protected
+  verify    Connect as your app's role and test the isolation (needs --tenant
+            and DB_FIREWALL_TENANT_KEY)
+  key       Print the database's tenant signing key (run as an admin role)
+
+Options:
+  --url <url>        PostgreSQL URL (default: $DATABASE_URL)
+  --column <name>    Tenant column (default: tenant_id)
+  --schema <name>    Schema (default: public; repeatable)
+  --mode <mode>      migrate: permissive (default) or restrictive
+  --context <ctx>    migrate/scan: signed (default) or plain. Signed: the app signs
+                     the tenant per transaction with DB_FIREWALL_TENANT_KEY, so SQL
+                     it runs cannot switch tenants. migrate installs that key when
+                     set, else keeps the database's key or generates one.
+  --harden-signals   migrate: revoke pg_terminate_backend / pg_cancel_backend from
+                     PUBLIC in this database (needs a superuser), so tenants sharing
+                     the app role cannot end each other's requests
+  --harden           migrate: also revoke CREATE on the database and every schema,
+                     TRIGGER and TRUNCATE on every table (default privileges
+                     too), and pg_stat_activity, from PUBLIC and --app-role, by
+                     any grantor (what verify fails on); needs a superuser.
+                     Refuses if --app-role owns the database, a schema or a table
+  --app-role <name>  migrate --harden: the app's role, revoked from as well
+  --ddl-guard        migrate: install event triggers that protect a new table
+                     with the tenant column at once, and refuse a change that
+                     weakens a protected table (RLS off, a firewall policy
+                     dropped or altered); needs a superuser
+  --tenant <id>      verify: a tenant id that has rows in your data
+  --write-probe      verify: also try a cross-tenant insert (rolled back, but it
+                     fires BEFORE INSERT triggers and uses up a sequence value)
+  --exclude <glob>   scan/verify: skip tables matching (repeatable; replaces the
+                     defaults, which are the tables the migration skips)
+  --strict           scan: exit 1 if any table is unprotected or none is found.
+                     verify: also fail on anything the app role can read that is
+                     not protected tenant data, and on SECURITY DEFINER functions
+  --allow-global <glob>  verify --strict: schema.name of a table, view or
+                     sequence, or schema.name(argtypes) of a function, that the
+                     app may reach without tenant scoping (shared reference
+                     data, say); repeatable. For array types, use * (app.f(*))
+  --allow-query-text verify --strict: accept that the role can read other
+                     sessions' SQL (managed PostgreSQL, where only the provider's
+                     superuser can revoke pg_stat_activity); send values as
+                     parameters
+  --json             machine-readable output
+  -h, --help
+
+Exit codes: 0 ok; 1 a check failed (scan --strict: a table is unprotected or
+none found); 2 usage or connection error; 3 verify: no failure, but a check was
+inconclusive.
+`;
+async function main(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv, allowPositionals: true,
+        options: {
+            url: { type: "string" }, column: { type: "string" }, schema: { type: "string", multiple: true },
+            "write-probe": { type: "boolean" }, "harden-signals": { type: "boolean" },
+            harden: { type: "boolean" }, "app-role": { type: "string" }, "ddl-guard": { type: "boolean" },
+            "allow-global": { type: "string", multiple: true }, "allow-query-text": { type: "boolean" },
+            mode: { type: "string" }, context: { type: "string" }, tenant: { type: "string" },
+            exclude: { type: "string", multiple: true },
+            strict: { type: "boolean" }, json: { type: "boolean" }, help: { type: "boolean", short: "h" },
+        },
+    });
+    const command = positionals[0];
+    if (values.help || !command) {
+        process.stdout.write(USAGE);
+        return command || values.help ? 0 : 2;
+    }
+    const url = values.url ?? process.env.DATABASE_URL;
+    if (!url) {
+        process.stderr.write("db-firewall: --url or DATABASE_URL is required\n");
+        return 2;
+    }
+    const context = (values.context ?? "signed").toLowerCase();
+    if (context !== "signed" && context !== "plain") {
+        process.stderr.write(`db-firewall: --context must be signed or plain, got ${values.context}\n`);
+        return 2;
+    }
+    let key;
+    try {
+        key = tenantKey();
+    }
+    catch (err) {
+        process.stderr.write(`db-firewall: ${err.message}\n`);
+        return 2;
+    }
+    if (command === "verify" && !key) {
+        process.stderr.write(`db-firewall verify: set ${TENANT_KEY_ENV} to the key your app uses ` +
+            "(db-firewall key prints the database's key)\n");
+        return 2;
+    }
+    const common = { schemas: values.schema, column: values.column, exclude: values.exclude, context: context };
+    const client = new pg.Client({ connectionString: url });
+    await client.connect();
+    try {
+        if (command === "migrate") {
+            for (const schema of values.schema?.length ? values.schema : ["public"]) {
+                await migrate(client, { schema, column: values.column, mode: values.mode, context,
+                    hardenSignals: values["harden-signals"], harden: values.harden,
+                    appRole: values["app-role"], ddlGuard: values["ddl-guard"] });
+            }
+            const result = await scan(client, common);
+            print(values.json, { migrated: true, ...result }, () => `Migration applied. ` +
+                `${result.tables.filter((t) => t.protected).length} of ${result.tables.length} tables protected.\n` +
+                tablesText(result));
+            return 0;
+        }
+        if (command === "key") {
+            const { rows } = await client.query("SELECT encode(key, 'hex') AS key FROM db_firewall._firewall_keys");
+            if (!rows.length) {
+                process.stderr.write("db-firewall: no key: run migrate first\n");
+                return 1;
+            }
+            process.stdout.write(`${rows[0].key}\n`);
+            return 0;
+        }
+        if (command === "scan") {
+            const result = await scan(client, common);
+            print(values.json, result, () => tablesText(result));
+            return values.strict && (!result.tables.length || result.tables.some((t) => !t.protected)) ? 1 : 0;
+        }
+        if (command === "verify") {
+            if (!values.tenant) {
+                process.stderr.write("db-firewall verify: --tenant is required\n");
+                return 2;
+            }
+            if ((values["allow-global"]?.length || values["allow-query-text"]) && !values.strict) {
+                process.stderr.write("db-firewall verify: --allow-global and --allow-query-text need --strict\n");
+                return 2;
+            }
+            const result = await verify(client, { ...common, tenant: values.tenant, key: key,
+                writeProbe: values["write-probe"], strict: values.strict,
+                allowGlobal: values["allow-global"],
+                allowQueryText: values["allow-query-text"] });
+            const failed = result.checks.filter((c) => c.ok === false).length;
+            const unsure = result.checks.filter((c) => c.ok === null).length;
+            print(values.json, result, () => checksText(result.checks) + skippedText(result.excluded) +
+                (failed ? `\n${failed} check(s) FAILED${unsure ? `, ${unsure} inconclusive` : ""}.\n`
+                    : unsure ? `\nNo failures, but ${unsure} check(s) inconclusive: not a pass.\n`
+                        : "\nAll checks passed.\n"));
+            return failed ? 1 : unsure ? 3 : 0;
+        }
+        process.stderr.write(`db-firewall: unknown command ${command}\n\n${USAGE}`);
+        return 2;
+    }
+    finally {
+        await client.end();
+    }
+}
+function print(json, data, text) {
+    process.stdout.write(json ? JSON.stringify(data, null, 2) + "\n" : text());
+}
+function tablesText({ tables, excluded }) {
+    if (!tables.length)
+        return "FAIL  no tables with the tenant column (wrong --column or --schema?)\n" +
+            skippedText(excluded);
+    return tables.map((t) => `${t.protected ? "OK  " : "FAIL"}  ${t.schema}.${t.table}  (${t.policy_mode}, ` +
+        `${t.tenant_context ?? "no policies"}` +
+        (t.protected ? ")" : `; ${reasons(t)})`) +
+        (t.stale_base_policy ? "  warning: stale base policy, re-run migrate" : "")).join("\n") + "\n" +
+        skippedText(excluded);
+}
+function skippedText(excluded) {
+    return excluded.length ? `Skipped (excluded): ${excluded.join(", ")}\n` : "";
+}
+function reasons(t) {
+    const r = [];
+    if (t.tenant_context === "plain")
+        r.push("plain tenant context, expected signed (re-run migrate, or scan --context plain)");
+    if (!t.rls_enabled)
+        r.push("RLS off");
+    else if (!t.rls_forced)
+        r.push("RLS not forced");
+    if (t.missing_policies.length)
+        r.push(`missing ${t.missing_policies.join(",")}`);
+    if (t.altered_policies.length && t.tenant_context !== "plain")
+        r.push(`altered ${t.altered_policies.join(",")}`);
+    if (t.policy_mode === "permissive" && t.extra_permissive_policies.length) {
+        r.push(`extra permissive ${t.extra_permissive_policies.join(",")}`);
+    }
+    if (t.predicate_check !== "ok")
+        r.push(t.predicate_check);
+    return r.join("; ");
+}
+function checksText(checks) {
+    return checks.map((c) => `${c.ok === true ? "OK  " : c.ok === false ? "FAIL" : "--  "}  ` +
+        `${c.table.padEnd(24)} ${c.check.padEnd(36)} ${c.detail}`).join("\n") + "\n";
+}
+main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (err) => {
+    process.stderr.write(`db-firewall: ${err.message}\n`);
+    process.exitCode = 2;
+});

package/dist/key.d.ts

@@ -0,0 +1,5 @@
+export declare const TENANT_KEY_ENV = "DB_FIREWALL_TENANT_KEY";
+/** The key (hex, 32 to 64 bytes), or undefined when unset. */
+export declare function tenantKey(): Buffer | undefined;
+/** hex(HMAC-SHA256(key, nonce:tenant)), as db_firewall._firewall_sign() computes it. */
+export declare const sign: (key: Buffer, nonce: string, tenant: string) => string;

package/dist/key.js

@@ -0,0 +1,15 @@
+// The signing key the app uses (DB_FIREWALL_TENANT_KEY), shared by migrate and verify.
+import { createHmac } from "node:crypto";
+export const TENANT_KEY_ENV = "DB_FIREWALL_TENANT_KEY";
+/** The key (hex, 32 to 64 bytes), or undefined when unset. */
+export function tenantKey() {
+    const raw = (process.env[TENANT_KEY_ENV] ?? "").trim();
+    if (!raw)
+        return undefined;
+    if (!/^(?:[0-9a-fA-F]{2}){32,64}$/.test(raw)) {
+        throw new Error(`${TENANT_KEY_ENV} must be 32 to 64 bytes, hex-encoded`);
+    }
+    return Buffer.from(raw, "hex");
+}
+/** hex(HMAC-SHA256(key, nonce:tenant)), as db_firewall._firewall_sign() computes it. */
+export const sign = (key, nonce, tenant) => createHmac("sha256", key).update(`${nonce}:${tenant}`, "utf8").digest("hex");

package/dist/migrate.d.ts

@@ -0,0 +1,12 @@
+import type pg from "pg";
+export declare const MIGRATION: URL;
+export declare function migrate(client: pg.ClientBase, opts?: {
+    schema?: string;
+    column?: string;
+    mode?: string;
+    context?: string;
+    hardenSignals?: boolean;
+    harden?: boolean;
+    appRole?: string;
+    ddlGuard?: boolean;
+}): Promise<void>;

package/dist/migrate.js

@@ -0,0 +1,43 @@
+// migrate: run the bundled migrations/001_postgresql.sql with the settings it reads.
+import { readFileSync } from "node:fs";
+import { tenantKey } from "./key.js";
+export const MIGRATION = new URL("../sql/001_postgresql.sql", import.meta.url);
+export async function migrate(client, opts = {}) {
+    const mode = (opts.mode ?? "permissive").toLowerCase();
+    if (mode !== "permissive" && mode !== "restrictive") {
+        throw new Error(`--mode must be permissive or restrictive, got ${opts.mode}`);
+    }
+    const context = (opts.context ?? "signed").toLowerCase();
+    if (context !== "signed" && context !== "plain") {
+        throw new Error(`--context must be signed or plain, got ${opts.context}`);
+    }
+    // DB_FIREWALL_TENANT_KEY installs (or rotates to) that key; unset keeps the
+    // database's key, or generates one on the first run. The script clears it.
+    const key = tenantKey();
+    // Session settings, as run_migration() does: the script runs its own
+    // BEGIN ... COMMIT, and this connection ends after the command.
+    // Keep the key out of the server log where this role may (a superuser):
+    // statement and parameter logging off for this session.
+    if (key) {
+        await client.query("SELECT set_config('log_statement', 'none', false), " +
+            "set_config('log_min_duration_statement', '-1', false), set_config('log_parameter_max_length', '0', false), " +
+            "set_config('log_parameter_max_length_on_error', '0', false) FROM pg_roles WHERE rolname = current_user AND rolsuper");
+    }
+    await client.query("SELECT set_config('dbfw.tenant_column', $1, false), set_config('dbfw.schema', $2, false), " +
+        "set_config('dbfw.policy_mode', $3, false), set_config('dbfw.context', $4, false), " +
+        "set_config('dbfw.tenant_key', $5, false), set_config('dbfw.harden_signals', $6, false), " +
+        "set_config('dbfw.harden', $7, false), set_config('dbfw.app_role', $8, false), " +
+        "set_config('dbfw.ddl_guard', $9, false)", [opts.column ?? "tenant_id", opts.schema ?? "public", mode, context, key?.toString("hex") ?? "",
+        opts.hardenSignals ? "on" : "off", opts.harden ? "on" : "off", opts.appRole ?? "", opts.ddlGuard ? "on" : "off"]);
+    try {
+        await client.query(readFileSync(MIGRATION, "utf8"));
+    }
+    catch (err) {
+        await client.query("ROLLBACK").catch(() => { }); // the script's transaction, if left open
+        throw err;
+    }
+    finally {
+        // The script clears the key when it succeeds; a failed run must not leave it.
+        await client.query("SELECT set_config('dbfw.tenant_key', '', false)").catch(() => { });
+    }
+}

package/dist/scan.d.ts

@@ -0,0 +1,55 @@
+import type pg from "pg";
+/** Exactly the tables migrations/001_postgresql.sql skips (@excluded in the
+ *  checks file), so a table the migration protects is never skipped here.
+ *  Skipped tables are reported. */
+export declare const DEFAULT_EXCLUDED: string[];
+export interface TableReport {
+    schema: string;
+    table: string;
+    protected: boolean;
+    has_tenant_col: true;
+    has_rls_policy: boolean;
+    owner: string;
+    rls_enabled: boolean;
+    rls_forced: boolean;
+    policy_mode: "permissive" | "restrictive";
+    missing_policies: string[];
+    extra_permissive_policies: string[];
+    altered_policies: string[];
+    stale_base_policy: boolean;
+    predicate_check: string;
+    /** The context the policies use: signed, plain, or altered (neither); null without policies. */
+    tenant_context: "signed" | "plain" | "altered" | null;
+}
+export type Context = "signed" | "plain";
+/** The migration's predicate for dbfw.context signed (default) or plain. */
+export declare function predicate(column: string, context: Context): string;
+export declare const ident: (name: string) => string;
+/** fnmatch-style glob (*, ?, [abc], [!abc]), as the Python scanner matches. */
+export declare function globMatch(pattern: string, name: string): boolean;
+export interface ScanResult {
+    tables: TableReport[];
+    excluded: string[];
+}
+/**
+ * Every function the migration creates must match it (body, SECURITY DEFINER,
+ * settings, volatility, language, return type), with no extra db_firewall._firewall_*
+ * function: the policies call some of them, others sign, and a changed body
+ * (say, a session-setting "maintenance switch") opens every table while the
+ * policies still look exact. Every db_firewall._firewall_* object must have one
+ * owner, or only superusers: an object another role planted keeps its owner.
+ */
+export declare function firewallObjects(client: pg.ClientBase): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+/** Run fn with search_path = pg_catalog, pg_temp, so a planted operator in
+ *  another schema cannot hide in how a policy reads, then put it back. */
+export declare function withCatalogPath<T>(client: pg.ClientBase, fn: () => Promise<T>): Promise<T>;
+/** Scan every table in the schemas that has the tenant column. */
+export declare function scan(client: pg.ClientBase, opts?: {
+    schemas?: string[];
+    column?: string;
+    exclude?: string[];
+    context?: Context;
+}): Promise<ScanResult>;