@hyper.authio/server 0.8.0 → 0.9.0

package/dist/index.d.cts

@@ -75,7 +75,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;
@@ -203,9 +203,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 +266,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;
 /**
@@ -301,13 +303,26 @@ declare class AuthioBearerError extends AuthioError {
     get wwwAuthenticate(): string;
 }
 /**
- * The caller is known but not allowed: answer `403`, with `wwwAuthenticate` when the refusal has a bearer error.
+ * A rule refused a caller whose token is valid. A refusal asking for a stronger or more recent sign-in
+ * (`insufficient_user_authentication`) answers `401`, as RFC 9470 §3 has it, naming the protected resource metadata
+ * (`resource_metadata`, RFC 9728 §5.1) when the API publishes it; every other refusal answers `403`, with
+ * `wwwAuthenticate` when it is about scopes (`insufficient_scope`, RFC 6750 §3.1).
  */
 declare class AuthioForbiddenError extends AuthioError {
-    readonly status = 403;
+    /** `401` for a step-up (`insufficient_user_authentication`), `403` otherwise. */
+    readonly status: 401 | 403;
     readonly failure: AuthioRuleFailure;
-    constructor(failure: AuthioRuleFailure);
-    /** The `WWW-Authenticate` value, or `undefined` when the refusal is not about scopes or the sign-in. */
+    /** The API's protected resource metadata URL (RFC 9728), sent as `resource_metadata` with a step-up `401`. */
+    readonly resourceMetadata: string | undefined;
+    constructor(failure: AuthioRuleFailure, options?: {
+        resourceMetadata?: string;
+    });
+    /** The same refusal, pointing at the API's protected resource metadata. */
+    withResourceMetadata(resourceMetadata: string | undefined): AuthioForbiddenError;
+    /**
+     * The `WWW-Authenticate` value, or `undefined` when the refusal is not about scopes or the sign-in. A step-up `401`
+     * carries `resource_metadata` when `resourceMetadata` is set.
+     */
     get wwwAuthenticate(): string | undefined;
 }
 /**
@@ -316,7 +331,8 @@ declare class AuthioForbiddenError extends AuthioError {
  */
 declare function toForbiddenChallenge(failure: AuthioRuleFailure): string | undefined;
 /**
- * Problem details (RFC 9457) for a `401` or `403`.
+ * Problem details (RFC 9457) for a `401` or `403`, with the refusal's `status`: a step-up refusal is `401`
+ * Unauthorized and carries `error`, `acr_values` and `max_age`.
  */
 declare function toProblemDetails(error: AuthioBearerError | AuthioForbiddenError): Record<string, unknown>;
 
@@ -367,7 +383,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

@@ -75,7 +75,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;
@@ -203,9 +203,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 +266,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;
 /**
@@ -301,13 +303,26 @@ declare class AuthioBearerError extends AuthioError {
     get wwwAuthenticate(): string;
 }
 /**
- * The caller is known but not allowed: answer `403`, with `wwwAuthenticate` when the refusal has a bearer error.
+ * A rule refused a caller whose token is valid. A refusal asking for a stronger or more recent sign-in
+ * (`insufficient_user_authentication`) answers `401`, as RFC 9470 §3 has it, naming the protected resource metadata
+ * (`resource_metadata`, RFC 9728 §5.1) when the API publishes it; every other refusal answers `403`, with
+ * `wwwAuthenticate` when it is about scopes (`insufficient_scope`, RFC 6750 §3.1).
  */
 declare class AuthioForbiddenError extends AuthioError {
-    readonly status = 403;
+    /** `401` for a step-up (`insufficient_user_authentication`), `403` otherwise. */
+    readonly status: 401 | 403;
     readonly failure: AuthioRuleFailure;
-    constructor(failure: AuthioRuleFailure);
-    /** The `WWW-Authenticate` value, or `undefined` when the refusal is not about scopes or the sign-in. */
+    /** The API's protected resource metadata URL (RFC 9728), sent as `resource_metadata` with a step-up `401`. */
+    readonly resourceMetadata: string | undefined;
+    constructor(failure: AuthioRuleFailure, options?: {
+        resourceMetadata?: string;
+    });
+    /** The same refusal, pointing at the API's protected resource metadata. */
+    withResourceMetadata(resourceMetadata: string | undefined): AuthioForbiddenError;
+    /**
+     * The `WWW-Authenticate` value, or `undefined` when the refusal is not about scopes or the sign-in. A step-up `401`
+     * carries `resource_metadata` when `resourceMetadata` is set.
+     */
     get wwwAuthenticate(): string | undefined;
 }
 /**
@@ -316,7 +331,8 @@ declare class AuthioForbiddenError extends AuthioError {
  */
 declare function toForbiddenChallenge(failure: AuthioRuleFailure): string | undefined;
 /**
- * Problem details (RFC 9457) for a `401` or `403`.
+ * Problem details (RFC 9457) for a `401` or `403`, with the refusal's `status`: a step-up refusal is `401`
+ * Unauthorized and carries `error`, `acr_values` and `max_age`.
  */
 declare function toProblemDetails(error: AuthioBearerError | AuthioForbiddenError): Record<string, unknown>;
 
@@ -367,7 +383,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, 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;
@@ -102,7 +102,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 +275,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 {
@@ -469,16 +470,30 @@ var AuthioBearerError = class _AuthioBearerError extends AuthioError {
     return parameters.length === 0 ? "Bearer" : `Bearer ${parameters.join(", ")}`;
   }
 };
-var AuthioForbiddenError = class extends AuthioError {
-  status = 403;
+var AuthioForbiddenError = class _AuthioForbiddenError extends AuthioError {
+  /** `401` for a step-up (`insufficient_user_authentication`), `403` otherwise. */
+  status;
   failure;
-  constructor(failure) {
+  /** The API's protected resource metadata URL (RFC 9728), sent as `resource_metadata` with a step-up `401`. */
+  resourceMetadata;
+  constructor(failure, options = {}) {
     super(failure.message);
     this.failure = failure;
+    this.status = failure.error === "insufficient_user_authentication" ? 401 : 403;
+    this.resourceMetadata = options.resourceMetadata;
   }
-  /** The `WWW-Authenticate` value, or `undefined` when the refusal is not about scopes or the sign-in. */
+  /** The same refusal, pointing at the API's protected resource metadata. */
+  withResourceMetadata(resourceMetadata) {
+    if (!resourceMetadata || resourceMetadata === this.resourceMetadata) return this;
+    return new _AuthioForbiddenError(this.failure, { resourceMetadata });
+  }
+  /**
+   * The `WWW-Authenticate` value, or `undefined` when the refusal is not about scopes or the sign-in. A step-up `401`
+   * carries `resource_metadata` when `resourceMetadata` is set.
+   */
   get wwwAuthenticate() {
-    return toForbiddenChallenge(this.failure);
+    const challenge = toForbiddenChallenge(this.failure);
+    return challenge && this.status === 401 && this.resourceMetadata ? `${challenge}, resource_metadata="${escapeQuoted(this.resourceMetadata)}"` : challenge;
   }
 };
 function toForbiddenChallenge(failure) {
@@ -492,15 +507,15 @@ function toForbiddenChallenge(failure) {
 function toProblemDetails(error) {
   if (error instanceof AuthioBearerError)
     return {
-      type: "https://tools.ietf.org/html/rfc9110#section-15.5.2",
+      type: unauthorizedType,
       title: "Unauthorized",
       status: 401,
       detail: "A valid Authio access token is required."
     };
   return {
-    type: "https://tools.ietf.org/html/rfc9110#section-15.5.4",
-    title: "Forbidden",
-    status: 403,
+    type: error.status === 401 ? unauthorizedType : "https://tools.ietf.org/html/rfc9110#section-15.5.4",
+    title: error.status === 401 ? "Unauthorized" : "Forbidden",
+    status: error.status,
     detail: error.failure.message || "The caller is not allowed to access this resource.",
     ...error.failure.error ? { error: error.failure.error } : {},
     ...error.failure.scope ? { scope: error.failure.scope } : {},
@@ -508,6 +523,7 @@ function toProblemDetails(error) {
     ...error.failure.maxAge !== void 0 ? { max_age: error.failure.maxAge } : {}
   };
 }
+var unauthorizedType = "https://tools.ietf.org/html/rfc9110#section-15.5.2";
 function toHeaderText(text) {
   return [...text].map((character) => character >= " " && character <= "~" && character !== '"' && character !== "\\" ? character : "?").join("");
 }
@@ -621,13 +637,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 });
@@ -903,13 +921,16 @@ function createOnBehalfOf(options) {
         };
         const token = await getToken(subject, request.signal);
         const response = await attempt(token);
-        if (response.status !== 401) return response;
+        if (response.status !== 401 || isStepUpChallenge(response)) return response;
         await invalidate(subject, token.accessToken);
         return attempt(await getToken(subject, request.signal));
       };
     }
   };
 }
+function isStepUpChallenge(response) {
+  return parseAuthioBearerChallenge(response.headers.get("www-authenticate"))?.error === AuthioOAuthErrors.InsufficientUserAuthentication;
+}
 function tokenOf(subject) {
   if (!subject) return void 0;
   return typeof subject === "string" ? subject : subject.token;