@synap-core/sdk 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synap-core/sdk",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Type-safe tRPC client SDK for Synap data pods, public-door client, and server-only pod-app sign-in",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -8,22 +8,34 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
     "./public": {
-      "types": "./dist/public.d.ts",
+      "types": {
+        "import": "./dist/public.d.ts",
+        "require": "./dist/public.d.cts"
+      },
       "import": "./dist/public.js",
       "require": "./dist/public.cjs"
     },
     "./testing": {
-      "types": "./dist/testing.d.ts",
+      "types": {
+        "import": "./dist/testing.d.ts",
+        "require": "./dist/testing.d.cts"
+      },
       "import": "./dist/testing.js",
       "require": "./dist/testing.cjs"
     },
     "./connect": {
-      "types": "./dist/connect.d.ts",
+      "types": {
+        "import": "./dist/connect.d.ts",
+        "require": "./dist/connect.d.cts"
+      },
       "edge-light": "./dist/connect.js",
       "workerd": "./dist/connect.js",
       "browser": "./dist/connect.browser.js",
@@ -31,11 +43,23 @@
       "require": "./dist/connect.cjs"
     }
   },
+  "sideEffects": [
+    "./dist/connect.js",
+    "./dist/connect.cjs",
+    "./dist/connect.browser.js",
+    "./dist/connect.browser.cjs",
+    "./src/connect/index.ts",
+    "./src/connect/browser.ts"
+  ],
   "files": [
     "dist",
     "src",
-    "!src/__tests__"
+    "!src/__tests__",
+    "CHANGELOG.md"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "keywords": [
     "synap",
     "sdk",

package/src/connect/auth.ts

@@ -34,6 +34,7 @@ import { serializeCookie, parseCookies } from "./encoding";
 import { createPodClient, type PodClient, type PodClientOptions } from "./client";
 import { assertPermissions, handleCallback, refreshConnection, revokeConnection, startConnect, TRANSACTION_TTL_MS } from "./flow";
 import { assertServerRuntime } from "./guard";
+import { isIpLiteral, LOOPBACK_HOSTS, SPACE_HINT_RE } from "./rules";
 import { assertAppSecret, type AppSecret } from "./seal";
 import { applySetCookies, cookieNames, createSealedCookieStore, markerCookie, readMarker, type ConnectionStore } from "./store";
 import type { AppRequest, ClientMetadataDocument, PodConnection } from "./types";
@@ -69,7 +70,12 @@ export const DEFAULT_PATHS: PodAppPaths = {
 export const REFRESH_WINDOW_MS = 5 * 60 * 1000;
 
 export interface PodAppAuthConfig {
-  /** The app's origin, e.g. https://studio.example.com (http only on localhost). */
+  /**
+   * The app's origin, e.g. https://studio.example.com. `http://localhost` is
+   * accepted for the SDK's MOCK pod only: every real pod, a local one
+   * included, refuses an http client_id and redirect_uri, so an app that signs
+   * in to a real pod runs on https (a tunnel in development).
+   */
   appUrl: string;
   /** Shown on the pod's consent screen (at most 100 characters). */
   clientName: string;
@@ -89,7 +95,11 @@ export interface PodAppAuthConfig {
    * "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). */
+  /**
+   * Accept a pod (and a Control Plane) on http://localhost: development
+   * against the SDK's mock pod (`@synap-core/sdk/testing`). A real local pod
+   * still refuses an app that is not on https (see `appUrl`).
+   */
   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;
@@ -108,9 +118,9 @@ export type RefreshStatus =
   | "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. */
+  /** The access token is spent and cannot be renewed (lapsed, or the pod moved: `error.code`): connect again. The session cookie is cleared (the marker stays). */
   | "expired"
-  /** The pod refused the refresh token (access removed): connect again. */
+  /** The pod refused the refresh token (access removed): connect again. The session cookie is cleared (the marker stays). */
   | "revoked"
   /** The pod could not be reached and the access token is spent: try later. */
   | "unavailable";
@@ -132,6 +142,30 @@ export interface RefreshOutcome {
   lapsed?: { podUrl: string };
 }
 
+export interface RefreshOptions {
+  /**
+   * Rotate now, whatever the access token's expiry says: the pod refused it
+   * (a Hub call answered `unauthorized` with `refreshable`). Needs a refresh
+   * token. If the pod refuses the refresh too, the outcome is `revoked` (or
+   * `expired`), never `kept`: the access token is known dead.
+   */
+  force?: boolean;
+}
+
+export interface PodAppClientOptions extends PodClientOptions {
+  /**
+   * Where the client may set cookies (a route handler, a server action): after
+   * a 401 it then renews the connection ONCE (rotate, seal, `persist` the
+   * Set-Cookie values, retry the request once). The rotation spends the old
+   * refresh token, so it is never done where its result cannot be stored: a
+   * server component passes no `persist`, and a 401 there answers
+   * `unauthorized` with `refreshable` (see `RefreshOptions.force`).
+   */
+  persist?: (setCookies: string[]) => void | Promise<void>;
+  /** The request (or its Cookie header) the connection came from: chunks a larger old cookie left are cleared. */
+  request?: Request | string | null;
+}
+
 export interface PodAppAuth {
   clientId: string;
   redirectUri: string;
@@ -161,15 +195,48 @@ export interface PodAppAuth {
    * (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;
+  /** For `proxy.ts` / a route handler: rotate near expiry (or now, `force`), lost-race safe. */
+  refreshIfNeeded(request: Request, opts?: RefreshOptions): Promise<RefreshOutcome>;
+  /** A Hub REST client for the connection (renewing it after a 401 when it can `persist`). */
+  client(connection: PodConnection, opts?: PodAppClientOptions): PodClient;
 }
 
-const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
 const TEMPLATE_SLUG_RE = /^[a-z0-9][a-z0-9._/-]{0,99}$/;
 const MAX_METADATA_BYTES = 5 * 1024;
+const MAX_REQUESTS = 32;
+/** How long a refused refresh is not asked again while the access token still works ("kept"). */
+const KEPT_RETRY_MS = 60_000;
+
+/** The pod's grant actions: the only verbs a pod app may ask for (client-metadata.ts `assertAppPermission`). */
+const GRANT_ACTIONS = ["read", "create", "update", "delete"];
+/** The review verbs only an official Synap app (`https://<id>.synap.live`) may ask for, spelled exactly. */
+const SYNAP_APP_REVIEW_PERMISSIONS = ["proposal.approve", "proposal.reject"];
+const PERMISSION_SEGMENT_RE = /^[a-z0-9][a-z0-9_-]*$/;
+
+function isSynapAppOrigin(origin: string): boolean {
+  return /^https:\/\/[a-z0-9]([a-z0-9-]*[a-z0-9])?\.synap\.live$/.test(origin);
+}
+
+/**
+ * One `synap_requests[].permission`, refused here exactly when the pod would
+ * refuse it: `<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).
+ */
+function assertAppPermission(permission: string, origin: string): void {
+  const segs = permission.split(".");
+  const fail = (why: string) => {
+    throw new ConnectError("misconfigured", `requests: "${permission}" ${why}`);
+  };
+  if (segs.length < 2 || segs.length > 3 || segs.some((seg) => !PERMISSION_SEGMENT_RE.test(seg))) {
+    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 (!GRANT_ACTIONS.includes(segs[segs.length - 1])) {
+    fail(`asks for "${segs[segs.length - 1]}", which an app cannot be granted (read, create, update, delete)`);
+  }
+}
 
 function appOriginOf(appUrl: string): { origin: string; secure: boolean } {
   let url: URL;
@@ -179,8 +246,11 @@ function appOriginOf(appUrl: string): { origin: string; secure: boolean } {
     throw new ConnectError("misconfigured", "appUrl is not a URL");
   }
   const secure = url.protocol === "https:";
-  if (!secure && !(url.protocol === "http:" && LOOPBACK.has(url.hostname))) {
-    throw new ConnectError("misconfigured", "appUrl must be https (http only on localhost)");
+  if (!secure && !(url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname))) {
+    throw new ConnectError("misconfigured", "appUrl must be https (http only on localhost, for the SDK's mock pod)");
+  }
+  if (secure && isIpLiteral(url.hostname)) {
+    throw new ConnectError("misconfigured", "appUrl must use a domain name: the pod refuses an IP address client_id");
   }
   if (url.pathname !== "/" || url.search || url.hash || url.username || url.password) {
     throw new ConnectError("misconfigured", "appUrl is an origin: no path, query, fragment or credentials");
@@ -194,7 +264,12 @@ function assertPath(name: string, path: string): void {
   }
 }
 
-/** The CIMD document (spec 17 §6.1), validated the way the pod will validate it. */
+/**
+ * The app's client metadata document (its client_id URL serves it). Refuses,
+ * at setup, every document the pod would refuse at sign-in: the permissions
+ * (`assertAppPermission`), at most 32 requests counted as sent, duplicates
+ * included, an IP address origin, the 5 KB cap.
+ */
 export function buildClientMetadata(opts: {
   appUrl: string;
   clientName: string;
@@ -207,9 +282,13 @@ export function buildClientMetadata(opts: {
   for (const [name, path] of Object.entries(paths)) assertPath(name, path);
   const clientName = opts.clientName.trim();
   if (!clientName || clientName.length > 100) throw new ConnectError("misconfigured", "clientName must be 1-100 characters");
+  // The pod counts the entries as sent, before it drops duplicates.
+  if (opts.requests.length === 0 || opts.requests.length > MAX_REQUESTS) {
+    throw new ConnectError("misconfigured", `requests must hold 1-${MAX_REQUESTS} entries (duplicates count)`);
+  }
   assertPermissions(opts.requests.map((r) => r.permission));
   for (const r of opts.requests) {
-    if (r.permission.includes("*")) throw new ConnectError("misconfigured", "a permission cannot contain *");
+    assertAppPermission(r.permission, origin);
     if (typeof r.reason !== "string" || !r.reason.trim() || r.reason.length > 200) {
       throw new ConnectError("misconfigured", `the reason for ${r.permission} must be 1-200 characters`);
     }
@@ -335,7 +414,7 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
       permissions,
       secret: config.secret,
       resource: config.resource,
-      spaceHint: opts.space && /^[A-Za-z0-9_-]{1,64}$/.test(opts.space) ? opts.space : null,
+      spaceHint: opts.space && SPACE_HINT_RE.test(opts.space) ? opts.space : null,
       next: opts.next,
       prompt: opts.prompt,
       allowInsecureLoopback: config.allowInsecureLoopback,
@@ -422,7 +501,7 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
         clientId,
         secret: config.secret,
         next,
-        spaceHint: space && /^[A-Za-z0-9_-]{1,64}$/.test(space) ? space : null,
+        spaceHint: space && SPACE_HINT_RE.test(space) ? space : null,
         prompt: formField(form, "prompt") === "consent" ? "consent" : null,
         now,
       });
@@ -459,7 +538,10 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
     }
   }
 
-  async function refreshIfNeeded(request: Request): Promise<RefreshOutcome> {
+  /** Refresh tokens whose refresh failed while their access token still worked ("kept"): not asked again for a minute. */
+  const keptFailures = new Map<string, { error: ConnectError; at: number }>();
+
+  async function refreshIfNeeded(request: Request, opts: RefreshOptions = {}): Promise<RefreshOutcome> {
     const connection = await store.read(request);
     const unchanged = (status: RefreshStatus, conn: PodConnection | null, error?: ConnectError): RefreshOutcome => ({
       status,
@@ -474,12 +556,16 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
     }
     if (isPrefetchOrAsset(request)) return unchanged("skipped", connection);
     const t = now();
-    const accessLives = connection.accessExpiresAt > t;
-    if (connection.accessExpiresAt - t > REFRESH_WINDOW_MS) return unchanged("fresh", connection);
+    // Forced: the pod already refused the access token, whatever its expiry says.
+    const accessLives = !opts.force && connection.accessExpiresAt > t;
+    if (!opts.force && connection.accessExpiresAt - t > REFRESH_WINDOW_MS) return unchanged("fresh", connection);
     if (!connection.refreshToken) {
-      // The pod issued none (before PB3): the connection ends with its access token.
+      // The pod issued none: the connection ends with its access token.
       return accessLives ? unchanged("fresh", connection) : unchanged("expired", null, new ConnectError("expired", "No refresh token; connect again"));
     }
+    for (const [token, f] of keptFailures) if (t - f.at >= KEPT_RETRY_MS) keptFailures.delete(token);
+    const keptFailure = accessLives ? keptFailures.get(connection.refreshToken) : undefined;
+    if (keptFailure) return unchanged("kept", connection, keptFailure.error);
     let next: PodConnection;
     try {
       next = await refreshConnection(connection, flow);
@@ -487,13 +573,24 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
       const e = fail(err, "refresh");
       // LOST-RACE SAFE: another instance may have redeemed the token at the
       // same moment; the pod refuses the concurrent loser without a family
-      // revoke (PB3), and the access token we hold is still good. Keep it and
-      // set NOTHING, so the winner's cookie stands. (Within one process the
-      // race never reaches the pod: `refreshConnection` is single-flight.)
-      // Never clear the cookie here either: a clear racing the winner's
-      // Set-Cookie would sign the person out.
-      if (accessLives) return unchanged("kept", connection, e);
-      if (e.code === "revoked" || e.code === "expired") return unchanged(e.code, null, e);
+      // revoke, and the access token we hold is still good. Keep it and set
+      // NOTHING, so the winner's cookie stands. (Within one process the race
+      // never reaches the pod: `refreshConnection` is single-flight.) Never
+      // clear the cookie here either: a clear racing the winner's Set-Cookie
+      // would sign the person out. The failure is remembered for a minute, so
+      // each page view does not ask the pod again.
+      if (accessLives) {
+        keptFailures.set(connection.refreshToken, { error: e, at: t });
+        return unchanged("kept", connection, e);
+      }
+      // Spent and refused for good: clear the session cookie, so every later
+      // page view does not post the dead token to /token again (that budget is
+      // per caller IP: the app server, shared by all its visitors). The marker
+      // stays: the person still reads "expired, connect again to <pod>".
+      if (e.code === "revoked" || e.code === "expired" || e.code === "pod_moved") {
+        const cleared = await store.clear(request).catch(() => [] as string[]);
+        return { status: e.code === "revoked" ? "revoked" : "expired", connection: null, setCookies: cleared, cookieHeader: applySetCookies(request.headers.get("cookie"), cleared), error: e };
+      }
       return unchanged("unavailable", null, e);
     }
     // PERSIST BEFORE USE: the old refresh token is spent now; only a stored
@@ -517,6 +614,30 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
     };
   }
 
+  /**
+   * The client's renewal after a 401: rotate (single-flight per
+   * process), PERSIST through `persist`, then hand the new connection over.
+   * A rotation that cannot be persisted is not used (persist before use).
+   */
+  function renewer(persist: NonNullable<PodAppClientOptions["persist"]>, source: Request | string | null | undefined) {
+    return async (connection: PodConnection): Promise<PodConnection> => {
+      let next: PodConnection;
+      try {
+        next = await refreshConnection(connection, flow);
+      } catch (err) {
+        throw fail(err, "refresh");
+      }
+      try {
+        const cookies = await store.write(next, asRequest(source ?? null));
+        await persist([...cookies, marker(next.podUrl)]);
+      } catch (err) {
+        fail(err, "refresh");
+        throw new ConnectError("expired", "The renewed connection could not be stored; connect again");
+      }
+      return next;
+    };
+  }
+
   return {
     clientId,
     redirectUri,
@@ -530,6 +651,14 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
       return (await store.read(request)) ? null : lapsedIn(request);
     },
     refreshIfNeeded,
-    client: (connection, opts) => createPodClient(connection, { fetch: config.fetch, now: config.now, ...opts }),
+    client(connection, opts = {}) {
+      const { persist, request, ...clientOpts } = opts;
+      return createPodClient(connection, {
+        fetch: config.fetch,
+        now: config.now,
+        ...(persist ? { renew: renewer(persist, request) } : {}),
+        ...clientOpts,
+      });
+    },
   };
 }