import { StepUpQuorumLike } from "@kya-os/checkpoint-shared/policy/enforcement"; //#region src/step-up.d.ts /** * The policy decision the orchestrator branches on. Structural mirror of the * `@kya-os/mcp` `PolicyDecision` discriminated union, kept local so the core * takes no `@kya-os/mcp` dependency; the host's real `PolicyDecision` is * structurally assignable. `reason` is present on `deny`, `quorum` on `step_up`. */ export interface StepUpDecision { decision: 'allow' | 'deny' | 'step_up'; reason?: string; quorum?: StepUpQuorumLike; } /** Outcome of the injected approval-quorum check (mirrors `@kya-os/mcp` `QuorumResult`). */ export interface QuorumVerifyResult { satisfied: boolean; reason?: string; } /** * Injected: verify the presented grants satisfy the quorum, bound to * `requestHash` (TOCTOU defense). The gateway binds `@kya-os/mcp` * `verifyApprovalQuorum` with its own per-grant signature verifier (today a * deliberate reject-all kill switch, pending E3.2 / #2889). Required — there is * no default, so a missing injection is a type error, never an accidental * permissive pass. */ export type QuorumVerifier = (grants: TGrant[], requestHash: string, quorum: StepUpQuorumLike) => Promise; /** Minimal structural logger the host supplies; a pino instance satisfies it. */ export interface StepUpLogger { info(obj: object, msg?: string): void; warn(obj: object, msg?: string): void; } /** * Transport-neutral NEEDS_APPROVAL descriptor. The host maps it to its wire * error: the gateway feeds it to `@kya-os/mcp` `createNeedsApprovalError` * (→ JSON-RPC `-32008`); an edge runtime renders it as an HTTP response. The * field set matches `@kya-os/mcp`'s `createNeedsApprovalError` init so the * gateway can pass it straight through. */ export interface NeedsApprovalDescriptor { message: string; resumeToken: string; /** Unix seconds. */ expiresAt: number; requestHash: string; quorum: StepUpQuorumLike; } /** Everything {@link evaluateStepUp} needs for ONE tool call's enforce decision. */ export interface StepUpContext { /** The neutral policy decision (allow / deny / step_up) from the policy gate. */ decision: StepUpDecision; /** True when the gate faulted (the host's `PolicyGateResult.faulted`). */ faulted: boolean; /** SHA-256 of the suspended action's canonical (clean) args — host computes it. */ requestHash: string; /** Presented approval grants parsed from the stripped control envelope. */ grants: TGrant[]; /** Injected per-grant quorum verifier (TOCTOU-bound to `requestHash`). */ verifyQuorum: QuorumVerifier; /** Fields echoed verbatim into every emitted `policy.enforce.*` event * (the gateway passes `{ orgId, projectId, agentDid, tool }`). */ logContext?: Record; /** Optional structured logger; the six enforce events are emitted through it. */ log?: StepUpLogger; /** Builds the human NEEDS_APPROVAL message; the host owns the wire copy. */ buildMessage?: (quorum: StepUpQuorumLike, reason: string) => string; /** Seconds until the resume token expires (default 300, matching the gateway). */ approvalTtlSeconds?: number; } /** Tagged outcome the host maps to its transport. */ export type StepUpEvaluationResult = { status: 'allow'; } | { status: 'deny'; reason: string; } | { status: 'needs-approval'; needs: NeedsApprovalDescriptor; }; /** * Run the enforce-mode step-up gate for one tool call. Only called when the host * has already decided to ENFORCE. Pure: never throws on the live path; emits the * six `policy.enforce.*` events; runs {@link validateStepUpQuorum} (fail-closed) * BEFORE the verifier; and calls the injected `verifyQuorum`. * * Behavioral parity with the gateway's prior inline branch * (`apps/gateway/src/routes/mcp.ts`): fault → deny `policy_evaluation_failed`; * `deny` → deny with the engine reason; `step_up` → fail-closed quorum guard, * then quorum verify (TOCTOU-bound) → `needs-approval` when unmet, else allow. */ export declare function evaluateStepUp(ctx: StepUpContext): Promise; /** * Pending action awaiting an N-of-M approval quorum. `requestHash` is the * SHA-256 of the suspended action's canonical args, which both the agent's * resume token and every approver signature MUST bind to (TOCTOU defense). */ export interface PendingApproval { requestId: string; requestHash: string; quorum: StepUpQuorumLike; createdAt: number; expiresAt: number; } /** * Storage for pending approvals — write a pending record, read it back by id. * Quorum verification of the presented grants lives in the host's injected * verifier, not here; this store only tracks the action-binding state across * the suspend → resume gap. */ export interface ApprovalStore { recordPending(entry: PendingApproval): Promise; /** Returns the entry if present and not expired; otherwise null. */ getPending(requestId: string): Promise<{ requestHash: string; quorum: StepUpQuorumLike; expiresAt: number; } | null>; } /** * In-memory implementation. Single-pod, process-restart resets. Entries past * `expiresAt` are treated as absent at read time AND lazily evicted on the same * read (no background sweep — the suspend → resume window is bounded by the * NEEDS_APPROVAL `expiresAt`). */ export declare class InMemoryApprovalStore implements ApprovalStore { private readonly entries; recordPending(entry: PendingApproval): Promise; getPending(requestId: string): Promise<{ requestHash: string; quorum: StepUpQuorumLike; expiresAt: number; } | null>; } //#endregion //# sourceMappingURL=step-up.d.ts.map