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

package/dist/esm/permissions/checker.js

@@ -0,0 +1,322 @@
+import { hasCapability, capabilityForClassification, capabilityForMessageType, explainWhyNotAProvableRead, isProvableRead, } from './role-policy';
+import { classifyStatement } from '../execution/statement-classifier';
+import { SqlParseError, SqlParserUnavailableError } from '../execution/sql-parser';
+import { previewStatement } from '../audit/redact';
+export class PermissionChecker {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Decide whether a request may proceed. This is the ONLY method the
+     * dispatcher calls.
+     *
+     * Order of checks (all of them must pass):
+     *   0. Parse. A statement we cannot parse is denied, never guessed at. A
+     *      parse error and an unavailable parser are both terminal.
+     *   1. Exactly one statement. Multi-statement execution is refused outright
+     *      because node-postgres uses the simple query protocol when no bind
+     *      parameters are supplied, and the simple protocol runs every
+     *      semicolon-separated statement.
+     *   2. Anti-spoofing. The browser-claimed intent must match the parsed
+     *      classification. No intent value exempts the request from this check;
+     *      `intent: 'migration'` is accepted only on the `migration_run` message
+     *      type and never in place of the comparison.
+     *   3. Role capability for the message type and for the parsed class. A
+     *      classification that is not a *provable* read requires `ddl`.
+     *   4. Permission level.
+     *
+     * @param resolveFunctionEffects Answers "what can this function call do?"
+     *      from `pg_proc` on a live connection. It is an argument, not a global,
+     *      because only the caller knows which database the statement is about —
+     *      and OIDs, and therefore which overloads exist, are per-database. A
+     *      caller that cannot supply one gets `analysed: false`, and every
+     *      statement that calls a function is then escalated rather than
+     *      trusted.
+     */
+    async check(req, statements, resolveFunctionEffects) {
+        const resolveEffects = resolveFunctionEffects ?? this.opts.resolveFunctionEffects ?? undefined;
+        // ---- Step 0: parse. Fail closed. ------------------------------------
+        // A migration_run carries an array of statements. Classifying only the
+        // first one was a hole: `['SELECT 1', 'DROP TABLE users']` passed the read
+        // check on statements[0] and then executed the DROP. Every statement is
+        // classified, and the most restrictive result governs.
+        const isMigrationRun = req.message_type === 'migration_run';
+        const perStatement = [];
+        const statementsToParse = isMigrationRun ? (statements ?? [req.sql]) : [req.sql];
+        for (let i = 0; i < statementsToParse.length; i++) {
+            let c;
+            try {
+                c = await classifyStatement(statementsToParse[i], {
+                    resolveFunctionEffects: resolveEffects,
+                });
+            }
+            catch (err) {
+                if (err instanceof SqlParserUnavailableError) {
+                    return {
+                        allowed: false,
+                        reason: 'The PostgreSQL parser is unavailable, so the statement cannot be verified. ' +
+                            'Refusing to execute unverified SQL.',
+                        code: 'parser_unavailable',
+                    };
+                }
+                if (err instanceof SqlParseError) {
+                    const where = statementsToParse.length > 1 ? ` (statement ${i + 1})` : '';
+                    return {
+                        allowed: false,
+                        reason: `PostgreSQL could not parse the statement${where}: ${err.message}`,
+                        code: 'unparseable_statement',
+                    };
+                }
+                throw err;
+            }
+            perStatement.push(c);
+        }
+        const actualClassification = aggregateClassification(perStatement);
+        // ---- Step 1: single-statement invariant -----------------------------
+        // Every plan entry must be exactly one statement, otherwise the simple
+        // query protocol can run extra statements the classifier never saw.
+        const empty = perStatement.find((c) => c.statement_count === 0);
+        if (empty) {
+            return {
+                allowed: false,
+                reason: 'The statement contains no executable SQL (comments or whitespace only). ' +
+                    'Nothing to verify, so nothing is executed.',
+                code: 'unparseable_statement',
+                classification: actualClassification,
+            };
+        }
+        const offenders = perStatement.filter((c) => c.statement_count !== 1);
+        if (offenders.length > 0) {
+            const where = statementsToParse.length > 1 ? ' in migration plan' : '';
+            return {
+                allowed: false,
+                reason: `Expected exactly one statement${where} but PostgreSQL's parser found ` +
+                    `${offenders[0].statement_count} in one of them. Multi-statement execution is ` +
+                    'refused because it would run every statement regardless of how it is classified.',
+                code: 'multiple_statements',
+                classification: actualClassification,
+            };
+        }
+        // ---- Step 2: anti-spoofing -----------------------------------------
+        // No intent value grants an exemption. `intent` is advisory input; the
+        // parsed classification is the only thing that decides. The previous
+        // implementation carried `&& req.intent !== 'migration'`, which let a
+        // caller disable this check entirely by claiming an intent the message type
+        // does not support.
+        const claimed = req.intent;
+        const actualType = actualClassification.type;
+        if (claimed === 'migration' && !isMigrationRun) {
+            return {
+                allowed: false,
+                reason: `Intent 'migration' is only meaningful on a migration_run message, not on ` +
+                    `'${req.message_type}'. The statement was parsed as '${actualType}' ` +
+                    `(${actualClassification.verb}); 'migration' is not an exemption from intent verification.`,
+                code: 'intent_not_applicable',
+                classification: actualClassification,
+            };
+        }
+        const intentMatches = claimed === actualType ||
+            // A SELECT statement declared with intent 'read' is structurally a read query,
+            // even if non-immutable functions demoted its type to 'write'. Role capability
+            // and permission level checks below will continue to enforce security.
+            (claimed === 'read' && actualClassification.verb === 'SELECT') ||
+            // A migration_run's `intent` is 'migration' and its payload is a plan, not
+            // a single statement, so there is no single parsed type to compare with.
+            (claimed === 'migration' && isMigrationRun);
+        if (!intentMatches) {
+            return {
+                allowed: false,
+                reason: `Intent mismatch: request declared '${claimed}' but PostgreSQL parsed it as '${actualType}' (${actualClassification.verb}${actualClassification.kind !== actualClassification.verb
+                    ? ' ' + actualClassification.kind
+                    : ''})`,
+                code: 'intent_mismatch',
+                classification: actualClassification,
+            };
+        }
+        // ---- Step 3: role capability ---------------------------------------
+        const messageTypeCap = capabilityForMessageType(req.message_type);
+        if (messageTypeCap && !hasCapability(req.role, messageTypeCap)) {
+            return {
+                allowed: false,
+                reason: `Role '${req.role}' cannot perform '${messageTypeCap}'`,
+                code: 'role_insufficient',
+                classification: actualClassification,
+            };
+        }
+        const classificationCap = capabilityForClassification(actualClassification);
+        if (classificationCap && !hasCapability(req.role, classificationCap)) {
+            return {
+                allowed: false,
+                reason: `Role '${req.role}' cannot run '${actualClassification.type}' statements (${actualClassification.kind})`,
+                code: 'role_insufficient',
+                classification: actualClassification,
+            };
+        }
+        // ---- Step 4: permission level ---------------------------------------
+        const provableRead = isProvableRead(actualClassification);
+        switch (req.permission_level) {
+            case 'full':
+                return {
+                    allowed: true,
+                    reason: 'Full permission',
+                    code: 'allowed',
+                    classification: actualClassification,
+                };
+            case 'read_only': {
+                if (!provableRead) {
+                    return {
+                        allowed: false,
+                        reason: `Read-only mode: ${explainWhyNotAProvableRead(actualClassification)}. ` +
+                            'PostgreSQL will not refuse it for you: default_transaction_read_only = on ' +
+                            'constrains writes to relations, not reads, notifications or function bodies.',
+                        code: 'permission_denied',
+                        classification: actualClassification,
+                    };
+                }
+                return {
+                    allowed: true,
+                    reason: 'Read allowed in read_only mode',
+                    code: 'allowed',
+                    classification: actualClassification,
+                };
+            }
+            case 'auto_upgrade': {
+                if (provableRead) {
+                    return {
+                        allowed: true,
+                        reason: 'Read allowed',
+                        code: 'allowed',
+                        classification: actualClassification,
+                    };
+                }
+                const upgrade = await this.opts.autoUpgradeChecker.check(req, statements);
+                if (upgrade.granted) {
+                    return {
+                        allowed: true,
+                        reason: upgrade.reason,
+                        code: 'auto_upgrade_granted',
+                        classification: actualClassification,
+                    };
+                }
+                return {
+                    allowed: false,
+                    reason: `Auto-upgrade not granted: ${upgrade.reason}`,
+                    code: 'plan_not_registered',
+                    classification: actualClassification,
+                };
+            }
+            case 'manual': {
+                if (provableRead) {
+                    return {
+                        allowed: true,
+                        reason: 'Read allowed',
+                        code: 'allowed',
+                        classification: actualClassification,
+                    };
+                }
+                // Everything else needs approval from the user who requested it.
+                // `ManualApprovalHandler` binds the pending approval to this user id
+                // and to a nonce it minted itself, so nobody else on the relay can
+                // approve it. Only a redacted preview is transmitted: the full SQL can
+                // carry PII literals and this event crosses the cloud boundary.
+                const approvalRequest = {
+                    request_id: req.request_id,
+                    sql_preview: previewStatement(req.sql),
+                    intent: actualClassification.type === 'write' ? 'write' : 'ddl',
+                    db_alias: req.db_alias,
+                };
+                const approval = await this.opts.manualApprovalHandler.requestApproval({
+                    ...approvalRequest,
+                    project: req.project,
+                    user: req.user,
+                });
+                if (approval.approved) {
+                    return {
+                        allowed: true,
+                        reason: 'Approved by user',
+                        code: 'allowed',
+                        classification: actualClassification,
+                    };
+                }
+                return {
+                    allowed: false,
+                    reason: approval.reason || 'Approval denied',
+                    code: 'permission_denied',
+                    classification: actualClassification,
+                    approval_request: approvalRequest,
+                };
+            }
+            default:
+                return {
+                    allowed: false,
+                    reason: `Invalid permission level '${req.permission_level}'`,
+                    code: 'permission_denied',
+                    classification: actualClassification,
+                };
+        }
+    }
+}
+/**
+ * Combine per-statement classifications for a multi-statement request.
+ *
+ * The aggregate is the MOST restrictive classification present, and it carries
+ * the union of every read violation, function-effect record and side effect.
+ * This is what stops `['SELECT 1', 'DROP TABLE users']` from being treated as a
+ * read because its first statement is one.
+ */
+function aggregateClassification(parts) {
+    if (parts.length === 0) {
+        return {
+            type: 'unknown',
+            kind: 'EMPTY',
+            transactional: true,
+            verb: '',
+            statement_count: 0,
+            parse_ok: false,
+            read_violations: ['parse_error'],
+            function_effects: [],
+            side_effects: [],
+        };
+    }
+    if (parts.length === 1)
+        return parts[0];
+    const rank = {
+        read: 0,
+        utility: 1,
+        write: 2,
+        ddl: 3,
+        unknown: 4,
+    };
+    let worst = parts[0];
+    for (const p of parts) {
+        if (rank[p.type] > rank[worst.type])
+            worst = p;
+    }
+    const violations = [...new Set(parts.flatMap((p) => p.read_violations))];
+    const functionEffects = dedupeRecords(parts.flatMap((p) => p.function_effects ?? []));
+    const sideEffects = [...new Set(parts.flatMap((p) => p.side_effects ?? []))];
+    return {
+        type: worst.type,
+        kind: parts.length > 1 ? `${parts.length} statements` : worst.kind,
+        // A plan is only transactional if every statement is.
+        transactional: parts.every((p) => p.transactional),
+        verb: worst.verb,
+        statement_count: parts.reduce((n, p) => n + p.statement_count, 0),
+        parse_ok: parts.every((p) => p.parse_ok),
+        read_violations: violations,
+        function_effects: functionEffects,
+        side_effects: sideEffects,
+    };
+}
+/** One record per distinct function name; the first verdict for a name wins. */
+function dedupeRecords(records) {
+    const byName = new Map();
+    for (const record of records) {
+        const key = record.name.toLowerCase();
+        if (!byName.has(key))
+            byName.set(key, record);
+    }
+    return [...byName.values()];
+}
+//# sourceMappingURL=checker.js.map

package/dist/esm/permissions/checker.js.map

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

package/dist/esm/permissions/manual-approval.d.ts

@@ -0,0 +1,213 @@
+import { AgentMessage, Role } from '../protocol/envelope';
+import { ApprovalResponseEvent } from '../protocol/messages';
+import { ManualApprovalResult } from './types';
+import { AuditSink } from '../audit/sink';
+/**
+ * Resolve the manual-approval window: the single source of truth is
+ * DEFAULTS.APPROVAL_TIMEOUT_MS, with an optional operator override read from
+ * APPROVAL_TIMEOUT_ENV_VAR and clamped into
+ * [LIMITS.APPROVAL_TIMEOUT_MIN_MS, LIMITS.APPROVAL_TIMEOUT_MAX_MS].
+ *
+ * Audit L-03. The window existed in three places with three different
+ * fallbacks (the dead constant, a hardcoded 60_000 in the value advertised to the
+ * browser, and `opts ?? env ?? 60_000` in this module), and an override set to
+ * something absurd was honoured verbatim. Export this so every caller resolves
+ * the same number instead of re-deriving it: `new ManualApprovalHandler({ … })`
+ * with no `timeoutMs` already does, so passing `timeoutMs: DEFAULTS.…` at a call
+ * site is unnecessary and would *bypass* the env override.
+ */
+export declare function resolveApprovalTimeoutMs(env?: NodeJS.ProcessEnv): {
+    timeoutMs: number;
+    source: 'constant' | 'env' | 'clamped' | 'invalid';
+};
+export interface ManualApprovalOptions {
+    /**
+     * Approval window in ms. Omit to resolve from DEFAULTS.APPROVAL_TIMEOUT_MS with
+     * a clamped env override (see {@link resolveApprovalTimeoutMs}); an explicit
+     * value is still clamped so no caller can create an unbounded window.
+     */
+    timeoutMs?: number;
+    /**
+     * Extra slack before the independent reaper fires, in ms. Clamped to
+     * [MIN_STRANDED_SLACK_MS, MAX_STRANDED_SLACK_MS]; the lower bound exists so the
+     * reaper can never be turned into "the same instant as the approval timer",
+     * which would report every ordinary expiry as a stranding. Tests use it to keep
+     * the reaper observable without waiting out a real approval window.
+     */
+    strandedSlackMs?: number;
+    /** Clock injection point so expiry is testable deterministically. */
+    now?: () => number;
+    /** Called to send a message to the browser. */
+    send: (msg: AgentMessage) => Promise<void>;
+    /** Called to register a pending approval (for tracking). */
+    onPending?: (requestId: string, expiresAt: number) => void;
+    /** Called when approval is resolved (for tracking). */
+    onResolved?: (requestId: string, result: ManualApprovalResult) => void;
+    /**
+     * Called when the independent reaper has to force an approval closed.
+     *
+     * This is the hook that makes permit release independent of the approval
+     * promise settling: the dispatcher releases its concurrency permit here
+     * rather than relying on a promise an attacker-controlled `request_id` could
+     * strand. It runs before the promise is settled, and it is not allowed to
+     * throw into the timer.
+     */
+    onStranded?: (info: {
+        request_id: string;
+        project: string;
+        user_id: string;
+    }) => void;
+    /** Optional audit sink for logging decisions and outcomes. */
+    auditSink?: AuditSink;
+}
+/**
+ * What {@link ManualApprovalHandler.requestApproval} hands back.
+ *
+ * Deliberately BOTH a promise and a discriminated result. The permission checker
+ * (`src/permissions/checker.ts`) has always awaited this call and reads
+ * `approval.approved`, so the promise must keep being the return value; a caller
+ * that needs to know *why* nothing was approved reads `ok`/`code`. A duplicate
+ * `request_id` is therefore a refusal with its own code, not an exception and not
+ * an overwrite: the pending entry belongs to the first caller and its promise has
+ * to stay reachable, or that request waits out its window and never returns
+ *.
+ */
+export type ManualApprovalRequestResult = (Promise<ManualApprovalResult> & {
+    ok: true;
+    promise: Promise<ManualApprovalResult>;
+    approval_id: string;
+}) | (Promise<ManualApprovalResult> & {
+    ok: false;
+    code: 'duplicate_request_id';
+    reason: string;
+    promise: null;
+    approval_id: null;
+});
+/**
+ * Extra slack on top of the approval window before the independent reaper fires.
+ *
+ * The approval timer settles the promise; the reaper is what guarantees the
+ * permit is released and the trail records that it had to be. It must be strictly
+ * later than the approval timer so the ordinary expiry path never looks like a
+ * stranding.
+ */
+export declare const APPROVAL_STRANDED_SLACK_MS = 5000;
+export declare class ManualApprovalHandler {
+    /**
+     * Pending approvals, keyed by a **server-minted** id.
+     *
+     * The key is `randomUUID()` — not the caller-supplied `request_id`.
+     * The request id is still recorded on the entry and is still what the map is
+     * *searched* by (`findByRequestId`), but it can no longer *address* an entry, so
+     * a second frame reusing someone else's id cannot overwrite, expire or resolve
+     * their approval. Two requests that both claim id `X` now occupy two distinct
+     * keys and neither can reach the other.
+     */
+    private pending;
+    private readonly timeoutMs;
+    private readonly send;
+    private readonly onPending?;
+    private readonly onResolved?;
+    private readonly onStranded?;
+    private readonly auditSink?;
+    private readonly now;
+    private readonly strandedSlackMs;
+    constructor(opts: ManualApprovalOptions);
+    /** The window this handler enforces, in ms. */
+    getTimeoutMs(): number;
+    /**
+     * When the independent reaper for a request parked *now* would fire.
+     *
+     * The dispatcher arms its own watchdog at this deadline so it can release a
+     * concurrency permit even if the approval promise never settles.
+     */
+    getStrandedReaperMs(): number;
+    /**
+     * Whether an approval is pending for exactly this `(request_id, requester)`
+     * pair, addressed by SEARCH rather than by key.
+     *
+     * The dispatcher's watchdog uses this to tell a stranded approval from a
+     * merely slow one: a request that is not parked is not waiting for a human.
+     */
+    isPending(requestId: string, requesterId: string): boolean;
+    /**
+     * Request approval for a query.
+     *
+     * The pending approval is bound to a **server-minted** key and carries a
+     * cryptographically random nonce that only this process knows. `handleResponse`
+     * requires the nonce and the requesting user id to match; the key is not
+     * derivable from anything the sender controls, so a duplicate `request_id`
+     * cannot reach, overwrite or expire another approval.
+     *
+     * A second request that reuses an id that is already pending for the same
+     * requester is REFUSED with `duplicate_request_id` — it does not overwrite the
+     * first entry, and the first promise stays reachable. The caller is expected to
+     * release the resources it acquired for the refused request.
+     *
+     * Only a redacted, length-capped preview of the statement is transmitted. The
+     * full SQL can carry PII literals (`INSERT INTO users(email) VALUES
+     * ('alice@corp.com')`) and this event crosses the cloud boundary.
+     */
+    requestApproval(params: {
+        request_id: string;
+        /** Full statement text. Used only to build the redacted preview. */
+        sql?: string;
+        sql_preview: string;
+        intent: 'write' | 'ddl';
+        db_alias: string;
+        project: string;
+        user: {
+            id: string;
+            role: Role;
+        };
+    }): ManualApprovalRequestResult;
+    /**
+     * Resolve a pending approval from a browser response.
+     *
+     * All of the following must hold, or the pending approval is left untouched:
+     *   - a pending approval exists for `(request_id, requesting_user_id)`
+     *   - `actorId` (falling back to `user_id`) equals the requesting user
+     *   - the actor's role holds the `approve_ddl` capability, so a `viewer` can
+     *     never approve a pending write/DDL
+     *   - `approval_nonce` matches the value this process minted
+     *
+     * A nonce is consumed exactly once: the entry is removed as it resolves, so a
+     * replayed frame finds nothing.
+     *
+     * `params` carries the *envelope* identity, which is the only identity the
+     * dispatcher has verified. The payload's own `approved_by` string is treated
+     * as untrusted display data and is deliberately ignored — the audit record
+     * takes the approver from `params`.
+     */
+    handleResponse(event: ApprovalResponseEvent, params: {
+        actorId: string;
+        actorRole: Role;
+        now?: number;
+    }): {
+        handled: boolean;
+        reason?: string;
+    };
+    /** Cancel all pending approvals (e.g. on shutdown). */
+    cancelAll(reason?: string): void;
+    /** Get count of pending approvals. */
+    get pendingCount(): number;
+    /**
+     * Drop an entry and disarm both of its timers.
+     *
+     * Both timers, always: leaving the reaper armed after a legitimate resolution
+     * would have it fire against a settled promise and record a stranding that
+     * never happened.
+     */
+    private forget;
+    /**
+     * The pending approval `(requestId, requesterId)` may address.
+     *
+     * The requester's own entry wins, so a duplicate id cannot make one of two
+     * requests unreachable to its own requester; the other entry is only reachable
+     * by its own requester too.
+     */
+    private findPending;
+    /** Pending approvals are few; a scan keeps the failure messages precise. */
+    private findByRequestId;
+}
+//# sourceMappingURL=manual-approval.d.ts.map

package/dist/esm/permissions/manual-approval.d.ts.map

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