@synap-core/sdk 1.2.0 → 1.4.0

package/src/connect/discovery.ts

@@ -0,0 +1,263 @@
+/**
+ * Pod discovery (spec 17 §6.3): a typed address or a launch `iss` → the pod's
+ * authorization server metadata (RFC 8414), validated before any redirect.
+ *
+ *  - the metadata's `issuer` must equal the address it was fetched for, byte
+ *    for byte (RFC 8414 §3.3): a document naming another issuer is not used;
+ *  - it must advertise CIMD clients, `iss` on every authorization response
+ *    (RFC 9207) and PKCE S256, else the pod is too old for app sign-in;
+ *  - every endpoint must live on the issuer's own origin.
+ *
+ * The fetch runs on the app's server with an address a visitor typed, so it is
+ * fenced: https only (http only on loopback when `allowInsecureLoopback`), no
+ * IP literal outside public space, no single-label or `.local`/`.internal`
+ * host, no redirect followed, 5 s, 64 KB. Residual: a public DNS name that
+ * resolves to a private address cannot be refused without a resolver; a
+ * deployment that cares adds egress rules.
+ *
+ * Connecting through Synap Cloud (the CP pod chooser, wave C1) is ./cloud.ts.
+ */
+import { ConnectError, retryAfterSeconds } from "./errors";
+import type { PodIssuer } from "./types";
+
+const METADATA_PATH = "/.well-known/oauth-authorization-server";
+const TIMEOUT_MS = 5_000;
+const MAX_METADATA_BYTES = 64 * 1024;
+
+export interface DiscoverOptions {
+  fetch?: typeof fetch;
+  /** Allow `http://localhost` (and 127.0.0.1, [::1]) pods: development only. */
+  allowInsecureLoopback?: boolean;
+  now?: () => number;
+}
+
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+function isPrivateIpv4(host: string): boolean {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (!m) return false;
+  const [a, b] = [Number(m[1]), Number(m[2])];
+  return (
+    a === 0 ||
+    a === 10 ||
+    a === 127 ||
+    (a === 100 && b >= 64 && b <= 127) ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168) ||
+    a >= 224
+  );
+}
+
+/**
+ * The canonical issuer for a typed address, or a ConnectError. Adds `https://`
+ * when no scheme is given; drops a trailing slash.
+ */
+export function canonicalPodUrl(input: string, opts: { allowInsecureLoopback?: boolean } = {}): string {
+  const raw = input.trim();
+  if (!raw || raw.length > 512) throw new ConnectError("invalid_pod_address", "Empty or overlong pod address");
+  let url: URL;
+  try {
+    url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `https://${raw}`);
+  } catch {
+    throw new ConnectError("invalid_pod_address", "Not a URL");
+  }
+  const host = url.hostname.toLowerCase();
+  const loopback = LOOPBACK_HOSTS.has(host); // WHATWG keeps the brackets: "[::1]"
+  if (url.protocol === "http:" && !(loopback && opts.allowInsecureLoopback)) {
+    throw new ConnectError("invalid_pod_address", "A pod address must use https");
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new ConnectError("invalid_pod_address", "A pod address must use https");
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new ConnectError("invalid_pod_address", "A pod address has no credentials, query or fragment");
+  }
+  if (!(loopback && opts.allowInsecureLoopback)) {
+    if (loopback || host.startsWith("[") || isPrivateIpv4(host) || /^\d+$/.test(host)) {
+      throw new ConnectError("invalid_pod_address", "A pod address must be a public host name");
+    }
+    if (!host.includes(".") || /\.(local|internal|localhost|lan|home\.arpa)$/.test(host)) {
+      throw new ConnectError("invalid_pod_address", "A pod address must be a public host name");
+    }
+  }
+  const path = url.pathname.replace(/\/+$/, "");
+  return `${url.origin}${path}`;
+}
+
+function metadataUrl(issuer: string): string {
+  const url = new URL(issuer);
+  const path = url.pathname === "/" ? "" : url.pathname;
+  return `${url.origin}${METADATA_PATH}${path}`;
+}
+
+function sameOriginEndpoint(value: unknown, issuer: string): string | null {
+  if (typeof value !== "string") return null;
+  try {
+    const url = new URL(value);
+    return url.origin === new URL(issuer).origin && !url.username && !url.hash ? url.href : null;
+  } catch {
+    return null;
+  }
+}
+
+async function readJsonCapped(res: Response): Promise<unknown> {
+  const text = await res.text();
+  if (text.length > MAX_METADATA_BYTES) throw new ConnectError("not_a_pod", "Metadata document too large");
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new ConnectError("not_a_pod", "Metadata is not JSON");
+  }
+}
+
+/** Fetch and validate one candidate issuer's metadata. */
+async function discoverIssuer(issuer: string, opts: DiscoverOptions): Promise<PodIssuer> {
+  const doFetch = opts.fetch ?? fetch;
+  let res: Response;
+  try {
+    res = await doFetch(metadataUrl(issuer), {
+      method: "GET",
+      headers: { Accept: "application/json" },
+      redirect: "manual",
+      signal: typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(TIMEOUT_MS) : undefined,
+    });
+  } catch {
+    throw new ConnectError("pod_unreachable", "The pod 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 pod answered ${res.status}`);
+  if (res.status !== 200) throw new ConnectError("not_a_pod", `No authorization server metadata (${res.status})`);
+  const doc = await readJsonCapped(res);
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw new ConnectError("not_a_pod", "Metadata is not an object");
+  const m = doc as Record<string, unknown>;
+
+  // RFC 8414 §3.3 — the mix-up defence at discovery time.
+  if (m.issuer !== issuer) {
+    throw new ConnectError("not_a_pod", "The metadata names a different issuer than the address it was fetched from");
+  }
+  const list = (v: unknown) => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : null);
+  const pkce = list(m.code_challenge_methods_supported);
+  const responseTypes = list(m.response_types_supported);
+  if (
+    m.authorization_response_iss_parameter_supported !== true ||
+    m.client_id_metadata_document_supported !== true ||
+    !pkce?.includes("S256") ||
+    (responseTypes !== null && !responseTypes.includes("code"))
+  ) {
+    throw new ConnectError("pod_unsupported", "This pod does not support app sign-in (CIMD, iss, S256)");
+  }
+  const authorizationEndpoint = sameOriginEndpoint(m.authorization_endpoint, issuer);
+  const tokenEndpoint = sameOriginEndpoint(m.token_endpoint, issuer);
+  if (!authorizationEndpoint || !tokenEndpoint) {
+    throw new ConnectError("pod_unsupported", "The pod's endpoints are missing or not on its own origin");
+  }
+  return {
+    issuer,
+    authorizationEndpoint,
+    tokenEndpoint,
+    revocationEndpoint: sameOriginEndpoint(m.revocation_endpoint, issuer),
+    refreshSupported: list(m.grant_types_supported)?.includes("refresh_token") ?? false,
+  };
+}
+
+/**
+ * A typed pod address (or a launch `iss`) → its validated authorization server.
+ * Tries the address, then `pod.<host>` (so "antoine.synap.live" finds
+ * "pod.antoine.synap.live").
+ */
+export async function discoverPod(input: string, opts: DiscoverOptions = {}): Promise<PodIssuer> {
+  const first = canonicalPodUrl(input, opts);
+  try {
+    return await discoverIssuer(first, opts);
+  } catch (err) {
+    const url = new URL(first);
+    const retry =
+      err instanceof ConnectError &&
+      (err.code === "not_a_pod" || err.code === "pod_unreachable") &&
+      !url.hostname.startsWith("pod.") &&
+      url.pathname === "/" &&
+      url.hostname.includes(".");
+    if (!retry) throw err;
+    const second = `${url.protocol}//pod.${url.host}`;
+    try {
+      return await discoverIssuer(second, opts);
+    } catch (err2) {
+      // A pod that is there but too old says more than "nothing answered".
+      throw err2 instanceof ConnectError && err2.code === "pod_unsupported" ? err2 : err;
+    }
+  }
+}
+
+/**
+ * A same-origin path to return to after connecting, or null. Accepts a
+ * relative path (never `//host` or `/\host`) or an absolute URL on the app's
+ * own origin; anything else is dropped (no open redirect).
+ */
+export function safeNextPath(value: string | null | undefined, appOrigin: string): string | null {
+  if (!value || value.length > 2048) return null;
+  if (value.startsWith("/") && !value.startsWith("//") && !value.startsWith("/\\")) {
+    try {
+      const url = new URL(value, appOrigin);
+      return url.origin === appOrigin ? `${url.pathname}${url.search}${url.hash}` : null;
+    } catch {
+      return null;
+    }
+  }
+  try {
+    const url = new URL(value);
+    return url.origin === appOrigin ? `${url.pathname}${url.search}${url.hash}` : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface LaunchHint {
+  /** The pod issuer the launcher named (`iss`), to pre-fill and CONFIRM (T6), never to auto-connect. */
+  pod: string | null;
+  /** Where to land after connecting (`target_link_uri`), same origin only. */
+  next: string | null;
+  /** A space to preselect on consent (`synap_space_hint`). */
+  spaceHint: string | null;
+  /**
+   * The `state` of a Synap Cloud return (the CP pod chooser answers
+   * `initiate_login_uri?iss=…&state=…`, or `?state=…&error=access_denied` when
+   * the person cancelled), shape-checked only. NOT verified here:
+   * send the request's query to the cloud handler (GET `paths.cloud`), which
+   * checks it against this browser's sealed cookie. Never act on `pod` because
+   * a state is present.
+   */
+  cloudState: string | null;
+}
+
+/**
+ * Read a third-party-initiated login (OIDC Core §4, spec 17 §7.2): the browser
+ * opens the app's `initiate_login_uri?iss=…&target_link_uri=…`. One parser for
+ * the browser launch and the Synap Cloud chooser's return (`cloudState`).
+ */
+export function acceptLaunch(url: string | URL, appOrigin: string, opts: { allowInsecureLoopback?: boolean } = {}): LaunchHint {
+  const params = new URL(url).searchParams;
+  let pod: string | null = null;
+  const iss = params.get("iss");
+  if (iss) {
+    try {
+      pod = canonicalPodUrl(iss, opts);
+    } catch {
+      pod = null;
+    }
+  }
+  const hint = params.get("synap_space_hint");
+  const state = params.get("state");
+  return {
+    pod,
+    next: safeNextPath(params.get("target_link_uri"), appOrigin),
+    spaceHint: hint && /^[A-Za-z0-9_-]{1,64}$/.test(hint) ? hint : null,
+    // A browser launch never carries a state: any well-formed one is a Synap Cloud return
+    // (a pick: iss + state; a cancel: state + error=access_denied, no iss).
+    cloudState: state && /^[A-Za-z0-9._~-]{16,256}$/.test(state) ? state : null,
+  };
+}

package/src/connect/encoding.ts

@@ -0,0 +1,93 @@
+/**
+ * Web-standard primitives (WebCrypto, TextEncoder, btoa/atob): the same code
+ * runs on Node 18+, edge runtimes and workers. No Node import.
+ */
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** `Uint8Array<ArrayBuffer>`: what WebCrypto's `BufferSource` takes under TS 5.7+ lib types. */
+export type Bytes = Uint8Array<ArrayBuffer>;
+
+export function utf8(text: string): Bytes {
+  return encoder.encode(text);
+}
+
+export function fromUtf8(bytes: Uint8Array): string {
+  return decoder.decode(bytes);
+}
+
+export function base64url(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** Null when `text` is not base64url. */
+export function fromBase64url(text: string): Bytes | null {
+  if (!/^[A-Za-z0-9_-]*$/.test(text)) return null;
+  const padded = text.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((text.length + 3) % 4);
+  let binary: string;
+  try {
+    binary = atob(padded);
+  } catch {
+    return null;
+  }
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+export function randomBytes(length: number): Bytes {
+  const out = new Uint8Array(length);
+  crypto.getRandomValues(out);
+  return out;
+}
+
+/** 32 random bytes, base64url (43 chars): a state value or a PKCE verifier. */
+export function randomToken(): string {
+  return base64url(randomBytes(32));
+}
+
+/** RFC 7636 §4.2: `BASE64URL(SHA256(ASCII(code_verifier)))`. */
+export async function pkceChallenge(verifier: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", utf8(verifier));
+  return base64url(new Uint8Array(digest));
+}
+
+/** Compare two strings without an early exit on the first differing byte. */
+export function constantTimeEqual(a: string, b: string): boolean {
+  const x = utf8(a);
+  const y = utf8(b);
+  let diff = x.length ^ y.length;
+  for (let i = 0; i < Math.max(x.length, y.length); i++) diff |= (x[i] ?? 0) ^ (y[i] ?? 0);
+  return diff === 0;
+}
+
+/** The request's cookies by name (the first value wins, as browsers order the most specific first). */
+export function parseCookies(header: string | null): Map<string, string> {
+  const out = new Map<string, string>();
+  if (!header) return out;
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const name = part.slice(0, eq).trim();
+    if (!name || out.has(name)) continue;
+    let value = part.slice(eq + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1);
+    out.set(name, value);
+  }
+  return out;
+}
+
+export interface CookieAttributes {
+  maxAgeSec: number;
+  secure: boolean;
+}
+
+/** `HttpOnly; SameSite=Lax; Path=/` always; `Secure` on https. Never a `Domain`. */
+export function serializeCookie(name: string, value: string, attrs: CookieAttributes): string {
+  const parts = [`${name}=${value}`, "Path=/", "HttpOnly", "SameSite=Lax", `Max-Age=${Math.max(0, Math.floor(attrs.maxAgeSec))}`];
+  if (attrs.secure) parts.push("Secure");
+  return parts.join("; ");
+}

package/src/connect/errors.ts

@@ -0,0 +1,115 @@
+/**
+ * The one error type of `@synap-core/sdk/connect`. `code` is the contract a UI
+ * branches on; `message` and `detail` are for the developer's logs, never for
+ * the person (a sign-in failure page says one sentence per code, never why).
+ */
+
+export type ConnectErrorCode =
+  /** The typed pod address is not a usable URL. */
+  | "invalid_pod_address"
+  /** Something answered, but it is not a Synap pod (no AS metadata). */
+  | "not_a_pod"
+  /** The pod did not answer (network, timeout, 5xx). */
+  | "pod_unreachable"
+  /** A Synap pod, but too old for app sign-in (no CIMD, no `iss`, no S256). */
+  | "pod_unsupported"
+  /** Connecting through Synap Cloud is not configured for this app (no Control Plane URL). */
+  | "cp_unavailable"
+  /** The person said no on the consent screen. */
+  | "denied"
+  /** No sign-in in progress here, or it is older than 10 minutes. */
+  | "expired_transaction"
+  /** The answer does not belong to the sign-in this browser started (`state` or `iss`). */
+  | "mismatch"
+  /** The app's own setup is wrong (client metadata, scopes, secret, redirect). */
+  | "misconfigured"
+  /** The pod asked to slow down; see `retryAfterSec`. */
+  | "rate_limited"
+  /** The connection lapsed (refresh token idle past its life, or none was issued). */
+  | "expired"
+  /** The pod refused the connection's refresh token while it should still live. */
+  | "revoked"
+  /** The pod answered something the SDK cannot use. */
+  | "server_error";
+
+export class ConnectError extends Error {
+  readonly code: ConnectErrorCode;
+  /** Seconds to wait, from `Retry-After`, when `code` is `rate_limited`. */
+  readonly retryAfterSec?: number;
+  /** The OAuth error code the pod sent, when there was one (logs only). */
+  readonly oauthError?: string;
+
+  constructor(
+    code: ConnectErrorCode,
+    message: string,
+    extra: { retryAfterSec?: number; oauthError?: string } = {},
+  ) {
+    super(message);
+    this.name = "ConnectError";
+    this.code = code;
+    if (extra.retryAfterSec !== undefined) this.retryAfterSec = extra.retryAfterSec;
+    if (extra.oauthError !== undefined) this.oauthError = extra.oauthError;
+  }
+}
+
+export function isConnectError(err: unknown): err is ConnectError {
+  return err instanceof ConnectError;
+}
+
+export const CONNECT_ERROR_CODES: readonly ConnectErrorCode[] = [
+  "invalid_pod_address",
+  "not_a_pod",
+  "pod_unreachable",
+  "pod_unsupported",
+  "cp_unavailable",
+  "denied",
+  "expired_transaction",
+  "mismatch",
+  "misconfigured",
+  "rate_limited",
+  "expired",
+  "revoked",
+  "server_error",
+];
+
+/** Parse an untrusted `?error=` value back into a code (null when unknown). */
+export function parseConnectErrorCode(value: string | null | undefined): ConnectErrorCode | null {
+  return (CONNECT_ERROR_CODES as readonly string[]).includes(value ?? "") ? (value as ConnectErrorCode) : null;
+}
+
+/**
+ * RFC 6749 §4.1.2.1 / §5.2 error codes → ours. `invalid_grant` at the token
+ * endpoint during a callback means the code was used, expired or does not
+ * match: for the person that is "the link expired".
+ */
+export function fromOAuthError(oauthError: string, during: "authorize" | "token" | "refresh"): ConnectErrorCode {
+  switch (oauthError) {
+    case "access_denied":
+      return "denied";
+    case "temporarily_unavailable":
+    case "server_error":
+      return "pod_unreachable";
+    case "invalid_grant":
+      return during === "refresh" ? "revoked" : "expired_transaction";
+    case "invalid_request":
+    case "invalid_client":
+    case "invalid_scope":
+    case "invalid_target":
+    case "unauthorized_client":
+    case "unsupported_grant_type":
+    case "unsupported_response_type":
+      return "misconfigured";
+    default:
+      return "server_error";
+  }
+}
+
+/** `Retry-After` as whole seconds (delta-seconds or an HTTP date); undefined when unusable. */
+export function retryAfterSeconds(header: string | null, now: number): number | undefined {
+  if (!header) return undefined;
+  const trimmed = header.trim();
+  if (/^\d{1,9}$/.test(trimmed)) return Number(trimmed);
+  const at = Date.parse(trimmed);
+  if (Number.isNaN(at)) return undefined;
+  return Math.max(0, Math.ceil((at - now) / 1000));
+}