@broberg/sso 0.4.0 → 0.6.0

package/README.md

@@ -259,3 +259,67 @@ const answer = await client.addressOwnership(accessToken, "a@example.dk");
 ```
 
 Calls BID's `POST /api/app/address-ownership` with the user's access token. **It throws `SsoError` on anything else** — a non-2xx, a body that is not JSON, a missing or unknown status. Do not catch that into `"unverified"`: an error means *we do not know*, and treating it as "not verified" quietly downgrades a real user.
+
+## Inviting users and tracking the move to BID (since 0.5.0)
+
+Two calls that authenticate with **your app's own key** (`bidk_…`, issued by Broberg ID) — not the client secret, not a user's token.
+
+```ts
+const results = await client.inviteUsers(process.env.BID_APP_KEY!, {
+  customerName: "Sanne Andersen",
+  appUrl: "https://sanneandersen.dk",
+  appName: "CMS",               // optional
+  switchDate: "2026-10-15",     // optional
+  users: [{ email: "sanne@example.dk", name: "Sanne" }],   // max 500 per call
+});
+// [{ email, outcome: "invited" | "already_invited" | "existing" | "invalid"
+//                   | "too_soon" | "too_many_today" | "send_failed", mailId?, problem? }]
+
+const status = await client.migrationStatus(process.env.BID_APP_KEY!, ["sanne@example.dk"]);
+// { users: [{ email, state: "ready" | "invited" | "expired" | "not_invited", expiresAt? }], counts, complete }
+```
+
+**Both throw `SsoError`** on a non-2xx (a refused key says `invalid_app_key`), a body that is not JSON, a missing array, or an outcome/state this client does not know. **Never treat an error as `"ready"`**: switching off a user's old login because BID's answer was unclear is how someone gets locked out.
+
+**Timeout.** `addressOwnership`, `inviteUsers` and `migrationStatus` give up after `timeoutMs` (default 10 000) with `SsoError`, so a hanging BID cannot hang your app: `createSsoClient(config, { timeoutMs: 5_000 })`.
+
+## «Log ud overalt» — receiving it from BID (since 0.6.0)
+
+When a user presses **«Log ud overalt»** in Broberg ID, BID tells every app it has registered for that: an OIDC Back-Channel Logout token to `POST <mount>/backchannel-logout`. The ordinary «Log ud» in BID does **not** reach your app (owner decision D-376ffa), and the package refuses a token carrying `sid` to keep it that way.
+
+```ts
+const sso = ssoRoutes({
+  backchannel: {
+    store,                    // REQUIRED — shared by every instance of the app
+    onStoreError: "reject",   // default: if the store is down, treat the user as logged out
+  },
+});
+app.route("/auth", sso.app);  // → POST /auth/backchannel-logout; give BID that exact URL
+```
+
+**The store is yours, and it must be shared.** Your app runs on more than one machine; a list kept in memory would log the user out on one and not the other. There is no in-memory default — `ssoRoutes` throws at startup without a store. A table in the database you already have is enough:
+
+```ts
+// CREATE TABLE sso_logout (sub TEXT PRIMARY KEY, before INTEGER NOT NULL);
+// CREATE TABLE sso_logout_jti (jti TEXT PRIMARY KEY, until INTEGER NOT NULL);
+const store: BackchannelStore = {
+  async revokeSubBefore(sub, iat) {
+    await db.execute({ sql: `INSERT INTO sso_logout (sub, before) VALUES (?, ?)
+      ON CONFLICT(sub) DO UPDATE SET before = MAX(before, excluded.before)`, args: [sub, iat] });
+  },
+  async revokedBefore(sub) {
+    const r = await db.execute({ sql: "SELECT before FROM sso_logout WHERE sub = ?", args: [sub] });
+    return r.rows[0] ? Number(r.rows[0].before) : null;
+  },
+  async useJti(jti, until) {
+    const r = await db.execute({ sql: "INSERT OR IGNORE INTO sso_logout_jti (jti, until) VALUES (?, ?)", args: [jti, until] });
+    return r.rowsAffected === 1;   // false = a replay: answered 200, no new effect
+  },
+};
+```
+
+What happens: a verified token → `revokeSubBefore(sub, iat)` → from then on `attach`/`require` look up the user and refuse every session minted at or before that moment (sessions from before 0.6.0 carry no timestamp and count as older). A session started after the logout is untouched. Invalid tokens → 400; store down while receiving → 503, so BID can tell the user this app did not log out.
+
+**Nothing arrives until BID has registered your URL** — mounting it early is safe (ship dark). Tell broberg-id the exact URL once it is deployed.
+
+**The cost:** one store lookup per request that goes through `attach`/`require`.

package/dist/hono.cjs

@@ -187,6 +187,18 @@ async function challengeFor(verifier) {
   return b64url(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier)));
 }
 var ADDRESS_OWNERSHIP = /* @__PURE__ */ new Set(["verified", "unverified", "not_on_account"]);
+var INVITATION_OUTCOMES = /* @__PURE__ */ new Set([
+  "invited",
+  "already_invited",
+  "existing",
+  "invalid",
+  "too_soon",
+  "too_many_today",
+  "send_failed"
+]);
+var MIGRATION_STATES = /* @__PURE__ */ new Set(["ready", "invited", "expired", "not_invited"]);
+var BACKCHANNEL_EVENT = "http://schemas.openid.net/event/backchannel-logout";
+var MAX_INVITATIONS = 500;
 function excerptForLog(raw, clientSecret) {
   let text = raw.replace(/\s+/g, " ").trim();
   if (clientSecret) text = text.split(clientSecret).join("[redacted client_secret]");
@@ -221,6 +233,40 @@ var ALLOWED_ALGS = [
 ];
 function createSsoClient(config, options = {}) {
   const fetchImpl = options.fetchImpl ?? fetch;
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  async function appPost(path, bearer, payload, what) {
+    const url = new URL(path, config.issuer).toString();
+    const ctrl = new AbortController();
+    let timer;
+    const timedOut = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        ctrl.abort();
+        reject(new SsoError(`${url} did not answer within ${timeoutMs} ms \u2014 ${what} is unknown.`));
+      }, timeoutMs);
+    });
+    try {
+      const res = await Promise.race([
+        fetchImpl(url, {
+          method: "POST",
+          headers: { authorization: `Bearer ${bearer}`, "content-type": "application/json" },
+          body: JSON.stringify(payload),
+          signal: ctrl.signal
+        }),
+        timedOut
+      ]);
+      if (!res.ok) {
+        const detail = await res.text().catch(() => "");
+        const hint = detail.includes("invalid_app_key") ? " (invalid_app_key: this app's bidk_ key was refused)" : "";
+        throw new SsoError(`${url} answered ${res.status}${hint} \u2014 ${what} is unknown.`);
+      }
+      return await Promise.race([res.json().catch(() => null), timedOut]);
+    } catch (e) {
+      if (e instanceof SsoError) throw e;
+      throw new SsoError(`${url} could not be reached: ${e instanceof Error ? e.message : String(e)} \u2014 ${what} is unknown.`);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   let discoveryPromise = null;
   let jwksCache = null;
   async function discovery() {
@@ -261,6 +307,38 @@ function createSsoClient(config, options = {}) {
     }
     return jwksCache;
   }
+  async function verifyLogoutToken(token) {
+    const cache = await keys();
+    let header;
+    try {
+      header = jose.decodeProtectedHeader(token);
+    } catch {
+      throw new SsoError("logout_token is not a JWS");
+    }
+    if (!header.kid) throw new SsoError("logout_token has no kid \u2014 cannot pick a signing key");
+    let payload;
+    try {
+      ({ payload } = await jose.jwtVerify(token, async () => cache.getKey(header.kid, header.alg ?? "RS256"), {
+        issuer: config.issuer,
+        audience: config.clientId,
+        algorithms: ALLOWED_ALGS,
+        typ: "logout+jwt",
+        requiredClaims: ["iat", "exp", "jti"]
+      }));
+    } catch (e) {
+      throw new SsoError(`logout_token rejected: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const events = payload.events;
+    if (!events || typeof events !== "object" || !(BACKCHANNEL_EVENT in events)) {
+      throw new SsoError("logout_token has no back-channel logout event");
+    }
+    if ("nonce" in payload) throw new SsoError("logout_token carries a nonce \u2014 that is an ID token, not a logout token");
+    if ("sid" in payload) {
+      throw new SsoError("logout_token carries sid \u2014 only sub-wide \xABLog ud overalt\xBB is accepted (D-376ffa)");
+    }
+    if (typeof payload.sub !== "string" || payload.sub === "") throw new SsoError("logout_token has no sub");
+    return { sub: payload.sub, iat: payload.iat, jti: String(payload.jti), exp: payload.exp };
+  }
   async function verifyIdToken(idToken, opts = {}) {
     const cache = await keys();
     const header = jose.decodeProtectedHeader(idToken);
@@ -387,21 +465,45 @@ function createSsoClient(config, options = {}) {
       return `${doc.end_session_endpoint}?${params}`;
     },
     async addressOwnership(accessToken, address) {
-      const url = new URL("/api/app/address-ownership", config.issuer).toString();
-      const res = await fetchImpl(url, {
-        method: "POST",
-        headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
-        body: JSON.stringify({ address })
-      });
-      if (!res.ok) {
-        throw new SsoError(`${url} answered ${res.status} \u2014 address ownership is unknown, not "unverified".`);
-      }
-      const body = await res.json().catch(() => null);
+      const body = await appPost(
+        "/api/app/address-ownership",
+        accessToken,
+        { address },
+        'address ownership (not "unverified")'
+      );
       const status = body?.status;
       if (typeof status !== "string" || !ADDRESS_OWNERSHIP.has(status)) {
-        throw new SsoError(`${url} returned status ${JSON.stringify(status)} \u2014 expected verified, unverified or not_on_account.`);
+        throw new SsoError(`address-ownership returned status ${JSON.stringify(status)} \u2014 expected verified, unverified or not_on_account.`);
       }
       return status;
+    },
+    verifyLogoutToken,
+    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.`);
+      }
+      const body = await appPost("/api/app/invitations", appKey, input, "the invitation outcome");
+      if (!Array.isArray(body?.results)) {
+        throw new SsoError(`invitations returned no "results" array \u2014 the invitation outcome is unknown.`);
+      }
+      for (const r of body.results) {
+        if (typeof r?.outcome !== "string" || !INVITATION_OUTCOMES.has(r.outcome)) {
+          throw new SsoError(`invitations returned outcome ${JSON.stringify(r?.outcome)} for ${String(r?.email)} \u2014 not one this client knows.`);
+        }
+      }
+      return body.results;
+    },
+    async migrationStatus(appKey, emails) {
+      const body = await appPost("/api/app/migration-status", appKey, { emails }, "the migration state");
+      if (!Array.isArray(body?.users) || typeof body.complete !== "boolean") {
+        throw new SsoError(`migration-status returned no "users" array or no "complete" flag \u2014 the migration state is unknown.`);
+      }
+      for (const u of body.users) {
+        if (typeof u?.state !== "string" || !MIGRATION_STATES.has(u.state)) {
+          throw new SsoError(`migration-status returned state ${JSON.stringify(u?.state)} for ${String(u?.email)} \u2014 never read as "ready".`);
+        }
+      }
+      return body;
     }
   };
 }
@@ -531,7 +633,51 @@ function ssoRoutes(options = {}) {
   const defaultReturnTo = options.defaultReturnTo ?? "/";
   const txCookie = `${config.cookieName}_tx`;
   const idTokenCookie = `${config.cookieName}_idt`;
+  const backchannel = options.backchannel;
+  if (backchannel && !backchannel.store) {
+    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";
+  async function liveSession(c) {
+    const session = await verifySession(readCookie(c.req.header("cookie"), config.cookieName), config.cookieSecret);
+    if (!session || !backchannel) return session;
+    try {
+      const before = await backchannel.store.revokedBefore(session.sub);
+      if (before !== null && (session.iat ?? 0) <= before) return null;
+      return session;
+    } catch {
+      return onStoreError === "allow" ? session : null;
+    }
+  }
   const app = new hono.Hono();
+  if (backchannel) {
+    app.post("/backchannel-logout", async (c) => {
+      c.header("Cache-Control", "no-store");
+      let token;
+      try {
+        const form = await c.req.parseBody();
+        token = typeof form.logout_token === "string" ? form.logout_token : void 0;
+      } catch {
+        token = void 0;
+      }
+      if (!token) return c.json({ error: "invalid_request", error_description: "logout_token is missing" }, 400);
+      let verified;
+      try {
+        verified = await client.verifyLogoutToken(token);
+      } catch (e) {
+        const msg = e instanceof SsoError ? e.message : "logout_token could not be verified";
+        return c.json({ error: "invalid_request", error_description: msg }, 400);
+      }
+      try {
+        if (await backchannel.store.useJti(verified.jti, verified.exp)) {
+          await backchannel.store.revokeSubBefore(verified.sub, verified.iat);
+        }
+      } catch {
+        return c.json({ error: "store_unavailable" }, 503);
+      }
+      return c.body(null, 200);
+    });
+  }
   app.get("/login", async (c) => {
     const prompt = c.req.query("prompt");
     const start = await client.beginLogin(
@@ -592,6 +738,7 @@ function ssoRoutes(options = {}) {
     const session = {
       sub: result.claims.sub,
       exp,
+      iat: Math.floor(Date.now() / 1e3),
       ...result.claims.email ? { email: result.claims.email } : {},
       ...result.claims.name ? { name: result.claims.name } : {},
       ...result.claims.picture ? { picture: result.claims.picture } : {}
@@ -635,13 +782,11 @@ function ssoRoutes(options = {}) {
     return c.redirect(await client.logoutUrl(idTokenHint ? { idTokenHint } : {}), 302);
   });
   const attach = async (c, next) => {
-    const cookie = readCookie(c.req.header("cookie"), config.cookieName);
-    c.set(SESSION_KEY, await verifySession(cookie, config.cookieSecret));
+    c.set(SESSION_KEY, await liveSession(c));
     await next();
   };
   const require2 = async (c, next) => {
-    const cookie = readCookie(c.req.header("cookie"), config.cookieName);
-    const session = await verifySession(cookie, config.cookieSecret);
+    const session = await liveSession(c);
     if (!session) {
       const url = new URL(c.req.url);
       return c.redirect(