@hyper.authio/server 0.1.1 → 0.7.0

package/dist/index.js

@@ -1,10 +1,45 @@
-import { systemClock, AuthioClaimTypes, parseResourceAccess, AuthioError, AuthioConfigurationError, resolveConnection, createAuthioDiscoveryClient, seconds, AuthioAsymmetricAlgorithms, createAuthioClient, toScopeString, AuthioDefaults, AuthioWebhookHeaders, verifyWebhookSignature, tryParseWebhookEvent, toClientCredentialsToken, isAuthioTokenEncrypted, AuthioTokenTypes } from '@hyper.authio/client';
-import { jwtVerify, createRemoteJWKSet, customFetch, errors, decodeProtectedHeader } from 'jose';
+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';
 
 // src/user.ts
-var AuthioUser = class {
+var accessTokenTypes = /* @__PURE__ */ new Set(["bearer", "api_key"]);
+var AuthioUser = class _AuthioUser {
   /** `sub`: the person's id, or the credential's for a machine caller. */
   subject;
+  /**
+   * Who called: `user` (a person signed in), `client` (a client as itself), `consumer` (a machine consumer of a
+   * client) or `account_credential` (a credential of an Authio account).
+   */
+  kind;
+  /**
+   * How a machine caller proved who it is (`client_secret`, `personal_access_token`, `api_key`,
+   * `consumer_api_key`); `undefined` for a person or a client.
+   */
+  credentialForm;
+  /** `consumer_name`, for a consumer. */
+  consumerName;
+  /** `credential_name`, for an account credential. */
+  credentialName;
+  /** `owner_user_id`: the person who made the credential. */
+  ownerUserId;
+  /**
+   * `owner_username`: the person who made the credential. On an account credential Authio wrote it to
+   * `consumer_name` before, which is read when `owner_username` is absent.
+   */
+  ownerUsername;
+  /** `credential_realm`: the one realm an account credential is limited to. */
+  credentialRealm;
+  /** `credential_client`: the one client an account credential is limited to. */
+  credentialClient;
+  /** Whether an administrator impersonates the subject. */
+  impersonated;
+  /** The administrator impersonating the subject. */
+  impersonator;
+  /** Whether a client acts for the subject through a delegation (`act` with `client_id`). */
+  delegated;
+  /** The clients acting for the subject, outermost first. */
+  actorChain;
+  /** `auth_time`, in seconds since the epoch. */
+  authTime;
   /** The client the token was issued to (`azp`, else `client_id`). */
   clientId;
   /** `sid`. */
@@ -58,8 +93,11 @@ var AuthioUser = class {
    * @param claims The token's payload, or the introspection answer's members.
    * @param settings Where flat roles and groups are read from.
    * @param token The access token, kept for forwarding and on-behalf-of.
+   * @param source Where the claims come from: a JWT (default) or an introspection answer. An introspection answer for
+   * a consumer that reports no `exp` and no `actor_type` is the consumer's API key (Authio reports no lifetime for a
+   * key), so its `credentialForm` is `consumer_api_key`.
    */
-  constructor(claims, settings = {}, token) {
+  constructor(claims, settings = {}, token, source = "token") {
     const text = (name) => typeof claims[name] === "string" && claims[name] ? claims[name] : void 0;
     this.claims = Object.freeze({ ...claims });
     this.subject = text(AuthioClaimTypes.Subject) ?? "";
@@ -89,11 +127,29 @@ var AuthioUser = class {
     this.preferredUsername = text(AuthioClaimTypes.PreferredUsername);
     this.credentialType = text(AuthioClaimTypes.CredentialType);
     this.credentialId = text(AuthioClaimTypes.CredentialId);
+    this.authTime = toSeconds(claims[AuthioClaimTypes.AuthTime]);
+    this.kind = this.credentialType === "client_consumer" ? "consumer" : this.credentialType === "account_secret" ? "account_credential" : this.authTime !== void 0 ? "user" : "client";
+    const machine = this.kind === "consumer" || this.kind === "account_credential";
+    const keyIntrospected = source === "introspection" && this.kind === "consumer" && claims[AuthioClaimTypes.Expiration] === void 0;
+    this.credentialForm = machine ? text(AuthioClaimTypes.ActorType) ?? (keyIntrospected ? "consumer_api_key" : "client_secret") : void 0;
+    this.consumerName = this.kind === "consumer" ? text(AuthioClaimTypes.ConsumerName) : void 0;
+    this.credentialName = text(AuthioClaimTypes.CredentialName);
+    this.ownerUserId = text(AuthioClaimTypes.OwnerUserId);
+    this.ownerUsername = text(AuthioClaimTypes.OwnerUsername) ?? (this.kind === "account_credential" ? text(AuthioClaimTypes.ConsumerName) : void 0);
+    this.credentialRealm = text(AuthioClaimTypes.CredentialRealm);
+    this.credentialClient = text(AuthioClaimTypes.CredentialClient);
+    this.delegated = this.actor?.clientId !== void 0;
+    this.actorChain = Object.freeze(chainOf(this.actor));
+    this.impersonated = !this.delegated && this.actor?.subject !== void 0;
+    this.impersonator = this.impersonated ? Object.freeze({ subject: this.actor.subject, name: this.actor.name }) : void 0;
     Object.defineProperty(this, "token", { value: token, enumerable: false });
   }
-  /** Whether an actor exchanged the token on the subject's behalf. */
-  get isDelegated() {
-    return this.actor !== void 0;
+  /**
+   * Reads the caller from an introspection answer: `client_id` becomes `azp`, `username` becomes
+   * `preferred_username`, and `token_type` becomes `typ` unless it is `api_key` (a consumer's API key).
+   */
+  static fromIntrospection(result, settings = {}, token) {
+    return new _AuthioUser(claimsOfIntrospection(result), settings, token, "introspection");
   }
   /** Whether the scope was granted. */
   hasScope(scope) {
@@ -137,9 +193,20 @@ var AuthioUser = class {
   /** Every member but the raw token. */
   toJSON() {
     const { flatRoles: _flatRoles, ...members } = this;
-    return { ...members, resourceAccess: this.resourceAccess.entries, isDelegated: this.isDelegated };
+    return { ...members, resourceAccess: this.resourceAccess.entries };
   }
 };
+function claimsOfIntrospection(result) {
+  const { active: _active, token_type: tokenType, username, ...members } = result;
+  const claims = { ...members };
+  if (typeof tokenType === "string" && claims.typ === void 0 && tokenType.toLowerCase() !== "api_key") claims.typ = tokenType;
+  if (typeof username === "string" && claims.preferred_username === void 0) claims.preferred_username = username;
+  if (typeof result.client_id === "string" && claims.azp === void 0) claims.azp = result.client_id;
+  return claims;
+}
+function isAccessTokenType(type) {
+  return accessTokenTypes.has(type.toLowerCase());
+}
 function valuesOf(value) {
   if (value === void 0 || value === null) return [];
   if (Array.isArray(value)) return value.flatMap((item) => item === null || item === void 0 ? [] : [toText(item)]);
@@ -168,11 +235,20 @@ function readActor(value, depth = 0) {
   if (!actor || typeof actor !== "object" || Array.isArray(actor) || depth > 16) return void 0;
   const record = actor;
   return Object.freeze({
-    clientId: typeof record.client_id === "string" ? record.client_id : void 0,
-    subject: typeof record.sub === "string" ? record.sub : void 0,
+    clientId: typeof record.client_id === "string" && record.client_id ? record.client_id : void 0,
+    subject: typeof record.sub === "string" && record.sub ? record.sub : void 0,
+    name: typeof record.name === "string" && record.name ? record.name : void 0,
     actor: readActor(record.act, depth + 1)
   });
 }
+function chainOf(actor) {
+  const chain = [];
+  for (let current = actor; current; current = current.actor) if (current.clientId) chain.push(current.clientId);
+  return chain;
+}
+function toSeconds(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : typeof value === "string" && /^\d+$/.test(value) ? Number(value) : void 0;
+}
 function toDate(value) {
   const seconds3 = typeof value === "number" ? value : typeof value === "string" && /^\d+$/.test(value) ? Number(value) : void 0;
   return seconds3 === void 0 ? void 0 : new Date(seconds3 * 1e3);
@@ -195,16 +271,19 @@ function distinctIgnoringCase(values) {
     return true;
   });
 }
-
-// src/rules.ts
 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 bearer = failures.find((failure) => failure.error === "insufficient_user_authentication") ?? failures.find((failure) => failure.error);
+  const stepUps = failures.filter((failure) => failure.error === "insufficient_user_authentication");
+  const bearer = stepUps[0] ?? failures.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 {
     message: failures.map((failure) => failure.message).join(" "),
     ...bearer?.error ? { error: bearer.error } : {},
-    ...bearer?.scope ? { scope: bearer.scope } : {}
+    ...bearer?.scope ? { scope: bearer.scope } : {},
+    ...acrValues ? { acrValues } : {},
+    ...maxAges.length > 0 ? { maxAge: Math.min(...maxAges) } : {}
   };
 }
 function requireScope(scopes, match = "any") {
@@ -259,23 +338,60 @@ function requireOrganization(organization) {
     }
   };
 }
-function requireAuthenticationLevel(minimumLevel) {
+function requireAuthenticationLevel(minimumLevel, options = {}) {
   if (!Number.isInteger(minimumLevel) || minimumLevel < 0) throw new RangeError("The minimum level must be a non-negative integer.");
+  const recency = options.maxAge === void 0 ? void 0 : requireRecentAuthentication(options.maxAge, { clock: options.clock });
   return {
-    description: `Authio authentication level >= ${minimumLevel}`,
-    check: (user) => user.authenticationLevel !== void 0 && user.authenticationLevel >= minimumLevel ? void 0 : { message: `The authentication level must be at least ${minimumLevel}.`, error: "insufficient_user_authentication" }
+    description: `Authio authentication level >= ${minimumLevel}${recency ? `, ${recency.description}` : ""}`,
+    check: (user) => {
+      const levelMet = user.authenticationLevel !== void 0 && user.authenticationLevel >= minimumLevel;
+      const recent = recency?.check(user);
+      if (levelMet && !recent) return void 0;
+      return {
+        message: [levelMet ? void 0 : `The authentication level must be at least ${minimumLevel}.`, recent?.message].filter(Boolean).join(" "),
+        error: "insufficient_user_authentication",
+        acrValues: String(minimumLevel),
+        ...options.maxAge !== void 0 ? { maxAge: options.maxAge } : {}
+      };
+    }
   };
 }
-function requireAuthenticationMethod(methods, match = "any") {
+var methodLevels = { mfa: "2", otp: "2", mca: "2", sms: "2", swk: "3", hwk: "3" };
+function requireAuthenticationMethod(methods, match = "any", options = {}) {
   const required = listOf(methods, "authentication method");
+  const levels = required.map((method) => methodLevels[method.toLowerCase()]).filter((level) => level !== void 0);
+  const acrValues = options.acrValues ?? (levels.length === 0 ? void 0 : match === "all" ? strongestAcr(levels) : weakestAcr(levels));
   return {
     description: `Authio authentication method (${match}): ${required.join(", ")}`,
     check: (user) => {
       const used = user.authenticationMethods.map((method) => method.toLowerCase());
-      return satisfies(required, match, (method) => used.includes(method.toLowerCase())) ? void 0 : { message: `The user must authenticate with (${match}): ${required.join(", ")}.`, error: "insufficient_user_authentication" };
+      return satisfies(required, match, (method) => used.includes(method.toLowerCase())) ? void 0 : {
+        message: `The user must authenticate with (${match}): ${required.join(", ")}.`,
+        error: "insufficient_user_authentication",
+        ...acrValues ? { acrValues } : {}
+      };
     }
   };
 }
+function requireRecentAuthentication(maxAge, options = {}) {
+  if (!Number.isInteger(maxAge) || maxAge < 0) throw new RangeError("maxAge must be a non-negative whole number of seconds.");
+  const clock = options.clock ?? systemClock;
+  return {
+    description: `Authio sign-in at most ${maxAge} s old`,
+    check: (user) => user.authTime !== void 0 && clock.now() - user.authTime * 1e3 <= maxAge * 1e3 ? void 0 : {
+      message: user.authTime === void 0 ? `The token carries no sign-in time; a sign-in at most ${maxAge} seconds old is required.` : `The sign-in must be at most ${maxAge} seconds old.`,
+      error: "insufficient_user_authentication",
+      maxAge
+    }
+  };
+}
+function requireCallerKind(kinds) {
+  const required = listOf(kinds, "caller kind");
+  return {
+    description: `Authio caller kind: ${required.join(", ")}`,
+    check: (user) => required.includes(user.kind) ? void 0 : { message: `The caller is a ${user.kind}, not one of: ${required.join(", ")}.` }
+  };
+}
 function requireClient(clientIds) {
   const required = listOf(clientIds, "client id");
   return {
@@ -307,24 +423,49 @@ function listOf(values, name) {
 function satisfies(required, match, holds) {
   return match === "all" ? required.every(holds) : required.some(holds);
 }
+function strongestAcr(values) {
+  return rankAcr(values, (left, right) => right - left);
+}
+function weakestAcr(values) {
+  return rankAcr(values, (left, right) => left - right);
+}
+function rankAcr(values, order) {
+  const known = values.filter((value) => !!value);
+  const numeric = known.filter((value) => /^\d+$/.test(value)).sort((left, right) => order(Number(left), Number(right)));
+  return numeric[0] ?? known[0];
+}
 function describeSources(sources) {
   return sources && sources.length > 0 ? ` from ${[...new Set(sources)].join(", ")}` : "";
 }
-var AuthioBearerError = class extends AuthioError {
+var AuthioBearerError = class _AuthioBearerError extends AuthioError {
   status = 401;
   /** `invalid_token`, or `undefined` when the request had no token at all (RFC 6750 §3.1). */
   error;
   /** Why the token was refused, safe to send to the caller. */
   description;
+  /** Why the token was refused, as a stable code; `undefined` when there was no token or Authio could not be asked. */
+  reason;
+  /** The API's protected resource metadata URL (RFC 9728), sent as `resource_metadata` when configured. */
+  resourceMetadata;
   constructor(description, options = {}) {
     super(description ?? "A valid Authio access token is required.", { cause: options.cause });
     this.error = "error" in options ? options.error : "invalid_token";
     this.description = description === void 0 ? void 0 : toHeaderText(description);
+    this.reason = options.reason;
+    this.resourceMetadata = options.resourceMetadata;
+  }
+  /** The same refusal, pointing at the API's protected resource metadata. */
+  withResourceMetadata(resourceMetadata) {
+    if (!resourceMetadata || resourceMetadata === this.resourceMetadata) return this;
+    return new _AuthioBearerError(this.description, { error: this.error, cause: this.cause, reason: this.reason, resourceMetadata });
   }
   /** The `WWW-Authenticate` value. */
   get wwwAuthenticate() {
-    if (!this.error) return "Bearer";
-    return this.description ? `Bearer error="${this.error}", error_description="${this.description}"` : `Bearer error="${this.error}"`;
+    const parameters = [];
+    if (this.error) parameters.push(`error="${this.error}"`);
+    if (this.error && this.description) parameters.push(`error_description="${this.description}"`);
+    if (this.resourceMetadata) parameters.push(`resource_metadata="${escapeQuoted(this.resourceMetadata)}"`);
+    return parameters.length === 0 ? "Bearer" : `Bearer ${parameters.join(", ")}`;
   }
 };
 var AuthioForbiddenError = class extends AuthioError {
@@ -341,8 +482,11 @@ var AuthioForbiddenError = class extends AuthioError {
 };
 function toForbiddenChallenge(failure) {
   if (!failure.error) return void 0;
-  const value = `Bearer error="${failure.error}", error_description="${escapeQuoted(failure.message)}"`;
-  return failure.scope ? `${value}, scope="${escapeQuoted(failure.scope)}"` : value;
+  const parameters = [`error="${failure.error}"`, `error_description="${escapeQuoted(toHeaderText(failure.message))}"`];
+  if (failure.scope) parameters.push(`scope="${escapeQuoted(failure.scope)}"`);
+  if (failure.acrValues) parameters.push(`acr_values="${escapeQuoted(failure.acrValues)}"`);
+  if (failure.maxAge !== void 0) parameters.push(`max_age=${failure.maxAge}`);
+  return `Bearer ${parameters.join(", ")}`;
 }
 function toProblemDetails(error) {
   if (error instanceof AuthioBearerError)
@@ -358,7 +502,9 @@ function toProblemDetails(error) {
     status: 403,
     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 } : {}
+    ...error.failure.scope ? { scope: error.failure.scope } : {},
+    ...error.failure.acrValues ? { acr_values: error.failure.acrValues } : {},
+    ...error.failure.maxAge !== void 0 ? { max_age: error.failure.maxAge } : {}
   };
 }
 function toHeaderText(text) {
@@ -367,17 +513,53 @@ function toHeaderText(text) {
 function escapeQuoted(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
+function protectedResourceMetadataUrl(resource) {
+  const url = parseResource(resource);
+  const path = url.pathname.replace(/\/+$/, "");
+  return `${url.origin}${AuthioDefaults.ProtectedResourceMetadataPath}${path}`;
+}
+function protectedResourceMetadataPath(resource) {
+  return new URL(protectedResourceMetadataUrl(resource)).pathname;
+}
+function createProtectedResourceMetadata(options) {
+  parseResource(options.resource);
+  const document = {
+    ...options.extra,
+    resource: options.resource,
+    authorization_servers: [resolveIssuer(options)],
+    bearer_methods_supported: ["header"]
+  };
+  if (options.scopesSupported && options.scopesSupported.length > 0) document.scopes_supported = [...options.scopesSupported];
+  if (options.resourceName) document.resource_name = options.resourceName;
+  if (options.resourceDocumentation) document.resource_documentation = options.resourceDocumentation;
+  return document;
+}
+function parseResource(resource) {
+  let url;
+  try {
+    url = new URL(resource);
+  } catch (error) {
+    throw new AuthioConfigurationError(`The resource '${resource}' is not an absolute URL.`, { cause: error });
+  }
+  if (url.hash) throw new AuthioConfigurationError(`The resource '${resource}' must not carry a fragment (RFC 8707).`);
+  return url;
+}
+
+// src/verifier.ts
 var AuthioBearerErrorDescriptions = {
   Inactive: "Authio reports the token as not active to this API's client. It was revoked or has expired or its session ended; or this API's client is not the introspection client of the resource server the token is for.",
   Unconfirmed: "Authio could not be reached to confirm that the token is active.",
   Empty: "The token is empty.",
-  Encrypted: "The token is encrypted; validate it with introspection ('introspectionOnly').",
+  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."
 };
 var maxCachedAnswers = 1e4;
 function createAuthioVerifier(options) {
-  const audiences = [...new Set((typeof options.audiences === "string" ? [options.audiences] : [...options.audiences ?? []]).filter((value) => value?.trim()))];
-  if (audiences.length === 0) throw new AuthioConfigurationError("The Authio verifier needs at least one audience: the API's resource identifier or client id.");
+  const resource = options.resource?.trim() || void 0;
+  const given = typeof options.audiences === "string" ? [options.audiences] : [...options.audiences ?? []];
+  const audiences = [...new Set([...given, ...resource ? [resource] : []].filter((value) => value?.trim()))];
+  if (audiences.length === 0)
+    throw new AuthioConfigurationError("The Authio verifier needs at least one audience: the API's resource identifier or client id.");
   const connection = resolveConnection(options);
   const discovery = createAuthioDiscoveryClient(connection);
   const introspection = options.introspection ?? "none";
@@ -386,13 +568,20 @@ function createAuthioVerifier(options) {
     throw new AuthioConfigurationError(
       `Authio introspection ('${introspection}') needs the API's confidential client: pass options.client with its clientId and clientSecret or private key.`
     );
+  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] : [...AuthioAsymmetricAlgorithms];
+  const algorithms = options.validAlgorithms && options.validAlgorithms.length > 0 ? [...options.validAlgorithms] : void 0;
   const rejectNonAccessTokens = options.rejectNonAccessTokens ?? true;
   const claimSettings = { roleClaims: options.roleClaims, groupClaims: options.groupClaims };
   const cache = /* @__PURE__ */ new Map();
-  let keys;
+  const signingKeys = createAuthioSigningKeys(connection, discovery);
+  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
+  });
+  const requiredScopes = Object.freeze([...new Set((options.requiredScopes ?? []).filter((scope) => scope?.trim()))]);
   const introspect = async (token, key, signal) => {
     const now = connection.clock.now();
     const cached = cache.get(key);
@@ -407,37 +596,39 @@ function createAuthioVerifier(options) {
     }
     return result;
   };
-  const signingKeys = async (signal) => {
-    const document = await discovery.get(signal);
-    const uri = document.jwks_uri;
-    if (!uri) throw new AuthioError("The Authio discovery document has no jwks_uri.");
-    if (!keys || keys.uri !== uri) keys = { uri, set: createRemoteJWKSet(new URL(uri), { [customFetch]: connection.fetch, timeoutDuration: connection.httpTimeoutMs }) };
-    return keys.set;
-  };
   const verifyJwt = async (token, signal) => {
-    if (isAuthioTokenEncrypted(token)) throw new AuthioBearerError(AuthioBearerErrorDescriptions.Encrypted);
+    let signed = token;
+    if (isAuthioTokenEncrypted(token)) {
+      if (!decrypt) throw new AuthioBearerError(AuthioBearerErrorDescriptions.Encrypted, { reason: "decryption_failed" });
+      try {
+        signed = await decrypt(token);
+      } catch (error) {
+        if (error instanceof AuthioTokenValidationError) throw new AuthioBearerError(error.message, { cause: error, reason: error.reason });
+        throw error;
+      }
+    }
     let keySet;
     try {
       keySet = await signingKeys(signal);
     } catch (error) {
-      throw new AuthioBearerError(AuthioBearerErrorDescriptions.SigningKeysUnavailable, { cause: error });
+      throw new AuthioBearerError(AuthioBearerErrorDescriptions.SigningKeysUnavailable, { cause: error, reason: "signing_keys_unavailable" });
     }
     let payload;
     try {
-      ({ payload } = await jwtVerify(token, keySet, {
+      ({ payload } = await verifyAuthioJwt(signed, keySet, {
         issuer: connection.issuer,
-        audience: audiences,
+        audiences,
         algorithms,
-        clockTolerance: clockSkew,
-        requiredClaims: ["exp"],
-        currentDate: new Date(connection.clock.now())
+        clockSkew,
+        now: connection.clock.now()
       }));
     } catch (error) {
-      throw new AuthioBearerError(describeJwtFailure(error, audiences, token), { cause: error });
+      if (error instanceof AuthioTokenValidationError) throw new AuthioBearerError(error.message, { cause: error, reason: error.reason });
+      throw error;
     }
     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}'.`);
+      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);
   };
@@ -448,9 +639,9 @@ function createAuthioVerifier(options) {
       result = await introspect(token, key, signal);
     } catch (error) {
       if (signal?.aborted) throw error;
-      throw new AuthioBearerError(AuthioBearerErrorDescriptions.Unconfirmed, { cause: error });
+      throw new AuthioBearerError(AuthioBearerErrorDescriptions.Unconfirmed, { cause: error, reason: "unconfirmed" });
     }
-    if (!result) throw new AuthioBearerError(AuthioBearerErrorDescriptions.Inactive);
+    if (!result) throw new AuthioBearerError(AuthioBearerErrorDescriptions.Inactive, { reason: "inactive" });
   };
   const verifyByIntrospection = async (token, signal) => {
     let result;
@@ -458,38 +649,42 @@ function createAuthioVerifier(options) {
       result = await introspect(token, await keyForToken(token), signal);
     } catch (error) {
       if (signal?.aborted) throw error;
-      throw new AuthioBearerError(AuthioBearerErrorDescriptions.Unconfirmed, { cause: error });
+      throw new AuthioBearerError(AuthioBearerErrorDescriptions.Unconfirmed, { cause: error, reason: "unconfirmed" });
     }
-    if (!result) throw new AuthioBearerError(AuthioBearerErrorDescriptions.Inactive);
-    if (result.iss && result.iss !== connection.issuer) throw new AuthioBearerError(`The issuer '${result.iss}' is invalid`);
+    if (!result) throw new AuthioBearerError(AuthioBearerErrorDescriptions.Inactive, { reason: "inactive" });
+    if (result.iss && result.iss !== connection.issuer) throw new AuthioBearerError(`The issuer '${result.iss}' is invalid`, { reason: "invalid_issuer" });
     const tokenAudiences = [result.aud ?? []].flat();
-    if (!tokenAudiences.some((audience) => audiences.includes(audience))) throw new AuthioBearerError(describeAudience(tokenAudiences, audiences));
+    if (!tokenAudiences.some((audience) => audiences.includes(audience)))
+      throw new AuthioBearerError(describeAudience(tokenAudiences, audiences), { reason: "invalid_audience" });
     if (typeof result.exp === "number" && (result.exp + clockSkew) * 1e3 <= connection.clock.now())
-      throw new AuthioBearerError(`The token expired at '${new Date(result.exp * 1e3).toISOString()}'`);
-    const { active: _active, token_type: tokenType, username, ...members } = result;
-    const claims = { ...members };
-    if (typeof tokenType === "string" && claims.typ === void 0) claims.typ = tokenType;
-    if (typeof username === "string" && claims.preferred_username === void 0) claims.preferred_username = username;
-    if (typeof result.client_id === "string" && claims.azp === void 0) claims.azp = result.client_id;
+      throw new AuthioBearerError(`The token expired at '${new Date(result.exp * 1e3).toISOString()}'`, { reason: "expired" });
+    const claims = claimsOfIntrospection(result);
     const type = typeof claims.typ === "string" ? claims.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}'.`);
-    return new AuthioUser(claims, claimSettings, token);
+    if (rejectNonAccessTokens && type !== void 0 && !isAccessTokenType(type))
+      throw new AuthioBearerError(`Only access tokens are accepted; this token's typ is '${type}'.`, { reason: "not_access_token" });
+    return new AuthioUser(claims, claimSettings, token, "introspection");
   };
   const verify = async (token, signal) => {
-    if (typeof token !== "string" || !token.trim()) throw new AuthioBearerError(AuthioBearerErrorDescriptions.Empty);
-    return introspection === "introspectionOnly" ? verifyByIntrospection(token.trim(), signal) : verifyJwt(token.trim(), signal);
+    try {
+      if (typeof token !== "string" || !token.trim()) throw new AuthioBearerError(AuthioBearerErrorDescriptions.Empty, { reason: "malformed" });
+      return introspection === "introspectionOnly" ? await verifyByIntrospection(token.trim(), signal) : await verifyJwt(token.trim(), signal);
+    } catch (error) {
+      throw error instanceof AuthioBearerError ? error.withResourceMetadata(resourceMetadataUrl) : error;
+    }
   };
   return {
     connection,
     discovery,
     audiences,
+    resource,
+    resourceMetadataUrl,
+    requiredScopes,
     introspection,
     client,
     verify,
     async verifyAuthorizationHeader(header, signal) {
       const token = readBearerToken(header);
-      if (token === void 0) throw new AuthioBearerError(void 0, { error: void 0 });
+      if (token === void 0) throw new AuthioBearerError(void 0, { error: void 0, resourceMetadata: resourceMetadataUrl });
       return verify(token, signal);
     }
   };
@@ -502,6 +697,13 @@ async function keyForToken(token) {
   const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(token)));
   return `token:${[...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
 }
+function resolveResourceMetadata(setting, resource) {
+  if (!setting) return void 0;
+  if (typeof setting === "string") return setting;
+  if (!resource)
+    throw new AuthioConfigurationError("resourceMetadata: true needs the API's resource identifier: set options.resource, or pass the metadata URL.");
+  return protectedResourceMetadataUrl(resource);
+}
 function resolveClient(options) {
   const given = options.client;
   if (!given) return void 0;
@@ -521,44 +723,11 @@ function resolveClient(options) {
 function isClient(value) {
   return typeof value.introspect === "function" && typeof value.tokens === "object";
 }
-function describeJwtFailure(error, audiences, token) {
-  if (error instanceof errors.JWTExpired) {
-    const exp = error.payload.exp;
-    return typeof exp === "number" ? `The token expired at '${new Date(exp * 1e3).toISOString()}'` : "The token has expired";
-  }
-  if (error instanceof errors.JWTClaimValidationFailed) {
-    switch (error.claim) {
-      case "aud":
-        return describeAudience([error.payload.aud ?? []].flat(), audiences);
-      case "iss":
-        return `The issuer '${error.payload.iss ?? ""}' is invalid`;
-      case "nbf":
-        return typeof error.payload.nbf === "number" ? `The token is not valid before '${new Date(error.payload.nbf * 1e3).toISOString()}'` : "The token is not valid yet";
-      case "exp":
-        return "The token has no expiration";
-      default:
-        return `The token's ${error.claim} claim is invalid`;
-    }
-  }
-  if (error instanceof errors.JWSSignatureVerificationFailed) return "The signature is invalid";
-  if (error instanceof errors.JWKSNoMatchingKey) return "The signature key was not found";
-  if (error instanceof errors.JOSEAlgNotAllowed) return `The algorithm '${algorithmOf(token)}' is not available`;
-  if (error instanceof errors.JWKSTimeout || error instanceof errors.JWKSInvalid) return AuthioBearerErrorDescriptions.SigningKeysUnavailable;
-  if (error instanceof errors.JWTInvalid || error instanceof errors.JWSInvalid) return "The token is malformed";
-  return void 0;
-}
 function describeAudience(tokenAudiences, audiences) {
   const known = tokenAudiences.length === 0 ? "" : ` ${tokenAudiences.map((audience) => `'${audience}'`).join(" and ")}`;
   const accepted = audiences.map((audience) => `'${audience}'`).join(" or ");
   return audiences.length === 1 ? `The token is not addressed to this API: its audience${known} is not ${accepted}. Request the token for that resource (RFC 8707).` : `The token is not addressed to this API: its audience${known} is not ${accepted}. Request the token for one of those resources (RFC 8707).`;
 }
-function algorithmOf(token) {
-  try {
-    return String(decodeProtectedHeader(token).alg ?? "");
-  } catch {
-    return "";
-  }
-}
 function createAuthioWebhooks(options) {
   const secrets = [...new Set([options.secret, ...options.secrets ?? []].filter((secret) => !!secret?.trim()))];
   if (secrets.length === 0) throw new AuthioConfigurationError("Authio webhooks need the webhook's secret.");
@@ -709,6 +878,6 @@ function tokenOf(subject) {
   return typeof subject === "string" ? subject : subject.token;
 }
 
-export { AuthioBearerError, AuthioBearerErrorDescriptions, AuthioForbiddenError, AuthioUser, allOf, anyOf, authorize, createAuthioVerifier, createAuthioWebhooks, createForwardingFetch, createMemoryDeduplicationStore, createOnBehalfOf, readBearerToken, requireAuthenticationLevel, requireAuthenticationMethod, requireClaim, requireClient, requireGroup, requireOrganization, requirePermission, requireRole, requireScope, toForbiddenChallenge, toProblemDetails };
+export { AuthioBearerError, AuthioBearerErrorDescriptions, AuthioForbiddenError, AuthioUser, allOf, anyOf, authorize, createAuthioVerifier, createAuthioWebhooks, createForwardingFetch, createMemoryDeduplicationStore, createOnBehalfOf, createProtectedResourceMetadata, protectedResourceMetadataPath, protectedResourceMetadataUrl, readBearerToken, requireAuthenticationLevel, requireAuthenticationMethod, requireCallerKind, requireClaim, requireClient, requireGroup, requireOrganization, requirePermission, requireRecentAuthentication, requireRole, requireScope, toForbiddenChallenge, toProblemDetails };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map