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

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