@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/org/oidc.ts

@@ -0,0 +1,435 @@
+// brain org: OpenID Connect primitives, used by the server (sso.ts: verify an ID token) and by the CLI (the browser sign-in flow).
+//
+// SERVER SIDE
+//   * discovery (`<issuer>/.well-known/openid-configuration`), cached; the document's `issuer` must equal the configured one;
+//   * JWKS, cached for an hour, refetched (at most every 10 s) when a token names a key id the cache does not know (key rotation);
+//   * verifyIdToken: RS256 / ES256 only (`alg: none`, HS256 and anything else are refused: a symmetric alg would let anyone who
+//     knows the public key forge a token), signature against the matching JWK, then `iss`, `aud` (+ `azp`), `exp`, `iat`, `nbf`,
+//     `nonce`. The caller decides about the email, the domain and the user.
+//   * every outgoing request has a timeout, refuses redirects, caps the response size, and requires https (plain http only to a
+//     loopback host, so a developer can run a local identity provider).
+//   Errors are `OidcError` with a short fixed `reason`; a reason NEVER contains any part of a token, a code or a response body.
+// CLIENT SIDE
+//   * pkce(), buildAuthorizeUrl(), and ssoLoginFlow(): loopback listener on 127.0.0.1:<random port>, state check, one-shot.
+import { createHash, randomBytes } from "node:crypto"
+
+export class OidcError extends Error {
+  constructor(readonly reason: string) {
+    super(reason)
+    this.name = "OidcError"
+  }
+}
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+export const MAX_JSON_BYTES = 256_000
+export const MAX_ID_TOKEN_CHARS = 16_384
+export const CLOCK_SKEW_SEC = 60
+/** An ID token comes straight from the token endpoint: one issued long ago is not what a sign-in just produced. */
+export const MAX_IAT_AGE_SEC = 600
+
+export function isLoopbackHostname(host: string): boolean {
+  const h = host.replace(/^\[|\]$/g, "").toLowerCase()
+  return h === "localhost" || h.endsWith(".localhost") || h === "::1" || /^127\.\d+\.\d+\.\d+$/.test(h)
+}
+
+/** An endpoint the server may call or the CLI may open: https, or http to loopback only. No credentials in the URL. */
+export function endpointOk(raw: unknown): URL | undefined {
+  if (typeof raw !== "string" || raw.length > 2048) return undefined
+  let u: URL
+  try {
+    u = new URL(raw)
+  } catch {
+    return undefined
+  }
+  if (u.username || u.password || u.hash) return undefined
+  if (u.protocol === "https:") return u
+  if (u.protocol === "http:" && isLoopbackHostname(u.hostname)) return u
+  return undefined
+}
+
+// ---- outgoing HTTP ---------------------------------------------------------------------------------------------------------
+
+export interface FetchOpts {
+  timeoutMs?: number
+  maxBytes?: number
+}
+
+/** One request, JSON answer, bounded in time and size. Any problem (network, status, size, content) is an OidcError(reason). */
+export async function fetchJson(url: string, init: RequestInit, reason: string, o: FetchOpts = {}): Promise<unknown> {
+  if (!endpointOk(url)) throw new OidcError(`${reason}_url`)
+  const ctl = new AbortController()
+  const timer = setTimeout(() => ctl.abort(), o.timeoutMs ?? 8_000)
+  const max = o.maxBytes ?? MAX_JSON_BYTES
+  try {
+    const res = await fetch(url, { ...init, redirect: "error", signal: ctl.signal, headers: { accept: "application/json", ...(init.headers as Record<string, string> | undefined) } })
+    if (res.status !== 200) {
+      void res.body?.cancel().catch(() => {})
+      throw new OidcError(`${reason}_status`)
+    }
+    const declared = Number(res.headers.get("content-length") ?? "0")
+    if (Number.isFinite(declared) && declared > max) {
+      void res.body?.cancel().catch(() => {})
+      throw new OidcError(`${reason}_too_large`)
+    }
+    const chunks: Uint8Array[] = []
+    let total = 0
+    if (res.body) {
+      const r = res.body.getReader()
+      for (;;) {
+        const { done, value } = await r.read()
+        if (done) break
+        total += value.byteLength
+        if (total > max) {
+          void r.cancel().catch(() => {})
+          throw new OidcError(`${reason}_too_large`)
+        }
+        chunks.push(value)
+      }
+    }
+    try {
+      return JSON.parse(Buffer.concat(chunks).toString("utf8"))
+    } catch {
+      throw new OidcError(`${reason}_garbled`)
+    }
+  } catch (e) {
+    if (e instanceof OidcError) throw e
+    throw new OidcError(`${reason}_unreachable`)
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+// ---- discovery and keys ----------------------------------------------------------------------------------------------------
+
+export interface Discovery {
+  issuer: string
+  authorization_endpoint: string
+  token_endpoint: string
+  jwks_uri: string
+  /** Where the profile claims are when the provider keeps them out of the ID token (OIDC Core 5.3; the code flow often does). */
+  userinfo_endpoint?: string
+  token_endpoint_auth_methods_supported?: string[]
+}
+
+export const discoveryUrl = (issuer: string): string => `${issuer.replace(/\/+$/, "")}/.well-known/openid-configuration`
+
+export async function fetchDiscovery(issuer: string): Promise<Discovery> {
+  return checkDiscovery(issuer, await fetchJson(discoveryUrl(issuer), { method: "GET" }, "discovery"))
+}
+
+/** Checks a discovery document for `issuer` (exported so real providers' published documents can be tested offline). */
+export function checkDiscovery(issuer: string, d: unknown): Discovery {
+  if (!isObj(d)) throw new OidcError("discovery_issuer")
+  // Multi-tenant endpoints (Microsoft's /common, /organizations) publish a template issuer: tokens then carry each tenant's own
+  // issuer, which no single configured issuer can match. The admin must configure the tenant's issuer instead.
+  if (typeof d.issuer === "string" && d.issuer.includes("{")) throw new OidcError("discovery_issuer_template")
+  // Accept a difference of a trailing slash only (Auth0 publishes "https://tenant.auth0.com/"); the provider's own spelling is
+  // then the issuer that ID tokens must carry.
+  if (typeof d.issuer !== "string" || d.issuer.replace(/\/+$/, "") !== issuer.replace(/\/+$/, "")) throw new OidcError("discovery_issuer")
+  const exact = d.issuer
+  if (Array.isArray(d.code_challenge_methods_supported) && !d.code_challenge_methods_supported.includes("S256")) throw new OidcError("discovery_no_pkce")
+  for (const k of ["authorization_endpoint", "token_endpoint", "jwks_uri"] as const) if (!endpointOk(d[k])) throw new OidcError("discovery_endpoint")
+  const userinfo = d.userinfo_endpoint === undefined ? undefined : endpointOk(d.userinfo_endpoint) ? (d.userinfo_endpoint as string) : undefined
+  const methods = Array.isArray(d.token_endpoint_auth_methods_supported) ? d.token_endpoint_auth_methods_supported.filter((m): m is string => typeof m === "string") : undefined
+  return {
+    issuer: exact,
+    authorization_endpoint: d.authorization_endpoint as string,
+    token_endpoint: d.token_endpoint as string,
+    jwks_uri: d.jwks_uri as string,
+    ...(userinfo ? { userinfo_endpoint: userinfo } : {}),
+    ...(methods ? { token_endpoint_auth_methods_supported: methods } : {}),
+  }
+}
+
+export type TokenAuth = "client_secret_basic" | "client_secret_post"
+
+/**
+ * How a confidential client authenticates at the token endpoint. client_secret_basic is the default of OAuth 2.0 (RFC 6749 2.3.1:
+ * servers MUST support it) and of OpenID Connect registration, and the only method some providers accept for a client registered
+ * with it; client_secret_post when the admin asks for it, or when the provider says it supports post but not basic.
+ */
+export function tokenAuthFor(d: Discovery, wanted?: TokenAuth): TokenAuth {
+  if (wanted) return wanted
+  const m = d.token_endpoint_auth_methods_supported
+  if (m && !m.includes("client_secret_basic") && m.includes("client_secret_post")) return "client_secret_post"
+  return "client_secret_basic"
+}
+
+/** The Authorization header for client_secret_basic: both parts form-urlencoded, then base64 (RFC 6749 2.3.1). */
+export const basicAuth = (clientId: string, secret: string): string =>
+  `Basic ${Buffer.from(`${encodeURIComponent(clientId).replace(/%20/g, "+")}:${encodeURIComponent(secret).replace(/%20/g, "+")}`).toString("base64")}`
+
+/**
+ * Whether the provider says the email is verified: `email_verified` true (a boolean, or the string "true" that some providers put
+ * in userinfo). Microsoft Entra ID sends no email_verified; there an admin adds the optional claim `xms_edov` ("email domain owner
+ * verified"), accepted only when email_verified is absent.
+ */
+export function emailVerified(c: Record<string, unknown>): boolean {
+  const v = c.email_verified
+  if (v === true || v === "true") return true
+  if (v !== undefined) return false
+  const edov = c.xms_edov
+  return edov === true || edov === "true" || edov === 1 || edov === "1"
+}
+
+export interface Jwk {
+  kty?: string
+  kid?: string
+  use?: string
+  alg?: string
+  n?: string
+  e?: string
+  crv?: string
+  x?: string
+  y?: string
+}
+
+export async function fetchJwks(uri: string): Promise<Jwk[]> {
+  const d = await fetchJson(uri, { method: "GET" }, "jwks")
+  if (!isObj(d) || !Array.isArray(d.keys) || d.keys.length > 100) throw new OidcError("jwks_garbled")
+  return (d.keys as unknown[]).filter(isObj) as Jwk[]
+}
+
+/** Caches discovery and the key set. `now` is injectable (the server's clock) so rotation can be tested without waiting. */
+export class KeyCache {
+  private disc?: { at: number; issuer: string; doc: Discovery }
+  private jwks?: { at: number; uri: string; keys: Jwk[] }
+  constructor(
+    private readonly now: () => number,
+    private readonly ttlMs = 3_600_000,
+    private readonly refetchCooldownMs = 10_000,
+  ) {}
+
+  async discovery(issuer: string): Promise<Discovery> {
+    const t = this.now()
+    if (this.disc && this.disc.issuer === issuer && t - this.disc.at < this.ttlMs) return this.disc.doc
+    const doc = await fetchDiscovery(issuer)
+    this.disc = { at: t, issuer, doc }
+    return doc
+  }
+
+  /** The keys for `uri`; `force` refetches (used on an unknown key id) unless one was fetched within the cooldown. */
+  async keys(uri: string, force = false): Promise<Jwk[]> {
+    const t = this.now()
+    const c = this.jwks
+    const fresh = c && c.uri === uri && t - c.at < this.ttlMs
+    if (fresh && !(force && t - c!.at >= this.refetchCooldownMs)) return c!.keys
+    const keys = await fetchJwks(uri)
+    this.jwks = { at: t, uri, keys }
+    return keys
+  }
+}
+
+// ---- JWT ---------------------------------------------------------------------------------------------------------------------
+
+const B64URL = /^[A-Za-z0-9_-]*$/
+const b64uDecode = (s: string): Buffer => {
+  if (!B64URL.test(s)) throw new OidcError("token_malformed")
+  return Buffer.from(s, "base64url")
+}
+const parsePart = (s: string): Record<string, unknown> => {
+  try {
+    const v = JSON.parse(b64uDecode(s).toString("utf8"))
+    if (!isObj(v)) throw new OidcError("token_malformed")
+    return v
+  } catch (e) {
+    throw e instanceof OidcError ? e : new OidcError("token_malformed")
+  }
+}
+
+export interface IdClaims extends Record<string, unknown> {
+  iss: string
+  sub: string
+  email?: string
+  email_verified?: boolean
+}
+
+async function importKey(jwk: Jwk, alg: "RS256" | "ES256"): Promise<CryptoKey> {
+  if (alg === "RS256") {
+    if (jwk.kty !== "RSA" || typeof jwk.n !== "string" || typeof jwk.e !== "string") throw new OidcError("key_unusable")
+    if (b64uDecode(jwk.n).length < 256) throw new OidcError("key_too_weak") // under 2048 bits
+    return crypto.subtle.importKey("jwk", { kty: "RSA", n: jwk.n, e: jwk.e, alg: "RS256", ext: true }, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["verify"])
+  }
+  if (jwk.kty !== "EC" || jwk.crv !== "P-256" || typeof jwk.x !== "string" || typeof jwk.y !== "string") throw new OidcError("key_unusable")
+  return crypto.subtle.importKey("jwk", { kty: "EC", crv: "P-256", x: jwk.x, y: jwk.y, ext: true }, { name: "ECDSA", namedCurve: "P-256" }, false, ["verify"])
+}
+
+export interface VerifyParams {
+  token: string
+  issuer: string
+  clientId: string
+  nonce: string
+  nowMs: number
+  /** Returns the JWKS; called again with force=true when the token's key id is unknown. */
+  keys: (force: boolean) => Promise<Jwk[]>
+}
+
+/** Verifies the ID token completely (signature and the standard claims) or throws OidcError. Never returns an unverified claim. */
+export async function verifyIdToken(p: VerifyParams): Promise<IdClaims> {
+  if (typeof p.token !== "string" || p.token.length > MAX_ID_TOKEN_CHARS) throw new OidcError("token_malformed")
+  const parts = p.token.split(".")
+  if (parts.length !== 3 || !parts[0] || !parts[1]) throw new OidcError("token_malformed")
+  const header = parsePart(parts[0]!)
+  const alg = header.alg
+  if (alg !== "RS256" && alg !== "ES256") throw new OidcError("alg_not_allowed")
+  if (header.kid !== undefined && (typeof header.kid !== "string" || header.kid.length > 256)) throw new OidcError("token_malformed")
+  if (header.crit !== undefined) throw new OidcError("token_malformed")
+  const sig = b64uDecode(parts[2]!)
+  if (!sig.length) throw new OidcError("bad_signature")
+  if (alg === "ES256" && sig.length !== 64) throw new OidcError("bad_signature")
+
+  const kty = alg === "RS256" ? "RSA" : "EC"
+  const pick = (keys: Jwk[]): Jwk[] => keys.filter((k) => k.kty === kty && (k.use === undefined || k.use === "sig") && (k.alg === undefined || k.alg === alg) && (header.kid === undefined ? true : k.kid === header.kid))
+  let cands = pick(await p.keys(false))
+  if (!cands.length && header.kid !== undefined) cands = pick(await p.keys(true)) // rotation: look again, once
+  if (!cands.length) throw new OidcError("unknown_key")
+  if (header.kid === undefined && cands.length !== 1) throw new OidcError("unknown_key") // without a key id the key must be unambiguous
+  const signed = new TextEncoder().encode(`${parts[0]}.${parts[1]}`)
+  let ok = false
+  for (const jwk of cands.slice(0, 5)) {
+    try {
+      const key = await importKey(jwk, alg)
+      ok = await crypto.subtle.verify(alg === "RS256" ? { name: "RSASSA-PKCS1-v1_5" } : { name: "ECDSA", hash: "SHA-256" }, key, new Uint8Array(sig), signed)
+    } catch (e) {
+      if (e instanceof OidcError && e.reason === "key_too_weak") throw e
+      ok = false
+    }
+    if (ok) break
+  }
+  if (!ok) throw new OidcError("bad_signature")
+
+  const c = parsePart(parts[1]!)
+  const nowSec = Math.floor(p.nowMs / 1000)
+  if (c.iss !== p.issuer) throw new OidcError("bad_issuer")
+  const aud = c.aud
+  const auds = typeof aud === "string" ? [aud] : Array.isArray(aud) && aud.every((a) => typeof a === "string") ? (aud as string[]) : []
+  if (!auds.includes(p.clientId)) throw new OidcError("bad_audience")
+  if (auds.length > 1 && c.azp !== p.clientId) throw new OidcError("bad_audience")
+  if (c.azp !== undefined && c.azp !== p.clientId) throw new OidcError("bad_audience")
+  const num = (v: unknown): number | undefined => (typeof v === "number" && Number.isFinite(v) ? v : undefined)
+  const exp = num(c.exp)
+  const iat = num(c.iat)
+  if (exp === undefined || iat === undefined) throw new OidcError("missing_time_claims")
+  if (exp + CLOCK_SKEW_SEC <= nowSec) throw new OidcError("expired")
+  if (iat - CLOCK_SKEW_SEC > nowSec) throw new OidcError("issued_in_future")
+  if (iat + MAX_IAT_AGE_SEC + CLOCK_SKEW_SEC < nowSec) throw new OidcError("too_old")
+  if (c.nbf !== undefined && (num(c.nbf) === undefined || num(c.nbf)! - CLOCK_SKEW_SEC > nowSec)) throw new OidcError("not_yet_valid")
+  if (typeof c.nonce !== "string" || !safeEq(c.nonce, p.nonce)) throw new OidcError("bad_nonce")
+  if (typeof c.sub !== "string" || !c.sub) throw new OidcError("token_malformed")
+  return c as IdClaims
+}
+
+function safeEq(a: string, b: string): boolean {
+  const x = createHash("sha256").update(a).digest()
+  const y = createHash("sha256").update(b).digest()
+  return x.equals(y) && a.length === b.length
+}
+
+// ---- PKCE and the browser flow (client side) ------------------------------------------------------------------------------
+
+export interface Pkce {
+  verifier: string
+  challenge: string
+}
+export function pkce(): Pkce {
+  const verifier = randomBytes(32).toString("base64url") // 43 characters
+  return { verifier, challenge: createHash("sha256").update(verifier).digest("base64url") }
+}
+export const randomToken = (): string => randomBytes(32).toString("base64url")
+
+export interface PublicSsoConfig {
+  enabled: boolean
+  issuer?: string
+  authorizationEndpoint?: string
+  clientId?: string
+  scopes?: string
+}
+
+export function buildAuthorizeUrl(c: { authorizationEndpoint: string; clientId: string; scopes: string; redirectUri: string; state: string; nonce: string; challenge: string }): string {
+  const u = new URL(c.authorizationEndpoint)
+  u.searchParams.set("response_type", "code")
+  u.searchParams.set("client_id", c.clientId)
+  u.searchParams.set("redirect_uri", c.redirectUri)
+  u.searchParams.set("scope", c.scopes)
+  u.searchParams.set("state", c.state)
+  u.searchParams.set("nonce", c.nonce)
+  u.searchParams.set("code_challenge", c.challenge)
+  u.searchParams.set("code_challenge_method", "S256")
+  return u.toString()
+}
+
+export interface SsoFlowDeps {
+  config(): Promise<PublicSsoConfig>
+  exchange(req: { code: string; codeVerifier: string; redirectUri: string; nonce: string }): Promise<{ token: string; user: unknown; expiresAt: string }>
+  /** Opens the URL in the person's browser (best effort); the URL is always printed as well. */
+  open?: (url: string) => void
+  print(line: string): void
+  timeoutMs?: number
+}
+
+const PAGE = (msg: string): Response => new Response(`<!doctype html><meta charset="utf-8"><title>brain</title><p style="font:16px system-ui;margin:3em">${msg}</p>`, { headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" } })
+
+/** The whole browser sign-in. Returns what the server issued; throws Error with a message fit to print (never contains the token). */
+export async function ssoLoginFlow(d: SsoFlowDeps): Promise<{ token: string; user: unknown; expiresAt: string }> {
+  const cfg = await d.config()
+  if (!cfg.enabled) throw new Error("single sign-on is not enabled on this server (ask an admin to run `brain org admin sso set`)")
+  const authz = endpointOk(cfg.authorizationEndpoint)
+  if (!authz || typeof cfg.clientId !== "string" || !cfg.clientId) throw new Error("the server sent an unusable sign-in configuration")
+  const scopes = typeof cfg.scopes === "string" && cfg.scopes ? cfg.scopes : "openid email profile"
+  const { verifier, challenge } = pkce()
+  const state = randomToken()
+  const nonce = randomToken()
+
+  let done!: (v: { code: string } | { error: string }) => void
+  const result = new Promise<{ code: string } | { error: string }>((r) => (done = r))
+  const listener = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    fetch(req) {
+      const u = new URL(req.url)
+      if (u.pathname !== "/callback" || req.method !== "GET") return new Response("not found", { status: 404 })
+      const given = u.searchParams.get("state") ?? ""
+      if (!given || !safeEq(given, state)) {
+        done({ error: "the sign-in answer did not match this request (state mismatch); nothing was stored" })
+        return PAGE("Sign-in failed: the answer did not match the request. You can close this tab.")
+      }
+      const err = u.searchParams.get("error")
+      if (err) {
+        done({ error: `the identity provider refused the sign-in (${err.replace(/[^A-Za-z0-9_ .-]/g, "").slice(0, 60) || "error"})` })
+        return PAGE("Sign-in was not completed. You can close this tab.")
+      }
+      const code = u.searchParams.get("code")
+      if (!code || code.length > 2048) {
+        done({ error: "the identity provider sent no authorization code" })
+        return PAGE("Sign-in failed. You can close this tab.")
+      }
+      done({ code })
+      return PAGE("Signed in. You can close this tab and return to the terminal.")
+    },
+  })
+  const timer = setTimeout(() => done({ error: "timed out waiting for the browser sign-in" }), d.timeoutMs ?? 300_000)
+  try {
+    const redirectUri = `http://127.0.0.1:${listener.port}/callback`
+    const url = buildAuthorizeUrl({ authorizationEndpoint: authz.toString(), clientId: cfg.clientId, scopes, redirectUri, state, nonce, challenge })
+    d.print("open this address in your browser to sign in:")
+    d.print(url)
+    try {
+      d.open?.(url)
+    } catch {}
+    const r = await result
+    if ("error" in r) throw new Error(r.error)
+    return await d.exchange({ code: r.code, codeVerifier: verifier, redirectUri, nonce })
+  } finally {
+    clearTimeout(timer)
+    void listener.stop() // graceful: the page the browser is being sent still arrives
+  }
+}
+
+/** Best-effort browser launch. Failure is fine: the URL has been printed. */
+export function openInBrowser(url: string): void {
+  const cmd = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? ["cmd", "/c", "start", "", url.replace(/&/g, "^&")] : ["xdg-open", url]
+  try {
+    Bun.spawn(cmd, { stdin: "ignore", stdout: "ignore", stderr: "ignore" }).unref()
+  } catch {}
+}