@paperclipai/server 2026.817.0 → 2026.818.0-beta.1

package/dist/services/setup-token-session.d.ts

@@ -0,0 +1,630 @@
+import type { Db } from "@paperclipai/db";
+/**
+ * The session states. The four terminal states end the login. The `stored`
+ * state is not terminal: a session enters `stored` after a successful
+ * owner-bound secret write, and the durable row then persists as a one-time
+ * claim. The create path consumes the claim, or the reaper removes the row after
+ * the deadline.
+ */
+export type SetupTokenSessionState = "starting" | "awaiting_code" | "submitting" | "stored" | "completed" | "failed" | "timed_out" | "cancelled";
+/** The four terminal states. Cleanup runs once when a session reaches one. */
+export declare const SETUP_TOKEN_TERMINAL_STATES: readonly SetupTokenSessionState[];
+export declare function isTerminalSessionState(state: SetupTokenSessionState): boolean;
+/**
+ * The immutable owner scope of a session. Every operation verifies all five
+ * fields against the stored scope. The service builds the scope once at start
+ * and never changes it.
+ *
+ * The `targetAgentId` is null for a company-and-environment login. That login
+ * has no agent id: a hire flow starts one session before an agent exists. The
+ * agent-scoped login sets `targetAgentId` to the agent id. The full-scope match
+ * treats null as one immutable value, so a company login and an agent login
+ * never resolve one another.
+ */
+export interface SetupTokenSessionScope {
+    companyId: string;
+    ownerUserId: string;
+    targetAgentId: string | null;
+    adapterType: string;
+    environmentId: string;
+    confirmedOverwrite?: {
+        expectedSecretId: string;
+        expectedLatestVersion: number;
+    } | null;
+}
+/** The terminal outcome of the live login process. */
+export type SetupTokenLoginOutcome = "success" | "failure" | "timeout" | "cancelled";
+/**
+ * The live login process the service drives for one session. A production
+ * factory binds this to the setup-token runner over a sandbox pseudo-terminal.
+ * A unit test binds it to a fake. The process holds the flow state in memory.
+ */
+export interface SetupTokenLoginProcess {
+    /** Resolves with the terminal outcome when the login process ends. */
+    readonly done: Promise<SetupTokenLoginOutcome>;
+    /**
+     * Forwards the one browser code to the live process. The service calls it one
+     * time, only after the single `awaiting_code` to `submitting` transition wins.
+     */
+    submitCode(code: string): void;
+    /**
+     * Stops the direct child process. The service calls it before it releases the
+     * lease. The method must be safe to call more than one time.
+     */
+    stop(): void;
+}
+/** The prompt sink the factory calls one time when it surfaces the sign-in URL. */
+export type SetupTokenPromptSink = (prompt: {
+    url: string;
+}) => void;
+/**
+ * The credential sink the factory calls one time when the login binds the minted
+ * token from the success record. The sink is asynchronous: it awaits the
+ * owner-bound secret write and rejects on a storage failure. The factory (or the
+ * runner it wraps) awaits this sink before it reports success, so a storage
+ * failure ends the login as a failure. The sink never logs the token and never
+ * returns it.
+ */
+export type SetupTokenCredentialSink = (token: string) => Promise<void>;
+/**
+ * The atomic credential-claim writer. The service awaits it one time with the
+ * minted token, the owner scope, and the durable session id. It runs one
+ * control-plane transaction that first transitions the exact durable row to
+ * `stored` with a full-scope conditional update, then performs the owner-bound
+ * secret compare-and-set on the same transaction handle. The commit establishes
+ * the encrypted secret and the `stored` claim together. It resolves on a
+ * successful commit. It rejects and rolls back the whole transaction on a
+ * zero-row transition or on a storage failure, so neither the secret nor the
+ * claim commits. The service holds the token only for this call; it never stores
+ * it.
+ */
+export type SetupTokenSecretWriter = (input: {
+    scope: SetupTokenSessionScope;
+    sessionId: string;
+    token: string;
+}) => Promise<void>;
+/**
+ * Builds the live login process for one session. The factory receives the
+ * prompt sink, the credential sink, the host timeout, and an abort signal that
+ * the service aborts on cancel and on expiry. The factory awaits the credential
+ * sink one time before it reports success.
+ */
+export type SetupTokenLoginProcessFactory = (params: {
+    scope: SetupTokenSessionScope;
+    onPrompt: SetupTokenPromptSink;
+    onCredential: SetupTokenCredentialSink;
+    timeoutMs: number;
+    signal: AbortSignal;
+}) => SetupTokenLoginProcess;
+/** An opaque sandbox lease handle. The service holds one per session. */
+export interface SetupTokenLease {
+    id: string;
+}
+/**
+ * Acquires and releases the sandbox lease for a login session. The production
+ * manager wraps the environment runtime. The service sets an external lease
+ * expiry no later than the session deadline through the `deadline` field.
+ */
+export interface SetupTokenLeaseManager {
+    acquire(input: {
+        scope: SetupTokenSessionScope;
+        deadline: number;
+    }): Promise<SetupTokenLease>;
+    release(lease: SetupTokenLease): Promise<void>;
+    /** Releases a lease by id. The startup reaper uses this after a restart. */
+    releaseById(leaseId: string): Promise<void>;
+}
+/**
+ * The non-secret cleanup record. It holds only ids, the deadline, the claim
+ * marker, and the state. It never holds a URL, a code, a token, or a raw process
+ * chunk. The service persists it at start so a restart can reap the
+ * lease. The record keys on the company, the owner, the adapter, and the
+ * environment, not the agent id, so a hire flow with no agent still resolves it.
+ */
+export interface SetupTokenCleanupRecord {
+    sessionId: string;
+    companyId: string;
+    ownerUserId: string;
+    adapterType: string;
+    environmentId: string;
+    leaseId: string;
+    deadline: number;
+    state: SetupTokenSessionState;
+    boundAt: number | null;
+}
+/**
+ * The immutable identity of a cleanup record. It is the full owner scope plus
+ * the session id. Every durable write matches on all five fields, so a write
+ * never updates a row by session id alone.
+ */
+export interface SetupTokenCleanupIdentity {
+    sessionId: string;
+    companyId: string;
+    ownerUserId: string;
+    adapterType: string;
+    environmentId: string;
+}
+/**
+ * The durable store for the non-secret cleanup record. A restart reads the
+ * store and reaps a lease whose session is terminal, past its deadline, or
+ * already consumed. The store persists no secret.
+ */
+export interface SetupTokenCleanupStore {
+    record(record: SetupTokenCleanupRecord): Promise<void>;
+    /**
+     * Marks the state only when the full owner scope and the session id match. The
+     * write never updates a row by the session id alone.
+     */
+    markState(identity: SetupTokenCleanupIdentity, state: SetupTokenSessionState): Promise<void>;
+    /**
+     * Deletes the record only when the full owner scope and the session id match.
+     * The delete never removes a row by the session id alone, so a cross-scope
+     * caller cannot delete a foreign row.
+     */
+    remove(identity: SetupTokenCleanupIdentity): Promise<void>;
+    /**
+     * Returns each record whose session is terminal, whose deadline is past, or
+     * whose claim is already consumed.
+     */
+    listReapable(now: number): Promise<SetupTokenCleanupRecord[]>;
+    /**
+     * Consumes a `stored` claim with one conditional write. The predicate carries
+     * the full owner scope, the session id, `state = stored`, an unexpired
+     * deadline that it checks with `clock_timestamp()`, and an unconsumed marker.
+     * The write sets `bound_at` one time and returns the row on a valid consume.
+     * It returns null for a missing, foreign-scope, expired, non-`stored`, or
+     * already-consumed claim. It never reads the state or the expiry in a separate
+     * step. The agent-service transaction calls this method.
+     */
+    consumeStoredClaim(identity: SetupTokenCleanupIdentity): Promise<SetupTokenCleanupRecord | null>;
+}
+/** A per-key start rate limiter. It matches the invite-rate-limit shape. */
+export interface SetupTokenRateLimiter {
+    consume(key: string): {
+        allowed: boolean;
+        retryAfterSeconds: number;
+    };
+}
+export interface SetupTokenSessionCaps {
+    perOwner: number;
+    perAgent: number;
+    perCompany: number;
+}
+export declare const DEFAULT_SETUP_TOKEN_SESSION_CAPS: SetupTokenSessionCaps;
+/** The default host timeout for one login session. */
+export declare const DEFAULT_SETUP_TOKEN_SESSION_TTL_MS: number;
+/**
+ * The default retention window for a completed token. The service releases the
+ * sandbox lease at once on success, but it keeps the token in memory for this
+ * window, so the authorized owner can receive it one time. A short window bounds
+ * how long the service holds the secret if the owner never receives it (SR-4).
+ */
+export declare const DEFAULT_SETUP_TOKEN_RETENTION_MS = 60000;
+export declare const SETUP_TOKEN_SESSION_NOT_FOUND = "Setup-token login session not found.";
+export declare const SETUP_TOKEN_SUBMIT_CONFLICT = "The setup-token login session cannot accept this code.";
+export declare const SETUP_TOKEN_RATE_LIMITED = "Too many setup-token login attempts. Try again later.";
+export declare const SETUP_TOKEN_CAP_EXCEEDED = "Too many active setup-token login sessions.";
+export declare const SETUP_TOKEN_TOKEN_UNAVAILABLE = "The setup-token is not available for this session.";
+export declare const SETUP_TOKEN_START_FAILED = "The setup-token login session could not start.";
+export declare const SETUP_TOKEN_PROVIDER_UNSUPPORTED = "The sandbox provider does not support the Claude setup-token login.";
+export declare const SETUP_TOKEN_PROVIDER_UNSUPPORTED_CODE = "setup_token_provider_unsupported";
+export declare const SETUP_TOKEN_STORAGE_FAILED = "The setup-token login could not store the credential.";
+/** A typed error the route maps to a fixed status and the fixed text above. */
+export declare class SetupTokenSessionError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Builds the sanitized login-URL form for every non-owner sink (SR-5). The
+ * function removes the query, the fragment, and the credentials, so no OAuth
+ * parameter and no secret reaches a log, an activity detail, an error, a trace,
+ * or client telemetry. It keeps the origin and the path for a useful diagnostic.
+ * It returns a fixed placeholder for a value it cannot parse, so it never falls
+ * back to the raw input.
+ */
+export declare function toSanitizedLoginUrl(rawUrl: string): string;
+/**
+ * The startup transport configuration for the confidential responses. The
+ * server resolves it once at startup. `trustedProxies` is the dedicated,
+ * explicit proxy IP or CIDR allowlist for the confidential routes. The global
+ * `TRUST_PROXY` setting does not appear here, so `TRUST_PROXY=true` and a
+ * hop-count value never satisfy the guard (SR-7).
+ */
+export interface ConfidentialTransportConfig {
+    deploymentMode: "local_trusted" | "authenticated";
+    trustedProxies: string[];
+    /**
+     * The explicit operator declaration that every client request reaches this
+     * server through a platform edge that terminates TLS (a managed PaaS such as
+     * Railway, Render, or Fly, where the app socket is always plain HTTP and the
+     * edge-proxy peer addresses are not operator-visible, so `trustedProxies`
+     * cannot express them). Unlike the global `TRUST_PROXY` setting, which the
+     * guard deliberately never reads (SR-7), this is a dedicated, single-purpose
+     * statement about the confidential login routes only. When declared, a
+     * request is confidential unless the edge itself labels the client hop as
+     * plain `http` in `X-Forwarded-Proto`. Defaults to false.
+     */
+    edgeTlsTerminated?: boolean;
+}
+/** The per-request transport signals the guard reads from the raw socket. */
+export interface ConfidentialTransportRequest {
+    /** The raw TLS bit on the immediate socket. It ignores `trust proxy`. */
+    socketEncrypted: boolean;
+    /** The immediate peer address. It ignores `trust proxy`. */
+    remoteAddress: string | undefined;
+    /** The `X-Forwarded-Proto` header value. The guard reads its first hop only. */
+    forwardedProto: string | undefined;
+}
+export interface ConfidentialTransportDecision {
+    allowed: boolean;
+    reason: string;
+}
+/**
+ * Decides whether the request may receive a confidential response (the full
+ * login URL or the token). The guard fails closed. It never trusts a
+ * client-supplied header for the TLS decision unless the immediate peer is on
+ * the dedicated proxy allowlist. It never reads the global `trust proxy`
+ * setting.
+ *
+ * The guard allows a confidential response only in these cases:
+ *   1. The immediate socket is TLS. A direct TLS request is always valid (SR-6).
+ *   2. The deployment is `local_trusted` and the peer is loopback. This is the
+ *      only local exception (SR-6).
+ *   3. The operator declared platform edge TLS termination
+ *      (`edgeTlsTerminated`) and the edge does not label the client hop as
+ *      plain `http`. The declaration is a deliberate, single-purpose operator
+ *      statement about these routes; it is never derived from `TRUST_PROXY`
+ *      (SR-7).
+ *   4. The peer is on the dedicated proxy allowlist and the forwarded protocol's
+ *      first hop is `https`. A `TRUST_PROXY=true` or hop-count value does not
+ *      reach this branch, because the guard never reads it (SR-7).
+ *
+ * Every other request fails closed and the route returns the fixed no-secret
+ * error.
+ */
+export declare function evaluateConfidentialTransport(config: ConfidentialTransportConfig, request: ConfidentialTransportRequest): ConfidentialTransportDecision;
+/**
+ * Assesses the confidential transport at startup (SR-7). The server disables
+ * proxy-forwarded confidential responses when the dedicated allowlist is empty
+ * and the operator has not declared platform edge TLS termination.
+ * A direct TLS request and a `local_trusted` loopback request still pass at
+ * runtime, because the runtime guard checks them first. The server logs the
+ * returned reason so an operator can see why forwarded requests fail closed.
+ */
+export declare function assessConfidentialStartup(config: ConfidentialTransportConfig): {
+    proxyForwardingEnabled: boolean;
+    reason: string;
+};
+/** The public read view of a session prompt. */
+export interface SetupTokenPromptView {
+    state: SetupTokenSessionState;
+    /** The full login URL, present only when the prompt has surfaced (SR-5). */
+    loginUrl: string | null;
+}
+/**
+ * The owner descriptor of a session. The company-and-environment routes read it
+ * to build the response contract. It carries the immutable environment and the
+ * session deadline, plus the current state and the full login URL. The route
+ * projects it: the public status response drops the login URL; the owner prompt
+ * response returns the login URL through the confidential transport guard.
+ */
+export interface SetupTokenSessionDescriptor {
+    sessionId: string;
+    state: SetupTokenSessionState;
+    environmentId: string;
+    /** The session deadline in epoch milliseconds. */
+    deadline: number;
+    /** The full login URL, present only after the prompt surfaces. */
+    loginUrl: string | null;
+}
+/**
+ * The completion contract for the authorized owner. It carries the non-secret
+ * `storedSessionId` claim and no token. The `storedSessionId` is the
+ * durable session id; the agent-create transaction consumes it as the one-time
+ * stored-session claim.
+ */
+export interface SetupTokenCompletionView {
+    storedSessionId: string;
+}
+export interface SetupTokenSessionServiceOptions {
+    factory: SetupTokenLoginProcessFactory;
+    leases: SetupTokenLeaseManager;
+    store: SetupTokenCleanupStore;
+    /**
+     * The owner-bound secret writer. The service awaits it one time when the login
+     * binds the token. It performs the compare-and-set. The service fails
+     * closed on a rejection.
+     */
+    completeCredential: SetupTokenSecretWriter;
+    rateLimiter: SetupTokenRateLimiter;
+    caps?: SetupTokenSessionCaps;
+    ttlMs?: number;
+    /** The retention window for a completed token. Defaults to the constant. */
+    tokenRetentionMs?: number;
+    now?: () => number;
+    /** Returns an opaque, cryptographically random session id. */
+    generateSessionId?: () => string;
+    /** A non-leaking diagnostic sink. It receives only fixed status lines. */
+    log?: (line: string) => void;
+}
+/**
+ * The setup-token login session service. It holds every live session in memory
+ * and persists a non-secret cleanup record for each. It bounds active sessions
+ * per owner, per agent, and per company, and it rate-limits the start path.
+ */
+export declare class SetupTokenSessionService {
+    private readonly sessions;
+    private readonly reservedByOwner;
+    private readonly reservedByAgent;
+    private readonly reservedByCompany;
+    private readonly factory;
+    private readonly leases;
+    private readonly store;
+    private readonly completeCredential;
+    private readonly rateLimiter;
+    private readonly caps;
+    private readonly ttlMs;
+    private readonly tokenRetentionMs;
+    private readonly now;
+    private readonly generateSessionId;
+    private readonly log;
+    constructor(options: SetupTokenSessionServiceOptions);
+    /**
+     * Builds the durable-record identity for a session. The store matches every
+     * write on the full owner scope and the session id, so no write updates a row
+     * by the session id alone.
+     */
+    private identityOf;
+    /**
+     * Runs `fn` under the per-session lock. The lock serializes the owner-bound
+     * secret write against a cancel, an expiry, and the process-done transition, so
+     * a terminal transition and the write never interleave (complete mediation).
+     * The caller inside `fn` must not call another locked method, or it deadlocks;
+     * the failure path of {@link onCredential} calls {@link terminateLocked}, the
+     * lock-free variant, for this reason.
+     */
+    private withSessionLock;
+    private countActive;
+    private static incrementCount;
+    private static decrementCount;
+    /**
+     * Reserves the capacity for one start under every enforced cap. The method is
+     * synchronous, so it runs to completion before the first `await` in
+     * {@link start}. Two concurrent starts for one owner cannot interleave inside
+     * it: the first reserves the owner slot, and the second reads the incremented
+     * count and fails closed with the fixed 429 cap error. The method holds the
+     * per-owner, per-agent, and per-company semantics: it counts the agent slot
+     * only for an agent-scoped login, because a null agent id is not a shared key
+     * across owners. It increments no counter on a rejection, so a rejected start
+     * reserves nothing.
+     */
+    private reserveCapacity;
+    /**
+     * Releases a capacity reservation exactly one time. The `released` flag makes
+     * the release idempotent, so an early start failure and the terminal cleanup
+     * never double-release one reservation. The method decrements the same counters
+     * that {@link reserveCapacity} incremented, and it drops the agent counter only
+     * for an agent-scoped login.
+     */
+    private releaseReservation;
+    /**
+     * Starts a login session. It rate-limits the start, enforces the caps,
+     * acquires the lease with an external expiry no later than the deadline,
+     * persists the non-secret cleanup record, and starts the one live process.
+     * It returns the opaque session id and no token.
+     */
+    start(scope: SetupTokenSessionScope): Promise<{
+        sessionId: string;
+        state: SetupTokenSessionState;
+    }>;
+    private onPrompt;
+    /**
+     * Receives the minted token from the login process and writes it to the
+     * owner-bound secret. The service awaits the compare-and-set. The
+     * service never stores the token: it passes the token to the writer, then it
+     * drops the reference.
+     *
+     * The service runs the whole sink under the per-session lock, so a cancel or an
+     * expiry cannot interleave with the write. A cancel or an expiry that wins the
+     * lock first sets a terminal state; the service then writes no secret and fails
+     * closed with the fixed, non-secret error. This is complete mediation: a
+     * terminal session never commits a secret write.
+     *
+     * The writer runs one control-plane transaction. Inside it, the writer first
+     * transitions the exact durable row to `stored` with a full-scope conditional
+     * update, then writes or rotates the secret on the same transaction handle. The
+     * commit establishes the encrypted secret and the `stored` claim together, so a
+     * crash between the two steps cannot leave a stored token with no valid claim.
+     * The service does not mark the durable row separately; the writer owns the
+     * transition.
+     *
+     * On a successful write the service records the non-secret `secretStored`
+     * marker. The process outcome then moves the session to `completed`. A cancel or
+     * an expiry that arrives after the write committed sees the `secretStored`
+     * marker and reports the completed state; it does not erase the claim (see
+     * {@link terminateLocked}).
+     *
+     * On a zero-row transition or on a storage failure the writer rolls back the
+     * whole transaction and rejects. The service then fails closed: it moves the
+     * session to `failed`, keeps no secret and no claim, and rejects with a fixed,
+     * non-secret error. The factory (or the runner it wraps) awaits this sink, so
+     * the rejection ends the login as a failure and the process never reports
+     * success.
+     */
+    private onCredential;
+    /**
+     * Resolves a session for an operation. It returns the session only when the
+     * id exists and the stored scope equals the caller scope in all five fields:
+     * the company, the owner, the agent, the adapter, and the environment. A
+     * missing session and a cross-scope session both throw the same not-found
+     * error, so a caller cannot tell them apart. The full-scope match makes
+     * a cross-adapter and a cross-environment session return the same not-found
+     * error as a missing session.
+     */
+    private resolveOwned;
+    /**
+     * Resolves the immutable scope of a company-and-environment session. The
+     * caller provides the company, the owner, and the adapter it derived from the
+     * request; the route path gives the company, the actor gives the owner, and
+     * the route fixes the adapter. The lookup matches these three fields and the
+     * agentless marker, then returns the full scope, including the intrinsic
+     * environment.
+     *
+     * A caller never supplies the environment on a read, a submit, a cancel, or a
+     * completion. The environment is intrinsic to the session, so a foreign
+     * environment cannot address the session. A missing session and a
+     * cross-company, cross-owner, or cross-adapter session all throw the same
+     * not-found error. The agentless marker rejects an
+     * agent-scoped session, so a company route never resolves an agent session.
+     */
+    resolveCompanyScope(sessionId: string, key: {
+        companyId: string;
+        ownerUserId: string;
+        adapterType: string;
+    }): SetupTokenSessionScope;
+    /**
+     * Returns the owner descriptor for a session. The company-and-environment
+     * routes read it to build the response contract. The scope check runs first,
+     * so a cross-scope caller gets the same not-found error. The route
+     * projects the descriptor: the public status response drops the login URL; the
+     * owner prompt response returns the login URL behind the transport guard.
+     */
+    describeOwned(sessionId: string, scope: SetupTokenSessionScope): SetupTokenSessionDescriptor;
+    /**
+     * Returns the prompt view for the authorized owner. The full login URL rides
+     * only in this response (SR-5). The route sets `Cache-Control: no-store` and
+     * applies the confidential transport guard before it calls this method.
+     */
+    readPrompt(sessionId: string, scope: SetupTokenSessionScope): SetupTokenPromptView;
+    /**
+     * Submits the one browser code. It performs the single compare-and-set from
+     * `awaiting_code` to `submitting`, then forwards the code to the live process
+     * one time. It rejects every later submit, including one after an
+     * invalid-code retry (SR-3).
+     */
+    submitCode(sessionId: string, scope: SetupTokenSessionScope, code: string): {
+        state: SetupTokenSessionState;
+    };
+    /**
+     * Cancels a session. It stops the direct child before it releases the lease.
+     * It is idempotent: a cancel on a terminal session returns the terminal state.
+     */
+    cancel(sessionId: string, scope: SetupTokenSessionScope): Promise<{
+        state: SetupTokenSessionState;
+    }>;
+    /**
+     * Expires a session on a timeout. It stops the direct child before it releases
+     * the lease. The harness can call it, and the deadline timer calls the same
+     * path internally.
+     */
+    expire(sessionId: string, scope: SetupTokenSessionScope): Promise<{
+        state: SetupTokenSessionState;
+    }>;
+    private expireInternal;
+    /**
+     * Returns the completion contract for the authorized owner. It returns the
+     * non-secret `storedSessionId` claim only from a completed session whose
+     * owner-bound secret write succeeded. It returns no token. It
+     * returns the fixed unavailable error when the session is not completed with a
+     * stored secret. The scope check runs first, so a cross-scope caller gets the
+     * same not-found error, not the unavailable error.
+     *
+     * The read leaves the durable row in place as the one-time stored-session
+     * claim; the agent-create transaction consumes it. The route sets
+     * `Cache-Control: no-store` before it calls this method.
+     */
+    completeSession(sessionId: string, scope: SetupTokenSessionScope): SetupTokenCompletionView;
+    /**
+     * Stops the direct child, then runs the idempotent cleanup under the
+     * per-session lock. The lock serializes the terminal transition against the
+     * owner-bound secret write, so a cancel or an expiry never interleaves with the
+     * write (complete mediation). The order stops the child before the lease
+     * release on every terminal path.
+     */
+    private terminate;
+    /**
+     * The lock-free terminal transition. The caller must already hold the
+     * per-session lock. The failure path of {@link onCredential} calls it directly,
+     * because that path already holds the lock.
+     *
+     * If the owner-bound secret write already committed, the delivery won the
+     * serialized ordering. The service completes the session and keeps the stored
+     * claim; it does not cancel, expire, or erase the claim. This makes the
+     * terminal API report the completed state after a successful write, rather than
+     * erase it.
+     */
+    private terminateLocked;
+    /**
+     * Maps the live process outcome to the terminal state and runs the cleanup
+     * under the per-session lock. A cancel or an expire already set the state, so
+     * this call is a no-op then.
+     */
+    private onProcessDone;
+    /**
+     * Runs the idempotent cleanup for a terminal session: clear the timer, mark
+     * the durable record terminal, release the lease, and drop the in-memory
+     * session. It clears the in-memory login URL reference promptly (SR-3, SR-5).
+     * A cleanup failure stays retryable and records no process output (SR-4).
+     *
+     * A completed session with a stored secret keeps its durable row as the
+     * one-time stored-session claim: the cleanup marks no terminal state and does
+     * not remove the row. The agent-create transaction consumes the claim, or the
+     * reaper removes the row after the deadline. The cleanup still releases the
+     * sandbox lease at once. It retains the in-memory session for the retention
+     * window, so the owner can read the completion once.
+     */
+    private runCleanup;
+    /**
+     * Purges a retained completed session from memory. It clears the retention
+     * timer and drops the in-memory session. The durable stored-session claim
+     * stays in the store for the create flow or the reaper.
+     */
+    private purgeRetained;
+    private releaseLeaseSafely;
+    /**
+     * The startup reaper. It reads the durable store and releases any lease whose
+     * session is terminal or past its deadline. It runs after a restart, so it
+     * frees a lease that a crash left behind (SR-4). A release failure stays
+     * retryable: the reaper leaves the record for a later run.
+     */
+    reap(now?: number): Promise<{
+        released: number;
+        failed: number;
+    }>;
+    /**
+     * The graceful-shutdown cleanup. It cancels every live session, so the server
+     * stops each direct child before it releases each lease (SR-4).
+     */
+    shutdown(): Promise<void>;
+    /** Returns the count of live sessions. The route and the tests use it. */
+    activeSessionCount(): number;
+}
+/**
+ * The live pre-`stored` states a session may hold when the credential arrives.
+ * The atomic claim writer transitions a row to `stored` only from one of these
+ * states. It never transitions a terminal, an already-`stored`, or a foreign row.
+ */
+export declare const SETUP_TOKEN_STORED_PREDECESSOR_STATES: readonly SetupTokenSessionState[];
+/**
+ * Transitions the exact session row to `stored` with one conditional update. The
+ * predicate matches the full owner scope and the session id, an allowed
+ * predecessor state, an unexpired deadline against `clock_timestamp()`, and an
+ * unconsumed `bound_at`. It uses `UPDATE … RETURNING` and returns true only when
+ * exactly one row transitions.
+ *
+ * The atomic claim writer runs this update on the same transaction handle as the
+ * secret write, so the commit establishes the `stored` claim and the encrypted
+ * secret together. A zero-row result rolls back the whole transaction, so a
+ * stale, expired, terminal, foreign-scope, or already-bound row writes no
+ * secret.
+ */
+export declare function transitionSetupTokenSessionToStored(executor: Db, identity: SetupTokenCleanupIdentity): Promise<boolean>;
+/**
+ * Builds the durable, database-backed cleanup store. It persists only the
+ * non-secret record. Every write matches the full owner scope and the session
+ * id, so no write updates a row by the session id alone. The
+ * claim-consumption write folds the state check, the deadline check, and the
+ * consumption into one conditional write.
+ */
+export declare function createDbSetupTokenCleanupStore(db: Db): SetupTokenCleanupStore;
+//# sourceMappingURL=setup-token-session.d.ts.map

package/dist/services/setup-token-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-token-session.d.ts","sourceRoot":"","sources":["../../src/services/setup-token-session.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AAI1C;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,GAC9B,UAAU,GACV,eAAe,GACf,YAAY,GACZ,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,WAAW,GACX,WAAW,CAAC;AAEhB,8EAA8E;AAC9E,eAAO,MAAM,2BAA2B,EAAE,SAAS,sBAAsB,EAKxE,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAE7E;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAI7B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IAMtB,kBAAkB,CAAC,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAC;QAAC,qBAAqB,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACzF;AAED,sDAAsD;AACtD,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;AAErF;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/C;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;OAGG;IACH,IAAI,IAAI,IAAI,CAAC;CACd;AAED,mFAAmF;AACnF,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAExE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE;IAC3C,KAAK,EAAE,sBAAsB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,MAAM,EAAE;IACnD,KAAK,EAAE,sBAAsB,CAAC;IAC9B,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,YAAY,EAAE,wBAAwB,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,CAAC;CACrB,KAAK,sBAAsB,CAAC;AAE7B,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,sBAAsB,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9F,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,4EAA4E;IAC5E,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,sBAAsB,CAAC;IAG9B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,yBAAyB,EAAE,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7F;;;;OAIG;IACH,MAAM,CAAC,QAAQ,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D;;;OAGG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAC9D;;;;;;;;OAQG;IACH,kBAAkB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAC;CAClG;AAED,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,CAAC;CACvE;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,gCAAgC,EAAE,qBAI9C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,kCAAkC,QAAa,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAKvD,eAAO,MAAM,6BAA6B,yCAAyC,CAAC;AACpF,eAAO,MAAM,2BAA2B,2DAA2D,CAAC;AACpG,eAAO,MAAM,wBAAwB,0DAA0D,CAAC;AAChG,eAAO,MAAM,wBAAwB,gDAAgD,CAAC;AAGtF,eAAO,MAAM,6BAA6B,uDAAuD,CAAC;AAClG,eAAO,MAAM,wBAAwB,mDAAmD,CAAC;AAMzF,eAAO,MAAM,gCAAgC,wEAC0B,CAAC;AACxE,eAAO,MAAM,qCAAqC,qCAAqC,CAAC;AAGxF,eAAO,MAAM,0BAA0B,0DAA0D,CAAC;AAElG,+EAA+E;AAC/E,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK5C;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAW1D;AAID;;;;;;GAMG;AACH,MAAM,WAAW,2BAA2B;IAC1C,cAAc,EAAE,eAAe,GAAG,eAAe,CAAC;IAClD,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,6EAA6E;AAC7E,MAAM,WAAW,4BAA4B;IAC3C,yEAAyE;IACzE,eAAe,EAAE,OAAO,CAAC;IACzB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,gFAAgF;IAChF,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAqED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,2BAA2B,EACnC,OAAO,EAAE,4BAA4B,GACpC,6BAA6B,CAyB/B;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,2BAA2B,GAAG;IAC9E,sBAAsB,EAAE,OAAO,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB,CAcA;AAmDD,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,sBAAsB,CAAC;IAC9B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,sBAAsB,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,6BAA6B,CAAC;IACvC,MAAM,EAAE,sBAAsB,CAAC;IAC/B,KAAK,EAAE,sBAAsB,CAAC;IAC9B;;;;OAIG;IACH,kBAAkB,EAAE,sBAAsB,CAAC;IAC3C,WAAW,EAAE,qBAAqB,CAAC;IACnC,IAAI,CAAC,EAAE,qBAAqB,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,MAAM,MAAM,CAAC;IACjC,0EAA0E;IAC1E,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAMD;;;;GAIG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAI7D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAC7D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAC7D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAC/C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyB;IAC5D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;IACpD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwB;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAe;IACjD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAyB;gBAEjC,OAAO,EAAE,+BAA+B;IAcpD;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAUlB;;;;;;;OAOG;YACW,eAAe;IAc7B,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,MAAM,CAAC,cAAc;IAI7B,OAAO,CAAC,MAAM,CAAC,cAAc;IAS7B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,eAAe;IA0BvB;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;;;;OAKG;IACG,KAAK,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,sBAAsB,CAAA;KAAE,CAAC;IA4GzG,OAAO,CAAC,QAAQ;IAUhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;YACW,YAAY;IAwB1B;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAepB;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CACjB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GACnE,sBAAsB;IAczB;;;;;;OAMG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,GAAG,2BAA2B;IAW5F;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,GAAG,oBAAoB;IAKlF;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,sBAAsB,CAAA;KAAE;IAW7G;;;OAGG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,sBAAsB,CAAA;KAAE,CAAC;IAS1G;;;;OAIG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,sBAAsB,CAAA;KAAE,CAAC;YAS5F,cAAc;IAM5B;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,GAAG,wBAAwB;IAQ3F;;;;;;OAMG;YACW,SAAS;IAIvB;;;;;;;;;;OAUG;YACW,eAAe;IAa7B;;;;OAIG;YACW,aAAa;IAkB3B;;;;;;;;;;;;OAYG;YACW,UAAU;IAqCxB;;;;OAIG;IACH,OAAO,CAAC,aAAa;YAUP,kBAAkB;IAUhC;;;;;OAKG;IACG,IAAI,CAAC,GAAG,GAAE,MAAmB,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAuBnF;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAO/B,0EAA0E;IAC1E,kBAAkB,IAAI,MAAM;CAG7B;AAmCD;;;;GAIG;AACH,eAAO,MAAM,qCAAqC,EAAE,SAAS,sBAAsB,EAIlF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAsB,mCAAmC,CACvD,QAAQ,EAAE,EAAE,EACZ,QAAQ,EAAE,yBAAyB,GAClC,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,EAAE,GAAG,sBAAsB,CAyE7E"}