@hyper.authio/client 0.0.0-stage → 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,995 @@
+import { JWK, CryptoKey } from 'jose';
+
+/**
+ * Claim names Authio writes into its tokens.
+ */
+declare const AuthioClaimTypes: {
+    readonly Subject: "sub";
+    readonly JwtId: "jti";
+    readonly Issuer: "iss";
+    readonly Audience: "aud";
+    readonly Expiration: "exp";
+    readonly IssuedAt: "iat";
+    readonly NotBefore: "nbf";
+    readonly AuthTime: "auth_time";
+    readonly TokenType: "typ";
+    readonly AuthorizedParty: "azp";
+    readonly Scope: "scope";
+    readonly SessionId: "sid";
+    readonly AuthenticationContextClass: "acr";
+    readonly AuthenticationMethods: "amr";
+    readonly IdentityProvider: "idp";
+    readonly Nonce: "nonce";
+    readonly OrganizationId: "org_id";
+    readonly OrganizationAlias: "org_alias";
+    readonly AccountId: "account_id";
+    readonly Actor: "act";
+    readonly DelegationId: "delegation_id";
+    readonly ClientId: "client_id";
+    readonly Name: "name";
+    readonly GivenName: "given_name";
+    readonly FamilyName: "family_name";
+    readonly UniqueName: "unique_name";
+    readonly PreferredUsername: "preferred_username";
+    readonly UpdatedAt: "updated_at";
+    readonly Email: "email";
+    readonly EmailVerified: "email_verified";
+    readonly PhoneNumber: "phone_number";
+    readonly PhoneNumberVerified: "phone_number_verified";
+    readonly ConsumerName: "consumer_name";
+    readonly CredentialId: "credential_id";
+    readonly CredentialType: "credential_type";
+    readonly UserResourceAccess: "user_resource_access";
+    readonly RealmResourceAccess: "realm_resource_access";
+    readonly ClientResourceAccess: "client_resource_access";
+    readonly PlanResourceAccess: "plan_resource_access";
+    readonly ConsumerResourceAccess: "consumer_resource_access";
+    readonly SecretResourceAccess: "secret_resource_access";
+    readonly SystemResourceAccess: "system_resource_access";
+};
+/**
+ * Where a role in a `*_resource_access` claim was granted.
+ *
+ * - `user`: to the person, directly or through one of their groups.
+ * - `realm`: to everyone who signs in to the realm.
+ * - `client`: to everyone who signs in through the client.
+ * - `plan`: by the plan of an Authio platform account (platform users only).
+ * - `consumer`: to a machine consumer of the client.
+ * - `secret`: to an account credential (API key, client secret, personal access token).
+ * - `system`: to an Authio platform user (the console).
+ */
+type AuthioResourceAccessSource = "user" | "realm" | "client" | "plan" | "consumer" | "secret" | "system";
+/**
+ * The seven `*_resource_access` claim names, mapped to their source.
+ */
+declare const AuthioResourceAccessClaims: Readonly<Record<string, AuthioResourceAccessSource>>;
+/**
+ * Scopes Authio defines.
+ */
+declare const AuthioScopes: {
+    readonly OpenId: "openid";
+    readonly Profile: "profile";
+    readonly Email: "email";
+    readonly Phone: "phone";
+    readonly Roles: "roles";
+    readonly OfflineAccess: "offline_access";
+};
+/**
+ * Grant types Authio's token endpoint accepts.
+ */
+declare const AuthioGrantTypes: {
+    readonly AuthorizationCode: "authorization_code";
+    readonly RefreshToken: "refresh_token";
+    readonly ClientCredentials: "client_credentials";
+    readonly Password: "password";
+    readonly DeviceCode: "urn:ietf:params:oauth:grant-type:device_code";
+    readonly TokenExchange: "urn:ietf:params:oauth:grant-type:token-exchange";
+    readonly PersonalAccessToken: "personal_access_token";
+};
+/**
+ * Token type identifiers.
+ */
+declare const AuthioTokenTypes: {
+    readonly AccessTokenUrn: "urn:ietf:params:oauth:token-type:access_token";
+    readonly ConnectionAccessTokenUrn: "urn:authio:params:oauth:token-type:connection-access-token";
+    readonly AccessToken: "access_token";
+    readonly RefreshToken: "refresh_token";
+};
+/**
+ * OAuth error codes Authio answers with.
+ */
+declare const AuthioOAuthErrors: {
+    readonly InvalidRequest: "invalid_request";
+    readonly InvalidClient: "invalid_client";
+    readonly InvalidGrant: "invalid_grant";
+    readonly UnauthorizedClient: "unauthorized_client";
+    readonly UnsupportedGrantType: "unsupported_grant_type";
+    readonly InvalidScope: "invalid_scope";
+    readonly InvalidTarget: "invalid_target";
+    readonly AccessDenied: "access_denied";
+    readonly InvalidToken: "invalid_token";
+    readonly AuthorizationPending: "authorization_pending";
+    readonly SlowDown: "slow_down";
+    readonly ExpiredToken: "expired_token";
+    readonly ConnectionRequired: "connection_required";
+    readonly ConnectionSelectionRequired: "connection_selection_required";
+    readonly ConnectionPolicyViolation: "connection_policy_violation";
+    readonly ServerError: "server_error";
+    readonly TemporarilyUnavailable: "temporarily_unavailable";
+};
+/**
+ * Webhook event types.
+ */
+declare const AuthioWebhookEventTypes: {
+    readonly UserCreated: "user_created";
+    readonly UserUpdated: "user_updated";
+    readonly UserDeleted: "user_deleted";
+    readonly LoginSucceeded: "login_succeeded";
+    readonly LoginFailed: "login_failed";
+    readonly UserLockedOut: "user_locked_out";
+    readonly TokenRevoked: "token_revoked";
+    readonly KeysRotated: "keys_rotated";
+    readonly TokenReuseDetected: "token_reuse_detected";
+    readonly AdminResourceCreated: "admin_resource_created";
+    readonly AdminResourceUpdated: "admin_resource_updated";
+    readonly AdminResourceDeleted: "admin_resource_deleted";
+    readonly UserSuspended: "user_suspended";
+    readonly UserSuspensionEnded: "user_suspension_ended";
+    readonly Ping: "ping";
+};
+/**
+ * Headers Authio sends with a webhook delivery.
+ */
+declare const AuthioWebhookHeaders: {
+    readonly Signature: "X-Authio-Signature";
+    readonly Event: "X-Authio-Event";
+    readonly EventId: "X-Authio-Event-Id";
+};
+/**
+ * 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"];
+/**
+ * Defaults shared by every Authio SDK.
+ */
+declare const AuthioDefaults: {
+    readonly DiscoveryPath: "/.well-known/openid-configuration";
+    readonly RedactedValue: "[redacted]";
+    readonly PlatformRealm: "authio";
+    readonly PlatformClientId: "authio";
+    readonly ApiKeyPrefix: "ak_";
+    readonly ClientSecretPrefix: "cs_";
+    readonly PersonalAccessTokenPrefix: "pat_";
+    /** Seconds. */
+    readonly ClientAssertionLifetime: 120;
+    /** Seconds. */
+    readonly MaxClientAssertionLifetime: 3600;
+    /** Seconds. */
+    readonly DeviceInterval: 5;
+    /** Seconds. */
+    readonly DeviceSlowDownIncrement: 5;
+    /** Seconds a token without `expires_in` is assumed to live. */
+    readonly AssumedTokenLifetime: 300;
+    /** Seconds. */
+    readonly DiscoveryCacheDuration: 3600;
+    /** Seconds. */
+    readonly HttpTimeout: 30;
+    /** Seconds. */
+    readonly TokenRefreshSkew: 60;
+    /** Seconds. */
+    readonly WebhookTolerance: 300;
+    /** Smallest RSA key Authio verifies a client assertion from, in bits. */
+    readonly MinimumRsaKeySize: 2048;
+    readonly CredentialHeaders: readonly ["authorization", "proxy-authorization", "x-api-key", "cookie", "set-cookie"];
+};
+
+/**
+ * Base class of every error the Authio SDKs throw on purpose.
+ */
+declare class AuthioError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * An OAuth error Authio answered with, or an answer the SDK could not read.
+ *
+ * `error` is the OAuth error code; `http_{status}` when the body carried none, and `invalid_response` when a success
+ * body could not be read.
+ */
+declare class AuthioProtocolError extends AuthioError {
+    /** The OAuth error code. */
+    readonly error: string;
+    /** The OAuth error description. */
+    readonly errorDescription: string | undefined;
+    /** Authio's own error code (`error_code`), more specific than `error`. */
+    readonly errorCode: string | undefined;
+    /** The HTTP status, when the error came from a response. */
+    readonly status: number | undefined;
+    constructor(error: string, errorDescription?: string, errorCode?: string, status?: number, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The discovery document could not be read, or names another issuer.
+ */
+declare class AuthioDiscoveryError extends AuthioError {
+}
+/**
+ * The SDK was configured in a way it cannot work with.
+ */
+declare class AuthioConfigurationError extends AuthioError {
+}
+
+/**
+ * Time as the SDK sees it. Replace it in tests to control expiry, caching and device polling.
+ */
+interface AuthioClock {
+    /** Milliseconds since the epoch. */
+    now(): number;
+    /** Waits `ms` milliseconds; rejects when the signal aborts. */
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+/**
+ * The real clock.
+ */
+declare const systemClock: AuthioClock;
+/**
+ * Where Authio is and how to reach it. Shared by the client, the API verifier and the BFF.
+ */
+interface AuthioConnectionOptions {
+    /**
+     * The realm's issuer, such as `https://auth.example.com/realms/acme`. When absent it is composed from
+     * `authority` and `realm`.
+     */
+    issuer?: string;
+    /** Authio's base URL, such as `https://auth.example.com`. */
+    authority?: string;
+    /** The realm name. */
+    realm?: string;
+    /**
+     * Refuses an `http` issuer or authority unless it is loopback. Defaults to `true`; turn it off only in
+     * development.
+     */
+    requireHttps?: boolean;
+    /** Seconds the discovery document is kept. Defaults to 3600. */
+    discoveryCacheDuration?: number;
+    /** Seconds every HTTP call may take. Defaults to 30. */
+    httpTimeout?: number;
+    /** The `fetch` every call goes through. Defaults to the global one. */
+    fetch?: typeof fetch;
+    /** The clock. Defaults to the system clock. */
+    clock?: AuthioClock;
+}
+/**
+ * How the client authenticates to the token, introspection, revocation and device endpoints.
+ */
+type AuthioClientAuthentication = "client_secret_basic" | "client_secret_post" | "private_key_jwt" | "none";
+/**
+ * The connection settings, resolved once.
+ */
+interface AuthioConnection {
+    readonly issuer: string;
+    readonly discoveryUrl: string;
+    readonly requireHttps: boolean;
+    readonly discoveryCacheDurationMs: number;
+    readonly httpTimeoutMs: number;
+    readonly fetch: typeof fetch;
+    readonly clock: AuthioClock;
+}
+/**
+ * Resolves and validates the connection settings.
+ *
+ * @throws AuthioConfigurationError when the issuer cannot be composed or is not HTTPS.
+ */
+declare function resolveConnection(options: AuthioConnectionOptions): AuthioConnection;
+/**
+ * The issuer: `issuer` when set, else `{authority}/realms/{realm}`.
+ *
+ * @throws AuthioConfigurationError when neither is configured.
+ */
+declare function resolveIssuer(options: Pick<AuthioConnectionOptions, "issuer" | "authority" | "realm">): string;
+/**
+ * Whether a URL may be used to reach Authio: HTTPS, or HTTP on loopback (or anywhere when HTTPS is not required).
+ */
+declare function isAllowedUrl(value: string, requireHttps: boolean): boolean;
+/**
+ * Percent-encodes everything but RFC 3986 unreserved characters, as .NET's `Uri.EscapeDataString` does.
+ */
+declare function escapeDataString(value: string): string;
+/**
+ * Converts optional seconds to milliseconds, refusing negative or non-finite values.
+ *
+ * @internal
+ */
+declare function seconds(value: number | undefined, fallback: number, name: string): number;
+
+/**
+ * The realm's OpenID Connect discovery document. Members not listed are kept as sent.
+ */
+interface AuthioDiscoveryDocument {
+    issuer: string;
+    authorization_endpoint?: string;
+    token_endpoint?: string;
+    userinfo_endpoint?: string;
+    jwks_uri?: string;
+    introspection_endpoint?: string;
+    revocation_endpoint?: string;
+    end_session_endpoint?: string;
+    device_authorization_endpoint?: string;
+    pushed_authorization_request_endpoint?: string;
+    scopes_supported?: string[];
+    response_types_supported?: string[];
+    response_modes_supported?: string[];
+    grant_types_supported?: string[];
+    subject_types_supported?: string[];
+    id_token_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[];
+    revocation_endpoint_auth_methods_supported?: string[];
+    code_challenge_methods_supported?: string[];
+    claims_supported?: string[];
+    prompt_values_supported?: string[];
+    authorization_response_iss_parameter_supported?: boolean;
+    [member: string]: unknown;
+}
+/**
+ * Reads and caches the discovery document.
+ */
+interface AuthioDiscoveryClient {
+    /** The connection settings the client was built with. */
+    readonly connection: AuthioConnection;
+    /**
+     * The document, read at most once per cache period (concurrent callers share one read).
+     *
+     * @throws AuthioDiscoveryError when it cannot be read or names another issuer.
+     */
+    get(signal?: AbortSignal): Promise<AuthioDiscoveryDocument>;
+    /** Drops the cached document, so the next `get` reads it again. */
+    invalidate(): void;
+}
+/**
+ * Creates a discovery client. It needs no client credentials, so an API that only validates tokens can use it.
+ */
+declare function createAuthioDiscoveryClient(options: AuthioConnectionOptions | AuthioConnection): AuthioDiscoveryClient;
+
+/**
+ * The OAuth error body Authio answers with.
+ */
+interface AuthioErrorResponse {
+    error?: string;
+    error_description?: string;
+    error_code?: string;
+    connect_uri?: string;
+    connection_provider?: string;
+    connections?: {
+        id: string;
+        label?: string;
+        external_login?: string;
+    }[];
+    [member: string]: unknown;
+}
+/**
+ * Joins scopes into one space-separated value, splitting values that already hold several and dropping duplicates.
+ *
+ * @returns `undefined` when there is no scope.
+ */
+declare function toScopeString(scopes: Iterable<string> | string | undefined | null): string | undefined;
+
+/**
+ * A private key as the SDK accepts it: PEM text (PKCS#8, PKCS#1 RSA or SEC1 EC; PKCS#1 and SEC1 need Node), a JWK
+ * (object or JSON text), or a `CryptoKey`.
+ */
+type AuthioPrivateKeyInput = string | JWK | CryptoKey;
+/**
+ * The algorithms a client assertion may be signed with.
+ */
+declare const AuthioClientAssertionAlgorithms: readonly ["RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512"];
+
+/**
+ * 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`.
+     */
+    clientAuthentication?: AuthioClientAuthentication;
+    /** 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. */
+    clientPrivateKeyPath?: string;
+    /** The `kid` of the key, as registered in Authio. */
+    clientKeyId?: string;
+    /** The assertion's signing algorithm. Defaults to RS256 for RSA keys and the curve's ES algorithm for EC keys. */
+    clientSigningAlgorithm?: string;
+    /** Seconds a client assertion lives. Defaults to 120, at most 3600. */
+    clientAssertionLifetime?: number;
+}
+/**
+ * Builds the HTTP Basic value for a client id and secret, escaping both first as RFC 6749 §2.3.1 asks.
+ */
+declare function toBasicAuthorization(clientId: string, clientSecret: string): string;
+
+/**
+ * The client's own encryption key, the pair Authio encrypts the client's tokens and UserInfo to: the private JWK
+ * 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;
+/**
+ * Opens a compact JWE and returns its plaintext; a token that is not a JWE comes back unchanged.
+ */
+type AuthioTokenDecrypter = (token: string) => Promise<string>;
+/**
+ * The key management algorithms Authio encrypts with.
+ */
+declare const AuthioKeyManagementAlgorithms: readonly ["RSA-OAEP", "RSA-OAEP-256"];
+/**
+ * The content encryption algorithms Authio encrypts with.
+ */
+declare const AuthioContentEncryptionAlgorithms: readonly ["A128CBC-HS256", "A192CBC-HS384", "A256CBC-HS512"];
+/**
+ * Whether a value is a compact JWE (five segments).
+ */
+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.
+ */
+declare function createAuthioTokenDecrypter(key: AuthioEncryptionKey | undefined, setting?: string): AuthioTokenDecrypter;
+
+/**
+ * A token endpoint answer, as Authio sends it.
+ */
+interface AuthioTokenResponse {
+    access_token: string;
+    token_type?: string;
+    /** Seconds. */
+    expires_in?: number;
+    /** Rotated on every refresh: store the new one. */
+    refresh_token?: string;
+    /** Seconds. */
+    refresh_expires_in?: number;
+    id_token?: string;
+    scope?: string;
+    session_state?: string;
+    issued_token_type?: string;
+    [member: string]: unknown;
+}
+/**
+ * An introspection answer (RFC 7662). Authio adds the token's other claims (roles, organization, claim-mapper
+ * claims, the user's own claims) as extra members.
+ */
+interface AuthioIntrospectionResult {
+    active: boolean;
+    scope?: string;
+    client_id?: string;
+    username?: string;
+    token_type?: string;
+    exp?: number;
+    iat?: number;
+    nbf?: number;
+    sub?: string;
+    aud?: string | string[];
+    iss?: string;
+    jti?: string;
+    [member: string]: unknown;
+}
+/**
+ * A device authorization answer (RFC 8628).
+ */
+interface AuthioDeviceAuthorization {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    /** Seconds. */
+    expires_in: number;
+    /** Seconds between polls. */
+    interval?: number;
+    [member: string]: unknown;
+}
+/**
+ * What Authio's UserInfo endpoint answers: `sub` and the standard claims of the granted `profile`, `email` and `phone`
+ * scopes. Roles, claim-mapper claims, the user's own claims and the organization never reach it; read them from the
+ * access token or the ID token.
+ */
+interface AuthioUserInfo {
+    sub: string;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    preferred_username?: string;
+    email?: string;
+    email_verified?: boolean;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    [claim: string]: unknown;
+}
+/**
+ * A cached client-credentials token.
+ */
+interface AuthioClientCredentialsToken {
+    readonly accessToken: string;
+    readonly tokenType: string;
+    /** Milliseconds since the epoch. */
+    readonly expiresAt: number;
+    /** When the cache renews it, in milliseconds since the epoch. */
+    readonly refreshAt: number;
+    readonly scope: string | undefined;
+}
+/**
+ * One of the person's connected accounts at a provider.
+ */
+interface AuthioConnectionChoice {
+    id: string;
+    label?: string;
+    external_login?: string;
+}
+/**
+ * The account at the provider a connection token belongs to.
+ */
+interface AuthioExternalAccount {
+    id?: string;
+    login?: string;
+    email?: string;
+}
+/**
+ * The outcome of exchanging a user's token for the token of one of their connected accounts.
+ */
+type AuthioConnectionExchangeResult = AuthioConnectionGranted | AuthioConnectionRequired | AuthioConnectionSelectionRequired | AuthioConnectionRefused;
+/**
+ * The provider's access token.
+ */
+interface AuthioConnectionGranted {
+    readonly status: "granted";
+    readonly accessToken: string;
+    readonly provider: string;
+    readonly providerType?: string;
+    readonly connectionId?: string;
+    readonly tokenType?: string;
+    readonly issuedTokenType?: string;
+    readonly scope?: string;
+    readonly externalAccount?: AuthioExternalAccount;
+    /** Seconds. */
+    readonly expiresIn?: number;
+}
+/**
+ * The person has not connected an account at the provider yet; send them to `connectUri`.
+ */
+interface AuthioConnectionRequired {
+    readonly status: "required";
+    readonly connectUri?: string;
+    readonly description: string;
+}
+/**
+ * The person has several accounts at the provider; ask again with one `connectionId`.
+ */
+interface AuthioConnectionSelectionRequired {
+    readonly status: "selection_required";
+    readonly connections: readonly AuthioConnectionChoice[];
+    readonly description: string;
+}
+/**
+ * Authio refused the exchange.
+ */
+interface AuthioConnectionRefused {
+    readonly status: "refused";
+    readonly error: string;
+    readonly code?: string;
+    readonly description: string;
+    readonly connectUri?: string;
+}
+
+/**
+ * Everything the Authio client needs: where Authio is, and the client's credentials.
+ */
+interface AuthioClientOptions extends AuthioConnectionOptions, AuthioClientCredentialsSettings {
+    /**
+     * 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;
+}
+/**
+ * Per-call options.
+ */
+interface AuthioCallOptions {
+    /** Aborts the call. */
+    signal?: AbortSignal;
+}
+/**
+ * The token endpoint's grants.
+ */
+interface AuthioTokenClient {
+    /** `client_credentials`, optionally for a resource (RFC 8707). */
+    clientCredentials(options?: {
+        scopes?: Iterable<string> | string;
+        resource?: string;
+    } & AuthioCallOptions): Promise<AuthioTokenResponse>;
+    /** Redeems an authorization code. */
+    authorizationCode(options: {
+        code: string;
+        redirectUri: string;
+        codeVerifier?: string;
+        resource?: string;
+    } & AuthioCallOptions): Promise<AuthioTokenResponse>;
+    /** Refreshes; the answer carries the rotated refresh token, which must be stored. */
+    refresh(options: {
+        refreshToken: string;
+        scopes?: Iterable<string> | string;
+    } & AuthioCallOptions): Promise<AuthioTokenResponse>;
+    /** Exchanges a user's access token for one addressed to another resource (RFC 8693, on-behalf-of). */
+    exchange(options: {
+        subjectToken: string;
+        scopes?: Iterable<string> | string;
+        resource?: string;
+    } & AuthioCallOptions): Promise<AuthioTokenResponse>;
+    /**
+     * Exchanges a user's access token for the token of one of their connected accounts. OAuth refusals come back as
+     * a result, never thrown.
+     */
+    exchangeForConnection(options: {
+        subjectToken: string;
+        provider: string;
+        connectionId?: string;
+    } & AuthioCallOptions): Promise<AuthioConnectionExchangeResult>;
+    /** Starts the device flow (RFC 8628). */
+    deviceAuthorization(options?: {
+        scopes?: Iterable<string> | string;
+    } & AuthioCallOptions): Promise<AuthioDeviceAuthorization>;
+    /**
+     * Polls until the person approves: waits `interval` (default 5 s) before each poll, adds 5 s on `slow_down`, throws
+     * on `access_denied` and `expired_token`, and throws `expired_token` when `expires_in` elapses locally.
+     */
+    pollDevice(authorization: AuthioDeviceAuthorization | {
+        device_code: string;
+        interval?: number;
+        expires_in?: number;
+    }, options?: AuthioCallOptions): Promise<AuthioTokenResponse>;
+    /** The resource owner password grant, where the client allows it. */
+    password(options: {
+        username: string;
+        password: string;
+        scopes?: Iterable<string> | string;
+    } & AuthioCallOptions): Promise<AuthioTokenResponse>;
+}
+/**
+ * Client-credentials tokens, cached per scopes and resource.
+ */
+interface AuthioClientCredentialsCache {
+    /**
+     * A token for the scopes and resource, renewed `tokenRefreshSkew` before expiry (at most half its lifetime);
+     * concurrent callers for one key share one request.
+     */
+    getToken(options?: {
+        scopes?: Iterable<string> | string;
+        resource?: string;
+    } & AuthioCallOptions): Promise<AuthioClientCredentialsToken>;
+    /** Drops the cached token; with `accessToken`, only when the cache still holds that token. */
+    invalidate(options?: {
+        scopes?: Iterable<string> | string;
+        resource?: string;
+        accessToken?: string;
+    }): void;
+}
+/**
+ * The Authio client.
+ */
+interface AuthioClient {
+    /** The issuer. */
+    readonly issuer: string;
+    /** The client id. */
+    readonly clientId: string;
+    /** The connection settings. */
+    readonly connection: AuthioConnection;
+    /** The discovery document. */
+    readonly discovery: AuthioDiscoveryClient;
+    /** The token endpoint. */
+    readonly tokens: AuthioTokenClient;
+    /** Cached client-credentials tokens. */
+    readonly clientCredentials: AuthioClientCredentialsCache;
+    /**
+     * Introspects a token as this client (RFC 7662). Authio answers according to who asks: a token requested for a
+     * resource (RFC 8707) is active only to the client that resource server names as its introspection client.
+     */
+    introspect(token: string, options?: {
+        tokenTypeHint?: string;
+    } & AuthioCallOptions): Promise<AuthioIntrospectionResult>;
+    /** Revokes a token (RFC 7009). */
+    revoke(token: string, options?: {
+        tokenTypeHint?: string;
+    } & AuthioCallOptions): Promise<void>;
+    /**
+     * Reads UserInfo. A UserInfo answered as `application/jwt` is decrypted with `clientEncryptionKey` when it is a
+     * JWE, then verified against the realm's keys (`iss` the issuer, `aud` the client).
+     */
+    userInfo(accessToken: string, options?: AuthioCallOptions): Promise<AuthioUserInfo>;
+    /**
+     * A `fetch` that sends a cached client-credentials token, and on a `401` drops it and retries once.
+     */
+    clientCredentialsFetch(options?: {
+        scopes?: Iterable<string> | string;
+        resource?: string;
+        fetch?: typeof fetch;
+    }): typeof fetch;
+}
+/**
+ * Creates the Authio client.
+ *
+ * @throws AuthioConfigurationError when the settings are incomplete.
+ */
+declare function createAuthioClient(options: AuthioClientOptions): AuthioClient;
+/**
+ * When a token answer expires, and when a cache should renew it: `expires_in` (else 5 minutes) after `issuedAt`,
+ * renewed `refreshSkewMs` before that, at most half its lifetime.
+ */
+declare function toClientCredentialsToken(response: AuthioTokenResponse, issuedAt: number, refreshSkewMs: number): AuthioClientCredentialsToken;
+
+/**
+ * One role read from a `*_resource_access` claim, with the permissions it grants.
+ */
+interface AuthioResourceAccessRole {
+    /** The claim the role came from. */
+    readonly source: AuthioResourceAccessSource;
+    /** The role name. */
+    readonly name: string;
+    /** Resource → methods the role allows on it. */
+    readonly permissions: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * The roles and permissions a token carries in its `*_resource_access` claims, merged across sources.
+ *
+ * Every comparison is case-insensitive, as Authio's own check is. When a name appears in different case, the first
+ * spelling read is the one listed.
+ */
+declare class AuthioResourceAccess {
+    /** No role at all. */
+    static readonly empty: AuthioResourceAccess;
+    /** Every role read, in claim order, one entry per source it came from. */
+    readonly entries: readonly AuthioResourceAccessRole[];
+    /** Every distinct role name. */
+    readonly roles: readonly string[];
+    /** Resource → every method any role allows on it. */
+    readonly permissions: Readonly<Record<string, readonly string[]>>;
+    private readonly lookup;
+    constructor(entries: Iterable<AuthioResourceAccessRole>);
+    /** Whether no role was read. */
+    get isEmpty(): boolean;
+    /**
+     * Whether the token holds the role, from any source or only from the given ones.
+     */
+    hasRole(role: string, sources?: readonly AuthioResourceAccessSource[]): boolean;
+    /**
+     * Authio's grant rule: whether any role (from any source, or only from the given ones) allows `method` on
+     * `resource`.
+     */
+    grants(resource: string, method: string, sources?: readonly AuthioResourceAccessSource[]): boolean;
+    /**
+     * The roles that came from one source.
+     */
+    fromSource(source: AuthioResourceAccessSource): AuthioResourceAccessRole[];
+}
+/**
+ * The source a claim name stands for, when it is one of the seven `*_resource_access` claims.
+ */
+declare function resourceAccessSourceOf(claimType: string | undefined | null): AuthioResourceAccessSource | undefined;
+/**
+ * Reads the roles of every `*_resource_access` claim. Takes a JWT payload or introspection answer, or
+ * `[type, value]` pairs; each value may be the JSON object itself or its JSON text. Other claims are ignored.
+ */
+declare function parseResourceAccess(claims: Readonly<Record<string, unknown>> | Iterable<readonly [string, unknown]>): AuthioResourceAccess;
+/**
+ * Reads the roles of one claim value, as strictly as Authio does: a value that is not exactly
+ * `{role: {resource: [method]}}` contributes nothing at all. `null` roles, resources and methods are allowed and grant
+ * nothing.
+ */
+declare function parseResourceAccessClaim(source: AuthioResourceAccessSource, value: unknown): AuthioResourceAccessRole[];
+
+/**
+ * Why a webhook delivery failed verification.
+ */
+type AuthioWebhookVerificationFailure = "missing_signature" | "malformed_signature" | "signature_mismatch" | "timestamp_outside_tolerance";
+/**
+ * The outcome of verifying a webhook signature.
+ */
+type AuthioWebhookVerificationResult = {
+    readonly valid: true;
+    readonly timestamp: Date;
+} | {
+    readonly valid: false;
+    readonly failure: AuthioWebhookVerificationFailure;
+    readonly reason: string;
+    readonly timestamp?: Date;
+};
+/**
+ * A webhook event. `data` holds the event-specific payload; read it typed 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 data: unknown;
+    [member: string]: unknown;
+}
+/** `user_created`, `user_updated`, `user_deleted`. */
+interface AuthioWebhookUserData {
+    id: string;
+    username?: string;
+    email?: string;
+    first_name?: string;
+    last_name?: string;
+    email_confirmed: boolean;
+    status?: string;
+    realm_id?: string;
+    client_id?: string;
+}
+/** `login_succeeded`, `login_failed`. */
+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;
+}
+/** `user_locked_out`. */
+interface AuthioWebhookUserLockedOutData {
+    user_id: string;
+    username?: string;
+    email?: string;
+    lockout_end?: string;
+    access_failed_count: number;
+}
+/** `token_revoked`. */
+interface AuthioWebhookTokenRevokedData {
+    token_id?: string;
+    subject?: string;
+    session_id?: string;
+    token_type_hint?: string;
+}
+/** `keys_rotated`. */
+interface AuthioWebhookKeysRotatedData {
+    signing_key_id?: string;
+    encryption_key_id?: string;
+    revoked_keys_count?: number;
+    rotation_days?: number;
+    automatic?: boolean;
+}
+/** `token_reuse_detected`. */
+interface AuthioWebhookTokenReuseDetectedData {
+    token_id?: string;
+    subject?: string;
+    session_id?: string;
+    ip_address?: string;
+    user_agent?: string;
+}
+/** `admin_resource_created`, `admin_resource_updated`, `admin_resource_deleted`. */
+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`. */
+interface AuthioWebhookUserSuspensionData {
+    id: string;
+    user_id: string;
+    level?: string;
+    status?: string;
+    starts_at?: string;
+    ends_at?: string;
+    restricted_scopes: string[];
+    revokes_every_role: boolean;
+    revoked_role_ids: string[];
+    sessions_terminated_at?: string;
+    lifted_at?: string;
+}
+/** `ping`. */
+interface AuthioWebhookPingData {
+    message?: string;
+    subscription?: string;
+}
+/**
+ * The data shape of each event type.
+ */
+interface AuthioWebhookDataByType {
+    user_created: AuthioWebhookUserData;
+    user_updated: AuthioWebhookUserData;
+    user_deleted: AuthioWebhookUserData;
+    login_succeeded: AuthioWebhookLoginData;
+    login_failed: AuthioWebhookLoginData;
+    user_locked_out: AuthioWebhookUserLockedOutData;
+    token_revoked: AuthioWebhookTokenRevokedData;
+    keys_rotated: AuthioWebhookKeysRotatedData;
+    token_reuse_detected: AuthioWebhookTokenReuseDetectedData;
+    admin_resource_created: AuthioWebhookAdminResourceData;
+    admin_resource_updated: AuthioWebhookAdminResourceData;
+    admin_resource_deleted: AuthioWebhookAdminResourceData;
+    user_suspended: AuthioWebhookUserSuspensionData;
+    user_suspension_ended: AuthioWebhookUserSuspensionData;
+    ping: AuthioWebhookPingData;
+}
+/**
+ * An event narrowed to one type, with its data typed.
+ */
+type AuthioTypedWebhookEvent<T extends keyof AuthioWebhookDataByType> = AuthioWebhookEvent & {
+    readonly type: T;
+    readonly data: AuthioWebhookDataByType[T];
+};
+/**
+ * Verifies the `X-Authio-Signature` header (`t={unixSeconds},v1={hex}`) against the raw body: HMAC-SHA256 of
+ * `{t}.{body}` with the secret, compared in constant time, any matching `v1` accepted, the signature checked before
+ * the timestamp.
+ *
+ * @param signatureHeader The header value.
+ * @param rawBody The body exactly as received.
+ * @param secret The webhook's secret.
+ * @param options `tolerance` in seconds (default 300) and `now` in milliseconds (default the current time).
+ */
+declare function verifyWebhookSignature(signatureHeader: string | null | undefined, rawBody: string | Uint8Array, secret: string, options?: {
+    tolerance?: number;
+    now?: number;
+}): Promise<AuthioWebhookVerificationResult>;
+/**
+ * Computes the `X-Authio-Signature` value Authio would send, for tests and replays.
+ *
+ * @param timestamp Milliseconds since the epoch, or a date.
+ */
+declare function computeWebhookSignatureHeader(rawBody: string | Uint8Array, secret: string, timestamp: number | Date): Promise<string>;
+/**
+ * Parses a webhook body.
+ *
+ * @throws SyntaxError when it is not JSON or has no `type`.
+ */
+declare function parseWebhookEvent(rawBody: string | Uint8Array): AuthioWebhookEvent;
+/**
+ * Parses a webhook body, or returns `undefined` when it cannot be read.
+ */
+declare function tryParseWebhookEvent(rawBody: string | Uint8Array | null | undefined): AuthioWebhookEvent | undefined;
+/**
+ * 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;
+
+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 };