db-firewall 0.0.0-stage → 0.1.0

package/dist/scan.js

@@ -0,0 +1,199 @@
+// PostgreSQL scan: the queries are in the shared checks file, which
+// hooks/scan_engines.py (_scan_postgres) runs too, so TypeScript teams need no
+// Python. The logic around them is kept in step with the Python scanner.
+import { readFileSync } from "node:fs";
+import { CHECKS, q } from "./checks.js";
+import { MIGRATION } from "./migrate.js";
+/** 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 const DEFAULT_EXCLUDED = CHECKS().excluded;
+/** The migration's predicate for dbfw.context signed (default) or plain. */
+export function predicate(column, context) {
+    return context === "plain"
+        ? `${ident(column)} = NULLIF(current_setting('app.current_tenant', true), '') ` +
+            "OR db_firewall._firewall_is_bypass_role(current_user::text)"
+        : `${ident(column)} = (SELECT db_firewall._firewall_tenant()) ` +
+            "OR (SELECT db_firewall._firewall_is_bypass_role(current_user::text))";
+}
+// The tables and their policies: @query scan_tables.
+const CMD = { sel: "SELECT", ins: "INSERT", upd: "UPDATE", del: "DELETE" };
+export const ident = (name) => `"${name.replace(/"/g, '""')}"`;
+/** fnmatch-style glob (*, ?, [abc], [!abc]), as the Python scanner matches. */
+export function globMatch(pattern, name) {
+    let re = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "*")
+            re += ".*";
+        else if (ch === "?")
+            re += ".";
+        else if (ch === "[") {
+            // As fnmatch: a leading "!" negates, then a leading "]" is literal.
+            let j = i + 1;
+            if (pattern[j] === "!")
+                j++;
+            if (pattern[j] === "]")
+                j++;
+            const end = pattern.indexOf("]", j);
+            if (end < 0) {
+                re += "\\[";
+                continue;
+            }
+            // fnmatch drops a reversed range ([z-a]) instead of failing.
+            let body = pattern.slice(i + 1, end).replace(/(.)-(.)/g, (m, a, b) => (a > b ? "" : m)).replace(/\\/g, "\\\\");
+            if (body.startsWith("!"))
+                body = "^" + body.slice(1).replace(/[[\]]/g, "\\$&");
+            else
+                body = (body.startsWith("^") ? "\\" : "") + body.replace(/[[\]]/g, "\\$&"); // "^": a literal, as fnmatch reads it
+            re += `[${body}]`;
+            i = end;
+        }
+        else
+            re += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    // "s": * and ? match a newline too, as in fnmatch.
+    try {
+        return new RegExp(`^${re}$`, "s").test(name);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The firewall predicate exactly as PostgreSQL deparses it for this table: a
+ * policy with the migration's predicate on a temporary copy of the table's
+ * columns, read back, then rolled back. Exact comparison catches a changed
+ * cast, constant or function overload.
+ */
+async function reference(client, rel, column, context) {
+    const pred = predicate(column, context);
+    await client.query("BEGIN");
+    try {
+        await client.query(`CREATE TEMP TABLE _fw_ref (LIKE ${rel})`);
+        await client.query(`CREATE POLICY _fw_ref_p ON pg_temp._fw_ref USING (${pred}) WITH CHECK (${pred})`);
+        const { rows } = await client.query(q("reference_qual"));
+        return rows[0] ? [rows[0].qual, null] : [null, "no result"];
+    }
+    catch (err) {
+        return [null, String(err.message).split("\n")[0] ?? "error"];
+    }
+    finally {
+        await client.query("ROLLBACK");
+    }
+}
+const norm = (x) => x.replace(/\s+/g, " ").trim();
+/**
+ * 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 async function firewallObjects(client) {
+    const sql = readFileSync(MIGRATION, "utf8");
+    const want = [...sql.matchAll(/CREATE OR REPLACE FUNCTION db_firewall\.(_firewall_\w+)\(([^)]*)\)\s*RETURNS (\w+) AS \$\$([\s\S]*?)\$\$ LANGUAGE (\w+)([^;]*);/g)]
+        .map(([, name, args, ret, body, lang, tail]) => ({
+        name: name, sig: args.split(",").map((a) => a.trim().split(/\s+/)[1]?.toLowerCase()).filter(Boolean).join(", "),
+        ret: ret.toLowerCase(), body: body, lang: lang.toLowerCase(), tail: tail,
+    }));
+    const diff = [];
+    for (const w of want) {
+        const { rows: [f] } = await client.query(q("fw_function"), [`db_firewall.${w.name}(${w.sig})`]);
+        if (!f) {
+            diff.push(`${w.name} (missing)`);
+            continue;
+        }
+        const path = /SET search_path = ([^\n;]+?)\s*$/m.exec(w.tail)?.[1];
+        const what = [
+            norm(f.prosrc) !== norm(w.body) && "body",
+            f.prosecdef !== /SECURITY DEFINER/.test(w.tail) && "SECURITY DEFINER",
+            JSON.stringify(f.proconfig) !== JSON.stringify(path ? [`search_path=${path}`] : null) && "settings",
+            f.provolatile !== (/STABLE/.test(w.tail) ? "s" : /IMMUTABLE/.test(w.tail) ? "i" : "v") && "volatility",
+            (f.lanname !== w.lang || f.ret !== w.ret) && "language or return type",
+        ].filter(Boolean);
+        if (what.length)
+            diff.push(`${w.name} (${what.join(", ")})`);
+    }
+    const { rows: extra } = await client.query(q("fw_extra"), [want.map((w) => `${w.name}(${w.sig})`)]);
+    if (extra.length)
+        diff.push(`extra ${extra.map((e) => e.fn).join(", ")}`);
+    const { rows: owners } = await client.query(q("fw_owners"));
+    const mixed = owners.length > 1 && owners.some((o) => !o.super);
+    if (mixed) {
+        diff.push(`more than one owner (${owners.map((o) => `${o.owner}: ${o.objects}`).join("; ")}): ` +
+            "objects another role planted? drop those and re-run the migration");
+    }
+    return { ok: diff.length === 0, detail: diff.length
+            ? `differ from the migration: ${diff.join("; ")}${mixed ? "" : ": re-run the migration"}`
+            : "match the migration, one owner" };
+}
+/** 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 async function withCatalogPath(client, fn) {
+    const { rows: [r] } = await client.query("SELECT current_setting('search_path') AS old, set_config('search_path', 'pg_catalog, pg_temp', false)");
+    try {
+        return await fn();
+    }
+    finally {
+        await client.query("SELECT set_config('search_path', $1, false)", [r.old]);
+    }
+}
+/** Scan every table in the schemas that has the tenant column. */
+export function scan(client, opts = {}) {
+    return withCatalogPath(client, () => scanTables(client, opts));
+}
+async function scanTables(client, opts) {
+    const context = opts.context ?? "signed";
+    // The predicate calls these: when they differ, no table is protected.
+    const objects = await firewallObjects(client).catch((e) => ({ ok: false, detail: e.message }));
+    const schemas = opts.schemas?.length ? opts.schemas : ["public"];
+    const column = opts.column ?? "tenant_id";
+    const exclude = opts.exclude ?? DEFAULT_EXCLUDED;
+    const out = [], excluded = [];
+    for (const schema of schemas) {
+        const { rows } = await client.query(q("scan_tables"), [schema, column]);
+        for (const r of rows) {
+            if (exclude.some((p) => globMatch(p, r.table))) {
+                excluded.push(`${schema}.${r.table}`);
+                continue;
+            }
+            const policies = r.policies;
+            const [ref, why] = policies.length ? await reference(client, r.ref_rel, column, context) : [null, null];
+            const unverified = policies.length > 0 && ref === null;
+            const alteredFrom = (want) => policies.filter(([name, cmd, roles, qual, check]) => {
+                const op = name.slice(name.lastIndexOf("_") + 1);
+                const wantQual = ["sel", "upd", "del"].includes(op) ? want : null;
+                const wantCheck = ["ins", "upd"].includes(op) ? want : null;
+                return !(roles.length === 1 && roles[0] === "public") || cmd !== CMD[op]
+                    || qual !== wantQual || check !== wantCheck;
+            }).map(([name]) => name).sort();
+            const altered = ref === null ? [] : alteredFrom(ref);
+            // Policies in the other context count as altered; the report names it.
+            let found = policies.length && !unverified && !altered.length ? context : null;
+            if (policies.length && !unverified && altered.length) {
+                const other = context === "signed" ? "plain" : "signed";
+                const [ref2] = await reference(client, r.ref_rel, column, other);
+                found = ref2 !== null && !alteredFrom(ref2).length ? other : "altered";
+            }
+            const extra = [...r.extra].sort();
+            out.push({
+                schema, table: r.table, has_tenant_col: true, has_rls_policy: r.missing.length === 0, owner: r.owner,
+                rls_enabled: r.enabled, rls_forced: r.forced,
+                policy_mode: r.restrictive ? "restrictive" : "permissive",
+                missing_policies: [...r.missing].sort(),
+                extra_permissive_policies: extra,
+                altered_policies: altered,
+                tenant_context: found,
+                stale_base_policy: r.base && extra.some((e) => !e.endsWith("_base")),
+                predicate_check: unverified
+                    ? `unavailable: ${why} (run outside a read-only transaction, with the TEMP privilege and SELECT on the table)`
+                    : !objects.ok ? `firewall functions ${objects.detail}` : "ok",
+                protected: r.enabled && r.forced && r.missing.length === 0 && altered.length === 0 && !unverified
+                    && objects.ok && (r.restrictive || extra.length === 0),
+            });
+        }
+    }
+    return { tables: out, excluded };
+}

package/dist/verify.d.ts

@@ -0,0 +1,40 @@
+import type pg from "pg";
+import { type GlobalCheck } from "./checks.js";
+import { type TableReport } from "./scan.js";
+/** ok: true pass, false fail, null inconclusive (counted separately, never as a pass). */
+export interface Check {
+    table: string;
+    check: string;
+    ok: boolean | null;
+    detail: string;
+}
+/**
+ * The global checks of the shared checks file (@check and @info blocks), in
+ * file order, then the firewall functions. The "strict:" ones run only with
+ * --strict, after the table checks. One client runs one query at a time.
+ */
+export declare function roleChecks(client: pg.ClientBase): Promise<Check[]>;
+/** One @check or @info block: ok only when the row says true (NULL fails). */
+export declare function fileCheck(client: pg.ClientBase, c: GlobalCheck): Promise<Check>;
+type VerifyOpts = {
+    tenant: string;
+    key: Buffer;
+    schemas?: string[];
+    column?: string;
+    exclude?: string[];
+    writeProbe?: boolean;
+    /** Allowlist mode: see strictChecks(). */
+    strict?: boolean;
+    allowGlobal?: string[];
+    /** --strict: accept that the role reads other sessions' SQL (an info line instead). */
+    allowQueryText?: boolean;
+};
+type VerifyResult = {
+    checks: Check[];
+    tables: TableReport[];
+    excluded: string[];
+};
+/** Every check runs with search_path = pg_catalog, pg_temp: a planted "="
+ *  must not make "tenant sees only its rows" count another tenant's rows as own. */
+export declare function verify(client: pg.ClientBase, opts: VerifyOpts): Promise<VerifyResult>;
+export {};

package/dist/verify.js

@@ -0,0 +1,271 @@
+import { sign } from "./key.js";
+import { CHECKS, q } from "./checks.js";
+import { firewallObjects, globMatch, ident, scan, withCatalogPath } from "./scan.js";
+const RLS_VIOLATION = "42501"; // insufficient_privilege: what an RLS refusal raises
+const MARK = "__dbfw_verify_other__";
+/**
+ * The global checks of the shared checks file (@check and @info blocks), in
+ * file order, then the firewall functions. The "strict:" ones run only with
+ * --strict, after the table checks. One client runs one query at a time.
+ */
+export async function roleChecks(client) {
+    const out = [];
+    for (const c of CHECKS().checks.filter((x) => !x.name.startsWith("strict:")))
+        out.push(await fileCheck(client, c));
+    // The policies call these (and they sign): see firewallObjects().
+    out.push(await guard("firewall functions unchanged", () => firewallObjects(client)));
+    return out;
+}
+/** One @check or @info block: ok only when the row says true (NULL fails). */
+export async function fileCheck(client, c) {
+    const run = async () => {
+        const { rows: [r] } = await client.query(c.sql);
+        return { ok: r.ok === true, detail: String(r.detail) };
+    };
+    return c.info ? info(c.name, run) : guard(c.name, run);
+}
+/** An information line: always ok, also when its query fails (say, an
+ *  unreadable catalog), so it can never change verify's result. */
+async function info(check, fn) {
+    try {
+        return { table: "-", check, ...await fn(), ok: true };
+    }
+    catch (err) {
+        return { table: "-", check, ok: true, detail: `could not read: ${msg(err)}` };
+    }
+}
+/** A global check; a query error fails it (a precondition that cannot be checked is not met). */
+async function guard(check, fn) {
+    try {
+        return { table: "-", check, ...await fn() };
+    }
+    catch (err) {
+        return { table: "-", check, ok: false, detail: `could not check (is the migration installed?): ${msg(err)}` };
+    }
+}
+/** Run fn in a transaction with that context, and always roll back. */
+async function inTx(client, ctx, fn) {
+    await client.query("BEGIN");
+    try {
+        if (ctx?.key) {
+            const { rows: [r] } = await client.query(q("nonce"));
+            await client.query("SELECT set_config('app.current_tenant', $1, true), set_config('app.tenant_sig', $2, true)", [ctx.tenant, sign(ctx.key, r.n, ctx.tenant)]);
+        }
+        else if (ctx) {
+            await client.query("SELECT set_config('app.current_tenant', $1, true)", [ctx.tenant]);
+        }
+        return await fn();
+    }
+    finally {
+        await client.query("ROLLBACK");
+    }
+}
+/** Every check runs with search_path = pg_catalog, pg_temp: a planted "="
+ *  must not make "tenant sees only its rows" count another tenant's rows as own. */
+export function verify(client, opts) {
+    return withCatalogPath(client, () => verifyTables(client, opts));
+}
+async function verifyTables(client, opts) {
+    const signed = { tenant: opts.tenant, key: opts.key };
+    const schemas = opts.schemas?.length ? opts.schemas : ["public"];
+    const column = opts.column ?? "tenant_id";
+    const checks = await roleChecks(client);
+    const { tables, excluded } = await scan(client, { schemas, column, exclude: opts.exclude, context: "signed" });
+    if (!tables.length) {
+        checks.push({ table: "-", check: "tables found", ok: false,
+            detail: `no table with column ${column} in ${schemas.join(", ")} (wrong --column or --schema?)` });
+    }
+    let ownRows = 0;
+    for (const t of tables) {
+        const label = `${t.schema}.${t.table}`, name = `${ident(t.schema)}.${ident(t.table)}`;
+        // Privileges RLS does not cover: the owner can turn RLS off; TRUNCATE ignores it.
+        const { rows: [priv] } = await client.query(q("table_privileges"), [name, column]);
+        checks.push({ table: label, check: "role does not own the table", ok: !priv.owns,
+            detail: priv.owns ? `owned by ${t.owner}, which this role can act as: it can disable RLS`
+                : `owned by ${t.owner}` });
+        checks.push({ table: label, check: "no TRUNCATE", ok: !priv.truncate,
+            detail: priv.truncate ? "TRUNCATE is granted and RLS does not apply to it" : "not granted" });
+        checks.push({ table: label, check: "policies", ok: t.protected,
+            detail: t.protected ? `${t.policy_mode} policies in place` : summary(t) });
+        if (!priv.can_select) {
+            // No direct reads (e.g. a partition read through its parent): the policies
+            // above and the view and function checks below cover the other paths.
+            checks.push(priv.some_role_selects
+                ? { table: label, check: "row checks", ok: null,
+                    detail: `readable only after SET ROLE to another role: run verify as that role` }
+                : { table: label, check: "row checks", ok: true, detail: `no role it can use can SELECT ${column}: no direct reads` });
+            continue;
+        }
+        try {
+            // No tenant: no rows at all (fail closed).
+            const count = async () => Number((await client.query(`SELECT count(*) AS n FROM ${name}`)).rows[0].n);
+            const none = await inTx(client, null, count);
+            checks.push({ table: label, check: "no tenant sees nothing", ok: none === 0, detail: `${none} rows visible` });
+            // The tenant set without a signature, as SQL the app (or an agent) runs could set it.
+            const unsigned = await inTx(client, { tenant: opts.tenant }, count);
+            checks.push({ table: label, check: "unsigned tenant sees nothing", ok: unsigned === 0,
+                detail: unsigned ? `${unsigned} rows visible: SQL the app runs can switch tenants` : "0 rows" });
+            // As the tenant: every visible row is the tenant's.
+            const [foreign, own] = await inTx(client, signed, async () => {
+                const { rows: [r] } = await client.query(`SELECT count(*) FILTER (WHERE ${ident(column)} IS DISTINCT FROM $1) AS foreign,
+                  count(*) FILTER (WHERE ${ident(column)} = $1) AS own FROM ${name}`, [opts.tenant]);
+                return [Number(r.foreign), Number(r.own)];
+            });
+            ownRows += own;
+            checks.push({ table: label, check: "tenant sees only its rows", ok: foreign === 0,
+                detail: `${own} own rows, ${foreign} rows of another tenant visible` });
+        }
+        catch (err) {
+            checks.push({ table: label, check: "row checks", ok: null, detail: `query failed: ${msg(err)}` });
+            continue;
+        }
+        if (opts.writeProbe)
+            checks.push(await writeProbe(client, label, name, column, signed));
+    }
+    if (tables.length && ownRows === 0) {
+        checks.push({ table: "-", check: "tenant has rows", ok: false,
+            detail: `tenant ${opts.tenant} sees no rows in any table, so the row checks prove nothing: use a tenant that has data, and check that ` +
+                `DB_FIREWALL_TENANT_KEY is the database's key (db-firewall key)` });
+    }
+    checks.push(await bypassObjects(client, column, opts.allowGlobal ?? []));
+    checks.push(await otherSchemas(client, schemas, column));
+    checks.push(await keysCheck(client, tables.filter((t) => t.protected), column, !!opts.strict));
+    if (opts.strict) {
+        checks.push(...await strictChecks(client, tables.filter((t) => t.protected), opts.allowGlobal ?? [], !!opts.allowQueryText));
+    }
+    else
+        checks.push(await queryText(client, false));
+    return { checks, tables, excluded };
+}
+/**
+ * Opt-in (--write-probe): insert a row for another tenant as --tenant, which
+ * RLS must refuse. Rolled back, but it fires BEFORE INSERT triggers and uses
+ * up a sequence value even when refused.
+ */
+async function writeProbe(client, label, name, column, ctx) {
+    try {
+        await inTx(client, ctx, () => client.query(`INSERT INTO ${name} (${ident(column)}) VALUES ($1)`, [MARK]));
+        return { table: label, check: "cross-tenant insert refused", ok: false,
+            detail: "a row for another tenant was accepted (rolled back)" };
+    }
+    catch (err) {
+        const code = err.code;
+        return code === RLS_VIOLATION && /row-level security/i.test(msg(err))
+            ? { table: label, check: "cross-tenant insert refused", ok: true, detail: "refused by RLS" }
+            : { table: label, check: "cross-tenant insert refused", ok: null, detail: `inconclusive: ${msg(err)}` };
+    }
+}
+/**
+ * Read paths RLS does not guard, in any schema, that the role can use: the
+ * @query bypass_* blocks of the checks file (views and materialized views,
+ * foreign tables, rules, functions that run as their owner or LEAKPROOF).
+ */
+function bypassObjects(client, column, allow) {
+    return guard("no RLS-bypassing views or functions", async () => {
+        const { rows: views } = await client.query(q("bypass_views"), [column]);
+        const { rows: foreign } = await client.query(q("bypass_foreign"), [column]);
+        const { rows: rules } = await client.query(q("bypass_rules"));
+        const { rows: fns } = await client.query(q("bypass_functions"));
+        // --allow-global clears only what may hold shared data by design: a function
+        // (named with its arguments) or a foreign table without the tenant column.
+        // Never a view over a tenant table or a rule.
+        const list = [
+            ...views.map((v) => `${v.matview ? "materialized view" : "view"} ${v.name} (owner ${v.owner})`),
+            ...foreign.filter((f) => f.tenant || !allowedRel(allow, f.name)).map((f) => `foreign table ${f.name}`),
+            ...rules.map((r) => `rule ${r.name} (use a trigger)`),
+            ...fns.filter((f) => !allowedFn(allow, f.name))
+                .map((f) => `${f.leakproof ? "LEAKPROOF" : "SECURITY DEFINER"} function ${f.name} (owner ${f.owner})`),
+        ];
+        return { ok: list.length === 0,
+            detail: list.length ? `the role can read through: ${list.join("; ")}` : "none found" };
+    });
+}
+// --allow-global: an entry with "(" names functions with their arguments
+// (schema.name(argtypes), as verify prints them; "app.f(*)" for every
+// overload); one without names relations. "app.*" never clears a function.
+const allowedRel = (globs, name) => globs.some((g) => !g.includes("(") && globMatch(g, name));
+const allowedFn = (globs, sig) => globs.some((g) => g.includes("(") && globMatch(g, sig));
+const listed = (names) => names.slice(0, 25).join(", ") + (names.length > 25 ? `, and ${names.length - 25} more` : "");
+/** @query query_text. --strict fails on it (unless --allow-query-text); else an information line. */
+function queryText(client, strict) {
+    const check = async () => {
+        const { rows: [r] } = await client.query(q("query_text"));
+        return { ok: !r.can, detail: r.can
+                ? "yes: SQL one tenant runs can read the query text of another tenant's session (pg_stat_activity, " +
+                    "pg_stat_statements), literal values included (send values as parameters; migrate --harden revokes it, " +
+                    "or --allow-query-text where only the provider can)" : "no (pg_stat_activity and pg_stat_statements revoked)" };
+    };
+    return strict ? guard("strict: cannot read other sessions' SQL", check)
+        : info("reads other sessions' SQL (info)", check);
+}
+/**
+ * --strict: an allowlist instead of a list of known leak paths. Everything a
+ * role the app can use can read must be protected tenant data (see @query
+ * strict_readable); anything else needs --allow-global schema.name. The
+ * "strict:" @check blocks of the file, no SECURITY DEFINER function outside
+ * the firewall's own unless allowlisted, and no other sessions' SQL.
+ */
+async function strictChecks(client, protectedTables, allow, allowQueryText) {
+    const readable = () => guard("strict: only tenant data readable", async () => {
+        const { rows } = await client.query(q("strict_readable"), [JSON.stringify(protectedTables.map((t) => [t.schema, t.table]))]);
+        // --allow-query-text also accepts the views of the pg_stat_statements extension.
+        const bad = rows.filter((r) => !allowedRel(allow, r.name) && !(allowQueryText && r.extension === "pg_stat_statements") && !(r.safe || (r.invoker && !r.broken && r.blockers.every((b) => allowedRel(allow, b)))))
+            .map((r) => r.name).sort();
+        return { ok: bad.length === 0, detail: bad.length
+                ? `readable but not protected tenant data: ${listed(bad)} (protect them, revoke, or --allow-global schema.name)`
+                : "everything readable is protected tenant data or allowlisted" };
+    });
+    const definer = () => guard("strict: no SECURITY DEFINER functions", async () => {
+        const { rows } = await client.query(q("strict_definer"));
+        const bad = rows.filter((r) => !allowedFn(allow, r.sig)).map((r) => r.sig);
+        return { ok: bad.length === 0, detail: bad.length
+                ? `runs as its owner: ${listed(bad)} (drop it or make it SECURITY INVOKER, or --allow-global 'schema.name(args)')`
+                : "none outside the firewall's own (or allowlisted)" };
+    });
+    const out = [await readable()];
+    for (const c of CHECKS().checks.filter((x) => x.name.startsWith("strict:")))
+        out.push(await fileCheck(client, c));
+    out.push(await definer(), await queryText(client, !allowQueryText));
+    return out;
+}
+/** @query keys_without_tenant: a side channel, so --strict fails on it; else an information line. */
+function keysCheck(client, protectedTables, column, strict) {
+    const check = async () => {
+        const { rows } = await client.query(q("keys_without_tenant"), [JSON.stringify(protectedTables.map((t) => [t.schema, t.table])), column]);
+        const items = rows.map((r) => r.item);
+        return { ok: items.length === 0, detail: items.length
+                ? `without the tenant column: ${listed(items)} (a duplicate, or a missing parent, tells the app that another ` +
+                    `tenant has the value: put ${column} in the key)`
+                : `every key includes ${column}` };
+    };
+    return strict ? guard("strict: keys include the tenant", check) : info("keys include the tenant (info)", check);
+}
+/** Tables with the tenant column outside the scanned schemas that the role can read. */
+function otherSchemas(client, schemas, column) {
+    return guard("no tenant tables in other schemas", async () => {
+        const { rows } = await client.query(q("other_schemas"), [schemas, column]);
+        return { ok: rows.length === 0,
+            detail: rows.length ? `not checked, readable: ${rows.map((r) => r.name).join(", ")} (add --schema)`
+                : "none readable" };
+    });
+}
+function summary(t) {
+    if (t.tenant_context === "plain")
+        return "plain tenant context: SQL the app runs can switch tenants (re-run migrate)";
+    const parts = [];
+    if (!t.rls_enabled)
+        parts.push("RLS off");
+    else if (!t.rls_forced)
+        parts.push("RLS not forced");
+    if (t.missing_policies.length)
+        parts.push(`missing ${t.missing_policies.join(",")}`);
+    if (t.altered_policies.length)
+        parts.push(`altered ${t.altered_policies.join(",")}`);
+    if (t.policy_mode === "permissive" && t.extra_permissive_policies.length) {
+        parts.push(`extra permissive ${t.extra_permissive_policies.join(",")}`);
+    }
+    if (t.predicate_check !== "ok")
+        parts.push(t.predicate_check);
+    return parts.join("; ") || "not protected";
+}
+const msg = (err) => String(err.message).split("\n")[0] ?? "error";

package/package.json

@@ -1,6 +1,33 @@
-{
-  "name": "db-firewall",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "db-firewall",
+  "version": "0.1.0",
+  "description": "DB Firewall CLI for PostgreSQL: install the tenant RLS policies, scan them, and verify isolation as your app's role.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "db-firewall": "./dist/cli.js"
+  },
+  "files": ["dist", "sql", "README.md"],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node scripts/copy-sql.mjs && tsc -p tsconfig.json",
+    "test": "npm run build && node --test --test-concurrency=1 \"test/**/*.test.mjs\"",
+    "prepack": "npm run build"
+  },
+  "keywords": ["postgres", "rls", "row-level-security", "multi-tenant", "ai-agent", "cli", "security-scanner"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zackbear/DB-firewall.git",
+    "directory": "packages/cli"
+  },
+  "dependencies": {
+    "pg": "8.23.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.5",
+    "@types/pg": "8.23.1",
+    "typescript": "5.9.3"
+  }
+}