@synap-core/sdk 1.5.0 → 1.5.2

package/src/connect/auth.ts

@@ -18,6 +18,11 @@
  * what the app may touch); without it a person already connected to that pod
  * goes straight to `next`. Either way a sign-in is a fresh PKCE + state flow.
  *
+ * `prompt=login` is the step-up: a credential door refused a stale device
+ * (`step_up_required`), so the person re-confirms at the POD (never through
+ * Synap Cloud) and the callback redeems the code with the connection's refresh
+ * token. Then retry the refused call once.
+ *
  * `connect` and `disconnect` change state, so they are POST and same-origin
  * only (Origin, else Sec-Fetch-Site): a third-party page cannot start a
  * sign-in into an attacker's pod for a visitor (login CSRF) or sign them out.
@@ -218,10 +223,25 @@ function isSynapAppOrigin(origin: string): boolean {
 }
 
 /**
- * One `synap_requests[].permission`, refused here exactly when the pod would
- * refuse it: `<subject>[.<kind>].<action>`, lowercase, a kind only on
+ * Mock mode's origin (`http://localhost`): it signs in to the SDK's mock pod
+ * only, since a real pod refuses an http client_id before it reads a single
+ * permission (synap-backend `routers/oauth/client-id-url.ts`
+ * `assertClientMetadataUrl`: "client_id URL must use https"). So the review
+ * verbs are not refused here, and an app that asks for them can run on the mock.
+ */
+function isMockModeOrigin(origin: string): boolean {
+  const url = new URL(origin);
+  return url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+}
+
+/**
+ * One `synap_requests[].permission`, refused here when the pod would refuse
+ * it (at most as strict: any `https://<name>.synap.live` passes the review-verb
+ * check here, while the pod admits only its own list of Synap app ids, which
+ * this SDK does not copy; the pod's answer is the authority): `<subject>[.<kind>].<action>`, lowercase, a kind only on
  * `entity`, an action in the pod's grant actions (the review verbs only for a
- * Synap app). Stricter on one point: no `*` at all (`can()` matches exactly).
+ * Synap app, or on mock mode's loopback origin). Stricter on one point: no `*`
+ * at all (`can()` matches exactly).
  */
 function assertAppPermission(permission: string, origin: string): void {
   const segs = permission.split(".");
@@ -232,7 +252,7 @@ function assertAppPermission(permission: string, origin: string): void {
     fail("is not <subject>[.<kind>].<action> in lowercase (no *)");
   }
   if (segs.length === 3 && segs[0] !== "entity") fail(`names a kind, but "${segs[0]}" has none (only entity does)`);
-  if (SYNAP_APP_REVIEW_PERMISSIONS.includes(permission) && isSynapAppOrigin(origin)) return;
+  if (SYNAP_APP_REVIEW_PERMISSIONS.includes(permission) && (isSynapAppOrigin(origin) || isMockModeOrigin(origin))) return;
   if (!GRANT_ACTIONS.includes(segs[segs.length - 1])) {
     fail(`asks for "${segs[segs.length - 1]}", which an app cannot be granted (read, create, update, delete)`);
   }
@@ -405,7 +425,7 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
   };
 
   /** Off to the pod's consent: fresh PKCE + state, the transaction cookie set (extra cookies first). */
-  async function toPod(opts: { pod: string; next: string; space: string | null; prompt: "consent" | null }, extra: string[] = []) {
+  async function toPod(opts: { pod: string; next: string; space: string | null; prompt: "consent" | "login" | null }, extra: string[] = []) {
     const started = await startConnect({
       ...flow,
       pod: opts.pod,
@@ -445,7 +465,9 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
     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");
+    // `login` is a step-up of the pod's own sign-in; it never goes through Synap Cloud (a Cloud sign-in never counts).
+    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 });
@@ -463,6 +485,7 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
         ...flow,
         callbackUrl: request.url,
         transaction,
+        current: await store.read(request).catch(() => null),
         clientId,
         redirectUri,
         secret: config.secret,

package/src/connect/client.ts

@@ -66,8 +66,29 @@ export type PodErrorCode =
   | "pod_unreachable"
   /** The pod answered a redirect (a moved pod answers 308 from its old name): connect again at its new address. */
   | "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).
+ */
+export 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
@@ -86,6 +107,8 @@ export 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
@@ -297,14 +320,44 @@ function renewalError(err: unknown): PodError {
   }
 }
 
+/** The pod's step-up refusal (backend `STEP_UP_REQUIRED_MESSAGE`); the Hub's REST body carries only this text. */
+const STEP_UP_MESSAGE = "Confirm it's you before changing who or what can reach this pod.";
+
+/** The Control Plane's public problem codes (409, `{ error, code, recovery }`). */
+const CP_PROBLEMS: Readonly<Record<string, { code: PodErrorCode; recovery: PodRecovery }>> = {
+  CP_ACCOUNT_EMAIL_REQUIRED: { code: "email_unverified", recovery: "verify_email" },
+  FEDERATED_APPLICATION_ORIGIN_INSECURE: { code: "origin_insecure", recovery: "use_https" },
+};
+
+function isStepUp(obj: Record<string, unknown>): boolean {
+  const data = (v: unknown) => (v && typeof v === "object" ? (v as Record<string, unknown>) : {});
+  // tRPC shape (`error.data.reasonCode`), a flat reasonCode, or the Hub REST body: `{ error: <message> }`.
+  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;
+}
+
+/**
+ * A 403 or 409 body → its typed code. A step-up is read on a 403 only, a Control
+ * Plane problem on a 409 only; everything else keeps the plain `forbidden` /
+ * `door_unsupported` / `conflict`, so a typed refusal is never read as a generic one.
+ */
+export function classifyRefusal(status: 403 | 409 | number, body: unknown): { code: PodErrorCode; recovery?: PodRecovery } {
+  const obj = body && typeof body === "object" ? (body as Record<string, unknown>) : {};
+  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] : undefined;
+  return problem ?? { code: "conflict" };
+}
+
 function errorFor(status: number, body: unknown, retryAfter: string | null, now: number): PodError {
   const obj = body && typeof body === "object" ? (body as Record<string, unknown>) : {};
   const detail = typeof obj.error === "string" ? obj.error : typeof obj.message === "string" ? obj.message : undefined;
   const base = { status, ...(detail !== undefined ? { 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);
@@ -501,6 +554,9 @@ export function createPodClient(connection: PodConnection, opts: PodClientOption
       offset: clamp(opts.offset, 0, Number.MAX_SAFE_INTEGER),
       sort: opts.sort,
       includePodWide: opts.includePodWide,
+      facetSlug: opts.facetSlug,
+      // Sent only when asked: the default request stays the 1.5.0 one.
+      includeFacets: opts.includeFacets ? true : undefined,
     }, (data) => (Array.isArray(data) ? (data.filter(hasId) as PodEntity[]) : null));
   }
 

package/src/connect/flow.ts

@@ -48,6 +48,8 @@ export 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;
 }
 
@@ -74,8 +76,13 @@ export 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;
 }
 
@@ -124,7 +131,7 @@ export async function startConnect(opts: StartConnectOptions): Promise<StartedCo
   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: ConnectTransaction = {
     v: 1,
@@ -137,6 +144,7 @@ export async function startConnect(opts: StartConnectOptions): Promise<StartedCo
     verifier,
     resource,
     next: opts.next ?? null,
+    ...(opts.prompt === "login" ? { stepUp: true } : {}),
     createdAt: now,
   };
   const expiresAt = now + TRANSACTION_TTL_MS;
@@ -179,6 +187,13 @@ export 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;
 }
 
 export interface CallbackResult {
@@ -219,6 +234,11 @@ export async function handleCallback(opts: HandleCallbackOptions): Promise<Callb
     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,
@@ -226,6 +246,7 @@ export async function handleCallback(opts: HandleCallbackOptions): Promise<Callb
     tokenEndpoint: tx.tokenEndpoint,
     revocationEndpoint: tx.revocationEndpoint,
     now: (opts.now ?? Date.now)(),
+    ...(device ? { previous: device } : {}),
   });
   return { connection, next: tx.next };
 }

package/src/connect/hub-types.ts

@@ -38,9 +38,22 @@ export interface PodEntity {
   /** ISO 8601. */
   createdAt?: string;
   updatedAt?: string;
+  /** The roles it wears, with `includeFacets`; absent when it wears none. */
+  facetSlugs?: string[];
+  /** Each role's overlay, with `includeFacets`; absent when it wears none. */
+  facets?: PodEntityFacet[];
   [key: string]: unknown;
 }
 
+/** One role an entity wears (`FacetRowAnnotation`). */
+export interface PodEntityFacet {
+  facetId: string;
+  /** The role, e.g. `lead`. */
+  slug: string;
+  properties: Record<string, unknown>;
+  status: string | null;
+}
+
 export interface ListEntitiesOptions {
   /** One granted space. Omitted: every space the connection can read. */
   workspaceId?: string;
@@ -53,6 +66,10 @@ export interface ListEntitiesOptions {
   sort?: string;
   /** With `workspaceId`: also the person's pod-wide rows (the pod's default: true). */
   includePodWide?: boolean;
+  /** Only the entities wearing this role, e.g. `lead`. */
+  facetSlug?: string;
+  /** Put `facetSlugs` and `facets` on each row that wears a role. */
+  includeFacets?: boolean;
 }
 
 export type PodConnectionSource = "graph" | "property" | "thread" | "context_channel" | "focus_session";

package/src/connect/index.ts

@@ -30,6 +30,7 @@ export type {
   PodClientOptions,
   PodError,
   PodErrorCode,
+  PodRecovery,
   PodRefusalReason,
   PodResult,
   PodWriteResult,
@@ -48,6 +49,7 @@ export type {
   PodEntity,
   PodEntityConnection,
   PodEntityConnections,
+  PodEntityFacet,
   PodFileUrl,
   PodFocusSession,
   PodSessionSlot,