@broberg/sso 0.4.0 → 0.6.0

package/dist/hono.d.ts

@@ -204,10 +204,60 @@ interface SsoClient {
      * answers — see the implementation for why that must never become "unverified".
      */
     addressOwnership(accessToken: string, address: string): Promise<AddressOwnership>;
+    /**
+     * 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.
+     */
+    inviteUsers(appKey: string, input: InviteUsersInput): Promise<InvitationResult[]>;
+    /**
+     * Where each user is in the move to BID. Throws SsoError on any state it does
+     * not know — never a silent "ready", which would switch off a user's old login
+     * 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;
 }
 type AddressOwnership = "verified" | "unverified" | "not_on_account";
+type InvitationOutcome = "invited" | "already_invited" | "existing" | "invalid" | "too_soon" | "too_many_today" | "send_failed";
+interface InviteUsersInput {
+    customerName: string;
+    appUrl: string;
+    appName?: string;
+    switchDate?: string;
+    users: Array<{
+        email: string;
+        name: string;
+    }>;
+}
+interface InvitationResult {
+    email: string;
+    outcome: InvitationOutcome;
+    mailId?: string;
+    problem?: string;
+}
+type MigrationState = "ready" | "invited" | "expired" | "not_invited";
+interface MigrationStatus {
+    users: Array<{
+        email: string;
+        state: MigrationState;
+        expiresAt?: string;
+    }>;
+    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.
@@ -228,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;
@@ -237,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. */
@@ -257,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

@@ -185,6 +185,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]");
@@ -219,6 +231,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() {
@@ -259,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);
@@ -385,21 +463,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;
     }
   };
 }
@@ -529,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(
@@ -590,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 } : {}
@@ -633,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(