@dereekb/util 13.23.0 → 13.24.0

package/oidc/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@dereekb/util/oidc",
+  "version": "13.24.0",
+  "peerDependencies": {
+    "@dereekb/util": "13.24.0"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/oidc/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

package/oidc/src/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './oidc.protocol';
+export * from './oidc.token';

package/oidc/src/lib/oidc.protocol.d.ts

@@ -0,0 +1,96 @@
+import { type DiscoverOidcMetadataInput, type ExchangeAuthorizationCodeInput, type FetchSessionInfoInput, type FetchUserInfoInput, type OidcDiscoveryMetadata, type OidcSessionInfo, type OidcTokenResponse, type RefreshAccessTokenInput, type RevokeTokenInput } from '@dereekb/util';
+/**
+ * The fetch transport injected into every relying-party network call.
+ *
+ * Matches the global `fetch` signature so callers can pass raw `fetch`, a traced/timeout wrapper,
+ * or a `configureFetch(...)` result interchangeably.
+ *
+ * ⚠️ The transport passed to the token-endpoint calls (`exchangeAuthorizationCode`,
+ * `refreshAccessToken`, `revokeToken`, `discoverOidcMetadata`) MUST be a plain fetch — it must NOT
+ * inject an `Authorization: Bearer` header. Public PKCE clients authenticate via the
+ * `code_verifier`, not the access token; a Bearer-injecting transport belongs only on the
+ * resource-server (API) client.
+ */
+export type OidcRelyingPartyFetch = typeof fetch;
+/**
+ * Mixed into each network function's input to inject the {@link OidcRelyingPartyFetch} transport.
+ */
+export interface OidcRelyingPartyFetchInput {
+    readonly fetch: OidcRelyingPartyFetch;
+}
+/**
+ * Fetches the OIDC discovery document for the given issuer, trying the candidates returned by
+ * {@link buildOidcDiscoveryCandidates} in order.
+ *
+ * @param input - The discovery request plus the injected fetch transport.
+ * @param input.issuer - The OIDC issuer URL whose `.well-known/openid-configuration` is fetched first.
+ * @param input.fallbackBaseUrl - Optional sibling base URL tried after the issuer-prefixed and origin-rooted candidates.
+ * @param input.fetch - The plain fetch transport.
+ * @returns The parsed {@link OidcDiscoveryMetadata}. Throws an {@link OidcRelyingPartyError} (`DISCOVERY_FAILED`) when every candidate fails.
+ */
+export declare function discoverOidcMetadata(input: DiscoverOidcMetadataInput & OidcRelyingPartyFetchInput): Promise<OidcDiscoveryMetadata>;
+/**
+ * Exchanges an authorization code (from the redirect) for an access token + refresh token.
+ *
+ * Sends `client_secret` only when provided — public PKCE clients (`token_endpoint_auth_method: 'none'`)
+ * authenticate via the `code_verifier` alone.
+ *
+ * @param input - The token exchange parameters plus the injected fetch transport.
+ * @param input.tokenEndpoint - The OIDC token endpoint URL discovered from the issuer.
+ * @param input.clientId - The OAuth client ID.
+ * @param input.clientSecret - Optional client secret for `client_secret_post` auth; omit for public clients.
+ * @param input.redirectUri - The redirect URI registered with the OAuth client.
+ * @param input.code - The authorization code returned to the redirect URI.
+ * @param input.codeVerifier - The PKCE code verifier originally paired with the code challenge.
+ * @param input.fetch - The plain fetch transport.
+ * @returns The parsed {@link OidcTokenResponse} with access/refresh tokens.
+ */
+export declare function exchangeAuthorizationCode(input: ExchangeAuthorizationCodeInput & OidcRelyingPartyFetchInput): Promise<OidcTokenResponse>;
+/**
+ * Exchanges a refresh token for a new access token (and possibly a rotated refresh token).
+ *
+ * @param input - The refresh request plus the injected fetch transport.
+ * @param input.tokenEndpoint - The OIDC token endpoint URL discovered from the issuer.
+ * @param input.clientId - The OAuth client ID.
+ * @param input.clientSecret - Optional client secret; omit for public clients.
+ * @param input.refreshToken - The cached refresh token to redeem.
+ * @param input.fetch - The plain fetch transport.
+ * @returns The parsed {@link OidcTokenResponse} with the refreshed access token.
+ */
+export declare function refreshAccessToken(input: RefreshAccessTokenInput & OidcRelyingPartyFetchInput): Promise<OidcTokenResponse>;
+/**
+ * Revokes an access or refresh token at the OIDC revocation endpoint.
+ *
+ * @param input - The revocation request plus the injected fetch transport.
+ * @param input.revocationEndpoint - The OIDC revocation endpoint URL.
+ * @param input.clientId - The OAuth client ID.
+ * @param input.clientSecret - Optional client secret; omit for public clients.
+ * @param input.token - The access or refresh token to revoke.
+ * @param input.tokenTypeHint - Optional hint passed as `token_type_hint` (`access_token` or `refresh_token`).
+ * @param input.fetch - The plain fetch transport.
+ * @returns Resolves when the server returns a non-error status. Throws an {@link OidcRelyingPartyError} (`TOKEN_REVOCATION_FAILED`) on error.
+ */
+export declare function revokeToken(input: RevokeTokenInput & OidcRelyingPartyFetchInput): Promise<void>;
+/**
+ * Fetches the OIDC `userinfo` endpoint and returns the parsed claims object.
+ *
+ * @param input - The userinfo request plus the injected fetch transport.
+ * @param input.userinfoEndpoint - The OIDC userinfo endpoint URL discovered from the issuer.
+ * @param input.accessToken - The Bearer access token sent in the `Authorization` header.
+ * @param input.fetch - The fetch transport.
+ * @returns The parsed userinfo claims. Throws an {@link OidcRelyingPartyError} (`USERINFO_FAILED`) on a non-OK response.
+ */
+export declare function fetchUserInfo(input: FetchUserInfoInput & OidcRelyingPartyFetchInput): Promise<Record<string, unknown>>;
+/**
+ * Fetches the dbx-components `GET /oidc/session` route and returns the parsed session lifetime metadata.
+ *
+ * Mirrors {@link fetchUserInfo}, but reads the access token's baked-in session-lifetime claims
+ * (`dbx_session_expires_at` / `dbx_rotation_disabled`) which userinfo does not echo.
+ *
+ * @param input - The session request plus the injected fetch transport.
+ * @param input.sessionEndpoint - The `GET /oidc/session` endpoint URL.
+ * @param input.accessToken - The Bearer access token sent in the `Authorization` header.
+ * @param input.fetch - The fetch transport.
+ * @returns The parsed {@link OidcSessionInfo}. Throws an {@link OidcRelyingPartyError} (`SESSION_INFO_FAILED`) on a non-OK response.
+ */
+export declare function fetchSessionInfo(input: FetchSessionInfoInput & OidcRelyingPartyFetchInput): Promise<OidcSessionInfo>;

package/oidc/src/lib/oidc.token.d.ts

@@ -0,0 +1,175 @@
+import { type AsyncValueCache, type Getter, type Maybe, type OidcTokenResponse, type UnixDateTimeMillisecondsNumber } from '@dereekb/util';
+/**
+ * Default pre-emptive refresh buffer in milliseconds.
+ *
+ * An access token is treated as needing a refresh this far ahead of its real expiry to absorb
+ * clock skew and request latency.
+ */
+export declare const DEFAULT_OIDC_TOKEN_REFRESH_BUFFER_MS = 60000;
+/**
+ * Environment-agnostic snapshot of an OIDC relying party's current tokens.
+ *
+ * Persisted via an {@link OidcTokenStorage}. `expiresAt` is stored as an absolute unix epoch
+ * milliseconds value (rather than a `Date`) so the state round-trips cleanly through JSON storage
+ * such as `localStorage`.
+ */
+export interface OidcTokenState {
+    readonly accessToken: string;
+    readonly refreshToken?: Maybe<string>;
+    readonly idToken?: Maybe<string>;
+    readonly tokenType?: Maybe<string>;
+    readonly scope?: Maybe<string>;
+    /**
+     * Absolute access-token expiry as unix epoch milliseconds. Absent ⇒ unknown (treated as expired).
+     */
+    readonly expiresAt?: Maybe<UnixDateTimeMillisecondsNumber>;
+    /**
+     * Optional decoded identity claims (e.g. from the `id_token`), surfaced to UIs.
+     */
+    readonly claims?: Maybe<Record<string, unknown>>;
+}
+/**
+ * Single-value async cache holding the current {@link OidcTokenState}.
+ *
+ * Defaults to {@link inMemoryAsyncValueCache}; environment shells supply a persistent backing
+ * (e.g. a `localStorage`-backed cache in the browser, a file-backed cache in a CLI).
+ */
+export type OidcTokenStorage = AsyncValueCache<OidcTokenState>;
+export interface OidcTokenStateFromResponseConfig {
+    /**
+     * The current time used to anchor `expires_in`. Defaults to the present time.
+     */
+    readonly now?: Maybe<Date | UnixDateTimeMillisecondsNumber>;
+    /**
+     * Pre-decoded identity claims. When omitted, the claims are decoded from the response `id_token`.
+     */
+    readonly claims?: Maybe<Record<string, unknown>>;
+}
+/**
+ * Normalizes an {@link OidcTokenResponse} into an {@link OidcTokenState}, converting the relative
+ * `expires_in` (seconds) into an absolute `expiresAt` (epoch ms) anchored at `config.now`.
+ *
+ * @param response - The token endpoint response to normalize.
+ * @param config - Optional anchoring time and pre-decoded claims.
+ * @returns The normalized {@link OidcTokenState}.
+ */
+export declare function oidcTokenStateFromResponse(response: OidcTokenResponse, config?: OidcTokenStateFromResponseConfig): OidcTokenState;
+/**
+ * Returns true when the access token's real expiry has already passed (no buffer applied), or when
+ * the state / its `expiresAt` is missing.
+ *
+ * @param state - The token state to inspect.
+ * @param now - Optional current time override.
+ * @returns Whether the access token has expired.
+ */
+export declare function isAccessTokenExpired(state: Maybe<OidcTokenState>, now?: Maybe<Date | UnixDateTimeMillisecondsNumber>): boolean;
+/**
+ * Returns true when the access token is expired or within `bufferMs` of expiry (pre-emptive
+ * refresh), or when the state / its `expiresAt` is missing.
+ *
+ * @param state - The token state to inspect.
+ * @param now - Optional current time override.
+ * @param bufferMs - Pre-emptive refresh buffer in milliseconds. Defaults to {@link DEFAULT_OIDC_TOKEN_REFRESH_BUFFER_MS}.
+ * @returns Whether the access token should be refreshed.
+ */
+export declare function accessTokenNeedsRefresh(state: Maybe<OidcTokenState>, now?: Maybe<Date | UnixDateTimeMillisecondsNumber>, bufferMs?: number): boolean;
+/**
+ * Returns the milliseconds remaining until the access token should be pre-emptively refreshed
+ * (its real expiry minus `bufferMs`), clamped to a minimum of `0`.
+ *
+ * @param state - The token state to inspect.
+ * @param now - Optional current time override.
+ * @param bufferMs - Pre-emptive refresh buffer in milliseconds. Defaults to {@link DEFAULT_OIDC_TOKEN_REFRESH_BUFFER_MS}.
+ * @returns The delay in milliseconds, or `0` when already due / unknown.
+ */
+export declare function nextRefreshDelay(state: Maybe<OidcTokenState>, now?: Maybe<Date | UnixDateTimeMillisecondsNumber>, bufferMs?: number): number;
+/**
+ * Performs a single refresh-token exchange and returns the new token response.
+ *
+ * Wired by the environment shell to call {@link refreshAccessToken} with the resolved endpoint +
+ * client credentials + injected fetch.
+ */
+export type OidcTokenRefreshFunction = (input: OidcTokenRefreshFunctionInput) => Promise<OidcTokenResponse>;
+export interface OidcTokenRefreshFunctionInput {
+    /**
+     * The current token state being refreshed.
+     */
+    readonly state: OidcTokenState;
+    /**
+     * The refresh token to redeem (non-null — the manager only calls refresh when one is present).
+     */
+    readonly refreshToken: string;
+}
+export interface OidcTokenManagerConfig {
+    /**
+     * Backing token store. Defaults to an in-memory cache.
+     */
+    readonly storage?: OidcTokenStorage;
+    /**
+     * Refresh-token exchange function. Required.
+     */
+    readonly refresh: OidcTokenRefreshFunction;
+    /**
+     * Current-time getter (epoch ms). Defaults to `Date.now`.
+     */
+    readonly now?: Getter<UnixDateTimeMillisecondsNumber>;
+    /**
+     * Pre-emptive refresh buffer in milliseconds. Defaults to {@link DEFAULT_OIDC_TOKEN_REFRESH_BUFFER_MS}.
+     */
+    readonly refreshBufferMs?: number;
+}
+/**
+ * The env-agnostic token "brain": resolves a valid access token, refreshing lazily and
+ * de-duplicating concurrent refreshes into one network call.
+ */
+export interface OidcTokenManager {
+    /**
+     * Loads the stored state, returning a valid access token — refreshing first when the current one
+     * is missing/expired. Resolves to `undefined` when there is no usable token (logged out, or the
+     * refresh failed with `invalid_grant`, which also clears the store).
+     */
+    getValidAccessToken(): Promise<Maybe<string>>;
+    /**
+     * Returns the currently stored token state.
+     */
+    getState(): Promise<Maybe<OidcTokenState>>;
+    /**
+     * Replaces the stored token state (e.g. after an initial login exchange).
+     */
+    setState(state: OidcTokenState): Promise<void>;
+    /**
+     * Forces a refresh now (sharing any in-flight refresh), returning the new state.
+     */
+    refreshNow(): Promise<Maybe<OidcTokenState>>;
+    /**
+     * Clears the stored token state (logout).
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Creates an {@link OidcTokenManager} over the given storage + refresh function.
+ *
+ * - **Lazy** — refreshes only on demand (no timer), so it works unchanged in a CLI or browser.
+ * - **Single-flight** — concurrent `getValidAccessToken()` / `refreshNow()` calls share one
+ *   in-flight refresh, so N callers trigger at most one network exchange.
+ * - **Rotation-safe** — a rotated `refresh_token` replaces the old one; when the response omits it,
+ *   the prior refresh token is kept. The `id_token`/`claims` are likewise carried forward when a
+ *   refresh response omits them.
+ * - **invalid_grant → logout** — a refresh that fails with `TOKEN_INVALID_GRANT` clears the store
+ *   and surfaces as "no token" (`undefined`); other errors propagate.
+ *
+ * @param config - The manager configuration.
+ * @returns The configured {@link OidcTokenManager}.
+ */
+export declare function oidcTokenManager(config: OidcTokenManagerConfig): OidcTokenManager;
+/**
+ * Decodes the (unverified) payload claims from a JWT such as an `id_token`.
+ *
+ * This does NOT verify the signature — it is purely for surfacing identity claims a relying party
+ * already trusts (the token was just issued to it). Returns `undefined` when the input is missing
+ * or not a decodable JWT.
+ *
+ * @param token - The JWT string.
+ * @returns The decoded claims object, or `undefined`.
+ */
+export declare function decodeJwtClaims(token: Maybe<string>): Maybe<Record<string, unknown>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/util",
-  "version": "13.23.0",
+  "version": "13.24.0",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -15,6 +15,12 @@
       "import": "./fetch/index.cjs.mjs",
       "default": "./fetch/index.cjs.js"
     },
+    "./oidc": {
+      "module": "./oidc/index.esm.js",
+      "types": "./oidc/index.d.ts",
+      "import": "./oidc/index.cjs.mjs",
+      "default": "./oidc/index.cjs.js"
+    },
     "./eslint": {
       "module": "./eslint/index.esm.js",
       "types": "./eslint/index.d.ts",

package/src/lib/auth/oauth.d.ts

@@ -1,3 +1,6 @@
+import { BaseError } from 'make-error';
+import { type CodedError } from '../error/error';
+import { type Maybe } from '../value/maybe.type';
 /**
  * Standard "out-of-band" OAuth 2.0 redirect URI URN.
  *
@@ -10,3 +13,277 @@
  * bind a local port.
  */
 export declare const OAUTH_OOB_REDIRECT_URI = "urn:ietf:wg:oauth:2.0:oob";
+/**
+ * Default OAuth scope requested by an OIDC relying party when no explicit scope list is provided.
+ *
+ * `openid` is the one scope every OpenID Connect flow must request to receive an ID token.
+ */
+export declare const DEFAULT_OIDC_RELYING_PARTY_SCOPE = "openid";
+/**
+ * Stable error code identifying a failure raised by the OIDC relying-party (token-consumer) layer.
+ *
+ * Shared by the pure helpers here and the network protocol functions in `@dereekb/util/oidc`.
+ * Consumers (CLI, browser) re-wrap or branch on these codes at their boundary.
+ */
+export type OidcRelyingPartyErrorCode = 'DISCOVERY_FAILED' | 'TOKEN_EXCHANGE_FAILED' | 'TOKEN_INVALID_GRANT' | 'TOKEN_REVOCATION_FAILED' | 'USERINFO_FAILED' | 'SESSION_INFO_FAILED' | 'AUTH_NO_CODE' | 'AUTH_PROVIDER_ERROR' | 'AUTH_REDIRECT_PARSE_FAILED' | 'INVALID_STATE' | 'INVALID_SESSION_TTL';
+export interface OidcRelyingPartyErrorInput {
+    readonly message: string;
+    readonly code: OidcRelyingPartyErrorCode;
+    /**
+     * The original error, if this error wraps one.
+     */
+    readonly _error?: unknown;
+}
+/**
+ * Error raised by the OIDC relying-party layer (pure helpers here + the network protocol functions
+ * in `@dereekb/util/oidc`). Carries a stable {@link OidcRelyingPartyErrorCode} so environment shells
+ * (CLI, browser) can branch on or re-wrap it without string-matching messages.
+ */
+export declare class OidcRelyingPartyError extends BaseError implements CodedError {
+    readonly code: OidcRelyingPartyErrorCode;
+    readonly _error?: unknown;
+    constructor(input: OidcRelyingPartyErrorInput);
+}
+/**
+ * The subset of fields read from an OIDC discovery document.
+ *
+ * A relying party uses the authorization, token, userinfo, and revocation endpoints to drive
+ * the authorization-code-with-PKCE flow.
+ */
+export interface OidcDiscoveryMetadata {
+    readonly issuer: string;
+    readonly authorization_endpoint: string;
+    readonly token_endpoint: string;
+    readonly userinfo_endpoint?: string;
+    readonly revocation_endpoint?: string;
+    readonly end_session_endpoint?: string;
+    readonly jwks_uri?: string;
+    readonly scopes_supported?: string[];
+}
+/**
+ * Token response from a successful `authorization_code` or `refresh_token` exchange.
+ */
+export interface OidcTokenResponse {
+    readonly access_token: string;
+    readonly token_type?: string;
+    readonly expires_in?: number;
+    readonly refresh_token?: string;
+    readonly id_token?: string;
+    readonly scope?: string;
+}
+/**
+ * Session lifetime metadata returned by the dbx-components `GET /oidc/session` route.
+ */
+export interface OidcSessionInfo {
+    readonly sub?: string;
+    readonly scope?: Maybe<string>;
+    /**
+     * Grant (session) expiry as unix epoch SECONDS, or `null` when the provider could not resolve it.
+     */
+    readonly expiresAt?: Maybe<number>;
+    /**
+     * Whether refresh-token rotation is disabled for this grant (a long-lived service token).
+     */
+    readonly rotationDisabled?: boolean;
+}
+export interface DiscoverOidcMetadataInput {
+    readonly issuer: string;
+    /**
+     * Optional sibling base URL to try after the issuer-prefixed and origin-rooted paths.
+     *
+     * Useful when the discovery doc is served at `<api-base-url>/.well-known/openid-configuration`
+     * — e.g. when the issuer is reached via a different host than the API and the origin-rooted
+     * candidate would target the wrong host.
+     */
+    readonly fallbackBaseUrl?: string;
+}
+export interface ExchangeAuthorizationCodeInput {
+    readonly tokenEndpoint: string;
+    readonly clientId: string;
+    /**
+     * Optional client secret. Confidential clients authenticate via `client_secret_post`; public
+     * PKCE clients (`token_endpoint_auth_method: 'none'`) omit it and authenticate via the
+     * `code_verifier` alone.
+     */
+    readonly clientSecret?: Maybe<string>;
+    readonly redirectUri: string;
+    readonly code: string;
+    readonly codeVerifier: string;
+}
+export interface RefreshAccessTokenInput {
+    readonly tokenEndpoint: string;
+    readonly clientId: string;
+    /**
+     * Optional client secret. Omitted for public PKCE clients.
+     */
+    readonly clientSecret?: Maybe<string>;
+    readonly refreshToken: string;
+}
+export interface RevokeTokenInput {
+    readonly revocationEndpoint: string;
+    readonly clientId: string;
+    /**
+     * Optional client secret. Omitted for public PKCE clients.
+     */
+    readonly clientSecret?: Maybe<string>;
+    readonly token: string;
+    readonly tokenTypeHint?: 'access_token' | 'refresh_token';
+}
+export interface FetchUserInfoInput {
+    readonly userinfoEndpoint: string;
+    readonly accessToken: string;
+}
+export interface FetchSessionInfoInput {
+    /**
+     * The `GET /oidc/session` endpoint URL (typically `<oidcIssuer>/session`).
+     */
+    readonly sessionEndpoint: string;
+    readonly accessToken: string;
+}
+/**
+ * Builds the ordered list of `.well-known/openid-configuration` URLs probed when discovering OIDC
+ * metadata.
+ *
+ *   1. `<issuer>/.well-known/openid-configuration` (OpenID Connect Discovery 1.0).
+ *   2. `<issuer-origin>/.well-known/openid-configuration` (host-rooted; matches projects that
+ *      mount the discovery controller at the API/dev-server root rather than under the issuer
+ *      sub-path — e.g. demo's `OidcWellKnownController`).
+ *   3. `<fallbackBaseUrl>/.well-known/openid-configuration` when supplied and not already covered.
+ *
+ * Exported so diagnostic surfaces (e.g. a CLI `doctor`) can show the exact URLs the discovery step
+ * tried — without re-implementing the candidate ordering.
+ *
+ * @param input - The discovery request.
+ * @param input.issuer - The OIDC issuer URL whose `.well-known/openid-configuration` is fetched first.
+ * @param input.fallbackBaseUrl - Optional sibling base URL appended after the issuer-prefixed and origin-rooted candidates.
+ * @returns The candidate URL list in probe order, de-duplicated.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function buildOidcDiscoveryCandidates(input: DiscoverOidcMetadataInput): string[];
+/**
+ * Returns the input URL string with a single trailing slash removed, if present.
+ *
+ * @param url - The URL string to trim.
+ * @returns The URL without a trailing slash.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function trimSlash(url: string): string;
+export interface BuildAuthorizationUrlInput {
+    readonly authorizationEndpoint: string;
+    /**
+     * Optional OIDC issuer URL (e.g. `https://api.example.com/oidc`). Used as a fallback rebase
+     * origin when `appClientUrl` is not provided — the origin of `oidcIssuer` is applied to the
+     * discovered `authorizationEndpoint`. In typical OIDC deployments the issuer and authorization
+     * endpoint share an origin, so this fallback is a no-op rebase that ends up at the discovered
+     * `/oidc/auth` URL. Use `appClientUrl` to send the user to a different origin (e.g. a frontend
+     * dev server that proxies `/oidc/**` back to the API).
+     */
+    readonly oidcIssuer?: Maybe<string>;
+    /**
+     * Optional API base URL. Used as a fallback rebase origin when neither `appClientUrl` nor
+     * `oidcIssuer` is provided — only the origin is read, so prefix paths like `/api` are ignored.
+     * Prefer `oidcIssuer` for new deployments; `apiBaseUrl` is kept for backwards compatibility
+     * with envs that only declare an API base URL.
+     */
+    readonly apiBaseUrl?: Maybe<string>;
+    /**
+     * Optional client origin to rebase the authorization endpoint onto.
+     *
+     * When set, the path + search of `authorizationEndpoint` are kept and the origin is replaced
+     * with this URL. Takes precedence over both `oidcIssuer` and `apiBaseUrl`. Recommended for any
+     * env where the user-facing URL should differ from the discovered authorization endpoint —
+     * e.g. a frontend dev server that proxies `/oidc/**` to the API on another port. When omitted,
+     * the URL is derived from `oidcIssuer`/`apiBaseUrl` origin (or used verbatim if neither is set),
+     * so the relying party always opens the actual authorization endpoint (typically `/oidc/auth`).
+     */
+    readonly appClientUrl?: Maybe<string>;
+    readonly clientId: string;
+    readonly redirectUri: string;
+    /**
+     * Space-separated scope list. Defaults to {@link DEFAULT_OIDC_RELYING_PARTY_SCOPE}.
+     */
+    readonly scopes?: string;
+    readonly state: string;
+    readonly codeChallenge: string;
+    /**
+     * Optional requested login duration in seconds. When set, the URL includes the
+     * `dbx_session_ttl=<seconds>` query param so the OIDC server applies the requested
+     * lifetime to the issued Session, Grant, and RefreshToken (subject to per-client and
+     * server caps).
+     */
+    readonly requestedSessionTtlSeconds?: Maybe<number>;
+}
+/**
+ * Builds the authorization URL the user opens in a browser to start the PKCE flow.
+ *
+ * The user-facing endpoint is the discovered `authorizationEndpoint` (typically `/oidc/auth`)
+ * with its origin optionally rebased. The rebase origin is the first non-empty value among
+ * `appClientUrl` → `oidcIssuer` origin → `apiBaseUrl` origin. In a typical single-host
+ * deployment all three resolve to the same origin and the rebase is a no-op; in a split-host
+ * setup (frontend dev server proxying `/oidc/**` to the API) `appClientUrl` redirects the user
+ * through the frontend. When none of the three is provided, the discovered endpoint is used
+ * unchanged.
+ *
+ * Always lands at the actual authorization endpoint so oidc-provider can create an interaction
+ * and redirect to the app login page with a `uid`.
+ *
+ * @param input - The authorization URL inputs.
+ * @param input.authorizationEndpoint - The authorization endpoint discovered from OIDC metadata.
+ * @param input.appClientUrl - Optional client origin to rebase the authorization endpoint onto. Takes precedence over `oidcIssuer` and `apiBaseUrl`.
+ * @param input.oidcIssuer - Optional OIDC issuer URL; falls back to its origin as the rebase target when `appClientUrl` is missing.
+ * @param input.apiBaseUrl - Optional API base URL; falls back to its origin as the rebase target when neither `appClientUrl` nor `oidcIssuer` is set.
+ * @param input.clientId - The OAuth client ID.
+ * @param input.redirectUri - The redirect URI registered with the OAuth client.
+ * @param input.scopes - Space-separated scope list. Defaults to {@link DEFAULT_OIDC_RELYING_PARTY_SCOPE}.
+ * @param input.state - The opaque OAuth state token used for CSRF protection.
+ * @param input.codeChallenge - The PKCE code challenge derived from the verifier.
+ * @returns The full authorization URL with all OAuth params merged in.
+ * @throws {OidcRelyingPartyError} When `requestedSessionTtlSeconds` is provided but is not a positive integer.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function buildAuthorizationUrl(input: BuildAuthorizationUrlInput): string;
+export interface PkceMaterial {
+    readonly codeVerifier: string;
+    readonly codeChallenge: string;
+}
+/**
+ * Generates a fresh PKCE code verifier and the matching SHA-256 code challenge.
+ *
+ * @returns A {@link PkceMaterial} pair consisting of the random `codeVerifier` and its derived `codeChallenge`.
+ */
+export declare function generatePkceMaterial(): Promise<PkceMaterial>;
+/**
+ * Generates a random URL-safe state value for the OAuth state parameter.
+ *
+ * @returns A 32-character hex string derived from 16 random bytes.
+ */
+export declare function generateOAuthState(): string;
+export interface ParseAuthorizationRedirectInput {
+    /**
+     * The redirect URL (e.g. `window.location.href`) or a bare authorization code.
+     */
+    readonly url: string;
+    /**
+     * Optional state value to assert against the redirect's `state` when present.
+     */
+    readonly expectedState?: string;
+}
+export interface ParsedAuthorizationRedirect {
+    readonly code: string;
+    readonly state?: string;
+}
+/**
+ * Parses an authorization code out of a redirect URL or a bare code string.
+ *
+ * Validates the `state` parameter when an expected value is provided.
+ *
+ * @param input - The parse inputs.
+ * @param input.url - The redirect URL or bare authorization code.
+ * @param input.expectedState - Optional state value to assert against `state` when present in the URL.
+ * @returns The {@link ParsedAuthorizationRedirect} containing `code` and (when present) `state`.
+ * @throws {OidcRelyingPartyError} When `url` is empty, when the URL contains no `code` parameter, or when `expectedState` does not match the URL's `state`.
+ */
+export declare function parseAuthorizationRedirect(input: ParseAuthorizationRedirectInput): ParsedAuthorizationRedirect;

package/test/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@dereekb/util/test",
-  "version": "13.23.0",
+  "version": "13.24.0",
   "peerDependencies": {
-    "@dereekb/util": "13.23.0",
+    "@dereekb/util": "13.24.0",
     "make-error": "^1.3.6"
   },
   "exports": {