@broberg/sso 0.7.0 → 0.9.0

package/README.md

@@ -338,4 +338,58 @@ ssoRoutes({ logout: "central" });
 
 ## email_verified on the session (since 0.7.0)
 
-`getSession(c).email_verified` is `true` or `false` when BID said so, and absent when it did not. **Bind access to an email address only when it is `true`** — e.g. `session.email === "cb@broberg.ai" && session.email_verified === true`. Sessions minted before 0.7.0 have no such field; treat absent as not verified.
+`getSession(c).email_verified` is `true` or `false` when BID said so, and absent when it did not. Sessions minted before 0.7.0 have no such field; treat absent as not verified.
+
+> **On BID today, `email` and `email_verified` are NOT signed.** BID's ID token does not carry them — measured by broberg-id on 20 Sep 2026 against the real service: the token holds `acr · at_hash · aud · auth_time · exp · iat · iss · nonce · sid · sub`, and email + email_verified exist only in the `/oauth2/userinfo` response, which is plain HTTP with no signature. `email_verified === true` is still the right thing to require before linking on an address, but it is BID's word over TLS, not a signed claim.
+>
+> **If a decision must rest on a signed identity, bind on `sub`** (`session.sub`) — the ID token signs it, and the package refuses a userinfo answer whose `sub` differs. helpdesk moved its account linking from email to `sub` for exactly this reason.
+
+## Which claims were signed — `unverifiedClaims` (since 0.8.0)
+
+`completeLogin()` returns `unverifiedClaims: string[]` beside `claims`: the claims that came from the unsigned userinfo response and not from the signed ID token, sorted. Against BID today it is `["email", "email_verified", "name", …]`. An empty list means everything in `claims` was signed, or userinfo was not reached.
+
+When both sources carry a claim, **the signed token's value wins** and the claim is not listed. Before 0.8.0 userinfo was spread over the token, so an issuer whose userinfo disagreed with its own token had the unsigned value win. Against BID this changes nothing today — the two never overlap on email — so for BID it is a hardening, not a fix.
+
+## Calling BID as the user — the token store (since 0.9.0)
+
+The login already receives an **access token** and a **refresh token**. Give
+`ssoRoutes` a `tokenStore` and they are kept **server-side**, so your app can
+call BID's app API as the user — the account page (read and change your own
+name and picture) is the first thing that needs it.
+
+```ts
+import { ssoRoutes } from "@broberg/sso/hono";
+import type { TokenStore } from "@broberg/sso";
+
+const tokenStore: TokenStore = {            // backed by YOUR database (SQLite, Postgres, Redis …)
+  get: (sid) => db.tokens.get(sid),
+  set: (sid, t) => db.tokens.put(sid, t),   // t = { sub, accessToken, refreshToken?, expiresAt }
+  delete: (sid) => db.tokens.delete(sid),
+  deleteSub: (sub) => db.tokens.deleteWhere({ sub }),
+};
+const sso = ssoRoutes({ tokenStore, backchannel: { store } });
+
+app.get("/api/something", sso.require, async (c) => {
+  const token = await sso.getAccessToken(c);   // renewed for you when it has expired
+  …
+});
+```
+
+- **Never in the cookie.** The session cookie is signed, not encrypted, and the
+  browser can read it. It carries only a random `sid`; the tokens live in your
+  store under that key.
+- **`getAccessToken(c)`** returns the stored token, and when it has expired (or
+  is within 30 s of it) renews it with the refresh token, stores the new pair
+  and returns the new token. Two requests that need renewal at the same moment
+  share one renewal (with rotation, a second one would be refused).
+- **It throws `SsoError`, never returns a stale or empty token** — no live
+  session, a session from before you configured a store, no tokens, or a refused
+  renewal. A refused renewal also deletes the dead pair. The message names the
+  status and BID's error code, never a token.
+- **The tokens die with the session:** «Log ud» deletes the pair, and «Log ud
+  overalt» (the back channel) calls `deleteSub(sub)` — inside the same step, so
+  a failure is reported to BID as not done.
+- **`memoryTokenStore()`** is the reference implementation for tests and one
+  dev process. It warns once: in production it loses every user's tokens on a
+  restart and is not shared between machines.
+- **Without `tokenStore`, nothing changes** — login behaves exactly as in 0.8.0.

package/dist/hono.cjs

@@ -360,18 +360,19 @@ function createSsoClient(config, options = {}) {
   }
   async function withUserInfo(claims, accessToken) {
     const doc = await discovery();
-    if (!doc.userinfo_endpoint) return claims;
+    if (!doc.userinfo_endpoint) return { claims, unverifiedClaims: [] };
     const res = await fetchImpl(doc.userinfo_endpoint, {
       headers: { authorization: `Bearer ${accessToken}` }
     });
-    if (!res.ok) return claims;
+    if (!res.ok) return { claims, unverifiedClaims: [] };
     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 };
+    const unverifiedClaims = Object.keys(info).filter((k) => k !== "sub" && info[k] !== void 0 && !(k in claims)).sort();
+    return { claims: { ...info, ...claims, sub: claims.sub }, unverifiedClaims };
   }
   return {
     discovery,
@@ -443,11 +444,42 @@ function createSsoClient(config, options = {}) {
         );
       }
       const claims = await verifyIdToken(body.id_token, { nonce });
+      const merged = body.access_token ? await withUserInfo(claims, body.access_token) : { claims, unverifiedClaims: [] };
       return {
-        claims: body.access_token ? await withUserInfo(claims, body.access_token) : claims,
+        claims: merged.claims,
+        unverifiedClaims: merged.unverifiedClaims,
         idToken: body.id_token,
         ...body.access_token ? { accessToken: body.access_token } : {},
-        ...body.refresh_token ? { refreshToken: body.refresh_token } : {}
+        ...body.refresh_token ? { refreshToken: body.refresh_token } : {},
+        ...typeof body.expires_in === "number" ? { expiresIn: body.expires_in } : {}
+      };
+    },
+    async refreshTokens(refreshToken) {
+      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: "refresh_token",
+          refresh_token: refreshToken,
+          client_id: config.clientId,
+          ...config.clientSecret ? { client_secret: config.clientSecret } : {}
+        })
+      });
+      const raw = await res.text();
+      let body;
+      try {
+        body = raw.trim() === "" ? {} : JSON.parse(raw);
+      } catch {
+        throw new SsoError(`token refresh failed (${res.status}): the response body is not JSON`);
+      }
+      if (!res.ok || typeof body.access_token !== "string" || body.access_token === "") {
+        throw new SsoError(`token refresh failed (${res.status}): ${body.error ?? "no access_token in response"}`);
+      }
+      return {
+        accessToken: body.access_token,
+        ...typeof body.refresh_token === "string" && body.refresh_token ? { refreshToken: body.refresh_token } : {},
+        ...typeof body.expires_in === "number" ? { expiresIn: body.expires_in } : {}
       };
     },
     async logoutUrl(opts = {}) {
@@ -508,6 +540,26 @@ function createSsoClient(config, options = {}) {
   };
 }
 
+// src/tokens.ts
+function expiresAtFrom(expiresIn, accessToken, now) {
+  if (typeof expiresIn === "number" && expiresIn > 0) return now + Math.floor(expiresIn);
+  const parts = accessToken.split(".");
+  if (parts.length === 3) {
+    try {
+      const json = JSON.parse(atob(parts[1].replace(/-/g, "+").replace(/_/g, "/")));
+      if (typeof json.exp === "number" && json.exp > now) return json.exp;
+    } catch {
+    }
+  }
+  return now + 300;
+}
+function newSid() {
+  const b = crypto.getRandomValues(new Uint8Array(16));
+  let s = "";
+  for (const x of b) s += String.fromCharCode(x);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
 // src/session.ts
 var enc = new TextEncoder();
 var b64url2 = (bytes) => {
@@ -638,6 +690,7 @@ function ssoRoutes(options = {}) {
     throw new Error("ssoRoutes: backchannel needs a store shared by every instance of the app \u2014 there is no in-memory default.");
   }
   const onStoreError = backchannel?.onStoreError ?? "reject";
+  const tokenStore = options.tokenStore;
   async function liveSession(c) {
     const session = await verifySession(readCookie(c.req.header("cookie"), config.cookieName), config.cookieSecret);
     if (!session || !backchannel) return session;
@@ -670,6 +723,7 @@ function ssoRoutes(options = {}) {
       }
       try {
         await backchannel.store.revokeSubBefore(verified.sub, verified.iat);
+        if (tokenStore) await tokenStore.deleteSub(verified.sub);
         await backchannel.store.useJti(verified.jti, verified.exp);
       } catch {
         return c.json({ error: "store_unavailable" }, 503);
@@ -733,11 +787,23 @@ function ssoRoutes(options = {}) {
       codeVerifier: parsed.tx.codeVerifier,
       nonce: parsed.tx.nonce
     });
-    const exp = Math.floor(Date.now() / 1e3) + config.sessionMaxAge;
+    const nowS = Math.floor(Date.now() / 1e3);
+    const exp = nowS + config.sessionMaxAge;
+    let sid;
+    if (tokenStore && result.accessToken) {
+      sid = newSid();
+      await tokenStore.set(sid, {
+        sub: result.claims.sub,
+        accessToken: result.accessToken,
+        ...result.refreshToken ? { refreshToken: result.refreshToken } : {},
+        expiresAt: expiresAtFrom(result.expiresIn, result.accessToken, nowS)
+      });
+    }
     const session = {
       sub: result.claims.sub,
       exp,
-      iat: Math.floor(Date.now() / 1e3),
+      iat: nowS,
+      ...sid ? { sid } : {},
       ...result.claims.email ? { email: result.claims.email } : {},
       ...result.claims.name ? { name: result.claims.name } : {},
       ...result.claims.picture ? { picture: result.claims.picture } : {},
@@ -771,6 +837,10 @@ function ssoRoutes(options = {}) {
       readCookie(c.req.header("cookie"), idTokenCookie),
       config.cookieSecret
     );
+    if (tokenStore) {
+      const leaving = await verifySession(readCookie(c.req.header("cookie"), config.cookieName), config.cookieSecret);
+      if (leaving?.sid) await tokenStore.delete(leaving.sid);
+    }
     c.header(
       "Set-Cookie",
       cookieHeader(config.cookieName, "", { maxAge: 0, secure: isSecure(c) })
@@ -801,7 +871,54 @@ function ssoRoutes(options = {}) {
     c.set(SESSION_KEY, session);
     await next();
   };
-  return { app, attach, require: require2, client, config };
+  const refreshing = /* @__PURE__ */ new Map();
+  async function getAccessToken(c) {
+    if (!tokenStore) {
+      throw new SsoError("getAccessToken needs ssoRoutes({ tokenStore }) \u2014 without one the login's tokens are not kept.");
+    }
+    const raw = await verifySession(readCookie(c.req.header("cookie"), config.cookieName), config.cookieSecret);
+    const live = await liveSession(c);
+    if (!live) {
+      if (raw?.sid) await tokenStore.delete(raw.sid);
+      throw new SsoError("no live session \u2014 log in again.");
+    }
+    const sid = live.sid;
+    if (!sid) throw new SsoError("this session has no stored tokens (it began before tokenStore was configured) \u2014 log in again.");
+    const tokens = await tokenStore.get(sid);
+    if (!tokens) throw new SsoError("no tokens stored for this session \u2014 log in again.");
+    const now = Math.floor(Date.now() / 1e3);
+    if (tokens.expiresAt - 30 > now) return tokens.accessToken;
+    if (!tokens.refreshToken) {
+      await tokenStore.delete(sid);
+      throw new SsoError("the access token has expired and there is no refresh token \u2014 log in again.");
+    }
+    const inFlight = refreshing.get(sid);
+    if (inFlight) return inFlight;
+    const p = (async () => {
+      let next;
+      try {
+        next = await client.refreshTokens(tokens.refreshToken);
+      } catch (e) {
+        await tokenStore.delete(sid);
+        throw e instanceof SsoError ? e : new SsoError("token refresh failed");
+      }
+      await tokenStore.set(sid, {
+        sub: tokens.sub,
+        accessToken: next.accessToken,
+        // Rotation: use the new one if BID issued one, else keep the old.
+        ...next.refreshToken ?? tokens.refreshToken ? { refreshToken: next.refreshToken ?? tokens.refreshToken } : {},
+        expiresAt: expiresAtFrom(next.expiresIn, next.accessToken, Math.floor(Date.now() / 1e3))
+      });
+      return next.accessToken;
+    })();
+    refreshing.set(sid, p);
+    try {
+      return await p;
+    } finally {
+      refreshing.delete(sid);
+    }
+  }
+  return { app, attach, require: require2, client, config, getAccessToken };
 }
 async function parseTransaction(raw, secret) {
   if (raw === void 0) return { ok: false, reason: "absent" };