@udibo/oauth2 0.1.0

package/esm/identity/captcha.js

@@ -0,0 +1,64 @@
+/**
+ * Bring-your-own bot-challenge verification for auth endpoints — the CAPTCHA
+ * analogue of the {@link RateLimiterLike} seam. {@link CaptchaProvider} is the
+ * contract a client-issued challenge token is verified against server-side;
+ * Cloudflare Turnstile, hCaptcha, and reCAPTCHA all satisfy it, so nothing here
+ * depends on a vendor SDK. {@link verifyCaptcha} composes a provider with the
+ * fail-open/closed discipline a login flow needs: a missing or rejected token
+ * is a refusal, but a provider *outage* degrades to your existing rate-limit and
+ * lockout floor rather than locking everyone out.
+ *
+ * Tenant-agnostic: scope by passing whatever `action` and `ip` your provider
+ * scores on. **No provider means no challenge** — {@link verifyCaptcha} passes
+ * every request, so wiring the seam without configuring a provider changes
+ * nothing about existing behavior.
+ *
+ * @module
+ */
+/**
+ * Verify a client-issued CAPTCHA token with the fail-open/closed discipline an
+ * auth endpoint needs, and return a {@link CaptchaOutcome}.
+ *
+ * - **No provider** → unchallenged `"pass"` (`challenged: false`).
+ * - **Missing/empty token** → `"fail"` (the challenge went unanswered).
+ * - **Provider `{ success }`** → `"pass"`/`"fail"` accordingly.
+ * - **Provider throws (outage)** → `failOpen` decides `"pass"` or `"fail"`;
+ *   either way the outcome is `degraded: true`, because no token was really
+ *   evaluated.
+ *
+ * Never throws — a broken provider becomes a decision, not an exception the
+ * route must catch. Compose the result with your rate limiter and lockout; this
+ * does not replace them.
+ *
+ * @example
+ * ```ts
+ * const outcome = await verifyCaptcha({ provider, token, context: { ip, action: "signin" } });
+ * if (outcome.decision === "fail") return uniformRejection();
+ * ```
+ */
+export async function verifyCaptcha(options) {
+    const { provider, token, context } = options;
+    const failOpen = options.failOpen ?? true;
+    if (!provider) {
+        return { decision: "pass", challenged: false, degraded: false };
+    }
+    if (!token)
+        return { decision: "fail", challenged: true, degraded: false };
+    try {
+        const result = await provider.verify(token, context);
+        return {
+            decision: result.success ? "pass" : "fail",
+            challenged: true,
+            score: result.score,
+            degraded: false,
+        };
+    }
+    catch (error) {
+        console.error("[@udibo/oauth2] captcha provider verify failed (%s):", failOpen ? "fail-open, allowing" : "fail-closed, refusing", error instanceof Error ? error.message : error);
+        return {
+            decision: failOpen ? "pass" : "fail",
+            challenged: true,
+            degraded: true,
+        };
+    }
+}

package/esm/identity/delivery.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Delivery seam for identity self-service messages (verification, reset, and
+ * passwordless sign-in links, plus one-time sign-in codes).
+ *
+ * The library owns the **token lifecycle** ({@link TokenFlowService}); your app
+ * owns **transport** — SMTP, SES, Resend, Twilio, etc. So delivery is a set of
+ * app-supplied async hooks, and the package ships URL builders so apps stop
+ * hand-assembling `${protocol}://${host}/verify-email?token=…` strings. This is
+ * the Better Auth model (`sendVerificationEmail` / `sendResetPassword`).
+ *
+ * @module
+ */
+/** What a delivery hook receives for one message. */
+export interface DeliveryMessage {
+    /** Recipient — an email address or phone number. */
+    to: string;
+    /**
+     * The ready-to-use action link (already carrying the token), when the caller
+     * built one via {@link buildVerificationUrl} / {@link buildResetUrl}. Absent
+     * if you'd rather build the message body from `token` yourself.
+     */
+    url?: string;
+    /** The raw token, for apps that compose their own URL or message. */
+    token: string;
+    /** The subject the token acts on (typically a user id). */
+    subject: string;
+    /** Token expiry, epoch ms. */
+    expiresAt: number;
+}
+/** A single delivery transport callback. */
+export type DeliveryHook = (message: DeliveryMessage) => Promise<void> | void;
+/**
+ * What a code-delivery hook receives for one message. Unlike a
+ * {@link DeliveryMessage} there is no URL — a one-time code is typed in, not
+ * clicked — and the raw `code` is the whole payload.
+ */
+export interface CodeDeliveryMessage {
+    /** Recipient — an email address or phone number. */
+    to: string;
+    /** The one-time code to include in the message body, e.g. `"482913"`. */
+    code: string;
+    /** The subject the code signs in (typically a user id). */
+    subject: string;
+    /** Code expiry, epoch ms. */
+    expiresAt: number;
+}
+/** A delivery transport callback for one-time codes. */
+export type CodeDeliveryHook = (message: CodeDeliveryMessage) => Promise<void> | void;
+/**
+ * App-supplied delivery transports. Omit a hook to disable that message type.
+ * The package calls the relevant hook after minting the token; you send it.
+ *
+ * Trigger point `delivery` (see `docs/trigger-points.md`). The package calls a
+ * hook after minting the credential; a **throw** (e.g. a mailer outage) is
+ * trapped for every hook here: `IdentityService` invalidates the just-minted
+ * token or code — best effort, so a failed send does not leave a live,
+ * un-emailed credential in your store — and the requesting flow still resolves
+ * with its uniform result, so a transport outage cannot become an
+ * account-enumeration oracle. Handle transport failures inside the hook (log,
+ * retry, queue) if you need to observe or recover from them; the flow will not
+ * surface the throw to your caller.
+ *
+ * Every trapped failure emits the `delivery.failed` identity event, carrying the
+ * hook and an `invalidated` flag. `invalidated: false` means the cleanup failed
+ * too and a credential the recipient never received is live until it expires —
+ * the one case that needs an alert, and only your `onEvent` hook can see it.
+ */
+export interface DeliveryHooks {
+    /** Deliver an email-verification link. */
+    sendEmailVerification?: DeliveryHook;
+    /** Deliver a password-reset link. */
+    sendPasswordReset?: DeliveryHook;
+    /** Deliver an account-unlock link after a failed-attempt lockout. */
+    sendAccountUnlock?: DeliveryHook;
+    /** Deliver a passwordless sign-in (magic) link. */
+    sendSignInLink?: DeliveryHook;
+    /** Deliver a one-time sign-in code (no URL; the user types the code in). */
+    sendSignInCode?: CodeDeliveryHook;
+}
+/**
+ * Build an absolute action URL that embeds a token as a query parameter.
+ *
+ * @param base An origin (e.g. `https://app.example`) or origin + path prefix.
+ * @param path The route the token is consumed at (e.g. `/reset-password`).
+ * @param token The raw token to embed.
+ * @param param The query parameter name. Defaults to `"token"`.
+ */
+export declare function buildTokenUrl(base: string, path: string, token: string, param?: string): string;
+/** Build an email-verification URL (default path `/verify-email`). */
+export declare function buildVerificationUrl(base: string, token: string, path?: string): string;
+/** Build a password-reset URL (default path `/reset-password`). */
+export declare function buildResetUrl(base: string, token: string, path?: string): string;
+/** Build a passwordless sign-in (magic-link) URL (default path `/signin-link`). */
+export declare function buildSignInUrl(base: string, token: string, path?: string): string;
+/** Build an account-unlock URL (default path `/unlock-account`). */
+export declare function buildUnlockUrl(base: string, token: string, path?: string): string;

package/esm/identity/delivery.js

@@ -0,0 +1,41 @@
+/**
+ * Delivery seam for identity self-service messages (verification, reset, and
+ * passwordless sign-in links, plus one-time sign-in codes).
+ *
+ * The library owns the **token lifecycle** ({@link TokenFlowService}); your app
+ * owns **transport** — SMTP, SES, Resend, Twilio, etc. So delivery is a set of
+ * app-supplied async hooks, and the package ships URL builders so apps stop
+ * hand-assembling `${protocol}://${host}/verify-email?token=…` strings. This is
+ * the Better Auth model (`sendVerificationEmail` / `sendResetPassword`).
+ *
+ * @module
+ */
+/**
+ * Build an absolute action URL that embeds a token as a query parameter.
+ *
+ * @param base An origin (e.g. `https://app.example`) or origin + path prefix.
+ * @param path The route the token is consumed at (e.g. `/reset-password`).
+ * @param token The raw token to embed.
+ * @param param The query parameter name. Defaults to `"token"`.
+ */
+export function buildTokenUrl(base, path, token, param = "token") {
+    const url = new URL(path, base);
+    url.searchParams.set(param, token);
+    return url.toString();
+}
+/** Build an email-verification URL (default path `/verify-email`). */
+export function buildVerificationUrl(base, token, path = "/verify-email") {
+    return buildTokenUrl(base, path, token);
+}
+/** Build a password-reset URL (default path `/reset-password`). */
+export function buildResetUrl(base, token, path = "/reset-password") {
+    return buildTokenUrl(base, path, token);
+}
+/** Build a passwordless sign-in (magic-link) URL (default path `/signin-link`). */
+export function buildSignInUrl(base, token, path = "/signin-link") {
+    return buildTokenUrl(base, path, token);
+}
+/** Build an account-unlock URL (default path `/unlock-account`). */
+export function buildUnlockUrl(base, token, path = "/unlock-account") {
+    return buildTokenUrl(base, path, token);
+}

package/esm/identity/errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A stable error contract for identity flows, so a front-end can switch on a
+ * code instead of parsing messages, and the Hono route factory can map errors
+ * to consistent responses.
+ *
+ * @module
+ */
+/**
+ * Stable, machine-readable identity error codes. Most are raised by your store
+ * or the service; `forbidden_origin` is raised by the Hono route factory's
+ * same-origin guard before a handler runs.
+ */
+export type IdentityErrorCode = "invalid_credentials" | "invalid_token" | "rate_limited" | "weak_password" | "identifier_taken" | "email_not_verified" | "mfa_not_enrolled" | "mfa_already_enrolled" | "captcha_failed" | "forbidden_origin";
+/** Options for {@link IdentityError}. */
+export interface IdentityErrorOptions extends ErrorOptions {
+    /** For `rate_limited`: milliseconds until the caller may retry. */
+    retryAfterMs?: number;
+}
+/**
+ * A typed error for identity flows. Throw it from your `IdentityUserStore`
+ * (e.g. `identifier_taken` on a duplicate) or your own validation; the Hono
+ * route factory maps it to `{ error: code }` with the right status.
+ */
+export declare class IdentityError extends Error {
+    /** Always `"IdentityError"`, so instances are recognizable across realms. */
+    readonly name = "IdentityError";
+    /** The stable, machine-readable code a client can switch on. */
+    readonly code: IdentityErrorCode;
+    /** For `rate_limited`: ms until retry, if known. */
+    readonly retryAfterMs?: number;
+    /** Builds an identity error; `message` defaults to the `code` when omitted. */
+    constructor(code: IdentityErrorCode, message?: string, options?: IdentityErrorOptions);
+}
+/** Type guard for {@link IdentityError}. */
+export declare function isIdentityError(value: unknown): value is IdentityError;
+/** The HTTP statuses an identity error maps to (a `ContentfulStatusCode` union). */
+export type IdentityErrorStatus = 400 | 401 | 403 | 409 | 422 | 429;
+/** The HTTP status conventionally paired with an identity error code. */
+export declare function identityErrorStatus(code: IdentityErrorCode): IdentityErrorStatus;

package/esm/identity/errors.js

@@ -0,0 +1,46 @@
+/**
+ * A stable error contract for identity flows, so a front-end can switch on a
+ * code instead of parsing messages, and the Hono route factory can map errors
+ * to consistent responses.
+ *
+ * @module
+ */
+/**
+ * A typed error for identity flows. Throw it from your `IdentityUserStore`
+ * (e.g. `identifier_taken` on a duplicate) or your own validation; the Hono
+ * route factory maps it to `{ error: code }` with the right status.
+ */
+export class IdentityError extends Error {
+    /** Always `"IdentityError"`, so instances are recognizable across realms. */
+    name = "IdentityError";
+    /** The stable, machine-readable code a client can switch on. */
+    code;
+    /** For `rate_limited`: ms until retry, if known. */
+    retryAfterMs;
+    /** Builds an identity error; `message` defaults to the `code` when omitted. */
+    constructor(code, message, options) {
+        super(message ?? code, options);
+        this.code = code;
+        this.retryAfterMs = options?.retryAfterMs;
+    }
+}
+/** Type guard for {@link IdentityError}. */
+export function isIdentityError(value) {
+    return value instanceof IdentityError;
+}
+const STATUS = {
+    invalid_credentials: 401,
+    invalid_token: 400,
+    rate_limited: 429,
+    weak_password: 422,
+    identifier_taken: 409,
+    email_not_verified: 403,
+    mfa_not_enrolled: 409,
+    mfa_already_enrolled: 409,
+    captcha_failed: 403,
+    forbidden_origin: 403,
+};
+/** The HTTP status conventionally paired with an identity error code. */
+export function identityErrorStatus(code) {
+    return STATUS[code] ?? 400;
+}

package/esm/identity/events.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Identity flow events — the observability seam for audit capture.
+ *
+ * {@link IdentityService} emits an {@link IdentityEvent} after each significant
+ * auth outcome (sign-in success/failure, sign-up, credential upgrade-on-login,
+ * reset and verification lifecycle, passwordless sign-in links and codes),
+ * `MfaService` emits the `mfa.*` events, and a password-policy validator emits
+ * `password_policy.check_unavailable` when it cannot complete its check. Wire
+ * an {@link IdentityEventHook} via the service's `onEvent`
+ * option to persist them in your own audit store — storage stays app-owned,
+ * like every other seam in this layer.
+ *
+ * Some outcomes are *only* visible here, because the flow that produced them
+ * resolves uniformly by design: `delivery.failed` is the sole in-band signal
+ * that a message never went out (and, when `invalidated` is `false`, that a
+ * live credential the user never received is still outstanding). Treat this
+ * hook as a monitored surface, not just an audit log.
+ *
+ * Events describe internal outcomes (including whether an identifier resolved
+ * to an account), so they are for server-side capture only — never surface
+ * their contents to the end user, or they become an enumeration oracle.
+ *
+ * @module
+ */
+import type { DeliveryHooks } from "./delivery.js";
+/** Why a sign-in attempt failed. Internal detail — never shown to the user. */
+export type SignInFailureReason = "unknown_identifier" | "no_password" | "wrong_password";
+/**
+ * Why a sign-in code verification failed. `unknown_email` is internal-only
+ * detail — the caller-facing result reports it as `invalid`.
+ */
+export type SignInCodeFailureReason = "invalid" | "expired" | "locked" | "unknown_email";
+/**
+ * An auth outcome emitted by {@link IdentityService}, `MfaService`, or a
+ * password-policy validator. Discriminated on `type`; `userId` is present when
+ * the flow resolved an account.
+ */
+export type IdentityEvent = {
+    type: "sign_in.succeeded";
+    userId: string;
+    identifier: string;
+} | {
+    type: "sign_in.failed";
+    identifier: string;
+    reason: SignInFailureReason;
+    userId?: string;
+} | {
+    type: "sign_in.rate_limited";
+    identifier: string;
+    retryAfterMs: number;
+    enforced: boolean;
+} | {
+    type: "sign_in.locked";
+    userId: string;
+    identifier: string;
+    enforced: boolean;
+} | {
+    type: "lockout";
+    userId: string;
+    identifier: string;
+    failures: number;
+    lockedUntil?: number;
+    enforced: boolean;
+} | {
+    type: "account_unlock.requested";
+    userId: string;
+    email: string;
+} | {
+    type: "account_unlock.rate_limited";
+    userId: string;
+    email: string;
+    retryAfterMs: number;
+    enforced: boolean;
+} | {
+    type: "account_unlock.completed";
+    userId: string;
+} | {
+    type: "account_unlock.failed";
+    reason: "expired" | "invalid";
+} | {
+    type: "sign_up";
+    userId: string;
+} | {
+    type: "password.upgraded";
+    userId: string;
+    verifierId: string;
+} | {
+    type: "password_policy.check_unavailable";
+    /**
+     * Which {@link PasswordPolicy} validator could not finish, as a stable
+     * snake_case name. {@link breachedPasswordValidator} reports
+     * `"breached_password"`.
+     */
+    validator: string;
+    /**
+     * `true` when the password was accepted anyway (the validator's `failOpen`
+     * default), `false` when it was rejected instead. A run of `true` is a
+     * control that stopped running — the question this event exists to answer.
+     */
+    failedOpen: boolean;
+    /**
+     * The underlying failure's message — a timeout, a DNS or egress-policy
+     * refusal, a non-2xx status from the upstream service.
+     */
+    error: string;
+} | {
+    type: "password_reset.requested";
+    email: string;
+    userId?: string;
+} | {
+    type: "password_reset.rate_limited";
+    email: string;
+    retryAfterMs: number;
+    enforced: boolean;
+} | {
+    type: "password_reset.completed";
+    userId: string;
+} | {
+    type: "password_reset.failed";
+    /**
+     * `"invalid_token"` — the reset link was unknown, expired, or already used.
+     * `"session_revocation_failed"` — the new password was set but the
+     * configured {@link RevocableSessionService} threw before the user's other
+     * sessions could be revoked, so the reset is reported failed (and rethrown)
+     * rather than trusted; retry it so the still-live sessions are cleared.
+     */
+    reason: "invalid_token" | "session_revocation_failed";
+} | {
+    type: "email_verification.requested";
+    userId: string;
+    email: string;
+} | {
+    type: "email_verification.rate_limited";
+    userId: string;
+    email: string;
+    retryAfterMs: number;
+    enforced: boolean;
+} | {
+    type: "email_verification.completed";
+    userId: string;
+    email?: string;
+} | {
+    type: "email_verification.failed";
+    reason: "expired" | "invalid";
+} | {
+    type: "signin_link.requested";
+    email: string;
+    userId?: string;
+} | {
+    type: "signin_link.consumed";
+    userId: string;
+} | {
+    type: "signin_link.failed";
+    reason: "expired" | "invalid";
+} | {
+    type: "signin_link.rate_limited";
+    email: string;
+    retryAfterMs?: number;
+    enforced: boolean;
+} | {
+    type: "signin_code.requested";
+    email: string;
+    userId?: string;
+} | {
+    type: "signin_code.verified";
+    userId: string;
+} | {
+    type: "signin_code.failed";
+    email: string;
+    reason: SignInCodeFailureReason;
+} | {
+    type: "signin_code.rate_limited";
+    email: string;
+    retryAfterMs?: number;
+    enforced: boolean;
+} | {
+    type: "delivery.failed";
+    /** Which {@link DeliveryHooks} hook threw. */
+    hook: keyof DeliveryHooks;
+    /**
+     * `true` when the just-minted token or code was invalidated after the
+     * failed send — the intended outcome, nothing usable left behind. `false`
+     * when that cleanup *also* failed: a live credential the recipient never
+     * received is still outstanding until it expires. Alert on `false`.
+     */
+    invalidated: boolean;
+    /** The delivery hook's failure message. */
+    error: string;
+} | {
+    type: "mfa.enrollment.confirmed";
+    userId: string;
+} | {
+    type: "mfa.verify.succeeded";
+    userId: string;
+    method: "totp" | "recovery";
+    remainingRecoveryCodes?: number;
+} | {
+    type: "mfa.verify.failed";
+    userId: string;
+    /**
+     * `"replayed"` marks a *valid* TOTP code rejected because its time step
+     * was already spent — the classic signal of code interception or a
+     * concurrent session, worth distinguishing from a typo in audit review.
+     */
+    reason: "invalid" | "replayed";
+} | {
+    type: "mfa.verify.rate_limited";
+    userId: string;
+    retryAfterMs: number;
+    enforced: boolean;
+} | {
+    type: "mfa.recovery_codes.regenerated";
+    userId: string;
+} | {
+    type: "mfa.disabled";
+    userId: string;
+};
+/**
+ * Receives each {@link IdentityEvent} after the flow's outcome is decided. The
+ * hook is awaited, but it must not affect the flow: a rejection is caught and
+ * logged, never rethrown — report failures through your own channel if you
+ * need delivery guarantees.
+ *
+ * Trigger point `event` (see `docs/trigger-points.md`) — the one
+ * **fire-and-forget** seam in the identity layer.
+ */
+export type IdentityEventHook = (event: IdentityEvent) => void | Promise<void>;
+/** The `*.rate_limited` members of {@link IdentityEvent}. */
+export type RateLimitedEvent = Extract<IdentityEvent, {
+    type: `${string}.rate_limited`;
+}>;
+/**
+ * A {@link RateLimitedEvent} minus the fields the throttle sequence fills in
+ * (`retryAfterMs`, `enforced`) — what a flow passes to `enforceRateLimit`.
+ */
+export type RateLimitedEventInit<E = RateLimitedEvent> = E extends RateLimitedEvent ? Omit<E, "retryAfterMs" | "enforced"> : never;
+/**
+ * Deliver an event to an optional {@link IdentityEventHook}, upholding the
+ * hook contract: a rejection is logged (prefixed with `label`), never
+ * rethrown. Every identity-layer service emits through this.
+ */
+export declare function dispatchIdentityEvent(hook: IdentityEventHook | undefined, label: string, event: IdentityEvent): Promise<void>;

package/esm/identity/events.js

@@ -0,0 +1,39 @@
+/**
+ * Identity flow events — the observability seam for audit capture.
+ *
+ * {@link IdentityService} emits an {@link IdentityEvent} after each significant
+ * auth outcome (sign-in success/failure, sign-up, credential upgrade-on-login,
+ * reset and verification lifecycle, passwordless sign-in links and codes),
+ * `MfaService` emits the `mfa.*` events, and a password-policy validator emits
+ * `password_policy.check_unavailable` when it cannot complete its check. Wire
+ * an {@link IdentityEventHook} via the service's `onEvent`
+ * option to persist them in your own audit store — storage stays app-owned,
+ * like every other seam in this layer.
+ *
+ * Some outcomes are *only* visible here, because the flow that produced them
+ * resolves uniformly by design: `delivery.failed` is the sole in-band signal
+ * that a message never went out (and, when `invalidated` is `false`, that a
+ * live credential the user never received is still outstanding). Treat this
+ * hook as a monitored surface, not just an audit log.
+ *
+ * Events describe internal outcomes (including whether an identifier resolved
+ * to an account), so they are for server-side capture only — never surface
+ * their contents to the end user, or they become an enumeration oracle.
+ *
+ * @module
+ */
+/**
+ * Deliver an event to an optional {@link IdentityEventHook}, upholding the
+ * hook contract: a rejection is logged (prefixed with `label`), never
+ * rethrown. Every identity-layer service emits through this.
+ */
+export async function dispatchIdentityEvent(hook, label, event) {
+    if (!hook)
+        return;
+    try {
+        await hook(event);
+    }
+    catch (error) {
+        console.error(`[@udibo/oauth2] ${label} onEvent hook failed:`, error);
+    }
+}

package/esm/identity/external/_shared.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Internal helpers shared by the external-provider connectors.
+ *
+ * Not part of the public API — reach for a connector from
+ * `@udibo/oauth2/identity/external` instead, which re-exports the one type an
+ * adopter configures ({@link AzpPolicy}). These live here so the same failure
+ * reads the same way whichever connector hit it: one error renderer, one
+ * error-body reader, one provider-text sanitizer, and one id_token claim gate
+ * rather than a copy per provider. The token exchange itself is
+ * `_token-exchange.ts`.
+ *
+ * @module
+ */
+import { PROVIDER_TEXT_MAX_LENGTH, sanitizeProviderText } from "../../utils/text.js";
+export { PROVIDER_TEXT_MAX_LENGTH, sanitizeProviderText };
+/**
+ * Clock-skew allowance, in seconds, when checking an id_token's `exp` claim.
+ * The default for {@link assertIdTokenClaims}.
+ */
+export declare const ID_TOKEN_EXPIRY_LEEWAY_SECONDS = 120;
+/**
+ * Renders a thrown value for an error message, unwrapping an OAuth2 error into
+ * its `error` / `error_description` extensions so a provider-reported failure
+ * is quoted rather than buried in a generic message. Every branch is
+ * {@link sanitizeProviderText}-bounded: the thrown value routinely carries
+ * provider bytes — a JSON parse error quotes the body it choked on, and an
+ * OAuth2 error carries a description the provider wrote.
+ */
+export declare function describeError(error: unknown): string;
+/**
+ * Reads a failed response's body into a bounded, single-line `": <text>"`
+ * suffix to append to an error message, or `""` when the body is empty or
+ * unreadable. Consumes the body, so the caller must not read it again.
+ */
+export declare function readErrorBody(res: Response): Promise<string>;
+/**
+ * Drops one trailing `"/"` so issuer URLs compare and concatenate consistently
+ * (`"https://x/"` and `"https://x"` identify the same issuer).
+ */
+export declare function stripTrailingSlash(value: string): string;
+/**
+ * How {@link assertIdTokenClaims} treats an id_token's `azp` (authorized
+ * party) claim.
+ *
+ * - `"conditional"` — OpenID Connect Core §3.1.3.7: when the token carries
+ *   multiple audiences or an `azp` claim, `azp` must be this client id.
+ * - `"ignore"` — skip the check. For a provider that legitimately reports a
+ *   *different* authorized party than the client doing the exchange: Google's
+ *   cross-client identity, where another client of the same project requests the
+ *   token (`azp` is that client id) for this client's audience (`aud`), is the
+ *   canonical case. Weakens §3.1.3.7 rules 4 and 5, so `aud` remains the only
+ *   check binding the token to this registration — reach for it only when a real
+ *   provider forces it. Configure it on
+ *   {@link OidcProviderOptions.azp}/{@link GoogleProviderOptions.azp}.
+ */
+export type AzpPolicy = "conditional" | "ignore";
+/** Input for {@link assertIdTokenClaims}. */
+export interface IdTokenClaimsInput {
+    /** Provider id carried on the thrown {@link ExternalAuthError}. */
+    provider: string;
+    /** The decoded id_token claims. */
+    claims: Record<string, unknown>;
+    /** The issuer the `iss` claim must equal exactly. */
+    issuer: string;
+    /** The client id the `aud` claim must contain. */
+    clientId: string;
+    /** The nonce sent on the authorize request; omit when none was sent. */
+    expectedNonce?: string;
+    /** How to check `azp`. Defaults to `"conditional"`. */
+    azp?: AzpPolicy;
+    /**
+     * Clock-skew allowance for `exp`, in seconds. Defaults to
+     * {@link ID_TOKEN_EXPIRY_LEEWAY_SECONDS}.
+     */
+    leewaySeconds?: number;
+}
+/**
+ * Enforces the id_token claim rules of OpenID Connect Core §3.1.3.7 that do not
+ * depend on the signature: `iss`, `aud`, `azp`, `exp`, and `nonce`, in that
+ * order. Callers verify the signature (or establish the token's provenance)
+ * themselves before calling this.
+ *
+ * Throws {@link ExternalAuthError} with code `nonce_mismatch` when the `nonce`
+ * claim does not match, and `provider_error` for every other rule.
+ */
+export declare function assertIdTokenClaims(input: IdTokenClaimsInput): void;