@hyper.authio/server 0.7.0 → 0.8.1

package/dist/index.d.cts

@@ -301,13 +301,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 +329,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>;
 
@@ -359,8 +373,14 @@ interface AuthioVerifierOptions extends AuthioConnectionOptions, AuthioUserClaim
     introspectionCacheDuration?: number;
     /** Seconds of clock skew tolerated on `exp` and `nbf`. Defaults to 30. */
     clockSkew?: number;
-    /** Accepted signing algorithms. Defaults to the asymmetric ones (RS*, PS*, ES*). */
-    validAlgorithms?: readonly string[];
+    /**
+     * The algorithm (or algorithms) access tokens are signed with, as the client registered in Authio signs them:
+     * RS/PS/ES 256/384/512, or HS256/384/512 verified with the `clientSecret` of `client` (its UTF-8 octets, at least
+     * 32, 48 or 64 bytes as RFC 7518 §3.2 asks). Only the client's own API holds that secret, so only it validates an HS*
+     * token locally; any other API validates such tokens with introspection. Left out, the asymmetric algorithms of the
+     * 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`. */
     rejectNonAccessTokens?: boolean;
     /**
@@ -370,6 +390,13 @@ interface AuthioVerifierOptions extends AuthioConnectionOptions, AuthioUserClaim
     clientEncryptionKey?: AuthioEncryptionKeySource;
     /** A PEM or JWK file holding `clientEncryptionKey` (Node only). */
     clientEncryptionKeyPath?: string;
+    /**
+     * The key management algorithms (`alg`) decrypted. Defaults to RSA-OAEP and RSA-OAEP-256; RSA1_5 cannot be listed,
+     * because Node cannot decrypt it.
+     */
+    encryptionAlgorithms?: readonly string[];
+    /** The content encryption algorithms (`enc`) decrypted. Defaults to A128CBC-HS256, A192CBC-HS384, A256CBC-HS512. */
+    encryptionMethods?: readonly string[];
     /** Accepted for parity with the other Authio SDKs; RSA1_5 stays refused, because Node cannot decrypt it. */
     allowLegacyEncryptionAlgorithms?: boolean;
 }
@@ -416,6 +443,7 @@ declare const AuthioBearerErrorDescriptions: {
     readonly Empty: "The token is empty.";
     readonly Encrypted: "The token is encrypted; set clientEncryptionKey to decrypt it, or validate it with introspection ('introspectionOnly').";
     readonly SigningKeysUnavailable: "Authio could not be reached to read its signing keys.";
+    readonly Symmetric: "The token is signed with the client's secret (HS*): set accessTokenSignedResponseAlg and the client's clientSecret to validate it locally, or validate it with introspection ('introspectionOnly').";
 };
 /**
  * Creates a token verifier.

package/dist/index.d.ts

@@ -301,13 +301,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 +329,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>;
 
@@ -359,8 +373,14 @@ interface AuthioVerifierOptions extends AuthioConnectionOptions, AuthioUserClaim
     introspectionCacheDuration?: number;
     /** Seconds of clock skew tolerated on `exp` and `nbf`. Defaults to 30. */
     clockSkew?: number;
-    /** Accepted signing algorithms. Defaults to the asymmetric ones (RS*, PS*, ES*). */
-    validAlgorithms?: readonly string[];
+    /**
+     * The algorithm (or algorithms) access tokens are signed with, as the client registered in Authio signs them:
+     * RS/PS/ES 256/384/512, or HS256/384/512 verified with the `clientSecret` of `client` (its UTF-8 octets, at least
+     * 32, 48 or 64 bytes as RFC 7518 §3.2 asks). Only the client's own API holds that secret, so only it validates an HS*
+     * token locally; any other API validates such tokens with introspection. Left out, the asymmetric algorithms of the
+     * 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`. */
     rejectNonAccessTokens?: boolean;
     /**
@@ -370,6 +390,13 @@ interface AuthioVerifierOptions extends AuthioConnectionOptions, AuthioUserClaim
     clientEncryptionKey?: AuthioEncryptionKeySource;
     /** A PEM or JWK file holding `clientEncryptionKey` (Node only). */
     clientEncryptionKeyPath?: string;
+    /**
+     * The key management algorithms (`alg`) decrypted. Defaults to RSA-OAEP and RSA-OAEP-256; RSA1_5 cannot be listed,
+     * because Node cannot decrypt it.
+     */
+    encryptionAlgorithms?: readonly string[];
+    /** The content encryption algorithms (`enc`) decrypted. Defaults to A128CBC-HS256, A192CBC-HS384, A256CBC-HS512. */
+    encryptionMethods?: readonly string[];
     /** Accepted for parity with the other Authio SDKs; RSA1_5 stays refused, because Node cannot decrypt it. */
     allowLegacyEncryptionAlgorithms?: boolean;
 }
@@ -416,6 +443,7 @@ declare const AuthioBearerErrorDescriptions: {
     readonly Empty: "The token is empty.";
     readonly Encrypted: "The token is encrypted; set clientEncryptionKey to decrypt it, or validate it with introspection ('introspectionOnly').";
     readonly SigningKeysUnavailable: "Authio could not be reached to read its signing keys.";
+    readonly Symmetric: "The token is signed with the client's secret (HS*): set accessTokenSignedResponseAlg and the client's clientSecret to validate it locally, or validate it with introspection ('introspectionOnly').";
 };
 /**
  * Creates a token verifier.

package/dist/index.js

@@ -1,4 +1,5 @@
-import { systemClock, AuthioClaimTypes, parseResourceAccess, AuthioError, AuthioDefaults, resolveIssuer, AuthioConfigurationError, resolveConnection, createAuthioDiscoveryClient, seconds, createAuthioSigningKeys, encryptionKeyFromFile, createAuthioTokenDecrypter, createAuthioClient, toScopeString, AuthioWebhookHeaders, verifyWebhookSignature, tryParseWebhookEvent, toClientCredentialsToken, isAuthioTokenEncrypted, AuthioTokenValidationError, 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, AuthioTokenTypes } from '@hyper.authio/client';
+import { decodeProtectedHeader } from 'jose';
 
 // src/user.ts
 var accessTokenTypes = /* @__PURE__ */ new Set(["bearer", "api_key"]);
@@ -468,16 +469,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) {
@@ -491,15 +506,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 } : {},
@@ -507,6 +522,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("");
 }
@@ -551,7 +567,8 @@ var AuthioBearerErrorDescriptions = {
   Unconfirmed: "Authio could not be reached to confirm that the token is active.",
   Empty: "The token is empty.",
   Encrypted: "The token is encrypted; set clientEncryptionKey to decrypt it, or validate it with introspection ('introspectionOnly').",
-  SigningKeysUnavailable: "Authio could not be reached to read its signing keys."
+  SigningKeysUnavailable: "Authio could not be reached to read its signing keys.",
+  Symmetric: "The token is signed with the client's secret (HS*): set accessTokenSignedResponseAlg and the client's clientSecret to validate it locally, or validate it with introspection ('introspectionOnly')."
 };
 var maxCachedAnswers = 1e4;
 function createAuthioVerifier(options) {
@@ -571,7 +588,9 @@ function createAuthioVerifier(options) {
   const resourceMetadataUrl = resolveResourceMetadata(options.resourceMetadata, resource);
   const cacheDurationMs = seconds(options.introspectionCacheDuration, 30, "introspectionCacheDuration");
   const clockSkew = seconds(options.clockSkew, 30, "clockSkew") / 1e3;
-  const algorithms = options.validAlgorithms && options.validAlgorithms.length > 0 ? [...options.validAlgorithms] : void 0;
+  const algorithms = resolveAccessTokenAlgorithms(options.accessTokenSignedResponseAlg);
+  const symmetric = algorithms?.filter((algorithm) => AuthioHmacAlgorithms.includes(algorithm)) ?? [];
+  const clientSecret = symmetric.length > 0 ? resolveClientSecret(options, symmetric) : void 0;
   const rejectNonAccessTokens = options.rejectNonAccessTokens ?? true;
   const claimSettings = { roleClaims: options.roleClaims, groupClaims: options.groupClaims };
   const cache = /* @__PURE__ */ new Map();
@@ -579,7 +598,9 @@ function createAuthioVerifier(options) {
   const encryptionKey = options.clientEncryptionKey ?? (options.clientEncryptionKeyPath ? encryptionKeyFromFile(options.clientEncryptionKeyPath) : void 0);
   const decrypt = encryptionKey === void 0 ? void 0 : createAuthioTokenDecrypter(encryptionKey, {
     setting: options.clientEncryptionKey === void 0 ? "clientEncryptionKeyPath" : "clientEncryptionKey",
-    allowLegacyEncryptionAlgorithms: options.allowLegacyEncryptionAlgorithms
+    allowLegacyEncryptionAlgorithms: options.allowLegacyEncryptionAlgorithms,
+    encryptionAlgorithms: options.encryptionAlgorithms,
+    encryptionMethods: options.encryptionMethods
   });
   const requiredScopes = Object.freeze([...new Set((options.requiredScopes ?? []).filter((scope) => scope?.trim()))]);
   const introspect = async (token, key, signal) => {
@@ -609,7 +630,7 @@ function createAuthioVerifier(options) {
     }
     let keySet;
     try {
-      keySet = await signingKeys(signal);
+      keySet = withClientSecret(await signingKeys(signal), clientSecret);
     } catch (error) {
       throw new AuthioBearerError(AuthioBearerErrorDescriptions.SigningKeysUnavailable, { cause: error, reason: "signing_keys_unavailable" });
     }
@@ -623,6 +644,8 @@ function createAuthioVerifier(options) {
         now: connection.clock.now()
       }));
     } 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 });
       if (error instanceof AuthioTokenValidationError) throw new AuthioBearerError(error.message, { cause: error, reason: error.reason });
       throw error;
     }
@@ -704,6 +727,35 @@ function resolveResourceMetadata(setting, resource) {
     throw new AuthioConfigurationError("resourceMetadata: true needs the API's resource identifier: set options.resource, or pass the metadata URL.");
   return protectedResourceMetadataUrl(resource);
 }
+function resolveAccessTokenAlgorithms(setting) {
+  const algorithms = [...new Set((typeof setting === "string" ? [setting] : [...setting ?? []]).map((algorithm) => algorithm.trim()).filter(Boolean))];
+  const known = [...AuthioAsymmetricAlgorithms, ...AuthioHmacAlgorithms];
+  for (const algorithm of algorithms)
+    if (!known.includes(algorithm))
+      throw new AuthioConfigurationError(`The Authio accessTokenSignedResponseAlg '${algorithm}' is not one of ${known.join(", ")}.`);
+  return algorithms.length > 0 ? algorithms : void 0;
+}
+function resolveClientSecret(options, symmetric) {
+  const given = options.client;
+  const source = given && !isClient(given) ? given.clientSecret : void 0;
+  if (!source)
+    throw new AuthioConfigurationError(
+      `accessTokenSignedResponseAlg ${symmetric.join(", ")} is verified with the client secret: pass options.client as { clientId, clientSecret } (an AuthioClient does not expose its secret).`
+    );
+  if (typeof source === "string") for (const algorithm of symmetric) requireHmacSecretLength(algorithm, new TextEncoder().encode(source).length);
+  return async () => {
+    const value = typeof source === "function" ? await source() : source;
+    if (typeof value !== "string" || !value) throw new AuthioConfigurationError("The Authio clientSecret function returned no secret.");
+    return value;
+  };
+}
+function isSymmetricToken(token) {
+  try {
+    return AuthioHmacAlgorithms.includes(String(decodeProtectedHeader(token).alg));
+  } catch {
+    return false;
+  }
+}
 function resolveClient(options) {
   const given = options.client;
   if (!given) return void 0;
@@ -866,13 +918,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;