@broberg/sso 0.7.0 → 0.9.0

package/dist/hono.d.cts

@@ -162,9 +162,23 @@ interface SsoClaims extends JWTPayload {
 }
 interface LoginResult {
     claims: SsoClaims;
+    /**
+     * The claims in `claims` that came from the UNSIGNED userinfo response and
+     * not from the signed ID token (components-F084.51, since 0.8.0). Sorted; 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.
+     *
+     * On BID today this always contains "email" and "email_verified": the ID
+     * token does not carry them (measured by broberg-id, 20 Sep 2026). A decision
+     * that must rest on a signed identity binds on `claims.sub`, never on email.
+     */
+    unverifiedClaims: string[];
     idToken: string;
     accessToken?: string;
     refreshToken?: string;
+    /** Seconds the access token lives, when BID said so (`expires_in`). */
+    expiresIn?: number;
 }
 /**
  * `prompt=none` asks BID to answer WITHOUT showing anything (components-F084.6).
@@ -204,6 +218,16 @@ interface SsoClient {
      * answers — see the implementation for why that must never become "unverified".
      */
     addressOwnership(accessToken: string, address: string): Promise<AddressOwnership>;
+    /**
+     * F095.1 — trade a refresh token for a new access token (`grant_type=refresh_token`).
+     * Throws SsoError on refusal; the message carries the status and BID's error
+     * code, never a token.
+     */
+    refreshTokens(refreshToken: string): Promise<{
+        accessToken: string;
+        refreshToken?: string;
+        expiresIn?: number;
+    }>;
     /**
      * Invite users to BID on behalf of this app (the app's OWN key, `bidk_…`).
      * One result per email. Throws SsoError on anything BID did not clearly say.
@@ -259,6 +283,41 @@ interface LogoutToken {
     exp: number;
 }
 
+/**
+ * Server-side tokens for calling Broberg ID on the user's behalf (F095.1).
+ *
+ * The login already RECEIVES an access token and a refresh token; before 0.9.0
+ * ssoRoutes dropped both, so an app could not call BID's app API (the account
+ * page: read and change your own name and picture) as the user.
+ *
+ * ── WHY NOT IN THE COOKIE ────────────────────────────────────────────────
+ * The session cookie is SIGNED, not encrypted, and the browser can read it. A
+ * refresh token is the longest-lived, highest-value credential in the whole
+ * flow: whoever holds it can mint access tokens until it is revoked. So the
+ * tokens live server-side, keyed by a random `sid` that is the only thing the
+ * cookie carries. A stolen cookie still needs the server to be useful.
+ */
+interface TokenSet {
+    /** The BID subject the tokens belong to — lets «Log ud overalt» find them. */
+    sub: string;
+    accessToken: string;
+    refreshToken?: string;
+    /** Unix seconds. */
+    expiresAt: number;
+}
+/**
+ * Where the tokens live. The APP provides it in production, backed by
+ * something every instance shares (SQLite on one machine, a database or Redis
+ * on several) — the same reason BackchannelStore has no in-memory default.
+ */
+interface TokenStore {
+    get(sid: string): Promise<TokenSet | undefined>;
+    set(sid: string, tokens: TokenSet): Promise<void>;
+    delete(sid: string): Promise<void>;
+    /** Drop every token set for `sub` — what «Log ud overalt» calls. */
+    deleteSub(sub: string): Promise<void>;
+}
+
 /**
  * The app's OWN session cookie — signed, not encrypted.
  *
@@ -284,6 +343,12 @@ interface SessionPayload {
      * older than any logout.
      */
     iat?: number;
+    /**
+     * F095.1 — the key to this session's server-side tokens (ssoRoutes'
+     * `tokenStore`). Random, 128 bits. The tokens themselves are NEVER in the
+     * cookie: it is signed, not encrypted, and the browser can read it.
+     */
+    sid?: string;
     /** Optional convenience copies; never authorisation data. */
     email?: string;
     name?: string;
@@ -344,6 +409,12 @@ interface SsoRoutesOptions {
     loginPath?: string;
     /** Where to send a user after a successful login when no returnTo is given. */
     defaultReturnTo?: string;
+    /**
+     * F095.1 — keep the user's access and refresh token SERVER-SIDE, so the app
+     * can call BID's app API (the account page) as the user via getAccessToken.
+     * Without it, login behaves exactly as in 0.8.0 and the tokens are dropped.
+     */
+    tokenStore?: TokenStore;
 }
 declare function ssoRoutes(options?: SsoRoutesOptions): {
     app: Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
@@ -351,6 +422,7 @@ declare function ssoRoutes(options?: SsoRoutesOptions): {
     require: MiddlewareHandler;
     client: SsoClient;
     config: SsoConfig;
+    getAccessToken: (c: Context) => Promise<string>;
 };
 /** Why a login transaction could not be read back. Three states, three answers. */
 type TransactionFailure = "absent" | "expired" | "unreadable";

package/dist/hono.d.ts

@@ -162,9 +162,23 @@ interface SsoClaims extends JWTPayload {
 }
 interface LoginResult {
     claims: SsoClaims;
+    /**
+     * The claims in `claims` that came from the UNSIGNED userinfo response and
+     * not from the signed ID token (components-F084.51, since 0.8.0). Sorted; 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.
+     *
+     * On BID today this always contains "email" and "email_verified": the ID
+     * token does not carry them (measured by broberg-id, 20 Sep 2026). A decision
+     * that must rest on a signed identity binds on `claims.sub`, never on email.
+     */
+    unverifiedClaims: string[];
     idToken: string;
     accessToken?: string;
     refreshToken?: string;
+    /** Seconds the access token lives, when BID said so (`expires_in`). */
+    expiresIn?: number;
 }
 /**
  * `prompt=none` asks BID to answer WITHOUT showing anything (components-F084.6).
@@ -204,6 +218,16 @@ interface SsoClient {
      * answers — see the implementation for why that must never become "unverified".
      */
     addressOwnership(accessToken: string, address: string): Promise<AddressOwnership>;
+    /**
+     * F095.1 — trade a refresh token for a new access token (`grant_type=refresh_token`).
+     * Throws SsoError on refusal; the message carries the status and BID's error
+     * code, never a token.
+     */
+    refreshTokens(refreshToken: string): Promise<{
+        accessToken: string;
+        refreshToken?: string;
+        expiresIn?: number;
+    }>;
     /**
      * Invite users to BID on behalf of this app (the app's OWN key, `bidk_…`).
      * One result per email. Throws SsoError on anything BID did not clearly say.
@@ -259,6 +283,41 @@ interface LogoutToken {
     exp: number;
 }
 
+/**
+ * Server-side tokens for calling Broberg ID on the user's behalf (F095.1).
+ *
+ * The login already RECEIVES an access token and a refresh token; before 0.9.0
+ * ssoRoutes dropped both, so an app could not call BID's app API (the account
+ * page: read and change your own name and picture) as the user.
+ *
+ * ── WHY NOT IN THE COOKIE ────────────────────────────────────────────────
+ * The session cookie is SIGNED, not encrypted, and the browser can read it. A
+ * refresh token is the longest-lived, highest-value credential in the whole
+ * flow: whoever holds it can mint access tokens until it is revoked. So the
+ * tokens live server-side, keyed by a random `sid` that is the only thing the
+ * cookie carries. A stolen cookie still needs the server to be useful.
+ */
+interface TokenSet {
+    /** The BID subject the tokens belong to — lets «Log ud overalt» find them. */
+    sub: string;
+    accessToken: string;
+    refreshToken?: string;
+    /** Unix seconds. */
+    expiresAt: number;
+}
+/**
+ * Where the tokens live. The APP provides it in production, backed by
+ * something every instance shares (SQLite on one machine, a database or Redis
+ * on several) — the same reason BackchannelStore has no in-memory default.
+ */
+interface TokenStore {
+    get(sid: string): Promise<TokenSet | undefined>;
+    set(sid: string, tokens: TokenSet): Promise<void>;
+    delete(sid: string): Promise<void>;
+    /** Drop every token set for `sub` — what «Log ud overalt» calls. */
+    deleteSub(sub: string): Promise<void>;
+}
+
 /**
  * The app's OWN session cookie — signed, not encrypted.
  *
@@ -284,6 +343,12 @@ interface SessionPayload {
      * older than any logout.
      */
     iat?: number;
+    /**
+     * F095.1 — the key to this session's server-side tokens (ssoRoutes'
+     * `tokenStore`). Random, 128 bits. The tokens themselves are NEVER in the
+     * cookie: it is signed, not encrypted, and the browser can read it.
+     */
+    sid?: string;
     /** Optional convenience copies; never authorisation data. */
     email?: string;
     name?: string;
@@ -344,6 +409,12 @@ interface SsoRoutesOptions {
     loginPath?: string;
     /** Where to send a user after a successful login when no returnTo is given. */
     defaultReturnTo?: string;
+    /**
+     * F095.1 — keep the user's access and refresh token SERVER-SIDE, so the app
+     * can call BID's app API (the account page) as the user via getAccessToken.
+     * Without it, login behaves exactly as in 0.8.0 and the tokens are dropped.
+     */
+    tokenStore?: TokenStore;
 }
 declare function ssoRoutes(options?: SsoRoutesOptions): {
     app: Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
@@ -351,6 +422,7 @@ declare function ssoRoutes(options?: SsoRoutesOptions): {
     require: MiddlewareHandler;
     client: SsoClient;
     config: SsoConfig;
+    getAccessToken: (c: Context) => Promise<string>;
 };
 /** Why a login transaction could not be read back. Three states, three answers. */
 type TransactionFailure = "absent" | "expired" | "unreadable";

package/dist/hono.js

@@ -358,18 +358,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,
@@ -441,11 +442,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 = {}) {
@@ -506,6 +538,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) => {
@@ -636,6 +688,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;
@@ -668,6 +721,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);
@@ -731,11 +785,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 } : {},
@@ -769,6 +835,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) })
@@ -799,7 +869,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" };