@synap-core/sdk 1.1.0 → 1.3.0

package/src/connect/flow.ts

@@ -0,0 +1,449 @@
+/**
+ * The OAuth 2.1 authorization-code flow of a pod app (spec 17 §6.4-§6.7), as
+ * plain functions over a SEALED transaction string. `createPodAppAuth` wires
+ * them to cookies and route handlers; use these directly for another store.
+ *
+ * Security properties (each pinned by a test in src/__tests__/connect.*):
+ *  - PKCE S256 with a fresh 32-byte verifier per sign-in;
+ *  - a fresh 32-byte `state`, compared in constant time on the callback;
+ *  - mix-up defence (RFC 9207): the callback's `iss` must equal the issuer the
+ *    transaction was started with; a missing `iss` is refused too;
+ *  - the transaction lives 10 minutes and is sealed (AES-GCM) under the app
+ *    secret with its own purpose: tampered, foreign or stale → refused;
+ *  - the `error` of a callback is honoured only AFTER `iss` and `state` match,
+ *    so a forged error cannot end someone else's sign-in;
+ *  - tokens never leave the server: nothing here returns a value meant for a
+ *    browser except the authorize URL.
+ */
+import { ConnectError, fromOAuthError, retryAfterSeconds } from "./errors";
+import { constantTimeEqual, pkceChallenge, randomToken } from "./encoding";
+import { discoverPod, type DiscoverOptions } from "./discovery";
+import { seal, unseal, type AppSecret } from "./seal";
+import type { PodConnection, PodGrant, PodIssuer, PodUser } from "./types";
+
+/** How long a started sign-in stays valid. */
+export const TRANSACTION_TTL_MS = 10 * 60 * 1000;
+/** The refresh token's idle life when the pod does not say (spec 17 F5: 30 days). */
+export const DEFAULT_REFRESH_IDLE_MS = 30 * 24 * 60 * 60 * 1000;
+const DEFAULT_ACCESS_TTL_SEC = 3600;
+const TIMEOUT_MS = 10_000;
+
+/** A sealed `ConnectTransaction`: opaque, safe to put in an HttpOnly cookie. */
+export type SealedTransaction = string & { readonly __sealedTransaction: true };
+
+/** What a started sign-in remembers (sealed; never sent to the pod). */
+export 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;
+}
+
+export interface FlowOptions {
+  fetch?: typeof fetch;
+  now?: () => number;
+}
+
+export 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;
+}
+
+export 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;
+}
+
+const PERMISSION_RE = /^[a-z][a-z0-9_-]*(\.[a-z0-9_-]+)+$/i;
+
+export function assertPermissions(permissions: readonly string[]): string[] {
+  const unique = [...new Set(permissions)];
+  if (unique.length === 0 || unique.length > 32 || unique.some((p) => !PERMISSION_RE.test(p))) {
+    throw new ConnectError(
+      "misconfigured",
+      "permissions must be 1-32 grant-grammar strings such as entity.post.read (no *)",
+    );
+  }
+  return unique;
+}
+
+export async function startConnect(opts: StartConnectOptions): Promise<StartedConnect> {
+  const now = (opts.now ?? Date.now)();
+  const permissions = assertPermissions(opts.permissions);
+  const issuer =
+    typeof opts.pod === "string"
+      ? await discoverPod(opts.pod, { fetch: opts.fetch, now: opts.now, allowInsecureLoopback: opts.allowInsecureLoopback } satisfies DiscoverOptions)
+      : opts.pod;
+  const verifier = randomToken();
+  const state = randomToken();
+  const resourceKind = opts.resource === undefined ? "api/hub" : opts.resource;
+  const resource = resourceKind ? `${issuer.issuer}/${resourceKind}` : null;
+
+  const url = new URL(issuer.authorizationEndpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", opts.clientId);
+  url.searchParams.set("redirect_uri", opts.redirectUri);
+  url.searchParams.set("scope", permissions.join(" "));
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", await pkceChallenge(verifier));
+  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);
+
+  const tx: ConnectTransaction = {
+    v: 1,
+    issuer: issuer.issuer,
+    tokenEndpoint: issuer.tokenEndpoint,
+    revocationEndpoint: issuer.revocationEndpoint,
+    clientId: opts.clientId,
+    redirectUri: opts.redirectUri,
+    state,
+    verifier,
+    resource,
+    next: opts.next ?? null,
+    createdAt: now,
+  };
+  const expiresAt = now + TRANSACTION_TTL_MS;
+  const transaction = (await seal(tx, {
+    secret: opts.secret,
+    purpose: "synap-connect/transaction",
+    expiresAt,
+  })) as SealedTransaction;
+  return { authorizeUrl: url.toString(), transaction, expiresAt, issuer };
+}
+
+/** Open a sealed transaction; refuses tampered, foreign and stale ones. */
+export async function openTransaction(
+  sealed: string | null | undefined,
+  opts: { secret: AppSecret; now?: () => number },
+): Promise<ConnectTransaction> {
+  if (!sealed) throw new ConnectError("expired_transaction", "No sign-in in progress in this browser");
+  const opened = await unseal<ConnectTransaction>(sealed, {
+    secret: opts.secret,
+    purpose: "synap-connect/transaction",
+    now: (opts.now ?? Date.now)(),
+  });
+  if (!opened.ok) {
+    throw new ConnectError(
+      "expired_transaction",
+      opened.reason === "expired" ? "The sign-in is older than 10 minutes" : "The sign-in cookie is not one this app sealed",
+    );
+  }
+  const tx = opened.value;
+  if (!tx || tx.v !== 1 || typeof tx.state !== "string" || typeof tx.issuer !== "string") {
+    throw new ConnectError("expired_transaction", "The sign-in cookie is not one this app sealed");
+  }
+  return tx;
+}
+
+export 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;
+}
+
+export interface CallbackResult {
+  connection: PodConnection;
+  /** The same-origin path the sign-in was started for. */
+  next: string | null;
+}
+
+export async function handleCallback(opts: HandleCallbackOptions): Promise<CallbackResult> {
+  const tx = await openTransaction(opts.transaction, opts);
+  if (tx.clientId !== opts.clientId || tx.redirectUri !== opts.redirectUri) {
+    throw new ConnectError("misconfigured", "The sign-in was started for another client_id or redirect_uri");
+  }
+  const params = new URL(opts.callbackUrl).searchParams;
+
+  // RFC 9207: the answer must name the AS this sign-in went to. Absent = refused
+  // (every Synap pod sends it, and discovery required it).
+  const iss = params.get("iss");
+  if (iss === null || iss !== tx.issuer) {
+    throw new ConnectError("mismatch", iss === null ? "The answer names no issuer" : "The answer comes from another pod than the one asked");
+  }
+  const state = params.get("state");
+  if (state === null || !constantTimeEqual(state, tx.state)) {
+    throw new ConnectError("mismatch", "The answer does not belong to the sign-in this browser started");
+  }
+  const error = params.get("error");
+  if (error !== null) {
+    throw new ConnectError(fromOAuthError(error, "authorize"), `The pod answered ${error}`, { oauthError: error });
+  }
+  const code = params.get("code");
+  if (!code) throw new ConnectError("server_error", "The answer carries no code");
+
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: tx.redirectUri,
+    client_id: tx.clientId,
+    code_verifier: tx.verifier,
+  });
+  if (tx.resource) body.set("resource", tx.resource);
+  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)(),
+  });
+  return { connection, next: tx.next };
+}
+
+async function tokenRequest(
+  endpoint: string,
+  body: URLSearchParams,
+  during: "token" | "refresh",
+  opts: FlowOptions,
+): Promise<Record<string, unknown>> {
+  const doFetch = opts.fetch ?? fetch;
+  let res: Response;
+  try {
+    res = await doFetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+      body: body.toString(),
+      redirect: "manual",
+      signal: typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(TIMEOUT_MS) : undefined,
+    });
+  } catch {
+    throw new ConnectError("pod_unreachable", "The pod's token endpoint did not answer");
+  }
+  if (res.status === 429) {
+    throw new ConnectError("rate_limited", "The pod asked to slow down", {
+      retryAfterSec: retryAfterSeconds(res.headers.get("retry-after"), (opts.now ?? Date.now)()),
+    });
+  }
+  if (res.status >= 500) throw new ConnectError("pod_unreachable", `The token endpoint answered ${res.status}`);
+  let json: unknown;
+  try {
+    json = await res.json();
+  } catch {
+    throw new ConnectError("server_error", `The token endpoint answered ${res.status} without JSON`);
+  }
+  const obj = json && typeof json === "object" && !Array.isArray(json) ? (json as Record<string, unknown>) : {};
+  if (res.status !== 200) {
+    const oauthError = typeof obj.error === "string" ? obj.error : "server_error";
+    throw new ConnectError(fromOAuthError(oauthError, during), `The token endpoint answered ${oauthError}`, { oauthError });
+  }
+  return obj;
+}
+
+function parseGrant(value: unknown): PodGrant[] | null {
+  if (!Array.isArray(value)) return null;
+  const out: PodGrant[] = [];
+  for (const g of value) {
+    if (!g || typeof g !== "object") return null;
+    const { permission, workspaceId, workspaceName } = g as Record<string, unknown>;
+    if (typeof permission !== "string" || typeof workspaceId !== "string") return null;
+    out.push({ permission, workspaceId, workspaceName: typeof workspaceName === "string" ? workspaceName : "" });
+  }
+  return out;
+}
+
+function parseUser(value: unknown): PodUser | null {
+  if (!value || typeof value !== "object") return null;
+  const { id, name } = value as Record<string, unknown>;
+  return typeof id === "string" ? { id, name: typeof name === "string" ? name : "" } : null;
+}
+
+/**
+ * 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.
+ */
+export function parseTokenResponse(
+  body: Record<string, unknown>,
+  ctx: {
+    podUrl: string;
+    clientId: string;
+    tokenEndpoint: string;
+    revocationEndpoint: string | null;
+    now: number;
+    previous?: PodConnection;
+  },
+): PodConnection {
+  const { access_token, token_type, expires_in, scope, refresh_token, refresh_token_expires_in } = body;
+  if (typeof access_token !== "string" || access_token === "") {
+    throw new ConnectError("server_error", "The token response has no access_token");
+  }
+  if (typeof token_type !== "string" || token_type.toLowerCase() !== "bearer") {
+    throw new ConnectError("server_error", "The token response is not a Bearer token");
+  }
+  if (expires_in !== undefined && (typeof expires_in !== "number" || !Number.isFinite(expires_in) || expires_in < 0)) {
+    throw new ConnectError("server_error", "The token response has an invalid expires_in");
+  }
+  const grant = parseGrant(body.synap_grant) ?? ctx.previous?.grant ?? null;
+  const user = parseUser(body.synap_user) ?? ctx.previous?.user ?? null;
+  if (!grant || !user) {
+    throw new ConnectError("pod_unsupported", "The token response lacks synap_grant / synap_user (pod older than app sign-in)");
+  }
+  const scopes =
+    typeof scope === "string" ? scope.split(/\s+/).filter(Boolean) : (ctx.previous?.scope ?? [...new Set(grant.map((g) => g.permission))]);
+  const connection: PodConnection = {
+    podUrl: ctx.podUrl,
+    clientId: ctx.clientId,
+    tokenEndpoint: ctx.tokenEndpoint,
+    revocationEndpoint: ctx.revocationEndpoint,
+    accessToken: access_token,
+    accessExpiresAt: ctx.now + (typeof expires_in === "number" ? expires_in : DEFAULT_ACCESS_TTL_SEC) * 1000,
+    scope: scopes,
+    grant,
+    user,
+    connectedAt: ctx.previous?.connectedAt ?? ctx.now,
+  };
+  if (typeof refresh_token === "string" && refresh_token !== "") {
+    connection.refreshToken = refresh_token;
+    const idle =
+      typeof refresh_token_expires_in === "number" && Number.isFinite(refresh_token_expires_in) && refresh_token_expires_in > 0
+        ? refresh_token_expires_in * 1000
+        : DEFAULT_REFRESH_IDLE_MS;
+    connection.refreshExpiresAt = ctx.now + idle;
+  }
+  return connection;
+}
+
+/**
+ * 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.
+ */
+export const ROTATION_MEMORY_MS = 2 * 60 * 1000;
+
+interface Rotation {
+  result: Promise<PodConnection>;
+  /** When it succeeded (ms, the caller's clock); undefined while in flight. */
+  settledAt?: number;
+}
+
+/** Spent refresh token → its rotation, per process. */
+const rotations = new Map<string, Rotation>();
+
+function pruneRotations(now: number): void {
+  for (const [token, r] of rotations) {
+    if (r.settledAt !== undefined && now - r.settledAt > ROTATION_MEMORY_MS) rotations.delete(token);
+  }
+}
+
+/**
+ * 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`.
+ */
+export function refreshConnection(connection: PodConnection, opts: FlowOptions = {}): Promise<PodConnection> {
+  const clock = opts.now ?? Date.now;
+  const now = clock();
+  const token = connection.refreshToken;
+  if (!token) return Promise.reject(new ConnectError("expired", "The pod issued no refresh token; connect again"));
+  pruneRotations(now);
+  const known = rotations.get(token);
+  if (known) return known.result;
+  if (connection.refreshExpiresAt !== undefined && connection.refreshExpiresAt <= now) {
+    return Promise.reject(new ConnectError("expired", "The connection was idle too long; connect again"));
+  }
+  const body = new URLSearchParams({ grant_type: "refresh_token", refresh_token: token, client_id: connection.clientId });
+  const rotation: Rotation = {
+    result: tokenRequest(connection.tokenEndpoint, body, "refresh", opts)
+      .then((json) => {
+        const next = parseTokenResponse(json, {
+          podUrl: connection.podUrl,
+          clientId: connection.clientId,
+          tokenEndpoint: connection.tokenEndpoint,
+          revocationEndpoint: connection.revocationEndpoint,
+          now: clock(),
+          previous: connection,
+        });
+        rotation.settledAt = clock();
+        return next;
+      })
+      .catch((err: unknown) => {
+        rotations.delete(token);
+        // The AS answers invalid_grant to an idle-expired AND a revoked token;
+        // the locally known idle deadline tells them apart.
+        if (err instanceof ConnectError && err.code === "revoked" && connection.refreshExpiresAt !== undefined && connection.refreshExpiresAt <= clock()) {
+          throw new ConnectError("expired", err.message, { oauthError: err.oauthError });
+        }
+        throw err;
+      }),
+  };
+  rotations.set(token, rotation);
+  return rotation.result;
+}
+
+/**
+ * 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.
+ */
+export async function revokeConnection(connection: PodConnection, opts: FlowOptions = {}): Promise<{ revoked: boolean }> {
+  if (!connection.revocationEndpoint) return { revoked: false };
+  const doFetch = opts.fetch ?? fetch;
+  let revoked = true;
+  const tokens: Array<[string | undefined, string]> = [
+    [connection.refreshToken, "refresh_token"],
+    [connection.accessToken, "access_token"],
+  ];
+  for (const [token, hint] of tokens) {
+    if (!token) continue;
+    try {
+      const res = await doFetch(connection.revocationEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ token, token_type_hint: hint, client_id: connection.clientId }).toString(),
+        redirect: "manual",
+        signal: typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(TIMEOUT_MS) : undefined,
+      });
+      if (res.status !== 200) revoked = false;
+    } catch {
+      revoked = false;
+    }
+  }
+  return { revoked };
+}

package/src/connect/guard.ts

@@ -0,0 +1,25 @@
+/**
+ * `@synap-core/sdk/connect` holds pod tokens and the app secret: it must never
+ * run in a browser. Two guards:
+ *
+ *  - BUILD: the package's `exports["./connect"]` maps the `browser` condition
+ *    to `connect.browser` (src/connect/browser.ts), which exports nothing and
+ *    throws on load, so a client bundle never contains this code and a strict
+ *    ESM bundler fails on the missing named import. Server and edge
+ *    conditions (`edge-light`, `workerd`, `import`, `require`) get the real
+ *    module;
+ *  - RUNTIME: importing the real module where `window` and `document` exist
+ *    throws (a test DOM, a misconfigured bundler).
+ */
+export const BROWSER_REFUSAL =
+  "@synap-core/sdk/connect is server-only: it holds the pod's tokens and the app secret. " +
+  "Import it from route handlers, proxy.ts or server code, never from a client component.";
+
+export function isBrowserRuntime(): boolean {
+  const g = globalThis as { window?: unknown; document?: unknown };
+  return typeof g.window !== "undefined" && typeof g.document !== "undefined";
+}
+
+export function assertServerRuntime(): void {
+  if (isBrowserRuntime()) throw new Error(BROWSER_REFUSAL);
+}

package/src/connect/index.ts

@@ -0,0 +1,59 @@
+/**
+ * `@synap-core/sdk/connect` — pod-app sign-in, SERVER-ONLY (spec 17 §10.1,
+ * doc 18 § SDK): an app connects to a person's own pod as an OAuth 2.1 public
+ * client (CIMD client_id, PKCE S256, `iss`-checked answers), keeps the pod
+ * token on its server in a sealed HttpOnly cookie, refreshes it in `proxy.ts`,
+ * and reads/writes the pod's Hub API with typed results.
+ *
+ * Framework-free and Web-standard (Request/Response, WebCrypto): Node 18+,
+ * edge runtimes, workers. Throws when loaded in a browser (./guard.ts).
+ *
+ * Invariant (pinned by src/__tests__/connect.guard.test.ts): every file of
+ * this entry imports only its siblings.
+ */
+import { assertServerRuntime } from "./guard";
+
+assertServerRuntime();
+
+export { createPodAppAuth, buildClientMetadata, DEFAULT_PATHS, REFRESH_WINDOW_MS } from "./auth";
+export type { PodAppAuth, PodAppAuthConfig, PodAppPaths, RefreshOutcome, RefreshStatus } from "./auth";
+export {
+  discoverPod,
+  canonicalPodUrl,
+  acceptLaunch,
+  safeNextPath,
+  cloudConnectAvailable,
+  startCloudConnect,
+} from "./discovery";
+export type { DiscoverOptions, LaunchHint } from "./discovery";
+export {
+  startConnect,
+  openTransaction,
+  handleCallback,
+  refreshConnection,
+  revokeConnection,
+  parseTokenResponse,
+  TRANSACTION_TTL_MS,
+  DEFAULT_REFRESH_IDLE_MS,
+  ROTATION_MEMORY_MS,
+} from "./flow";
+export type {
+  CallbackResult,
+  ConnectTransaction,
+  FlowOptions,
+  HandleCallbackOptions,
+  SealedTransaction,
+  StartConnectOptions,
+  StartedConnect,
+} from "./flow";
+export { createPodClient, can, reviewUrlFor } from "./client";
+export type { PodClient, PodClientOptions, PodError, PodErrorCode, PodResult, PodWriteResult, QueryValue } from "./client";
+export { createSealedCookieStore, cookieNames, applySetCookies, connectionExpiresAt } from "./store";
+export type { ConnectionStore, CookieNames, SealedCookieStoreOptions } from "./store";
+export { seal, unseal, MIN_SECRET_LENGTH } from "./seal";
+export type { AppSecret, Opened, SealPurpose } from "./seal";
+export { pkceChallenge } from "./encoding";
+export { ConnectError, isConnectError, parseConnectErrorCode, CONNECT_ERROR_CODES } from "./errors";
+export type { ConnectErrorCode } from "./errors";
+export { isBrowserRuntime } from "./guard";
+export type { AppRequest, ClientMetadataDocument, PodConnection, PodGrant, PodIssuer, PodUser } from "./types";

package/src/connect/seal.ts

@@ -0,0 +1,119 @@
+/**
+ * Sealed values: AES-256-GCM under a key derived (HKDF-SHA-256) from the app
+ * secret and a PURPOSE. The purpose is both the HKDF `info` and the GCM
+ * additional data, so a value sealed as a sign-in transaction never opens as a
+ * session, and the reverse. Any change to the sealed text, a wrong secret or a
+ * wrong purpose fails GCM authentication: the value reads as absent.
+ *
+ *   v1.<base64url(iv[12] ‖ ciphertext ‖ tag[16])>
+ *
+ * The plaintext carries its own expiry (`exp`, ms), checked after decryption,
+ * so a cookie kept past its Max-Age by a hostile client still expires.
+ */
+import { ConnectError } from "./errors";
+import { base64url, fromBase64url, fromUtf8, randomBytes, utf8 } from "./encoding";
+
+export type SealPurpose = "synap-connect/transaction" | "synap-connect/session";
+
+/** The app secret: one value, or several to rotate (the first seals, all open). */
+export type AppSecret = string | readonly string[];
+
+const VERSION = "v1";
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+export const MIN_SECRET_LENGTH = 32;
+const SALT = utf8("synap-connect/v1");
+
+const keyCache = new Map<string, Promise<CryptoKey>>();
+
+function secretsOf(secret: AppSecret): readonly string[] {
+  const list = typeof secret === "string" ? [secret] : secret;
+  if (list.length === 0 || list.some((s) => typeof s !== "string" || s.length < MIN_SECRET_LENGTH)) {
+    throw new ConnectError(
+      "misconfigured",
+      `The app session secret must be at least ${MIN_SECRET_LENGTH} characters (set SYNAP_APP_SESSION_SECRET on the server).`,
+    );
+  }
+  return list;
+}
+
+/** Fail fast at setup when the secret is unusable. */
+export function assertAppSecret(secret: AppSecret): void {
+  secretsOf(secret);
+}
+
+function keyFor(secret: string, purpose: SealPurpose): Promise<CryptoKey> {
+  const cacheKey = `${purpose}\u0000${secret}`;
+  let key = keyCache.get(cacheKey);
+  if (!key) {
+    key = crypto.subtle
+      .importKey("raw", utf8(secret), "HKDF", false, ["deriveKey"])
+      .then((base) =>
+        crypto.subtle.deriveKey(
+          { name: "HKDF", hash: "SHA-256", salt: SALT, info: utf8(purpose) },
+          base,
+          { name: "AES-GCM", length: 256 },
+          false,
+          ["encrypt", "decrypt"],
+        ),
+      );
+    keyCache.set(cacheKey, key);
+  }
+  return key;
+}
+
+export async function seal(value: unknown, opts: { secret: AppSecret; purpose: SealPurpose; expiresAt: number }): Promise<string> {
+  const [current] = secretsOf(opts.secret);
+  const iv = randomBytes(IV_BYTES);
+  const plaintext = utf8(JSON.stringify({ exp: opts.expiresAt, data: value }));
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv, additionalData: utf8(opts.purpose) },
+    await keyFor(current, opts.purpose),
+    plaintext,
+  );
+  const out = new Uint8Array(IV_BYTES + ciphertext.byteLength);
+  out.set(iv, 0);
+  out.set(new Uint8Array(ciphertext), IV_BYTES);
+  return `${VERSION}.${base64url(out)}`;
+}
+
+export 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`.
+ */
+export async function unseal<T = unknown>(
+  sealed: string,
+  opts: { secret: AppSecret; purpose: SealPurpose; now: number },
+): Promise<Opened<T>> {
+  const secrets = secretsOf(opts.secret);
+  const dot = sealed.indexOf(".");
+  if (dot < 0 || sealed.slice(0, dot) !== VERSION) return { ok: false, reason: "invalid" };
+  const bytes = fromBase64url(sealed.slice(dot + 1));
+  if (!bytes || bytes.length < IV_BYTES + TAG_BYTES) return { ok: false, reason: "invalid" };
+  const iv = bytes.slice(0, IV_BYTES);
+  const ciphertext = bytes.slice(IV_BYTES);
+  for (const secret of secrets) {
+    let plaintext: ArrayBuffer;
+    try {
+      plaintext = await crypto.subtle.decrypt(
+        { name: "AES-GCM", iv, additionalData: utf8(opts.purpose) },
+        await keyFor(secret, opts.purpose),
+        ciphertext,
+      );
+    } catch {
+      continue; // not this secret (or tampered): try the next, then refuse
+    }
+    let parsed: { exp?: unknown; data?: unknown };
+    try {
+      parsed = JSON.parse(fromUtf8(new Uint8Array(plaintext))) as { exp?: unknown; data?: unknown };
+    } catch {
+      return { ok: false, reason: "invalid" };
+    }
+    if (typeof parsed.exp !== "number") return { ok: false, reason: "invalid" };
+    if (parsed.exp <= opts.now) return { ok: false, reason: "expired" };
+    return { ok: true, value: parsed.data as T, expiresAt: parsed.exp };
+  }
+  return { ok: false, reason: "invalid" };
+}