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

package/dist/cjs/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/cjs/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/cjs/permissions/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/permissions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/permissions/types.ts"],"names":[],"mappings":""}

package/dist/cjs/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/cjs/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/cjs/protocol/constants.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APPROVAL_NONCE_PATTERN = exports.ENVELOPE_NONCE_PATTERN = exports.ENVELOPE_MAC_KDF = exports.ENVELOPE_MAC_REQUIRED_DEFAULT = exports.APPROVAL_TIMEOUT_ENV_VAR = exports.LIMITS = exports.DEFAULTS = exports.PROTOCOL_VERSION = void 0;
+exports.PROTOCOL_VERSION = 1;
+exports.DEFAULTS = {
+    QUERY_TIMEOUT_MS: 30_000, // 30s default for one-shot queries
+    MIGRATION_TIMEOUT_MS: 1_800_000, // 30 min default for migrations
+    STREAM_CHUNK_ROWS: 100, // chunk if 100 rows collected
+    STREAM_CHUNK_BYTES: 65_536, // chunk if 64KB collected
+    STREAM_CHUNK_MS: 100, // chunk if 100ms elapsed
+    MAX_QUERY_ROWS: 10_000, // hard cap for non-streaming query
+    MAX_STREAM_ROWS: 1_000_000, // hard cap for streaming query
+    MAX_CELL_BYTES: 1_048_576, // 1MB per cell (larger = truncated)
+    // SINGLE SOURCE OF TRUTH for the manual-approval window. The value enforced by
+    // `ManualApprovalHandler` and the `expires_at` it advertises to the browser are
+    // both derived from this (see `resolveApprovalTimeoutMs` in
+    // permissions/manual-approval.ts); an operator override is clamped into
+    // [LIMITS.APPROVAL_TIMEOUT_MIN_MS, LIMITS.APPROVAL_TIMEOUT_MAX_MS].
+    APPROVAL_TIMEOUT_MS: 60_000, // manual approval: 60s timeout
+    IDLE_WSS_TIMEOUT_MS: 60_000, // close WSS after 60s idle
+    WAKE_KEEPALIVE_MS: 300_000, // SSE keepalive every 5 min
+    RECONNECT_BACKOFF_MS: [1_000, 2_000, 4_000, 8_000, 16_000, 32_000, 60_000],
+    ORPHAN_REQUEST_TIMEOUT_MS: 300_000, // 5 min: kill query if no reconnect
+    // Absolute clock skew tolerated on an inbound envelope's `ts`. Wide enough to
+    // absorb relay latency and browser clock drift, narrow enough that a captured
+    // frame is useless minutes later.
+    ENVELOPE_MAX_CLOCK_SKEW_MS: 120_000, // 2 min
+    // Age of an SSE wake event, measured from `queued_at`. A captured event replayed
+    // after this window is rejected regardless of what token it carries.
+    WAKE_MAX_EVENT_AGE_MS: 120_000, // 2 min
+    // Clock skew tolerated on a wake event's `queued_at` and
+    // `data_channel_token_expires_at`, both of which are stamped by the cloud.
+    WAKE_CLOCK_SKEW_MS: 30_000, // 30s
+    // Minimum remaining life a data-channel token must have for the wake event to
+    // be accepted at all; the data channel applies its own margin before dialling.
+    WAKE_MIN_TOKEN_LIFE_MS: 5_000, // 5s
+    // Session churn (audit M-15): a wake event that replaces the active browser
+    // session is refused while the current one is healthy, and any session change
+    // closer together than this is refused outright.
+    SESSION_CHANGE_COOLDOWN_MS: 2_000, // 2s
+    // …and at most this many session changes inside any one window.
+    SESSION_CHANGE_WINDOW_MS: 300_000, // 5 min
+    SESSION_CHANGE_MAX_PER_WINDOW: 100,
+};
+exports.LIMITS = {
+    MAX_STATEMENT_COUNT_PER_MIGRATION: 500,
+    // Protocol-level invariant for a single `query`/`stream_query` payload.
+    // PostgreSQL's simple query protocol executes every semicolon-separated
+    // statement in one round trip, so anything above 1 is a parser differential.
+    MAX_STATEMENT_COUNT_PER_QUERY: 1,
+    MAX_STATEMENT_LENGTH: 1_048_576, // 1MB per SQL statement
+    MAX_PAYLOAD_BYTES: 16_777_216, // 16MB per message (envelope + payload)
+    ID_MAX_LENGTH: 64,
+    PROJECT_MAX_LENGTH: 64,
+    ALIAS_MAX_LENGTH: 64,
+    ENVELOPE_NONCE_MIN_LENGTH: 16,
+    ENVELOPE_NONCE_MAX_LENGTH: 64,
+    // 32 bytes of HMAC-SHA256, hex encoded.
+    ENVELOPE_MAC_HEX_LENGTH: 64,
+    // Bounded replay cache. Oldest nonce is evicted first once the cache is full,
+    // so a flood cannot grow memory without bound (eviction can only re-admit an
+    // evicted nonce, and the freshness window bounds the value of doing so).
+    REPLAY_CACHE_MAX_ENTRIES: 8_192,
+    // Bounded wake_id replay cache (audit M-14). Oldest id is evicted first. This is
+    // a DoS control in its own right: an unbounded Set of cloud-supplied ids would
+    // be an unbounded memory sink on a stream the agent cannot authenticate the
+    // producer of. Eviction can only re-admit an id whose token has already
+    // expired, so the token check is the backstop, not this cache.
+    WAKE_REPLAY_CACHE_MAX_ENTRIES: 1_024,
+    // Bounds on the clamped manual-approval timeout override.
+    APPROVAL_TIMEOUT_MIN_MS: 5_000, // 5s
+    APPROVAL_TIMEOUT_MAX_MS: 900_000, // 15 min
+    // crypto.randomBytes(32).toString('hex')
+    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.
+ */
+exports.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.
+ */
+exports.ENVELOPE_MAC_REQUIRED_DEFAULT = true;
+/** HKDF suite used to turn a data-channel token into an envelope MAC key. */
+exports.ENVELOPE_MAC_KDF = {
+    digest: 'sha256',
+    saltLabel: 'sw-agent/v1/envelope-mac/salt',
+    infoLabel: 'sw-agent/v1/envelope-mac/info',
+    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.
+ */
+exports.ENVELOPE_NONCE_PATTERN = /^[A-Za-z0-9_-]{16,64}$/;
+/** Approval nonces are 32 random bytes, lowercase hex. */
+exports.APPROVAL_NONCE_PATTERN = /^[0-9a-f]{64}$/;
+//# sourceMappingURL=constants.js.map

package/dist/cjs/protocol/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/protocol/constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,gBAAgB,GAAG,CAAU,CAAC;AAE9B,QAAA,QAAQ,GAAG;IACtB,gBAAgB,EAAE,MAAM,EAAY,mCAAmC;IACvE,oBAAoB,EAAE,SAAS,EAAK,gCAAgC;IACpE,iBAAiB,EAAE,GAAG,EAAc,8BAA8B;IAClE,kBAAkB,EAAE,MAAM,EAAU,0BAA0B;IAC9D,eAAe,EAAE,GAAG,EAAgB,yBAAyB;IAC7D,cAAc,EAAE,MAAM,EAAc,mCAAmC;IACvE,eAAe,EAAE,SAAS,EAAU,+BAA+B;IACnE,cAAc,EAAE,SAAS,EAAW,oCAAoC;IACxE,+EAA+E;IAC/E,gFAAgF;IAChF,4DAA4D;IAC5D,wEAAwE;IACxE,oEAAoE;IACpE,mBAAmB,EAAE,MAAM,EAAS,+BAA+B;IACnE,mBAAmB,EAAE,MAAM,EAAS,2BAA2B;IAC/D,iBAAiB,EAAE,OAAO,EAAU,4BAA4B;IAChE,oBAAoB,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;IAC1E,yBAAyB,EAAE,OAAO,EAAE,oCAAoC;IACxE,8EAA8E;IAC9E,8EAA8E;IAC9E,kCAAkC;IAClC,0BAA0B,EAAE,OAAO,EAAE,QAAQ;IAC7C,iFAAiF;IACjF,qEAAqE;IACrE,qBAAqB,EAAE,OAAO,EAAM,QAAQ;IAC5C,yDAAyD;IACzD,2EAA2E;IAC3E,kBAAkB,EAAE,MAAM,EAAU,MAAM;IAC1C,8EAA8E;IAC9E,+EAA+E;IAC/E,sBAAsB,EAAE,KAAK,EAAO,KAAK;IACzC,4EAA4E;IAC5E,8EAA8E;IAC9E,iDAAiD;IACjD,0BAA0B,EAAE,KAAK,EAAG,KAAK;IACzC,gEAAgE;IAChE,wBAAwB,EAAE,OAAO,EAAG,QAAQ;IAC5C,6BAA6B,EAAE,GAAG;CAC1B,CAAC;AAEE,QAAA,MAAM,GAAG;IACpB,iCAAiC,EAAE,GAAG;IACtC,wEAAwE;IACxE,wEAAwE;IACxE,6EAA6E;IAC7E,6BAA6B,EAAE,CAAC;IAChC,oBAAoB,EAAE,SAAS,EAAK,wBAAwB;IAC5D,iBAAiB,EAAE,UAAU,EAAO,wCAAwC;IAC5E,aAAa,EAAE,EAAE;IACjB,kBAAkB,EAAE,EAAE;IACtB,gBAAgB,EAAE,EAAE;IACpB,yBAAyB,EAAE,EAAE;IAC7B,yBAAyB,EAAE,EAAE;IAC7B,wCAAwC;IACxC,uBAAuB,EAAE,EAAE;IAC3B,8EAA8E;IAC9E,6EAA6E;IAC7E,yEAAyE;IACzE,wBAAwB,EAAE,KAAK;IAC/B,iFAAiF;IACjF,+EAA+E;IAC/E,4EAA4E;IAC5E,wEAAwE;IACxE,+DAA+D;IAC/D,6BAA6B,EAAE,KAAK;IACpC,0DAA0D;IAC1D,uBAAuB,EAAE,KAAK,EAAM,KAAK;IACzC,uBAAuB,EAAE,OAAO,EAAI,SAAS;IAC7C,yCAAyC;IACzC,yBAAyB,EAAE,EAAE;CACrB,CAAC;AAEX;;;;;;GAMG;AACU,QAAA,wBAAwB,GAAG,qCAAqC,CAAC;AAE9E;;;;;;;GAOG;AACU,QAAA,6BAA6B,GAAG,IAAI,CAAC;AAElD,6EAA6E;AAChE,QAAA,gBAAgB,GAAG;IAC9B,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,+BAA+B;IAC1C,SAAS,EAAE,+BAA+B;IAC1C,QAAQ,EAAE,EAAE;CACJ,CAAC;AAEX;;;GAGG;AACU,QAAA,sBAAsB,GAAG,wBAAwB,CAAC;AAE/D,0DAA0D;AAC7C,QAAA,sBAAsB,GAAG,gBAAgB,CAAC"}

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