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

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

package/dist/types/permissions/plan-registry.d.ts

@@ -0,0 +1,274 @@
+import { Role } from '../protocol/envelope';
+import { PermissionLevel, PlanConsumeRefusal, PlanRegistrationRefusal } from './types';
+export interface RegisteredPlan {
+    plan_id: string;
+    /** Hash of the statements (for matching). */
+    statements_hash: string;
+    /** How many statements were registered. Each must be exactly one statement. */
+    statement_count: number;
+    /** When the plan was registered (epoch ms). */
+    registered_at: number;
+    /** When the plan expires (epoch ms). Default 5 min. */
+    expires_at: number;
+    /** The user_id who registered it (for audit). */
+    registered_by: string;
+    /**
+     * The project the plan was registered against, as the **resolved** database
+     * entry's `project_name` — never the frame's claim.
+     *
+     * every other authority a plan carries (identity, role, permission
+     * level) was bound to the registration, and the database was not. A statement
+     * set reviewed and approved against a development database therefore executed
+     * unchanged against production. Required: a registration that cannot name its
+     * database is refused rather than stored unbound.
+     */
+    project: string;
+    /** The resolved `db_alias` of the entry the plan was registered against. */
+    db_alias: string;
+    /**
+     * The role the registrant held at registration time.
+     *
+     * `null` means the caller did not attest a principal. Such a plan is
+     * unattested: it may only ever be executed by the user id that registered it
+     * (no escalation from a more privileged role, because the registrant role is
+     * unknown) and its permission level is not bound at all. The dispatcher must
+     * pass the principal; see `register()`.
+     */
+    registered_by_role: Role | null;
+    /**
+     * The permission level in force when the plan was registered.
+     *
+     * `null` for an unattested plan. A recorded level is a floor on execution: a
+     * plan registered while the database was at `full` may not be executed at
+     * `auto_upgrade`, where no human ever saw it.
+     */
+    registered_permission_level: PermissionLevel | null;
+    /** Optional: risk level (low/medium/high) — browser computes this. */
+    risk_level?: 'low' | 'medium' | 'high';
+}
+/** The principal on whose authority a plan is registered. */
+export interface PlanPrincipal {
+    user_id: string;
+    role: Role;
+    permission_level: PermissionLevel;
+    /**
+     * The resolved database the plan is registered against. Both parts are
+     * required: `consume()`/`assertExecutionScope()` compare them to the frame's
+     * resolved entry, and a plan that cannot be compared is a plan that could
+     * execute anywhere.
+     */
+    project?: string;
+    db_alias?: string;
+}
+/**
+ * The database a plan execution is being evaluated for, as the resolved entry.
+ */
+export interface PlanExecutionScope {
+    project: string;
+    db_alias: string;
+}
+export interface PlanRegistryOptions {
+    /** How long plans stay valid. Default 300_000 (5 min). */
+    ttlMs?: number;
+    /** Max plans in registry (LRU eviction). Default 100. */
+    maxPlans?: number;
+}
+/** Outcome of a registration attempt. Refusals are decisions, not exceptions. */
+export type RegisterResult = {
+    ok: true;
+    plan: RegisteredPlan;
+} | {
+    ok: false;
+    code: PlanRegistrationRefusal;
+    reason: string;
+};
+/**
+ * Outcome of consuming a plan for execution.
+ *
+ * A consumption is the *only* decision that hands out execution authority, so
+ * it is a single synchronous step: validate, authorise, destroy. See
+ * `PlanRegistry.consume()`.
+ */
+export type ConsumeResult = {
+    ok: true;
+    plan: RegisteredPlan;
+} | {
+    ok: false;
+    code: PlanConsumeRefusal;
+    reason: string;
+};
+/**
+ * In-memory registry of single-use migration plans, keyed by plan id.
+ *
+ * Every question about a plan is asked about **one** id: `validate()` to inspect,
+ * `consume()` to decide and hand out authority, `unregister()` for administrative
+ * removal. There is deliberately no "list every live plan" accessor — it had no
+ * production caller, and an enumeration API over live plan ids invites exactly the
+ * probing that the single-id refusals are written to prevent (finding M-22). Do
+ * not reintroduce one for debugging: log the id you are about to look up.
+ */
+export declare class PlanRegistry {
+    private plans;
+    /**
+     * Tombstones of plans that were consumed, oldest first.
+     *
+     * Without them a consumed plan is indistinguishable from one that was never
+     * registered, so a replay attempt reads as a typo. They carry the id and the
+     * consumption time only — no statements, no user id, no role — so a refusal
+     * built from them says "this id was already spent" and nothing about any
+     * other plan. Bounded to `maxPlans` entries.
+     */
+    private consumed;
+    private readonly opts;
+    constructor(opts?: PlanRegistryOptions);
+    /**
+     * Whether this principal may register a migration plan at all.
+     *
+     * This is the source of truth for the `plan_register` entry gate so the
+     * dispatcher and the registry cannot disagree:
+     *   - `read_only` never registers plans; there is nothing to approve a
+     *     write against.
+     *   - a role without the `migration_run` capability never registers plans.
+     */
+    canRegister(role: Role, permissionLevel: PermissionLevel): {
+        allowed: boolean;
+        code?: PlanRegistrationRefusal;
+        reason?: string;
+    };
+    /**
+     * Register a migration plan on behalf of `principal`.
+     *
+     * Registration is an authorization event, so the plan records WHO registered
+     * it, WITH WHAT ROLE, and AT WHAT PERMISSION LEVEL. Without all three the
+     * registry is a self-attesting allow-list: the same untrusted principal
+     * registers the plan and runs it, and a statement-hash match proves nothing.
+     *
+     * `principal` is optional only so the record can distinguish "no principal
+     * attested" from "no principal": an unattested plan is stored but is
+     * restricted to its registrant and carries no permission-level floor. Callers
+     * must pass it.
+     */
+    register(planId: string, statements: string[], registeredBy: string, riskLevel?: 'low' | 'medium' | 'high', principal?: PlanPrincipal): RegisterResult;
+    /**
+     * Look up a live plan, distinguishing "never registered" from "already
+     * consumed".
+     *
+     * Both refusals are about this id only: neither mentions another plan, a
+     * user, a role or a statement, so probing for someone else's plan id tells
+     * the prober nothing beyond "no such plan".
+     */
+    private lookup;
+    /**
+     * Check if a plan is valid (exists, not expired, statements match).
+     *
+     * This does NOT consume the plan and does NOT check who is asking, so it is
+     * an inspection helper only. Anything about to execute a plan must call
+     * `consume()`, which is the single atomic hand-off of authority.
+     */
+    validate(planId: string, statements: string[]): {
+        valid: boolean;
+        reason?: string;
+        plan?: RegisteredPlan;
+    };
+    /**
+     * Validate, authorise and destroy `planId` in one synchronous step.
+     *
+     * `check()` in the permission pipeline is async, so authority must not be
+     * handed out by a `validate()` … `unregister()` pair: that sequence is only
+     * single-use by accident of the current call graph, and any `await` added
+     * between the two turns it into a replay of the same plan. Here the plan
+     * leaves the map in the same synchronous step that grants it, so a second
+     * caller — whatever it interleaved at — sees a tombstone and is refused.
+     *
+     * A refused attempt does NOT burn the plan: an unauthorised runner must not
+     * be able to invalidate somebody else's registration by trying it. Expiry is
+     * the only other way a plan leaves the map.
+     */
+    consume(planId: string, statements: string[], runner: {
+        user_id: string;
+        role: Role;
+        permission_level: PermissionLevel;
+        scope?: PlanExecutionScope;
+    }): ConsumeResult;
+    /**
+     * Inspect a plan without consuming it and check only its database binding.
+     *
+     * The dispatcher calls this before the permission pipeline runs, because the
+     * registry cannot see the frame on its own: `AutoUpgradeChecker` (which owns
+     * the `consume()` call) receives an `ActionRequest` and today forwards only
+     * the principal. Comparing here means the check cannot be skipped by a code
+     * path that reaches `consume()` some other way — and a plan id that is not
+     * registered at all passes, because a `migration_run` at `full` legitimately
+     * needs no plan.
+     *
+     * A refused attempt does NOT burn the plan: an out-of-scope runner must not be
+     * able to invalidate somebody else's registration.
+     */
+    assertExecutionScope(planId: string, scope: PlanExecutionScope): {
+        ok: true;
+    } | {
+        ok: false;
+        code: 'plan_scope_mismatch';
+        reason: string;
+    };
+    /**
+     * Whether `runner` may execute `plan`.
+     *
+     * Four independent conditions, all fail-closed:
+     *   0. The runner's resolved database must equal the one the plan was
+     *      registered against. See {@link assertPlanScope}; enforced by
+     *      `consume()` when the runner supplies a scope and by
+     *      {@link assertExecutionScope} on the request path.
+     *   1. The runner's role must be at least as privileged as the role the plan
+     *      was registered under. Authority is not retained across a demotion: a
+     *      plan registered by an `admin` is admin authority even when the same
+     *      user id now presents a weaker role.
+     *   2. The runner must be the registering principal, or hold a STRICTLY more
+     *      privileged role. An admin may run a developer's plan; a peer may not
+     *      run another peer's, because the plan is authority exercised at the
+     *      registrant's level.
+     *   3. The plan may only be executed at a permission level at least as
+     *      permissive as the one it was registered under, so a plan that needed
+     *      no human at `full` cannot be executed unattended at `auto_upgrade`.
+     *
+     * An unattested plan (no role or level recorded) may only be executed by the
+     * user that registered it.
+     */
+    mayExecutePlan(plan: RegisteredPlan, runner: {
+        user_id: string;
+        role: Role;
+        permission_level: PermissionLevel;
+        scope?: PlanExecutionScope;
+    }): {
+        allowed: boolean;
+        reason?: string;
+    };
+    /**
+     * Remove a plan (after migration runs or fails).
+     *
+     * This is administrative removal, not a consumption: no tombstone is left,
+     * so a later use of the id is reported as unknown rather than as a replay.
+     * `consume()` is what a migration run must use.
+     */
+    unregister(planId: string): void;
+    /**
+     * Drop plans whose TTL has elapsed. Called on the registration path, so an
+     * expired plan never occupies a slot or survives until process exit.
+     *
+     * Expiry is `expires_at = registered_at + ttlMs`, so a plan registered
+     * moments ago has `expires_at` five minutes in the future and can never be
+     * swept by this. Nothing here decides authorisation.
+     */
+    purgeExpired(): number;
+    /** Record a consumption as a tombstone, bounded to `maxPlans` entries. */
+    private rememberConsumed;
+    /**
+     * Compute a stable hash of statements.
+     *
+     * Whitespace is collapsed and case folded so the comparison cannot be
+     * defeated by re-spacing, and the entries are length-delimited so
+     * `['A','BC']` and `['AB','C']` cannot collide.
+     */
+    private hashStatements;
+}
+//# sourceMappingURL=plan-registry.d.ts.map

package/dist/types/permissions/plan-registry.d.ts.map

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