run402-mcp/sdk/core-dist/control-plane-session.d.ts

MCP server for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.

/**
 * The cached **sign-in session** — a person's one Run402 session, bound to
 * their principal and graded by how it was minted: `loopback` (`run402 login`,
 * the loopback-PKCE browser ceremony; full, step-up-able) or `device`
 * (`run402 login --device`, RFC 8628; read-only — the gateway refuses every
 * mutation with `SESSION_READ_ONLY`). The wire token class is
 * `control_plane_session`. The session authorizes most control-plane writes,
 * but provisioning, deploying, and writing secrets additionally need a
 * passkey-signed **write approval** (`X-Run402-Write-Approval`, minted by
 * `run402 approve`; see `write-approvals.ts`). Cached at the BASE config dir
 * (principal-scoped, shared across local named wallets), mode 0600 — the token
 * is as sensitive as the wallet key.
 *
 * Stored shape vs the gateway payload: the gateway returns a relative
 * `expires_in` (seconds); we persist the absolute `expires_at` (epoch ms) so a
 * cached session can be expiry-checked without knowing when it was written.
 */
/** How a sign-in session was minted, as the gateway reports it. */
export type SessionGrade = "browser" | "loopback" | "device";
export interface ControlPlaneSessionCache {
    control_plane_session_token: string;
    token_type: string;
    grade: SessionGrade;
    principal_id: string;
    amr: string[];
    /** Epoch ms when the session expires (issued_at + expires_in). */
    expires_at: number;
}
/**
 * The token payload returned by `POST /agent/v1/control-plane/cli/token`
 * (grade `loopback`) and `POST /agent/v1/control-plane/cli/device/token`
 * (grade `device`).
 */
export interface ControlPlaneSessionTokenResponse {
    control_plane_session_token: string;
    token_type?: string;
    grade?: string;
    principal_id?: string;
    amr?: string[];
    expires_in?: number;
}
/**
 * Path to the cached control-plane session: `{base}/control-plane-session.json`.
 * `RUN402_CONTROL_PLANE_SESSION_PATH` overrides for testing.
 */
export declare function getControlPlaneSessionPath(): string;
/**
 * Load the cached control-plane session. Returns `null` for the "no session"
 * cases (absent, unreadable, unparseable). Throws when the file parses as JSON
 * but the shape is wrong, so a corrupted cache surfaces a clear fix-it.
 */
export declare function readControlPlaneSession(path?: string): ControlPlaneSessionCache | null;
/** Persist a control-plane session atomically (temp-file + rename), mode 0600. */
export declare function saveControlPlaneSession(data: ControlPlaneSessionCache, path?: string): void;
/** Delete the cached sign-in session — local half of `run402 logout`. Idempotent. */
export declare function clearControlPlaneSession(path?: string): void;
/** Whether a cached session is past its usable life (with a small skew buffer). */
export declare function isControlPlaneSessionExpired(session: ControlPlaneSessionCache, nowMs?: number, skewMs?: number): boolean;
/** Read the cached session and return it only if still usable; `null` if absent or expired. */
export declare function loadLiveControlPlaneSession(path?: string, nowMs?: number): ControlPlaneSessionCache | null;
/** Map a gateway token payload (relative `expires_in`) into the cached shape (absolute `expires_at`). */
export declare function controlPlaneSessionFromTokenResponse(resp: ControlPlaneSessionTokenResponse, nowMs?: number): ControlPlaneSessionCache;
/**
 * Delete the session caches of the retired email-scoped session
 * (`{base}/operator-session.json`) and the retired approval cache file
 * (`{base}/write-auth-session.json`). Neither is read any more; `run402 login`
 * and `run402 logout` call this so a stale token does not linger on disk.
 * Best-effort and idempotent.
 */
export declare function clearRetiredSessionCaches(): void;
//# sourceMappingURL=control-plane-session.d.ts.map