@hyper.authio/server 0.0.0-stage → 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,588 @@
+import { AuthioCallerKind, AuthioCredentialForm, AuthioResourceAccess, AuthioIntrospectionResult, AuthioResourceAccessSource, AuthioClock, AuthioError, AuthioTokenFailure, AuthioConnection, AuthioDiscoveryClient, AuthioClient, AuthioConnectionOptions, AuthioClientOptions, AuthioEncryptionKeySource, AuthioWebhookEvent, AuthioWebhookDataByType, AuthioTypedWebhookEvent, AuthioClientCredentialsToken } from '@hyper.authio/client';
+
+/**
+ * The party acting for the subject, from the `act` claim (RFC 8693): who exchanged the token, nested when the chain
+ * is longer.
+ */
+interface AuthioActor {
+    readonly clientId: string | undefined;
+    readonly subject: string | undefined;
+    /** `name`, on an impersonation: the administrator's display name. */
+    readonly name: string | undefined;
+    readonly actor: AuthioActor | undefined;
+}
+/**
+ * The administrator who impersonates the subject (an `act` with `sub` and no `client_id`).
+ */
+interface AuthioImpersonator {
+    readonly subject: string;
+    readonly name: string | undefined;
+}
+/**
+ * Where the user reads flat (non-`*_resource_access`) roles and groups from.
+ */
+interface AuthioUserClaimSettings {
+    /**
+     * Claims holding role names directly, such as one written by a claim mapper with the Role source. They count for
+     * `hasRole` without a source filter. Defaults to `["role"]`.
+     */
+    roleClaims?: readonly string[];
+    /**
+     * Claims holding group names, such as one written by a claim mapper with the Group source. Defaults to
+     * `["groups"]`.
+     */
+    groupClaims?: readonly string[];
+}
+/**
+ * The caller of an API, read from a validated access token or an introspection answer: identity, every form of
+ * permission Authio issues, and the raw claims for anything else.
+ */
+declare class AuthioUser {
+    /** `sub`: the person's id, or the credential's for a machine caller. */
+    readonly subject: string;
+    /**
+     * Who called: `user` (a person signed in), `client` (a client as itself), `consumer` (a machine consumer of a
+     * client) or `account_credential` (a credential of an Authio account).
+     */
+    readonly kind: AuthioCallerKind;
+    /**
+     * How a machine caller proved who it is (`client_secret`, `personal_access_token`, `api_key`,
+     * `consumer_api_key`); `undefined` for a person or a client.
+     */
+    readonly credentialForm: AuthioCredentialForm | undefined;
+    /** `consumer_name`, for a consumer. */
+    readonly consumerName: string | undefined;
+    /** `credential_name`, for an account credential. */
+    readonly credentialName: string | undefined;
+    /** `owner_user_id`: the person who made the credential. */
+    readonly ownerUserId: string | undefined;
+    /**
+     * `owner_username`: the person who made the credential. On an account credential Authio wrote it to
+     * `consumer_name` before, which is read when `owner_username` is absent.
+     */
+    readonly ownerUsername: string | undefined;
+    /** `credential_realm`: the one realm an account credential is limited to. */
+    readonly credentialRealm: string | undefined;
+    /** `credential_client`: the one client an account credential is limited to. */
+    readonly credentialClient: string | undefined;
+    /** Whether an administrator impersonates the subject. */
+    readonly impersonated: boolean;
+    /** The administrator impersonating the subject. */
+    readonly impersonator: AuthioImpersonator | undefined;
+    /** Whether a client acts for the subject through a delegation (`act` with `client_id`). */
+    readonly delegated: boolean;
+    /** The clients acting for the subject, outermost first. */
+    readonly actorChain: readonly string[];
+    /** `auth_time`, in seconds since the epoch. */
+    readonly authTime: number | undefined;
+    /** The client the token was issued to (`azp`, else `client_id`). */
+    readonly clientId: string | undefined;
+    /** `sid`. */
+    readonly sessionId: string | undefined;
+    /** `jti`. */
+    readonly tokenId: string | undefined;
+    /** `aud`. */
+    readonly audiences: readonly string[];
+    /** The granted scopes. */
+    readonly scopes: readonly string[];
+    /** The roles of the seven `*_resource_access` claims, with their source and permissions. */
+    readonly resourceAccess: AuthioResourceAccess;
+    /** Every role name: the `*_resource_access` roles, then the flat role claims. */
+    readonly roles: readonly string[];
+    /** Resource → every method any role allows on it. */
+    readonly permissions: Readonly<Record<string, readonly string[]>>;
+    /** The group names of the group claims. */
+    readonly groups: readonly string[];
+    /** `org_id`. */
+    readonly organizationId: string | undefined;
+    /** `org_alias`. */
+    readonly organizationAlias: string | undefined;
+    /** `account_id`. */
+    readonly accountId: string | undefined;
+    /** `acr`. */
+    readonly acr: string | undefined;
+    /** `acr` as a number: 1 one factor, 2 several, 3 one of them phishing-resistant. */
+    readonly authenticationLevel: number | undefined;
+    /** `amr`. */
+    readonly authenticationMethods: readonly string[];
+    /** `idp`. */
+    readonly identityProvider: string | undefined;
+    /** `auth_time`. */
+    readonly authenticatedAt: Date | undefined;
+    /** `act`. */
+    readonly actor: AuthioActor | undefined;
+    /** `delegation_id`. */
+    readonly delegationId: string | undefined;
+    readonly email: string | undefined;
+    readonly emailVerified: boolean | undefined;
+    readonly name: string | undefined;
+    readonly preferredUsername: string | undefined;
+    /** `credential_type`, on a token issued to an account credential or a consumer. */
+    readonly credentialType: string | undefined;
+    /** `credential_id`. */
+    readonly credentialId: string | undefined;
+    /** Every claim, as the token or the introspection answer carried it. */
+    readonly claims: Readonly<Record<string, unknown>>;
+    /** The access token the user was read from. Not enumerable, so it stays out of logs and JSON. */
+    readonly token: string | undefined;
+    private readonly flatRoles;
+    /**
+     * @param claims The token's payload, or the introspection answer's members.
+     * @param settings Where flat roles and groups are read from.
+     * @param token The access token, kept for forwarding and on-behalf-of.
+     * @param source Where the claims come from: a JWT (default) or an introspection answer. An introspection answer for
+     * a consumer that reports no `exp` and no `actor_type` is the consumer's API key (Authio reports no lifetime for a
+     * key), so its `credentialForm` is `consumer_api_key`.
+     */
+    constructor(claims: Readonly<Record<string, unknown>>, settings?: AuthioUserClaimSettings, token?: string, source?: "token" | "introspection");
+    /**
+     * Reads the caller from an introspection answer: `client_id` becomes `azp`, `username` becomes
+     * `preferred_username`, and `token_type` becomes `typ` unless it is `api_key` (a consumer's API key).
+     */
+    static fromIntrospection(result: AuthioIntrospectionResult, settings?: AuthioUserClaimSettings, token?: string): AuthioUser;
+    /** Whether the scope was granted. */
+    hasScope(scope: string): boolean;
+    /**
+     * Whether the user holds the role. Without sources, from any `*_resource_access` claim or a flat role claim; with
+     * sources, only from those `*_resource_access` claims.
+     */
+    hasRole(role: string, options?: {
+        sources?: readonly AuthioResourceAccessSource[];
+    }): boolean;
+    /**
+     * Authio's grant rule: whether a role (from any source, or only from the given ones) allows `method` on
+     * `resource`. Case-insensitive.
+     */
+    hasPermission(resource: string, method: string, options?: {
+        sources?: readonly AuthioResourceAccessSource[];
+    }): boolean;
+    /** Whether the user is in the group (exact match). */
+    hasGroup(group: string): boolean;
+    /**
+     * Whether the claim is present (not `null`), and, given values, whether it holds one of them (exact match; an
+     * array claim matches when any item does).
+     */
+    hasClaim(type: string, ...values: string[]): boolean;
+    /**
+     * The claim's values as text: one for a scalar, one per item for an array, JSON text for an object.
+     */
+    claimValues(type: string): string[];
+    /** Every member but the raw token. */
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * How several required values combine.
+ */
+type AuthioMatch = "any" | "all";
+/**
+ * Why a rule refused the caller.
+ */
+interface AuthioRuleFailure {
+    /** What is missing, in words. */
+    readonly message: string;
+    /**
+     * The RFC 6750 / RFC 9470 error to put in `WWW-Authenticate`: `insufficient_scope` for scopes,
+     * `insufficient_user_authentication` for `acr`/`amr`, none otherwise.
+     */
+    readonly error?: "insufficient_scope" | "insufficient_user_authentication";
+    /** The required scopes, for `insufficient_scope`. */
+    readonly scope?: string;
+    /** The context classes to ask for again, for `insufficient_user_authentication` (RFC 9470 `acr_values`). */
+    readonly acrValues?: string;
+    /** How old the sign-in may be, in seconds, for `insufficient_user_authentication` (RFC 9470 `max_age`). */
+    readonly maxAge?: number;
+}
+/**
+ * A condition on the caller.
+ */
+interface AuthioRule {
+    /** What the rule requires, for logs. */
+    readonly description: string;
+    /** `undefined` when the caller satisfies the rule, else why not. */
+    check(user: AuthioUser): AuthioRuleFailure | undefined;
+}
+/**
+ * Checks every rule. On refusal the message joins every rule's, and the error is the one asking for a stronger
+ * sign-in (with the strongest `acr_values` and the shortest `max_age` the failing rules ask for), else the first one
+ * that has an error.
+ */
+declare function authorize(user: AuthioUser, ...rules: AuthioRule[]): AuthioRuleFailure | undefined;
+/**
+ * Requires granted scopes.
+ */
+declare function requireScope(scopes: string | readonly string[], match?: AuthioMatch): AuthioRule;
+/**
+ * Requires roles, from any source or only from the given `*_resource_access` claims.
+ */
+declare function requireRole(roles: string | readonly string[], options?: {
+    match?: AuthioMatch;
+    sources?: readonly AuthioResourceAccessSource[];
+}): AuthioRule;
+/**
+ * Requires a permission (`method` on `resource`), granted by a role from any source or only from the given ones.
+ */
+declare function requirePermission(resource: string, method: string, options?: {
+    sources?: readonly AuthioResourceAccessSource[];
+}): AuthioRule;
+/**
+ * Requires groups, read from the group claims (a claim mapper with the Group source).
+ */
+declare function requireGroup(groups: string | readonly string[], match?: AuthioMatch): AuthioRule;
+/**
+ * Requires a claim: present, or holding one of the given values. Fits claim-mapper claims, the user's own claims and
+ * any other claim Authio issues.
+ */
+declare function requireClaim(type: string, ...values: string[]): AuthioRule;
+/**
+ * Requires an organization context, or a given organization (alias or id, case-insensitive).
+ */
+declare function requireOrganization(organization?: string): AuthioRule;
+/**
+ * Requires a minimum authentication level (`acr`): 1 one factor, 2 several, 3 one of them phishing-resistant. The
+ * refusal asks for that level again (`acr_values`), and for a sign-in at most `maxAge` seconds old when given.
+ */
+declare function requireAuthenticationLevel(minimumLevel: number, options?: {
+    maxAge?: number;
+    clock?: AuthioClock;
+}): AuthioRule;
+/**
+ * Requires authentication methods (`amr`, case-insensitive), such as `otp`, `swk` or `fed`. The refusal asks for the
+ * context class the methods imply (`2` for `mfa`/`otp`/`mca`, `3` for `swk`/`hwk`), or for `acrValues` when given.
+ */
+declare function requireAuthenticationMethod(methods: string | readonly string[], match?: AuthioMatch, options?: {
+    acrValues?: string;
+}): AuthioRule;
+/**
+ * Requires a sign-in at most `maxAge` seconds old (`auth_time`); the refusal asks for it with `max_age` (RFC 9470).
+ */
+declare function requireRecentAuthentication(maxAge: number, options?: {
+    clock?: AuthioClock;
+}): AuthioRule;
+/**
+ * Requires the caller to be of one of the kinds: `user`, `client`, `consumer`, `account_credential`.
+ */
+declare function requireCallerKind(kinds: AuthioCallerKind | readonly AuthioCallerKind[]): AuthioRule;
+/**
+ * Requires the token to have been issued to one of the clients (`azp`, else `client_id`).
+ */
+declare function requireClient(clientIds: string | readonly string[]): AuthioRule;
+/**
+ * Requires every rule.
+ */
+declare function allOf(...rules: AuthioRule[]): AuthioRule;
+/**
+ * Requires at least one rule; the refusal is the first rule's.
+ */
+declare function anyOf(...rules: AuthioRule[]): AuthioRule;
+
+/**
+ * The request carries no valid access token: answer `401` with `wwwAuthenticate`.
+ */
+declare class AuthioBearerError extends AuthioError {
+    readonly status = 401;
+    /** `invalid_token`, or `undefined` when the request had no token at all (RFC 6750 §3.1). */
+    readonly error: "invalid_token" | undefined;
+    /** Why the token was refused, safe to send to the caller. */
+    readonly description: string | undefined;
+    /** Why the token was refused, as a stable code; `undefined` when there was no token or Authio could not be asked. */
+    readonly reason: AuthioTokenFailure | "inactive" | "unconfirmed" | undefined;
+    /** The API's protected resource metadata URL (RFC 9728), sent as `resource_metadata` when configured. */
+    readonly resourceMetadata: string | undefined;
+    constructor(description: string | undefined, options?: {
+        error?: "invalid_token" | undefined;
+        cause?: unknown;
+        reason?: AuthioTokenFailure | "inactive" | "unconfirmed";
+        resourceMetadata?: string;
+    });
+    /** The same refusal, pointing at the API's protected resource metadata. */
+    withResourceMetadata(resourceMetadata: string | undefined): AuthioBearerError;
+    /** The `WWW-Authenticate` value. */
+    get wwwAuthenticate(): string;
+}
+/**
+ * The caller is known but not allowed: answer `403`, with `wwwAuthenticate` when the refusal has a bearer error.
+ */
+declare class AuthioForbiddenError extends AuthioError {
+    readonly status = 403;
+    readonly failure: AuthioRuleFailure;
+    constructor(failure: AuthioRuleFailure);
+    /** The `WWW-Authenticate` value, or `undefined` when the refusal is not about scopes or the sign-in. */
+    get wwwAuthenticate(): string | undefined;
+}
+/**
+ * The `WWW-Authenticate` value of a refusal: `insufficient_scope` (with `scope`) or `insufficient_user_authentication`
+ * (with `acr_values` and `max_age`, RFC 9470).
+ */
+declare function toForbiddenChallenge(failure: AuthioRuleFailure): string | undefined;
+/**
+ * Problem details (RFC 9457) for a `401` or `403`.
+ */
+declare function toProblemDetails(error: AuthioBearerError | AuthioForbiddenError): Record<string, unknown>;
+
+/**
+ * Whether and how Authio's introspection endpoint takes part in validating a token.
+ *
+ * - `none`: the JWT is validated locally (signature, issuer, audience, lifetime). Fastest; a revoked token stays
+ *   valid until it expires.
+ * - `activeCheck`: validated locally, then confirmed active by introspection (cached per `jti`).
+ * - `introspectionOnly`: introspection alone, for opaque (reference) tokens, or encrypted ones without the key.
+ */
+type AuthioIntrospectionMode = "none" | "activeCheck" | "introspectionOnly";
+/**
+ * How an API validates Authio access tokens.
+ */
+interface AuthioVerifierOptions extends AuthioConnectionOptions, AuthioUserClaimSettings {
+    /** The audiences this API accepts: its resource identifier (RFC 8707) or client id. Required unless `resource` is set. */
+    audiences?: string | readonly string[];
+    /**
+     * The API's own resource identifier (RFC 8707), such as `https://orders.example.com`. Added to `audiences`, and
+     * the `resource` of its protected resource metadata (RFC 9728).
+     */
+    resource?: string;
+    /**
+     * Points `401` challenges at the API's protected resource metadata (RFC 9728) with `resource_metadata`: `true`
+     * for `{origin of resource}/.well-known/oauth-protected-resource{path of resource}`, or the URL itself. Off by default.
+     */
+    resourceMetadata?: boolean | string;
+    /** Scopes every request must carry (all of them); `authioBearer` answers `403 insufficient_scope` otherwise. */
+    requiredScopes?: readonly string[];
+    /** Defaults to `none`. */
+    introspection?: AuthioIntrospectionMode;
+    /**
+     * The API's confidential client, for introspection: a client already created, or its options (issuer settings are
+     * taken from these options when absent). It must be the client the resource server names as its introspection
+     * client, since Authio answers introspection according to who asks.
+     */
+    client?: AuthioClient | Omit<AuthioClientOptions, keyof AuthioConnectionOptions>;
+    /** Seconds an active introspection answer is kept (never past the token's expiry). Defaults to 30. */
+    introspectionCacheDuration?: number;
+    /** Seconds of clock skew tolerated on `exp` and `nbf`. Defaults to 30. */
+    clockSkew?: number;
+    /** Accepted signing algorithms. Defaults to the asymmetric ones (RS*, PS*, ES*). */
+    validAlgorithms?: readonly string[];
+    /** Refuses a token whose `typ` claim is present and not `Bearer` (an ID token, for one). Defaults to `true`. */
+    rejectNonAccessTokens?: boolean;
+    /**
+     * The private half of the encryption key Authio encrypts this API's access tokens to (the resource server's or its
+     * client's), so encrypted tokens are decrypted and validated locally (RSA-OAEP, RSA-OAEP-256).
+     */
+    clientEncryptionKey?: AuthioEncryptionKeySource;
+    /** A PEM or JWK file holding `clientEncryptionKey` (Node only). */
+    clientEncryptionKeyPath?: string;
+    /** Accepted for parity with the other Authio SDKs; RSA1_5 stays refused, because Node cannot decrypt it. */
+    allowLegacyEncryptionAlgorithms?: boolean;
+}
+/**
+ * Validates Authio access tokens and reads the caller.
+ */
+interface AuthioVerifier {
+    /** The connection settings. */
+    readonly connection: AuthioConnection;
+    /** The discovery document. */
+    readonly discovery: AuthioDiscoveryClient;
+    /** The accepted audiences. */
+    readonly audiences: readonly string[];
+    /** The API's resource identifier, when configured. */
+    readonly resource: string | undefined;
+    /** The protected resource metadata URL sent in challenges, when turned on. */
+    readonly resourceMetadataUrl: string | undefined;
+    /** Scopes every request must carry. */
+    readonly requiredScopes: readonly string[];
+    /** The introspection mode. */
+    readonly introspection: AuthioIntrospectionMode;
+    /** The client used for introspection, when there is one. */
+    readonly client: AuthioClient | undefined;
+    /**
+     * Validates a token and reads the caller.
+     *
+     * @throws AuthioBearerError when the token is not valid for this API.
+     */
+    verify(token: string, signal?: AbortSignal): Promise<AuthioUser>;
+    /**
+     * Validates the token of an `Authorization: Bearer` header.
+     *
+     * @throws AuthioBearerError without an error code when there is no bearer token, with `invalid_token` when it is
+     * not valid.
+     */
+    verifyAuthorizationHeader(header: string | null | undefined, signal?: AbortSignal): Promise<AuthioUser>;
+}
+/**
+ * Error descriptions of the refusals the SDK makes itself.
+ */
+declare const AuthioBearerErrorDescriptions: {
+    readonly Inactive: "Authio reports the token as not active to this API's client. It was revoked or has expired or its session ended; or this API's client is not the introspection client of the resource server the token is for.";
+    readonly Unconfirmed: "Authio could not be reached to confirm that the token is active.";
+    readonly Empty: "The token is empty.";
+    readonly Encrypted: "The token is encrypted; set clientEncryptionKey to decrypt it, or validate it with introspection ('introspectionOnly').";
+    readonly SigningKeysUnavailable: "Authio could not be reached to read its signing keys.";
+};
+/**
+ * Creates a token verifier.
+ *
+ * @throws AuthioConfigurationError when no audience is given, or introspection is asked for without a client.
+ */
+declare function createAuthioVerifier(options: AuthioVerifierOptions): AuthioVerifier;
+/**
+ * The token of an `Authorization: Bearer` header, or `undefined` when the header is absent or of another scheme.
+ */
+declare function readBearerToken(header: string | null | undefined): string | undefined;
+
+/**
+ * What an API publishes about itself as a protected resource (RFC 9728).
+ */
+interface AuthioProtectedResourceMetadataOptions extends Pick<AuthioConnectionOptions, "issuer" | "authority" | "realm"> {
+    /** The API's resource identifier (RFC 8707), such as `https://orders.example.com/api`. Required. */
+    resource: string;
+    /** Scopes a client can ask for to call the API. */
+    scopesSupported?: readonly string[];
+    /** A name to show to people. */
+    resourceName?: string;
+    /** A page documenting the API. */
+    resourceDocumentation?: string;
+    /** Further members, sent as given. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * The protected resource metadata document (RFC 9728 §2).
+ */
+interface AuthioProtectedResourceMetadata {
+    resource: string;
+    authorization_servers: string[];
+    bearer_methods_supported: string[];
+    scopes_supported?: string[];
+    resource_name?: string;
+    resource_documentation?: string;
+    [member: string]: unknown;
+}
+/**
+ * Where a resource's metadata is published: `{origin}/.well-known/oauth-protected-resource{path}` (RFC 9728 §3.1),
+ * the path being the resource's own, without a trailing slash.
+ */
+declare function protectedResourceMetadataUrl(resource: string): string;
+/**
+ * The path a resource's metadata is served at on the API itself: `/.well-known/oauth-protected-resource{path}`.
+ */
+declare function protectedResourceMetadataPath(resource: string): string;
+/**
+ * Builds the API's protected resource metadata: the resource, the realm's issuer as its authorization server, bearer
+ * tokens in the `Authorization` header, and the optional scopes, name and documentation.
+ */
+declare function createProtectedResourceMetadata(options: AuthioProtectedResourceMetadataOptions): AuthioProtectedResourceMetadata;
+
+/**
+ * Remembers delivered event ids, so a redelivery is acknowledged without running the handlers twice.
+ */
+interface AuthioWebhookDeduplicationStore {
+    /** Records the id; `false` when it was already recorded within the window. */
+    tryBegin(eventId: string, windowMs: number): boolean | Promise<boolean>;
+    /** Forgets the id, after a handler failed, so the redelivery runs again. */
+    release(eventId: string): void | Promise<void>;
+}
+/**
+ * How webhook deliveries are received.
+ */
+interface AuthioWebhookOptions {
+    /** The webhook's secret. */
+    secret?: string;
+    /** Several secrets, while one is being rotated; a delivery signed with any of them is accepted. */
+    secrets?: readonly string[];
+    /** Seconds a signature's timestamp may differ from now. Defaults to 300. */
+    tolerance?: number;
+    /** `memory` (default), `none`, or a store shared between instances. */
+    deduplication?: "memory" | "none" | AuthioWebhookDeduplicationStore;
+    /** Seconds a delivered id is remembered. Defaults to 86400. */
+    deduplicationWindow?: number;
+    /** The largest body accepted, in bytes. Defaults to 1 MiB. */
+    maxBodySize?: number;
+    /** The clock. */
+    clock?: AuthioClock;
+    /** Called when a delivery is refused or a handler fails. */
+    onError?: (error: unknown, context: {
+        reason: string;
+        eventId?: string;
+        eventType?: string;
+    }) => void;
+}
+/**
+ * A handler of one event type, or of every type.
+ */
+type AuthioWebhookHandler<E extends AuthioWebhookEvent = AuthioWebhookEvent> = (event: E) => void | Promise<void>;
+/**
+ * What to answer a delivery with.
+ */
+interface AuthioWebhookOutcome {
+    /** `200` handled, duplicate or ping; `400` unreadable; `401` bad or stale signature; `413` too large; `500` a handler failed. */
+    readonly status: 200 | 400 | 401 | 413 | 500;
+    /** Why, for logs. */
+    readonly reason: "handled" | "duplicate" | "unreadable" | "unsigned" | "too_large" | "handler_failed";
+    readonly event?: AuthioWebhookEvent;
+}
+/**
+ * Receives Authio webhook deliveries: verifies, deduplicates and dispatches them.
+ */
+interface AuthioWebhooks {
+    /** Handles one event type, typed. */
+    on<T extends keyof AuthioWebhookDataByType>(type: T, handler: AuthioWebhookHandler<AuthioTypedWebhookEvent<T>>): AuthioWebhooks;
+    /** Handles another event type, or `*` for every type. */
+    on(type: string, handler: AuthioWebhookHandler): AuthioWebhooks;
+    /**
+     * Handles a delivery: the body exactly as received and the request headers.
+     */
+    handle(delivery: {
+        body: string | Uint8Array;
+        headers: Headers | Record<string, string | string[] | undefined>;
+    }): Promise<AuthioWebhookOutcome>;
+    /** The largest body accepted, in bytes. */
+    readonly maxBodySize: number;
+}
+/**
+ * Creates a webhook receiver. Handlers run in registration order; a `*` handler sees every event.
+ *
+ * @throws AuthioConfigurationError when no secret is configured.
+ */
+declare function createAuthioWebhooks(options: AuthioWebhookOptions): AuthioWebhooks;
+/**
+ * A deduplication store kept in this process's memory.
+ */
+declare function createMemoryDeduplicationStore(clock?: AuthioClock): AuthioWebhookDeduplicationStore;
+
+/**
+ * Who a downstream call is made for: a caller read by the verifier, or the incoming access token itself.
+ */
+type AuthioDownstreamSubject = AuthioUser | string;
+/**
+ * A `fetch` that forwards the caller's own access token, unchanged, to a downstream API that accepts the same
+ * audience. Sends no `Authorization` when there is no token.
+ */
+declare function createForwardingFetch(subject: AuthioDownstreamSubject | undefined, inner?: typeof fetch): typeof fetch;
+/**
+ * Exchanges the caller's token for one addressed to a downstream API (RFC 8693), and caches it.
+ */
+interface AuthioOnBehalfOf {
+    /**
+     * A token for the downstream API on the caller's behalf: cached per incoming `jti` (else token hash), resource and
+     * sorted scopes, renewed `tokenRefreshSkew` before expiry (at most half its lifetime); concurrent callers share
+     * one exchange.
+     *
+     * @throws AuthioError when there is no incoming token.
+     */
+    getToken(subject: AuthioDownstreamSubject | undefined, signal?: AbortSignal): Promise<AuthioClientCredentialsToken>;
+    /** Drops a cached token; with `accessToken`, only when the cache still holds that token. */
+    invalidate(subject: AuthioDownstreamSubject, accessToken?: string): Promise<void>;
+    /** A `fetch` that sends the exchanged token, and on a `401` drops it and retries once. */
+    fetch(subject: AuthioDownstreamSubject | undefined, inner?: typeof fetch): typeof fetch;
+}
+/**
+ * Creates an on-behalf-of exchanger.
+ *
+ * @param options `client` (the API's confidential client), the downstream `resource` and `scopes`.
+ */
+declare function createOnBehalfOf(options: {
+    client: AuthioClient;
+    resource?: string;
+    scopes?: Iterable<string> | string;
+    tokenRefreshSkew?: number;
+}): AuthioOnBehalfOf;
+
+export { type AuthioActor, AuthioBearerError, AuthioBearerErrorDescriptions, type AuthioDownstreamSubject, AuthioForbiddenError, type AuthioImpersonator, type AuthioIntrospectionMode, type AuthioMatch, type AuthioOnBehalfOf, type AuthioProtectedResourceMetadata, type AuthioProtectedResourceMetadataOptions, type AuthioRule, type AuthioRuleFailure, AuthioUser, type AuthioUserClaimSettings, type AuthioVerifier, type AuthioVerifierOptions, type AuthioWebhookDeduplicationStore, type AuthioWebhookHandler, type AuthioWebhookOptions, type AuthioWebhookOutcome, type AuthioWebhooks, allOf, anyOf, authorize, createAuthioVerifier, createAuthioWebhooks, createForwardingFetch, createMemoryDeduplicationStore, createOnBehalfOf, createProtectedResourceMetadata, protectedResourceMetadataPath, protectedResourceMetadataUrl, readBearerToken, requireAuthenticationLevel, requireAuthenticationMethod, requireCallerKind, requireClaim, requireClient, requireGroup, requireOrganization, requirePermission, requireRecentAuthentication, requireRole, requireScope, toForbiddenChallenge, toProblemDetails };