@synap-core/sdk 1.2.0 → 1.4.0

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" | "synap-connect/cloud";
+
+/** 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" };
+}

package/src/connect/store.ts

@@ -0,0 +1,189 @@
+/**
+ * Where a PodConnection lives between requests. The default keeps it in the
+ * browser as a SEALED cookie (AES-GCM under the app secret, HttpOnly, Secure
+ * on https, SameSite=Lax, Path=/, `__Host-` prefix on https): the browser holds
+ * ciphertext it cannot read or forge, the pod token never reaches JS.
+ *
+ * Bring your own (a database, a KV) by implementing `ConnectionStore`; it
+ * answers with the Set-Cookie values to send (e.g. its own session id).
+ */
+import { canonicalPodUrl } from "./discovery";
+import { base64url, fromBase64url, fromUtf8, parseCookies, serializeCookie, utf8 } from "./encoding";
+import { ConnectError } from "./errors";
+import { seal, unseal, type AppSecret } from "./seal";
+import type { PodConnection, PodGrant } from "./types";
+
+export interface ConnectionStore {
+  /** The request's connection, or null (absent, tampered, foreign, expired). */
+  read(request: Request): Promise<PodConnection | null>;
+  /** Persist; returns the Set-Cookie header values to send. */
+  write(connection: PodConnection, request: Request): Promise<string[]>;
+  /** Forget; returns the Set-Cookie header values to send. */
+  clear(request: Request): Promise<string[]>;
+}
+
+export 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). */
+export function cookieNames(secure: boolean): CookieNames {
+  return secure
+    ? { session: "__Host-synap_session", transaction: "__Host-synap_tx", cloud: "__Host-synap_cloud", marker: "__Host-synap_seen" }
+    : { session: "synap_session", transaction: "synap_tx", cloud: "synap_cloud", marker: "synap_seen" };
+}
+
+/** The marker outlives the connection: as long as browsers keep a cookie (400 days). */
+export const MARKER_TTL_SEC = 400 * 24 * 60 * 60;
+
+/**
+ * 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.
+ */
+export function markerCookie(podUrl: string, opts: { secure: boolean; name?: string }): string {
+  return serializeCookie(opts.name ?? cookieNames(opts.secure).marker, base64url(utf8(podUrl)), {
+    maxAgeSec: MARKER_TTL_SEC,
+    secure: opts.secure,
+  });
+}
+
+/** The marker's pod URL, or null (absent, or not a canonical pod address). */
+export function readMarker(
+  cookieHeader: string | null,
+  opts: { secure: boolean; name?: string; allowInsecureLoopback?: boolean },
+): string | null {
+  const raw = parseCookies(cookieHeader).get(opts.name ?? cookieNames(opts.secure).marker);
+  const bytes = raw ? fromBase64url(raw) : null;
+  if (!bytes || bytes.length > 512) return null;
+  const podUrl = fromUtf8(bytes);
+  try {
+    return canonicalPodUrl(podUrl, opts) === podUrl ? podUrl : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Browsers cap a cookie near 4096 bytes; a big grant spans several. */
+const CHUNK_SIZE = 3800;
+const MAX_CHUNKS = 4;
+
+function chunkName(name: string, i: number): string {
+  return i === 0 ? name : `${name}.${i}`;
+}
+
+/** The sealed form: the grant grouped per space (it repeats the space otherwise). */
+interface StoredConnection extends Omit<PodConnection, "grant"> {
+  g: Array<[workspaceId: string, workspaceName: string, permissions: string[]]>;
+}
+
+function pack(c: PodConnection): StoredConnection {
+  const bySpace = new Map<string, [string, string, string[]]>();
+  for (const g of c.grant) {
+    const row = bySpace.get(g.workspaceId) ?? [g.workspaceId, g.workspaceName, []];
+    row[2].push(g.permission);
+    bySpace.set(g.workspaceId, row);
+  }
+  const { grant: _grant, ...rest } = c;
+  return { ...rest, g: [...bySpace.values()] };
+}
+
+function unpack(s: StoredConnection): PodConnection | null {
+  if (!s || typeof s.podUrl !== "string" || typeof s.accessToken !== "string" || !Array.isArray(s.g)) return null;
+  const { g, ...rest } = s;
+  const grant: PodGrant[] = g.flatMap(([workspaceId, workspaceName, permissions]) =>
+    permissions.map((permission) => ({ permission, workspaceId, workspaceName })),
+  );
+  return { ...rest, grant };
+}
+
+/** When the stored value stops being useful. */
+export function connectionExpiresAt(c: PodConnection): number {
+  return c.refreshToken && c.refreshExpiresAt !== undefined ? Math.max(c.refreshExpiresAt, c.accessExpiresAt) : c.accessExpiresAt;
+}
+
+export interface SealedCookieStoreOptions {
+  secret: AppSecret;
+  /** True on https (the default when the app URL is https). */
+  secure: boolean;
+  name?: string;
+  now?: () => number;
+}
+
+export function createSealedCookieStore(opts: SealedCookieStoreOptions): ConnectionStore {
+  const name = opts.name ?? cookieNames(opts.secure).session;
+  const now = opts.now ?? Date.now;
+
+  const presentChunks = (request: Request) => {
+    const cookies = parseCookies(request.headers.get("cookie"));
+    const names: string[] = [];
+    for (let i = 0; i < MAX_CHUNKS; i++) if (cookies.has(chunkName(name, i))) names.push(chunkName(name, i));
+    return { cookies, names };
+  };
+
+  return {
+    async read(request) {
+      const { cookies } = presentChunks(request);
+      let sealed = "";
+      for (let i = 0; i < MAX_CHUNKS; i++) {
+        const part = cookies.get(chunkName(name, i));
+        if (part === undefined) break;
+        sealed += part;
+      }
+      if (!sealed) return null;
+      const opened = await unseal<StoredConnection>(sealed, { secret: opts.secret, purpose: "synap-connect/session", now: now() });
+      return opened.ok ? unpack(opened.value) : null;
+    },
+
+    async write(connection, request) {
+      const expiresAt = connectionExpiresAt(connection);
+      const sealed = await seal(pack(connection), { secret: opts.secret, purpose: "synap-connect/session", expiresAt });
+      const parts: string[] = [];
+      for (let i = 0; i < sealed.length; i += CHUNK_SIZE) parts.push(sealed.slice(i, i + CHUNK_SIZE));
+      if (parts.length > MAX_CHUNKS) {
+        throw new ConnectError(
+          "misconfigured",
+          "The connection is too large for a cookie (a very wide grant); pass a server-side ConnectionStore",
+        );
+      }
+      const maxAgeSec = (expiresAt - now()) / 1000;
+      const out = parts.map((value, i) => serializeCookie(chunkName(name, i), value, { maxAgeSec, secure: opts.secure }));
+      // Drop chunks a previous, larger value left behind.
+      for (const stale of presentChunks(request).names.slice(parts.length)) {
+        out.push(serializeCookie(stale, "", { maxAgeSec: 0, secure: opts.secure }));
+      }
+      return out;
+    },
+
+    async clear(request) {
+      const { names } = presentChunks(request);
+      return (names.length > 0 ? names : [name]).map((n) => serializeCookie(n, "", { maxAgeSec: 0, secure: opts.secure }));
+    },
+  };
+}
+
+/**
+ * Apply Set-Cookie values to a request's Cookie header, so code that runs
+ * later IN THE SAME REQUEST (a server component after `proxy.ts`) reads the
+ * refreshed value. A `Max-Age=0` removes the cookie.
+ */
+export function applySetCookies(cookieHeader: string | null, setCookies: readonly string[]): string {
+  const cookies = parseCookies(cookieHeader);
+  for (const sc of setCookies) {
+    const [pair, ...attrs] = sc.split(";");
+    const eq = pair.indexOf("=");
+    if (eq < 0) continue;
+    const name = pair.slice(0, eq).trim();
+    const removed = attrs.some((a) => /^\s*max-age\s*=\s*0\s*$/i.test(a));
+    if (removed) cookies.delete(name);
+    else cookies.set(name, pair.slice(eq + 1).trim());
+  }
+  return [...cookies].map(([k, v]) => `${k}=${v}`).join("; ");
+}

package/src/connect/types.ts

@@ -0,0 +1,100 @@
+/**
+ * Wire and session shapes of pod-app sign-in.
+ *
+ * DRIFT RISK: hand-written from the pod's OAuth AS (synap-backend
+ * `routers/oauth/routes.ts` /token for a CIMD client, `protocol.ts`
+ * `buildAuthorizationServerMetadata`, spec 17 §6.6). The contract fixture
+ * `src/__tests__/connect.contract.test.ts` copies the token response; when the
+ * backend changes, update both.
+ */
+
+/** One permission the app asks for, with the sentence the consent screen shows. */
+export interface AppRequest {
+  /** Grant grammar, e.g. `entity.post.read`, `document.update`. No `*`. */
+  permission: string;
+  /** Why the app needs it (at most 200 characters). */
+  reason: string;
+}
+
+/** What the person approved: one row per permission per space. */
+export interface PodGrant {
+  permission: string;
+  workspaceId: string;
+  workspaceName: string;
+}
+
+export interface PodUser {
+  id: string;
+  name: string;
+}
+
+/** A pod's authorization server, as `discoverPod` validated it. */
+export interface PodIssuer {
+  /** The canonical issuer, which is also the pod's base URL. */
+  issuer: string;
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  revocationEndpoint: string | null;
+  /** The AS advertises `grant_types_supported: [..., "refresh_token"]`. */
+  refreshSupported: boolean;
+}
+
+/**
+ * A live connection of this app to one person's pod. Server-only: it holds the
+ * bearer token. Serialisable, so a custom store can keep it anywhere.
+ */
+export interface PodConnection {
+  /** The pod's canonical issuer = its base URL (no trailing slash). */
+  podUrl: string;
+  /** The app's client_id (its CIMD URL) the tokens were issued to. */
+  clientId: string;
+  tokenEndpoint: string;
+  revocationEndpoint: string | null;
+  accessToken: string;
+  /** ms since epoch. */
+  accessExpiresAt: number;
+  /** Absent when the pod issued none (then the connection ends at `accessExpiresAt`). */
+  refreshToken?: string;
+  /** ms since epoch; the refresh token's idle life, renewed by each rotation. */
+  refreshExpiresAt?: number;
+  /** The approved permissions (the token response's `scope`). */
+  scope: string[];
+  grant: PodGrant[];
+  user: PodUser;
+  /** ms since epoch. */
+  connectedAt: number;
+  /**
+   * The pod's id for this app connection (`app_…`, the grant's client id), when
+   * the token response names it (`synap_app.id`). Absent from pods that do not.
+   */
+  appId?: string;
+  /**
+   * The pod's own page for this app connection (pod-admin `/apps/<appId>`:
+   * what it may touch, narrow it, apply automatically, revoke), when the token
+   * response names it (`synap_app.manageUrl`). Absent otherwise: hide the link,
+   * never guess one.
+   */
+  manageUrl?: string;
+}
+
+/** One space of the grant, its permissions together (`spaces(connection)`). */
+export interface PodSpace {
+  workspaceId: string;
+  /** "" when the pod sent no name. */
+  workspaceName: string;
+  permissions: string[];
+}
+
+/** The CIMD document an app serves at its client_id URL (spec 17 §6.1). */
+export interface ClientMetadataDocument {
+  client_id: string;
+  client_name: string;
+  client_uri: string;
+  redirect_uris: string[];
+  grant_types: string[];
+  response_types: string[];
+  token_endpoint_auth_method: "none";
+  initiate_login_uri: string;
+  synap_requests: AppRequest[];
+  synap_templates?: string[];
+}