@hyper.authio/client 0.1.1 → 0.8.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { JWK, CryptoKey } from 'jose';
+import { JWK, CryptoKey, JWTPayload, JWTVerifyGetKey } from 'jose';
 
 /**
  * Claim names Authio writes into its tokens.
@@ -20,6 +20,8 @@ declare const AuthioClaimTypes: {
     readonly AuthenticationMethods: "amr";
     readonly IdentityProvider: "idp";
     readonly Nonce: "nonce";
+    readonly AccessTokenHash: "at_hash";
+    readonly Events: "events";
     readonly OrganizationId: "org_id";
     readonly OrganizationAlias: "org_alias";
     readonly AccountId: "account_id";
@@ -39,6 +41,12 @@ declare const AuthioClaimTypes: {
     readonly ConsumerName: "consumer_name";
     readonly CredentialId: "credential_id";
     readonly CredentialType: "credential_type";
+    readonly CredentialName: "credential_name";
+    readonly CredentialRealm: "credential_realm";
+    readonly CredentialClient: "credential_client";
+    readonly ActorType: "actor_type";
+    readonly OwnerUserId: "owner_user_id";
+    readonly OwnerUsername: "owner_username";
     readonly UserResourceAccess: "user_resource_access";
     readonly RealmResourceAccess: "realm_resource_access";
     readonly ClientResourceAccess: "client_resource_access";
@@ -116,6 +124,12 @@ declare const AuthioOAuthErrors: {
     readonly ConnectionPolicyViolation: "connection_policy_violation";
     readonly ServerError: "server_error";
     readonly TemporarilyUnavailable: "temporarily_unavailable";
+    readonly LoginRequired: "login_required";
+    readonly InteractionRequired: "interaction_required";
+    readonly ConsentRequired: "consent_required";
+    readonly AccountSelectionRequired: "account_selection_required";
+    readonly InsufficientScope: "insufficient_scope";
+    readonly InsufficientUserAuthentication: "insufficient_user_authentication";
 };
 /**
  * Webhook event types.
@@ -135,6 +149,8 @@ declare const AuthioWebhookEventTypes: {
     readonly AdminResourceDeleted: "admin_resource_deleted";
     readonly UserSuspended: "user_suspended";
     readonly UserSuspensionEnded: "user_suspension_ended";
+    readonly AttackDetected: "attack_detected";
+    readonly CredentialCompromised: "credential_compromised";
     readonly Ping: "ping";
 };
 /**
@@ -145,21 +161,67 @@ declare const AuthioWebhookHeaders: {
     readonly Event: "X-Authio-Event";
     readonly EventId: "X-Authio-Event-Id";
 };
+/**
+ * Who called an API, read from the access token (see `conformance/callers.json`).
+ *
+ * - `user`: a person signed in (the token carries `auth_time`).
+ * - `client`: a client authenticated as itself.
+ * - `consumer`: a machine consumer of a client (`credential_type` `client_consumer`).
+ * - `account_credential`: a credential of an Authio account (`credential_type` `account_secret`).
+ */
+type AuthioCallerKind = "user" | "client" | "consumer" | "account_credential";
+/**
+ * How a machine caller proved who it is.
+ */
+type AuthioCredentialForm = "client_secret" | "personal_access_token" | "api_key" | "consumer_api_key";
+/**
+ * The caller kinds.
+ */
+declare const AuthioCallerKinds: readonly ["user", "client", "consumer", "account_credential"];
+/**
+ * The values of `prompt` Authio honours.
+ */
+declare const AuthioPrompts: readonly ["none", "login", "select_account", "consent"];
+/**
+ * A value of `prompt`.
+ */
+type AuthioPrompt = (typeof AuthioPrompts)[number];
 /**
  * Asymmetric signing algorithms Authio issues tokens with and accepts in client assertions.
  */
 declare const AuthioAsymmetricAlgorithms: readonly ["RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512"];
+/**
+ * Symmetric algorithms Authio may sign a client's tokens with. A client verifies them with its own client secret
+ * (OpenID Connect Core §10.1), and only when `idTokenSignedResponseAlg` names one.
+ */
+declare const AuthioHmacAlgorithms: readonly ["HS256", "HS384", "HS512"];
+/**
+ * The shortest client secret, in bytes of its UTF-8 form, each HS* algorithm is verified with: the size of the hash
+ * output (RFC 7518 §3.2). Authio refuses a shorter secret for the algorithm, and so do the SDKs.
+ */
+declare const AuthioHmacMinimumSecretBytes: Readonly<Record<(typeof AuthioHmacAlgorithms)[number], number>>;
 /**
  * Defaults shared by every Authio SDK.
  */
 declare const AuthioDefaults: {
     readonly DiscoveryPath: "/.well-known/openid-configuration";
+    readonly ProtectedResourceMetadataPath: "/.well-known/oauth-protected-resource";
     readonly RedactedValue: "[redacted]";
     readonly PlatformRealm: "authio";
     readonly PlatformClientId: "authio";
     readonly ApiKeyPrefix: "ak_";
     readonly ClientSecretPrefix: "cs_";
     readonly PersonalAccessTokenPrefix: "pat_";
+    /** The `client_id` an account credential's client secret is exchanged with: `cred_` and the credential id (format N). */
+    readonly CredentialClientIdPrefix: "cred_";
+    readonly ApiKeyHeader: "x-api-key";
+    readonly RequestIdHeader: "X-Request-Id";
+    /** The header `typ` of a back-channel logout token. */
+    readonly LogoutTokenType: "logout+jwt";
+    /** The event a back-channel logout token carries. */
+    readonly BackchannelLogoutEvent: "http://schemas.openid.net/event/backchannel-logout";
+    /** Seconds. */
+    readonly ClockSkew: 30;
     /** Seconds. */
     readonly ClientAssertionLifetime: 120;
     /** Seconds. */
@@ -220,6 +282,65 @@ declare class AuthioDiscoveryError extends AuthioError {
  */
 declare class AuthioConfigurationError extends AuthioError {
 }
+/**
+ * Why a token was refused, with the outcome names of `conformance/tokens.json`.
+ */
+type AuthioTokenFailure = "not_access_token" | "not_id_token" | "invalid_audience" | "invalid_issuer" | "expired" | "not_yet_valid" | "invalid_signature" | "invalid_algorithm" | "reference_token" | "malformed" | "decryption_failed" | "legacy_algorithm" | "invalid_nonce" | "invalid_at_hash" | "authentication_too_old" | "invalid_logout_token" | "signing_keys_unavailable";
+/**
+ * A token (ID token, logout token, signed UserInfo, encrypted token) did not pass validation.
+ */
+declare class AuthioTokenValidationError extends AuthioError {
+    /** Why, as a stable code. */
+    readonly reason: AuthioTokenFailure;
+    constructor(reason: AuthioTokenFailure, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Why an authorization callback was refused before any code was exchanged.
+ */
+type AuthioCallbackFailure = "state_mismatch" | "issuer_mismatch" | "missing_issuer" | "missing_code";
+/**
+ * The authorization callback does not belong to the request this client made: `state` differs, the `iss` parameter
+ * (RFC 9207) names another issuer or is missing where Authio sends it, or there is no code.
+ */
+declare class AuthioCallbackError extends AuthioError {
+    /** Why, as a stable code. */
+    readonly reason: AuthioCallbackFailure;
+    constructor(reason: AuthioCallbackFailure, message: string);
+}
+/**
+ * One message of an Admin API error, optionally tied to a field of the request.
+ */
+interface AuthioAdminNotification {
+    readonly message: string;
+    readonly field?: string;
+    readonly code?: string;
+}
+/**
+ * The Admin API refused a request. `errorCode` is the envelope's top-level `errorCode`; the HTTP status is read from
+ * the response, never from the envelope's numeric `statusCode`.
+ */
+declare class AuthioAdminError extends AuthioError {
+    /** The HTTP status. */
+    readonly status: number;
+    /** Authio's error code, such as `ValidationFailed` or `RealmNotFound`. */
+    readonly errorCode: string | undefined;
+    /** The messages, with the field each one is about. */
+    readonly notifications: readonly AuthioAdminNotification[];
+    /** The request id, from the envelope or the `X-Request-Id` header. */
+    readonly requestId: string | undefined;
+    /** Seconds to wait before retrying, from `Retry-After` (`429` and `503`). */
+    readonly retryAfterSeconds: number | undefined;
+    constructor(details: {
+        status: number;
+        errorCode?: string;
+        notifications?: readonly AuthioAdminNotification[];
+        requestId?: string;
+        retryAfterSeconds?: number;
+        cause?: unknown;
+    });
+}
 
 /**
  * Time as the SDK sees it. Replace it in tests to control expiry, caching and device polling.
@@ -235,7 +356,7 @@ interface AuthioClock {
  */
 declare const systemClock: AuthioClock;
 /**
- * Where Authio is and how to reach it. Shared by the client, the API verifier and the BFF.
+ * Where Authio is and how to reach it. Shared by the client and the API verifier.
  */
 interface AuthioConnectionOptions {
     /**
@@ -262,9 +383,14 @@ interface AuthioConnectionOptions {
     clock?: AuthioClock;
 }
 /**
- * How the client authenticates to the token, introspection, revocation and device endpoints.
+ * How the client authenticates to the token, introspection, revocation and device endpoints: the client's
+ * `token_endpoint_auth_method` in Authio, which Authio matches exactly.
  */
-type AuthioClientAuthentication = "client_secret_basic" | "client_secret_post" | "private_key_jwt" | "none";
+type AuthioTokenEndpointAuthMethod = "client_secret_basic" | "client_secret_post" | "private_key_jwt" | "none";
+/**
+ * The values of `tokenEndpointAuthMethod`.
+ */
+declare const AuthioTokenEndpointAuthMethods: readonly ["client_secret_basic", "client_secret_post", "private_key_jwt", "none"];
 /**
  * The connection settings, resolved once.
  */
@@ -324,6 +450,7 @@ interface AuthioDiscoveryDocument {
     grant_types_supported?: string[];
     subject_types_supported?: string[];
     id_token_signing_alg_values_supported?: string[];
+    userinfo_signing_alg_values_supported?: string[];
     token_endpoint_auth_methods_supported?: string[];
     token_endpoint_auth_signing_alg_values_supported?: string[];
     introspection_endpoint_auth_methods_supported?: string[];
@@ -332,6 +459,8 @@ interface AuthioDiscoveryDocument {
     claims_supported?: string[];
     prompt_values_supported?: string[];
     authorization_response_iss_parameter_supported?: boolean;
+    frontchannel_logout_supported?: boolean;
+    frontchannel_logout_session_supported?: boolean;
     [member: string]: unknown;
 }
 /**
@@ -387,19 +516,27 @@ type AuthioPrivateKeyInput = string | JWK | CryptoKey;
  */
 declare const AuthioClientAssertionAlgorithms: readonly ["RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512"];
 
+/**
+ * The client secret, or a function returning the current one, called for every request so a rotated secret is used
+ * without a restart.
+ */
+type AuthioSecretSource = string | (() => string | Promise<string>);
 /**
  * How the client proves who it is.
  */
 interface AuthioClientCredentialsSettings {
     /** The client id. */
     clientId: string;
-    /** The client secret, for `client_secret_basic` and `client_secret_post`. */
-    clientSecret?: string;
     /**
-     * Defaults to `private_key_jwt` when only a private key is configured, else `client_secret_basic`. A public client
-     * sets `none`.
+     * The client secret, for `client_secret_basic` and `client_secret_post`; or a function returning the current one,
+     * called for every request.
      */
-    clientAuthentication?: AuthioClientAuthentication;
+    clientSecret?: AuthioSecretSource;
+    /**
+     * How the client authenticates, as registered in Authio (which matches it exactly). Defaults to
+     * `client_secret_basic` with a `clientSecret`, `private_key_jwt` with only a private key, and `none` with neither.
+     */
+    tokenEndpointAuthMethod?: AuthioTokenEndpointAuthMethod;
     /** The private key for `private_key_jwt`. */
     clientPrivateKey?: AuthioPrivateKeyInput;
     /** A PEM file holding the private key for `private_key_jwt` (Node only); re-read when it changes. */
@@ -421,18 +558,54 @@ declare function toBasicAuthorization(clientId: string, clientSecret: string): s
  * Authio hands over when it generates the pair (object or JSON text), or a PEM private key (PKCS#8 or PKCS#1 RSA).
  */
 type AuthioEncryptionKey = string | JWK;
+/**
+ * Where the encryption key comes from: the key itself, or a function returning it (read again on every new
+ * algorithm, so a rotated key is picked up).
+ */
+type AuthioEncryptionKeySource = AuthioEncryptionKey | (() => AuthioEncryptionKey | Promise<AuthioEncryptionKey>);
 /**
  * Opens a compact JWE and returns its plaintext; a token that is not a JWE comes back unchanged.
+ *
+ * @throws AuthioTokenValidationError with `legacy_algorithm` for RSA1_5 and `decryption_failed` when the key cannot
+ * open it.
  */
 type AuthioTokenDecrypter = (token: string) => Promise<string>;
 /**
- * The key management algorithms Authio encrypts with.
+ * The key management algorithms Authio encrypts with, and this SDK decrypts.
  */
 declare const AuthioKeyManagementAlgorithms: readonly ["RSA-OAEP", "RSA-OAEP-256"];
 /**
- * The content encryption algorithms Authio encrypts with.
+ * Key management algorithms Authio may still use for clients registered long ago. Node and WebCrypto cannot decrypt
+ * RSA1_5 (PKCS#1 v1.5), so this SDK refuses it even with `allowLegacyEncryptionAlgorithms`.
+ */
+declare const AuthioLegacyKeyManagementAlgorithms: readonly ["RSA1_5"];
+/**
+ * The content encryption algorithms Authio encrypts with to a client's own key, the default `encryptionMethods`.
  */
 declare const AuthioContentEncryptionAlgorithms: readonly ["A128CBC-HS256", "A192CBC-HS384", "A256CBC-HS512"];
+/**
+ * Every content encryption algorithm `encryptionMethods` may list: the CBC-HS ones and AES-GCM.
+ */
+declare const AuthioSupportedContentEncryptionAlgorithms: readonly ["A128CBC-HS256", "A192CBC-HS384", "A256CBC-HS512", "A128GCM", "A192GCM", "A256GCM"];
+/**
+ * Options of the decrypter.
+ */
+interface AuthioTokenDecrypterOptions {
+    /** The setting the key came from, named in errors. Defaults to `clientEncryptionKey`. */
+    setting?: string;
+    /**
+     * Accepted for parity with the other Authio SDKs. RSA1_5 stays refused here, with an error saying so, because
+     * neither Node nor WebCrypto can decrypt PKCS#1 v1.5.
+     */
+    allowLegacyEncryptionAlgorithms?: boolean;
+    /**
+     * The key management algorithms (`alg`) accepted, as registered for the client in Authio. Defaults to RSA-OAEP and
+     * RSA-OAEP-256. RSA1_5 cannot be listed: neither Node nor WebCrypto can decrypt it.
+     */
+    encryptionAlgorithms?: readonly string[];
+    /** The content encryption algorithms (`enc`) accepted. Defaults to A128CBC-HS256, A192CBC-HS384 and A256CBC-HS512. */
+    encryptionMethods?: readonly string[];
+}
 /**
  * Whether a value is a compact JWE (five segments).
  */
@@ -440,10 +613,249 @@ declare function isAuthioTokenEncrypted(token: unknown): token is string;
 /**
  * Creates a decrypter for the client's own encryption key. Keys are imported once per algorithm.
  *
- * @param key The key, or `undefined` when none is configured: an encrypted token then throws.
- * @param setting The setting the key came from, named in errors.
+ * @param key The key, a function returning it, or `undefined` when none is configured: an encrypted token then throws.
+ * @param options The setting name for errors, and the legacy algorithm switch. A string is taken as the setting name.
+ */
+declare function createAuthioTokenDecrypter(key: AuthioEncryptionKeySource | undefined, options?: AuthioTokenDecrypterOptions | string): AuthioTokenDecrypter;
+/**
+ * Reads the client's encryption key from a PEM or JWK file (Node only), again whenever the file changes.
+ *
+ * @internal
+ */
+declare function encryptionKeyFromFile(path: string, setting?: string): () => Promise<AuthioEncryptionKey>;
+
+/**
+ * The claims of a validated ID token. Authio writes `typ` = `ID`, `sid`, `auth_time`, `acr`, `amr`, `nonce` and
+ * `at_hash`, besides the profile claims of the granted scopes.
+ */
+interface AuthioIdTokenClaims extends JWTPayload {
+    sub: string;
+    sid?: string;
+    nonce?: string;
+    auth_time?: number;
+    acr?: string;
+    amr?: string[];
+    at_hash?: string;
+    [claim: string]: unknown;
+}
+/**
+ * A validated back-channel logout token: end the sessions of `subject`, or the one session `sessionId` names.
+ */
+interface AuthioLogoutToken {
+    /** `sub`, when the token names the person. */
+    readonly subject: string | undefined;
+    /** `sid`, when the token names one session. */
+    readonly sessionId: string | undefined;
+    /** `jti`. */
+    readonly tokenId: string | undefined;
+    /** Every claim. */
+    readonly claims: Readonly<JWTPayload>;
+}
+/**
+ * The realm's signing keys, read from the discovery document's `jwks_uri` and cached; an unknown `kid` makes it read
+ * them again (at most once every 30 seconds).
+ *
+ * @internal
+ */
+type AuthioSigningKeys = (signal?: AbortSignal) => Promise<JWTVerifyGetKey>;
+/**
+ * What a JWT is checked against.
+ *
+ * @internal
+ */
+interface AuthioJwtExpectations {
+    readonly issuer: string;
+    /** The accepted audiences; `aud` is not checked when absent. */
+    readonly audiences?: readonly string[];
+    readonly algorithms?: readonly string[];
+    /** Seconds. */
+    readonly clockSkew?: number;
+    /** Milliseconds since the epoch. */
+    readonly now: number;
+    readonly requiredClaims?: readonly string[];
+}
+/**
+ * Creates the cached reader of the realm's signing keys.
+ *
+ * @internal
  */
-declare function createAuthioTokenDecrypter(key: AuthioEncryptionKey | undefined, setting?: string): AuthioTokenDecrypter;
+declare function createAuthioSigningKeys(connection: AuthioConnection, discovery: AuthioDiscoveryClient): AuthioSigningKeys;
+/**
+ * Verifies a signed JWT: signature by a realm key with an accepted algorithm, `iss`, `aud`, `exp` (required) and
+ * `nbf` with the clock skew.
+ *
+ * @throws AuthioTokenValidationError naming why the token was refused.
+ * @internal
+ */
+declare function verifyAuthioJwt(token: string, keys: JWTVerifyGetKey, expected: AuthioJwtExpectations): Promise<{
+    payload: JWTPayload;
+    header: Record<string, unknown>;
+}>;
+/**
+ * Wraps the realm's keys so an HS256, HS384 or HS512 signature is verified with the client secret instead (OpenID
+ * Connect Core §10.1: the octets of its UTF-8 form). Only reached for an algorithm the allowlist accepts, so an HS*
+ * token is verified with the secret only when `idTokenSignedResponseAlg` names that algorithm.
+ *
+ * @internal
+ */
+declare function withClientSecret(keys: JWTVerifyGetKey, secret: (() => Promise<string>) | undefined): JWTVerifyGetKey;
+/**
+ * Refuses a client secret shorter than the HS* algorithm's hash output (RFC 7518 §3.2).
+ *
+ * @throws AuthioConfigurationError naming the algorithm and both lengths.
+ * @internal
+ */
+declare function requireHmacSecretLength(algorithm: string, length: number): void;
+/**
+ * Turns a `jose` failure into the refusal it stands for, worded as ASP.NET Core's bearer handler words it.
+ *
+ * @internal
+ */
+declare function toTokenValidationError(error: unknown, audiences: readonly string[], token: string): AuthioTokenValidationError;
+/**
+ * The `at_hash` / `c_hash` of a value for a signing algorithm: the left half of its SHA-256, SHA-384 or SHA-512
+ * digest, base64url-encoded (OpenID Connect Core §3.1.3.6).
+ */
+declare function computeAuthioTokenHash(value: string, algorithm: string): Promise<string>;
+
+/**
+ * The PKCE method (RFC 7636). `S256` is the default; `plain` only when asked for, for a client that cannot hash.
+ */
+type AuthioCodeChallengeMethod = "S256" | "plain";
+/**
+ * What the client checks on an authorization round trip, as the client is registered in Authio: `pkce` sends a code
+ * challenge and redeems the code with its verifier, `state` binds the callback to the request, `nonce` binds the ID
+ * token to it. `none` is the same as an empty list. Nothing is checked unless listed.
+ */
+type AuthioCheck = "pkce" | "state" | "nonce" | "none";
+/**
+ * How Authio answers the authorization request: `query` (a redirect) or `web_message` (posted to the opener window).
+ */
+type AuthioResponseMode = "query" | "web_message";
+/**
+ * The checks every Authio library accepts.
+ */
+declare const AuthioChecks: readonly ["pkce", "state", "nonce", "none"];
+/**
+ * A PKCE pair: send `codeChallenge` with the authorization request and `codeVerifier` with the code exchange.
+ */
+interface AuthioPkcePair {
+    readonly codeVerifier: string;
+    readonly codeChallenge: string;
+    readonly codeChallengeMethod: AuthioCodeChallengeMethod;
+}
+/**
+ * What an authorization request asks Authio for. Every member is optional; `redirectUri` falls back to the client's.
+ */
+interface AuthioAuthorizationRequest {
+    /** Where Authio sends the person back. Defaults to the client's `redirectUri`. */
+    redirectUri?: string;
+    /** Defaults to `openid`. */
+    scopes?: Iterable<string> | string;
+    /** The resource server the access token is for (RFC 8707). */
+    resource?: string;
+    /** The organization (its handle) the sign-in is for. Authoritative: the person cannot switch to another one. */
+    organization?: string;
+    /** `none` (silent), `login`, `select_account`, `consent`; several are joined with spaces. */
+    prompt?: AuthioPrompt | readonly AuthioPrompt[];
+    /** Seconds the person's sign-in may be old; Authio asks again past it, and the ID token's `auth_time` is checked. */
+    maxAge?: number;
+    /** Authentication context classes asked for: `1` one factor, `2` several, `3` one of them phishing-resistant. */
+    acrValues?: string | readonly string[];
+    /** Pre-fills the identifier on the sign-in screen. */
+    loginHint?: string;
+    /** A previously issued ID token, naming the person whose session is renewed. */
+    idTokenHint?: string;
+    /** Languages of the hosted screens, most preferred first. */
+    uiLocales?: string | readonly string[];
+    /** `page` (default) or `popup`, the layout of the hosted screens. */
+    display?: "page" | "popup";
+    /** `query` or `web_message` (the answer posted to the opener window). Defaults to the client's `responseMode`. */
+    responseMode?: AuthioResponseMode;
+    /** Shorthand for `display: "popup"` with `responseMode: "web_message"`. */
+    popup?: boolean;
+    /** The alias of the identity provider to go straight to, skipping Authio's sign-in screen. */
+    idpHint?: string;
+    /** The checks of this request. Defaults to the client's `checks`. */
+    checks?: readonly AuthioCheck[];
+    /** The PKCE method, when `checks` holds `pkce`. Defaults to the client's `codeChallengeMethod`, else `S256`. */
+    codeChallengeMethod?: AuthioCodeChallengeMethod;
+    /** A `state` of your own for the `state` check (a random one otherwise); without the check it is sent unchecked. */
+    state?: string;
+    /** A `nonce` of your own for the `nonce` check (a random one otherwise); without the check it is sent unchecked. */
+    nonce?: string;
+    /** Further parameters, sent as given. */
+    extraParameters?: Record<string, string | undefined>;
+}
+/**
+ * What the application keeps between the authorization request and the callback (in its session, a cookie, …), to
+ * check the callback and redeem the code.
+ */
+interface AuthioAuthorizationTransaction {
+    /** The checks the request was made with; the callback checks exactly these. */
+    readonly checks: readonly Exclude<AuthioCheck, "none">[];
+    /** With the `state` check. */
+    readonly state?: string;
+    /** With the `nonce` check. */
+    readonly nonce?: string;
+    /** With the `pkce` check. */
+    readonly codeVerifier?: string;
+    /** With the `pkce` check. */
+    readonly codeChallengeMethod?: AuthioCodeChallengeMethod;
+    readonly redirectUri: string;
+    readonly resource?: string;
+    readonly maxAge?: number;
+}
+/**
+ * An authorization URL and the transaction to keep until the callback.
+ */
+interface AuthioAuthorizationUrl {
+    readonly url: string;
+    readonly transaction: AuthioAuthorizationTransaction;
+}
+/**
+ * A `WWW-Authenticate` bearer challenge, as an API answers it (RFC 6750, RFC 9470, RFC 9728).
+ */
+interface AuthioBearerChallenge {
+    readonly error: string | undefined;
+    readonly errorDescription: string | undefined;
+    /** `insufficient_scope`: the scopes required. */
+    readonly scope: string | undefined;
+    /** `insufficient_user_authentication`: the context classes to ask for. */
+    readonly acrValues: string | undefined;
+    /** `insufficient_user_authentication`: how old the sign-in may be, in seconds. */
+    readonly maxAge: number | undefined;
+    /** RFC 9728: where the API's protected resource metadata is. */
+    readonly resourceMetadata: string | undefined;
+}
+/**
+ * Creates a PKCE pair: a 256-bit random verifier and its S256 (or plain) challenge.
+ */
+declare function createAuthioPkce(method?: AuthioCodeChallengeMethod): Promise<AuthioPkcePair>;
+/**
+ * A random, URL-safe value of `bytes` random bytes, for `state` and `nonce`.
+ */
+declare function randomValue(bytes?: number): string;
+/**
+ * A front-channel logout request (OpenID Connect Front-Channel Logout 1.0): Authio loads the client's
+ * `frontchannel_logout_uri` in an iframe, with `iss` and `sid` when the client requires the session.
+ */
+interface AuthioFrontChannelLogout {
+    /** `sid`: the Authio session that ended, when Authio sent it. */
+    readonly sessionId: string | undefined;
+    /** `iss`, when Authio sent it; always this client's issuer. */
+    readonly issuer: string | undefined;
+}
+/**
+ * Reads a front-channel logout request: `iss` and `sid` come together, and `iss` must be the issuer.
+ *
+ * @throws AuthioCallbackError with `issuer_mismatch` for another issuer, `missing_issuer` for a `sid` without `iss`.
+ */
+declare function readAuthioFrontChannelLogout(request: string | URL | URLSearchParams | Readonly<Record<string, unknown>>, issuer: string): AuthioFrontChannelLogout;
+/**
+ * Parses a `WWW-Authenticate` bearer challenge, or `undefined` when the header holds none.
+ */
+declare function parseAuthioBearerChallenge(header: string | null | undefined): AuthioBearerChallenge | undefined;
 
 /**
  * A token endpoint answer, as Authio sends it.
@@ -529,9 +941,10 @@ interface AuthioClientCredentialsToken {
  * One of the person's connected accounts at a provider.
  */
 interface AuthioConnectionChoice {
-    id: string;
-    label?: string;
-    external_login?: string;
+    readonly id: string;
+    readonly label?: string;
+    /** The account's login at the provider. */
+    readonly externalLogin?: string;
 }
 /**
  * The account at the provider a connection token belongs to.
@@ -540,6 +953,7 @@ interface AuthioExternalAccount {
     id?: string;
     login?: string;
     email?: string;
+    [member: string]: unknown;
 }
 /**
  * The outcome of exchanging a user's token for the token of one of their connected accounts.
@@ -551,15 +965,17 @@ type AuthioConnectionExchangeResult = AuthioConnectionGranted | AuthioConnection
 interface AuthioConnectionGranted {
     readonly status: "granted";
     readonly accessToken: string;
-    readonly provider: string;
-    readonly providerType?: string;
-    readonly connectionId?: string;
-    readonly tokenType?: string;
+    /** `urn:authio:params:oauth:token-type:connection-access-token`. */
     readonly issuedTokenType?: string;
-    readonly scope?: string;
-    readonly externalAccount?: AuthioExternalAccount;
+    readonly tokenType?: string;
     /** Seconds. */
     readonly expiresIn?: number;
+    readonly scope?: string;
+    readonly connectionId?: string;
+    readonly provider: string;
+    /** The kind of provider, such as `GitHubApp`. */
+    readonly providerType?: string;
+    readonly externalAccount?: AuthioExternalAccount;
 }
 /**
  * The person has not connected an account at the provider yet; send them to `connectUri`.
@@ -567,15 +983,19 @@ interface AuthioConnectionGranted {
 interface AuthioConnectionRequired {
     readonly status: "required";
     readonly connectUri?: string;
-    readonly description: string;
+    readonly provider: string;
+    readonly errorCode?: string;
+    readonly errorDescription: string;
 }
 /**
  * The person has several accounts at the provider; ask again with one `connectionId`.
  */
 interface AuthioConnectionSelectionRequired {
     readonly status: "selection_required";
+    readonly provider: string;
     readonly connections: readonly AuthioConnectionChoice[];
-    readonly description: string;
+    readonly errorCode?: string;
+    readonly errorDescription: string;
 }
 /**
  * Authio refused the exchange.
@@ -583,10 +1003,20 @@ interface AuthioConnectionSelectionRequired {
 interface AuthioConnectionRefused {
     readonly status: "refused";
     readonly error: string;
-    readonly code?: string;
-    readonly description: string;
+    readonly errorCode?: string;
+    readonly errorDescription: string;
     readonly connectUri?: string;
 }
+/**
+ * What one poll of the device flow's token endpoint means (RFC 8628 §3.5).
+ */
+type AuthioDevicePollOutcome = {
+    readonly outcome: "keep_polling";
+    readonly intervalIncrease: number;
+} | {
+    readonly outcome: "failed";
+    readonly error: string;
+};
 
 /**
  * Everything the Authio client needs: where Authio is, and the client's credentials.
@@ -596,8 +1026,78 @@ interface AuthioClientOptions extends AuthioConnectionOptions, AuthioClientCrede
      * Seconds before expiry a cached token is renewed (capped at half its lifetime). Defaults to 60.
      */
     tokenRefreshSkew?: number;
-    /** The client's own encryption key, to read a UserInfo Authio answers encrypted. */
-    clientEncryptionKey?: AuthioEncryptionKey;
+    /**
+     * What the authorization round trip checks, as the client is registered in Authio: `pkce`, `state`, `nonce`, or
+     * `none`. Only the listed checks are made; omitted, none is (a client that requires PKCE needs `["pkce"]`).
+     */
+    checks?: readonly AuthioCheck[];
+    /** The PKCE method, when `checks` holds `pkce`: one of the client's allowed methods. Defaults to `S256`. */
+    codeChallengeMethod?: AuthioCodeChallengeMethod;
+    /** The `response_mode` sent with every authorization request: `query` or `web_message`. Omitted, none is sent. */
+    responseMode?: AuthioResponseMode;
+    /**
+     * The algorithm the client's ID tokens are signed with, as registered in Authio, which signs the client's logout
+     * tokens with it too. HS256, HS384 and HS512 are verified with `clientSecret` (OpenID Connect Core
+     * §10.1). Omitted, the asymmetric algorithms the discovery document announces are accepted (RS*, PS*, ES*).
+     */
+    idTokenSignedResponseAlg?: string;
+    /** The algorithm a signed UserInfo answer is signed with. Defaults to `idTokenSignedResponseAlg`. */
+    userinfoSignedResponseAlg?: string;
+    /**
+     * The algorithm the client's access tokens are signed with (Authio's second signing setting), for
+     * `readAccessTokenClaims`. HS* is verified with `clientSecret`. Omitted, the asymmetric algorithms the discovery
+     * document announces are accepted, and never HS*.
+     */
+    accessTokenSignedResponseAlg?: string;
+    /**
+     * The private half of the client's own encryption key, to read ID tokens, UserInfo and logout tokens Authio
+     * encrypts to the client; or a function returning it. Without it, nothing is decrypted.
+     */
+    clientEncryptionKey?: AuthioEncryptionKeySource;
+    /** A PEM or JWK file holding `clientEncryptionKey` (Node only), read on first use. */
+    clientEncryptionKeyPath?: string;
+    /**
+     * The key management algorithms (`alg`) decrypted, as registered for the client. Defaults to RSA-OAEP and
+     * RSA-OAEP-256; RSA1_5 cannot be listed, because Node and WebCrypto 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 here, because Node and WebCrypto cannot
+     * decrypt it. Defaults to `false`.
+     */
+    allowLegacyEncryptionAlgorithms?: boolean;
+    /** Where Authio sends the person back after signing in, unless a request names another. */
+    redirectUri?: string;
+    /** Where Authio sends the person after signing out, unless a request names another. */
+    postLogoutRedirectUri?: string;
+    /** Seconds of clock skew tolerated on ID tokens, logout tokens and signed UserInfo. Defaults to 30. */
+    clockSkew?: number;
+}
+/**
+ * What a completed sign-in yields.
+ */
+interface AuthioAuthorizationResult {
+    /** The token endpoint's answer: access token, refresh token, ID token. */
+    readonly tokens: AuthioTokenResponse;
+    /** The validated ID token's claims, when Authio issued one (the `openid` scope). */
+    readonly idToken: AuthioIdTokenClaims | undefined;
+}
+/**
+ * What the end-session URL carries (OpenID Connect RP-Initiated Logout).
+ */
+interface AuthioEndSessionRequest {
+    /** The ID token of the session to end. */
+    idTokenHint?: string;
+    /** Where to send the person afterwards; must be registered. Defaults to the client's `postLogoutRedirectUri`. */
+    postLogoutRedirectUri?: string;
+    /** Echoed back to `postLogoutRedirectUri`. */
+    state?: string;
+    /** The language of the signed-out screen. */
+    uiLocales?: string | readonly string[];
+    /** Sends the client id unless `false`, so Authio knows the client without an ID token. */
+    includeClientId?: boolean;
 }
 /**
  * Per-call options.
@@ -622,10 +1122,14 @@ interface AuthioTokenClient {
         codeVerifier?: string;
         resource?: string;
     } & AuthioCallOptions): Promise<AuthioTokenResponse>;
-    /** Refreshes; the answer carries the rotated refresh token, which must be stored. */
+    /**
+     * Refreshes; the answer carries the rotated refresh token, which must be stored. `scopes` may only narrow the
+     * granted ones; `resource` (RFC 8707) asks for an access token addressed to that resource server.
+     */
     refresh(options: {
         refreshToken: string;
         scopes?: Iterable<string> | string;
+        resource?: string;
     } & AuthioCallOptions): Promise<AuthioTokenResponse>;
     /** Exchanges a user's access token for one addressed to another resource (RFC 8693, on-behalf-of). */
     exchange(options: {
@@ -661,6 +1165,16 @@ interface AuthioTokenClient {
         password: string;
         scopes?: Iterable<string> | string;
     } & AuthioCallOptions): Promise<AuthioTokenResponse>;
+    /**
+     * The `personal_access_token` grant: a `pat_` value presented as `client_secret`, with the consumer's client id for
+     * a consumer's token or none for an account's token. The client's own credentials are not sent.
+     */
+    personalAccessToken(options: {
+        token: string;
+        clientId?: string;
+        scopes?: Iterable<string> | string;
+        resource?: string;
+    } & AuthioCallOptions): Promise<AuthioTokenResponse>;
 }
 /**
  * Client-credentials tokens, cached per scopes and resource.
@@ -721,6 +1235,65 @@ interface AuthioClient {
         resource?: string;
         fetch?: typeof fetch;
     }): typeof fetch;
+    /**
+     * Builds the authorization URL (the parameters of the configured `checks`, and Authio's parameters) and the
+     * transaction to keep until the callback.
+     */
+    createAuthorizationUrl(request?: AuthioAuthorizationRequest & AuthioCallOptions): Promise<AuthioAuthorizationUrl>;
+    /**
+     * Completes a sign-in: checks `state` (with the `state` check) and the `iss` parameter (RFC 9207), throws the OAuth
+     * error Authio sent back, redeems the code (with the PKCE verifier, with the `pkce` check), and validates the ID
+     * token (`nonce` with the `nonce` check, `at_hash`, `max_age`). A `state` the transaction did not ask for is ignored.
+     *
+     * @param callback The callback URL, its query, or its parameters (a `web_message` answer, a parsed query).
+     * @param transaction What `createAuthorizationUrl` returned with the URL.
+     * @throws AuthioCallbackError when the callback is not for this transaction.
+     * @throws AuthioProtocolError for an OAuth error.
+     * @throws AuthioTokenValidationError when the ID token does not validate.
+     */
+    handleAuthorizationCallback(callback: string | URL | URLSearchParams | Readonly<Record<string, unknown>>, transaction: AuthioAuthorizationTransaction, options?: AuthioCallOptions): Promise<AuthioAuthorizationResult>;
+    /**
+     * Validates an ID token: decrypted with `clientEncryptionKey` when it is a JWE, then signature (cached JWKS), `iss`,
+     * `aud` = the client id, `exp` with the skew, payload `typ` = `ID`, and `nonce`, `at_hash` and `auth_time` when
+     * given.
+     *
+     * @throws AuthioTokenValidationError naming why it was refused.
+     */
+    validateIdToken(idToken: string, expectations?: {
+        nonce?: string;
+        accessToken?: string;
+        maxAge?: number;
+    } & AuthioCallOptions): Promise<AuthioIdTokenClaims>;
+    /**
+     * Validates a back-channel logout token Authio posted as `logout_token`.
+     *
+     * @throws AuthioTokenValidationError naming why it was refused (`invalid_logout_token` for the logout-specific rules).
+     */
+    validateLogoutToken(logoutToken: string, options?: AuthioCallOptions): Promise<AuthioLogoutToken>;
+    /**
+     * Reads a front-channel logout request Authio loaded in an iframe: `iss` must be the issuer, and `sid` comes with
+     * it. End the sessions of `sessionId`, or the browser's own session when Authio sent none.
+     *
+     * @throws AuthioCallbackError when `iss` names another issuer, or `sid` comes without `iss`.
+     */
+    validateFrontChannelLogout(request: string | URL | URLSearchParams | Readonly<Record<string, unknown>>): AuthioFrontChannelLogout;
+    /**
+     * Reads an access token this client received from Authio: decrypted with `clientEncryptionKey` when it is a JWE,
+     * then its signature (with `accessTokenSignedResponseAlg`), `iss` and `exp` checked. Its audience is the API's, so it is not checked. `undefined` for an
+     * opaque token, or an encrypted one without `clientEncryptionKey`.
+     *
+     * @throws AuthioTokenValidationError naming why it was refused.
+     */
+    readAccessTokenClaims(accessToken: string, options?: AuthioCallOptions): Promise<JWTPayload | undefined>;
+    /** Builds the end-session URL (RP-Initiated Logout). */
+    createEndSessionUrl(request?: AuthioEndSessionRequest & AuthioCallOptions): Promise<string>;
+    /**
+     * Builds an authorization URL that satisfies an API's `insufficient_user_authentication` challenge (RFC 9470): its
+     * `acr_values` and `max_age`, with `prompt=login` when the challenge asks for a sign-in made just now (`max_age=0`).
+     *
+     * @param challenge The `WWW-Authenticate` header value, or the challenge already parsed.
+     */
+    createStepUpAuthorizationUrl(challenge: string | AuthioBearerChallenge, request?: AuthioAuthorizationRequest & AuthioCallOptions): Promise<AuthioAuthorizationUrl>;
 }
 /**
  * Creates the Authio client.
@@ -733,6 +1306,102 @@ declare function createAuthioClient(options: AuthioClientOptions): AuthioClient;
  * renewed `refreshSkewMs` before that, at most half its lifetime.
  */
 declare function toClientCredentialsToken(response: AuthioTokenResponse, issuedAt: number, refreshSkewMs: number): AuthioClientCredentialsToken;
+/**
+ * Reads the answer of a connected-account token exchange (see `conformance/oauth-responses.json`).
+ *
+ * @internal
+ */
+declare function toConnectionExchangeResult(body: string, status: number, provider: string): AuthioConnectionExchangeResult;
+/**
+ * What a device-flow poll's OAuth error means: keep polling (5 seconds slower after `slow_down`), or stop with it.
+ */
+declare function toDevicePollOutcome(error: string): AuthioDevicePollOutcome;
+
+/**
+ * A successful Admin API answer: the envelope's `data` (one object, or a listing's page `{ items, totalCount,
+ * pageNumber, pageSize }`), nothing for `204`.
+ */
+interface AuthioAdminSuccess<T = unknown> {
+    readonly ok: true;
+    readonly data?: T;
+}
+/**
+ * A refused Admin API answer.
+ */
+interface AuthioAdminFailure {
+    readonly ok: false;
+    readonly error: AuthioAdminError;
+}
+/**
+ * An Admin API answer, read.
+ */
+type AuthioAdminEnvelope<T = unknown> = AuthioAdminSuccess<T> | AuthioAdminFailure;
+/**
+ * How an account credential is presented: `ak_` (API key), `cs_` (client secret, exchanged first) or `pat_`
+ * (personal access token).
+ */
+type AuthioAccountCredentialKind = "api_key" | "client_secret" | "personal_access_token";
+/**
+ * Options of `createAuthioAccountCredential`.
+ */
+interface AuthioAccountCredentialOptions extends Omit<AuthioConnectionOptions, "issuer" | "realm"> {
+    /** Authio's base URL, such as `https://auth.example.com`. Required. */
+    authority?: string;
+    /** The credential's value: `ak_…`, `cs_…` or `pat_…`. */
+    credential: string;
+    /** The credential's id, needed to exchange a `cs_` secret (its `client_id` is `cred_` and the id without dashes). */
+    credentialId?: string;
+    /** How an `ak_` or `pat_` value is sent directly: `Authorization: Bearer` (default) or `x-api-key`. */
+    presentAs?: "bearer" | "x-api-key";
+    /** Exchanges a `pat_` value with the `personal_access_token` grant instead of sending it directly. */
+    exchangePersonalAccessToken?: boolean;
+    /** Narrows an exchanged token to these `admin:{permission}:{method}` scopes. */
+    scopes?: Iterable<string> | string;
+    /** Seconds before expiry an exchanged token is renewed (at most half its lifetime). Defaults to 60. */
+    tokenRefreshSkew?: number;
+}
+/**
+ * An account credential ready to call the Admin API with.
+ */
+interface AuthioAccountCredential {
+    /** How the credential is presented. */
+    readonly kind: AuthioAccountCredentialKind;
+    /** Whether it is exchanged at the `authio` realm's token endpoint before use. */
+    readonly exchanged: boolean;
+    /** The headers that authenticate a request: `Authorization` or `x-api-key`. */
+    headers(signal?: AbortSignal): Promise<Record<string, string>>;
+    /** Drops an exchanged token, so the next request exchanges again. */
+    invalidate(): void;
+    /**
+     * A `fetch` that authenticates every request; on `401` with an exchanged token it exchanges again and retries once;
+     * on `429` or `503` it waits `Retry-After` and retries an idempotent request (`GET`, `HEAD`, `PUT`, `DELETE`) once.
+     */
+    readonly fetch: typeof fetch;
+}
+/**
+ * Reads an Admin API answer (see `conformance/admin-envelopes.json`). The status is the HTTP one, never the
+ * envelope's numeric `statusCode`; `requestId` falls back to `X-Request-Id`, and `retryAfterSeconds` comes from
+ * `Retry-After`.
+ */
+declare function parseAuthioAdminEnvelope<T = unknown>(status: number, body: string | null | undefined, headers?: Headers | Readonly<Record<string, string | undefined>>): AuthioAdminEnvelope<T>;
+/**
+ * Reads an Admin API response, throwing `AuthioAdminError` when it is not a success.
+ */
+declare function readAuthioAdminResponse<T = unknown>(response: Response): Promise<AuthioAdminSuccess<T>>;
+/**
+ * Prepares an account credential for the Admin API: `ak_` and `pat_` go directly as `Authorization: Bearer` (or
+ * `x-api-key`); a `cs_` secret is exchanged at `{authority}/realms/authio` with `client_credentials` and the
+ * `client_id` `cred_{id}`; a `pat_` may be exchanged with the `personal_access_token` grant instead. Exchanged tokens
+ * are cached and renewed before expiry.
+ *
+ * @throws AuthioConfigurationError when the value has no known prefix or a `cs_` secret comes without its id.
+ */
+declare function createAuthioAccountCredential(options: AuthioAccountCredentialOptions): AuthioAccountCredential;
+/**
+ * The `client_id` an account credential's client secret is exchanged with: `cred_` and the id in format N (no dashes,
+ * lower case). An id already starting with `cred_` is kept.
+ */
+declare function toCredentialClientId(credentialId: string): string;
 
 /**
  * One role read from a `*_resource_access` claim, with the permissions it grants.
@@ -811,109 +1480,152 @@ type AuthioWebhookVerificationResult = {
     readonly timestamp?: Date;
 };
 /**
- * A webhook event. `data` holds the event-specific payload; read it typed with the `as…` helpers.
+ * A webhook event. `data` holds the event-specific payload as delivered (snake_case); read it typed, in camelCase,
+ * with the `as…` helpers.
  */
 interface AuthioWebhookEvent {
     readonly id: string;
     readonly type: string;
     /** Seconds since the epoch. */
     readonly created_at: number;
-    readonly realm_id?: string;
-    readonly client_id?: string;
+    readonly realm_id?: string | null;
+    readonly client_id?: string | null;
     readonly data: unknown;
     [member: string]: unknown;
 }
-/** `user_created`, `user_updated`, `user_deleted`. */
+/** `user_created`, `user_updated`, `user_deleted`, as delivered. */
 interface AuthioWebhookUserData {
     id: string;
-    username?: string;
-    email?: string;
-    first_name?: string;
-    last_name?: string;
+    username?: string | null;
+    email?: string | null;
+    first_name?: string | null;
+    last_name?: string | null;
     email_confirmed: boolean;
-    status?: string;
-    realm_id?: string;
-    client_id?: string;
+    status?: string | null;
+    realm_id?: string | null;
+    client_id?: string | null;
 }
-/** `login_succeeded`, `login_failed`. */
+/** `login_succeeded`, `login_failed`, as delivered. */
 interface AuthioWebhookLoginData {
-    grant_type?: string;
-    user_id?: string;
-    username?: string;
-    email?: string;
-    ip_address?: string;
-    user_agent?: string;
-    session_id?: string;
-    failure_reason?: string;
-    resource?: string;
-    scopes?: string;
+    grant_type?: string | null;
+    user_id?: string | null;
+    username?: string | null;
+    email?: string | null;
+    ip_address?: string | null;
+    user_agent?: string | null;
+    session_id?: string | null;
+    failure_reason?: string | null;
+    resource?: string | null;
+    scopes?: string[] | null;
+    authentication_methods?: string[] | null;
+    acr?: string | null;
+    identity_provider?: string | null;
+    consumer_id?: string | null;
+    consumer_name?: string | null;
 }
-/** `user_locked_out`. */
+/** `user_locked_out`, as delivered. */
 interface AuthioWebhookUserLockedOutData {
     user_id: string;
-    username?: string;
-    email?: string;
-    lockout_end?: string;
+    username?: string | null;
+    email?: string | null;
+    lockout_end?: string | null;
     access_failed_count: number;
 }
-/** `token_revoked`. */
+/** `token_revoked`, as delivered. */
 interface AuthioWebhookTokenRevokedData {
-    token_id?: string;
-    subject?: string;
-    session_id?: string;
-    token_type_hint?: string;
+    token_id?: string | null;
+    subject?: string | null;
+    session_id?: string | null;
+    token_type_hint?: string | null;
 }
-/** `keys_rotated`. */
+/**
+ * `keys_rotated`, as delivered: `rotation_days` and `automatic` on a scheduled rotation, `revoked_keys_count` on a
+ * manual one.
+ */
 interface AuthioWebhookKeysRotatedData {
-    signing_key_id?: string;
-    encryption_key_id?: string;
-    revoked_keys_count?: number;
-    rotation_days?: number;
-    automatic?: boolean;
+    signing_key_id?: string | null;
+    encryption_key_id?: string | null;
+    revoked_keys_count?: number | null;
+    rotation_days?: number | null;
+    automatic?: boolean | null;
 }
-/** `token_reuse_detected`. */
+/** `token_reuse_detected`, as delivered. */
 interface AuthioWebhookTokenReuseDetectedData {
-    token_id?: string;
-    subject?: string;
-    session_id?: string;
-    ip_address?: string;
-    user_agent?: string;
+    token_id?: string | null;
+    subject?: string | null;
+    session_id?: string | null;
+    ip_address?: string | null;
+    user_agent?: string | null;
 }
-/** `admin_resource_created`, `admin_resource_updated`, `admin_resource_deleted`. */
+/** `admin_resource_created`, `admin_resource_updated`, `admin_resource_deleted`, as delivered. */
 interface AuthioWebhookAdminResourceData {
-    action?: string;
-    resource_type?: string;
-    resource_id?: string;
-    realm_id?: string;
-    client_id?: string;
-    actor_user_id?: string;
-    actor_username?: string;
-    actor_email?: string;
-    ip_address?: string;
-    method?: string;
-    path?: string;
-}
-/** `user_suspended`, `user_suspension_ended`. */
+    action?: string | null;
+    resource_type?: string | null;
+    resource_id?: string | null;
+    parent_id?: string | null;
+    realm_id?: string | null;
+    client_id?: string | null;
+    /** `User` or `Credential`. */
+    actor_type?: string | null;
+    actor_user_id?: string | null;
+    actor_username?: string | null;
+    actor_email?: string | null;
+    actor_credential_id?: string | null;
+    actor_credential_name?: string | null;
+    actor_platform_operator?: boolean | null;
+    ip_address?: string | null;
+    method?: string | null;
+    path?: string | null;
+    /** What changed, by resource type; kept as delivered. */
+    details?: Record<string, unknown> | null;
+}
+/** `user_suspended`, `user_suspension_ended`, as delivered. */
 interface AuthioWebhookUserSuspensionData {
     id: string;
     user_id: string;
-    level?: string;
-    status?: string;
-    starts_at?: string;
-    ends_at?: string;
+    level?: string | null;
+    status?: string | null;
+    starts_at?: string | null;
+    ends_at?: string | null;
     restricted_scopes: string[];
     revokes_every_role: boolean;
     revoked_role_ids: string[];
-    sessions_terminated_at?: string;
-    lifted_at?: string;
+    sessions_terminated_at?: string | null;
+    lifted_at?: string | null;
+}
+/** `attack_detected`, as delivered: an attack on the realm and the measure Authio took. */
+interface AuthioWebhookAttackDetectedData {
+    incident_id: string;
+    /** Such as `credential_stuffing`. */
+    kind?: string | null;
+    severity?: string | null;
+    /** Such as `source_blocked`. */
+    measure?: string | null;
+    ip_address?: string | null;
+    country?: string | null;
+    asn?: number | null;
+    network_operator?: string | null;
+    user_id?: string | null;
+    started_at?: string | null;
+}
+/** `credential_compromised`, as delivered: a person's password was used by an attacker. */
+interface AuthioWebhookCredentialCompromisedData {
+    incident_id: string;
+    user_id?: string | null;
+    username?: string | null;
+    ip_address?: string | null;
+    country?: string | null;
+    asn?: number | null;
+    network_operator?: string | null;
+    password_change_required?: boolean | null;
 }
-/** `ping`. */
+/** `ping`, as delivered. */
 interface AuthioWebhookPingData {
-    message?: string;
-    subscription?: string;
+    message?: string | null;
+    subscription?: string | null;
 }
 /**
- * The data shape of each event type.
+ * The data shape of each event type, as delivered (snake_case).
  */
 interface AuthioWebhookDataByType {
     user_created: AuthioWebhookUserData;
@@ -930,10 +1642,44 @@ interface AuthioWebhookDataByType {
     admin_resource_deleted: AuthioWebhookAdminResourceData;
     user_suspended: AuthioWebhookUserSuspensionData;
     user_suspension_ended: AuthioWebhookUserSuspensionData;
+    attack_detected: AuthioWebhookAttackDetectedData;
+    credential_compromised: AuthioWebhookCredentialCompromisedData;
     ping: AuthioWebhookPingData;
 }
 /**
- * An event narrowed to one type, with its data typed.
+ * A snake_case name in camelCase.
+ */
+type AuthioCamelCase<S extends string> = S extends `${infer Head}_${infer Tail}` ? `${Head}${Capitalize<AuthioCamelCase<Tail>>}` : S;
+/**
+ * An object whose top-level member names are turned into camelCase, values unchanged.
+ */
+type AuthioCamelCased<T> = {
+    [K in keyof T as K extends string ? AuthioCamelCase<K> : K]: T[K];
+};
+/** The data of a user event, as the typed accessor exposes it. */
+type AuthioWebhookUser = AuthioCamelCased<AuthioWebhookUserData>;
+/** The data of a login event, as the typed accessor exposes it. */
+type AuthioWebhookLogin = AuthioCamelCased<AuthioWebhookLoginData>;
+/** The data of a lockout event, as the typed accessor exposes it. */
+type AuthioWebhookUserLockedOut = AuthioCamelCased<AuthioWebhookUserLockedOutData>;
+/** The data of a revocation event, as the typed accessor exposes it. */
+type AuthioWebhookTokenRevoked = AuthioCamelCased<AuthioWebhookTokenRevokedData>;
+/** The data of a key rotation event, as the typed accessor exposes it. */
+type AuthioWebhookKeysRotated = AuthioCamelCased<AuthioWebhookKeysRotatedData>;
+/** The data of a refresh token reuse event, as the typed accessor exposes it. */
+type AuthioWebhookTokenReuseDetected = AuthioCamelCased<AuthioWebhookTokenReuseDetectedData>;
+/** The data of an admin resource event, as the typed accessor exposes it. */
+type AuthioWebhookAdminResource = AuthioCamelCased<AuthioWebhookAdminResourceData>;
+/** The data of a suspension event, as the typed accessor exposes it. */
+type AuthioWebhookUserSuspension = AuthioCamelCased<AuthioWebhookUserSuspensionData>;
+/** The data of an attack event, as the typed accessor exposes it. */
+type AuthioWebhookAttackDetected = AuthioCamelCased<AuthioWebhookAttackDetectedData>;
+/** The data of a compromised credential event, as the typed accessor exposes it. */
+type AuthioWebhookCredentialCompromised = AuthioCamelCased<AuthioWebhookCredentialCompromisedData>;
+/** The data of a ping, as the typed accessor exposes it. */
+type AuthioWebhookPing = AuthioCamelCased<AuthioWebhookPingData>;
+/**
+ * An event narrowed to one type, with its data typed as delivered.
  */
 type AuthioTypedWebhookEvent<T extends keyof AuthioWebhookDataByType> = AuthioWebhookEvent & {
     readonly type: T;
@@ -973,23 +1719,40 @@ declare function tryParseWebhookEvent(rawBody: string | Uint8Array | null | unde
  * Whether the event is of one of the given types, narrowing its data.
  */
 declare function isWebhookEventOfType<T extends keyof AuthioWebhookDataByType>(event: AuthioWebhookEvent, ...types: T[]): event is AuthioTypedWebhookEvent<T>;
-/** The data of a user event, or `undefined` for any other type. */
-declare const asUserEvent: (event: AuthioWebhookEvent) => AuthioWebhookUserData | undefined;
-/** The data of a login event, or `undefined` for any other type. */
-declare const asLoginEvent: (event: AuthioWebhookEvent) => AuthioWebhookLoginData | undefined;
-/** The data of a lockout event, or `undefined` for any other type. */
-declare const asUserLockedOutEvent: (event: AuthioWebhookEvent) => AuthioWebhookUserLockedOutData | undefined;
-/** The data of a revocation event, or `undefined` for any other type. */
-declare const asTokenRevokedEvent: (event: AuthioWebhookEvent) => AuthioWebhookTokenRevokedData | undefined;
-/** The data of a key rotation event, or `undefined` for any other type. */
-declare const asKeysRotatedEvent: (event: AuthioWebhookEvent) => AuthioWebhookKeysRotatedData | undefined;
-/** The data of a refresh token reuse event, or `undefined` for any other type. */
-declare const asTokenReuseDetectedEvent: (event: AuthioWebhookEvent) => AuthioWebhookTokenReuseDetectedData | undefined;
-/** The data of an admin resource event, or `undefined` for any other type. */
-declare const asAdminResourceEvent: (event: AuthioWebhookEvent) => AuthioWebhookAdminResourceData | undefined;
-/** The data of a suspension event, or `undefined` for any other type. */
-declare const asUserSuspensionEvent: (event: AuthioWebhookEvent) => AuthioWebhookUserSuspensionData | undefined;
-/** The data of a ping, or `undefined` for any other type. */
-declare const asPingEvent: (event: AuthioWebhookEvent) => AuthioWebhookPingData | undefined;
+/** The data of a user event in camelCase, or `undefined` for any other type. */
+declare const asUserEvent: (event: AuthioWebhookEvent) => AuthioCamelCased<AuthioWebhookUserData> | undefined;
+/** The data of a login event in camelCase, or `undefined` for any other type. */
+declare const asLoginEvent: (event: AuthioWebhookEvent) => AuthioCamelCased<AuthioWebhookLoginData> | undefined;
+/** The data of a lockout event in camelCase, or `undefined` for any other type. */
+declare const asUserLockedOutEvent: (event: AuthioWebhookEvent) => AuthioCamelCased<AuthioWebhookUserLockedOutData> | undefined;
+/** The data of a revocation event in camelCase, or `undefined` for any other type. */
+declare const asTokenRevokedEvent: (event: AuthioWebhookEvent) => AuthioCamelCased<AuthioWebhookTokenRevokedData> | undefined;
+/** The data of a key rotation event in camelCase, or `undefined` for any other type. */
+declare const asKeysRotatedEvent: (event: AuthioWebhookEvent) => AuthioCamelCased<AuthioWebhookKeysRotatedData> | undefined;
+/** The data of a refresh token reuse event in camelCase, or `undefined` for any other type. */
+declare const asTokenReuseDetectedEvent: (event: AuthioWebhookEvent) => AuthioCamelCased<AuthioWebhookTokenReuseDetectedData> | undefined;
+/** The data of an admin resource event in camelCase, or `undefined` for any other type. */
+declare const asAdminResourceEvent: (event: AuthioWebhookEvent) => AuthioCamelCased<AuthioWebhookAdminResourceData> | undefined;
+/** The data of a suspension event in camelCase, or `undefined` for any other type. */
+declare const asUserSuspensionEvent: (event: AuthioWebhookEvent) => AuthioCamelCased<AuthioWebhookUserSuspensionData> | undefined;
+/** The data of an attack event in camelCase, or `undefined` for any other type. */
+declare const asAttackDetectedEvent: (event: AuthioWebhookEvent) => AuthioCamelCased<AuthioWebhookAttackDetectedData> | undefined;
+/** The data of a compromised credential event in camelCase, or `undefined` for any other type. */
+declare const asCredentialCompromisedEvent: (event: AuthioWebhookEvent) => AuthioCamelCased<AuthioWebhookCredentialCompromisedData> | undefined;
+/** The data of a ping in camelCase, or `undefined` for any other type. */
+declare const asPingEvent: (event: AuthioWebhookEvent) => AuthioCamelCased<AuthioWebhookPingData> | undefined;
+/**
+ * Whether Authio documents the event type. An unknown type still parses; read its `data` as delivered.
+ */
+declare function isKnownWebhookEventType(type: string): type is keyof AuthioWebhookDataByType;
+/**
+ * The data of any known event in camelCase (what the typed accessor of its type returns), or `undefined` for an
+ * unknown type.
+ */
+declare function readWebhookEventData(event: AuthioWebhookEvent): Record<string, unknown> | undefined;
+/**
+ * Turns the top-level member names of an object from snake_case into camelCase, leaving the values as they are.
+ */
+declare function toCamelCasedMembers<T extends object>(value: T): AuthioCamelCased<T>;
 
-export { AuthioAsymmetricAlgorithms, type AuthioCallOptions, AuthioClaimTypes, type AuthioClient, AuthioClientAssertionAlgorithms, type AuthioClientAuthentication, type AuthioClientCredentialsCache, type AuthioClientCredentialsSettings, type AuthioClientCredentialsToken, type AuthioClientOptions, type AuthioClock, AuthioConfigurationError, type AuthioConnection, type AuthioConnectionChoice, type AuthioConnectionExchangeResult, type AuthioConnectionGranted, type AuthioConnectionOptions, type AuthioConnectionRefused, type AuthioConnectionRequired, type AuthioConnectionSelectionRequired, AuthioContentEncryptionAlgorithms, AuthioDefaults, type AuthioDeviceAuthorization, type AuthioDiscoveryClient, type AuthioDiscoveryDocument, AuthioDiscoveryError, type AuthioEncryptionKey, AuthioError, type AuthioErrorResponse, type AuthioExternalAccount, AuthioGrantTypes, type AuthioIntrospectionResult, AuthioKeyManagementAlgorithms, AuthioOAuthErrors, type AuthioPrivateKeyInput, AuthioProtocolError, AuthioResourceAccess, AuthioResourceAccessClaims, type AuthioResourceAccessRole, type AuthioResourceAccessSource, AuthioScopes, type AuthioTokenClient, type AuthioTokenDecrypter, type AuthioTokenResponse, AuthioTokenTypes, type AuthioTypedWebhookEvent, type AuthioUserInfo, type AuthioWebhookAdminResourceData, type AuthioWebhookDataByType, type AuthioWebhookEvent, AuthioWebhookEventTypes, AuthioWebhookHeaders, type AuthioWebhookKeysRotatedData, type AuthioWebhookLoginData, type AuthioWebhookPingData, type AuthioWebhookTokenReuseDetectedData, type AuthioWebhookTokenRevokedData, type AuthioWebhookUserData, type AuthioWebhookUserLockedOutData, type AuthioWebhookUserSuspensionData, type AuthioWebhookVerificationFailure, type AuthioWebhookVerificationResult, asAdminResourceEvent, asKeysRotatedEvent, asLoginEvent, asPingEvent, asTokenReuseDetectedEvent, asTokenRevokedEvent, asUserEvent, asUserLockedOutEvent, asUserSuspensionEvent, computeWebhookSignatureHeader, createAuthioClient, createAuthioDiscoveryClient, createAuthioTokenDecrypter, escapeDataString, isAllowedUrl, isAuthioTokenEncrypted, isWebhookEventOfType, parseResourceAccess, parseResourceAccessClaim, parseWebhookEvent, resolveConnection, resolveIssuer, resourceAccessSourceOf, seconds, systemClock, toBasicAuthorization, toClientCredentialsToken, toScopeString, tryParseWebhookEvent, verifyWebhookSignature };
+export { type AuthioAccountCredential, type AuthioAccountCredentialKind, type AuthioAccountCredentialOptions, type AuthioAdminEnvelope, AuthioAdminError, type AuthioAdminFailure, type AuthioAdminNotification, type AuthioAdminSuccess, AuthioAsymmetricAlgorithms, type AuthioAuthorizationRequest, type AuthioAuthorizationResult, type AuthioAuthorizationTransaction, type AuthioAuthorizationUrl, type AuthioBearerChallenge, type AuthioCallOptions, AuthioCallbackError, type AuthioCallbackFailure, type AuthioCallerKind, AuthioCallerKinds, type AuthioCamelCase, type AuthioCamelCased, type AuthioCheck, AuthioChecks, AuthioClaimTypes, type AuthioClient, AuthioClientAssertionAlgorithms, type AuthioClientCredentialsCache, type AuthioClientCredentialsSettings, type AuthioClientCredentialsToken, type AuthioClientOptions, type AuthioClock, type AuthioCodeChallengeMethod, AuthioConfigurationError, type AuthioConnection, type AuthioConnectionChoice, type AuthioConnectionExchangeResult, type AuthioConnectionGranted, type AuthioConnectionOptions, type AuthioConnectionRefused, type AuthioConnectionRequired, type AuthioConnectionSelectionRequired, AuthioContentEncryptionAlgorithms, type AuthioCredentialForm, AuthioDefaults, type AuthioDeviceAuthorization, type AuthioDevicePollOutcome, type AuthioDiscoveryClient, type AuthioDiscoveryDocument, AuthioDiscoveryError, type AuthioEncryptionKey, type AuthioEncryptionKeySource, type AuthioEndSessionRequest, AuthioError, type AuthioErrorResponse, type AuthioExternalAccount, type AuthioFrontChannelLogout, AuthioGrantTypes, AuthioHmacAlgorithms, AuthioHmacMinimumSecretBytes, type AuthioIdTokenClaims, type AuthioIntrospectionResult, type AuthioJwtExpectations, AuthioKeyManagementAlgorithms, AuthioLegacyKeyManagementAlgorithms, type AuthioLogoutToken, AuthioOAuthErrors, type AuthioPkcePair, type AuthioPrivateKeyInput, type AuthioPrompt, AuthioPrompts, AuthioProtocolError, AuthioResourceAccess, AuthioResourceAccessClaims, type AuthioResourceAccessRole, type AuthioResourceAccessSource, type AuthioResponseMode, AuthioScopes, type AuthioSecretSource, type AuthioSigningKeys, AuthioSupportedContentEncryptionAlgorithms, type AuthioTokenClient, type AuthioTokenDecrypter, type AuthioTokenDecrypterOptions, type AuthioTokenEndpointAuthMethod, AuthioTokenEndpointAuthMethods, type AuthioTokenFailure, type AuthioTokenResponse, AuthioTokenTypes, AuthioTokenValidationError, type AuthioTypedWebhookEvent, type AuthioUserInfo, type AuthioWebhookAdminResource, type AuthioWebhookAdminResourceData, type AuthioWebhookAttackDetected, type AuthioWebhookAttackDetectedData, type AuthioWebhookCredentialCompromised, type AuthioWebhookCredentialCompromisedData, type AuthioWebhookDataByType, type AuthioWebhookEvent, AuthioWebhookEventTypes, AuthioWebhookHeaders, type AuthioWebhookKeysRotated, type AuthioWebhookKeysRotatedData, type AuthioWebhookLogin, type AuthioWebhookLoginData, type AuthioWebhookPing, type AuthioWebhookPingData, type AuthioWebhookTokenReuseDetected, type AuthioWebhookTokenReuseDetectedData, type AuthioWebhookTokenRevoked, type AuthioWebhookTokenRevokedData, type AuthioWebhookUser, type AuthioWebhookUserData, type AuthioWebhookUserLockedOut, type AuthioWebhookUserLockedOutData, type AuthioWebhookUserSuspension, type AuthioWebhookUserSuspensionData, type AuthioWebhookVerificationFailure, type AuthioWebhookVerificationResult, asAdminResourceEvent, asAttackDetectedEvent, asCredentialCompromisedEvent, asKeysRotatedEvent, asLoginEvent, asPingEvent, asTokenReuseDetectedEvent, asTokenRevokedEvent, asUserEvent, asUserLockedOutEvent, asUserSuspensionEvent, computeAuthioTokenHash, computeWebhookSignatureHeader, createAuthioAccountCredential, createAuthioClient, createAuthioDiscoveryClient, createAuthioPkce, createAuthioSigningKeys, createAuthioTokenDecrypter, encryptionKeyFromFile, escapeDataString, isAllowedUrl, isAuthioTokenEncrypted, isKnownWebhookEventType, isWebhookEventOfType, parseAuthioAdminEnvelope, parseAuthioBearerChallenge, parseResourceAccess, parseResourceAccessClaim, parseWebhookEvent, randomValue, readAuthioAdminResponse, readAuthioFrontChannelLogout, readWebhookEventData, requireHmacSecretLength, resolveConnection, resolveIssuer, resourceAccessSourceOf, seconds, systemClock, toBasicAuthorization, toCamelCasedMembers, toClientCredentialsToken, toConnectionExchangeResult, toCredentialClientId, toDevicePollOutcome, toScopeString, toTokenValidationError, tryParseWebhookEvent, verifyAuthioJwt, verifyWebhookSignature, withClientSecret };