@hyper.authio/server 0.1.1 → 0.8.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AuthioResourceAccess, AuthioResourceAccessSource, AuthioError, AuthioConnection, AuthioDiscoveryClient, AuthioClient, AuthioConnectionOptions, AuthioClientOptions, AuthioWebhookEvent, AuthioClock, AuthioWebhookDataByType, AuthioTypedWebhookEvent, AuthioClientCredentialsToken } from '@hyper.authio/client';
+import { AuthioCallerKind, AuthioCredentialForm, AuthioResourceAccess, AuthioIntrospectionResult, AuthioResourceAccessSource, AuthioClock, AuthioError, AuthioTokenFailure, AuthioConnection, AuthioDiscoveryClient, AuthioClient, AuthioConnectionOptions, AuthioClientOptions, AuthioEncryptionKeySource, AuthioWebhookEvent, AuthioWebhookDataByType, AuthioTypedWebhookEvent, AuthioClientCredentialsToken } from '@hyper.authio/client';
 
 /**
  * The party acting for the subject, from the `act` claim (RFC 8693): who exchanged the token, nested when the chain
@@ -7,8 +7,17 @@ import { AuthioResourceAccess, AuthioResourceAccessSource, AuthioError, AuthioCo
 interface AuthioActor {
     readonly clientId: string | undefined;
     readonly subject: string | undefined;
+    /** `name`, on an impersonation: the administrator's display name. */
+    readonly name: string | undefined;
     readonly actor: AuthioActor | undefined;
 }
+/**
+ * The administrator who impersonates the subject (an `act` with `sub` and no `client_id`).
+ */
+interface AuthioImpersonator {
+    readonly subject: string;
+    readonly name: string | undefined;
+}
 /**
  * Where the user reads flat (non-`*_resource_access`) roles and groups from.
  */
@@ -31,6 +40,41 @@ interface AuthioUserClaimSettings {
 declare class AuthioUser {
     /** `sub`: the person's id, or the credential's for a machine caller. */
     readonly subject: string;
+    /**
+     * 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).
+     */
+    readonly kind: AuthioCallerKind;
+    /**
+     * 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.
+     */
+    readonly credentialForm: AuthioCredentialForm | undefined;
+    /** `consumer_name`, for a consumer. */
+    readonly consumerName: string | undefined;
+    /** `credential_name`, for an account credential. */
+    readonly credentialName: string | undefined;
+    /** `owner_user_id`: the person who made the credential. */
+    readonly ownerUserId: string | undefined;
+    /**
+     * `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.
+     */
+    readonly ownerUsername: string | undefined;
+    /** `credential_realm`: the one realm an account credential is limited to. */
+    readonly credentialRealm: string | undefined;
+    /** `credential_client`: the one client an account credential is limited to. */
+    readonly credentialClient: string | undefined;
+    /** Whether an administrator impersonates the subject. */
+    readonly impersonated: boolean;
+    /** The administrator impersonating the subject. */
+    readonly impersonator: AuthioImpersonator | undefined;
+    /** Whether a client acts for the subject through a delegation (`act` with `client_id`). */
+    readonly delegated: boolean;
+    /** The clients acting for the subject, outermost first. */
+    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`). */
     readonly clientId: string | undefined;
     /** `sid`. */
@@ -86,10 +130,16 @@ declare class AuthioUser {
      * @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: Readonly<Record<string, unknown>>, settings?: AuthioUserClaimSettings, token?: string);
-    /** Whether an actor exchanged the token on the subject's behalf. */
-    get isDelegated(): boolean;
+    constructor(claims: Readonly<Record<string, unknown>>, settings?: AuthioUserClaimSettings, token?: string, source?: "token" | "introspection");
+    /**
+     * 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: AuthioIntrospectionResult, settings?: AuthioUserClaimSettings, token?: string): AuthioUser;
     /** Whether the scope was granted. */
     hasScope(scope: string): boolean;
     /**
@@ -138,6 +188,10 @@ interface AuthioRuleFailure {
     readonly error?: "insufficient_scope" | "insufficient_user_authentication";
     /** The required scopes, for `insufficient_scope`. */
     readonly scope?: string;
+    /** The context classes to ask for again, for `insufficient_user_authentication` (RFC 9470 `acr_values`). */
+    readonly acrValues?: string;
+    /** How old the sign-in may be, in seconds, for `insufficient_user_authentication` (RFC 9470 `max_age`). */
+    readonly maxAge?: number;
 }
 /**
  * A condition on the caller.
@@ -150,7 +204,8 @@ interface AuthioRule {
 }
 /**
  * Checks every rule. On refusal the message joins every rule's, and the error is the one asking for a stronger
- * sign-in, else the first one that has an error.
+ * 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.
  */
 declare function authorize(user: AuthioUser, ...rules: AuthioRule[]): AuthioRuleFailure | undefined;
 /**
@@ -184,13 +239,30 @@ declare function requireClaim(type: string, ...values: string[]): AuthioRule;
  */
 declare function requireOrganization(organization?: string): AuthioRule;
 /**
- * Requires a minimum authentication level (`acr`): 1 one factor, 2 several, 3 one of them phishing-resistant.
+ * Requires a minimum authentication level (`acr`): 1 one factor, 2 several, 3 one of them phishing-resistant. The
+ * refusal asks for that level again (`acr_values`), and for a sign-in at most `maxAge` seconds old when given.
+ */
+declare function requireAuthenticationLevel(minimumLevel: number, options?: {
+    maxAge?: number;
+    clock?: AuthioClock;
+}): AuthioRule;
+/**
+ * Requires authentication methods (`amr`, case-insensitive), such as `otp`, `swk` or `fed`. The refusal asks for the
+ * context class the methods imply (`2` for `mfa`/`otp`/`mca`, `3` for `swk`/`hwk`), or for `acrValues` when given.
  */
-declare function requireAuthenticationLevel(minimumLevel: number): AuthioRule;
+declare function requireAuthenticationMethod(methods: string | readonly string[], match?: AuthioMatch, options?: {
+    acrValues?: string;
+}): AuthioRule;
+/**
+ * Requires a sign-in at most `maxAge` seconds old (`auth_time`); the refusal asks for it with `max_age` (RFC 9470).
+ */
+declare function requireRecentAuthentication(maxAge: number, options?: {
+    clock?: AuthioClock;
+}): AuthioRule;
 /**
- * Requires authentication methods (`amr`, case-insensitive), such as `otp`, `swk` or `fed`.
+ * Requires the caller to be of one of the kinds: `user`, `client`, `consumer`, `account_credential`.
  */
-declare function requireAuthenticationMethod(methods: string | readonly string[], match?: AuthioMatch): AuthioRule;
+declare function requireCallerKind(kinds: AuthioCallerKind | readonly AuthioCallerKind[]): AuthioRule;
 /**
  * Requires the token to have been issued to one of the clients (`azp`, else `client_id`).
  */
@@ -213,10 +285,18 @@ declare class AuthioBearerError extends AuthioError {
     readonly error: "invalid_token" | undefined;
     /** Why the token was refused, safe to send to the caller. */
     readonly description: string | undefined;
+    /** Why the token was refused, as a stable code; `undefined` when there was no token or Authio could not be asked. */
+    readonly reason: AuthioTokenFailure | "inactive" | "unconfirmed" | undefined;
+    /** The API's protected resource metadata URL (RFC 9728), sent as `resource_metadata` when configured. */
+    readonly resourceMetadata: string | undefined;
     constructor(description: string | undefined, options?: {
         error?: "invalid_token" | undefined;
         cause?: unknown;
+        reason?: AuthioTokenFailure | "inactive" | "unconfirmed";
+        resourceMetadata?: string;
     });
+    /** The same refusal, pointing at the API's protected resource metadata. */
+    withResourceMetadata(resourceMetadata: string | undefined): AuthioBearerError;
     /** The `WWW-Authenticate` value. */
     get wwwAuthenticate(): string;
 }
@@ -231,8 +311,8 @@ declare class AuthioForbiddenError extends AuthioError {
     get wwwAuthenticate(): string | undefined;
 }
 /**
- * The `WWW-Authenticate` value of a refusal: `insufficient_scope` (with `scope`) or
- * `insufficient_user_authentication`.
+ * The `WWW-Authenticate` value of a refusal: `insufficient_scope` (with `scope`) or `insufficient_user_authentication`
+ * (with `acr_values` and `max_age`, RFC 9470).
  */
 declare function toForbiddenChallenge(failure: AuthioRuleFailure): string | undefined;
 /**
@@ -246,15 +326,27 @@ declare function toProblemDetails(error: AuthioBearerError | AuthioForbiddenErro
  * - `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) or encrypted tokens.
+ * - `introspectionOnly`: introspection alone, for opaque (reference) tokens, or encrypted ones without the key.
  */
 type AuthioIntrospectionMode = "none" | "activeCheck" | "introspectionOnly";
 /**
  * How an API validates Authio access tokens.
  */
 interface AuthioVerifierOptions extends AuthioConnectionOptions, AuthioUserClaimSettings {
-    /** The audiences this API accepts: its resource identifier (RFC 8707) or client id. Required. */
-    audiences: string | readonly string[];
+    /** The audiences this API accepts: its resource identifier (RFC 8707) or client id. Required unless `resource` is set. */
+    audiences?: string | readonly string[];
+    /**
+     * The API's own resource identifier (RFC 8707), such as `https://orders.example.com`. Added to `audiences`, and
+     * the `resource` of its protected resource metadata (RFC 9728).
+     */
+    resource?: string;
+    /**
+     * Points `401` challenges at the API's protected resource metadata (RFC 9728) with `resource_metadata`: `true`
+     * for `{origin of resource}/.well-known/oauth-protected-resource{path of resource}`, or the URL itself. Off by default.
+     */
+    resourceMetadata?: boolean | string;
+    /** Scopes every request must carry (all of them); `authioBearer` answers `403 insufficient_scope` otherwise. */
+    requiredScopes?: readonly string[];
     /** Defaults to `none`. */
     introspection?: AuthioIntrospectionMode;
     /**
@@ -267,10 +359,32 @@ 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;
+    /**
+     * The private half of the encryption key Authio encrypts this API's access tokens to (the resource server's or its
+     * client's), so encrypted tokens are decrypted and validated locally (RSA-OAEP, RSA-OAEP-256).
+     */
+    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;
 }
 /**
  * Validates Authio access tokens and reads the caller.
@@ -282,6 +396,12 @@ interface AuthioVerifier {
     readonly discovery: AuthioDiscoveryClient;
     /** The accepted audiences. */
     readonly audiences: readonly string[];
+    /** The API's resource identifier, when configured. */
+    readonly resource: string | undefined;
+    /** The protected resource metadata URL sent in challenges, when turned on. */
+    readonly resourceMetadataUrl: string | undefined;
+    /** Scopes every request must carry. */
+    readonly requiredScopes: readonly string[];
     /** The introspection mode. */
     readonly introspection: AuthioIntrospectionMode;
     /** The client used for introspection, when there is one. */
@@ -307,8 +427,9 @@ declare const AuthioBearerErrorDescriptions: {
     readonly 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.";
     readonly Unconfirmed: "Authio could not be reached to confirm that the token is active.";
     readonly Empty: "The token is empty.";
-    readonly Encrypted: "The token is encrypted; validate it with introspection ('introspectionOnly').";
+    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.
@@ -321,6 +442,48 @@ declare function createAuthioVerifier(options: AuthioVerifierOptions): AuthioVer
  */
 declare function readBearerToken(header: string | null | undefined): string | undefined;
 
+/**
+ * What an API publishes about itself as a protected resource (RFC 9728).
+ */
+interface AuthioProtectedResourceMetadataOptions extends Pick<AuthioConnectionOptions, "issuer" | "authority" | "realm"> {
+    /** The API's resource identifier (RFC 8707), such as `https://orders.example.com/api`. Required. */
+    resource: string;
+    /** Scopes a client can ask for to call the API. */
+    scopesSupported?: readonly string[];
+    /** A name to show to people. */
+    resourceName?: string;
+    /** A page documenting the API. */
+    resourceDocumentation?: string;
+    /** Further members, sent as given. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * The protected resource metadata document (RFC 9728 §2).
+ */
+interface AuthioProtectedResourceMetadata {
+    resource: string;
+    authorization_servers: string[];
+    bearer_methods_supported: string[];
+    scopes_supported?: string[];
+    resource_name?: string;
+    resource_documentation?: string;
+    [member: string]: unknown;
+}
+/**
+ * Where a resource's metadata is published: `{origin}/.well-known/oauth-protected-resource{path}` (RFC 9728 §3.1),
+ * the path being the resource's own, without a trailing slash.
+ */
+declare function protectedResourceMetadataUrl(resource: string): string;
+/**
+ * The path a resource's metadata is served at on the API itself: `/.well-known/oauth-protected-resource{path}`.
+ */
+declare function protectedResourceMetadataPath(resource: string): string;
+/**
+ * Builds the API's protected resource metadata: the resource, the realm's issuer as its authorization server, bearer
+ * tokens in the `Authorization` header, and the optional scopes, name and documentation.
+ */
+declare function createProtectedResourceMetadata(options: AuthioProtectedResourceMetadataOptions): AuthioProtectedResourceMetadata;
+
 /**
  * Remembers delivered event ids, so a redelivery is acknowledged without running the handlers twice.
  */
@@ -436,4 +599,4 @@ declare function createOnBehalfOf(options: {
     tokenRefreshSkew?: number;
 }): AuthioOnBehalfOf;
 
-export { type AuthioActor, AuthioBearerError, AuthioBearerErrorDescriptions, type AuthioDownstreamSubject, AuthioForbiddenError, type AuthioIntrospectionMode, type AuthioMatch, type AuthioOnBehalfOf, type AuthioRule, type AuthioRuleFailure, AuthioUser, type AuthioUserClaimSettings, type AuthioVerifier, type AuthioVerifierOptions, type AuthioWebhookDeduplicationStore, type AuthioWebhookHandler, type AuthioWebhookOptions, type AuthioWebhookOutcome, type AuthioWebhooks, allOf, anyOf, authorize, createAuthioVerifier, createAuthioWebhooks, createForwardingFetch, createMemoryDeduplicationStore, createOnBehalfOf, readBearerToken, requireAuthenticationLevel, requireAuthenticationMethod, requireClaim, requireClient, requireGroup, requireOrganization, requirePermission, requireRole, requireScope, toForbiddenChallenge, toProblemDetails };
+export { type AuthioActor, AuthioBearerError, AuthioBearerErrorDescriptions, type AuthioDownstreamSubject, AuthioForbiddenError, type AuthioImpersonator, type AuthioIntrospectionMode, type AuthioMatch, type AuthioOnBehalfOf, type AuthioProtectedResourceMetadata, type AuthioProtectedResourceMetadataOptions, type AuthioRule, type AuthioRuleFailure, AuthioUser, type AuthioUserClaimSettings, type AuthioVerifier, type AuthioVerifierOptions, type AuthioWebhookDeduplicationStore, type AuthioWebhookHandler, type AuthioWebhookOptions, type AuthioWebhookOutcome, type AuthioWebhooks, 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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AuthioResourceAccess, AuthioResourceAccessSource, AuthioError, AuthioConnection, AuthioDiscoveryClient, AuthioClient, AuthioConnectionOptions, AuthioClientOptions, AuthioWebhookEvent, AuthioClock, AuthioWebhookDataByType, AuthioTypedWebhookEvent, AuthioClientCredentialsToken } from '@hyper.authio/client';
+import { AuthioCallerKind, AuthioCredentialForm, AuthioResourceAccess, AuthioIntrospectionResult, AuthioResourceAccessSource, AuthioClock, AuthioError, AuthioTokenFailure, AuthioConnection, AuthioDiscoveryClient, AuthioClient, AuthioConnectionOptions, AuthioClientOptions, AuthioEncryptionKeySource, AuthioWebhookEvent, AuthioWebhookDataByType, AuthioTypedWebhookEvent, AuthioClientCredentialsToken } from '@hyper.authio/client';
 
 /**
  * The party acting for the subject, from the `act` claim (RFC 8693): who exchanged the token, nested when the chain
@@ -7,8 +7,17 @@ import { AuthioResourceAccess, AuthioResourceAccessSource, AuthioError, AuthioCo
 interface AuthioActor {
     readonly clientId: string | undefined;
     readonly subject: string | undefined;
+    /** `name`, on an impersonation: the administrator's display name. */
+    readonly name: string | undefined;
     readonly actor: AuthioActor | undefined;
 }
+/**
+ * The administrator who impersonates the subject (an `act` with `sub` and no `client_id`).
+ */
+interface AuthioImpersonator {
+    readonly subject: string;
+    readonly name: string | undefined;
+}
 /**
  * Where the user reads flat (non-`*_resource_access`) roles and groups from.
  */
@@ -31,6 +40,41 @@ interface AuthioUserClaimSettings {
 declare class AuthioUser {
     /** `sub`: the person's id, or the credential's for a machine caller. */
     readonly subject: string;
+    /**
+     * 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).
+     */
+    readonly kind: AuthioCallerKind;
+    /**
+     * 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.
+     */
+    readonly credentialForm: AuthioCredentialForm | undefined;
+    /** `consumer_name`, for a consumer. */
+    readonly consumerName: string | undefined;
+    /** `credential_name`, for an account credential. */
+    readonly credentialName: string | undefined;
+    /** `owner_user_id`: the person who made the credential. */
+    readonly ownerUserId: string | undefined;
+    /**
+     * `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.
+     */
+    readonly ownerUsername: string | undefined;
+    /** `credential_realm`: the one realm an account credential is limited to. */
+    readonly credentialRealm: string | undefined;
+    /** `credential_client`: the one client an account credential is limited to. */
+    readonly credentialClient: string | undefined;
+    /** Whether an administrator impersonates the subject. */
+    readonly impersonated: boolean;
+    /** The administrator impersonating the subject. */
+    readonly impersonator: AuthioImpersonator | undefined;
+    /** Whether a client acts for the subject through a delegation (`act` with `client_id`). */
+    readonly delegated: boolean;
+    /** The clients acting for the subject, outermost first. */
+    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`). */
     readonly clientId: string | undefined;
     /** `sid`. */
@@ -86,10 +130,16 @@ declare class AuthioUser {
      * @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: Readonly<Record<string, unknown>>, settings?: AuthioUserClaimSettings, token?: string);
-    /** Whether an actor exchanged the token on the subject's behalf. */
-    get isDelegated(): boolean;
+    constructor(claims: Readonly<Record<string, unknown>>, settings?: AuthioUserClaimSettings, token?: string, source?: "token" | "introspection");
+    /**
+     * 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: AuthioIntrospectionResult, settings?: AuthioUserClaimSettings, token?: string): AuthioUser;
     /** Whether the scope was granted. */
     hasScope(scope: string): boolean;
     /**
@@ -138,6 +188,10 @@ interface AuthioRuleFailure {
     readonly error?: "insufficient_scope" | "insufficient_user_authentication";
     /** The required scopes, for `insufficient_scope`. */
     readonly scope?: string;
+    /** The context classes to ask for again, for `insufficient_user_authentication` (RFC 9470 `acr_values`). */
+    readonly acrValues?: string;
+    /** How old the sign-in may be, in seconds, for `insufficient_user_authentication` (RFC 9470 `max_age`). */
+    readonly maxAge?: number;
 }
 /**
  * A condition on the caller.
@@ -150,7 +204,8 @@ interface AuthioRule {
 }
 /**
  * Checks every rule. On refusal the message joins every rule's, and the error is the one asking for a stronger
- * sign-in, else the first one that has an error.
+ * 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.
  */
 declare function authorize(user: AuthioUser, ...rules: AuthioRule[]): AuthioRuleFailure | undefined;
 /**
@@ -184,13 +239,30 @@ declare function requireClaim(type: string, ...values: string[]): AuthioRule;
  */
 declare function requireOrganization(organization?: string): AuthioRule;
 /**
- * Requires a minimum authentication level (`acr`): 1 one factor, 2 several, 3 one of them phishing-resistant.
+ * Requires a minimum authentication level (`acr`): 1 one factor, 2 several, 3 one of them phishing-resistant. The
+ * refusal asks for that level again (`acr_values`), and for a sign-in at most `maxAge` seconds old when given.
+ */
+declare function requireAuthenticationLevel(minimumLevel: number, options?: {
+    maxAge?: number;
+    clock?: AuthioClock;
+}): AuthioRule;
+/**
+ * Requires authentication methods (`amr`, case-insensitive), such as `otp`, `swk` or `fed`. The refusal asks for the
+ * context class the methods imply (`2` for `mfa`/`otp`/`mca`, `3` for `swk`/`hwk`), or for `acrValues` when given.
  */
-declare function requireAuthenticationLevel(minimumLevel: number): AuthioRule;
+declare function requireAuthenticationMethod(methods: string | readonly string[], match?: AuthioMatch, options?: {
+    acrValues?: string;
+}): AuthioRule;
+/**
+ * Requires a sign-in at most `maxAge` seconds old (`auth_time`); the refusal asks for it with `max_age` (RFC 9470).
+ */
+declare function requireRecentAuthentication(maxAge: number, options?: {
+    clock?: AuthioClock;
+}): AuthioRule;
 /**
- * Requires authentication methods (`amr`, case-insensitive), such as `otp`, `swk` or `fed`.
+ * Requires the caller to be of one of the kinds: `user`, `client`, `consumer`, `account_credential`.
  */
-declare function requireAuthenticationMethod(methods: string | readonly string[], match?: AuthioMatch): AuthioRule;
+declare function requireCallerKind(kinds: AuthioCallerKind | readonly AuthioCallerKind[]): AuthioRule;
 /**
  * Requires the token to have been issued to one of the clients (`azp`, else `client_id`).
  */
@@ -213,10 +285,18 @@ declare class AuthioBearerError extends AuthioError {
     readonly error: "invalid_token" | undefined;
     /** Why the token was refused, safe to send to the caller. */
     readonly description: string | undefined;
+    /** Why the token was refused, as a stable code; `undefined` when there was no token or Authio could not be asked. */
+    readonly reason: AuthioTokenFailure | "inactive" | "unconfirmed" | undefined;
+    /** The API's protected resource metadata URL (RFC 9728), sent as `resource_metadata` when configured. */
+    readonly resourceMetadata: string | undefined;
     constructor(description: string | undefined, options?: {
         error?: "invalid_token" | undefined;
         cause?: unknown;
+        reason?: AuthioTokenFailure | "inactive" | "unconfirmed";
+        resourceMetadata?: string;
     });
+    /** The same refusal, pointing at the API's protected resource metadata. */
+    withResourceMetadata(resourceMetadata: string | undefined): AuthioBearerError;
     /** The `WWW-Authenticate` value. */
     get wwwAuthenticate(): string;
 }
@@ -231,8 +311,8 @@ declare class AuthioForbiddenError extends AuthioError {
     get wwwAuthenticate(): string | undefined;
 }
 /**
- * The `WWW-Authenticate` value of a refusal: `insufficient_scope` (with `scope`) or
- * `insufficient_user_authentication`.
+ * The `WWW-Authenticate` value of a refusal: `insufficient_scope` (with `scope`) or `insufficient_user_authentication`
+ * (with `acr_values` and `max_age`, RFC 9470).
  */
 declare function toForbiddenChallenge(failure: AuthioRuleFailure): string | undefined;
 /**
@@ -246,15 +326,27 @@ declare function toProblemDetails(error: AuthioBearerError | AuthioForbiddenErro
  * - `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) or encrypted tokens.
+ * - `introspectionOnly`: introspection alone, for opaque (reference) tokens, or encrypted ones without the key.
  */
 type AuthioIntrospectionMode = "none" | "activeCheck" | "introspectionOnly";
 /**
  * How an API validates Authio access tokens.
  */
 interface AuthioVerifierOptions extends AuthioConnectionOptions, AuthioUserClaimSettings {
-    /** The audiences this API accepts: its resource identifier (RFC 8707) or client id. Required. */
-    audiences: string | readonly string[];
+    /** The audiences this API accepts: its resource identifier (RFC 8707) or client id. Required unless `resource` is set. */
+    audiences?: string | readonly string[];
+    /**
+     * The API's own resource identifier (RFC 8707), such as `https://orders.example.com`. Added to `audiences`, and
+     * the `resource` of its protected resource metadata (RFC 9728).
+     */
+    resource?: string;
+    /**
+     * Points `401` challenges at the API's protected resource metadata (RFC 9728) with `resource_metadata`: `true`
+     * for `{origin of resource}/.well-known/oauth-protected-resource{path of resource}`, or the URL itself. Off by default.
+     */
+    resourceMetadata?: boolean | string;
+    /** Scopes every request must carry (all of them); `authioBearer` answers `403 insufficient_scope` otherwise. */
+    requiredScopes?: readonly string[];
     /** Defaults to `none`. */
     introspection?: AuthioIntrospectionMode;
     /**
@@ -267,10 +359,32 @@ 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;
+    /**
+     * The private half of the encryption key Authio encrypts this API's access tokens to (the resource server's or its
+     * client's), so encrypted tokens are decrypted and validated locally (RSA-OAEP, RSA-OAEP-256).
+     */
+    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;
 }
 /**
  * Validates Authio access tokens and reads the caller.
@@ -282,6 +396,12 @@ interface AuthioVerifier {
     readonly discovery: AuthioDiscoveryClient;
     /** The accepted audiences. */
     readonly audiences: readonly string[];
+    /** The API's resource identifier, when configured. */
+    readonly resource: string | undefined;
+    /** The protected resource metadata URL sent in challenges, when turned on. */
+    readonly resourceMetadataUrl: string | undefined;
+    /** Scopes every request must carry. */
+    readonly requiredScopes: readonly string[];
     /** The introspection mode. */
     readonly introspection: AuthioIntrospectionMode;
     /** The client used for introspection, when there is one. */
@@ -307,8 +427,9 @@ declare const AuthioBearerErrorDescriptions: {
     readonly 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.";
     readonly Unconfirmed: "Authio could not be reached to confirm that the token is active.";
     readonly Empty: "The token is empty.";
-    readonly Encrypted: "The token is encrypted; validate it with introspection ('introspectionOnly').";
+    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.
@@ -321,6 +442,48 @@ declare function createAuthioVerifier(options: AuthioVerifierOptions): AuthioVer
  */
 declare function readBearerToken(header: string | null | undefined): string | undefined;
 
+/**
+ * What an API publishes about itself as a protected resource (RFC 9728).
+ */
+interface AuthioProtectedResourceMetadataOptions extends Pick<AuthioConnectionOptions, "issuer" | "authority" | "realm"> {
+    /** The API's resource identifier (RFC 8707), such as `https://orders.example.com/api`. Required. */
+    resource: string;
+    /** Scopes a client can ask for to call the API. */
+    scopesSupported?: readonly string[];
+    /** A name to show to people. */
+    resourceName?: string;
+    /** A page documenting the API. */
+    resourceDocumentation?: string;
+    /** Further members, sent as given. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * The protected resource metadata document (RFC 9728 §2).
+ */
+interface AuthioProtectedResourceMetadata {
+    resource: string;
+    authorization_servers: string[];
+    bearer_methods_supported: string[];
+    scopes_supported?: string[];
+    resource_name?: string;
+    resource_documentation?: string;
+    [member: string]: unknown;
+}
+/**
+ * Where a resource's metadata is published: `{origin}/.well-known/oauth-protected-resource{path}` (RFC 9728 §3.1),
+ * the path being the resource's own, without a trailing slash.
+ */
+declare function protectedResourceMetadataUrl(resource: string): string;
+/**
+ * The path a resource's metadata is served at on the API itself: `/.well-known/oauth-protected-resource{path}`.
+ */
+declare function protectedResourceMetadataPath(resource: string): string;
+/**
+ * Builds the API's protected resource metadata: the resource, the realm's issuer as its authorization server, bearer
+ * tokens in the `Authorization` header, and the optional scopes, name and documentation.
+ */
+declare function createProtectedResourceMetadata(options: AuthioProtectedResourceMetadataOptions): AuthioProtectedResourceMetadata;
+
 /**
  * Remembers delivered event ids, so a redelivery is acknowledged without running the handlers twice.
  */
@@ -436,4 +599,4 @@ declare function createOnBehalfOf(options: {
     tokenRefreshSkew?: number;
 }): AuthioOnBehalfOf;
 
-export { type AuthioActor, AuthioBearerError, AuthioBearerErrorDescriptions, type AuthioDownstreamSubject, AuthioForbiddenError, type AuthioIntrospectionMode, type AuthioMatch, type AuthioOnBehalfOf, type AuthioRule, type AuthioRuleFailure, AuthioUser, type AuthioUserClaimSettings, type AuthioVerifier, type AuthioVerifierOptions, type AuthioWebhookDeduplicationStore, type AuthioWebhookHandler, type AuthioWebhookOptions, type AuthioWebhookOutcome, type AuthioWebhooks, allOf, anyOf, authorize, createAuthioVerifier, createAuthioWebhooks, createForwardingFetch, createMemoryDeduplicationStore, createOnBehalfOf, readBearerToken, requireAuthenticationLevel, requireAuthenticationMethod, requireClaim, requireClient, requireGroup, requireOrganization, requirePermission, requireRole, requireScope, toForbiddenChallenge, toProblemDetails };
+export { type AuthioActor, AuthioBearerError, AuthioBearerErrorDescriptions, type AuthioDownstreamSubject, AuthioForbiddenError, type AuthioImpersonator, type AuthioIntrospectionMode, type AuthioMatch, type AuthioOnBehalfOf, type AuthioProtectedResourceMetadata, type AuthioProtectedResourceMetadataOptions, type AuthioRule, type AuthioRuleFailure, AuthioUser, type AuthioUserClaimSettings, type AuthioVerifier, type AuthioVerifierOptions, type AuthioWebhookDeduplicationStore, type AuthioWebhookHandler, type AuthioWebhookOptions, type AuthioWebhookOutcome, type AuthioWebhooks, 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 };