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

package/dist/esm/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/esm/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/esm/execution/database-lookup.js

@@ -0,0 +1,38 @@
+/** Read the entry out of any accepted lookup result, or null. */
+export function resolvedEntry(result) {
+    if (result === null || result === undefined)
+        return null;
+    if (isLookupRefusal(result))
+        return null;
+    return 'entry' in result ? result.entry : result;
+}
+/** Whether a lookup result is a refusal rather than a hit. */
+export function isLookupRefusal(result) {
+    return (typeof result === 'object' &&
+        result !== null &&
+        'ok' in result &&
+        result.ok === false);
+}
+/**
+ * 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 function normaliseLookupResult(result, assertedProject, assertedAlias) {
+    if (result === null || result === undefined) {
+        return {
+            ok: false,
+            code: 'database_not_found',
+            reason: `No configured database matches project "${assertedProject}"`,
+            asserted_project: assertedProject,
+            asserted_db_alias: assertedAlias ?? '',
+        };
+    }
+    if (isLookupRefusal(result))
+        return result;
+    if ('entry' in result)
+        return result;
+    return { ok: true, entry: result };
+}
+//# sourceMappingURL=database-lookup.js.map

package/dist/esm/execution/database-lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-lookup.js","sourceRoot":"","sources":["../../../src/execution/database-lookup.ts"],"names":[],"mappings":"AAqDA,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,MAA6C;IACzE,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,eAAe,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;AACnD,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,eAAe,CAC7B,MAA6C;IAE7C,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,IAAI,IAAI,MAAM;QACb,MAA2B,CAAC,EAAE,KAAK,KAAK,CAC1C,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAA6C,EAC7C,eAAuB,EACvB,aAAiC;IAEjC,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC5C,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,oBAAoB;YAC1B,MAAM,EAAE,2CAA2C,eAAe,GAAG;YACrE,gBAAgB,EAAE,eAAe;YACjC,iBAAiB,EAAE,aAAa,IAAI,EAAE;SACvC,CAAC;IACJ,CAAC;IACD,IAAI,eAAe,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IAC3C,IAAI,OAAO,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IACrC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AACrC,CAAC"}

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