@broberg/sso 0.5.0 → 0.6.0

package/dist/hono.d.ts

@@ -215,6 +215,11 @@ interface SsoClient {
      * while they cannot get in.
      */
     migrationStatus(appKey: string, emails: string[]): Promise<MigrationStatus>;
+    /**
+     * Verify an OIDC Back-Channel Logout token from BID («Log ud overalt»).
+     * Throws SsoError on anything that is not a valid, sub-only logout token.
+     */
+    verifyLogoutToken(token: string): Promise<LogoutToken>;
     /** Exposed for tests and for a health check; not needed in normal use. */
     readonly jwks: JwksCache;
 }
@@ -246,6 +251,13 @@ interface MigrationStatus {
     counts: Record<string, number>;
     complete: boolean;
 }
+/** A verified back-channel logout: every session for `sub` issued at or before `iat` is over. */
+interface LogoutToken {
+    sub: string;
+    iat: number;
+    jti: string;
+    exp: number;
+}
 
 /**
  * The app's OWN session cookie — signed, not encrypted.
@@ -266,6 +278,12 @@ interface SessionPayload {
     sub: string;
     /** Unix seconds. Checked on every read. */
     exp: number;
+    /**
+     * Unix seconds, when this session was minted. What «Log ud overalt» compares
+     * against (F084.151). Absent on sessions minted before 0.6.0 — those count as
+     * older than any logout.
+     */
+    iat?: number;
     /** Optional convenience copies; never authorisation data. */
     email?: string;
     name?: string;
@@ -275,7 +293,37 @@ interface SessionPayload {
     picture?: string;
 }
 
+/**
+ * Where «Log ud overalt» is remembered (F084.151). The APP provides it, backed by
+ * something every instance shares — apps run on two machines, so a per-process
+ * list would log the user out on one machine and not the other. There is
+ * deliberately no in-memory default.
+ */
+interface BackchannelStore {
+    /** Every session for `sub` minted at or before `iat` is over. Keep the LATEST iat. */
+    revokeSubBefore(sub: string, iat: number): Promise<void>;
+    /** The iat recorded for `sub`, or null. */
+    revokedBefore(sub: string): Promise<number | null>;
+    /** Record a logout token id; true the FIRST time, false for a replay. Keep it until `until` (unix s). */
+    useJti(jti: string, until: number): Promise<boolean>;
+}
+interface BackchannelOptions {
+    store: BackchannelStore;
+    /**
+     * When the store cannot answer: "reject" (default) treats the user as logged
+     * out; "allow" lets the session through unchecked. «reject» is the secure
+     * choice — a user who pressed «Log ud overalt» must not stay in because a
+     * database hiccupped — at the price of everyone being out while it lasts.
+     */
+    onStoreError?: "reject" | "allow";
+}
 interface SsoRoutesOptions {
+    /**
+     * Receive «Log ud overalt» from BID at POST <mount>/backchannel-logout.
+     * Nothing arrives until BID has registered that URL for this app (ship dark),
+     * so mounting it early is safe.
+     */
+    backchannel?: BackchannelOptions;
     config?: SsoConfig;
     client?: SsoClient;
     /** Path prefix these routes are mounted under. Used to build the return URL. */
@@ -295,4 +343,4 @@ type TransactionFailure = "absent" | "expired" | "unreadable";
 /** Read the session a middleware attached. */
 declare function getSession(c: Context): SessionPayload | null;
 
-export { type SsoRoutesOptions, type TransactionFailure, getSession, ssoRoutes };
+export { type BackchannelOptions, type BackchannelStore, type SsoRoutesOptions, type TransactionFailure, getSession, ssoRoutes };

package/dist/hono.js

@@ -195,6 +195,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();
@@ -304,6 +305,38 @@ function createSsoClient(config, options = {}) {
     }
     return jwksCache;
   }
+  async function verifyLogoutToken(token) {
+    const cache = await keys();
+    let header;
+    try {
+      header = 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 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 = decodeProtectedHeader(idToken);
@@ -442,6 +475,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.`);
@@ -597,7 +631,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();
+  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(
@@ -658,6 +736,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 } : {}
@@ -701,13 +780,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(