@broberg/sso 0.5.0 → 0.6.1

package/README.md

@@ -282,3 +282,44 @@ const status = await client.migrationStatus(process.env.BID_APP_KEY!, ["sanne@ex
 **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

@@ -197,6 +197,7 @@ var INVITATION_OUTCOMES = /* @__PURE__ */ new Set([
   "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();
@@ -306,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);
@@ -444,6 +477,7 @@ function createSsoClient(config, options = {}) {
       }
       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.`);
@@ -599,7 +633,50 @@ 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 {
+        await backchannel.store.revokeSubBefore(verified.sub, verified.iat);
+        await backchannel.store.useJti(verified.jti, verified.exp);
+      } 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(
@@ -660,6 +737,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 } : {}
@@ -703,13 +781,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(