@hyper.authio/bff 0.9.0 → 0.10.1

package/dist/index.d.cts

@@ -93,6 +93,15 @@ declare const AuthioBffDefaults: {
  * refresh token (its access token when there is none) every `sessionValidationInterval`.
  */
 type AuthioBffSessionValidation = "none" | "introspection";
+/**
+ * Where the BFF reads the claims only the access token carries (the `*_resource_access` roles and permissions,
+ * `org_id`, `org_alias`, `account_id`): `token`, from the access token once its signature verifies; or
+ * `introspection`, from Authio's introspection of the access token, asked as the BFF's own client. Mirror the client's
+ * access token format: `introspection` for `Lightweight`, whose token leaves those claims to introspection. Under
+ * `token`, an opaque (`Reference`) access token is introspected too, and contributes nothing when it is not active to
+ * the BFF's client.
+ */
+type AuthioBffAccessTokenClaims = "token" | "introspection";
 /**
  * The `SameSite` mode of the session cookie.
  */
@@ -128,6 +137,17 @@ interface AuthioBffOptions extends Partial<AuthioClientOptions> {
     scopes?: readonly string[];
     /** Adds the `roles` scope, so the session carries the `*_resource_access` claims flattened on `/bff/user`. */
     requestRoles?: boolean;
+    /**
+     * Where the session's roles, permissions and organization come from, read at sign-in and again on every refresh:
+     * `token` (default), the access token once its signature verifies; `introspection`, Authio's introspection of the
+     * access token, asked as the BFF's own confidential client. Use `introspection` when the client's access token
+     * format is `Lightweight`: then a failed or inactive introspection fails the sign-in, and on a refresh an inactive
+     * answer ends the session while any other failure keeps the session's previous claims until the next refresh and
+     * goes to `onError`. Under `token`, an opaque (`Reference`) access token is introspected too: an inactive answer
+     * (a token requested for another resource server's introspection client) leaves its claims out and keeps the session
+     * on a refresh, while a failed introspection fails the sign-in and, on a refresh, keeps the previous claims.
+     */
+    accessTokenClaims?: AuthioBffAccessTokenClaims;
     /** Calls Authio's UserInfo endpoint after sign-in and adds its claims to the session. Defaults to `false`. */
     getClaimsFromUserInfoEndpoint?: boolean;
     /** The `organization` sent on every sign-in unless the login request names one. */
@@ -234,7 +254,10 @@ interface AuthioBffSessionInfo {
     readonly subject: string | undefined;
     /** The Authio session (`sid`). */
     readonly sessionId: string | undefined;
-    /** The session's claims: the ID token's, the access token's `*_resource_access` and organization, UserInfo's. */
+    /**
+     * The session's claims: the ID token's, the access token's `*_resource_access` and organization (read from the
+     * token or its introspection, as `accessTokenClaims` says), UserInfo's.
+     */
     readonly claims: Readonly<Record<string, unknown>>;
     /** When the BFF session expires, in milliseconds since the epoch. */
     readonly expiresAt: number;
@@ -337,4 +360,4 @@ interface AuthioBffError {
     readonly error_description?: string;
 }
 
-export { type AuthioBff, type AuthioBffApiOptions, type AuthioBffClaim, AuthioBffClaimTypes, type AuthioBffCookieSameSite, AuthioBffDefaults, type AuthioBffError, type AuthioBffMemoryStore, type AuthioBffMemoryStoreOptions, type AuthioBffOptions, type AuthioBffRemoteApiOptions, type AuthioBffRemoteApiTokenMode, type AuthioBffSessionInfo, type AuthioBffSessionStore, type AuthioBffSessionValidation, type AuthioBffStoredSession, type AuthioBffUserTokenOptions, authioBff, createAuthioBffMemoryStore, isLocalUrl };
+export { type AuthioBff, type AuthioBffAccessTokenClaims, type AuthioBffApiOptions, type AuthioBffClaim, AuthioBffClaimTypes, type AuthioBffCookieSameSite, AuthioBffDefaults, type AuthioBffError, type AuthioBffMemoryStore, type AuthioBffMemoryStoreOptions, type AuthioBffOptions, type AuthioBffRemoteApiOptions, type AuthioBffRemoteApiTokenMode, type AuthioBffSessionInfo, type AuthioBffSessionStore, type AuthioBffSessionValidation, type AuthioBffStoredSession, type AuthioBffUserTokenOptions, authioBff, createAuthioBffMemoryStore, isLocalUrl };

package/dist/index.d.ts

@@ -93,6 +93,15 @@ declare const AuthioBffDefaults: {
  * refresh token (its access token when there is none) every `sessionValidationInterval`.
  */
 type AuthioBffSessionValidation = "none" | "introspection";
+/**
+ * Where the BFF reads the claims only the access token carries (the `*_resource_access` roles and permissions,
+ * `org_id`, `org_alias`, `account_id`): `token`, from the access token once its signature verifies; or
+ * `introspection`, from Authio's introspection of the access token, asked as the BFF's own client. Mirror the client's
+ * access token format: `introspection` for `Lightweight`, whose token leaves those claims to introspection. Under
+ * `token`, an opaque (`Reference`) access token is introspected too, and contributes nothing when it is not active to
+ * the BFF's client.
+ */
+type AuthioBffAccessTokenClaims = "token" | "introspection";
 /**
  * The `SameSite` mode of the session cookie.
  */
@@ -128,6 +137,17 @@ interface AuthioBffOptions extends Partial<AuthioClientOptions> {
     scopes?: readonly string[];
     /** Adds the `roles` scope, so the session carries the `*_resource_access` claims flattened on `/bff/user`. */
     requestRoles?: boolean;
+    /**
+     * Where the session's roles, permissions and organization come from, read at sign-in and again on every refresh:
+     * `token` (default), the access token once its signature verifies; `introspection`, Authio's introspection of the
+     * access token, asked as the BFF's own confidential client. Use `introspection` when the client's access token
+     * format is `Lightweight`: then a failed or inactive introspection fails the sign-in, and on a refresh an inactive
+     * answer ends the session while any other failure keeps the session's previous claims until the next refresh and
+     * goes to `onError`. Under `token`, an opaque (`Reference`) access token is introspected too: an inactive answer
+     * (a token requested for another resource server's introspection client) leaves its claims out and keeps the session
+     * on a refresh, while a failed introspection fails the sign-in and, on a refresh, keeps the previous claims.
+     */
+    accessTokenClaims?: AuthioBffAccessTokenClaims;
     /** Calls Authio's UserInfo endpoint after sign-in and adds its claims to the session. Defaults to `false`. */
     getClaimsFromUserInfoEndpoint?: boolean;
     /** The `organization` sent on every sign-in unless the login request names one. */
@@ -234,7 +254,10 @@ interface AuthioBffSessionInfo {
     readonly subject: string | undefined;
     /** The Authio session (`sid`). */
     readonly sessionId: string | undefined;
-    /** The session's claims: the ID token's, the access token's `*_resource_access` and organization, UserInfo's. */
+    /**
+     * The session's claims: the ID token's, the access token's `*_resource_access` and organization (read from the
+     * token or its introspection, as `accessTokenClaims` says), UserInfo's.
+     */
     readonly claims: Readonly<Record<string, unknown>>;
     /** When the BFF session expires, in milliseconds since the epoch. */
     readonly expiresAt: number;
@@ -337,4 +360,4 @@ interface AuthioBffError {
     readonly error_description?: string;
 }
 
-export { type AuthioBff, type AuthioBffApiOptions, type AuthioBffClaim, AuthioBffClaimTypes, type AuthioBffCookieSameSite, AuthioBffDefaults, type AuthioBffError, type AuthioBffMemoryStore, type AuthioBffMemoryStoreOptions, type AuthioBffOptions, type AuthioBffRemoteApiOptions, type AuthioBffRemoteApiTokenMode, type AuthioBffSessionInfo, type AuthioBffSessionStore, type AuthioBffSessionValidation, type AuthioBffStoredSession, type AuthioBffUserTokenOptions, authioBff, createAuthioBffMemoryStore, isLocalUrl };
+export { type AuthioBff, type AuthioBffAccessTokenClaims, type AuthioBffApiOptions, type AuthioBffClaim, AuthioBffClaimTypes, type AuthioBffCookieSameSite, AuthioBffDefaults, type AuthioBffError, type AuthioBffMemoryStore, type AuthioBffMemoryStoreOptions, type AuthioBffOptions, type AuthioBffRemoteApiOptions, type AuthioBffRemoteApiTokenMode, type AuthioBffSessionInfo, type AuthioBffSessionStore, type AuthioBffSessionValidation, type AuthioBffStoredSession, type AuthioBffUserTokenOptions, authioBff, createAuthioBffMemoryStore, isLocalUrl };

package/dist/index.js

@@ -184,6 +184,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),
@@ -221,6 +222,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))
@@ -247,6 +254,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))]);
 }
@@ -564,7 +575,6 @@ function authioBff(options) {
     }
   };
   const readAccessToken = async (accessToken) => {
-    if (!accessToken) return void 0;
     try {
       return await client.readAccessTokenClaims(accessToken);
     } catch (error) {
@@ -572,6 +582,25 @@ function authioBff(options) {
       return void 0;
     }
   };
+  const introspectAccessToken = async (accessToken) => {
+    const { active, ...claims } = await client.introspect(accessToken, { tokenTypeHint: 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.validateIdToken(idToken, { accessToken });
@@ -636,6 +665,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;
@@ -652,11 +690,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) {
@@ -777,7 +816,7 @@ function authioBff(options) {
     try {
       const { tokens, idToken } = await client.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.userInfo(tokens.access_token));
@@ -974,6 +1013,14 @@ function lifetimeOf(expiresIn) {
 function textOf(value) {
   return typeof value === "string" && value ? value : void 0;
 }
+var InactiveAccessTokenError = class extends 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");