@hyper.authio/bff 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -99,13 +99,16 @@ type AuthioBffSessionValidation = "none" | "introspection";
 type AuthioBffCookieSameSite = "lax" | "strict";
 /**
  * Settings of the Authio BFF. The client itself (`issuer` or `authority` + `realm`, `clientId`, `clientSecret`,
- * `clientAuthentication`, `clientPrivateKey`, `clientEncryptionKey`, `tokenRefreshSkew`…) takes the names of
- * `conformance/options.md`; the BFF's own settings are those of `Authio.AspNetCore.Bff` (`Authio:Bff`).
+ * `tokenEndpointAuthMethod`, `clientPrivateKey`, `clientEncryptionKey`, `checks`, `codeChallengeMethod`,
+ * `idTokenSignedResponseAlg`, `tokenRefreshSkew`…) takes the names of `conformance/options.md` and mirrors the client
+ * as registered in Authio: an option left out is off. The BFF's own settings are those of `Authio.AspNetCore.Bff`
+ * (`Authio:Bff`).
  */
 interface AuthioBffOptions extends Partial<AuthioClientOptions> {
     /**
      * An Authio client to use instead of creating one from the connection and credential options above. The BFF still
-     * reads `tokenRefreshSkew`, `clientEncryptionKey`, `redirectUri` and `postLogoutRedirectUri` from these options.
+     * reads `tokenRefreshSkew`, `checks`, `codeChallengeMethod`, `responseMode`, `redirectUri` and
+     * `postLogoutRedirectUri` from these options; tokens are validated and decrypted by the client.
      */
     client?: AuthioClient;
     /**
@@ -118,7 +121,10 @@ interface AuthioBffOptions extends Partial<AuthioClientOptions> {
     store?: AuthioBffSessionStore;
     /** The route prefix of the BFF endpoints. Defaults to `/bff`. */
     endpointPrefix?: string;
-    /** The scopes asked for at sign-in. Defaults to `openid profile email offline_access`; `openid` is always sent. */
+    /**
+     * The scopes asked for at sign-in, sent as configured: without `openid` there is no ID token, and the session is
+     * built from the access token (and UserInfo). Defaults to `openid profile email offline_access`.
+     */
     scopes?: readonly string[];
     /** Adds the `roles` scope, so the session carries the `*_resource_access` claims flattened on `/bff/user`. */
     requestRoles?: boolean;
@@ -174,6 +180,12 @@ interface AuthioBffOptions extends Partial<AuthioClientOptions> {
      * (`sub`) a logout token names. Defaults to `true`; register that URL as the client's back-channel logout URI.
      */
     backChannelLogout?: boolean;
+    /**
+     * Serves `GET {endpointPrefix}/frontchannel-logout`, which Authio loads in an iframe when a session ends: it ends the
+     * sessions of the `sid` it names (with `iss` checked), or the browser's own session when it names none. Defaults to
+     * `false`; register that URL as the client's front-channel logout URI, with the session required.
+     */
+    frontChannelLogout?: boolean;
     /** Called with errors the BFF recovers from: a failed revocation, introspection or refresh, a refused logout token. */
     onError?: (error: unknown) => void;
 }
@@ -289,8 +301,9 @@ interface AuthioBff extends RequestHandler {
 }
 /**
  * Creates the Authio BFF. Mount it with `app.use(bff)`: it serves `{endpointPrefix}/login`, `/logout`, `/user`,
- * `/silent-login`, `/silent-login-callback`, `/backchannel-logout`, the sign-in callback (`callbackPath`) and the
- * sign-out callback (`signedOutCallbackPath`), and reads the session of every other request that carries the cookie.
+ * `/silent-login`, `/silent-login-callback`, `/backchannel-logout`, `/frontchannel-logout` (when turned on), the sign-in
+ * callback (`callbackPath`) and the sign-out callback (`signedOutCallbackPath`), and reads the session of every other
+ * request that carries the cookie.
  *
  * @throws AuthioConfigurationError naming every invalid option.
  */

package/dist/index.d.ts

@@ -99,13 +99,16 @@ type AuthioBffSessionValidation = "none" | "introspection";
 type AuthioBffCookieSameSite = "lax" | "strict";
 /**
  * Settings of the Authio BFF. The client itself (`issuer` or `authority` + `realm`, `clientId`, `clientSecret`,
- * `clientAuthentication`, `clientPrivateKey`, `clientEncryptionKey`, `tokenRefreshSkew`…) takes the names of
- * `conformance/options.md`; the BFF's own settings are those of `Authio.AspNetCore.Bff` (`Authio:Bff`).
+ * `tokenEndpointAuthMethod`, `clientPrivateKey`, `clientEncryptionKey`, `checks`, `codeChallengeMethod`,
+ * `idTokenSignedResponseAlg`, `tokenRefreshSkew`…) takes the names of `conformance/options.md` and mirrors the client
+ * as registered in Authio: an option left out is off. The BFF's own settings are those of `Authio.AspNetCore.Bff`
+ * (`Authio:Bff`).
  */
 interface AuthioBffOptions extends Partial<AuthioClientOptions> {
     /**
      * An Authio client to use instead of creating one from the connection and credential options above. The BFF still
-     * reads `tokenRefreshSkew`, `clientEncryptionKey`, `redirectUri` and `postLogoutRedirectUri` from these options.
+     * reads `tokenRefreshSkew`, `checks`, `codeChallengeMethod`, `responseMode`, `redirectUri` and
+     * `postLogoutRedirectUri` from these options; tokens are validated and decrypted by the client.
      */
     client?: AuthioClient;
     /**
@@ -118,7 +121,10 @@ interface AuthioBffOptions extends Partial<AuthioClientOptions> {
     store?: AuthioBffSessionStore;
     /** The route prefix of the BFF endpoints. Defaults to `/bff`. */
     endpointPrefix?: string;
-    /** The scopes asked for at sign-in. Defaults to `openid profile email offline_access`; `openid` is always sent. */
+    /**
+     * The scopes asked for at sign-in, sent as configured: without `openid` there is no ID token, and the session is
+     * built from the access token (and UserInfo). Defaults to `openid profile email offline_access`.
+     */
     scopes?: readonly string[];
     /** Adds the `roles` scope, so the session carries the `*_resource_access` claims flattened on `/bff/user`. */
     requestRoles?: boolean;
@@ -174,6 +180,12 @@ interface AuthioBffOptions extends Partial<AuthioClientOptions> {
      * (`sub`) a logout token names. Defaults to `true`; register that URL as the client's back-channel logout URI.
      */
     backChannelLogout?: boolean;
+    /**
+     * Serves `GET {endpointPrefix}/frontchannel-logout`, which Authio loads in an iframe when a session ends: it ends the
+     * sessions of the `sid` it names (with `iss` checked), or the browser's own session when it names none. Defaults to
+     * `false`; register that URL as the client's front-channel logout URI, with the session required.
+     */
+    frontChannelLogout?: boolean;
     /** Called with errors the BFF recovers from: a failed revocation, introspection or refresh, a refused logout token. */
     onError?: (error: unknown) => void;
 }
@@ -289,8 +301,9 @@ interface AuthioBff extends RequestHandler {
 }
 /**
  * Creates the Authio BFF. Mount it with `app.use(bff)`: it serves `{endpointPrefix}/login`, `/logout`, `/user`,
- * `/silent-login`, `/silent-login-callback`, `/backchannel-logout`, the sign-in callback (`callbackPath`) and the
- * sign-out callback (`signedOutCallbackPath`), and reads the session of every other request that carries the cookie.
+ * `/silent-login`, `/silent-login-callback`, `/backchannel-logout`, `/frontchannel-logout` (when turned on), the sign-in
+ * callback (`callbackPath`) and the sign-out callback (`signedOutCallbackPath`), and reads the session of every other
+ * request that carries the cookie.
  *
  * @throws AuthioConfigurationError naming every invalid option.
  */

package/dist/index.js

@@ -1,5 +1,5 @@
 import { randomBytes, createDecipheriv, createCipheriv, timingSafeEqual, createHash, hkdfSync, createHmac } from 'crypto';
-import { AuthioClaimTypes, AuthioResourceAccessClaims, systemClock, createAuthioClient, createAuthioTokenDecrypter, encryptionKeyFromFile, AuthioPrompts, AuthioProtocolError, AuthioTokenTypes, AuthioError, AuthioConfigurationError, AuthioDefaults, resourceAccessSourceOf, parseResourceAccess, AuthioOAuthErrors, isAuthioTokenEncrypted } from '@hyper.authio/client';
+import { AuthioClaimTypes, AuthioResourceAccessClaims, systemClock, createAuthioClient, AuthioPrompts, AuthioProtocolError, AuthioTokenTypes, AuthioError, AuthioConfigurationError, AuthioDefaults, resourceAccessSourceOf, parseResourceAccess, AuthioOAuthErrors } from '@hyper.authio/client';
 import { Readable } from 'stream';
 import { pipeline } from 'stream/promises';
 
@@ -30,16 +30,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();
@@ -60,18 +55,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 = 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);
 }
@@ -200,7 +183,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),
@@ -224,6 +207,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),
@@ -252,6 +236,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 AuthioConfigurationError(`The Authio BFF options are not valid:
 - ${problems.join("\n- ")}`);
@@ -261,9 +247,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;
@@ -532,12 +517,9 @@ function authioBff(options) {
   const protector = createAuthioBffProtector(settings.cookieSecrets);
   const locks = new AuthioBffSessionLocks();
   const exchanges = /* @__PURE__ */ new Map();
-  const decrypt = createAuthioTokenDecrypter(
-    options.clientEncryptionKey ?? (options.clientEncryptionKeyPath ? encryptionKeyFromFile(options.clientEncryptionKeyPath) : void 0)
-  );
   const prefix = settings.endpointPrefix;
   const loginLifetimeMs = AuthioBffDefaults.LoginLifetime * 1e3;
-  const loginCookieName = (state) => `${settings.cookieName}.login.${createHash("sha256").update(state).digest("base64url").slice(0, 16)}`;
+  const loginCookieName = (state) => state ? `${settings.cookieName}.login.${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),
@@ -581,6 +563,26 @@ function authioBff(options) {
       return;
     }
   };
+  const readAccessToken = async (accessToken) => {
+    if (!accessToken) return void 0;
+    try {
+      return await client.readAccessTokenClaims(accessToken);
+    } catch (error) {
+      report(error);
+      return void 0;
+    }
+  };
+  const refusesIdToken = async (idToken, accessToken, subject) => {
+    try {
+      const claims = await client.validateIdToken(idToken, { accessToken });
+      if (typeof subject === "string" && claims.sub !== subject)
+        throw new 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;
@@ -641,12 +643,16 @@ function authioBff(options) {
     try {
       const issuedAt = clock.now();
       const answer = await client.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;
@@ -714,6 +720,9 @@ function authioBff(options) {
   const startLogin = async (request, response, parameters) => {
     const { url, transaction } = await client.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,
@@ -752,22 +761,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.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.userInfo(tokens.access_token));
       data = {
         publicId: randomBytes(16).toString("hex"),
@@ -869,6 +881,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.validateFrontChannelLogout(readQuery(request)).sessionId;
+    } catch (error) {
+      report(error);
+      if (!(error instanceof 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 }],
@@ -877,7 +911,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"));