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

package/dist/types/config/db-config.d.ts.map

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

package/dist/types/config/machine-config.d.ts

@@ -0,0 +1,85 @@
+import { type Role } from '../protocol/envelope';
+import { PermissionLevel } from '../permissions/checker';
+export { PermissionLevel };
+/**
+ * Machine-level config: sw-agent.config.json
+ * Contains: cloud URL, agent token, agent ID, default permission, machine label.
+ * Does NOT contain: database connection info (that's in db-config.ts).
+ */
+export interface MachineConfig {
+    config_version: 1;
+    cloud_url: string;
+    agent_token: string;
+    agent_id: string;
+    default_permission: PermissionLevel;
+    machine_label: string;
+    log_level: 'debug' | 'info' | 'warn' | 'error';
+    /** Cloud telemetry: ship audit + operation logs to the backend (best-effort). */
+    cloud_telemetry?: {
+        enabled: boolean;
+        ingest_url?: string;
+    };
+    /**
+     * Transport-security overrides. Every key is optional and absent means "the
+     * secure default", so a config written by an older build keeps working and a
+     * partially written block cannot silently relax a control.
+     */
+    security?: {
+        /** Require a per-session MAC on inbound data-channel envelopes. Default: true. */
+        envelope_mac_required?: boolean;
+        /**
+         * Hard local ceiling on the role a relay may assert for a data-channel
+         * session, applied by `InboundEnvelopeGuard` after the negotiated-set
+         * check.
+         *
+         * Default: `'developer'` — `ENVELOPE_MAX_NEGOTIABLE_ROLE_DEFAULT`, not
+         * `'admin'`. An earlier revision of this file documented `'admin'`, which is
+         * not what the code does: the default was the strongest role, so the
+         * ceiling bound nothing. Setting `'admin'` here is honoured and warned
+         * about at daemon startup, and `sw-agent status` reports the effective
+         * ceiling.
+         */
+        max_negotiable_role?: Role;
+    };
+    created_at: string;
+    updated_at: string;
+}
+export declare const DEFAULT_MACHINE_CONFIG: Partial<MachineConfig>;
+/** Least-privileged permission level; the default for every new install. */
+export declare const SAFEST_PERMISSION: PermissionLevel;
+/**
+ * Creates a new default MachineConfig with the given options and current ISO timestamps.
+ * Defaults to the least-privileged permission level; a more permissive level
+ * must be requested explicitly by the caller.
+ */
+export declare function createDefaultMachineConfig(opts: {
+    machineLabel: string;
+    cloudUrl?: string;
+    permission?: PermissionLevel;
+    token?: string;
+}): MachineConfig;
+/**
+ * Validates the raw JSON input to ensure it meets MachineConfig constraints.
+ */
+export declare function validateMachineConfig(raw: unknown): MachineConfig;
+/**
+ * Checks if the sw-agent.config.json file exists.
+ */
+export declare function machineConfigExists(): boolean;
+/**
+ * Loads and validates the machine config file.
+ */
+export declare function loadMachineConfig(): MachineConfig;
+/**
+ * Saves the machine config to disk with 0o600 permissions on POSIX, written
+ * atomically and with the mode repaired if a pre-existing file is readable by
+ * group or other.
+ */
+export declare function saveMachineConfig(config: MachineConfig): void;
+/**
+ * Runs a load → mutate → save cycle over sw-agent.config.json under an advisory
+ * lock, so a concurrent `config set` cannot be lost to a read-modify-write
+ * race. `mutate` edits the config in place; its return value is passed back.
+ */
+export declare function mutateMachineConfig<T>(mutate: (config: MachineConfig) => T): T;
+//# sourceMappingURL=machine-config.d.ts.map

package/dist/types/config/machine-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-config.d.ts","sourceRoot":"","sources":["../../../src/config/machine-config.ts"],"names":[],"mappings":"AAUA,OAAO,EAAU,KAAK,IAAI,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,CAAC;AAa3B;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,CAAC,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,eAAe,CAAC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC/C,iFAAiF;IACjF,eAAe,CAAC,EAAE;QAChB,OAAO,EAAE,OAAO,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF;;;;OAIG;IACH,QAAQ,CAAC,EAAE;QACT,kFAAkF;QAClF,qBAAqB,CAAC,EAAE,OAAO,CAAC;QAChC;;;;;;;;;;;WAWG;QACH,mBAAmB,CAAC,EAAE,IAAI,CAAC;KAC5B,CAAC;IACF,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,sBAAsB,EAAE,OAAO,CAAC,aAAa,CAKzD,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,EAAE,eAA6B,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,aAAa,CAkBhB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CA6GjE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAM7C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,aAAa,CAyBjD;AAMD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAY7D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,CAAC,GAAG,CAAC,CAO9E"}

package/dist/types/config/paths.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The environment variables that relocate the agent home, in precedence order.
+ * `AGENT_HOME` is deliberately absent: nothing reads it, and the startup banner
+ * used to print it as if it did, which invited an operator to "move the token
+ * store" by setting a variable that is silently ignored.
+ */
+export declare const AGENT_HOME_ENV_VARS: readonly ["PG_CONNECTOR_HOME", "SW_AGENT_HOME"];
+/**
+ * Returns the agent home directory.
+ * If PG_CONNECTOR_HOME or SW_AGENT_HOME is set, uses that. Otherwise uses
+ * ~/.sw-agent.
+ * Created with 0o700 on POSIX; a pre-existing directory is chmod'ed back to
+ * 0o700 rather than trusted, since a 0o755 home exposes the token and the
+ * database config inside it. mkdir is attempted and only EEXIST is ignored:
+ * an existsSync check followed by mkdirSync is a race, and it skips the repair
+ * for a directory that already exists.
+ */
+export declare function getAgentHome(): string;
+export declare function getSwAgentDir(): string;
+/**
+ * Returns the path to the machine config file sw-agent.config.json.
+ */
+export declare function getMachineConfigPath(): string;
+/**
+ * Returns the path to the database config file databases.config.json.
+ */
+export declare function getDbConfigPath(): string;
+/**
+ * Returns the path to the machine-local credential key file that encrypts
+ * database passwords at rest.
+ *
+ * Deliberately placed outside the agent home directory: a copy of the agent
+ * home (backup, sync folder, snapshot, EDR upload) must never carry the key
+ * that decrypts the credentials sitting next to it. The key file is created
+ * with mode 0400 and is only ever readable by its owner.
+ */
+export declare function getCredentialKeyPath(): string;
+/**
+ * Returns the path to the audit log directory audit/.
+ */
+export declare function getAuditDirPath(): string;
+/**
+ * Returns the path to the active audit log file, audit/audit.jsonl.
+ * Archives (audit-1.jsonl …) live next to it; the sink rolls them.
+ */
+export declare function getAuditLogPath(): string;
+/**
+ * Returns the path to the daemon PID file sw-agent.pid.
+ */
+export declare function getPidFilePath(): string;
+/**
+ * Returns the path to the daemon status file sw-agent.status.
+ */
+export declare function getStatusFilePath(): string;
+/**
+ * Returns the path to the daemon diagnostic log file daemon.log.
+ */
+export declare function getDaemonLogPath(): string;
+/**
+ * Returns the path to the active daemon error log errors.jsonl.
+ * Archives (errors-1.jsonl …) live next to it; the error tracker rolls them.
+ */
+export declare function getErrorsPath(): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/types/config/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/config/paths.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,iDAAkD,CAAC;AAEnF;;;;;;;;;GASG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAerC;AAMD,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/types/config/schema.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Config errors and hand-rolled validators for machine and database config files.
+ */
+export declare class ConfigError extends Error {
+    code: 'not_found' | 'invalid' | 'write_failed';
+    constructor(code: 'not_found' | 'invalid' | 'write_failed', message: string);
+}
+export declare class ConfigInvalidError extends ConfigError {
+    constructor(message: string);
+}
+export declare class ConfigNotFoundError extends ConfigError {
+    constructor(path: string);
+}
+/**
+ * Checks if a string is a valid hostname.
+ */
+export declare function isValidHostname(s: string): boolean;
+/**
+ * Checks if a string is a valid IPv4 address.
+ */
+export declare function isValidIpv4(s: string): boolean;
+/**
+ * Checks if a string is a valid IPv6 address.
+ */
+export declare function isValidIpv6(s: string): boolean;
+/**
+ * Checks if a string is a valid environment variable name.
+ */
+export declare function isValidEnvVarName(s: string): boolean;
+/**
+ * Checks if a string is a valid ISO 8601 timestamp.
+ */
+export declare function isValidIso8601(s: string): boolean;
+/**
+ * Checks if a string contains only letters, numbers, hyphens, and underscores, up to maxLen.
+ */
+export declare function isValidIdentifier(s: string, maxLen: number): boolean;
+/** URL schemes accepted for transport that carries a bearer token. */
+export type SecureScheme = 'wss:' | 'https:';
+/**
+ * Strictly parses a URL that is required to use `scheme` with an explicit
+ * "//" authority separator.
+ *
+ * The scheme is matched against the raw string with a case-sensitive prefix
+ * check *and* against the parsed URL, because the WHATWG parser normalises
+ * several downgrade shapes that must be rejected: "WSS://host" lower-cases to
+ * the "wss:" scheme, and "wss:/host" (single slash) is happily parsed as the
+ * host. Either one alone would be a bypassable transport check.
+ */
+export declare function parseSecureUrl(raw: unknown, scheme: SecureScheme): URL | null;
+/**
+ * True only for a wss: URL with an explicit lowercase "//" authority.
+ * ws:, http:, WSS: and "wss:/x" are all rejected.
+ */
+export declare function isSecureCloudUrl(raw: unknown): boolean;
+/**
+ * True only for an https: URL with an explicit lowercase "//" authority.
+ * http: is rejected.
+ */
+export declare function isSecureIngestUrl(raw: unknown): boolean;
+/**
+ * Writes a config file atomically with the given owner-only mode: a
+ * create-only mode option is not a control, so the mode is applied explicitly
+ * to both the temporary file and, through the rename, the final file.
+ */
+export declare function writeConfigFileAtomic(filePath: string, contents: string, mode: number): void;
+/**
+ * Redacts secret material from text that is about to be printed or logged.
+ * Replaces each known secret and any URL userinfo password with "***".
+ */
+export declare function redactSecrets(text: string, ...secrets: (string | undefined)[]): string;
+//# sourceMappingURL=schema.d.ts.map

package/dist/types/config/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/config/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,qBAAa,WAAY,SAAQ,KAAK;IAE3B,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,cAAc;gBAA9C,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,cAAc,EACrD,OAAO,EAAE,MAAM;CAKlB;AAED,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,mBAAoB,SAAQ,WAAW;gBACtC,IAAI,EAAE,MAAM;CAIzB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CASlD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAS9C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAK9C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAGpD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAMjD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAIpE;AAED,sEAAsE;AACtE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;AAa7C;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,GAAG,GAAG,GAAG,IAAI,CAqB7E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,GAAG,MAAM,CAQtF"}

package/dist/types/config/token.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Generates a cryptographically random agent token starting with swagt_ followed by 32 base62 characters.
+ */
+export declare function generateAgentToken(): string;
+/**
+ * Validates the format of an agent token.
+ * Returns true if it starts with "swagt_" and the body contains exactly 32 base62 characters.
+ */
+export declare function validateAgentTokenFormat(token: string): boolean;
+/**
+ * Generates an agent ID from the machine label and a random 8 hex char suffix.
+ */
+export declare function generateAgentId(machineLabel: string): string;
+/**
+ * The only token accepted in place of a generated one, for local development
+ * against a dev relay. It is not a credential: every caller must refuse to ship
+ * it to the cloud (see {@link isDevToken}), because it authenticates nothing.
+ */
+export declare const DEV_TOKEN = "swagt_DEV_LOCAL_ONLY";
+/**
+ * True when `token` is the local development token.
+ *
+ * Contract: accepts `unknown` so call sites reading a token out of a config
+ * file, an env var or a cloud payload cannot pass a value the type system
+ * claims is a string when it is not; anything that is not exactly
+ * {@link DEV_TOKEN} — including an empty or absent token — is not a dev token.
+ * This deliberately fails closed: a truthy answer must never mean "treat this
+ * as authenticated".
+ */
+export declare function isDevToken(token: unknown): token is typeof DEV_TOKEN;
+/**
+ * Domain-separation label for the relay-facing credential.
+ *
+ * Bumping this invalidates every derived credential, so it must stay stable
+ * across releases and must never be reused for another purpose.
+ */
+export declare const RELAY_CREDENTIAL_LABEL = "sw-agent/relay-auth/v1";
+/**
+ * Derive the credential actually transmitted to the relay.
+ *
+ * The agent keeps its `swagt_…` token locally and never puts it on the wire.
+ * What travels is this derived value, so the long-lived master token does not
+ * appear in proxy logs, TLS-terminating middleboxes, or `ps` output. The relay
+ * derives the same value from the token it holds at pairing time and compares
+ * digests, so it never needs to store a second secret.
+ *
+ * This is a transmission-hygiene measure, NOT an additional authentication
+ * factor. The derived value is itself a bearer credential with the same
+ * authority as the token it came from: anyone who captures it can
+ * authenticate. Its value is that a leaked relay-side credential is scoped to
+ * the relay and does not also yield the agent's master token for reuse against
+ * other endpoints.
+ *
+ * @param token the locally-held agent token
+ * @returns a lowercase hex digest, 64 characters
+ */
+export declare function deriveRelayCredential(token: string): string;
+/**
+ * Constant-time comparison of two derived relay credentials.
+ * Returns false rather than throwing on malformed input.
+ */
+export declare function relayCredentialsMatch(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=token.d.ts.map

package/dist/types/config/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../../src/config/token.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAU3C;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAM/D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAI5D;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,yBAAyB,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,SAAS,CAEpE;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAUrE"}

package/dist/types/execution/canceller.d.ts

@@ -0,0 +1,41 @@
+import { DbEntry } from '../config/db-config';
+import { InFlightRequest } from './types';
+import { PoolManager } from './pool';
+export interface CancellerOptions {
+    /**
+     * Reuse the pool for the cancellation connection.
+     *
+     * This is not an optimisation: without it every cancel opened a brand-new
+     * TCP + TLS + password-authenticated PostgreSQL connection, so a stream of
+     * cancel requests could exhaust `max_connections` on the customer's database.
+     */
+    poolManager?: PoolManager;
+}
+export interface CancelResult {
+    /** Whether a cancellation signal was delivered to the request. */
+    cancelled: boolean;
+    /** Whether the PostgreSQL backend was actually signalled. */
+    terminated: boolean;
+    /**
+     * Whether the in-process cooperative abort fired. The local runner stops at
+     * its next checkpoint without any database round trip, so this can be true
+     * while `terminated` is false — a blocked server-side statement is still
+     * running until `pg_cancel_backend` reaches it.
+     */
+    local_abort: boolean;
+    reason?: string;
+}
+export declare class Canceller {
+    private readonly inFlight;
+    private readonly opts;
+    constructor(opts?: CancellerOptions);
+    register(req: InFlightRequest): void;
+    unregister(requestId: string): void;
+    getInFlight(): Map<string, InFlightRequest>;
+    /**
+     * Cancel a request by request_id using pg_cancel_backend on a separate
+     * connection (PostgreSQL cannot cancel a query from the busy session).
+     */
+    cancel(requestId: string, dbEntry: DbEntry): Promise<CancelResult>;
+}
+//# sourceMappingURL=canceller.d.ts.map

package/dist/types/execution/canceller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canceller.d.ts","sourceRoot":"","sources":["../../../src/execution/canceller.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAmD,MAAM,QAAQ,CAAC;AAEtF,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IACpE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;gBAE5B,IAAI,GAAE,gBAAqB;IAIvC,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAIpC,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAInC,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC;IAI3C;;;OAGG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;CAuMzE"}

package/dist/types/execution/database-lookup.d.ts

@@ -0,0 +1,56 @@
+import type { DbEntry } from '../config/db-config';
+/**
+ * Why a frame's `(project, db_alias)` did not resolve to a database.
+ *
+ * These are the codes that reach the audit trail as `denial_reason` on a `deny`
+ * record, so they are stable, data-free and closed. They never name a database
+ * that exists: distinguishing "you named a project that is not configured" from
+ * "that project is out of scope" would be a database-existence oracle.
+ */
+export type DatabaseRefusalCode = 
+/** No configured entry matches the frame. */
+'database_not_found'
+/** The entry exists but the allow-list does not permit it. */
+ | 'database_out_of_scope'
+/** No allow-list is configured at all, so this installation serves ping only. */
+ | 'database_scope_not_configured'
+/** `project` and `db_alias` select different configured entries. */
+ | 'db_alias_project_mismatch';
+export interface DatabaseLookupRefusal {
+    ok: false;
+    code: DatabaseRefusalCode;
+    /** Data-free, caller-safe explanation. Never names a configured database. */
+    reason: string;
+    /** The project the frame claimed. */
+    asserted_project: string;
+    /** The `db_alias` the frame claimed, or `''` when it carried none. */
+    asserted_db_alias: string;
+}
+export interface DatabaseLookupHit {
+    ok: true;
+    entry: DbEntry;
+}
+export type DatabaseLookupResult = DatabaseLookupHit | DatabaseLookupRefusal;
+/**
+ * The lookup signature the dispatcher accepts.
+ *
+ * `DbEntry | null` is still accepted so an existing caller — and every test that
+ * passes a one-line `lookupDb` — keeps working; a `null` is read as
+ * `database_not_found`, which is exactly what it meant before. A caller that
+ * wants to say *why* (the allow-list, a project/alias collision) returns the rich
+ * form, and the dispatcher records that code instead of a generic
+ * `db_unavailable`.
+ */
+export type LookupDbFn = (project: string, alias?: string) => DbEntry | DatabaseLookupResult | null;
+/** Read the entry out of any accepted lookup result, or null. */
+export declare function resolvedEntry(result: DbEntry | DatabaseLookupResult | null): DbEntry | null;
+/** Whether a lookup result is a refusal rather than a hit. */
+export declare function isLookupRefusal(result: DbEntry | DatabaseLookupResult | null): result is DatabaseLookupRefusal;
+/**
+ * Normalise any accepted lookup result into the rich form.
+ *
+ * A legacy `DbEntry | null` becomes a hit or `database_not_found`, so the
+ * dispatcher has exactly one shape to audit from.
+ */
+export declare function normaliseLookupResult(result: DbEntry | DatabaseLookupResult | null, assertedProject: string, assertedAlias: string | undefined): DatabaseLookupResult;
+//# sourceMappingURL=database-lookup.d.ts.map

package/dist/types/execution/database-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-lookup.d.ts","sourceRoot":"","sources":["../../../src/execution/database-lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB;AAC7B,6CAA6C;AAC3C,oBAAoB;AACtB,8DAA8D;GAC5D,uBAAuB;AACzB,iFAAiF;GAC/E,+BAA+B;AACjC,oEAAoE;GAClE,2BAA2B,CAAC;AAEhC,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,mBAAmB,CAAC;IAC1B,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,gBAAgB,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,GAAG,qBAAqB,CAAC;AAE7E;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,KACX,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAAC;AAE3C,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,CAI3F;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAC7B,MAAM,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,GAC5C,MAAM,IAAI,qBAAqB,CAOjC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,EAC7C,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,MAAM,GAAG,SAAS,GAChC,oBAAoB,CAatB"}

package/dist/types/execution/dispatcher.d.ts

@@ -0,0 +1,181 @@
+import { AgentMessage, EventKind, Role } from '../protocol/envelope';
+import { PoolManager } from './pool';
+import { QueryRunner } from './query-runner';
+import { MigrationRunner } from './migration-runner';
+import { Canceller } from './canceller';
+import { Introspector } from './introspection';
+import { ErrorCode } from '../protocol/errors';
+import { PermissionChecker } from '../permissions/checker';
+import { PlanRegistry } from '../permissions/plan-registry';
+import { MachineConfig } from '../config/machine-config';
+import { PermissionLevel } from '../permissions/types';
+import { AuditSink } from '../audit/sink';
+import { AuditAction } from '../audit/types';
+import { RateLimiter } from './rate-limiter';
+import { type LookupDbFn } from './database-lookup';
+export interface DispatcherOptions {
+    poolManager: PoolManager;
+    queryRunner: QueryRunner;
+    migrationRunner: MigrationRunner;
+    canceller: Canceller;
+    introspector: Introspector;
+    permissionChecker: PermissionChecker;
+    planRegistry: PlanRegistry;
+    /**
+     * Look up the DB entry for a frame's `(project, db_alias)`.
+     *
+     * Returning the rich `DatabaseLookupResult` lets the caller say *why* a frame
+     * resolved to nothing (out of scope, no allow-list configured, or a
+     * project/alias collision) so the refusal is audited under a distinct reason
+     * instead of a generic "unavailable". A plain `DbEntry | null` is still
+     * accepted and is read as "no such database".
+     */
+    lookupDb: LookupDbFn;
+    /** Look up machine config (for default permission). */
+    getMachineConfig: () => MachineConfig;
+    /** Send a message back to the browser. */
+    send: (msg: AgentMessage) => Promise<void>;
+    /**
+     * Transport drain signal, awaited by the streaming fetch loop before every
+     * cursor fetch (audit H-10). Supplying it is what makes the pause/resume real:
+     * `send` alone only stops the producer when the socket write callback fires,
+     * which cannot see bytes already queued in the transport.
+     *
+     * Optional by design. Without it a stream still completes — it just
+     * self-throttles on each awaited chunk send instead of the send buffer.
+     */
+    waitForDrain?: () => Promise<void>;
+    /** Optional audit sink for logging decisions and outcomes. */
+    auditSink?: AuditSink;
+    /**
+     * Budget and concurrency control for inbound work. Defaults to a process-wide
+     * limiter; an explicit instance is only for tests and for a host that wants
+     * its own policy.
+     */
+    rateLimiter?: RateLimiter;
+}
+export declare class Dispatcher {
+    private readonly opts;
+    private readonly rateLimiter;
+    constructor(opts: DispatcherOptions);
+    private sendResponse;
+    /**
+     * `pg_error` is deliberately limited to the two allow-listed fields. Passing
+     * `detail` or `hint` here is a compile error on purpose: both routinely carry
+     * row data (`DETAIL:  Key (email)=(alice@corp.com) already exists.`) and the
+     * risk only ever grows.
+     */
+    private sendError;
+    /**
+     * Register a migration plan. Callers must have passed `evaluateEventGate`;
+     * this method re-checks the shape of the payload and never invents an
+     * effective permission level for the audit record.
+     */
+    handlePlanRegister(msg: AgentMessage, statements: string[], riskLevel: 'low' | 'medium' | 'high' | undefined, permissionLevel: PermissionLevel, resolvedAlias?: string): Promise<void>;
+    /**
+     * Derive the authorization decision for an inbound `event` frame.
+     *
+     * `PlanRegistry.canRegister` owns the plan-registration decision, so asking
+     * it directly is what keeps the entry gate and the registry from disagreeing.
+     */
+    private evaluateGate;
+    /**
+     * Handle an inbound `event` frame.
+     *
+     * Every kind is authorized before any handler runs. The previous
+     * implementation dispatched `approval_response` and `plan_register` from the
+     * top of `handle()`, ahead of the query/migration permission pipeline, so a
+     * `viewer` could resolve another user's pending manual approval and could
+     * register an arbitrary migration plan for later replay at `auto_upgrade`.
+     */
+    private handleEvent;
+    /**
+     * Handle one inbound frame.
+     *
+     * The frame's `(project, db_alias)` is resolved first and everything after —
+     * every authorization decision, every database call, every audit record —
+     * happens inside the resolved-database context. That ordering is the durable
+     * half of the  fix: the audit sink takes the resolved identity from the
+     * context, so no call site can write the frame's own claim into the record, and
+     * a frame that resolves to nothing is recorded as `unresolved` rather than as
+     * the database it asked for.
+     */
+    handle(msg: AgentMessage): Promise<void>;
+    /**
+     * The fields every audit record for one frame carries.
+     *
+     * Centralised so the asserted identity (`project`, `db_alias_asserted`) is
+     * recorded identically on allows and denials: the resolved identity comes from
+     * the sink's context, and these two come from the frame. A record that names
+     * what the frame claimed and what the agent resolved is the only way a
+     * mismatch like  is visible to anyone reading the trail afterwards.
+     */
+    private auditBase;
+    /** Awaited audit write, or a no-op when no sink is configured. */
+    private auditDeny;
+    private handleResolved;
+    /**
+     * Arm the independent approval watchdog for one request.
+     *
+     * Returns the timer so the caller can clear it. The watchdog fires only if an
+     * approval for THIS request is still outstanding at the handler's reaper
+     * deadline; if the request is merely running a long query, or already finished,
+     * it does nothing. It releases the concurrency permit — `RateLimitPermit`
+     * releases are idempotent, so the ordinary `finally` remains correct — and
+     * records `approval_promise_stranded`, because a stranded promise is exactly
+     * the condition that used to leak a permit per attack and disable the database
+     * for everyone.
+     */
+    private armApprovalWatchdog;
+    /**
+     * `cancel`, bound to the request it names.
+     *
+     * The only gate used to be `hasCapability(role, 'cancel')`, so any developer
+     * could abort any other principal's in-flight query in any project, and the
+     * target's database was resolved from the ATTACKER's project when the target
+     * had none. Two binding conditions are now required on top of the capability:
+     * the caller is the requesting principal, or holds a STRICTLY more privileged
+     * role. The target's database comes from the target's own frame and nowhere
+     * else.
+     */
+    private handleCancel;
+    /**
+     * Map an internal failure to an outbound `error` payload.
+     *
+     * PostgreSQL errors are reduced to an allow-list of fields plus a curated
+     * message per SQLSTATE. `detail` and `hint` are never forwarded: a duplicate
+     * key violation ships `Key (email)=(alice@corp.com) already exists.` in
+     * `detail`, and messages embed the offending SQL and absolute paths.
+     */
+    private mapErrorToPayload;
+}
+interface EventGateDecision {
+    allowed: boolean;
+    errorCode: ErrorCode;
+    reason: string;
+    /** Audit action to record on denial; null when the frame is not an action. */
+    auditAction: AuditAction | null;
+    code: string;
+}
+/**
+ * Decide whether an inbound `event` frame may be handled at all.
+ *
+ * This runs before any event handler. The `event` branch used to sit ahead of
+ * the query/migration permission pipeline, so a `viewer` could resolve another
+ * user's pending manual approval and could register an arbitrary migration
+ * plan for later replay under `auto_upgrade` — the default level. Both kinds
+ * now derive their required capability from the same `hasCapability` matrix
+ * the query path uses, and any kind the agent does not accept inbound is
+ * refused outright.
+ *
+ * `approval_response` requires both `query_write` and `ddl`: an approval can
+ * authorise a write or a DDL statement, so the responder must be able to do
+ * everything it can authorise.
+ */
+export declare function evaluateEventGate(kind: EventKind | undefined, role: Role, permissionLevel: PermissionLevel, canRegisterPlan?: (role: Role, permissionLevel: PermissionLevel) => {
+    allowed: boolean;
+    code?: string;
+    reason?: string;
+}): EventGateDecision;
+export {};
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/types/execution/dispatcher.d.ts.map

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