@synap-core/sdk 1.5.1 → 1.5.2

package/dist/connect.d.cts

@@ -316,7 +316,27 @@ interface ApproveProposalOptions {
 
 type PodErrorCode = "expired" | "unauthorized" | "forbidden" | "door_unsupported" | "not_found" | "invalid" | "conflict" | "rate_limited" | "pod_unreachable"
 /** The pod answered a redirect (a moved pod answers 308 from its old name): connect again at its new address. */
- | "pod_moved" | "server";
+ | "pod_moved"
+/**
+ * A credential door (approving a proposal that widens who or what can reach
+ * the pod) wants the person to re-confirm at the POD within 15 minutes; a
+ * Synap Cloud sign-in never counts. Recovery: `prompt_login`.
+ */
+ | "step_up_required"
+/** Synap Cloud refused to vouch a person with no verified email. Recovery: `verify_email`. */
+ | "email_unverified"
+/** Synap Cloud vouches an app origin over HTTPS only. Recovery: `use_https`. */
+ | "origin_insecure" | "server";
+/**
+ * What a typed refusal asks the app to do:
+ *  - `prompt_login`: send the person through the connect handler with
+ *    `prompt=login` (re-confirm at the pod; the SDK redeems it with the
+ *    device's refresh token), then retry ONCE;
+ *  - `verify_email`: tell the person to verify their Synap email;
+ *  - `use_https`: serve the app over HTTPS (`http://localhost` signs in to a
+ *    local Control Plane started with `CP_ALLOW_DEV_ORIGINS=true`, never to api.synap.live).
+ */
+type PodRecovery = "prompt_login" | "verify_email" | "use_https";
 /**
  * Why the SDK refused before sending anything (`status: null`):
  *  - `agent_cannot_approve`: an agent connection asked to approve (the pod
@@ -334,6 +354,8 @@ interface PodError {
     detail?: string;
     /** Set when the SDK refused locally (1.5). */
     reason?: PodRefusalReason;
+    /** What to do next, on `step_up_required`, `email_unverified` and `origin_insecure`. */
+    recovery?: PodRecovery;
     /**
      * On `unauthorized` (1.5): the pod refused the access token, the connection
      * still holds a refresh token, and this client could not renew it (no
@@ -914,6 +936,8 @@ interface ConnectTransaction {
     resource: string | null;
     /** A same-origin path to land on afterwards. */
     next: string | null;
+    /** The sign-in re-confirms a device that is already connected (`prompt=login`). */
+    stepUp?: boolean;
     createdAt: number;
 }
 interface FlowOptions {
@@ -938,8 +962,13 @@ interface StartConnectOptions extends FlowOptions {
      * `"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).
+     *
+     * `"login"`: a step-up. A credential door refused a stale device
+     * (`step_up_required`): the person re-confirms at the pod (OIDC
+     * `prompt=login`) and the callback redeems the code WITH the connection's
+     * refresh token (`synap_device_refresh_token`; see `HandleCallbackOptions.current`).
      */
-    prompt?: "consent" | null;
+    prompt?: "consent" | "login" | null;
     allowInsecureLoopback?: boolean;
 }
 interface StartedConnect {
@@ -964,6 +993,13 @@ interface HandleCallbackOptions extends FlowOptions {
     clientId: string;
     redirectUri: string;
     secret: AppSecret;
+    /**
+     * The connection this browser holds now. A step-up (`prompt=login`) of a
+     * Synap app's device is redeemed with ITS refresh token (the pod moves that
+     * device's clock instead of making a second device); without one, or for an
+     * app that is not a person's device, the code is redeemed as any other.
+     */
+    current?: PodConnection | null;
 }
 interface CallbackResult {
     connection: PodConnection;
@@ -1028,4 +1064,4 @@ declare function revokeConnection(connection: PodConnection, opts?: FlowOptions)
 /** RFC 7636 §4.2: `BASE64URL(SHA256(ASCII(code_verifier)))`. */
 declare function pkceChallenge(verifier: string): Promise<string>;
 
-export { type AcceptCloudReturnOptions, AppRequest, type AppSecret, type ApproveProposalOptions, 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 GetDocumentOptions, type GetEntityConnectionsOptions, type HandleCallbackOptions, type LaunchHint, type ListEntitiesOptions, type ListFocusSessionsOptions, type ListPendingProposalsOptions, MARKER_TTL_SEC, MIN_SECRET_LENGTH, type Opened, type PendingProposal, type PendingProposals, PodActsAs, type PodAppAuth, type PodAppAuthConfig, type PodAppClientOptions, type PodAppPaths, type PodApproval, type PodClient, type PodClientOptions, PodConnection, type PodConnectionSource, type PodDocument, type PodDocumentSection, type PodEntity, type PodEntityConnection, type PodEntityConnections, type PodEntityFacet, type PodError, type PodErrorCode, type PodFileUrl, type PodFocusSession, PodGrant, PodIssuer, type PodRefusalReason, type PodResult, type PodSessionSlot, type PodSessionStatus, PodSpace, type PodWriteResult, type QueryValue, REFRESH_WINDOW_MS, ROTATION_MEMORY_MS, type RefreshOptions, 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, connectionActsAs, connectionExpiresAt, cookieNames, createPodAppAuth, createPodClient, createSealedCookieStore, discoverPod, handleCallback, humanSlots, isBrowserRuntime, isConnectError, isPrefetchOrAsset, markerCookie, openTransaction, parseConnectErrorCode, parseTokenResponse, pkceChallenge, readMarker, refreshConnection, reviewUrlFor, revokeConnection, safeNextPath, seal, spaces, startCloudConnect, startConnect, unseal };
+export { type AcceptCloudReturnOptions, AppRequest, type AppSecret, type ApproveProposalOptions, 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 GetDocumentOptions, type GetEntityConnectionsOptions, type HandleCallbackOptions, type LaunchHint, type ListEntitiesOptions, type ListFocusSessionsOptions, type ListPendingProposalsOptions, MARKER_TTL_SEC, MIN_SECRET_LENGTH, type Opened, type PendingProposal, type PendingProposals, PodActsAs, type PodAppAuth, type PodAppAuthConfig, type PodAppClientOptions, type PodAppPaths, type PodApproval, type PodClient, type PodClientOptions, PodConnection, type PodConnectionSource, type PodDocument, type PodDocumentSection, type PodEntity, type PodEntityConnection, type PodEntityConnections, type PodEntityFacet, type PodError, type PodErrorCode, type PodFileUrl, type PodFocusSession, PodGrant, PodIssuer, type PodRecovery, type PodRefusalReason, type PodResult, type PodSessionSlot, type PodSessionStatus, PodSpace, type PodWriteResult, type QueryValue, REFRESH_WINDOW_MS, ROTATION_MEMORY_MS, type RefreshOptions, 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, connectionActsAs, connectionExpiresAt, cookieNames, createPodAppAuth, createPodClient, createSealedCookieStore, discoverPod, handleCallback, humanSlots, isBrowserRuntime, isConnectError, isPrefetchOrAsset, markerCookie, openTransaction, parseConnectErrorCode, parseTokenResponse, pkceChallenge, readMarker, refreshConnection, reviewUrlFor, revokeConnection, safeNextPath, seal, spaces, startCloudConnect, startConnect, unseal };

package/dist/connect.d.ts

@@ -316,7 +316,27 @@ interface ApproveProposalOptions {
 
 type PodErrorCode = "expired" | "unauthorized" | "forbidden" | "door_unsupported" | "not_found" | "invalid" | "conflict" | "rate_limited" | "pod_unreachable"
 /** The pod answered a redirect (a moved pod answers 308 from its old name): connect again at its new address. */
- | "pod_moved" | "server";
+ | "pod_moved"
+/**
+ * A credential door (approving a proposal that widens who or what can reach
+ * the pod) wants the person to re-confirm at the POD within 15 minutes; a
+ * Synap Cloud sign-in never counts. Recovery: `prompt_login`.
+ */
+ | "step_up_required"
+/** Synap Cloud refused to vouch a person with no verified email. Recovery: `verify_email`. */
+ | "email_unverified"
+/** Synap Cloud vouches an app origin over HTTPS only. Recovery: `use_https`. */
+ | "origin_insecure" | "server";
+/**
+ * What a typed refusal asks the app to do:
+ *  - `prompt_login`: send the person through the connect handler with
+ *    `prompt=login` (re-confirm at the pod; the SDK redeems it with the
+ *    device's refresh token), then retry ONCE;
+ *  - `verify_email`: tell the person to verify their Synap email;
+ *  - `use_https`: serve the app over HTTPS (`http://localhost` signs in to a
+ *    local Control Plane started with `CP_ALLOW_DEV_ORIGINS=true`, never to api.synap.live).
+ */
+type PodRecovery = "prompt_login" | "verify_email" | "use_https";
 /**
  * Why the SDK refused before sending anything (`status: null`):
  *  - `agent_cannot_approve`: an agent connection asked to approve (the pod
@@ -334,6 +354,8 @@ interface PodError {
     detail?: string;
     /** Set when the SDK refused locally (1.5). */
     reason?: PodRefusalReason;
+    /** What to do next, on `step_up_required`, `email_unverified` and `origin_insecure`. */
+    recovery?: PodRecovery;
     /**
      * On `unauthorized` (1.5): the pod refused the access token, the connection
      * still holds a refresh token, and this client could not renew it (no
@@ -914,6 +936,8 @@ interface ConnectTransaction {
     resource: string | null;
     /** A same-origin path to land on afterwards. */
     next: string | null;
+    /** The sign-in re-confirms a device that is already connected (`prompt=login`). */
+    stepUp?: boolean;
     createdAt: number;
 }
 interface FlowOptions {
@@ -938,8 +962,13 @@ interface StartConnectOptions extends FlowOptions {
      * `"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).
+     *
+     * `"login"`: a step-up. A credential door refused a stale device
+     * (`step_up_required`): the person re-confirms at the pod (OIDC
+     * `prompt=login`) and the callback redeems the code WITH the connection's
+     * refresh token (`synap_device_refresh_token`; see `HandleCallbackOptions.current`).
      */
-    prompt?: "consent" | null;
+    prompt?: "consent" | "login" | null;
     allowInsecureLoopback?: boolean;
 }
 interface StartedConnect {
@@ -964,6 +993,13 @@ interface HandleCallbackOptions extends FlowOptions {
     clientId: string;
     redirectUri: string;
     secret: AppSecret;
+    /**
+     * The connection this browser holds now. A step-up (`prompt=login`) of a
+     * Synap app's device is redeemed with ITS refresh token (the pod moves that
+     * device's clock instead of making a second device); without one, or for an
+     * app that is not a person's device, the code is redeemed as any other.
+     */
+    current?: PodConnection | null;
 }
 interface CallbackResult {
     connection: PodConnection;
@@ -1028,4 +1064,4 @@ declare function revokeConnection(connection: PodConnection, opts?: FlowOptions)
 /** RFC 7636 §4.2: `BASE64URL(SHA256(ASCII(code_verifier)))`. */
 declare function pkceChallenge(verifier: string): Promise<string>;
 
-export { type AcceptCloudReturnOptions, AppRequest, type AppSecret, type ApproveProposalOptions, 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 GetDocumentOptions, type GetEntityConnectionsOptions, type HandleCallbackOptions, type LaunchHint, type ListEntitiesOptions, type ListFocusSessionsOptions, type ListPendingProposalsOptions, MARKER_TTL_SEC, MIN_SECRET_LENGTH, type Opened, type PendingProposal, type PendingProposals, PodActsAs, type PodAppAuth, type PodAppAuthConfig, type PodAppClientOptions, type PodAppPaths, type PodApproval, type PodClient, type PodClientOptions, PodConnection, type PodConnectionSource, type PodDocument, type PodDocumentSection, type PodEntity, type PodEntityConnection, type PodEntityConnections, type PodEntityFacet, type PodError, type PodErrorCode, type PodFileUrl, type PodFocusSession, PodGrant, PodIssuer, type PodRefusalReason, type PodResult, type PodSessionSlot, type PodSessionStatus, PodSpace, type PodWriteResult, type QueryValue, REFRESH_WINDOW_MS, ROTATION_MEMORY_MS, type RefreshOptions, 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, connectionActsAs, connectionExpiresAt, cookieNames, createPodAppAuth, createPodClient, createSealedCookieStore, discoverPod, handleCallback, humanSlots, isBrowserRuntime, isConnectError, isPrefetchOrAsset, markerCookie, openTransaction, parseConnectErrorCode, parseTokenResponse, pkceChallenge, readMarker, refreshConnection, reviewUrlFor, revokeConnection, safeNextPath, seal, spaces, startCloudConnect, startConnect, unseal };
+export { type AcceptCloudReturnOptions, AppRequest, type AppSecret, type ApproveProposalOptions, 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 GetDocumentOptions, type GetEntityConnectionsOptions, type HandleCallbackOptions, type LaunchHint, type ListEntitiesOptions, type ListFocusSessionsOptions, type ListPendingProposalsOptions, MARKER_TTL_SEC, MIN_SECRET_LENGTH, type Opened, type PendingProposal, type PendingProposals, PodActsAs, type PodAppAuth, type PodAppAuthConfig, type PodAppClientOptions, type PodAppPaths, type PodApproval, type PodClient, type PodClientOptions, PodConnection, type PodConnectionSource, type PodDocument, type PodDocumentSection, type PodEntity, type PodEntityConnection, type PodEntityConnections, type PodEntityFacet, type PodError, type PodErrorCode, type PodFileUrl, type PodFocusSession, PodGrant, PodIssuer, type PodRecovery, type PodRefusalReason, type PodResult, type PodSessionSlot, type PodSessionStatus, PodSpace, type PodWriteResult, type QueryValue, REFRESH_WINDOW_MS, ROTATION_MEMORY_MS, type RefreshOptions, 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, connectionActsAs, connectionExpiresAt, cookieNames, createPodAppAuth, createPodClient, createSealedCookieStore, discoverPod, handleCallback, humanSlots, isBrowserRuntime, isConnectError, isPrefetchOrAsset, markerCookie, openTransaction, parseConnectErrorCode, parseTokenResponse, pkceChallenge, readMarker, refreshConnection, reviewUrlFor, revokeConnection, safeNextPath, seal, spaces, startCloudConnect, startConnect, unseal };

package/dist/connect.js

@@ -555,14 +555,32 @@ function renewalError(err) {
       return { code: "server", status: null, detail };
   }
 }
+var STEP_UP_MESSAGE = "Confirm it's you before changing who or what can reach this pod.";
+var CP_PROBLEMS = {
+  CP_ACCOUNT_EMAIL_REQUIRED: { code: "email_unverified", recovery: "verify_email" },
+  FEDERATED_APPLICATION_ORIGIN_INSECURE: { code: "origin_insecure", recovery: "use_https" }
+};
+function isStepUp(obj) {
+  const data = (v) => v && typeof v === "object" ? v : {};
+  const nested = data(data(obj.error).data).reasonCode ?? data(obj.data).reasonCode ?? obj.reasonCode;
+  return nested === "STEP_UP_REQUIRED" || obj.error === STEP_UP_MESSAGE || obj.message === STEP_UP_MESSAGE;
+}
+function classifyRefusal(status, body) {
+  const obj = body && typeof body === "object" ? body : {};
+  if (status === 403) {
+    if (isStepUp(obj)) return { code: "step_up_required", recovery: "prompt_login" };
+    return { code: obj.code === "GRANT_DOOR_UNSUPPORTED" ? "door_unsupported" : "forbidden" };
+  }
+  const problem = typeof obj.code === "string" ? CP_PROBLEMS[obj.code] : void 0;
+  return problem ?? { code: "conflict" };
+}
 function errorFor(status, body, retryAfter, now) {
   const obj = body && typeof body === "object" ? body : {};
   const detail = typeof obj.error === "string" ? obj.error : typeof obj.message === "string" ? obj.message : void 0;
   const base = { status, ...detail !== void 0 ? { detail } : {} };
   if (status === 401) return { code: "unauthorized", ...base };
-  if (status === 403) return { code: obj.code === "GRANT_DOOR_UNSUPPORTED" ? "door_unsupported" : "forbidden", ...base };
+  if (status === 403 || status === 409) return { ...classifyRefusal(status, body), ...base };
   if (status === 404) return { code: "not_found", ...base };
-  if (status === 409) return { code: "conflict", ...base };
   if (status === 400 || status === 422) return { code: "invalid", ...base };
   if (status === 429) {
     const retryAfterSec = retryAfterSeconds(retryAfter, now);
@@ -898,7 +916,7 @@ async function startConnect(opts) {
   url.searchParams.set("code_challenge_method", "S256");
   if (resource) url.searchParams.set("resource", resource);
   if (opts.spaceHint) url.searchParams.set("synap_space_hint", opts.spaceHint);
-  if (opts.prompt === "consent") url.searchParams.set("prompt", "consent");
+  if (opts.prompt === "consent" || opts.prompt === "login") url.searchParams.set("prompt", opts.prompt);
   const tx = {
     v: 1,
     issuer: issuer.issuer,
@@ -910,6 +928,7 @@ async function startConnect(opts) {
     verifier,
     resource,
     next: opts.next ?? null,
+    ...opts.prompt === "login" ? { stepUp: true } : {},
     createdAt: now
   };
   const expiresAt = now + TRANSACTION_TTL_MS;
@@ -967,13 +986,16 @@ async function handleCallback(opts) {
     code_verifier: tx.verifier
   });
   if (tx.resource) body.set("resource", tx.resource);
+  const device = tx.stepUp && opts.current && opts.current.actsAs === "person" && opts.current.podUrl === tx.issuer && opts.current.clientId === tx.clientId ? opts.current : null;
+  if (device?.refreshToken) body.set("synap_device_refresh_token", device.refreshToken);
   const json = await tokenRequest(tx.tokenEndpoint, body, "token", opts);
   const connection = parseTokenResponse(json, {
     podUrl: tx.issuer,
     clientId: tx.clientId,
     tokenEndpoint: tx.tokenEndpoint,
     revocationEndpoint: tx.revocationEndpoint,
-    now: (opts.now ?? Date.now)()
+    now: (opts.now ?? Date.now)(),
+    ...device ? { previous: device } : {}
   });
   return { connection, next: tx.next };
 }
@@ -1479,7 +1501,8 @@ function createPodAppAuth(config) {
     const pod = formField(form, "pod")?.slice(0, 512) ?? "";
     const next = safeNextPath(formField(form, "next"), origin) ?? paths.afterConnect;
     const space = formField(form, "space");
-    const prompt = formField(form, "prompt") === "consent" ? "consent" : null;
+    const asked = formField(form, "prompt");
+    const prompt = asked === "consent" || asked === "login" ? asked : null;
     try {
       if (!prompt && await liveConnectionTo(request, pod)) return redirect(new URL(next, origin).href);
       return await toPod({ pod, next, space, prompt });
@@ -1496,6 +1519,7 @@ function createPodAppAuth(config) {
         ...flow,
         callbackUrl: request.url,
         transaction,
+        current: await store.read(request).catch(() => null),
         clientId,
         redirectUri,
         secret: config.secret