@schema-weaver/pg-connector 0.0.0-stage → 2.0.1

package/dist/esm/permissions/role-policy.d.ts

@@ -0,0 +1,217 @@
+import { Role } from '../protocol/envelope';
+import { StatementClassification } from '../execution/types';
+import type { SideEffectKind } from '../execution/function-effects';
+import type { IntrospectionDetail } from '../execution/introspection';
+import { PermissionLevel } from './types';
+/**
+ * What a role can do, regardless of permission level.
+ *
+ * `approve_ddl` is separate from `ddl` on purpose: being able to run a
+ * statement yourself and being able to authorise someone else's statement are
+ * different powers, and only the second one is exercised by the manual
+ * approval flow.
+ */
+export type RoleCapability = 'introspect' | 'introspect_full' | 'query_read' | 'query_write' | 'ddl' | 'migration_run' | 'approve_ddl' | 'cancel' | 'view_history' | 'manage_team' | 'manage_agent';
+/**
+ * Capability matrix.
+ *
+ * `viewer` and `data_reader` hold `introspect` but NOT `introspect_full`, so
+ * they receive the reduced snapshot (see `IntrospectionDetail` in
+ * execution/introspection.ts). Admin and developer hold both. This keeps the
+ * data explorer usable for a read-only user while removing the schema dump.
+ */
+export declare const ROLE_CAPABILITIES: Record<Role, RoleCapability[]>;
+/** Introspection detail level implied by a role's capabilities. */
+export declare function introspectionDetailFor(role: Role): IntrospectionDetail;
+/**
+ * Ordering of roles by privilege, lowest first.
+ *
+ * Used to decide whether one principal may act on another's behalf (e.g. running
+ * a migration plan another user registered). It is a *matrix* ordering, not a
+ * real security hierarchy: the values come from this table and nothing else, so
+ * an unrecognised role can never be treated as privileged.
+ */
+export declare const ROLE_PRIVILEGE_RANK: Record<Role, number>;
+/**
+ * Ordering of permission levels by permissiveness, lowest first.
+ *
+ * `read_only` is the strictest. A plan registered while a database was at a
+ * permissive level must not be laundered through a stricter one: a plan that
+ * needed no human at `full` may not execute unattended at `auto_upgrade`.
+ */
+export declare const PERMISSION_LEVEL_RANK: Record<PermissionLevel, number>;
+/** Check if a role has a specific capability. */
+export declare function hasCapability(role: Role, cap: RoleCapability): boolean;
+/** True when `role` is at least as privileged as `minimum`. */
+export declare function isAtLeastAsPrivileged(role: Role, minimum: Role): boolean;
+/**
+ * True when `role` is strictly more privileged than `minimum`.
+ *
+ * Acting on another principal's behalf requires a *higher* role than they held,
+ * never merely an equal one: two developers are peers, and one peer's plan is
+ * not the other's to run.
+ */
+export declare function isStrictlyMorePrivileged(role: Role, minimum: Role): boolean;
+/** True when `level` is at least as permissive as `minimum`. */
+export declare function isAtLeastAsPermissive(level: PermissionLevel, minimum: PermissionLevel): boolean;
+/**
+ * Side effects that escape the transaction, and therefore escape
+ * `default_transaction_read_only` as well.
+ *
+ * `NOTIFY` is delivered when the statement commits and is not rolled back;
+ * advisory locks are released by session end, not by `ROLLBACK`; a sequence
+ * advance and an XID allocation both persist (the XID is written to WAL).
+ * `read_only` is a restriction on writes to relations, so none of these is
+ * covered by it, and none of them is recorded by the audit chain unless the
+ * classifier records it here.
+ */
+export declare const NON_TRANSACTIONAL_SIDE_EFFECTS: ReadonlySet<SideEffectKind>;
+/**
+ * True when the statement performs a side effect that a rollback does not undo.
+ *
+ * Consulted by `isProvableRead()` (any such effect makes the statement not a
+ * read) and exported so callers that need to explain WHY a statement was
+ * escalated do not have to re-derive the rule.
+ */
+export declare function hasNonTransactionalSideEffect(c: StatementClassification): boolean;
+/**
+ * The clause that says WHY {@link isProvableRead} returned false, in words a
+ * caller can act on.
+ *
+ * The permission layer refuses first and explains second, and the explanation
+ * used to assert that a refused statement "calls a function with a side effect
+ * outside the transaction (a notification, an advisory lock, …)" whenever any
+ * function was involved. For `SELECT extract(year FROM started_at)` that is
+ * simply false: `extract` does not notify, lock or advance anything, it is
+ * merely not proved `IMMUTABLE`. An automated caller reading a wrong reason
+ * adapts to the wrong thing, so this names the actual `pg_proc` verdict, the
+ * actual side-effect family, or the structural reason — whichever is the real
+ * cause, in that order of specificity.
+ *
+ * @returns A lowercase clause with no trailing full stop, suitable for
+ *   splicing into `Read-only mode: <clause>.`
+ */
+export declare function explainWhyNotAProvableRead(c: StatementClassification): string;
+/**
+ * True only for a statement that is provably side-effect free: one statement,
+ * parsed by PostgreSQL's own grammar, classified as a read, with no read
+ * violations, no recorded side effect, and every function it calls proved
+ * `IMMUTABLE` and not `SECURITY DEFINER` by `pg_proc`.
+ *
+ * This is the single definition of "a read" used by the permission layer. A
+ * classification that does not satisfy every clause is treated as a write.
+ *
+ * The function clause is what closes the transitive hole: an
+ * operator-written `SECURITY DEFINER` wrapper around `pg_read_file`, or any
+ * VOLATILE function that INSERTs, parses as a `SELECT` and is on no deny-list,
+ * but `pg_proc` reports it as unsafe — and a function reference with no
+ * catalogue verdict at all is refused too, which is why a caller that cannot
+ * reach a database must expect every statement that calls a function to be
+ * escalated here.
+ */
+export declare function isProvableRead(c: StatementClassification): boolean;
+/**
+ * Map a statement classification to the capability required to run it.
+ *
+ * `query_read` is granted ONLY for a provable read. Because every role holds
+ * `query_read`, this predicate is the entire role-layer defence for `SELECT`,
+ * so it must never widen: anything the classifier could not prove is a read is
+ * escalated to `ddl` here rather than trusted.
+ */
+export declare function capabilityForClassification(c: StatementClassification): RoleCapability | null;
+/** Map a message type to the capability required. */
+export declare function capabilityForMessageType(type: string): RoleCapability | null;
+/**
+ * Map an inbound `event` kind to the capability required to use it.
+ *
+ * `event` messages bypass the query pipeline, so the capability has to be
+ * named here rather than inferred from a SQL statement.
+ */
+export declare function capabilityForEventKind(kind: string): RoleCapability | null;
+/**
+ * Shape of the PostgreSQL login role this connector should be given.
+ *
+ * The agent's own controls are implemented in TypeScript and can have bugs, so
+ * the database role is where the boundary that cannot be bypassed from the wire
+ * is set. Two things the agent does about function calls are worth naming
+ * precisely, because they are frequently described as one control:
+ *
+ *   - `pg_proc` function-effect analysis (execution/function-effects.ts) is the
+ *     primary control: a statement is only a read when every function it calls
+ *     is `IMMUTABLE` and not `SECURITY DEFINER`. It does not depend on the
+ *     function's name, so it covers operator-written helpers.
+ *   - The `DENIED_READ_FUNCTIONS` list in sql-parser.ts is defence in depth. It
+ *     is incomplete by construction and is not a boundary.
+ *
+ * The revokes below are what a miss cannot get past: `read_only` on the
+ * connection constrains WRITES only, so a function that reads a server file,
+ * notifies a channel, or reaches another host is not covered by it, and only
+ * the absence of EXECUTE is.
+ *
+ * `sw-agent doctor` reports these attributes for the connected role; the
+ * statements below are what an operator should run once per deployment. Where a
+ * role name is shown as a placeholder, substitute the real one.
+ */
+export declare const RECOMMENDED_PG_ROLE: {
+    readonly role_name: "sw_agent";
+    /**
+     * Required `pg_roles` attributes. A role that satisfies all of these cannot
+     * escalate to superuser, cannot create databases or roles, cannot replicate,
+     * and cannot bypass row-level security.
+     */
+    readonly required_attributes: readonly ["rolsuper = false", "rolcreatedb = false", "rolcreaterole = false", "rolreplication = false", "rolbypassrls = false"];
+    /**
+     * Predefined roles that must NOT be granted. Several of them exist only in
+     * newer PostgreSQL releases; grant the ones the server actually has.
+     */
+    readonly forbidden_memberships: readonly ["pg_read_server_files", "pg_write_server_files", "pg_execute_server_program", "pg_read_all_settings", "pg_read_all_stats", "pg_stat_scan_tables", "pg_monitor", "pg_read_all_data", "pg_write_all_data"];
+    /** Bootstrap. Idempotent; safe to re-run. */
+    readonly bootstrap: readonly ["DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'sw_agent') THEN CREATE ROLE sw_agent LOGIN; END IF; END $$;", "ALTER ROLE sw_agent NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;"];
+    /**
+     * REVOKEs that matter. PostgreSQL grants a great deal to PUBLIC by default —
+     * notably `CREATE` on schema `public` (pre-14) and `EXECUTE` on every
+     * function — so the default state must be revoked explicitly rather than
+     * assumed absent.
+     *
+     * WHY THE DEFAULT-PRIVILEGES ROW IS NOT OPTIONAL: every `REVOKE … ON ALL
+     * FUNCTIONS` above is a ONE-SHOT SNAPSHOT of the functions that exist at the
+     * moment it runs. A function created afterwards is granted to PUBLIC again
+     * by the same default privileges that gave the current one away, so the
+     * revocation silently decays to nothing on a database that receives DDL. The
+     * `ALTER DEFAULT PRIVILEGES` row is what stops the decay; run it as the role
+     * that owns the objects (or as a superuser, which covers every future object),
+     * and re-run it after any role that creates functions is added.
+     */
+    readonly revokes: readonly ["REVOKE ALL ON DATABASE <database> FROM PUBLIC;", "REVOKE ALL ON SCHEMA public FROM PUBLIC;", "REVOKE ALL ON SCHEMA public FROM sw_agent;", "REVOKE CREATE ON SCHEMA public FROM PUBLIC;", "REVOKE EXECUTE ON ALL FUNCTIONS IN SCHEMA public FROM PUBLIC;", "REVOKE EXECUTE ON ALL FUNCTIONS IN SCHEMA public FROM sw_agent;", "REVOKE EXECUTE ON ALL PROCEDURES IN SCHEMA public FROM PUBLIC;", "REVOKE EXECUTE ON ALL PROCEDURES IN SCHEMA public FROM sw_agent;", "ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;", "ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE EXECUTE ON PROCEDURES FROM PUBLIC;", "REVOKE ALL ON ALL SEQUENCES IN SCHEMA public FROM sw_agent;", "REVOKE ALL ON ALL TABLES IN SCHEMA public FROM sw_agent;", "REVOKE ALL ON ALL SEQUENCES IN SCHEMA public FROM PUBLIC;"];
+    /** The only privileges the read-only posture needs. */
+    readonly grants: readonly ["GRANT CONNECT ON DATABASE <database> TO sw_agent;", "GRANT USAGE ON SCHEMA public TO sw_agent;", "GRANT SELECT ON ALL TABLES IN SCHEMA public TO sw_agent;", "REVOKE TEMP ON DATABASE <database> FROM sw_agent;"];
+    /**
+     * Session hardening, applied to every connection the role opens. The agent
+     * additionally sets `default_transaction_read_only` per connection for
+     * `read_only` entries; pinning it on the role means the guarantee also holds
+     * for an operator's own psql session and for any path the agent misses.
+     */
+    readonly role_settings: readonly ["ALTER ROLE sw_agent SET search_path = pg_catalog, public;", "ALTER ROLE sw_agent SET default_transaction_read_only = on;", "ALTER ROLE sw_agent SET statement_timeout = 30s;", "ALTER ROLE sw_agent SET idle_in_transaction_session_timeout = 60s;", "ALTER ROLE sw_agent SET log_statement = none;"];
+    /**
+     * What `doctor` should check on the connected role. Each row is a query and
+     * the value that means "acceptable"; anything else is reported to the
+     * operator as a finding.
+     */
+    readonly verification_queries: readonly [{
+        readonly sql: "SELECT rolsuper, rolcreatedb, rolcreaterole, rolreplication, rolbypassrls\n            FROM pg_roles WHERE rolname = current_user";
+        readonly expect: "six columns, every boolean false";
+    }, {
+        readonly sql: "SELECT has_database_privilege(current_user, current_database(), 'TEMP') AS can_create_temp";
+        readonly expect: "false";
+    }, {
+        readonly sql: "SELECT has_schema_privilege(current_user, 'public', 'CREATE') AS can_create_in_public";
+        readonly expect: "false";
+    }, {
+        readonly sql: "SELECT count(*) > 0 AS has_table_access\n            FROM pg_roles r\n            JOIN pg_auth_members m ON m.roleid = r.oid\n            WHERE r.rolname IN ('pg_read_server_files', 'pg_write_server_files',\n                                'pg_execute_server_program', 'pg_monitor',\n                                'pg_read_all_data', 'pg_write_all_data')";
+        readonly expect: "false";
+    }, {
+        readonly sql: "SHOW default_transaction_read_only";
+        readonly expect: "on";
+    }];
+};
+//# sourceMappingURL=role-policy.d.ts.map

package/dist/esm/permissions/role-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-policy.d.ts","sourceRoot":"","sources":["../../../src/permissions/role-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAwB,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC1F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAQtB,YAAY,GAMZ,iBAAiB,GACjB,YAAY,GACZ,aAAa,GACb,KAAK,GAGL,eAAe,GACf,aAAa,GACb,QAAQ,GACR,cAAc,GACd,aAAa,GACb,cAAc,CAAC;AAEnB;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,IAAI,EAAE,cAAc,EAAE,CA2B5D,CAAC;AAEF,mEAAmE;AACnE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,IAAI,GAAG,mBAAmB,CAEtE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAKpD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAKjE,CAAC;AAEF,iDAAiD;AACjD,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAEtE;AAED,+DAA+D;AAC/D,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,OAAO,CAKxE;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,OAAO,CAK3E;AAED,gEAAgE;AAChE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAK/F;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,EAAE,WAAW,CAAC,cAAc,CAUtE,CAAC;AAuBF;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAgBjF;AA+CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,uBAAuB,GAAG,MAAM,CAiD7E;AA2CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAOlE;AAqBD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,uBAAuB,GAAG,cAAc,GAAG,IAAI,CAkB7F;AAED,qDAAqD;AACrD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAgB5E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAS1E;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,mBAAmB;;IAG9B;;;;OAIG;;IASH;;;OAGG;;IAaH,6CAA6C;;IAM7C;;;;;;;;;;;;;;OAcG;;IAwBH,uDAAuD;;IASvD;;;;;OAKG;;IASH;;;;OAIG;;;;;;;;;;;;;;;;;CA6BK,CAAC"}