@synap-core/sdk 1.3.0 → 1.4.0

package/dist/connect.d.cts

@@ -1,5 +1,5 @@
-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';
+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
@@ -15,7 +15,7 @@ type ConnectErrorCode =
  | "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. */
+/** 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"
@@ -80,6 +80,35 @@ type PodWriteResult<T> = {
     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;
@@ -90,6 +119,16 @@ interface PodClient {
     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>>;
@@ -98,6 +137,11 @@ interface PodClient {
 }
 /** 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>`.
@@ -105,7 +149,7 @@ declare function can(connection: Pick<PodConnection, "grant">, permission: strin
 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";
+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;
@@ -143,9 +187,32 @@ interface ConnectionStore {
 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 {
@@ -169,6 +236,8 @@ interface PodAppPaths {
     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>`. */
@@ -195,7 +264,12 @@ interface PodAppAuthConfig {
     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). */
+    /**
+     * 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;
@@ -228,17 +302,31 @@ interface RefreshOutcome {
     /** 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
@@ -246,6 +334,14 @@ interface PodAppAuth {
      * 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. */
@@ -259,6 +355,21 @@ declare function buildClientMetadata(opts: {
     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 {
@@ -280,13 +391,6 @@ declare function canonicalPodUrl(input: string, opts?: {
  * "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
@@ -300,16 +404,109 @@ interface LaunchHint {
     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, later, the Synap Cloud chooser's return.
+ * 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). */
@@ -351,6 +548,12 @@ interface StartConnectOptions extends FlowOptions {
     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 {
@@ -384,7 +587,9 @@ interface CallbackResult {
 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
+ * 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.
  */
@@ -439,4 +644,4 @@ 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 };
+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 };