@broberg/sso 0.9.0 → 0.10.0

package/README.md

@@ -389,7 +389,76 @@ app.get("/api/something", sso.require, async (c) => {
 - **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.
+- **Purge old rows yourself — the package cannot.** A session that simply
+  expires (no «Log ud»), or a new login that replaces one without a logout,
+  leaves its row in your store indefinitely; nothing ever calls `delete` for it.
+  Delete rows older than `sessionMaxAge` (`SSO_SESSION_MAX_AGE`, default 7 days)
+  with a periodic job or a TTL — e.g. store a `createdAt` beside the row and
+  `DELETE FROM tokens WHERE created_at < now - sessionMaxAge`, or a Redis
+  `EX sessionMaxAge`. It matters because the row would hold a **refresh token**
+  if BID ever issues one, and a forgotten refresh token is a live credential.
+- **Since 0.10.0 the failures are `SsoReauthError`** (a subclass of `SsoError`,
+  so existing `catch` blocks still match) with a `reason`: `no_session`,
+  `no_tokens`, `expired` or `refresh_failed`. Every one of them means "log in
+  again".
 - **`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.
+
+## Your own profile — accountRoutes (since 0.10.0)
+
+The account page in your app: the signed-in user reads and changes her **own**
+name and picture without being sent to BID. Needs the token store above.
+
+```ts
+import { ssoRoutes, accountRoutes } from "@broberg/sso/hono";
+
+const sso = ssoRoutes({ tokenStore });
+app.route("/auth", sso.app);
+app.route("/api/account", accountRoutes(sso));   // pass what ssoRoutes returned
+```
+
+| route | does |
+|---|---|
+| `GET /api/account/profile` | `{sub, name, picture, email, account_url}` |
+| `POST /api/account/profile` `{"name":"…"}` | changes the name, answers the new profile |
+| `POST /api/account/profile/avatar` | raw image bytes as the body, `Content-Type: image/png`, `image/jpeg` or `image/webp`, max 2 MB |
+| `POST /api/account/profile/avatar/remove` | removes the picture |
+
+**Scopes.** Reading needs `profile` (in the default `SSO_SCOPES`). Changing needs
+`profile:write` — it must be in your app's registration at BID **and** in
+`SSO_SCOPES`, e.g. `SSO_SCOPES="openid profile email profile:write"`. A user who
+logged in before you added it gets `403 insufficient_scope` until she logs in again.
+
+**Every answer is JSON — it is an API, so never a login redirect:**
+
+| status | body | means — what the page should do |
+|---|---|---|
+| 403 | `{"error":"cross_site"}` | a write from another site (`Sec-Fetch-Site`), sibling subdomains included — call it from the app's own page |
+| 401 | `{"error":"unauthenticated"}` | no live session — send her to log in |
+| 401 | `{"error":"reauth"}` | the session's BID tokens are spent — «Log ind igen» |
+| 403 | `{"error":"insufficient_scope","scope":"profile:write"}` | «Log ind igen for at rette» |
+| 413 | `{"error":"too_large","max_bytes":2097152}` | picture over 2 MB (refused before a byte goes to BID) |
+| 415 | `{"error":"unsupported_type","accepted":[…]}` | not PNG, JPEG or WebP |
+| 4xx | `{"error":"<BID's code>"}` | BID refused the value (e.g. an invalid name) |
+| 502 | `{"error":"bid_unavailable"}` | BID did not answer usably |
+
+**`reauth` is the NORMAL case after an hour, not an edge case.** BID issues apps
+a one-hour access token and — measured in production, 2026-10-05 — **no refresh
+token**. So `getAccessToken` cannot renew, and an hour after login every
+account-page call answers `401 {"error":"reauth"}`. Build the page for that: a
+calm «Log ind igen» that goes to `/auth/login?returnTo=<the account page>`, not
+an error. The same answer comes back when BID itself refuses the token (a 401
+from BID — revoked, or the session was ended in BID). It is never a 500.
+
+**The core methods**, if you are not on Hono: `client.getProfile(token)`,
+`updateProfile(token, name)`, `uploadAvatar(token, bytes, contentType)`,
+`removeAvatar(token)` — each returns the profile. They throw named errors:
+`SsoInsufficientScopeError` (`.scope`), `SsoAvatarRejectedError` (`.reason`:
+`too_large` | `unsupported_type`, thrown **before** anything is sent) and
+`SsoAppApiError` (`.status`, BID's `.code`; `status` is null when BID did not
+answer). All extend `SsoError`. No message ever contains a token.
+
+Mail, password, passkeys, two-factor and sessions stay in BID: link to the
+profile's `account_url` in a new tab.

package/dist/hono.cjs

@@ -176,6 +176,45 @@ var SsoError = class extends Error {
     this.name = "SsoError";
   }
 };
+var SsoReauthError = class extends SsoError {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "SsoReauthError";
+  }
+  reason;
+};
+var SsoAppApiError = class extends SsoError {
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "SsoAppApiError";
+  }
+  status;
+  code;
+};
+var SsoInsufficientScopeError = class extends SsoAppApiError {
+  constructor(message, scope) {
+    super(message, 403, "insufficient_scope");
+    this.scope = scope;
+    this.name = "SsoInsufficientScopeError";
+  }
+  scope;
+};
+var SsoAvatarRejectedError = class extends SsoError {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "SsoAvatarRejectedError";
+  }
+  reason;
+};
+var MAX_AVATAR_BYTES = 2 * 1024 * 1024;
+var AVATAR_TYPES = ["image/png", "image/jpeg", "image/webp"];
+function mediaType(contentType) {
+  return (contentType ?? "").split(";")[0].trim().toLowerCase();
+}
 var b64url = (bytes) => {
   const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
   let s = "";
@@ -267,6 +306,68 @@ function createSsoClient(config, options = {}) {
       clearTimeout(timer);
     }
   }
+  async function appRequest(path, bearer, init, what) {
+    const url = new URL(path, config.issuer).toString();
+    const ctrl = new AbortController();
+    let timer;
+    const timedOut = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(new SsoAppApiError(`${url} did not answer within ${timeoutMs} ms \u2014 ${what} is unknown.`, null, void 0));
+        ctrl.abort();
+      }, timeoutMs);
+    });
+    const headers = { authorization: `Bearer ${bearer}` };
+    let body;
+    if (init.json !== void 0) {
+      headers["content-type"] = "application/json";
+      body = JSON.stringify(init.json);
+    } else if (init.bytes !== void 0) {
+      headers["content-type"] = init.contentType ?? "application/octet-stream";
+      body = init.bytes;
+    }
+    try {
+      const res = await Promise.race([
+        fetchImpl(url, { method: init.method, headers, ...body !== void 0 ? { body } : {}, signal: ctrl.signal }),
+        timedOut
+      ]);
+      const raw = await Promise.race([res.text(), timedOut]);
+      let parsed;
+      try {
+        parsed = raw.trim() === "" ? void 0 : JSON.parse(raw);
+      } catch {
+        parsed = void 0;
+      }
+      const fields = parsed && typeof parsed === "object" ? parsed : {};
+      const code = typeof fields.error === "string" ? fields.error : void 0;
+      if (!res.ok) {
+        if (res.status === 403 && code === "insufficient_scope") {
+          const scope = typeof fields.scope === "string" && fields.scope ? fields.scope : init.method === "GET" ? "profile" : "profile:write";
+          throw new SsoInsufficientScopeError(
+            `${url} answered 403 insufficient_scope \u2014 the user's token lacks scope "${scope}"; log in again with it requested.`,
+            scope
+          );
+        }
+        throw new SsoAppApiError(`${url} answered ${res.status}${code ? ` (${code})` : ""} \u2014 ${what} is unknown.`, res.status, code);
+      }
+      if (parsed === void 0) {
+        throw new SsoAppApiError(`${url} answered ${res.status} with a body that is not JSON \u2014 ${what} is unknown.`, res.status, void 0);
+      }
+      return parsed;
+    } catch (e) {
+      if (e instanceof SsoError) throw e;
+      throw new SsoAppApiError(`${url} could not be reached (${e instanceof Error ? e.name : "error"}) \u2014 ${what} is unknown.`, null, void 0);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  function asProfile(body, path) {
+    const b = body ?? {};
+    if (typeof b.sub !== "string" || b.sub === "" || typeof b.account_url !== "string") {
+      throw new SsoAppApiError(`${path} returned no "sub" or "account_url" \u2014 the profile is unknown.`, 200, void 0);
+    }
+    const opt = (v) => typeof v === "string" ? v : null;
+    return { sub: b.sub, name: opt(b.name), picture: opt(b.picture), email: opt(b.email), account_url: b.account_url };
+  }
   let discoveryPromise = null;
   let jwksCache = null;
   async function discovery() {
@@ -510,6 +611,35 @@ function createSsoClient(config, options = {}) {
       return status;
     },
     verifyLogoutToken,
+    async getProfile(accessToken) {
+      const path = "/api/app/profile";
+      return asProfile(await appRequest(path, accessToken, { method: "GET" }, "the profile"), path);
+    },
+    async updateProfile(accessToken, name) {
+      const path = "/api/app/profile";
+      return asProfile(await appRequest(path, accessToken, { method: "POST", json: { name } }, "the new name"), path);
+    },
+    async uploadAvatar(accessToken, bytes, contentType) {
+      const type = mediaType(contentType);
+      if (!AVATAR_TYPES.includes(type)) {
+        throw new SsoAvatarRejectedError(
+          `uploadAvatar: "${type}" is not accepted \u2014 BID takes ${AVATAR_TYPES.join(", ")}.`,
+          "unsupported_type"
+        );
+      }
+      if (bytes.byteLength > MAX_AVATAR_BYTES) {
+        throw new SsoAvatarRejectedError(
+          `uploadAvatar: ${bytes.byteLength} bytes \u2014 BID takes at most ${MAX_AVATAR_BYTES}.`,
+          "too_large"
+        );
+      }
+      const path = "/api/app/profile/avatar";
+      return asProfile(await appRequest(path, accessToken, { method: "POST", bytes, contentType: type }, "the new picture"), path);
+    },
+    async removeAvatar(accessToken) {
+      const path = "/api/app/profile/avatar/remove";
+      return asProfile(await appRequest(path, accessToken, { method: "POST" }, "the removed picture"), path);
+    },
     async inviteUsers(appKey, input) {
       if (input.users.length > MAX_INVITATIONS) {
         throw new SsoError(`inviteUsers: ${input.users.length} users, BID accepts at most ${MAX_INVITATIONS} per call.`);
@@ -880,17 +1010,17 @@ function ssoRoutes(options = {}) {
     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.");
+      throw new SsoReauthError("no live session \u2014 log in again.", "no_session");
     }
     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.");
+    if (!sid) throw new SsoReauthError("this session has no stored tokens (it began before tokenStore was configured) \u2014 log in again.", "no_tokens");
     const tokens = await tokenStore.get(sid);
-    if (!tokens) throw new SsoError("no tokens stored for this session \u2014 log in again.");
+    if (!tokens) throw new SsoReauthError("no tokens stored for this session \u2014 log in again.", "no_tokens");
     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.");
+      throw new SsoReauthError("the access token has expired and there is no refresh token \u2014 log in again.", "expired");
     }
     const inFlight = refreshing.get(sid);
     if (inFlight) return inFlight;
@@ -900,7 +1030,7 @@ function ssoRoutes(options = {}) {
         next = await client.refreshTokens(tokens.refreshToken);
       } catch (e) {
         await tokenStore.delete(sid);
-        throw e instanceof SsoError ? e : new SsoError("token refresh failed");
+        throw new SsoReauthError(e instanceof SsoError ? e.message : "token refresh failed", "refresh_failed");
       }
       await tokenStore.set(sid, {
         sub: tokens.sub,
@@ -937,7 +1067,100 @@ async function parseTransaction(raw, secret) {
 function getSession(c) {
   return c.get(SESSION_KEY) ?? null;
 }
+function errName(e) {
+  return e instanceof Error ? e.name : void 0;
+}
+async function readCapped(c, max) {
+  const stream = c.req.raw.body;
+  if (!stream) return new Uint8Array(0);
+  const reader = stream.getReader();
+  const chunks = [];
+  let size = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > max) {
+      await reader.cancel().catch(() => {
+      });
+      return null;
+    }
+    chunks.push(value);
+  }
+  const out = new Uint8Array(size);
+  let at = 0;
+  for (const ch of chunks) {
+    out.set(ch, at);
+    at += ch.byteLength;
+  }
+  return out;
+}
+function accountRoutes(sso) {
+  const app = new hono.Hono();
+  const { client } = sso;
+  app.use("*", async (c, next) => {
+    c.header("Cache-Control", "no-store");
+    await next();
+  });
+  app.use("*", async (c, next) => {
+    const site = c.req.header("sec-fetch-site");
+    if (c.req.method !== "GET" && site !== void 0 && site !== "same-origin" && site !== "none") {
+      return c.json({ error: "cross_site" }, 403);
+    }
+    await next();
+  });
+  app.get("/profile", async (c) => c.json(await client.getProfile(await sso.getAccessToken(c))));
+  app.post("/profile", async (c) => {
+    const token = await sso.getAccessToken(c);
+    const body = await c.req.json().catch(() => null);
+    if (typeof body?.name !== "string") {
+      return c.json({ error: "invalid_request", error_description: '"name" must be a string' }, 400);
+    }
+    return c.json(await client.updateProfile(token, body.name));
+  });
+  app.post("/profile/avatar", async (c) => {
+    const token = await sso.getAccessToken(c);
+    const type = mediaType(c.req.header("content-type"));
+    if (!AVATAR_TYPES.includes(type)) {
+      return c.json({ error: "unsupported_type", accepted: AVATAR_TYPES }, 415);
+    }
+    const declared = Number(c.req.header("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_AVATAR_BYTES) {
+      return c.json({ error: "too_large", max_bytes: MAX_AVATAR_BYTES }, 413);
+    }
+    const bytes = await readCapped(c, MAX_AVATAR_BYTES);
+    if (!bytes) return c.json({ error: "too_large", max_bytes: MAX_AVATAR_BYTES }, 413);
+    return c.json(await client.uploadAvatar(token, bytes, type));
+  });
+  app.post("/profile/avatar/remove", async (c) => c.json(await client.removeAvatar(await sso.getAccessToken(c))));
+  app.onError((err, c) => {
+    c.header("Cache-Control", "no-store");
+    const e = err;
+    switch (errName(err)) {
+      case "SsoReauthError":
+        return c.json({ error: e.reason === "no_session" ? "unauthenticated" : "reauth" }, 401);
+      case "SsoInsufficientScopeError":
+        return c.json({ error: "insufficient_scope", scope: e.scope }, 403);
+      case "SsoAvatarRejectedError":
+        return e.reason === "too_large" ? c.json({ error: "too_large", max_bytes: MAX_AVATAR_BYTES }, 413) : c.json({ error: "unsupported_type", accepted: AVATAR_TYPES }, 415);
+      case "SsoAppApiError": {
+        if (e.status === 401) return c.json({ error: "reauth" }, 401);
+        if (typeof e.status === "number" && e.status >= 400 && e.status < 500) {
+          return c.json({ error: e.code ?? "bid_refused" }, e.status);
+        }
+        return c.json({ error: "bid_unavailable" }, 502);
+      }
+      // A plain SsoError here is a setup mistake (e.g. ssoRoutes without tokenStore).
+      case "SsoError":
+        return c.json({ error: "sso_misconfigured" }, 500);
+      default:
+        return c.json({ error: "server_error" }, 500);
+    }
+  });
+  return app;
+}
 
+exports.accountRoutes = accountRoutes;
 exports.getSession = getSession;
 exports.ssoRoutes = ssoRoutes;
 //# sourceMappingURL=hono.cjs.map