@tdacorp/identity-client 0.1.0

package/dist/verify-BiGhwaIz.d.cts

@@ -0,0 +1,306 @@
+import { RolesClaim } from '@tdacorp/identity-authz';
+
+/**
+ * A successful OAuth2/OIDC token response, camelCased from the wire's
+ * snake_case (RFC 6749 §5.1).
+ */
+interface TokenSet {
+    accessToken: string;
+    tokenType: string;
+    refreshToken?: string;
+    /** Present only when the request's scope included `openid`. */
+    idToken?: string;
+    /** Lifetime of `accessToken` in seconds from the time of issuance, when
+     *  the server reports one. */
+    expiresIn?: number;
+    /** The scope actually granted, space-separated -- may be narrower than
+     *  what was requested; absent when the server considers it unchanged. */
+    scope?: string;
+}
+/** Thrown by `exchangeAuthorizationCode` and `clientCredentialsGrant` on any
+ *  non-success response. Both are one-shot actions with no live session to
+ *  protect from a bad classification, unlike `refreshTokens` below, so a
+ *  plain throw is enough: the caller has nothing to preserve either way. */
+declare class TokenRequestError extends Error {
+    readonly status?: number;
+    readonly error?: string;
+    readonly errorDescription?: string;
+    constructor(details: {
+        status?: number;
+        error?: string;
+        errorDescription?: string;
+    });
+}
+/** Options for `exchangeAuthorizationCode`. */
+interface AuthorizationCodeExchangeOptions {
+    /** The identity server's issuer URL, used to look up `token_endpoint`. */
+    issuer: string;
+    clientId: string;
+    /** Omit for a public client authenticating via PKCE alone. */
+    clientSecret?: string;
+    /** The `code` query param from the authorization callback. */
+    code: string;
+    /** Must exactly match the `redirect_uri` used on the authorization
+     *  request (RFC 6749 §4.1.3). */
+    redirectUri: string;
+    /** The PKCE verifier generated (and kept) alongside the code challenge
+     *  sent on the authorization request; see `generateCodeVerifier`. */
+    codeVerifier: string;
+}
+/** RFC 6749 §4.1.3 / RFC 7636 §4.5: exchanges an authorization code for a
+ *  token set. Throws `TokenRequestError` on any non-success response. */
+declare function exchangeAuthorizationCode(options: AuthorizationCodeExchangeOptions): Promise<TokenSet>;
+/** Options for `clientCredentialsGrant`. */
+interface ClientCredentialsGrantOptions {
+    /** The identity server's issuer URL, used to look up `token_endpoint`. */
+    issuer: string;
+    clientId: string;
+    /** Required -- this grant has no end user and no PKCE verifier, so the
+     *  client must authenticate with its own confidential secret. */
+    clientSecret: string;
+    /** Space-separated scopes to request for the resulting token. */
+    scope?: string;
+}
+/** RFC 6749 §4.4: mints a token with no end user, for service-to-service
+ *  calls. Always confidential -- `clientSecret` is required, not optional,
+ *  because this grant has no PKCE verifier to authenticate a public client
+ *  with. Throws `TokenRequestError` on any non-success response. */
+declare function clientCredentialsGrant(options: ClientCredentialsGrantOptions): Promise<TokenSet>;
+/** Options for `refreshTokens`. */
+interface RefreshTokensOptions {
+    /** The identity server's issuer URL, used to look up `token_endpoint`. */
+    issuer: string;
+    clientId: string;
+    /** Omit for a public client authenticating via PKCE alone. */
+    clientSecret?: string;
+    /** The refresh token to redeem. */
+    refreshToken: string;
+}
+type TokenRefreshOutcome = {
+    outcome: 'success';
+    tokens: TokenSet;
+}
+/** The refresh token's status is still unknown. The caller must deny the
+ *  request this refresh was gating, but must NOT clear the refresh token
+ *  or any session built on it -- see this function's own docblock. */
+ | {
+    outcome: 'transient';
+    error: unknown;
+}
+/** The refresh token is confirmed dead. Safe, and only now safe, for the
+ *  caller to clear it. */
+ | {
+    outcome: 'terminal';
+    error: TokenRequestError;
+};
+/**
+ * RFC 6749 §6: redeems a refresh token for a new token set, classifying
+ * failure as `transient` (retry later, credential still unknown) or
+ * `terminal` (the refresh token is confirmed dead) instead of collapsing
+ * both into one rejection.
+ *
+ * WHY THIS DISTINCTION EXISTS, AND WHY IT IS NOT OPTIONAL
+ *
+ * An infrastructure hiccup must never be treated the same as a rejected
+ * credential. A caller that clears a session/cookie on ANY refresh failure
+ * will force-log-out every one of its users during a transient outage, or
+ * the moment its own client secret is rotated or its client is temporarily
+ * disabled -- neither of those says anything about whether the refresh
+ * token itself is still good. This function classifies failures against the
+ * identity server's own status-code contract for exactly that reason: only
+ * a response that is actually a verdict on the refresh token gets to clear
+ * it.
+ *
+ * CLASSIFICATION
+ *
+ * - `transient`: a 408/429/5xx HTTP status, `fetch` itself throwing (DNS
+ *   failure, connection refused, TLS error, timeout), or a 401 response. A
+ *   401 here is the server rejecting THIS CALLER's own client credentials
+ *   (`invalid_client`) -- a verdict on the caller, not on the refresh token
+ *   being redeemed, so the token's status is still unknown just like the
+ *   other cases in this bucket.
+ * - `terminal`: a 400 response with `error: "invalid_grant"` -- RFC 6749
+ *   §5.2's own code for "the ... refresh token is invalid, expired,
+ *   revoked". This is the only shape that is actually the server SAYING the
+ *   refresh token itself is dead.
+ * - Anything else (an unrecognised 4xx, a 2xx with a malformed body) defaults
+ *   to `transient`. This is the safe direction, not a shrug: misclassifying
+ *   a live refresh token as terminal tells the caller to destroy a working
+ *   credential and force a real user to sign in again, while misclassifying
+ *   a dead one as transient only delays cleanup until the next refresh
+ *   attempt, which is self-correcting and costs nothing but a little
+ *   staleness.
+ */
+declare function refreshTokens(options: RefreshTokensOptions): Promise<TokenRefreshOutcome>;
+
+/**
+ * What a verified TDACorp Identity access token actually is: a token minted
+ * for an end user, or a token minted for a machine with none.
+ *
+ * Precedent: Clerk's backend SDK returns a discriminated `tokenType` /
+ * `acceptsToken` object from its own token verification rather than one flat
+ * claims bag, for the same reason this type exists -- a caller that reads a
+ * property off the wrong variant should get a compile error, not `undefined`
+ * read as "no roles" or a machine's `clientId` misread as a user's `sub`.
+ *
+ * The concrete reason this matters here: this identity server's
+ * `client_credentials` grant mints access tokens with no end user and no
+ * `roles` claim at all -- there is no subject for a roles claim to describe.
+ * Before this type existed, `verifyAccessToken` returned one flat claims
+ * object for both cases, so a caller checking `.sub` on a machine token
+ * silently got `undefined` instead of a type error telling it this branch
+ * has no subject.
+ */
+type VerifiedAccessToken = {
+    kind: 'user';
+    sub: string;
+    /** Present only when the token was minted with the `roles` scope.
+     *  Pass to `permits()` from `@tdacorp/identity-authz` to decide a
+     *  permission locally. */
+    roles?: RolesClaim;
+    claims: Record<string, unknown>;
+} | {
+    kind: 'machine';
+    clientId: string;
+    claims: Record<string, unknown>;
+};
+
+/**
+ * Allowed clock skew between this process and the identity server, applied
+ * via jose's `clockTolerance`.
+ *
+ * 60 seconds, matching Auth0's own documented default leeway for ID token
+ * validation (60000ms, e.g. Auth0's Lock.swift and Auth0.js configuration
+ * docs) and the conventional default several JWT libraries ship
+ * (`jsonwebtoken`'s own README recommendation, Spring Security's
+ * `JwtTimestampValidator`). Clerk's backend SDK is tighter, defaulting
+ * `clockSkewInMs` to 5000 (5s) -- verified against Clerk's own docs. 60s is
+ * chosen over Clerk's tighter figure deliberately: this is a first-party,
+ * low-latency deployment (the identity server and every relying party share
+ * infrastructure-grade NTP-synced clocks), so the risk a looser tolerance
+ * trades away -- a stolen, still-live token being replayed slightly past its
+ * `exp` -- is small next to the cost of a false rejection from ordinary
+ * clock drift, and 60s is not a novel number invented for this package: it
+ * is the figure Auth0 itself ships as a default.
+ */
+declare const CLOCK_SKEW_TOLERANCE_SECONDS = 60;
+/**
+ * Why `verifyIdToken`/`verifyAccessToken` could not produce a verified
+ * claims payload. Every value here is a property of the TOKEN itself, not a
+ * caller programming error -- a missing `options.issuer`/`options.audience`
+ * throws instead (see `requireConfig`).
+ *
+ * - `'expired'`: the token's `exp` has passed, even after
+ *   `CLOCK_SKEW_TOLERANCE_SECONDS` of leeway.
+ * - `'invalid-signature'`: the signature does not verify against any key in
+ *   the issuer's JWKS (wrong key, tampered token, or an ambiguous match).
+ * - `'invalid-issuer'`: the token's `iss` does not match `options.issuer`.
+ * - `'invalid-audience'`: the token's `aud` does not match `options.audience`.
+ * - `'unauthorized-party'`: `options.authorizedParties` was given and the
+ *   token's `azp` (or single-string `aud` fallback) is not in it -- see
+ *   `VerifyTokenOptions.authorizedParties`'s own docblock for why this
+ *   check exists alongside the plain audience check.
+ * - `'malformed-claims'`: the token verified but is missing a claim this
+ *   package requires (e.g. `sub` on an id_token).
+ * - `'malformed-token'`: the token is not a well-formed JWT at all.
+ * - `'jwks-unavailable'`: the issuer's discovery document or JWKS could not
+ *   be fetched -- infrastructure, not a verdict on the token.
+ */
+type TokenVerificationErrorCode = 'expired' | 'invalid-signature' | 'invalid-issuer' | 'invalid-audience' | 'unauthorized-party' | 'malformed-claims' | 'malformed-token' | 'jwks-unavailable';
+/** One verification failure: a stable `code` to branch on, plus a
+ *  human-readable `message` for logs. `verifyIdToken`/`verifyAccessToken`
+ *  return a list of these rather than throwing -- see `VerificationResult`. */
+interface TokenVerificationError {
+    code: TokenVerificationErrorCode;
+    message: string;
+}
+/**
+ * The outcome of `verifyIdToken`/`verifyAccessToken`: either the verified,
+ * typed claims (`success: true`), or the reasons verification failed
+ * (`success: false`). A discriminated union rather than a thrown error, on
+ * the same reasoning as `Permit` in `@tdacorp/identity-authz`: an expected
+ * verification failure (expired, bad signature, wrong audience) is data a
+ * caller branches on, not an exceptional condition -- only a genuine
+ * programming error (missing `options.issuer`/`options.audience`) throws.
+ *
+ * @example
+ * ```ts
+ * const result = await verifyIdToken(idToken, { issuer, audience })
+ * if (result.success) {
+ *   console.log(result.data.sub)
+ * } else {
+ *   console.warn(result.errors.map((e) => e.code))
+ * }
+ * ```
+ */
+type VerificationResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: TokenVerificationError[];
+};
+/** Configuration shared by `verifyIdToken` and `verifyAccessToken`: which
+ *  issuer and audience a token must match, plus an optional
+ *  `authorizedParties` allowlist (see that field's own docblock below). */
+interface VerifyTokenOptions {
+    issuer: string;
+    audience: string;
+    /**
+     * Origins/client ids this caller trusts a token to have been issued to,
+     * checked against the token's `azp` claim when present, falling back to a
+     * string `aud` otherwise.
+     *
+     * WHY `azp` FIRST: this identity server always sets `azp` to the
+     * requesting client's own id, even for an access token whose `aud` was
+     * overridden to an RFC 8707 resource indicator -- `azp` keeps naming who
+     * the token was issued to regardless of what `aud` also claims to be valid
+     * at. `aud` is only a safe fallback when it is a single string naming one
+     * party; this package does not attempt the allowlist check against a
+     * multi-valued `aud`.
+     *
+     * WHY THIS CHECK EXISTS AT ALL: every TDACorp product shares the
+     * `tdacorp.in` registrable domain, and this server's `aud`/`azp` values
+     * are opaque client ids, not origins that a browser's same-origin policy
+     * already separates. A token minted for one product is not otherwise
+     * prevented from being replayed against another product that shares this
+     * issuer -- both the plain `audience` check above and this allowlist are
+     * needed, and they check different things: one asks whether the token is
+     * FOR this resource server, the other asks whether it was issued THROUGH
+     * a client this caller has chosen to trust.
+     */
+    authorizedParties?: string[];
+}
+/**
+ * The verified claims of an OIDC id_token, as returned by `verifyIdToken`.
+ *
+ * Only the claims every id_token carries per OpenID Connect Core 1.0 §2 are
+ * typed here (`sub`, `iss`, `aud`, `exp`, `iat`); anything else the identity
+ * server includes (e.g. `email`, `name`) still comes through on the object,
+ * covered by the index signature, just not individually typed.
+ */
+interface IdTokenClaims extends Record<string, unknown> {
+    sub: string;
+    iss: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+}
+/** Verifies an OIDC id_token's signature, issuer, audience and expiry (with
+ *  the clock-skew tolerance documented on `CLOCK_SKEW_TOLERANCE_SECONDS`).
+ *  Never throws for an expected verification failure -- expired, bad
+ *  signature, wrong issuer/audience -- returning `{ success: false, errors
+ *  }` instead. Throws only for missing required config (`options.issuer` /
+ *  `options.audience`), which is a programming error, not a property of the
+ *  token. */
+declare function verifyIdToken(idToken: string, options: VerifyTokenOptions): Promise<VerificationResult<IdTokenClaims>>;
+/** Verifies an access token the same way `verifyIdToken` does, then shapes
+ *  the result as a `VerifiedAccessToken` (see that type's own docblock for
+ *  why user and machine tokens are a discriminated union rather than one
+ *  flat claims bag) with the `roles` claim, if present, typed as
+ *  `RolesClaim` from `@tdacorp/identity-authz` rather than left as an
+ *  unparsed field the caller has to know to reach for. Same throw/return
+ *  contract as `verifyIdToken`. */
+declare function verifyAccessToken(accessToken: string, options: VerifyTokenOptions): Promise<VerificationResult<VerifiedAccessToken>>;
+
+export { type AuthorizationCodeExchangeOptions as A, CLOCK_SKEW_TOLERANCE_SECONDS as C, type IdTokenClaims as I, type RefreshTokensOptions as R, type TokenRefreshOutcome as T, type VerificationResult as V, type ClientCredentialsGrantOptions as a, TokenRequestError as b, type TokenSet as c, type TokenVerificationError as d, type TokenVerificationErrorCode as e, type VerifiedAccessToken as f, type VerifyTokenOptions as g, clientCredentialsGrant as h, exchangeAuthorizationCode as i, verifyIdToken as j, refreshTokens as r, verifyAccessToken as v };

package/dist/verify-BiGhwaIz.d.ts

@@ -0,0 +1,306 @@
+import { RolesClaim } from '@tdacorp/identity-authz';
+
+/**
+ * A successful OAuth2/OIDC token response, camelCased from the wire's
+ * snake_case (RFC 6749 §5.1).
+ */
+interface TokenSet {
+    accessToken: string;
+    tokenType: string;
+    refreshToken?: string;
+    /** Present only when the request's scope included `openid`. */
+    idToken?: string;
+    /** Lifetime of `accessToken` in seconds from the time of issuance, when
+     *  the server reports one. */
+    expiresIn?: number;
+    /** The scope actually granted, space-separated -- may be narrower than
+     *  what was requested; absent when the server considers it unchanged. */
+    scope?: string;
+}
+/** Thrown by `exchangeAuthorizationCode` and `clientCredentialsGrant` on any
+ *  non-success response. Both are one-shot actions with no live session to
+ *  protect from a bad classification, unlike `refreshTokens` below, so a
+ *  plain throw is enough: the caller has nothing to preserve either way. */
+declare class TokenRequestError extends Error {
+    readonly status?: number;
+    readonly error?: string;
+    readonly errorDescription?: string;
+    constructor(details: {
+        status?: number;
+        error?: string;
+        errorDescription?: string;
+    });
+}
+/** Options for `exchangeAuthorizationCode`. */
+interface AuthorizationCodeExchangeOptions {
+    /** The identity server's issuer URL, used to look up `token_endpoint`. */
+    issuer: string;
+    clientId: string;
+    /** Omit for a public client authenticating via PKCE alone. */
+    clientSecret?: string;
+    /** The `code` query param from the authorization callback. */
+    code: string;
+    /** Must exactly match the `redirect_uri` used on the authorization
+     *  request (RFC 6749 §4.1.3). */
+    redirectUri: string;
+    /** The PKCE verifier generated (and kept) alongside the code challenge
+     *  sent on the authorization request; see `generateCodeVerifier`. */
+    codeVerifier: string;
+}
+/** RFC 6749 §4.1.3 / RFC 7636 §4.5: exchanges an authorization code for a
+ *  token set. Throws `TokenRequestError` on any non-success response. */
+declare function exchangeAuthorizationCode(options: AuthorizationCodeExchangeOptions): Promise<TokenSet>;
+/** Options for `clientCredentialsGrant`. */
+interface ClientCredentialsGrantOptions {
+    /** The identity server's issuer URL, used to look up `token_endpoint`. */
+    issuer: string;
+    clientId: string;
+    /** Required -- this grant has no end user and no PKCE verifier, so the
+     *  client must authenticate with its own confidential secret. */
+    clientSecret: string;
+    /** Space-separated scopes to request for the resulting token. */
+    scope?: string;
+}
+/** RFC 6749 §4.4: mints a token with no end user, for service-to-service
+ *  calls. Always confidential -- `clientSecret` is required, not optional,
+ *  because this grant has no PKCE verifier to authenticate a public client
+ *  with. Throws `TokenRequestError` on any non-success response. */
+declare function clientCredentialsGrant(options: ClientCredentialsGrantOptions): Promise<TokenSet>;
+/** Options for `refreshTokens`. */
+interface RefreshTokensOptions {
+    /** The identity server's issuer URL, used to look up `token_endpoint`. */
+    issuer: string;
+    clientId: string;
+    /** Omit for a public client authenticating via PKCE alone. */
+    clientSecret?: string;
+    /** The refresh token to redeem. */
+    refreshToken: string;
+}
+type TokenRefreshOutcome = {
+    outcome: 'success';
+    tokens: TokenSet;
+}
+/** The refresh token's status is still unknown. The caller must deny the
+ *  request this refresh was gating, but must NOT clear the refresh token
+ *  or any session built on it -- see this function's own docblock. */
+ | {
+    outcome: 'transient';
+    error: unknown;
+}
+/** The refresh token is confirmed dead. Safe, and only now safe, for the
+ *  caller to clear it. */
+ | {
+    outcome: 'terminal';
+    error: TokenRequestError;
+};
+/**
+ * RFC 6749 §6: redeems a refresh token for a new token set, classifying
+ * failure as `transient` (retry later, credential still unknown) or
+ * `terminal` (the refresh token is confirmed dead) instead of collapsing
+ * both into one rejection.
+ *
+ * WHY THIS DISTINCTION EXISTS, AND WHY IT IS NOT OPTIONAL
+ *
+ * An infrastructure hiccup must never be treated the same as a rejected
+ * credential. A caller that clears a session/cookie on ANY refresh failure
+ * will force-log-out every one of its users during a transient outage, or
+ * the moment its own client secret is rotated or its client is temporarily
+ * disabled -- neither of those says anything about whether the refresh
+ * token itself is still good. This function classifies failures against the
+ * identity server's own status-code contract for exactly that reason: only
+ * a response that is actually a verdict on the refresh token gets to clear
+ * it.
+ *
+ * CLASSIFICATION
+ *
+ * - `transient`: a 408/429/5xx HTTP status, `fetch` itself throwing (DNS
+ *   failure, connection refused, TLS error, timeout), or a 401 response. A
+ *   401 here is the server rejecting THIS CALLER's own client credentials
+ *   (`invalid_client`) -- a verdict on the caller, not on the refresh token
+ *   being redeemed, so the token's status is still unknown just like the
+ *   other cases in this bucket.
+ * - `terminal`: a 400 response with `error: "invalid_grant"` -- RFC 6749
+ *   §5.2's own code for "the ... refresh token is invalid, expired,
+ *   revoked". This is the only shape that is actually the server SAYING the
+ *   refresh token itself is dead.
+ * - Anything else (an unrecognised 4xx, a 2xx with a malformed body) defaults
+ *   to `transient`. This is the safe direction, not a shrug: misclassifying
+ *   a live refresh token as terminal tells the caller to destroy a working
+ *   credential and force a real user to sign in again, while misclassifying
+ *   a dead one as transient only delays cleanup until the next refresh
+ *   attempt, which is self-correcting and costs nothing but a little
+ *   staleness.
+ */
+declare function refreshTokens(options: RefreshTokensOptions): Promise<TokenRefreshOutcome>;
+
+/**
+ * What a verified TDACorp Identity access token actually is: a token minted
+ * for an end user, or a token minted for a machine with none.
+ *
+ * Precedent: Clerk's backend SDK returns a discriminated `tokenType` /
+ * `acceptsToken` object from its own token verification rather than one flat
+ * claims bag, for the same reason this type exists -- a caller that reads a
+ * property off the wrong variant should get a compile error, not `undefined`
+ * read as "no roles" or a machine's `clientId` misread as a user's `sub`.
+ *
+ * The concrete reason this matters here: this identity server's
+ * `client_credentials` grant mints access tokens with no end user and no
+ * `roles` claim at all -- there is no subject for a roles claim to describe.
+ * Before this type existed, `verifyAccessToken` returned one flat claims
+ * object for both cases, so a caller checking `.sub` on a machine token
+ * silently got `undefined` instead of a type error telling it this branch
+ * has no subject.
+ */
+type VerifiedAccessToken = {
+    kind: 'user';
+    sub: string;
+    /** Present only when the token was minted with the `roles` scope.
+     *  Pass to `permits()` from `@tdacorp/identity-authz` to decide a
+     *  permission locally. */
+    roles?: RolesClaim;
+    claims: Record<string, unknown>;
+} | {
+    kind: 'machine';
+    clientId: string;
+    claims: Record<string, unknown>;
+};
+
+/**
+ * Allowed clock skew between this process and the identity server, applied
+ * via jose's `clockTolerance`.
+ *
+ * 60 seconds, matching Auth0's own documented default leeway for ID token
+ * validation (60000ms, e.g. Auth0's Lock.swift and Auth0.js configuration
+ * docs) and the conventional default several JWT libraries ship
+ * (`jsonwebtoken`'s own README recommendation, Spring Security's
+ * `JwtTimestampValidator`). Clerk's backend SDK is tighter, defaulting
+ * `clockSkewInMs` to 5000 (5s) -- verified against Clerk's own docs. 60s is
+ * chosen over Clerk's tighter figure deliberately: this is a first-party,
+ * low-latency deployment (the identity server and every relying party share
+ * infrastructure-grade NTP-synced clocks), so the risk a looser tolerance
+ * trades away -- a stolen, still-live token being replayed slightly past its
+ * `exp` -- is small next to the cost of a false rejection from ordinary
+ * clock drift, and 60s is not a novel number invented for this package: it
+ * is the figure Auth0 itself ships as a default.
+ */
+declare const CLOCK_SKEW_TOLERANCE_SECONDS = 60;
+/**
+ * Why `verifyIdToken`/`verifyAccessToken` could not produce a verified
+ * claims payload. Every value here is a property of the TOKEN itself, not a
+ * caller programming error -- a missing `options.issuer`/`options.audience`
+ * throws instead (see `requireConfig`).
+ *
+ * - `'expired'`: the token's `exp` has passed, even after
+ *   `CLOCK_SKEW_TOLERANCE_SECONDS` of leeway.
+ * - `'invalid-signature'`: the signature does not verify against any key in
+ *   the issuer's JWKS (wrong key, tampered token, or an ambiguous match).
+ * - `'invalid-issuer'`: the token's `iss` does not match `options.issuer`.
+ * - `'invalid-audience'`: the token's `aud` does not match `options.audience`.
+ * - `'unauthorized-party'`: `options.authorizedParties` was given and the
+ *   token's `azp` (or single-string `aud` fallback) is not in it -- see
+ *   `VerifyTokenOptions.authorizedParties`'s own docblock for why this
+ *   check exists alongside the plain audience check.
+ * - `'malformed-claims'`: the token verified but is missing a claim this
+ *   package requires (e.g. `sub` on an id_token).
+ * - `'malformed-token'`: the token is not a well-formed JWT at all.
+ * - `'jwks-unavailable'`: the issuer's discovery document or JWKS could not
+ *   be fetched -- infrastructure, not a verdict on the token.
+ */
+type TokenVerificationErrorCode = 'expired' | 'invalid-signature' | 'invalid-issuer' | 'invalid-audience' | 'unauthorized-party' | 'malformed-claims' | 'malformed-token' | 'jwks-unavailable';
+/** One verification failure: a stable `code` to branch on, plus a
+ *  human-readable `message` for logs. `verifyIdToken`/`verifyAccessToken`
+ *  return a list of these rather than throwing -- see `VerificationResult`. */
+interface TokenVerificationError {
+    code: TokenVerificationErrorCode;
+    message: string;
+}
+/**
+ * The outcome of `verifyIdToken`/`verifyAccessToken`: either the verified,
+ * typed claims (`success: true`), or the reasons verification failed
+ * (`success: false`). A discriminated union rather than a thrown error, on
+ * the same reasoning as `Permit` in `@tdacorp/identity-authz`: an expected
+ * verification failure (expired, bad signature, wrong audience) is data a
+ * caller branches on, not an exceptional condition -- only a genuine
+ * programming error (missing `options.issuer`/`options.audience`) throws.
+ *
+ * @example
+ * ```ts
+ * const result = await verifyIdToken(idToken, { issuer, audience })
+ * if (result.success) {
+ *   console.log(result.data.sub)
+ * } else {
+ *   console.warn(result.errors.map((e) => e.code))
+ * }
+ * ```
+ */
+type VerificationResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: TokenVerificationError[];
+};
+/** Configuration shared by `verifyIdToken` and `verifyAccessToken`: which
+ *  issuer and audience a token must match, plus an optional
+ *  `authorizedParties` allowlist (see that field's own docblock below). */
+interface VerifyTokenOptions {
+    issuer: string;
+    audience: string;
+    /**
+     * Origins/client ids this caller trusts a token to have been issued to,
+     * checked against the token's `azp` claim when present, falling back to a
+     * string `aud` otherwise.
+     *
+     * WHY `azp` FIRST: this identity server always sets `azp` to the
+     * requesting client's own id, even for an access token whose `aud` was
+     * overridden to an RFC 8707 resource indicator -- `azp` keeps naming who
+     * the token was issued to regardless of what `aud` also claims to be valid
+     * at. `aud` is only a safe fallback when it is a single string naming one
+     * party; this package does not attempt the allowlist check against a
+     * multi-valued `aud`.
+     *
+     * WHY THIS CHECK EXISTS AT ALL: every TDACorp product shares the
+     * `tdacorp.in` registrable domain, and this server's `aud`/`azp` values
+     * are opaque client ids, not origins that a browser's same-origin policy
+     * already separates. A token minted for one product is not otherwise
+     * prevented from being replayed against another product that shares this
+     * issuer -- both the plain `audience` check above and this allowlist are
+     * needed, and they check different things: one asks whether the token is
+     * FOR this resource server, the other asks whether it was issued THROUGH
+     * a client this caller has chosen to trust.
+     */
+    authorizedParties?: string[];
+}
+/**
+ * The verified claims of an OIDC id_token, as returned by `verifyIdToken`.
+ *
+ * Only the claims every id_token carries per OpenID Connect Core 1.0 §2 are
+ * typed here (`sub`, `iss`, `aud`, `exp`, `iat`); anything else the identity
+ * server includes (e.g. `email`, `name`) still comes through on the object,
+ * covered by the index signature, just not individually typed.
+ */
+interface IdTokenClaims extends Record<string, unknown> {
+    sub: string;
+    iss: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+}
+/** Verifies an OIDC id_token's signature, issuer, audience and expiry (with
+ *  the clock-skew tolerance documented on `CLOCK_SKEW_TOLERANCE_SECONDS`).
+ *  Never throws for an expected verification failure -- expired, bad
+ *  signature, wrong issuer/audience -- returning `{ success: false, errors
+ *  }` instead. Throws only for missing required config (`options.issuer` /
+ *  `options.audience`), which is a programming error, not a property of the
+ *  token. */
+declare function verifyIdToken(idToken: string, options: VerifyTokenOptions): Promise<VerificationResult<IdTokenClaims>>;
+/** Verifies an access token the same way `verifyIdToken` does, then shapes
+ *  the result as a `VerifiedAccessToken` (see that type's own docblock for
+ *  why user and machine tokens are a discriminated union rather than one
+ *  flat claims bag) with the `roles` claim, if present, typed as
+ *  `RolesClaim` from `@tdacorp/identity-authz` rather than left as an
+ *  unparsed field the caller has to know to reach for. Same throw/return
+ *  contract as `verifyIdToken`. */
+declare function verifyAccessToken(accessToken: string, options: VerifyTokenOptions): Promise<VerificationResult<VerifiedAccessToken>>;
+
+export { type AuthorizationCodeExchangeOptions as A, CLOCK_SKEW_TOLERANCE_SECONDS as C, type IdTokenClaims as I, type RefreshTokensOptions as R, type TokenRefreshOutcome as T, type VerificationResult as V, type ClientCredentialsGrantOptions as a, TokenRequestError as b, type TokenSet as c, type TokenVerificationError as d, type TokenVerificationErrorCode as e, type VerifiedAccessToken as f, type VerifyTokenOptions as g, clientCredentialsGrant as h, exchangeAuthorizationCode as i, verifyIdToken as j, refreshTokens as r, verifyAccessToken as v };