@hyper.authio/bff 0.7.0 → 0.8.1

package/README.md

@@ -25,12 +25,16 @@ and refresh tokens outlive the page. With a BFF:
 
 ## Register the client at Authio
 
-- **Type**: confidential, with a secret (`client_secret_basic` by default, or `clientAuthentication:
+- **Type**: confidential, with a secret (`client_secret_basic` by default, or `tokenEndpointAuthMethod:
   "client_secret_post"`), or with `private_key_jwt` (`clientPrivateKey` or `clientPrivateKeyPath`, and
   `clientKeyId`).
+- **PKCE**: required with S256 is the recommended setting, mirrored by `checks: ["pkce", "state", "nonce"]` and
+  `codeChallengeMethod: "S256"`. The BFF checks only what `checks` lists: left out, it checks nothing.
 - **Redirect URI**: `https://<your-app>/signin-oidc` (`callbackPath`).
 - **Post-logout redirect URI**: `https://<your-app>/signout-callback-oidc` (`signedOutCallbackPath`).
 - **Back-channel logout URI**: `https://<your-app>/bff/backchannel-logout`.
+- **Front-channel logout URI** (optional, with `frontChannelLogout: true`): `https://<your-app>/bff/frontchannel-logout`,
+  with the session required so Authio sends `iss` and `sid`.
 - **Scopes**: `openid profile email offline_access` (`offline_access` gives the refresh token), plus `roles` if you set
   `requestRoles`, plus your API scopes.
 - **Resources** (optional): the API resource identifiers you ask for with `resource` or use with remote APIs; allow
@@ -49,12 +53,14 @@ const bff = authioBff({
   realm: "acme",
   clientId: "acme-web",
   clientSecret: () => process.env.AUTHIO_CLIENT_SECRET!, // read on every call: a rotated secret needs no restart
+  checks: ["pkce", "state", "nonce"], // the client requires PKCE with S256: mirror it, nothing is checked by default
+  codeChallengeMethod: "S256",
   cookieSecret: process.env.BFF_COOKIE_SECRET!, // 32+ characters; an array rotates them
   requestRoles: true,
   resource: "https://orders.example.com", // the session's token is addressed to the orders API
 });
 
-app.use(bff); // /bff/login, /bff/logout, /bff/user, /bff/silent-login, /bff/backchannel-logout, /signin-oidc, /signout-callback-oidc
+app.use(bff); // /bff/login, /bff/logout, /bff/user, /bff/silent-login, /bff/backchannel-logout, /bff/frontchannel-logout, /signin-oidc, /signout-callback-oidc
 
 // Remote APIs: mount them before any body parser, so the body is streamed through.
 app.use("/api/orders", bff.remoteApi("https://orders.example.com"));
@@ -99,11 +105,12 @@ if (response.status === 401) {
 | Endpoint | Behaviour |
 | --- | --- |
 | `GET /bff/login` | Starts the sign-in. `returnUrl` (local only, else `400`), `organization`, `prompt` (`none`, `login`, `select_account`, `consent`), `login_hint`, `ui_locales`, `max_age`, `resource` (must be `resource` or one of `allowedResources`, else `400 invalid_target`). A failure comes back as `returnUrl?error=<code>` (`access_denied`, `login_required`, `login_failed`…). |
-| `GET /signin-oidc` | The callback: checks `state` against the sealed sign-in cookie, the RFC 9207 `iss`, redeems the code with the PKCE verifier, validates the ID token (nonce, `at_hash`), creates the session and replaces any previous one. |
+| `GET /signin-oidc` | The callback: finds the sealed sign-in cookie (by `state` with the `state` check), checks the RFC 9207 `iss` and the configured `checks`, redeems the code (with the PKCE verifier with `pkce`), validates the ID token (`nonce` with `nonce`, `at_hash`), reads the access token's claims once its signature verifies, creates the session and replaces any previous one. |
 | `GET /bff/user` | With `X-CSRF: 1`: `[{ "type", "value" }]` — the session's claims (strings, one entry per array element), one `role` per Authio role and one `permission` (`resource:method`) per grant from the `*_resource_access` claims, `bff:session_expires_in` (seconds) and `bff:logout_url`. `401` without the header (`antiforgery_required`) or without a session (`unauthorized`), never a redirect. |
 | `GET\|POST /bff/logout` | With the session's `sid` (from `bff:logout_url`) or `X-CSRF: 1`, optionally `returnUrl`: revokes the refresh token, deletes the session, clears the cookie and redirects to Authio's end-session endpoint with `id_token_hint`, `post_logout_redirect_uri` and a sealed `state`; `/signout-callback-oidc` then sends the browser to `returnUrl`. Without `sid` or the header, a signed-in person cannot be logged out by another site (`400`). |
 | `GET /bff/silent-login` | A `prompt=none` sign-in for a hidden iframe; `/bff/silent-login-callback` posts `{ source: "authio-bff-silent-login", isLoggedIn, error }` to the parent window (same origin only). |
 | `POST /bff/backchannel-logout` | Authio's back-channel logout: validates the `logout_token` (`validateLogoutToken`) and deletes every session of that Authio session (`sid`), or of the person (`sub`) when the token names no `sid`. `400 invalid_request` for a missing or invalid token. |
+| `GET /bff/frontchannel-logout` | With `frontChannelLogout: true`, Authio's front-channel logout iframe: checks `iss` (`validateFrontChannelLogout`) and deletes every session of the `sid` it names, or the browser's own session when it names none; answers an empty page. `400 invalid_request` for another issuer or a `sid` without `iss`; `404` when turned off. |
 
 ## Calling APIs
 
@@ -142,7 +149,11 @@ refresh token, which stays addressed to the BFF.
 - **Refresh**: the access token is refreshed `tokenRefreshSkew` (60 s) before it expires, under a lock per session, so
   concurrent requests share one refresh (Authio rotates refresh tokens and treats a late reuse as a replay). The rotated
   refresh token is stored before the lock is released. A refused refresh (`invalid_grant`) ends the session; a network
-  error keeps the current token while it lasts.
+  error keeps the current token while it lasts. An ID token the refresh returns is validated (signature, `iss`, `aud`,
+  `exp`, `at_hash`, the same `sub`) before it is stored; one that does not validate ends the session.
+- **Claims**: the session's claims are the validated ID token's, plus the claims only the access token carries
+  (`*_resource_access`, `org_id`, `org_alias`, `account_id`) once the access token's signature, `iss` and `exp` verify
+  (`client.readAccessTokenClaims`), plus UserInfo's with `getClaimsFromUserInfoEndpoint`.
 - **Session check** (`sessionValidation: "introspection"`, the default): every `sessionValidationInterval` (300 s) the
   refresh token (or the access token when there is none) is introspected; an inactive answer ends the session. Needs a
   confidential client.
@@ -194,16 +205,31 @@ sessions) or rely on Authio's short refresh-token reuse leeway.
 ## Options
 
 The client takes the names of [`conformance/options.md`](../../conformance/options.md) (`issuer` or `authority` +
-`realm`, `clientId`, `clientSecret`, `clientAuthentication`, `clientPrivateKey`, `clientKeyId`,
-`clientEncryptionKey`, `tokenRefreshSkew`, `requireHttps`, `clock`…), or an existing `client`. The BFF's own options
-are those of `Authio.AspNetCore.Bff` (`Authio:Bff`), in camelCase, with durations in seconds:
+`realm`, `clientId`, `clientSecret`, `tokenEndpointAuthMethod`, `clientPrivateKey`, `clientKeyId`,
+`clientEncryptionKey`, `encryptionAlgorithms`, `encryptionMethods`, `idTokenSignedResponseAlg`, `tokenRefreshSkew`,
+`requireHttps`, `clock`…), or an existing `client`. They mirror the client as it is registered in Authio, and an
+option left out is off:
+
+| In the console | Options |
+| --- | --- |
+| PKCE required, S256 | `checks: ["pkce", "state", "nonce"]`, `codeChallengeMethod: "S256"` |
+| PKCE required, plain only | `checks: ["pkce", "state", "nonce"]`, `codeChallengeMethod: "plain"` |
+| PKCE off | `checks: ["state", "nonce"]` |
+| `client_secret_post` | `clientSecret`, `tokenEndpointAuthMethod: "client_secret_post"` |
+| ID token signing algorithm HS256 | `clientSecret`, `idTokenSignedResponseAlg: "HS256"` |
+| Access token signing algorithm HS256 | `clientSecret`, `accessTokenSignedResponseAlg: "HS256"` |
+| Front-channel logout URI with the session required | `frontChannelLogout: true` |
+
+`checks`, `codeChallengeMethod` and `responseMode` (only `query`: the BFF reads the callback itself) are read even with
+an existing `client`. The BFF's own options are those of `Authio.AspNetCore.Bff` (`Authio:Bff`), in camelCase, with
+durations in seconds:
 
 | Option | Default | |
 | --- | --- | --- |
 | `cookieSecret` | — (required) | 32+ characters; an array rotates: the first protects, every one is accepted. |
 | `store` | in memory | `AuthioBffSessionStore`. |
 | `endpointPrefix` | `/bff` | Where the BFF endpoints are served. |
-| `scopes` | `openid profile email offline_access` | `openid` is always sent. |
+| `scopes` | `openid profile email offline_access` | Sent as configured; `openid` is not added. Without it there is no ID token, and the session is built from the verified access token. |
 | `requestRoles` | `false` | Adds `roles`, so the session carries `*_resource_access`. |
 | `getClaimsFromUserInfoEndpoint` | `false` | Adds UserInfo's claims to the session. |
 | `organization`, `resource`, `prompt`, `uiLocales`, `maxAge` | — | Sent on every sign-in unless the login request names one. |
@@ -220,7 +246,8 @@ are those of `Authio.AspNetCore.Bff` (`Authio:Bff`), in camelCase, with duration
 | `antiForgeryHeaderName`, `antiForgeryHeaderValue` | `X-CSRF`, `1` | |
 | `sessionKeyPrefix` | `authio-bff:` | The prefix of the store keys. |
 | `backChannelLogout` | `true` | Serves `/bff/backchannel-logout`. |
-| `onError` | — | Errors the BFF recovers from (failed revocation, introspection or refresh, refused logout token, failed sign-in). |
+| `frontChannelLogout` | `false` | Serves `/bff/frontchannel-logout`. |
+| `onError` | — | Errors the BFF recovers from (failed revocation, introspection or refresh, refused logout token or ID token, an access token that does not verify, failed sign-in). |
 
 Every invalid option is named at once, in one `AuthioConfigurationError`, when `authioBff()` runs.
 

package/dist/index.cjs

@@ -32,16 +32,11 @@ function toSessionClaims(idToken, fallbackSubject) {
 function mergeUserInfo(claims, userInfo) {
   for (const [type, value] of Object.entries(userInfo)) if (claims[type] === void 0 && value !== void 0 && value !== null) claims[type] = value;
 }
-async function replaceAccessTokenClaims(claims, accessToken, decrypt) {
-  const payload = await readPayload(accessToken, decrypt);
+function replaceAccessTokenClaims(claims, payload) {
   if (!payload) return;
   for (const type of Object.keys(claims)) if (accessTokenClaimTypes.has(type)) delete claims[type];
   for (const [type, value] of Object.entries(payload)) if (accessTokenClaimTypes.has(type) && value !== void 0 && value !== null) claims[type] = value;
 }
-async function readAccessTokenSubject(accessToken, decrypt) {
-  const subject = (await readPayload(accessToken, decrypt))?.sub;
-  return typeof subject === "string" && subject ? subject : void 0;
-}
 function toAuthioBffClaims(claims, sessionExpiresIn, logoutUrl) {
   const entries = [];
   const seen = /* @__PURE__ */ new Set();
@@ -62,18 +57,6 @@ function toAuthioBffClaims(claims, sessionExpiresIn, logoutUrl) {
   entries.push({ type: AuthioBffClaimTypes.LogoutUrl, value: logoutUrl });
   return entries;
 }
-async function readPayload(token, decrypt) {
-  if (!token) return void 0;
-  try {
-    const signed = client.isAuthioTokenEncrypted(token) ? await decrypt(token) : token;
-    const parts = signed.split(".");
-    if (parts.length !== 3 || !parts[1]) return void 0;
-    const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
-    return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : void 0;
-  } catch {
-    return void 0;
-  }
-}
 function toText(value) {
   return typeof value === "string" ? value : typeof value === "object" ? JSON.stringify(value) : String(value);
 }
@@ -202,7 +185,7 @@ function resolveBffSettings(options) {
   const settings = {
     cookieSecrets,
     endpointPrefix: `/${(options.endpointPrefix ?? AuthioBffDefaults.EndpointPrefix).replace(/^\/+|\/+$/g, "")}`,
-    scopes: withOpenId([...options.scopes ?? AuthioBffDefaults.Scopes, ...options.requestRoles ? ["roles"] : []]),
+    scopes: distinct([...options.scopes ?? AuthioBffDefaults.Scopes, ...options.requestRoles ? ["roles"] : []]),
     getClaimsFromUserInfoEndpoint: options.getClaimsFromUserInfoEndpoint ?? false,
     organization: nonEmpty(options.organization),
     resource: nonEmpty(options.resource),
@@ -226,6 +209,7 @@ function resolveBffSettings(options) {
     antiForgeryHeaderValue: options.antiForgeryHeaderValue ?? AuthioBffDefaults.AntiForgeryHeaderValue,
     sessionKeyPrefix: options.sessionKeyPrefix ?? AuthioBffDefaults.SessionKeyPrefix,
     backChannelLogout: options.backChannelLogout ?? true,
+    frontChannelLogout: options.frontChannelLogout ?? false,
     tokenRefreshSkewMs: (options.tokenRefreshSkew ?? 60) * 1e3,
     redirectUri: nonEmpty(options.redirectUri),
     postLogoutRedirectUri: nonEmpty(options.postLogoutRedirectUri),
@@ -254,6 +238,8 @@ function resolveBffSettings(options) {
   if (settings.maxAge !== void 0 && (!Number.isInteger(settings.maxAge) || settings.maxAge < 0))
     problems.push("maxAge must be a non-negative whole number of seconds.");
   if (!settings.sessionKeyPrefix.trim()) problems.push("sessionKeyPrefix is required.");
+  if (options.responseMode !== void 0 && options.responseMode !== "query")
+    problems.push("responseMode must be query: the BFF reads Authio's answer at callbackPath (web_message needs a page of the SPA's own).");
   if (!Number.isFinite(settings.tokenRefreshSkewMs) || settings.tokenRefreshSkewMs < 0) problems.push("tokenRefreshSkew must be a non-negative number of seconds.");
   if (problems.length > 0) throw new client.AuthioConfigurationError(`The Authio BFF options are not valid:
 - ${problems.join("\n- ")}`);
@@ -263,9 +249,8 @@ function isLocalUrl(url) {
   if (typeof url !== "string" || !url || /[\u0000-\u001f\u007f-\u009f]/.test(url)) return false;
   return url[0] === "/" && (url.length === 1 || url[1] !== "/" && url[1] !== "\\");
 }
-function withOpenId(scopes) {
-  const distinct = [...new Set(scopes.map((scope) => scope.trim()).filter(Boolean))];
-  return Object.freeze(distinct.includes("openid") ? distinct : ["openid", ...distinct]);
+function distinct(scopes) {
+  return Object.freeze([...new Set(scopes.map((scope) => scope.trim()).filter(Boolean))]);
 }
 function nonEmpty(value) {
   return value?.trim() ? value : void 0;
@@ -534,12 +519,9 @@ function authioBff(options) {
   const protector = createAuthioBffProtector(settings.cookieSecrets);
   const locks = new AuthioBffSessionLocks();
   const exchanges = /* @__PURE__ */ new Map();
-  const decrypt = client.createAuthioTokenDecrypter(
-    options.clientEncryptionKey ?? (options.clientEncryptionKeyPath ? client.encryptionKeyFromFile(options.clientEncryptionKeyPath) : void 0)
-  );
   const prefix = settings.endpointPrefix;
   const loginLifetimeMs = AuthioBffDefaults.LoginLifetime * 1e3;
-  const loginCookieName = (state) => `${settings.cookieName}.login.${crypto.createHash("sha256").update(state).digest("base64url").slice(0, 16)}`;
+  const loginCookieName = (state) => state ? `${settings.cookieName}.login.${crypto.createHash("sha256").update(state).digest("base64url").slice(0, 16)}` : `${settings.cookieName}.login`;
   const toInfo = (session) => Object.freeze({
     subject: textOf(session.data.claims.sub),
     sessionId: textOf(session.data.claims.sid),
@@ -583,6 +565,26 @@ function authioBff(options) {
       return;
     }
   };
+  const readAccessToken = async (accessToken) => {
+    if (!accessToken) return void 0;
+    try {
+      return await client$1.readAccessTokenClaims(accessToken);
+    } catch (error) {
+      report(error);
+      return void 0;
+    }
+  };
+  const refusesIdToken = async (idToken, accessToken, subject) => {
+    try {
+      const claims = await client$1.validateIdToken(idToken, { accessToken });
+      if (typeof subject === "string" && claims.sub !== subject)
+        throw new client.AuthioError(`The ID token of the refresh names '${claims.sub}', not the session's person.`);
+      return false;
+    } catch (error) {
+      report(error);
+      return true;
+    }
+  };
   const isActive = async (data) => {
     const token = data.refreshToken ?? data.accessToken;
     if (!token) return void 0;
@@ -643,12 +645,16 @@ function authioBff(options) {
     try {
       const issuedAt = clock.now();
       const answer = await client$1.tokens.refresh({ refreshToken: data.refreshToken });
+      if (answer.id_token && await refusesIdToken(answer.id_token, answer.access_token, data.claims.sub)) {
+        await endSessionByKey(request, response, session.key);
+        return void 0;
+      }
       data.accessToken = answer.access_token;
       data.accessTokenExpiresAt = issuedAt + lifetimeOf(answer.expires_in);
       data.tokenType = answer.token_type ?? data.tokenType;
       if (answer.refresh_token) data.refreshToken = answer.refresh_token;
       if (answer.id_token) data.idToken = answer.id_token;
-      await replaceAccessTokenClaims(data.claims, answer.access_token, decrypt);
+      replaceAccessTokenClaims(data.claims, await readAccessToken(answer.access_token));
       if (!await store.get(session.key)) {
         await endSessionByKey(request, response, session.key);
         return void 0;
@@ -716,6 +722,9 @@ function authioBff(options) {
   const startLogin = async (request, response, parameters) => {
     const { url, transaction } = await client$1.createAuthorizationUrl({
       redirectUri: settings.redirectUri ?? requestBase(request) + settings.callbackPath,
+      checks: options.checks,
+      codeChallengeMethod: options.codeChallengeMethod,
+      responseMode: options.responseMode,
       scopes: settings.scopes,
       resource: parameters.resource ?? settings.resource,
       organization: parameters.organization ?? settings.organization,
@@ -754,22 +763,25 @@ function authioBff(options) {
   const silentLogin = (request, response) => startLogin(request, response, { returnUrl: `${request.baseUrl ?? ""}${prefix}/silent-login-callback`, prompt: "none" });
   const callback = async (request, response) => {
     const query = readQuery(request);
-    const state = query.get("state") ?? "";
-    const cookieName = state ? loginCookieName(state) : void 0;
-    const sealed = cookieName ? readCookies(request).get(cookieName) : void 0;
+    const state = query.get("state") || void 0;
+    const cookies = readCookies(request);
+    const cookieName = [loginCookieName(state), loginCookieName(void 0)].find((name) => cookies.has(name));
+    const sealed = cookieName ? cookies.get(cookieName) : void 0;
     const pending = sealed ? protector.open("login", sealed) : void 0;
     if (cookieName && sealed) setCookie(response, cookieName, "", "lax", 0);
     response.set("Cache-Control", "no-store");
     const fail = (target2, error) => response.redirect(302, withQueryParameter(target2, "error", error));
-    if (!pending || pending.transaction?.state !== state || pending.expiresAt <= clock.now()) return fail(settings.defaultReturnUrl, "login_failed");
+    if (!pending || pending.transaction?.state !== void 0 && pending.transaction.state !== state || pending.expiresAt <= clock.now())
+      return fail(settings.defaultReturnUrl, "login_failed");
     const target = isLocalUrl(pending.returnUrl) ? pending.returnUrl : settings.defaultReturnUrl;
     if (settings.requireIssuerParameter && !query.has("iss") && !query.has("error")) return fail(target, "login_failed");
     let data;
     try {
       const { tokens, idToken } = await client$1.handleAuthorizationCallback(query, pending.transaction);
       const now = clock.now();
-      const claims = toSessionClaims(idToken, await readAccessTokenSubject(tokens.access_token, decrypt));
-      await replaceAccessTokenClaims(claims, tokens.access_token, decrypt);
+      const accessClaims = await readAccessToken(tokens.access_token);
+      const claims = toSessionClaims(idToken, textOf(accessClaims?.sub));
+      replaceAccessTokenClaims(claims, accessClaims);
       if (settings.getClaimsFromUserInfoEndpoint) mergeUserInfo(claims, await client$1.userInfo(tokens.access_token));
       data = {
         publicId: crypto.randomBytes(16).toString("hex"),
@@ -871,6 +883,28 @@ function authioBff(options) {
     else if (logout2.subject) await store.deleteBySubject(logout2.subject);
     response.status(200).end();
   };
+  const frontChannelLogout = async (request, response) => {
+    response.set("Cache-Control", "no-store");
+    if (!settings.frontChannelLogout) return void response.status(404).end();
+    let sessionId;
+    try {
+      sessionId = client$1.validateFrontChannelLogout(readQuery(request)).sessionId;
+    } catch (error) {
+      report(error);
+      if (!(error instanceof client.AuthioError)) throw error;
+      return sendError(response, 400, "invalid_request", "The front-channel logout request is not valid.");
+    }
+    const cookie = readCookies(request).get(settings.cookieName);
+    const id = cookie ? protector.unsign(cookie) : void 0;
+    const key = id ? settings.sessionKeyPrefix + id : void 0;
+    if (sessionId) await store.deleteBySessionId(sessionId);
+    else if (key) {
+      await store.delete(key);
+      dropExchanges(key);
+    }
+    if (key && !await store.get(key)) clearCookie(response);
+    response.status(200).type("text/html; charset=utf-8").send('<!doctype html><html><head><meta charset="utf-8"><title>Authio</title></head><body></body></html>');
+  };
   const routes = /* @__PURE__ */ new Map([
     [settings.callbackPath, { methods: ["GET"], run: callback }],
     [settings.signedOutCallbackPath, { methods: ["GET"], run: signedOutCallback }],
@@ -879,7 +913,8 @@ function authioBff(options) {
     [`${prefix}/user`, { methods: ["GET"], run: user }],
     [`${prefix}/silent-login`, { methods: ["GET"], run: silentLogin }],
     [`${prefix}/silent-login-callback`, { methods: ["GET"], run: silentLoginCallback }],
-    [`${prefix}/backchannel-logout`, { methods: ["POST"], run: backChannelLogout }]
+    [`${prefix}/backchannel-logout`, { methods: ["POST"], run: backChannelLogout }],
+    [`${prefix}/frontchannel-logout`, { methods: ["GET"], run: frontChannelLogout }]
   ]);
   const middleware = (request, response, next) => {
     const route = routes.get(request.path.replace(/(.)\/+$/, "$1"));