@synap-core/sdk 1.2.0 → 1.3.0

package/dist/connect.d.cts

@@ -0,0 +1,442 @@
+import { b as PodConnection, P as PodGrant, C as ClientMetadataDocument, A as AppRequest, c as PodIssuer } from './types-DpqPNaaa.cjs';
+export { a as PodUser } from './types-DpqPNaaa.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 available yet. */
+ | "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>;
+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;
+    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;
+/**
+ * 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";
+/** 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;
+}
+/** `__Host-` names on https (Secure, Path=/, no Domain: bound to this exact host). */
+declare function cookieNames(secure: boolean): CookieNames;
+/** 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;
+    /** 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;
+    /** Accept pods 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;
+}
+interface PodAppAuth {
+    clientId: string;
+    redirectUri: string;
+    metadata: ClientMetadataDocument;
+    paths: PodAppPaths;
+    handlers: {
+        clientMetadata(request: Request): Promise<Response>;
+        connect(request: Request): Promise<Response>;
+        callback(request: Request): Promise<Response>;
+        disconnect(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>;
+    /** 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;
+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>;
+/** Whether "Continue with Synap Cloud" can be offered. False until the CP pod chooser (C1) ships. */
+declare function cloudConnectAvailable(): boolean;
+/** The Synap Cloud pod chooser (C1). Not available yet: always throws `cp_unavailable`. */
+declare function startCloudConnect(_opts: {
+    clientId: string;
+    state?: string;
+}): never;
+/**
+ * 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;
+}
+/**
+ * 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, later, the Synap Cloud chooser's return.
+ */
+declare function acceptLaunch(url: string | URL, appOrigin: string, opts?: {
+    allowInsecureLoopback?: boolean;
+}): LaunchHint;
+
+/** 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;
+    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). 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 { AppRequest, type AppSecret, CONNECT_ERROR_CODES, type CallbackResult, ClientMetadataDocument, ConnectError, type ConnectErrorCode, type ConnectTransaction, type ConnectionStore, type CookieNames, DEFAULT_PATHS, DEFAULT_REFRESH_IDLE_MS, type DiscoverOptions, type FlowOptions, type HandleCallbackOptions, type LaunchHint, MIN_SECRET_LENGTH, type Opened, type PodAppAuth, type PodAppAuthConfig, type PodAppPaths, type PodClient, type PodClientOptions, PodConnection, type PodError, type PodErrorCode, PodGrant, PodIssuer, type PodResult, type PodWriteResult, type QueryValue, REFRESH_WINDOW_MS, ROTATION_MEMORY_MS, type RefreshOutcome, type RefreshStatus, type SealPurpose, type SealedCookieStoreOptions, type SealedTransaction, type StartConnectOptions, type StartedConnect, TRANSACTION_TTL_MS, acceptLaunch, applySetCookies, buildClientMetadata, can, canonicalPodUrl, cloudConnectAvailable, connectionExpiresAt, cookieNames, createPodAppAuth, createPodClient, createSealedCookieStore, discoverPod, handleCallback, isBrowserRuntime, isConnectError, openTransaction, parseConnectErrorCode, parseTokenResponse, pkceChallenge, refreshConnection, reviewUrlFor, revokeConnection, safeNextPath, seal, startCloudConnect, startConnect, unseal };