@hyper.authio/server 0.8.1 → 0.10.0

package/dist/index.d.cts

@@ -34,8 +34,9 @@ interface AuthioUserClaimSettings {
     groupClaims?: readonly string[];
 }
 /**
- * The caller of an API, read from a validated access token or an introspection answer: identity, every form of
- * permission Authio issues, and the raw claims for anything else.
+ * The caller of an API, read from a validated access token, an introspection answer, or both (the token's claims and
+ * those of the answer the token does not carry, as `activeCheck` reads it): identity, every form of permission Authio
+ * issues, and the raw claims for anything else.
  */
 declare class AuthioUser {
     /** `sub`: the person's id, or the credential's for a machine caller. */
@@ -75,7 +76,7 @@ declare class AuthioUser {
     readonly actorChain: readonly string[];
     /** `auth_time`, in seconds since the epoch. */
     readonly authTime: number | undefined;
-    /** The client the token was issued to (`azp`, else `client_id`). */
+    /** The client the token was issued to (`client_id`, RFC 9068 §2.2, else `azp`). */
     readonly clientId: string | undefined;
     /** `sid`. */
     readonly sessionId: string | undefined;
@@ -121,7 +122,10 @@ declare class AuthioUser {
     readonly credentialType: string | undefined;
     /** `credential_id`. */
     readonly credentialId: string | undefined;
-    /** Every claim, as the token or the introspection answer carried it. */
+    /**
+     * Every claim, as the token or the introspection answer carried it (with `activeCheck`, the token's, plus the
+     * answer's the token does not carry).
+     */
     readonly claims: Readonly<Record<string, unknown>>;
     /** The access token the user was read from. Not enumerable, so it stays out of logs and JSON. */
     readonly token: string | undefined;
@@ -203,9 +207,11 @@ interface AuthioRule {
     check(user: AuthioUser): AuthioRuleFailure | undefined;
 }
 /**
- * Checks every rule. On refusal the message joins every rule's, and the error is the one asking for a stronger
- * sign-in (with the strongest `acr_values` and the shortest `max_age` the failing rules ask for), else the first one
- * that has an error.
+ * Checks every rule. On refusal the message joins every rule's. When a rule other than a step-up fails (a scope, role,
+ * permission, group, claim, organization, client or caller kind), no stronger sign-in can satisfy the request: the
+ * refusal is a `403`, with the first such rule's error (`insufficient_scope`) or none, and never asks for a step-up.
+ * Only when every failing rule asks for a stronger or more recent sign-in is the error `insufficient_user_authentication`,
+ * with the strongest `acr_values` and the shortest `max_age` they ask for.
  */
 declare function authorize(user: AuthioUser, ...rules: AuthioRule[]): AuthioRuleFailure | undefined;
 /**
@@ -264,7 +270,7 @@ declare function requireRecentAuthentication(maxAge: number, options?: {
  */
 declare function requireCallerKind(kinds: AuthioCallerKind | readonly AuthioCallerKind[]): AuthioRule;
 /**
- * Requires the token to have been issued to one of the clients (`azp`, else `client_id`).
+ * Requires the token to have been issued to one of the clients (`client_id`, else `azp`).
  */
 declare function requireClient(clientIds: string | readonly string[]): AuthioRule;
 /**
@@ -337,10 +343,15 @@ declare function toProblemDetails(error: AuthioBearerError | AuthioForbiddenErro
 /**
  * Whether and how Authio's introspection endpoint takes part in validating a token.
  *
- * - `none`: the JWT is validated locally (signature, issuer, audience, lifetime). Fastest; a revoked token stays
- *   valid until it expires.
- * - `activeCheck`: validated locally, then confirmed active by introspection (cached per `jti`).
- * - `introspectionOnly`: introspection alone, for opaque (reference) tokens, or encrypted ones without the key.
+ * - `none`: the JWT is validated locally (signature, issuer, audience, lifetime) and the caller is read from it alone.
+ *   Fastest; a revoked token stays valid until it expires. A lightweight access token carries no roles, permissions,
+ *   plan, profile or email, so it needs one of the modes below.
+ * - `activeCheck`: validated locally, then confirmed active by introspection (cached per `jti`). The caller is read
+ *   from the token, and the introspection answer adds the claims the token does not carry: the answer has every claim
+ *   of the complete token, so a lightweight access token's roles and permissions are read too. A claim the token
+ *   carries keeps the token's value, which its signature vouches for (the answer names a single `aud`).
+ * - `introspectionOnly`: introspection alone, for opaque (reference) tokens, or encrypted ones without the key. The
+ *   caller is read from the answer.
  */
 type AuthioIntrospectionMode = "none" | "activeCheck" | "introspectionOnly";
 /**
@@ -381,7 +392,10 @@ interface AuthioVerifierOptions extends AuthioConnectionOptions, AuthioUserClaim
      * realm's keys are accepted, and never HS*.
      */
     accessTokenSignedResponseAlg?: string | readonly string[];
-    /** Refuses a token whose `typ` claim is present and not `Bearer` (an ID token, for one). Defaults to `true`. */
+    /**
+     * Refuses a token whose `typ` claim is present and not `Bearer` (an ID token, for one). Defaults to `true`. A JWT
+     * whose header `typ` is not `at+jwt` (RFC 9068 §4) is refused whatever this says.
+     */
     rejectNonAccessTokens?: boolean;
     /**
      * The private half of the encryption key Authio encrypts this API's access tokens to (the resource server's or its

package/dist/index.d.ts

@@ -34,8 +34,9 @@ interface AuthioUserClaimSettings {
     groupClaims?: readonly string[];
 }
 /**
- * The caller of an API, read from a validated access token or an introspection answer: identity, every form of
- * permission Authio issues, and the raw claims for anything else.
+ * The caller of an API, read from a validated access token, an introspection answer, or both (the token's claims and
+ * those of the answer the token does not carry, as `activeCheck` reads it): identity, every form of permission Authio
+ * issues, and the raw claims for anything else.
  */
 declare class AuthioUser {
     /** `sub`: the person's id, or the credential's for a machine caller. */
@@ -75,7 +76,7 @@ declare class AuthioUser {
     readonly actorChain: readonly string[];
     /** `auth_time`, in seconds since the epoch. */
     readonly authTime: number | undefined;
-    /** The client the token was issued to (`azp`, else `client_id`). */
+    /** The client the token was issued to (`client_id`, RFC 9068 §2.2, else `azp`). */
     readonly clientId: string | undefined;
     /** `sid`. */
     readonly sessionId: string | undefined;
@@ -121,7 +122,10 @@ declare class AuthioUser {
     readonly credentialType: string | undefined;
     /** `credential_id`. */
     readonly credentialId: string | undefined;
-    /** Every claim, as the token or the introspection answer carried it. */
+    /**
+     * Every claim, as the token or the introspection answer carried it (with `activeCheck`, the token's, plus the
+     * answer's the token does not carry).
+     */
     readonly claims: Readonly<Record<string, unknown>>;
     /** The access token the user was read from. Not enumerable, so it stays out of logs and JSON. */
     readonly token: string | undefined;
@@ -203,9 +207,11 @@ interface AuthioRule {
     check(user: AuthioUser): AuthioRuleFailure | undefined;
 }
 /**
- * Checks every rule. On refusal the message joins every rule's, and the error is the one asking for a stronger
- * sign-in (with the strongest `acr_values` and the shortest `max_age` the failing rules ask for), else the first one
- * that has an error.
+ * Checks every rule. On refusal the message joins every rule's. When a rule other than a step-up fails (a scope, role,
+ * permission, group, claim, organization, client or caller kind), no stronger sign-in can satisfy the request: the
+ * refusal is a `403`, with the first such rule's error (`insufficient_scope`) or none, and never asks for a step-up.
+ * Only when every failing rule asks for a stronger or more recent sign-in is the error `insufficient_user_authentication`,
+ * with the strongest `acr_values` and the shortest `max_age` they ask for.
  */
 declare function authorize(user: AuthioUser, ...rules: AuthioRule[]): AuthioRuleFailure | undefined;
 /**
@@ -264,7 +270,7 @@ declare function requireRecentAuthentication(maxAge: number, options?: {
  */
 declare function requireCallerKind(kinds: AuthioCallerKind | readonly AuthioCallerKind[]): AuthioRule;
 /**
- * Requires the token to have been issued to one of the clients (`azp`, else `client_id`).
+ * Requires the token to have been issued to one of the clients (`client_id`, else `azp`).
  */
 declare function requireClient(clientIds: string | readonly string[]): AuthioRule;
 /**
@@ -337,10 +343,15 @@ declare function toProblemDetails(error: AuthioBearerError | AuthioForbiddenErro
 /**
  * Whether and how Authio's introspection endpoint takes part in validating a token.
  *
- * - `none`: the JWT is validated locally (signature, issuer, audience, lifetime). Fastest; a revoked token stays
- *   valid until it expires.
- * - `activeCheck`: validated locally, then confirmed active by introspection (cached per `jti`).
- * - `introspectionOnly`: introspection alone, for opaque (reference) tokens, or encrypted ones without the key.
+ * - `none`: the JWT is validated locally (signature, issuer, audience, lifetime) and the caller is read from it alone.
+ *   Fastest; a revoked token stays valid until it expires. A lightweight access token carries no roles, permissions,
+ *   plan, profile or email, so it needs one of the modes below.
+ * - `activeCheck`: validated locally, then confirmed active by introspection (cached per `jti`). The caller is read
+ *   from the token, and the introspection answer adds the claims the token does not carry: the answer has every claim
+ *   of the complete token, so a lightweight access token's roles and permissions are read too. A claim the token
+ *   carries keeps the token's value, which its signature vouches for (the answer names a single `aud`).
+ * - `introspectionOnly`: introspection alone, for opaque (reference) tokens, or encrypted ones without the key. The
+ *   caller is read from the answer.
  */
 type AuthioIntrospectionMode = "none" | "activeCheck" | "introspectionOnly";
 /**
@@ -381,7 +392,10 @@ interface AuthioVerifierOptions extends AuthioConnectionOptions, AuthioUserClaim
      * realm's keys are accepted, and never HS*.
      */
     accessTokenSignedResponseAlg?: string | readonly string[];
-    /** Refuses a token whose `typ` claim is present and not `Bearer` (an ID token, for one). Defaults to `true`. */
+    /**
+     * Refuses a token whose `typ` claim is present and not `Bearer` (an ID token, for one). Defaults to `true`. A JWT
+     * whose header `typ` is not `at+jwt` (RFC 9068 §4) is refused whatever this says.
+     */
     rejectNonAccessTokens?: boolean;
     /**
      * The private half of the encryption key Authio encrypts this API's access tokens to (the resource server's or its

package/dist/index.js

@@ -1,4 +1,4 @@
-import { systemClock, AuthioClaimTypes, parseResourceAccess, AuthioError, AuthioDefaults, resolveIssuer, AuthioConfigurationError, resolveConnection, createAuthioDiscoveryClient, seconds, AuthioHmacAlgorithms, createAuthioSigningKeys, encryptionKeyFromFile, createAuthioTokenDecrypter, AuthioAsymmetricAlgorithms, requireHmacSecretLength, createAuthioClient, toScopeString, parseAuthioBearerChallenge, AuthioOAuthErrors, AuthioWebhookHeaders, verifyWebhookSignature, tryParseWebhookEvent, toClientCredentialsToken, isAuthioTokenEncrypted, AuthioTokenValidationError, withClientSecret, verifyAuthioJwt, AuthioTokenTypes } from '@hyper.authio/client';
+import { systemClock, AuthioClaimTypes, parseResourceAccess, AuthioError, AuthioDefaults, resolveIssuer, AuthioConfigurationError, resolveConnection, createAuthioDiscoveryClient, seconds, AuthioHmacAlgorithms, createAuthioSigningKeys, encryptionKeyFromFile, createAuthioTokenDecrypter, AuthioAsymmetricAlgorithms, requireHmacSecretLength, createAuthioClient, toScopeString, parseAuthioBearerChallenge, AuthioOAuthErrors, AuthioWebhookHeaders, verifyWebhookSignature, tryParseWebhookEvent, toClientCredentialsToken, isAuthioTokenEncrypted, AuthioTokenValidationError, withClientSecret, verifyAuthioJwt, requireAccessTokenType, AuthioTokenTypes } from '@hyper.authio/client';
 import { decodeProtectedHeader } from 'jose';
 
 // src/user.ts
@@ -41,7 +41,7 @@ var AuthioUser = class _AuthioUser {
   actorChain;
   /** `auth_time`, in seconds since the epoch. */
   authTime;
-  /** The client the token was issued to (`azp`, else `client_id`). */
+  /** The client the token was issued to (`client_id`, RFC 9068 §2.2, else `azp`). */
   clientId;
   /** `sid`. */
   sessionId;
@@ -87,7 +87,10 @@ var AuthioUser = class _AuthioUser {
   credentialType;
   /** `credential_id`. */
   credentialId;
-  /** Every claim, as the token or the introspection answer carried it. */
+  /**
+   * Every claim, as the token or the introspection answer carried it (with `activeCheck`, the token's, plus the
+   * answer's the token does not carry).
+   */
   claims;
   flatRoles;
   /**
@@ -102,7 +105,7 @@ var AuthioUser = class _AuthioUser {
     const text = (name) => typeof claims[name] === "string" && claims[name] ? claims[name] : void 0;
     this.claims = Object.freeze({ ...claims });
     this.subject = text(AuthioClaimTypes.Subject) ?? "";
-    this.clientId = text(AuthioClaimTypes.AuthorizedParty) ?? text(AuthioClaimTypes.ClientId);
+    this.clientId = text(AuthioClaimTypes.ClientId) ?? text(AuthioClaimTypes.AuthorizedParty);
     this.sessionId = text(AuthioClaimTypes.SessionId);
     this.tokenId = text(AuthioClaimTypes.JwtId);
     this.audiences = Object.freeze(distinct(valuesOf(claims[AuthioClaimTypes.Audience])));
@@ -275,8 +278,9 @@ function distinctIgnoringCase(values) {
 function authorize(user, ...rules) {
   const failures = rules.map((rule) => rule.check(user)).filter((failure) => failure !== void 0);
   if (failures.length === 0) return void 0;
-  const stepUps = failures.filter((failure) => failure.error === "insufficient_user_authentication");
-  const bearer = stepUps[0] ?? failures.find((failure) => failure.error);
+  const others = failures.filter((failure) => failure.error !== "insufficient_user_authentication");
+  const stepUps = others.length === 0 ? failures : [];
+  const bearer = stepUps[0] ?? others.find((failure) => failure.error);
   const acrValues = strongestAcr(stepUps.map((failure) => failure.acrValues));
   const maxAges = stepUps.map((failure) => failure.maxAge).filter((value) => value !== void 0);
   return {
@@ -636,13 +640,15 @@ function createAuthioVerifier(options) {
     }
     let payload;
     try {
-      ({ payload } = await verifyAuthioJwt(signed, keySet, {
+      let header;
+      ({ payload, header } = await verifyAuthioJwt(signed, keySet, {
         issuer: connection.issuer,
         audiences,
         algorithms,
         clockSkew,
         now: connection.clock.now()
       }));
+      requireAccessTokenType(header);
     } catch (error) {
       if (error instanceof AuthioTokenValidationError && error.reason === "invalid_algorithm" && symmetric.length === 0 && isSymmetricToken(signed))
         throw new AuthioBearerError(AuthioBearerErrorDescriptions.Symmetric, { cause: error, reason: error.reason });
@@ -652,8 +658,9 @@ function createAuthioVerifier(options) {
     const type = typeof payload.typ === "string" ? payload.typ : void 0;
     if (rejectNonAccessTokens && type !== void 0 && type.toLowerCase() !== "bearer")
       throw new AuthioBearerError(`Only access tokens are accepted; this token's typ is '${type}'.`, { reason: "not_access_token" });
-    if (introspection === "activeCheck") await confirmActive(token, payload, signal);
-    return new AuthioUser(payload, claimSettings, token);
+    if (introspection !== "activeCheck") return new AuthioUser(payload, claimSettings, token);
+    const answer = await confirmActive(token, payload, signal);
+    return new AuthioUser({ ...claimsOfIntrospection(answer), ...payload }, claimSettings, token);
   };
   const confirmActive = async (token, payload, signal) => {
     const key = payload.jti ? `jti:${payload.jti}` : await keyForToken(token);
@@ -665,6 +672,7 @@ function createAuthioVerifier(options) {
       throw new AuthioBearerError(AuthioBearerErrorDescriptions.Unconfirmed, { cause: error, reason: "unconfirmed" });
     }
     if (!result) throw new AuthioBearerError(AuthioBearerErrorDescriptions.Inactive, { reason: "inactive" });
+    return result;
   };
   const verifyByIntrospection = async (token, signal) => {
     let result;