@broberg/sso 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# @broberg/sso
+
+The thin client for **Broberg ID** (`id.broberg.ai`). Send a user to central
+login, verify the ID token against JWKS, keep a local session. That is all it
+does, and the list of what it deliberately cannot do is part of the design.
+
+```bash
+pnpm add @broberg/sso
+```
+
+## Configure it with environment variables only
+
+```bash
+BID_ISSUER=https://id.broberg.ai        # the BARE origin
+SSO_CLIENT_ID=my-app                    # registered administratively in BID
+SSO_REDIRECT_URI=https://my.app/auth/callback   # EXACT match, one slash decides
+SSO_COOKIE_SECRET=$(openssl rand -hex 32)
+# optional
+SSO_SCOPES="openid profile email"
+SSO_COOKIE_NAME=bid_session
+SSO_SESSION_MAX_AGE=604800              # 7 days (fleet default, F084.7)
+SSO_POST_LOGOUT_REDIRECT_URI=https://my.app/
+```
+
+**Handling personal or health data? Set `SSO_SESSION_MAX_AGE=43200`.** The
+default is twelve hours' worth of convenience too long for that case — F084.7
+decided 12 hours plus a 30-minute inactivity cut for anything holding personal
+or health data. The default is a normal-app default, not a safe-for-everything
+one.
+
+## Mount it (Hono)
+
+```ts
+import { Hono } from "hono";
+import { ssoRoutes, getSession } from "@broberg/sso/hono";
+
+const app = new Hono();
+const sso = ssoRoutes({ loginPath: "/auth" });
+
+app.route("/auth", sso.app);          // /auth/login · /auth/callback · /auth/logout
+app.use("*", sso.attach);             // read the session, never block
+app.get("/me", sso.require, (c) => c.json(getSession(c)));  // block + redirect
+```
+
+That is the whole integration. No other code changes.
+
+## What it will never do
+
+No passwords. No passkey registration. No social-provider keys. No email
+verification. **No client secret** — it is a public client and PKCE carries the
+exchange.
+
+That last one is safe for a specific, measured reason rather than a hopeful
+one: BID matches redirect addresses exactly (a single trailing slash is
+refused), so an authorization code is delivered to your own server and nowhere
+else. An attacker who knows your client id can start a flow; they cannot
+receive its result. And a secret that does not exist cannot be committed,
+logged, copied into a second app, or left in a repo someone later opens.
+
+## Key rotation costs you nothing
+
+The key cache refetches when it sees an **unknown key id** — not on a timer. A
+timer is a guess about when somebody else will rotate; an unknown kid is the
+event itself. Refetches are rate-limited (10s by default) so a stream of tokens
+with invented kids cannot be used to aim traffic at BID.
+
+## One thing that is load-bearing and easy to undo
+
+The session cookie is `SameSite=Lax`, not `Strict`. The callback from Broberg ID
+is a top-level navigation from another site, and `Strict` withholds the cookie
+on exactly that navigation — every sign-in would fail with "state does not
+match", which sends you looking at the OAuth flow instead of at a cookie flag.
+
+## Licence
+
+MIT

package/dist/hono.cjs

@@ -0,0 +1,510 @@
+'use strict';
+
+var hono = require('hono');
+var jose = require('jose');
+
+// src/hono.ts
+
+// src/config.ts
+var SsoConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SsoConfigError";
+  }
+};
+function required(env, name, hint) {
+  const raw = env[name];
+  if (typeof raw !== "string" || raw.trim() === "") {
+    throw new SsoConfigError(`${name} is not set (or is blank). ${hint}`);
+  }
+  return raw.trim();
+}
+var DEFAULT_SESSION_MAX_AGE = 60 * 60 * 24 * 7;
+function loadSsoConfig(env = process.env) {
+  const rawIssuer = required(
+    env,
+    "BID_ISSUER",
+    "It is Broberg ID's bare origin, e.g. https://id.broberg.ai"
+  );
+  let issuer;
+  try {
+    const url = new URL(rawIssuer);
+    if (url.protocol !== "https:" && url.hostname !== "localhost") {
+      throw new SsoConfigError(
+        `BID_ISSUER must be https (got ${url.protocol}//). Only localhost may be http.`
+      );
+    }
+    issuer = url.origin;
+  } catch (err) {
+    if (err instanceof SsoConfigError) throw err;
+    throw new SsoConfigError(`BID_ISSUER is not a valid URL: ${rawIssuer}`);
+  }
+  const cookieSecret = required(
+    env,
+    "SSO_COOKIE_SECRET",
+    "Generate one with `openssl rand -hex 32`. It signs this app's session cookie."
+  );
+  if (cookieSecret.length < 32) {
+    throw new SsoConfigError(
+      `SSO_COOKIE_SECRET is ${cookieSecret.length} characters; it must be at least 32. A short secret is a forgeable session, and a forged session is any user you like.`
+    );
+  }
+  const rawMaxAge = env.SSO_SESSION_MAX_AGE?.trim();
+  let sessionMaxAge = DEFAULT_SESSION_MAX_AGE;
+  if (rawMaxAge) {
+    const n = Number(rawMaxAge);
+    if (!Number.isFinite(n) || n <= 0) {
+      throw new SsoConfigError(
+        `SSO_SESSION_MAX_AGE must be a positive number of seconds (got ${JSON.stringify(rawMaxAge)}).`
+      );
+    }
+    sessionMaxAge = Math.floor(n);
+  }
+  return {
+    issuer,
+    clientId: required(env, "SSO_CLIENT_ID", "The id this app is registered under in Broberg ID."),
+    redirectUri: required(
+      env,
+      "SSO_REDIRECT_URI",
+      "Must match the registered redirect EXACTLY \u2014 one trailing slash is a different address."
+    ),
+    scopes: (env.SSO_SCOPES?.trim() || "openid profile email").split(/\s+/),
+    cookieSecret,
+    cookieName: env.SSO_COOKIE_NAME?.trim() || "bid_session",
+    sessionMaxAge,
+    postLogoutRedirectUri: env.SSO_POST_LOGOUT_REDIRECT_URI?.trim() || void 0
+  };
+}
+var JwksError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "JwksError";
+  }
+};
+function createJwksCache(options) {
+  const {
+    jwksUri,
+    minRefetchIntervalMs = 1e4,
+    fetchImpl = fetch,
+    now = () => Date.now()
+  } = options;
+  let keys = [];
+  let lastFetchAt = -Infinity;
+  let fetchCount = 0;
+  let inFlight = null;
+  async function refresh() {
+    if (inFlight) return inFlight;
+    inFlight = (async () => {
+      const res = await fetchImpl(jwksUri);
+      if (!res.ok) {
+        throw new JwksError(`${jwksUri} answered ${res.status} \u2014 cannot verify any token`);
+      }
+      const body = await res.json();
+      if (!Array.isArray(body.keys)) {
+        throw new JwksError(`${jwksUri} returned no "keys" array`);
+      }
+      keys = body.keys;
+      lastFetchAt = now();
+      fetchCount++;
+    })().finally(() => {
+      inFlight = null;
+    });
+    return inFlight;
+  }
+  return {
+    get fetchCount() {
+      return fetchCount;
+    },
+    async getKey(kid, alg) {
+      let jwk = keys.find((k) => k.kid === kid);
+      if (!jwk) {
+        const sinceLast = now() - lastFetchAt;
+        if (sinceLast < minRefetchIntervalMs) {
+          throw new JwksError(
+            `no signing key with kid ${kid}, and the key set was refreshed ${sinceLast}ms ago (floor is ${minRefetchIntervalMs}ms). Refusing to refetch \u2014 retry shortly.`
+          );
+        }
+        await refresh();
+        jwk = keys.find((k) => k.kid === kid);
+      }
+      if (!jwk) {
+        throw new JwksError(
+          `Broberg ID does not publish a signing key with kid ${kid}. The token was not signed by this issuer.`
+        );
+      }
+      return jose.importJWK(jwk, alg);
+    }
+  };
+}
+
+// src/client.ts
+var SsoError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SsoError";
+  }
+};
+var b64url = (bytes) => {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let s = "";
+  for (const b of view) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+var randomToken = (bytes = 32) => b64url(crypto.getRandomValues(new Uint8Array(bytes)));
+async function challengeFor(verifier) {
+  return b64url(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier)));
+}
+function createSsoClient(config, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  let discoveryPromise = null;
+  let jwksCache = null;
+  async function discovery() {
+    discoveryPromise ??= (async () => {
+      const url = `${config.issuer}/.well-known/openid-configuration`;
+      const res = await fetchImpl(url);
+      if (!res.ok) throw new SsoError(`${url} answered ${res.status}`);
+      const doc = await res.json();
+      if (doc.issuer !== config.issuer) {
+        throw new SsoError(
+          `BID_ISSUER is ${config.issuer} but ${url} says its issuer is ${doc.issuer}. These must match exactly \u2014 tokens are validated against the issuer string.`
+        );
+      }
+      return doc;
+    })().catch((err) => {
+      discoveryPromise = null;
+      throw err;
+    });
+    return discoveryPromise;
+  }
+  async function keys() {
+    if (!jwksCache) {
+      const { jwks_uri } = await discovery();
+      jwksCache = createJwksCache({
+        jwksUri: jwks_uri,
+        fetchImpl,
+        ...options.minRefetchIntervalMs !== void 0 ? { minRefetchIntervalMs: options.minRefetchIntervalMs } : {}
+      });
+    }
+    return jwksCache;
+  }
+  async function verifyIdToken(idToken, opts = {}) {
+    const cache = await keys();
+    const header = jose.decodeProtectedHeader(idToken);
+    if (!header.kid) throw new SsoError("ID token has no kid \u2014 cannot pick a signing key");
+    const { payload } = await jose.jwtVerify(
+      idToken,
+      async () => cache.getKey(header.kid, header.alg ?? "RS256"),
+      { issuer: config.issuer, audience: config.clientId }
+    );
+    if (opts.nonce !== void 0 && payload.nonce !== opts.nonce) {
+      throw new SsoError(
+        "ID token nonce does not match this login request \u2014 refusing a token minted for another sign-in."
+      );
+    }
+    if (typeof payload.sub !== "string" || payload.sub === "") {
+      throw new SsoError("ID token has no sub \u2014 there is no user to be");
+    }
+    return payload;
+  }
+  async function withUserInfo(claims, accessToken) {
+    const doc = await discovery();
+    if (!doc.userinfo_endpoint) return claims;
+    const res = await fetchImpl(doc.userinfo_endpoint, {
+      headers: { authorization: `Bearer ${accessToken}` }
+    });
+    if (!res.ok) return claims;
+    const info = await res.json();
+    if (info.sub !== claims.sub) {
+      throw new SsoError(
+        `userinfo describes ${String(info.sub)} but the ID token is for ${claims.sub} \u2014 refusing to merge another user's profile onto this session.`
+      );
+    }
+    return { ...claims, ...info, sub: claims.sub };
+  }
+  return {
+    discovery,
+    get jwks() {
+      if (!jwksCache) throw new SsoError("the key cache is created on first verification");
+      return jwksCache;
+    },
+    verifyIdToken,
+    async beginLogin(opts = {}) {
+      const { authorization_endpoint } = await discovery();
+      const codeVerifier = randomToken();
+      const state = randomToken(16);
+      const nonce = randomToken(16);
+      const params = new URLSearchParams({
+        response_type: "code",
+        client_id: config.clientId,
+        redirect_uri: config.redirectUri,
+        scope: [.../* @__PURE__ */ new Set([...config.scopes, ...opts.scopes ?? []])].join(" "),
+        state,
+        nonce,
+        code_challenge: await challengeFor(codeVerifier),
+        code_challenge_method: "S256"
+      });
+      if (opts.prompt) params.set("prompt", opts.prompt);
+      return { url: `${authorization_endpoint}?${params}`, state, codeVerifier, nonce };
+    },
+    async completeLogin({ params, state, codeVerifier, nonce }) {
+      const error = params.get("error");
+      if (error) {
+        throw new SsoError(
+          `Broberg ID refused this login: ${error}` + (params.get("error_description") ? ` \u2014 ${params.get("error_description")}` : "")
+        );
+      }
+      const returned = params.get("state");
+      if (!returned || returned !== state) {
+        throw new SsoError(
+          "state does not match the login this browser started \u2014 refusing the callback."
+        );
+      }
+      const code = params.get("code");
+      if (!code) throw new SsoError("callback carried neither an error nor a code");
+      const { token_endpoint } = await discovery();
+      const res = await fetchImpl(token_endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          code,
+          redirect_uri: config.redirectUri,
+          client_id: config.clientId,
+          code_verifier: codeVerifier
+        })
+      });
+      const body = await res.json();
+      if (!res.ok || !body.id_token) {
+        throw new SsoError(
+          `token exchange failed (${res.status}): ${body.error ?? "no id_token in response"}` + (body.error_description ? ` \u2014 ${body.error_description}` : "")
+        );
+      }
+      const claims = await verifyIdToken(body.id_token, { nonce });
+      return {
+        claims: body.access_token ? await withUserInfo(claims, body.access_token) : claims,
+        idToken: body.id_token,
+        ...body.access_token ? { accessToken: body.access_token } : {},
+        ...body.refresh_token ? { refreshToken: body.refresh_token } : {}
+      };
+    },
+    async logoutUrl(opts = {}) {
+      const doc = await discovery();
+      if (!doc.end_session_endpoint) {
+        throw new SsoError(
+          `${config.issuer} does not advertise end_session_endpoint \u2014 central logout is unavailable.`
+        );
+      }
+      const params = new URLSearchParams();
+      if (opts.idTokenHint) params.set("id_token_hint", opts.idTokenHint);
+      const post = opts.postLogoutRedirectUri ?? config.postLogoutRedirectUri;
+      if (post) params.set("post_logout_redirect_uri", post);
+      params.set("client_id", config.clientId);
+      return `${doc.end_session_endpoint}?${params}`;
+    }
+  };
+}
+
+// src/session.ts
+var enc = new TextEncoder();
+var b64url2 = (bytes) => {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+var fromB64url = (s) => {
+  const pad = s.replace(/-/g, "+").replace(/_/g, "/");
+  const bin = atob(pad + "=".repeat((4 - pad.length % 4) % 4));
+  return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+};
+async function hmacKey(secret) {
+  return crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign",
+    "verify"
+  ]);
+}
+async function signValue(value, secret) {
+  const body = b64url2(enc.encode(value));
+  const sig = new Uint8Array(await crypto.subtle.sign("HMAC", await hmacKey(secret), enc.encode(body)));
+  return `${body}.${b64url2(sig)}`;
+}
+async function verifyValue(token, secret) {
+  if (!token) return null;
+  const dot = token.lastIndexOf(".");
+  if (dot <= 0) return null;
+  const body = token.slice(0, dot);
+  try {
+    const ok = await crypto.subtle.verify(
+      "HMAC",
+      await hmacKey(secret),
+      fromB64url(token.slice(dot + 1)),
+      enc.encode(body)
+    );
+    if (!ok) return null;
+    return new TextDecoder().decode(fromB64url(body));
+  } catch {
+    return null;
+  }
+}
+async function signSession(payload, secret) {
+  return signValue(JSON.stringify(payload), secret);
+}
+async function verifySession(token, secret, now = Date.now) {
+  const body = await verifyValue(token, secret);
+  if (body === null) return null;
+  try {
+    const payload = JSON.parse(body);
+    if (typeof payload.sub !== "string" || payload.sub === "") return null;
+    if (typeof payload.exp !== "number" || payload.exp * 1e3 <= now()) return null;
+    return payload;
+  } catch {
+    return null;
+  }
+}
+function cookieHeader(name, value, opts) {
+  const parts = [
+    `${name}=${value}`,
+    `Path=${opts.path ?? "/"}`,
+    `Max-Age=${opts.maxAge}`,
+    "HttpOnly",
+    // Lax, NOT Strict, and this is load-bearing: the callback from Broberg ID
+    // is a top-level GET navigation from another site. Strict withholds the
+    // cookie on exactly that navigation, so the login transaction cookie would
+    // be missing when it is needed and every sign-in would fail with "state
+    // does not match" — a message that sends you looking in the wrong place.
+    `SameSite=${opts.sameSite ?? "Lax"}`
+  ];
+  if (opts.secure) parts.push("Secure");
+  return parts.join("; ");
+}
+function readCookie(header, name) {
+  if (!header) return void 0;
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();
+  }
+  return void 0;
+}
+
+// src/hono.ts
+var SESSION_KEY = "bidSession";
+var TRANSACTION_MAX_AGE = 300;
+function isSecure(c) {
+  return new URL(c.req.url).protocol === "https:";
+}
+function safeReturnTo(raw, fallback) {
+  if (!raw) return fallback;
+  if (!raw.startsWith("/") || raw.startsWith("//")) return fallback;
+  return raw;
+}
+function ssoRoutes(options = {}) {
+  const config = options.config ?? loadSsoConfig();
+  const client = options.client ?? createSsoClient(config);
+  const loginPath = options.loginPath ?? "/auth";
+  const defaultReturnTo = options.defaultReturnTo ?? "/";
+  const txCookie = `${config.cookieName}_tx`;
+  const app = new hono.Hono();
+  app.get("/login", async (c) => {
+    const prompt = c.req.query("prompt");
+    const start = await client.beginLogin(
+      prompt === "none" ? { prompt: "none" } : {}
+    );
+    const tx = JSON.stringify({
+      state: start.state,
+      codeVerifier: start.codeVerifier,
+      nonce: start.nonce,
+      returnTo: safeReturnTo(c.req.query("returnTo"), defaultReturnTo)
+    });
+    c.header(
+      "Set-Cookie",
+      cookieHeader(txCookie, await signValue(tx, config.cookieSecret), {
+        maxAge: TRANSACTION_MAX_AGE,
+        secure: isSecure(c)
+      })
+    );
+    return c.redirect(start.url, 302);
+  });
+  app.get("/callback", async (c) => {
+    const parsed = await parseTransaction(
+      readCookie(c.req.header("cookie"), txCookie),
+      config.cookieSecret
+    );
+    if (!parsed) {
+      return c.json(
+        { error: "no_login_in_progress", message: "This browser did not start a login here, or it expired." },
+        400
+      );
+    }
+    const result = await client.completeLogin({
+      params: new URL(c.req.url).searchParams,
+      state: parsed.state,
+      codeVerifier: parsed.codeVerifier,
+      nonce: parsed.nonce
+    });
+    const exp = Math.floor(Date.now() / 1e3) + config.sessionMaxAge;
+    const session = {
+      sub: result.claims.sub,
+      exp,
+      ...result.claims.email ? { email: result.claims.email } : {},
+      ...result.claims.name ? { name: result.claims.name } : {}
+    };
+    c.header(
+      "Set-Cookie",
+      cookieHeader(config.cookieName, await signSession(session, config.cookieSecret), {
+        maxAge: config.sessionMaxAge,
+        secure: isSecure(c)
+      })
+    );
+    c.header(
+      "Set-Cookie",
+      cookieHeader(txCookie, "", { maxAge: 0, secure: isSecure(c) }),
+      { append: true }
+    );
+    return c.redirect(parsed.returnTo, 302);
+  });
+  app.get("/logout", async (c) => {
+    c.header(
+      "Set-Cookie",
+      cookieHeader(config.cookieName, "", { maxAge: 0, secure: isSecure(c) })
+    );
+    return c.redirect(await client.logoutUrl(), 302);
+  });
+  const attach = async (c, next) => {
+    const cookie = readCookie(c.req.header("cookie"), config.cookieName);
+    c.set(SESSION_KEY, await verifySession(cookie, config.cookieSecret));
+    await next();
+  };
+  const require2 = async (c, next) => {
+    const cookie = readCookie(c.req.header("cookie"), config.cookieName);
+    const session = await verifySession(cookie, config.cookieSecret);
+    if (!session) {
+      const url = new URL(c.req.url);
+      return c.redirect(
+        `${loginPath}/login?returnTo=${encodeURIComponent(url.pathname + url.search)}`,
+        302
+      );
+    }
+    c.set(SESSION_KEY, session);
+    await next();
+  };
+  return { app, attach, require: require2, client, config };
+}
+async function parseTransaction(raw, secret) {
+  const body = await verifyValue(raw, secret);
+  if (body === null) return null;
+  try {
+    const tx = JSON.parse(body);
+    if (!tx.state || !tx.codeVerifier || !tx.nonce) return null;
+    return tx;
+  } catch {
+    return null;
+  }
+}
+function getSession(c) {
+  return c.get(SESSION_KEY) ?? null;
+}
+
+exports.getSession = getSession;
+exports.ssoRoutes = ssoRoutes;
+//# sourceMappingURL=hono.cjs.map
+//# sourceMappingURL=hono.cjs.map