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

package/dist/types/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/types/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"}

package/dist/types/permissions/types.d.ts

@@ -0,0 +1,126 @@
+import { Role } from '../protocol/envelope';
+import { StatementClassification } from '../execution/types';
+export type PermissionLevel = 'read_only' | 'auto_upgrade' | 'manual' | 'full';
+/** What the user is trying to do. */
+export interface ActionRequest {
+    /** The user's role in the workspace. */
+    role: Role;
+    /** Effective permission level (already resolved from override + default). */
+    permission_level: PermissionLevel;
+    /** Original SQL. */
+    sql: string;
+    /** Browser-claimed intent (advisory only — we re-parse to verify). */
+    intent: 'read' | 'write' | 'ddl' | 'migration';
+    /** If intent=migration, the plan_id claimed by browser. */
+    plan_id?: string;
+    /** The message type (query, stream_query, migration_run, etc.). */
+    message_type: string;
+    /** The request_id (for tracking approval). */
+    request_id: string;
+    /** Which DB alias this targets. */
+    db_alias: string;
+    /** The project name. */
+    project: string;
+    /**
+     * The RESOLVED database identity, when the caller has resolved it.
+     *
+     * `project` and `db_alias` above are what the frame *claimed*; these are what
+     * the agent actually looked up. The audit trail records the resolved pair, and
+     * a plan is bound to the resolved pair, so a frame that names one database
+     * while executing against another cannot satisfy a plan registered against
+     * either. Omitted only by callers with no resolution step (the local CLI,
+     * tests), where the claimed values are the only ones there are.
+     */
+    resolved_project?: string;
+    resolved_db_alias?: string;
+    /** The user context. */
+    user: {
+        id: string;
+        role: Role;
+    };
+    /**
+     * Approval nonce for this request. Agent-minted only: `ManualApprovalHandler`
+     * mints it locally when the approval is parked, so a value arriving from the
+     * wire must never populate this field. It is recorded here so a decision can
+     * be correlated with the approval event that carried it.
+     */
+    approval_nonce?: string;
+}
+/** Outcome of a permission check. */
+export interface PermissionDecision {
+    /** Whether the action can proceed. */
+    allowed: boolean;
+    /** Why allowed or denied. */
+    reason: string;
+    /** Stable code for audit + browser UI. */
+    code: 'allowed' | 'role_insufficient' | 'permission_denied' | 'plan_not_registered' | 'intent_mismatch' | 'auto_upgrade_granted'
+    /** PostgreSQL could not parse the statement; denied rather than guessed. */
+     | 'unparseable_statement'
+    /** The parser found more than one statement; refused outright. */
+     | 'multiple_statements'
+    /** The parser could not be loaded; denied rather than falling back. */
+     | 'parser_unavailable'
+    /**
+     * `intent: 'migration'` was claimed on a message that is not a
+     * `migration_run`. The value is meaningful only on that path, so the claim
+     * is refused instead of being treated as an exemption from anti-spoofing.
+     */
+     | 'intent_not_applicable';
+    /**
+     * The classification the decision was based on. Returned so the execution
+     * layer uses the exact same verdict rather than re-parsing and possibly
+     * disagreeing.
+     */
+    classification?: StatementClassification;
+    /** Populated when approval was requested and refused/expired. */
+    approval_request?: {
+        request_id: string;
+        /**
+         * Redacted and length-capped. The full statement text must never leave the
+         * agent: it can carry PII literals that the cloud and the browser's audit
+         * view would otherwise store.
+         */
+        sql_preview: string;
+        intent: 'write' | 'ddl';
+        db_alias: string;
+    };
+}
+/**
+ * Refusal of a `plan_register` event, produced by `PlanRegistry` — the single
+ * source of truth for who may register a migration plan and at what level.
+ */
+export type PlanRegistrationRefusal = 'read_only_permission_level' | 'role_lacks_migration_run' | 'unattested_principal'
+/** the registration did not name the resolved project and db_alias. */
+ | 'unscoped_plan_registration';
+/** Why a registered plan may or may not be executed by a given principal. */
+export type PlanProvenanceRefusal = 'plan_not_registered' | 'plan_expired' | 'statements_changed' | 'runner_not_privileged' | 'registered_at_more_permissive_level' | 'principal_not_attested'
+/** the plan is bound to a different project/db_alias than this run. */
+ | 'plan_scope_mismatch';
+/**
+ * Refusal of a single consumption of a plan, produced by
+ * `PlanRegistry.consume()`.
+ *
+ * `plan_already_consumed` is kept separate from `plan_not_registered` on
+ * purpose: "you may not run this, it is not yours / not bound to these
+ * statements" and "you already ran this" are different operator problems, and
+ * collapsing them hides a replay attempt behind a typo. Neither code reveals
+ * anything about any *other* plan id.
+ */
+export type PlanConsumeRefusal = PlanProvenanceRefusal | 'plan_already_consumed';
+/** Result of auto-upgrade evaluation. */
+export interface AutoUpgradeResult {
+    /** Whether the auto-upgrade was granted. */
+    granted: boolean;
+    /** Why granted or denied. */
+    reason: string;
+}
+/** Result of manual approval flow. */
+export interface ManualApprovalResult {
+    /** Whether approval was given. */
+    approved: boolean;
+    /** Who approved/denied (user_id). */
+    approved_by?: string;
+    /** Why not approved (timeout, denied, etc.). */
+    reason?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/permissions/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/permissions/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,cAAc,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE/E,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,IAAI,EAAE,IAAI,CAAC;IACX,6EAA6E;IAC7E,gBAAgB,EAAE,eAAe,CAAC;IAClC,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,WAAW,CAAC;IAC/C,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB;IACxB,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC;IACjC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qCAAqC;AACrC,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,IAAI,EACA,SAAS,GACT,mBAAmB,GACnB,mBAAmB,GACnB,qBAAqB,GACrB,iBAAiB,GACjB,sBAAsB;IACxB,4EAA4E;OAC1E,uBAAuB;IACzB,kEAAkE;OAChE,qBAAqB;IACvB,uEAAuE;OACrE,oBAAoB;IACtB;;;;OAIG;OACD,uBAAuB,CAAC;IAC5B;;;;OAIG;IACH,cAAc,CAAC,EAAE,uBAAuB,CAAC;IACzC,iEAAiE;IACjE,gBAAgB,CAAC,EAAE;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB;;;;WAIG;QACH,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,OAAO,GAAG,KAAK,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAC/B,4BAA4B,GAC5B,0BAA0B,GAC1B,sBAAsB;AACxB,uEAAuE;GACrE,4BAA4B,CAAC;AAEjC,6EAA6E;AAC7E,MAAM,MAAM,qBAAqB,GAC7B,qBAAqB,GACrB,cAAc,GACd,oBAAoB,GACpB,uBAAuB,GACvB,qCAAqC,GACrC,wBAAwB;AAC1B,uEAAuE;GACrE,qBAAqB,CAAC;AAE1B;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG,qBAAqB,GAAG,uBAAuB,CAAC;AAEjF,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sCAAsC;AACtC,MAAM,WAAW,oBAAoB;IACnC,kCAAkC;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/types/protocol/constants.d.ts

@@ -0,0 +1,72 @@
+export declare const PROTOCOL_VERSION: 1;
+export declare const DEFAULTS: {
+    readonly QUERY_TIMEOUT_MS: 30000;
+    readonly MIGRATION_TIMEOUT_MS: 1800000;
+    readonly STREAM_CHUNK_ROWS: 100;
+    readonly STREAM_CHUNK_BYTES: 65536;
+    readonly STREAM_CHUNK_MS: 100;
+    readonly MAX_QUERY_ROWS: 10000;
+    readonly MAX_STREAM_ROWS: 1000000;
+    readonly MAX_CELL_BYTES: 1048576;
+    readonly APPROVAL_TIMEOUT_MS: 60000;
+    readonly IDLE_WSS_TIMEOUT_MS: 60000;
+    readonly WAKE_KEEPALIVE_MS: 300000;
+    readonly RECONNECT_BACKOFF_MS: readonly [1000, 2000, 4000, 8000, 16000, 32000, 60000];
+    readonly ORPHAN_REQUEST_TIMEOUT_MS: 300000;
+    readonly ENVELOPE_MAX_CLOCK_SKEW_MS: 120000;
+    readonly WAKE_MAX_EVENT_AGE_MS: 120000;
+    readonly WAKE_CLOCK_SKEW_MS: 30000;
+    readonly WAKE_MIN_TOKEN_LIFE_MS: 5000;
+    readonly SESSION_CHANGE_COOLDOWN_MS: 2000;
+    readonly SESSION_CHANGE_WINDOW_MS: 300000;
+    readonly SESSION_CHANGE_MAX_PER_WINDOW: 100;
+};
+export declare const LIMITS: {
+    readonly MAX_STATEMENT_COUNT_PER_MIGRATION: 500;
+    readonly MAX_STATEMENT_COUNT_PER_QUERY: 1;
+    readonly MAX_STATEMENT_LENGTH: 1048576;
+    readonly MAX_PAYLOAD_BYTES: 16777216;
+    readonly ID_MAX_LENGTH: 64;
+    readonly PROJECT_MAX_LENGTH: 64;
+    readonly ALIAS_MAX_LENGTH: 64;
+    readonly ENVELOPE_NONCE_MIN_LENGTH: 16;
+    readonly ENVELOPE_NONCE_MAX_LENGTH: 64;
+    readonly ENVELOPE_MAC_HEX_LENGTH: 64;
+    readonly REPLAY_CACHE_MAX_ENTRIES: 8192;
+    readonly WAKE_REPLAY_CACHE_MAX_ENTRIES: 1024;
+    readonly APPROVAL_TIMEOUT_MIN_MS: 5000;
+    readonly APPROVAL_TIMEOUT_MAX_MS: 900000;
+    readonly APPROVAL_NONCE_HEX_LENGTH: 64;
+};
+/**
+ * The only environment variable that may change the manual-approval window.
+ *
+ * Declared here so the daemon's env allow-list (src/cli/daemon/state.ts) and the
+ * resolver that enforces it cannot drift; the resolver clamps whatever it reads
+ * into LIMITS.APPROVAL_TIMEOUT_MIN_MS..LIMITS.APPROVAL_TIMEOUT_MAX_MS.
+ */
+export declare const APPROVAL_TIMEOUT_ENV_VAR = "SW_AGENT_MANUAL_APPROVAL_TIMEOUT_MS";
+/**
+ * Whether a per-session MAC is mandatory on inbound envelopes.
+ *
+ * Fail closed: an envelope with no MAC is rejected. A relay that has not yet
+ * implemented envelope signing therefore cannot drive the agent at all, which
+ * is the intended behaviour — the alternative (defaulting to "accept unsigned")
+ * preserves the C-04 vulnerability for every existing deployment.
+ */
+export declare const ENVELOPE_MAC_REQUIRED_DEFAULT = true;
+/** HKDF suite used to turn a data-channel token into an envelope MAC key. */
+export declare const ENVELOPE_MAC_KDF: {
+    readonly digest: "sha256";
+    readonly saltLabel: "sw-agent/v1/envelope-mac/salt";
+    readonly infoLabel: "sw-agent/v1/envelope-mac/info";
+    readonly keyBytes: 32;
+};
+/**
+ * Anti-replay nonces are opaque to the connector; it only requires them to be
+ * unique per session and unguessable enough not to collide across sessions.
+ */
+export declare const ENVELOPE_NONCE_PATTERN: RegExp;
+/** Approval nonces are 32 random bytes, lowercase hex. */
+export declare const APPROVAL_NONCE_PATTERN: RegExp;
+//# sourceMappingURL=constants.d.ts.map

package/dist/types/protocol/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/protocol/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,EAAG,CAAU,CAAC;AAE3C,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;CAuCX,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;CA8BT,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,wCAAwC,CAAC;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB;;;;;CAKnB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,sBAAsB,QAA2B,CAAC;AAE/D,0DAA0D;AAC1D,eAAO,MAAM,sBAAsB,QAAmB,CAAC"}

package/dist/types/protocol/envelope.d.ts

@@ -0,0 +1,165 @@
+import { PROTOCOL_VERSION } from './constants';
+export declare const PROTOCOL_VERSION_V1: 1;
+export type ProtocolVersion = typeof PROTOCOL_VERSION;
+/**
+ * Canonical list of RBAC roles. The `Role` type is derived from this tuple so
+ * the runtime allow-list and the compile-time union cannot drift apart.
+ */
+export declare const ROLES: readonly ["admin", "developer", "data_reader", "viewer"];
+export type Role = (typeof ROLES)[number];
+export declare function isRole(value: unknown): value is Role;
+/**
+ * Canonical list of message types. `MessageType` is derived from this tuple;
+ * `validateEnvelope` gates on the same array.
+ */
+export declare const MESSAGE_TYPES: readonly ["ping", "introspect", "query", "stream_query", "migration_run", "cancel", "response", "error", "stream_chunk", "stream_end", "event"];
+export type MessageType = (typeof MESSAGE_TYPES)[number];
+/**
+ * Canonical list of event kinds. `EventKind` is derived from this tuple, so an
+ * event kind that is not in this array cannot be validated and an array entry
+ * that is not a legal kind is a compile error.
+ */
+export declare const EVENT_KINDS: readonly ["status_change", "migration_progress", "approval_required", "approval_response", "warning", "resume_request", "plan_register"];
+export type EventKind = (typeof EVENT_KINDS)[number];
+export type MigrationStatementStatus = 'pending' | 'running' | 'success' | 'failed' | 'rolled_back';
+/**
+ * The security-relevant envelope fields covered by the per-session MAC, in
+ * canonical (sorted) order: db_alias, id, nonce, payload, project, ts, type, user, v.
+ *
+ * `canonicalEnvelopeJson` in fact covers *every* top-level field except `mac`,
+ * so a relay cannot smuggle an unsigned field past verification; this constant
+ * documents the minimum contract a compatible implementation must satisfy.
+ */
+export declare const MAC_SIGNED_ENVELOPE_FIELDS: readonly ["v", "id", "type", "project", "user", "db_alias", "ts", "nonce", "payload"];
+/**
+ * Single envelope format for every message between browser <-> cloud <-> agent.
+ * Every WebSocket frame contains exactly one AgentMessage serialized as UTF-8 JSON.
+ */
+export interface AgentMessage<T = unknown> {
+    /** Protocol version. Must equal 1. */
+    v: ProtocolVersion;
+    /** UUID v4. Generated by sender. Used for request/response correlation + cancellation. */
+    id: string;
+    /** Message type. Determines payload shape. */
+    type: MessageType;
+    /** Project name. Must match a project_name in databases.config.json. */
+    project: string;
+    /**
+     * Acting user, as asserted by the relay.
+     *
+     * This is a CLAIM, not a verified fact: nothing in a self-declared `role` is
+     * trustworthy on its own. It is only acted upon after
+     * `InboundEnvelopeGuard` (protocol/validate.ts) has verified the per-session
+     * MAC over this whole envelope, checked `ts` freshness, rejected a replayed
+     * `nonce`, and confirmed `role` is one of the roles the cloud negotiated when
+     * this data-channel session was created.
+     */
+    user: {
+        id: string;
+        role: Role;
+        /** Actual human initiator when the request is relayed for a team-shared
+         *  agent (equals id when the owner sends it). Optional; informational. */
+        actor_id?: string;
+    };
+    /** DB alias. Must match a db_alias in databases.config.json. */
+    db_alias: string;
+    /** Epoch milliseconds. Sender's clock. Used for audit + ordering. */
+    ts: number;
+    /**
+     * Anti-replay nonce, unique per message within a data-channel session.
+     * Required on every inbound envelope (see InboundEnvelopeGuard). Optional on
+     * outbound envelopes, which the agent does not sign: it holds no key the relay
+     * could verify with.
+     */
+    nonce?: string;
+    /**
+     * `HMAC-SHA256(session_mac_key, canonicalEnvelopeJson(envelope))` in lowercase
+     * hex, where the key is HKDF-derived from the data-channel token. The connector
+     * rejects any inbound envelope whose MAC is absent (when required) or does not
+     * verify. Absent on envelopes the agent emits.
+     */
+    mac?: string;
+    /** Type-specific payload. See messages.ts. */
+    payload: T;
+}
+/**
+ * Deterministic JSON serialization: object keys sorted by UTF-16 code unit at
+ * every depth, `undefined` object members dropped, arrays preserved in order.
+ *
+ * `JSON.stringify` cannot be used directly because its key order is insertion
+ * order, which the relay and the agent need not agree on. Any value that cannot
+ * be represented unambiguously (functions, symbols, bigint, NaN, Infinity,
+ * cycles, non-plain objects) throws rather than being silently coerced.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Canonical serialization of an envelope, i.e. the exact byte string the MAC is
+ * computed over. Covers every top-level field except `mac` itself, sorted
+ * deterministically at every depth.
+ */
+export declare function canonicalEnvelopeJson(msg: AgentMessage<unknown> | Record<string, unknown>): string;
+/**
+ * Derive the per-session envelope MAC key from the data-channel token.
+ *
+ * The data-channel token is already a secret shared by exactly one relay
+ * session; HKDF turns it into a key whose only purpose is envelope
+ * authentication, bound to the agent id and browser session so a key cannot be
+ * reused across sessions even if a relay ever re-issued the same token.
+ */
+export declare function deriveSessionMacKey(opts: {
+    dataChannelToken: string;
+    agentId: string;
+    browserSessionId: string;
+}): Buffer;
+/** Lowercase hex HMAC-SHA256 of the canonical envelope. */
+export declare function computeEnvelopeMac(macKey: Buffer, msg: AgentMessage<unknown> | Record<string, unknown>): string;
+/**
+ * Return a copy of `msg` carrying its MAC. `nonce` is taken from the message
+ * when present; callers building a fresh outbound envelope should set one first
+ * (see `newEnvelopeNonce`).
+ */
+export declare function signEnvelope<T>(macKey: Buffer, msg: AgentMessage<T>): AgentMessage<T>;
+/**
+ * Constant-time MAC check. Returns false for a missing, malformed, or
+ * non-matching MAC; never throws.
+ */
+export declare function verifyEnvelopeMac(macKey: Buffer, msg: AgentMessage<unknown> | Record<string, unknown>): boolean;
+/** Fresh anti-replay nonce (base64url, 24 random bytes). */
+export declare function newEnvelopeNonce(): string;
+/** True when `nonce` is a syntactically valid envelope nonce. */
+export declare function isValidEnvelopeNonce(nonce: unknown): nonce is string;
+/**
+ * Highest role a relay may assert for a data-channel session when the operator
+ * has configured no ceiling.
+ *
+ * the key `security.max_negotiable_role` exists in machine config and
+ * this constant was the only place it could have been honoured, yet the default
+ * was `'admin'` — the maximum. That made the ceiling inert: a compromised relay
+ * could assert `admin` and nothing local could stop it. `'developer'` is the
+ * default instead, so a deployment that never thought about the key still gets a
+ * bound, and an install that genuinely needs `admin` must say so explicitly in
+ * machine config (which is logged loudly at startup, and reported by
+ * `sw-agent status`).
+ *
+ * `developer` rather than `data_reader`/`viewer` because `developer` is the
+ * least-privileged role that can actually do the product's work (run
+ * migrations); a stricter default would break every existing install outright
+ * rather than narrowing it.
+ */
+export declare const ENVELOPE_MAX_NEGOTIABLE_ROLE_DEFAULT: Role;
+/**
+ * Helper: create a message with sensible defaults.
+ * Useful for tests and for agent's own message construction.
+ */
+export declare function createMessage<T>(type: MessageType, opts: {
+    id?: string;
+    project: string;
+    user: {
+        id: string;
+        role: Role;
+    };
+    db_alias: string;
+    payload: T;
+    nonce?: string;
+}): AgentMessage<T>;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/types/protocol/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../../src/protocol/envelope.ts"],"names":[],"mappings":"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"}

package/dist/types/protocol/errors.d.ts

@@ -0,0 +1,33 @@
+import { ErrorPayload } from './messages';
+export type ErrorCode = 'invalid_message' | 'unknown_message_type' | 'payload_invalid' | 'protocol_version_mismatch' | 'auth_failed' | 'token_expired' | 'permission_denied' | 'multiple_statements' | 'unparseable_statement' | 'parser_unavailable' | 'role_insufficient' | 'role_above_ceiling' | 'db_alias_project_mismatch' | 'database_scope_not_configured' | 'plan_scope_mismatch' | 'duplicate_request_id' | 'approval_timeout' | 'approval_denied' | 'MANUAL_APPROVAL_TIMEOUT' | 'MANUAL_APPROVAL_REJECTED' | 'db_unavailable' | 'db_auth_failed' | 'db_not_found' | 'db_pool_exhausted' | 'db_ssl_error' | 'migration_in_progress' | 'migration_plan_not_registered' | 'migration_statement_failed' | 'migration_rolled_back' | 'migration_partial' | 'query_timeout' | 'query_cancelled' | 'query_too_large' | 'stream_too_large' | 'STREAM_ROW_LIMIT' | 'CELL_SIZE_LIMIT' | 'cancel_failed' | 'cancel_target_not_found' | 'cancel_not_permitted' | 'concurrent_request_rejected' | 'orphaned_request' | 'channel_closed' | 'rate_limited' | 'config_invalid' | 'config_not_found' | 'env_var_missing' | 'execution_failed' | 'internal_error' | 'not_implemented';
+export interface ErrorMetadata {
+    code: ErrorCode;
+    /** Default human-readable message. May be overridden at throw site. */
+    default_message: string;
+    /** Whether browser should tear down the connection. */
+    fatal: boolean;
+    /** Whether browser may auto-retry the request. */
+    retryable: boolean;
+    /** Suggested recovery action shown in browser UI. */
+    recovery_hint: string;
+}
+export declare const ERROR_CATALOG: Record<ErrorCode, ErrorMetadata>;
+export declare function getErrorMetadata(code: ErrorCode): ErrorMetadata;
+export declare function isFatalError(code: ErrorCode): boolean;
+export declare function isRetryableError(code: ErrorCode): boolean;
+/**
+ * Construct an ErrorPayload for a given code.
+ * Optional overrides for message and request_id.
+ *
+ * `overrides.message` is caller-supplied and reaches the browser verbatim, so it
+ * must be either an agent-authored string or the output of a sanitiser
+ * (`src/audit/sanitize.ts`). Never pass a raw driver or parser message:
+ * PostgreSQL `DETAIL` lines carry row data and node-postgres embeds the
+ * connection topology. `pg_error` is limited to the two allow-listed fields the
+ * protocol defines.
+ */
+export declare function makeError(code: ErrorCode, request_id: string, overrides?: {
+    message?: string;
+    pg_error?: ErrorPayload['pg_error'];
+}): ErrorPayload;
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/protocol/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/protocol/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,MAAM,SAAS,GAEjB,iBAAiB,GACjB,sBAAsB,GACtB,iBAAiB,GACjB,2BAA2B,GAG3B,aAAa,GACb,eAAe,GACf,mBAAmB,GACnB,qBAAqB,GACrB,uBAAuB,GACvB,oBAAoB,GACpB,mBAAmB,GAGnB,oBAAoB,GAGpB,2BAA2B,GAG3B,+BAA+B,GAG/B,qBAAqB,GAGrB,sBAAsB,GACtB,kBAAkB,GAClB,iBAAiB,GACjB,yBAAyB,GACzB,0BAA0B,GAG1B,gBAAgB,GAChB,gBAAgB,GAChB,cAAc,GACd,mBAAmB,GACnB,cAAc,GAGd,uBAAuB,GACvB,+BAA+B,GAC/B,4BAA4B,GAC5B,uBAAuB,GACvB,mBAAmB,GAGnB,eAAe,GACf,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,kBAAkB,GAClB,iBAAiB,GAGjB,eAAe,GACf,yBAAyB,GAGzB,sBAAsB,GAGtB,6BAA6B,GAG7B,kBAAkB,GAClB,gBAAgB,GAChB,cAAc,GAGd,gBAAgB,GAChB,kBAAkB,GAClB,iBAAiB,GAGjB,kBAAkB,GAClB,gBAAgB,GAChB,iBAAiB,CAAC;AAEtB,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,eAAe,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,KAAK,EAAE,OAAO,CAAC;IACf,kDAAkD;IAClD,SAAS,EAAE,OAAO,CAAC;IACnB,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,SAAS,EAAE,aAAa,CAyW1D,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,aAAa,CAE/D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAErD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,SAAS,EACf,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE;IACV,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;CACrC,GACA,YAAY,CAUd"}