@hyper.authio/bff 0.8.1 → 0.10.0

package/README.md

@@ -37,6 +37,10 @@ and refresh tokens outlive the page. With a BFF:
   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.
+- **Access token format**: `Jwt` needs nothing; `Lightweight`, whose token leaves the roles and permissions to
+  introspection, is mirrored by `accessTokenClaims: "introspection"`; a `Reference` (an opaque handle) is introspected
+  under either value. The BFF introspects as its own confidential client. The refresh token, of either format, is
+  opaque to the BFF.
 - **Resources** (optional): the API resource identifiers you ask for with `resource` or use with remote APIs; allow
   the **token exchange** grant if a remote API needs a token for a specific resource or a narrower scope set.
 
@@ -152,8 +156,18 @@ refresh token, which stays addressed to the BFF.
   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`.
+  (`*_resource_access`, `org_id`, `org_alias`, `account_id`), plus UserInfo's with `getClaimsFromUserInfoEndpoint`.
+  The access token's are read at sign-in and replaced on every refresh, from where `accessTokenClaims` says: `token`
+  (the default) reads them once the access token's signature, `iss` and `exp` verify (`client.readAccessTokenClaims`);
+  `introspection` asks Authio's introspection about the access token, as the BFF's client, for a `Lightweight` token
+  that does not carry them: there a failed or inactive introspection fails the sign-in (`?error=login_failed`, or the
+  OAuth error), and on a refresh `active: false` ends the session while any other failure keeps the session's
+  previous claims until the next refresh, stores the new tokens and goes to `onError`. Under `token`, an opaque
+  (`Reference`) access token is introspected too: a token requested for a `resource` is active only to that resource
+  server's introspection client, so an inactive answer leaves its claims out, without failing the sign-in or ending
+  the session; a failed introspection (`5xx`, timeout, network) fails the sign-in and, on a refresh, keeps the
+  previous claims. The table of [`conformance/options.md`](../../conformance/options.md#access-token-formats) has
+  every case.
 - **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.
@@ -219,6 +233,7 @@ option left out is off:
 | 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` |
+| Access token format `Lightweight` | `accessTokenClaims: "introspection"` |
 
 `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
@@ -231,6 +246,7 @@ durations in seconds:
 | `endpointPrefix` | `/bff` | Where the BFF endpoints are served. |
 | `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`. |
+| `accessTokenClaims` | `token` | Where the session's roles, permissions and organization come from: `token` (the verified access token; an opaque one is introspected, and contributes nothing when it is not active to the BFF's client) or `introspection` (Authio's introspection of it, for the `Lightweight` access token format; needs a confidential client, and a failed or inactive answer fails the sign-in). |
 | `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. |
 | `allowedResources` | `[]` | What `/bff/login?resource=` may ask for. |

package/dist/index.cjs

@@ -186,6 +186,7 @@ function resolveBffSettings(options) {
     cookieSecrets,
     endpointPrefix: `/${(options.endpointPrefix ?? AuthioBffDefaults.EndpointPrefix).replace(/^\/+|\/+$/g, "")}`,
     scopes: distinct([...options.scopes ?? AuthioBffDefaults.Scopes, ...options.requestRoles ? ["roles"] : []]),
+    accessTokenClaims: options.accessTokenClaims ?? "token",
     getClaimsFromUserInfoEndpoint: options.getClaimsFromUserInfoEndpoint ?? false,
     organization: nonEmpty(options.organization),
     resource: nonEmpty(options.resource),
@@ -223,6 +224,12 @@ function resolveBffSettings(options) {
   else if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(settings.cookieName)) problems.push("cookieName holds characters a cookie name cannot.");
   if (settings.cookieSameSite !== "lax" && settings.cookieSameSite !== "strict") problems.push("cookieSameSite must be lax or strict.");
   if (!isPositive(settings.sessionLifetimeMs)) problems.push("sessionLifetime must be a positive number of seconds.");
+  if (settings.accessTokenClaims !== "token" && settings.accessTokenClaims !== "introspection")
+    problems.push("accessTokenClaims must be token or introspection.");
+  else if (settings.accessTokenClaims === "introspection" && !options.client && isPublicClient(options))
+    problems.push(
+      "accessTokenClaims introspection needs a confidential client: Authio answers introspection only to a client that authenticates, so set clientSecret or clientPrivateKey."
+    );
   if (settings.sessionValidation !== "none" && settings.sessionValidation !== "introspection")
     problems.push("sessionValidation must be none or introspection.");
   else if (settings.sessionValidation === "introspection" && !isPositive(settings.sessionValidationIntervalMs))
@@ -249,6 +256,10 @@ 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 isPublicClient(options) {
+  if (options.tokenEndpointAuthMethod !== void 0) return options.tokenEndpointAuthMethod === "none";
+  return !options.clientSecret && options.clientPrivateKey === void 0 && !options.clientPrivateKeyPath;
+}
 function distinct(scopes) {
   return Object.freeze([...new Set(scopes.map((scope) => scope.trim()).filter(Boolean))]);
 }
@@ -566,7 +577,6 @@ function authioBff(options) {
     }
   };
   const readAccessToken = async (accessToken) => {
-    if (!accessToken) return void 0;
     try {
       return await client$1.readAccessTokenClaims(accessToken);
     } catch (error) {
@@ -574,6 +584,25 @@ function authioBff(options) {
       return void 0;
     }
   };
+  const introspectAccessToken = async (accessToken) => {
+    const { active, ...claims } = await client$1.introspect(accessToken, { tokenTypeHint: client.AuthioTokenTypes.AccessToken });
+    if (active !== true) throw new InactiveAccessTokenError();
+    return claims;
+  };
+  const introspectOpaqueAccessToken = async (accessToken) => {
+    try {
+      return await introspectAccessToken(accessToken);
+    } catch (error) {
+      if (error instanceof InactiveAccessTokenError) return void 0;
+      throw error;
+    }
+  };
+  const accessTokenClaimsOf = async (accessToken) => {
+    if (!accessToken) return void 0;
+    if (settings.accessTokenClaims === "introspection") return introspectAccessToken(accessToken);
+    if (isReferenceToken(accessToken)) return introspectOpaqueAccessToken(accessToken);
+    return readAccessToken(accessToken);
+  };
   const refusesIdToken = async (idToken, accessToken, subject) => {
     try {
       const claims = await client$1.validateIdToken(idToken, { accessToken });
@@ -638,6 +667,15 @@ function authioBff(options) {
     return loading;
   };
   const isFresh = (data, skewMs) => Boolean(data.accessToken) && (data.accessTokenExpiresAt === void 0 || clock.now() < data.accessTokenExpiresAt - skewMs);
+  const refreshedAccessTokenClaims = async (accessToken) => {
+    try {
+      return await accessTokenClaimsOf(accessToken);
+    } catch (error) {
+      if (error instanceof InactiveAccessTokenError) return "inactive";
+      report(error);
+      return void 0;
+    }
+  };
   const refresh = async (request, response, session) => {
     const data = { ...session.data, claims: { ...session.data.claims } };
     const unexpired = isFresh(data, 0) ? data.accessToken : void 0;
@@ -654,11 +692,12 @@ function authioBff(options) {
       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;
-      replaceAccessTokenClaims(data.claims, await readAccessToken(answer.access_token));
-      if (!await store.get(session.key)) {
+      const accessClaims = await refreshedAccessTokenClaims(answer.access_token);
+      if (accessClaims === "inactive" || !await store.get(session.key)) {
         await endSessionByKey(request, response, session.key);
         return void 0;
       }
+      replaceAccessTokenClaims(data.claims, accessClaims);
       expose(request, await write(session.key, data, session.expiresAt));
       return answer.access_token;
     } catch (error) {
@@ -779,7 +818,7 @@ function authioBff(options) {
     try {
       const { tokens, idToken } = await client$1.handleAuthorizationCallback(query, pending.transaction);
       const now = clock.now();
-      const accessClaims = await readAccessToken(tokens.access_token);
+      const accessClaims = await accessTokenClaimsOf(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));
@@ -976,6 +1015,14 @@ function lifetimeOf(expiresIn) {
 function textOf(value) {
   return typeof value === "string" && value ? value : void 0;
 }
+var InactiveAccessTokenError = class extends client.AuthioError {
+  constructor() {
+    super("Authio reports the session's access token as not active, so its claims cannot be read.");
+  }
+};
+function isReferenceToken(token) {
+  return !token.includes(".");
+}
 function fixedTimeEquals(left, right) {
   const a = Buffer.from(left, "utf8");
   const b = Buffer.from(right, "utf8");