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

package/dist/cjs/protocol/envelope.js

@@ -0,0 +1,309 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENVELOPE_MAX_NEGOTIABLE_ROLE_DEFAULT = exports.MAC_SIGNED_ENVELOPE_FIELDS = exports.EVENT_KINDS = exports.MESSAGE_TYPES = exports.ROLES = exports.PROTOCOL_VERSION_V1 = void 0;
+exports.isRole = isRole;
+exports.canonicalJson = canonicalJson;
+exports.canonicalEnvelopeJson = canonicalEnvelopeJson;
+exports.deriveSessionMacKey = deriveSessionMacKey;
+exports.computeEnvelopeMac = computeEnvelopeMac;
+exports.signEnvelope = signEnvelope;
+exports.verifyEnvelopeMac = verifyEnvelopeMac;
+exports.newEnvelopeNonce = newEnvelopeNonce;
+exports.isValidEnvelopeNonce = isValidEnvelopeNonce;
+exports.createMessage = createMessage;
+const constants_1 = require("./constants");
+const crypto = __importStar(require("crypto"));
+exports.PROTOCOL_VERSION_V1 = constants_1.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.
+ */
+exports.ROLES = ['admin', 'developer', 'data_reader', 'viewer'];
+function isRole(value) {
+    return typeof value === 'string' && exports.ROLES.includes(value);
+}
+/**
+ * Canonical list of message types. `MessageType` is derived from this tuple;
+ * `validateEnvelope` gates on the same array.
+ */
+exports.MESSAGE_TYPES = [
+    'ping',
+    'introspect',
+    'query',
+    'stream_query',
+    'migration_run',
+    'cancel',
+    'response',
+    'error',
+    'stream_chunk',
+    'stream_end',
+    'event',
+];
+/**
+ * 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.
+ */
+exports.EVENT_KINDS = [
+    'status_change',
+    'migration_progress',
+    'approval_required',
+    'approval_response',
+    'warning',
+    'resume_request',
+    'plan_register',
+];
+/**
+ * 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.
+ */
+exports.MAC_SIGNED_ENVELOPE_FIELDS = [
+    'v',
+    'id',
+    'type',
+    'project',
+    'user',
+    'db_alias',
+    'ts',
+    'nonce',
+    'payload',
+];
+/* ------------------------------------------------------------------ */
+/* Canonical serialization                                             */
+/* ------------------------------------------------------------------ */
+/**
+ * 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.
+ */
+function canonicalJson(value) {
+    return canonicalize(value, new Set());
+}
+function canonicalize(value, seen) {
+    if (value === null) {
+        return 'null';
+    }
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'number':
+            if (!Number.isFinite(value)) {
+                throw new Error('canonicalJson: non-finite number is not representable');
+            }
+            return JSON.stringify(value);
+        case 'string':
+            return JSON.stringify(value);
+        case 'object':
+            break;
+        default:
+            throw new Error(`canonicalJson: unsupported value of type ${typeof value}`);
+    }
+    const obj = value;
+    if (seen.has(obj)) {
+        throw new Error('canonicalJson: circular structure');
+    }
+    seen.add(obj);
+    try {
+        if (Array.isArray(obj)) {
+            const items = obj.map((item) => (item === undefined ? 'null' : canonicalize(item, seen)));
+            return `[${items.join(',')}]`;
+        }
+        const proto = Object.getPrototypeOf(obj);
+        if (proto !== Object.prototype && proto !== null) {
+            throw new Error('canonicalJson: only plain objects are representable');
+        }
+        const record = obj;
+        const parts = [];
+        for (const key of Object.keys(record).sort()) {
+            const member = record[key];
+            if (member === undefined) {
+                continue;
+            }
+            parts.push(`${JSON.stringify(key)}:${canonicalize(member, seen)}`);
+        }
+        return `{${parts.join(',')}}`;
+    }
+    finally {
+        seen.delete(obj);
+    }
+}
+/**
+ * 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.
+ */
+function canonicalEnvelopeJson(msg) {
+    if (typeof msg !== 'object' || msg === null) {
+        throw new Error('canonicalEnvelopeJson: envelope must be an object');
+    }
+    const source = msg;
+    const signed = {};
+    for (const key of Object.keys(source)) {
+        if (key === 'mac' || source[key] === undefined) {
+            continue;
+        }
+        signed[key] = source[key];
+    }
+    return canonicalJson(signed);
+}
+/* ------------------------------------------------------------------ */
+/* Session MAC key derivation, signing, verification                   */
+/* ------------------------------------------------------------------ */
+/**
+ * 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.
+ */
+function deriveSessionMacKey(opts) {
+    if (typeof opts.dataChannelToken !== 'string' || opts.dataChannelToken.length === 0) {
+        throw new Error('deriveSessionMacKey: dataChannelToken must be a non-empty string');
+    }
+    const salt = crypto
+        .createHash('sha256')
+        .update(constants_1.ENVELOPE_MAC_KDF.saltLabel, 'utf8')
+        .update('\0', 'utf8')
+        .update(opts.agentId, 'utf8')
+        .update('\0', 'utf8')
+        .update(opts.browserSessionId, 'utf8')
+        .digest();
+    const info = `${constants_1.ENVELOPE_MAC_KDF.infoLabel}/${opts.agentId}/${opts.browserSessionId}`;
+    return Buffer.from(crypto.hkdfSync(constants_1.ENVELOPE_MAC_KDF.digest, Buffer.from(opts.dataChannelToken, 'utf8'), salt, info, constants_1.ENVELOPE_MAC_KDF.keyBytes));
+}
+/** Lowercase hex HMAC-SHA256 of the canonical envelope. */
+function computeEnvelopeMac(macKey, msg) {
+    if (!Buffer.isBuffer(macKey) || macKey.length !== constants_1.ENVELOPE_MAC_KDF.keyBytes) {
+        throw new Error(`computeEnvelopeMac: macKey must be ${constants_1.ENVELOPE_MAC_KDF.keyBytes} bytes`);
+    }
+    return crypto
+        .createHmac(constants_1.ENVELOPE_MAC_KDF.digest, macKey)
+        .update(canonicalEnvelopeJson(msg), 'utf8')
+        .digest('hex');
+}
+/**
+ * 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`).
+ */
+function signEnvelope(macKey, msg) {
+    const nonce = msg.nonce ?? newEnvelopeNonce();
+    const unsigned = { ...msg, nonce };
+    delete unsigned.mac;
+    return { ...unsigned, mac: computeEnvelopeMac(macKey, unsigned) };
+}
+/**
+ * Constant-time MAC check. Returns false for a missing, malformed, or
+ * non-matching MAC; never throws.
+ */
+function verifyEnvelopeMac(macKey, msg) {
+    const mac = msg.mac;
+    if (typeof mac !== 'string' ||
+        mac.length !== constants_1.LIMITS.ENVELOPE_MAC_HEX_LENGTH ||
+        !/^[0-9a-f]+$/.test(mac)) {
+        return false;
+    }
+    let expected;
+    let provided;
+    try {
+        expected = Buffer.from(computeEnvelopeMac(macKey, msg), 'hex');
+        provided = Buffer.from(mac, 'hex');
+    }
+    catch {
+        return false;
+    }
+    return expected.length === provided.length && crypto.timingSafeEqual(expected, provided);
+}
+/** Fresh anti-replay nonce (base64url, 24 random bytes). */
+function newEnvelopeNonce() {
+    return crypto.randomBytes(24).toString('base64url');
+}
+/** True when `nonce` is a syntactically valid envelope nonce. */
+function isValidEnvelopeNonce(nonce) {
+    return (typeof nonce === 'string' &&
+        nonce.length >= constants_1.LIMITS.ENVELOPE_NONCE_MIN_LENGTH &&
+        nonce.length <= constants_1.LIMITS.ENVELOPE_NONCE_MAX_LENGTH &&
+        constants_1.ENVELOPE_NONCE_PATTERN.test(nonce));
+}
+/**
+ * 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.
+ */
+exports.ENVELOPE_MAX_NEGOTIABLE_ROLE_DEFAULT = 'developer';
+/**
+ * Helper: create a message with sensible defaults.
+ * Useful for tests and for agent's own message construction.
+ */
+function createMessage(type, opts) {
+    if (!isRole(opts.user.role)) {
+        throw new Error(`Invalid role: ${opts.user.role}`);
+    }
+    return {
+        v: constants_1.PROTOCOL_VERSION,
+        id: opts.id || crypto.randomUUID(),
+        type,
+        project: opts.project,
+        user: opts.user,
+        db_alias: opts.db_alias,
+        ts: Date.now(),
+        nonce: opts.nonce ?? newEnvelopeNonce(),
+        payload: opts.payload,
+    };
+}
+//# sourceMappingURL=envelope.js.map

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

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

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