@synap-core/sdk 1.2.0 → 1.4.0

package/dist/connect.d.cts

@@ -0,0 +1,647 @@
+import { b as PodConnection, P as PodGrant, c as PodSpace, C as ClientMetadataDocument, A as AppRequest, d as PodIssuer } from './types-C2KGNXEn.cjs';
+export { a as PodUser } from './types-C2KGNXEn.cjs';
+
+/**
+ * The one error type of `@synap-core/sdk/connect`. `code` is the contract a UI
+ * branches on; `message` and `detail` are for the developer's logs, never for
+ * the person (a sign-in failure page says one sentence per code, never why).
+ */
+type ConnectErrorCode = 
+/** The typed pod address is not a usable URL. */
+"invalid_pod_address"
+/** Something answered, but it is not a Synap pod (no AS metadata). */
+ | "not_a_pod"
+/** The pod did not answer (network, timeout, 5xx). */
+ | "pod_unreachable"
+/** A Synap pod, but too old for app sign-in (no CIMD, no `iss`, no S256). */
+ | "pod_unsupported"
+/** Connecting through Synap Cloud is not configured for this app (no Control Plane URL). */
+ | "cp_unavailable"
+/** The person said no on the consent screen. */
+ | "denied"
+/** No sign-in in progress here, or it is older than 10 minutes. */
+ | "expired_transaction"
+/** The answer does not belong to the sign-in this browser started (`state` or `iss`). */
+ | "mismatch"
+/** The app's own setup is wrong (client metadata, scopes, secret, redirect). */
+ | "misconfigured"
+/** The pod asked to slow down; see `retryAfterSec`. */
+ | "rate_limited"
+/** The connection lapsed (refresh token idle past its life, or none was issued). */
+ | "expired"
+/** The pod refused the connection's refresh token while it should still live. */
+ | "revoked"
+/** The pod answered something the SDK cannot use. */
+ | "server_error";
+declare class ConnectError extends Error {
+    readonly code: ConnectErrorCode;
+    /** Seconds to wait, from `Retry-After`, when `code` is `rate_limited`. */
+    readonly retryAfterSec?: number;
+    /** The OAuth error code the pod sent, when there was one (logs only). */
+    readonly oauthError?: string;
+    constructor(code: ConnectErrorCode, message: string, extra?: {
+        retryAfterSec?: number;
+        oauthError?: string;
+    });
+}
+declare function isConnectError(err: unknown): err is ConnectError;
+declare const CONNECT_ERROR_CODES: readonly ConnectErrorCode[];
+/** Parse an untrusted `?error=` value back into a code (null when unknown). */
+declare function parseConnectErrorCode(value: string | null | undefined): ConnectErrorCode | null;
+
+type PodErrorCode = "expired" | "unauthorized" | "forbidden" | "door_unsupported" | "not_found" | "invalid" | "conflict" | "rate_limited" | "pod_unreachable" | "server";
+interface PodError {
+    code: PodErrorCode;
+    /** The HTTP status, or null when nothing was answered. */
+    status: number | null;
+    retryAfterSec?: number;
+    /** The pod's own error text, for logs only. */
+    detail?: string;
+}
+type PodResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: PodError;
+};
+type PodWriteResult<T> = {
+    ok: true;
+    status: "applied";
+    data: T;
+} | {
+    ok: true;
+    status: "proposed";
+    proposalId: string | null;
+    reviewUrl: string;
+    data: T;
+} | {
+    ok: false;
+    error: PodError;
+};
+type QueryValue = string | number | boolean | null | undefined | ReadonlyArray<string | number | boolean>;
+/** One pending proposal, the pod's summary row (`GET /proposals?view=basic`). */
+interface PendingProposal {
+    id: string;
+    proposalType: string;
+    targetType: string;
+    targetId: string | null;
+    workspaceId: string | null;
+    /** ISO 8601, as the pod sent it. */
+    createdAt: string;
+    /** The agent that filed it (this app's agent, or another one), when known. */
+    agentUserId: string | null;
+    sessionId: string | null;
+    summary?: string;
+    /** Where the person reviews it: the pod's deep link. */
+    reviewUrl: string;
+}
+interface PendingProposals {
+    /** Every pending proposal the connection can see, not only this page (the pod COUNTs it). */
+    total: number;
+    proposals: PendingProposal[];
+    hasMore: boolean;
+}
+interface ListPendingProposalsOptions {
+    /** One granted space only. */
+    workspaceId?: string;
+    /** 1-200, default 20. */
+    limit?: number;
+    offset?: number;
+}
+interface PodClientOptions {
+    fetch?: typeof fetch;
+    now?: () => number;
+}
+interface PodClient {
+    podUrl: string;
+    user: PodConnection["user"];
+    grant: PodGrant[];
+    /** Whether the connection was granted `permission` (in `workspaceId` when given). */
+    can(permission: string, workspaceId?: string): boolean;
+    /** The granted spaces, each with its permissions (`spaces(connection)`). */
+    spaces(): PodSpace[];
+    /**
+     * "Waiting for review: N". The person's pending proposals in the spaces this
+     * connection may read proposals in (any agent's, not only this app's), from
+     * the pod's seamed `GET /proposals` door. Needs the `proposal.read`
+     * permission (ask for it in `requests`): without it the pod would answer an
+     * empty list, so this answers `forbidden` instead, without a request.
+     */
+    listPendingProposals(opts?: ListPendingProposalsOptions): Promise<PodResult<PendingProposals>>;
+    get<T = unknown>(path: string, query?: Record<string, QueryValue>): Promise<PodResult<T>>;
+    post<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
+    put<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
+    delete<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
+}
+/** Whether `connection` was granted `permission` (in `workspaceId` when given). Exact match: grants carry no wildcard. */
+declare function can(connection: Pick<PodConnection, "grant">, permission: string, workspaceId?: string): boolean;
+/**
+ * The grant by space, in the grant's order, each permission once. The pod
+ * sends one row per permission per space; a space switcher wants one per space.
+ */
+declare function spaces(connection: Pick<PodConnection, "grant">): PodSpace[];
+/**
+ * Where to review a proposal: the pod's answer, resolved against the pod and
+ * kept only on the pod's own origin; else the pod's deep link `/open/<id>`.
+ */
+declare function reviewUrlFor(podUrl: string, reviewUrl: unknown, proposalId: string | null): string;
+declare function createPodClient(connection: PodConnection, opts?: PodClientOptions): PodClient;
+
+type SealPurpose = "synap-connect/transaction" | "synap-connect/session" | "synap-connect/cloud";
+/** The app secret: one value, or several to rotate (the first seals, all open). */
+type AppSecret = string | readonly string[];
+declare const MIN_SECRET_LENGTH = 32;
+declare function seal(value: unknown, opts: {
+    secret: AppSecret;
+    purpose: SealPurpose;
+    expiresAt: number;
+}): Promise<string>;
+type Opened<T> = {
+    ok: true;
+    value: T;
+    expiresAt: number;
+} | {
+    ok: false;
+    reason: "invalid" | "expired";
+};
+/**
+ * `invalid` = not ours (malformed, tampered, other secret, other purpose);
+ * `expired` = ours, but past its `exp`.
+ */
+declare function unseal<T = unknown>(sealed: string, opts: {
+    secret: AppSecret;
+    purpose: SealPurpose;
+    now: number;
+}): Promise<Opened<T>>;
+
+interface ConnectionStore {
+    /** The request's connection, or null (absent, tampered, foreign, expired). */
+    read(request: Request): Promise<PodConnection | null>;
+    /** Persist; returns the Set-Cookie header values to send. */
+    write(connection: PodConnection, request: Request): Promise<string[]>;
+    /** Forget; returns the Set-Cookie header values to send. */
+    clear(request: Request): Promise<string[]>;
+}
+interface CookieNames {
+    session: string;
+    transaction: string;
+    /** A Synap Cloud sign-in in progress (sealed state, 10 minutes). */
+    cloud: string;
+    /** "This browser was connected to <pod>": the pod's URL only, no secret (`markerCookie`). */
+    marker: string;
+}
+/** `__Host-` names on https (Secure, Path=/, no Domain: bound to this exact host). */
+declare function cookieNames(secure: boolean): CookieNames;
+/** The marker outlives the connection: as long as browsers keep a cookie (400 days). */
+declare const MARKER_TTL_SEC: number;
+/**
+ * The marker cookie: which pod this browser was connected to, so a connection
+ * that lapsed (idle past the refresh token's life, its sealed cookie gone)
+ * reads as "expired, connect again to <pod>" rather than "never connected".
+ * It holds the pod's public URL and NOTHING else: no token, no user, nothing
+ * sealed. A forged value can only pre-fill the address the person confirms.
+ */
+declare function markerCookie(podUrl: string, opts: {
+    secure: boolean;
+    name?: string;
+}): string;
+/** The marker's pod URL, or null (absent, or not a canonical pod address). */
+declare function readMarker(cookieHeader: string | null, opts: {
+    secure: boolean;
+    name?: string;
+    allowInsecureLoopback?: boolean;
+}): string | null;
+/** When the stored value stops being useful. */
+declare function connectionExpiresAt(c: PodConnection): number;
+interface SealedCookieStoreOptions {
+    secret: AppSecret;
+    /** True on https (the default when the app URL is https). */
+    secure: boolean;
+    name?: string;
+    now?: () => number;
+}
+declare function createSealedCookieStore(opts: SealedCookieStoreOptions): ConnectionStore;
+/**
+ * Apply Set-Cookie values to a request's Cookie header, so code that runs
+ * later IN THE SAME REQUEST (a server component after `proxy.ts`) reads the
+ * refreshed value. A `Max-Age=0` removes the cookie.
+ */
+declare function applySetCookies(cookieHeader: string | null, setCookies: readonly string[]): string;
+
+interface PodAppPaths {
+    /** The client metadata document; its absolute URL is the client_id. */
+    metadata: string;
+    connect: string;
+    callback: string;
+    disconnect: string;
+    /** Synap Cloud: POST starts it, GET is the pod chooser's return (forwarded from the connect page). */
+    cloud: string;
+    /** The app's connect page (also the CIMD `initiate_login_uri`). */
+    connectPage: string;
+    /** Where a failed callback lands, with `?error=<code>`. */
+    resultPage: string;
+    /** Where a sign-in lands when it named no `next`. */
+    afterConnect: string;
+}
+declare const DEFAULT_PATHS: PodAppPaths;
+/** Refresh only inside the last 5 minutes of the access token's life. */
+declare const REFRESH_WINDOW_MS: number;
+interface PodAppAuthConfig {
+    /** The app's origin, e.g. https://studio.example.com (http only on localhost). */
+    appUrl: string;
+    /** Shown on the pod's consent screen (at most 100 characters). */
+    clientName: string;
+    /** What the app asks for, each with the reason the consent screen shows. */
+    requests: readonly AppRequest[];
+    /** Workspace-template slugs the consent may offer to create (`synap_templates`). */
+    templates?: readonly string[];
+    /** SERVER-ONLY secret, at least 32 characters (SYNAP_APP_SESSION_SECRET). Several to rotate. */
+    secret: AppSecret;
+    paths?: Partial<PodAppPaths>;
+    /** Defaults to the sealed session cookie. */
+    store?: ConnectionStore;
+    /** RFC 8707 resource asked for (default the Hub API). */
+    resource?: "api/hub" | "mcp" | null;
+    /**
+     * The Synap Control Plane's URL (e.g. https://api.synap.live): offers
+     * "Continue with Synap Cloud" (`cloudConnectAvailable`). Unset = address only.
+     */
+    cloudUrl?: string | null;
+    /** Accept pods (and a Control Plane) on http://localhost (development against a local pod). */
+    allowInsecureLoopback?: boolean;
+    /** Developer log of every refused sign-in; messages never carry a token. Default: console.warn. */
+    onError?: (error: ConnectError, where: "connect" | "callback" | "disconnect" | "refresh") => void;
+    fetch?: typeof fetch;
+    now?: () => number;
+}
+type RefreshStatus = 
+/** No connection in this request. */
+"none"
+/** Prefetch or static asset: nothing refreshed (the connection is read as is). */
+ | "skipped"
+/** Valid beyond the refresh window, or no refresh token to use. */
+ | "fresh"
+/** Rotated: send `setCookies`, forward `cookieHeader`. */
+ | "refreshed"
+/** The refresh failed (a lost rotation race, the pod busy) but the access token still works: keep it, set nothing. */
+ | "kept"
+/** The access token is spent and cannot be renewed: connect again. */
+ | "expired"
+/** The pod refused the refresh token (access removed): connect again. */
+ | "revoked"
+/** The pod could not be reached and the access token is spent: try later. */
+ | "unavailable";
+interface RefreshOutcome {
+    status: RefreshStatus;
+    /** A usable connection, or null. */
+    connection: PodConnection | null;
+    /** Set-Cookie values to append to the response. */
+    setCookies: string[];
+    /** The request's Cookie header with the refreshed value, to forward to the render (null = unchanged). */
+    cookieHeader: string | null;
+    error?: ConnectError;
+    /**
+     * With `none`: this browser WAS connected to that pod and the connection
+     * lapsed (its sealed cookie is gone, idle past its life). Say "expired,
+     * connect again" with the pod pre-filled, not "connect your pod".
+     */
+    lapsed?: {
+        podUrl: string;
+    };
+}
+interface PodAppAuth {
+    clientId: string;
+    redirectUri: string;
+    metadata: ClientMetadataDocument;
+    paths: PodAppPaths;
+    /** Whether "Continue with Synap Cloud" can be offered (`cloudUrl` is configured). */
+    cloudConnectAvailable: boolean;
+    handlers: {
+        clientMetadata(request: Request): Promise<Response>;
+        connect(request: Request): Promise<Response>;
+        callback(request: Request): Promise<Response>;
+        disconnect(request: Request): Promise<Response>;
+        /** POST: start a Synap Cloud sign-in (same-origin, form { next?, space?, prompt? }). */
+        cloudConnect(request: Request): Promise<Response>;
+        /** GET: the Synap Cloud pod chooser's return (`?iss&state`), checked against this browser's cookie. */
+        cloudReturn(request: Request): Promise<Response>;
+    };
+    /**
+     * The stored connection (no refresh, no expiry check), or null. Takes the
+     * request, or just its Cookie header (a server component has no Request:
+     * pass `(await headers()).get("cookie")`).
+     */
+    readConnection(source: Request | string | null): Promise<PodConnection | null>;
+    /**
+     * The pod this browser WAS connected to, when no connection is stored any
+     * more (it lapsed); null when one is stored or this browser never connected
+     * (or disconnected). Same sources as `readConnection`.
+     */
+    readLapsed(source: Request | string | null): Promise<{
+        podUrl: string;
+    } | null>;
+    /** For `proxy.ts` / a route handler: rotate near expiry, lost-race safe. */
+    refreshIfNeeded(request: Request): Promise<RefreshOutcome>;
+    /** A Hub REST client for the connection. */
+    client(connection: PodConnection, opts?: PodClientOptions): PodClient;
+}
+/** The CIMD document (spec 17 §6.1), validated the way the pod will validate it. */
+declare function buildClientMetadata(opts: {
+    appUrl: string;
+    clientName: string;
+    requests: readonly AppRequest[];
+    templates?: readonly string[];
+    paths?: Partial<PodAppPaths>;
+}): ClientMetadataDocument;
+/**
+ * A prefetch or a static asset: `refreshIfNeeded` answers `skipped` for these.
+ *
+ * LIMIT (Next.js 16 `proxy.ts` on the Node runtime): Next strips its router
+ * headers (`next-router-prefetch`, `rsc`, …, `FLIGHT_HEADERS` in
+ * next/dist/server/web/adapter.js) and the `_rsc` query BEFORE the proxy runs,
+ * so a router prefetch is invisible here. Skip prefetches in the proxy
+ * MATCHER, which still sees the raw headers:
+ *
+ *   export const config = { matcher: [{ source: "/((?!_next/static|_next/image|.*\\.\\w+$).*)",
+ *     missing: [{ type: "header", key: "next-router-prefetch" }, { type: "header", key: "purpose", value: "prefetch" }] }] };
+ *
+ * Route handlers and other frameworks see the headers, and this still checks them.
+ */
+declare function isPrefetchOrAsset(request: Request): boolean;
+declare function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth;
+
+interface DiscoverOptions {
+    fetch?: typeof fetch;
+    /** Allow `http://localhost` (and 127.0.0.1, [::1]) pods: development only. */
+    allowInsecureLoopback?: boolean;
+    now?: () => number;
+}
+/**
+ * The canonical issuer for a typed address, or a ConnectError. Adds `https://`
+ * when no scheme is given; drops a trailing slash.
+ */
+declare function canonicalPodUrl(input: string, opts?: {
+    allowInsecureLoopback?: boolean;
+}): string;
+/**
+ * A typed pod address (or a launch `iss`) → its validated authorization server.
+ * Tries the address, then `pod.<host>` (so "antoine.synap.live" finds
+ * "pod.antoine.synap.live").
+ */
+declare function discoverPod(input: string, opts?: DiscoverOptions): Promise<PodIssuer>;
+/**
+ * A same-origin path to return to after connecting, or null. Accepts a
+ * relative path (never `//host` or `/\host`) or an absolute URL on the app's
+ * own origin; anything else is dropped (no open redirect).
+ */
+declare function safeNextPath(value: string | null | undefined, appOrigin: string): string | null;
+interface LaunchHint {
+    /** The pod issuer the launcher named (`iss`), to pre-fill and CONFIRM (T6), never to auto-connect. */
+    pod: string | null;
+    /** Where to land after connecting (`target_link_uri`), same origin only. */
+    next: string | null;
+    /** A space to preselect on consent (`synap_space_hint`). */
+    spaceHint: string | null;
+    /**
+     * The `state` of a Synap Cloud return (the CP pod chooser answers
+     * `initiate_login_uri?iss=…&state=…`, or `?state=…&error=access_denied` when
+     * the person cancelled), shape-checked only. NOT verified here:
+     * send the request's query to the cloud handler (GET `paths.cloud`), which
+     * checks it against this browser's sealed cookie. Never act on `pod` because
+     * a state is present.
+     */
+    cloudState: string | null;
+}
+/**
+ * Read a third-party-initiated login (OIDC Core §4, spec 17 §7.2): the browser
+ * opens the app's `initiate_login_uri?iss=…&target_link_uri=…`. One parser for
+ * the browser launch and the Synap Cloud chooser's return (`cloudState`).
+ */
+declare function acceptLaunch(url: string | URL, appOrigin: string, opts?: {
+    allowInsecureLoopback?: boolean;
+}): LaunchHint;
+
+/** How long a Synap Cloud sign-in may take, from the click to the pod chooser's return. */
+declare const CLOUD_TRANSACTION_TTL_MS: number;
+/** A sealed `CloudTransaction`: opaque, safe to put in an HttpOnly cookie. */
+type SealedCloudTransaction = string & {
+    readonly __sealedCloudTransaction: true;
+};
+/** What a started Synap Cloud sign-in remembers (sealed; never sent to the CP). */
+interface CloudTransaction {
+    v: 1;
+    state: string;
+    clientId: string;
+    /** The CP base it was sent to. */
+    cloudUrl: string;
+    next: string | null;
+    spaceHint: string | null;
+    prompt: "consent" | null;
+    createdAt: number;
+}
+interface CloudConnectConfig {
+    /** The Control Plane's base URL, e.g. https://api.synap.live. Unset = no Synap Cloud option. */
+    cloudUrl?: string | null;
+    /** Accept a CP on http://localhost (development). */
+    allowInsecureLoopback?: boolean;
+}
+/** The CP base (no trailing slash), or a ConnectError (`misconfigured`). */
+declare function cloudBaseUrl(cloudUrl: string, opts?: {
+    allowInsecureLoopback?: boolean;
+}): string;
+/** Whether "Continue with Synap Cloud" can be offered: a valid Control Plane URL is configured. */
+declare function cloudConnectAvailable(config?: CloudConnectConfig | null): boolean;
+interface StartCloudConnectOptions extends CloudConnectConfig {
+    /** The app's client_id (its CIMD URL): the CP reads `initiate_login_uri` from it. */
+    clientId: string;
+    /** SERVER-ONLY app secret that seals the transaction. */
+    secret?: AppSecret;
+    /** A same-origin path to land on afterwards (validate it first: `safeNextPath`). */
+    next?: string | null;
+    /** A space to preselect on the pod's consent. */
+    spaceHint?: string | null;
+    /** Show the pod's consent again even if this browser is already connected to the pod the person picks. */
+    prompt?: "consent" | null;
+    /** @deprecated Ignored: the SDK always draws its own 32-byte state. */
+    state?: string;
+    now?: () => number;
+}
+interface StartedCloudConnect {
+    /** Redirect the browser here (303): the CP's pod chooser. */
+    url: string;
+    /** Store in an HttpOnly cookie until the CP returns. */
+    transaction: SealedCloudTransaction;
+    /** ms since epoch. */
+    expiresAt: number;
+}
+/**
+ * Start a Synap Cloud sign-in. Throws `cp_unavailable` at once when no CP URL
+ * is configured (as 1.3 always did), `misconfigured` without a secret.
+ */
+declare function startCloudConnect(opts: StartCloudConnectOptions): Promise<StartedCloudConnect>;
+interface AcceptCloudReturnOptions {
+    /** The URL the CP sent the browser back to (`?iss=…&state=…`). */
+    url: string | URL;
+    transaction: string | null | undefined;
+    clientId: string;
+    secret: AppSecret;
+    allowInsecureLoopback?: boolean;
+    now?: () => number;
+}
+interface CloudReturn {
+    /** The pod the person picked (canonical issuer), still to be discovered and validated. */
+    pod: string;
+    next: string | null;
+    spaceHint: string | null;
+    prompt: "consent" | null;
+}
+/**
+ * Check the CP's return against the sealed transaction of THIS browser.
+ * Throws `expired_transaction` (none, foreign, tampered or older than 10
+ * minutes), `mismatch` (the state is not this browser's, or no pod is named),
+ * `denied` (the person cancelled on the chooser: `error=access_denied`, no
+ * `iss`; nothing is started), `invalid_pod_address`.
+ * `state` is compared BEFORE anything else in the query is used.
+ */
+declare function acceptCloudReturn(opts: AcceptCloudReturnOptions): Promise<CloudReturn>;
+
+/** How long a started sign-in stays valid. */
+declare const TRANSACTION_TTL_MS: number;
+/** The refresh token's idle life when the pod does not say (spec 17 F5: 30 days). */
+declare const DEFAULT_REFRESH_IDLE_MS: number;
+/** A sealed `ConnectTransaction`: opaque, safe to put in an HttpOnly cookie. */
+type SealedTransaction = string & {
+    readonly __sealedTransaction: true;
+};
+/** What a started sign-in remembers (sealed; never sent to the pod). */
+interface ConnectTransaction {
+    v: 1;
+    issuer: string;
+    tokenEndpoint: string;
+    revocationEndpoint: string | null;
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    verifier: string;
+    resource: string | null;
+    /** A same-origin path to land on afterwards. */
+    next: string | null;
+    createdAt: number;
+}
+interface FlowOptions {
+    fetch?: typeof fetch;
+    now?: () => number;
+}
+interface StartConnectOptions extends FlowOptions {
+    /** A validated issuer (`discoverPod`), or an address / launch `iss` to discover. */
+    pod: PodIssuer | string;
+    clientId: string;
+    redirectUri: string;
+    /** Grant-grammar permissions, each declared in the app's client metadata. */
+    permissions: readonly string[];
+    secret: AppSecret;
+    /** RFC 8707 resource: the pod's Hub API (default) or its MCP endpoint; null = none. */
+    resource?: "api/hub" | "mcp" | null;
+    /** A space to preselect on consent. */
+    spaceHint?: string | null;
+    /** A same-origin path to land on afterwards (validate it first: `safeNextPath`). */
+    next?: string | null;
+    /**
+     * `"consent"`: the person asked to see the consent screen again (to widen or
+     * narrow what the app may touch). Sent as OIDC `prompt=consent`; the sign-in
+     * is otherwise the same (fresh PKCE verifier and state).
+     */
+    prompt?: "consent" | null;
+    allowInsecureLoopback?: boolean;
+}
+interface StartedConnect {
+    /** Redirect the browser here (303). */
+    authorizeUrl: string;
+    /** Store in an HttpOnly cookie until the callback. */
+    transaction: SealedTransaction;
+    /** ms since epoch. */
+    expiresAt: number;
+    issuer: PodIssuer;
+}
+declare function startConnect(opts: StartConnectOptions): Promise<StartedConnect>;
+/** Open a sealed transaction; refuses tampered, foreign and stale ones. */
+declare function openTransaction(sealed: string | null | undefined, opts: {
+    secret: AppSecret;
+    now?: () => number;
+}): Promise<ConnectTransaction>;
+interface HandleCallbackOptions extends FlowOptions {
+    /** The full URL the pod redirected the browser to. */
+    callbackUrl: string | URL;
+    transaction: string | null | undefined;
+    clientId: string;
+    redirectUri: string;
+    secret: AppSecret;
+}
+interface CallbackResult {
+    connection: PodConnection;
+    /** The same-origin path the sign-in was started for. */
+    next: string | null;
+}
+declare function handleCallback(opts: HandleCallbackOptions): Promise<CallbackResult>;
+/**
+ * A token response → a connection. On a refresh, `previous` supplies what the
+ * response may omit (grant, user, app). `expires_in` is read as sent: a refresh
+ * answered within the pod's reuse grace (PB3b) hands back the live key the
+ * first redeem got, with less than an hour left. A refresh response WITHOUT a new
+ * refresh_token drops the old one: with single-use rotation, resending a
+ * consumed token reads as theft and revokes the whole family.
+ */
+declare function parseTokenResponse(body: Record<string, unknown>, ctx: {
+    podUrl: string;
+    clientId: string;
+    tokenEndpoint: string;
+    revocationEndpoint: string | null;
+    now: number;
+    previous?: PodConnection;
+}): PodConnection;
+/**
+ * How long a rotation's result is remembered for its SPENT refresh token.
+ * The pod (PB3) refuses a concurrent second redeem softly, but a token
+ * presented AGAIN after its use is a reuse: the whole family and the live
+ * access key are revoked. A browser easily sends that replay: parallel
+ * requests, a second tab, a response it had not stored yet, all still
+ * carrying the old cookie. Within this window such a request gets the
+ * rotation's result (and re-sends the new cookie) instead of reaching the pod.
+ */
+declare const ROTATION_MEMORY_MS: number;
+/**
+ * Exchange the refresh token for a new access token and the rotated refresh
+ * token (PB3: single-use, 30 days from issue, reach re-derived by the pod).
+ *
+ * SINGLE-FLIGHT per connection within this process: concurrent callers share
+ * one request, and for `ROTATION_MEMORY_MS` after it a caller still holding
+ * the spent token gets the same result, so this process never replays a
+ * spent token. Across processes nothing here can coordinate: a server-side
+ * `ConnectionStore` (one row per connection) is the way to rule that out.
+ * The caller must PERSIST the result before using its access token
+ * (`refreshIfNeeded` does).
+ *
+ * Throws `expired` (no refresh token, or past its idle life), `revoked`
+ * (invalid_grant while it should live: spent, revoked, the app removed or
+ * narrowed to nothing, or a concurrent redeem lost), `misconfigured`
+ * (invalid_client, unauthorized_client), `rate_limited`, `pod_unreachable`,
+ * `server_error`.
+ */
+declare function refreshConnection(connection: PodConnection, opts?: FlowOptions): Promise<PodConnection>;
+/**
+ * RFC 7009, best effort: the refresh token (the pod retires its whole family
+ * and the live access key) then the access token (for a pod without refresh).
+ * Never throws; `revoked` says whether the pod confirmed.
+ */
+declare function revokeConnection(connection: PodConnection, opts?: FlowOptions): Promise<{
+    revoked: boolean;
+}>;
+
+/** RFC 7636 §4.2: `BASE64URL(SHA256(ASCII(code_verifier)))`. */
+declare function pkceChallenge(verifier: string): Promise<string>;
+
+declare function isBrowserRuntime(): boolean;
+
+export { type AcceptCloudReturnOptions, AppRequest, type AppSecret, CLOUD_TRANSACTION_TTL_MS, CONNECT_ERROR_CODES, type CallbackResult, ClientMetadataDocument, type CloudConnectConfig, type CloudReturn, type CloudTransaction, ConnectError, type ConnectErrorCode, type ConnectTransaction, type ConnectionStore, type CookieNames, DEFAULT_PATHS, DEFAULT_REFRESH_IDLE_MS, type DiscoverOptions, type FlowOptions, type HandleCallbackOptions, type LaunchHint, type ListPendingProposalsOptions, MARKER_TTL_SEC, MIN_SECRET_LENGTH, type Opened, type PendingProposal, type PendingProposals, type PodAppAuth, type PodAppAuthConfig, type PodAppPaths, type PodClient, type PodClientOptions, PodConnection, type PodError, type PodErrorCode, PodGrant, PodIssuer, type PodResult, PodSpace, type PodWriteResult, type QueryValue, REFRESH_WINDOW_MS, ROTATION_MEMORY_MS, type RefreshOutcome, type RefreshStatus, type SealPurpose, type SealedCloudTransaction, type SealedCookieStoreOptions, type SealedTransaction, type StartCloudConnectOptions, type StartConnectOptions, type StartedCloudConnect, type StartedConnect, TRANSACTION_TTL_MS, acceptCloudReturn, acceptLaunch, applySetCookies, buildClientMetadata, can, canonicalPodUrl, cloudBaseUrl, cloudConnectAvailable, connectionExpiresAt, cookieNames, createPodAppAuth, createPodClient, createSealedCookieStore, discoverPod, handleCallback, isBrowserRuntime, isConnectError, isPrefetchOrAsset, markerCookie, openTransaction, parseConnectErrorCode, parseTokenResponse, pkceChallenge, readMarker, refreshConnection, reviewUrlFor, revokeConnection, safeNextPath, seal, spaces, startCloudConnect, startConnect, unseal };