@zudojs/auth-oauth 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# @zudojs/auth-oauth
+
+OAuth2 **authorization-code** client for the Zudojs framework: PKCE `S256` by
+default, mandatory anti-CSRF `state` with a timing-safe check, an SSRF guard on
+every endpoint URL, a redirect-URI allowlist, and size- and time-bounded
+requests to the provider.
+
+Depends on nothing but Node built-ins (`node:crypto` and the global `fetch`).
+
+```bash
+pnpm add @zudojs/auth-oauth
+```
+
+Requires Node >= 24.
+
+## Why this package exists
+
+`@zudojs/auth` handles passwords, JWTs, sessions and RBAC. It has no OAuth2 and
+never did. This package is the real implementation: it builds the authorization
+request, exchanges the code, refreshes tokens and normalises the provider's
+profile — with the parts people usually skip (PKCE, state, SSRF, response
+bounds) built in rather than bolted on.
+
+It does **not** create users, issue your own sessions, or verify an OIDC
+`id_token` signature. It gets you a verified provider profile; what you do with
+it is your application's business.
+
+## The whole flow
+
+```ts
+import {
+  createAuthorizationUrl,
+  exchangeCodeForToken,
+  fetchUserInfo,
+  generateState,
+  verifyState,
+  type OAuthConfig,
+} from "@zudojs/auth-oauth";
+
+const config: OAuthConfig = {
+  provider: "google",
+  clientId: process.env["GOOGLE_CLIENT_ID"] ?? "",
+  clientSecret: process.env["GOOGLE_CLIENT_SECRET"] ?? "",
+  // Every redirect URI this client may use, listed exactly.
+  allowedRedirectUris: ["https://app.example.com/auth/callback"],
+};
+
+const REDIRECT_URI = "https://app.example.com/auth/callback";
+
+// 1. Start the flow.
+app.get("/auth/google", (req, res) => {
+  const state = generateState();
+  const { url, codeVerifier } = createAuthorizationUrl(config, {
+    state,
+    redirectUri: REDIRECT_URI,
+  });
+
+  // Both values are secrets. Keep them server-side, scoped to this session,
+  // and short-lived (a few minutes is plenty).
+  req.session.oauth = { state, codeVerifier };
+  res.redirect(url);
+});
+
+// 2. Handle the callback.
+app.get("/auth/callback", async (req, res) => {
+  const pending = req.session.oauth;
+  delete req.session.oauth; // single use, whatever happens next
+
+  if (pending === undefined) return res.status(400).send("No pending login.");
+
+  // 3. Verify state before anything else touches the provider.
+  if (!verifyState(pending.state, String(req.query["state"] ?? ""))) {
+    return res.status(400).send("Invalid state.");
+  }
+
+  // 4. Exchange the code, proving possession of the PKCE verifier.
+  const tokens = await exchangeCodeForToken(config, {
+    code: String(req.query["code"] ?? ""),
+    codeVerifier: pending.codeVerifier,
+    redirectUri: REDIRECT_URI,
+  });
+
+  // 5. Fetch the profile.
+  const profile = await fetchUserInfo(config, tokens.accessToken);
+
+  if (profile.email === undefined) {
+    return res.status(400).send("This provider did not release an email address.");
+  }
+
+  // Now it is your application's turn: find or create the local account keyed
+  // by (provider, profile.providerId) — not by email alone.
+  const user = await users.upsertFromOAuth("google", profile);
+  req.session.userId = user.id;
+  res.redirect("/");
+});
+```
+
+Refreshing later:
+
+```ts
+import { refreshAccessToken } from "@zudojs/auth-oauth";
+
+const fresh = await refreshAccessToken(config, storedRefreshToken);
+// Most providers do not rotate the refresh token; keep the old one unless
+// `fresh.refreshToken` is set.
+```
+
+## API
+
+| Export | What it does |
+| --- | --- |
+| `createAuthorizationUrl(config, options)` | Builds the authorize URL. Returns `{ url, state, codeVerifier, codeChallenge }`. |
+| `exchangeCodeForToken(config, options)` | Authorization-code grant. Returns a validated `OAuthTokenSet`. |
+| `refreshAccessToken(config, refreshToken)` | Refresh-token grant, where the provider supports one. |
+| `fetchUserInfo(config, accessToken)` | Bearer GET of the user-info endpoint, normalised to `OAuthUserInfo`. |
+| `generateState()` / `verifyState(expected, received)` | 256-bit state, timing-safe comparison. |
+| `generateCodeVerifier()` / `deriveCodeChallenge(verifier)` | PKCE primitives (`S256`). |
+| `parseTokenResponse(payload)` | Validate a token payload you obtained elsewhere. |
+| `normalizeUserInfo(provider, payload)` | Normalise a profile payload you obtained elsewhere. |
+| `assertSafeUrl(url, label, use)` / `isBlockedFetchHost(host)` | The URL and SSRF guards, exposed for your own checks. |
+| `PROVIDER_PRESETS` | Endpoint defaults per provider. |
+
+## Providers
+
+| Provider | Endpoints | Client auth | Refresh | Notes |
+| --- | --- | --- | --- | --- |
+| `google` | preset | body | yes | `access_type=offline` + `prompt=consent` are sent so a refresh token is actually issued. |
+| `github` | preset | body | **no** | Classic OAuth App tokens do not expire and no refresh token is issued; `refreshAccessToken` throws rather than making a pointless request. |
+| `microsoft` | preset (`common` tenant) | body | yes | Override `authorizeUrl`/`tokenUrl` for a single-tenant app. |
+| `apple` | preset | body | yes | `clientSecret` is the ES256 JWT you mint from your private key — this package does not generate it. Apple has **no user-info endpoint**; the profile is in the `id_token`, so `fetchUserInfo` throws for `apple`. |
+| `discord` | preset | **basic** | yes | |
+| `custom` | you supply all three URLs | body | yes | |
+
+Any preset URL can be overridden on the config; every override goes through the
+same validation.
+
+### About email
+
+`OAuthUserInfo.email` is **optional**, and deliberately so.
+
+- **GitHub** omits `email` from `/user` whenever the address is private, which
+  is the default. When the `user:email` scope was granted, this package asks
+  `/user/emails` and uses the primary *verified* address. Without the scope, or
+  without a verified primary, the profile simply comes back with no email.
+- **Discord** returns no email unless the `email` scope was granted.
+
+No address is ever synthesised from a login name. Key your local accounts by
+`(provider, providerId)`, not by email — emails change, and an unverified email
+from a provider is not proof of anything.
+
+## Security
+
+Every one of these is covered by a test in `tests/`.
+
+- **`state` is mandatory.** `createAuthorizationUrl` refuses to build a URL
+  without one, and refuses one under 16 characters. `verifyState` compares with
+  `crypto.timingSafeEqual` after a length check, and returns `false` for empty
+  or non-string input, so a missing `state` can never pass.
+- **PKCE `S256`, always.** The verifier is 384 bits from `randomBytes`, encoded
+  base64url so it lands in the unreserved alphabet with no modulo bias. There is
+  no switch to turn PKCE off and `plain` is not implemented.
+- **Redirect-URI allowlist.** `allowedRedirectUris` is required and non-empty;
+  the requested URI is parsed, canonicalised (scheme and host case-insensitive,
+  fragment forbidden, path and query byte-exact) and must match an entry. An
+  arbitrary redirect target is never reflected.
+- **URL validation and SSRF guard.** Every URL must be `https` — `http` is
+  tolerated only for `localhost` / `127.0.0.1` / `[::1]` and only on
+  browser-facing URLs — and must not embed credentials. The *server-fetched*
+  endpoints (token, user-info) additionally may not point at a loopback,
+  private, CGNAT, link-local, unique-local, multicast or reserved address, at
+  `169.254.169.254` and friends, or at a `localhost` / `*.local` / `*.internal`
+  / `metadata.google.internal` name. Redirects are not followed
+  (`redirect: "manual"`), so a 3xx cannot walk the request somewhere that never
+  passed the guard.
+  **Limit:** the check is on the literal host; DNS is not resolved, so DNS
+  rebinding is out of scope. Pair this with network egress controls if endpoint
+  URLs come from untrusted operators.
+- **Bounded responses.** Every provider request carries
+  `AbortSignal.timeout(timeoutMs)` (default 10s) and the body is streamed and
+  abandoned the moment it passes `maxResponseBytes` (default 256 KiB); an
+  oversized `Content-Length` is refused before a byte is read.
+- **Defensive parsing.** A token response must be a JSON *object* with a
+  non-blank string `access_token`; `expires_in` must be a non-negative integer
+  (or its decimal string); `refresh_token`, `id_token`, `scope` and `token_type`
+  must be strings when present. `__proto__`, `constructor` and `prototype` are
+  stripped from every object reconstructed from provider JSON, at every depth.
+- **No secret in any error.** No message, and therefore no stack, ever contains
+  the client secret, an access or refresh token, or a PKCE verifier. The only
+  provider-supplied text that reaches a message is the OAuth `error` code, and
+  only after passing `[A-Za-z0-9_.:-]{1,64}` — an `error_description` is never
+  interpolated, so a provider cannot echo material into your logs.
+  The one thing this cannot police is `cause`: when you supply your own
+  `config.fetch`, its rejection is attached untouched.
+- **Secrets travel in the body or the `Authorization` header**, never in a URL
+  where a proxy or access log would capture them.
+
+## Errors
+
+Every failure is an `OAuthError` with a machine-readable `code`, a suggested
+`statusCode`, and `expose` saying whether the message is safe to show a user.
+
+| Class | Code | Status | Exposed |
+| --- | --- | --- | --- |
+| `OAuthConfigurationError` | `OAUTH_CONFIGURATION_INVALID` | 500 | no |
+| `OAuthEndpointNotAllowedError` | `OAUTH_ENDPOINT_NOT_ALLOWED` | 500 | no |
+| `OAuthRedirectUriError` | `OAUTH_REDIRECT_URI_NOT_ALLOWED` | 400 | yes |
+| `OAuthStateMismatchError` | `OAUTH_STATE_MISMATCH` | 400 | yes |
+| `OAuthProviderError` | `OAUTH_PROVIDER_REJECTED` | 502 | yes |
+| `OAuthResponseError` | `OAUTH_PROVIDER_RESPONSE_INVALID` | 502 | yes |
+| `OAuthResponseTooLargeError` | `OAUTH_RESPONSE_TOO_LARGE` | 502 | yes |
+| `OAuthNetworkError` | `OAUTH_NETWORK` | 504 | yes |
+
+## Configuration reference
+
+| Field | Required | Default |
+| --- | --- | --- |
+| `provider` | yes | — |
+| `clientId`, `clientSecret` | yes | — |
+| `allowedRedirectUris` | yes, non-empty | — |
+| `authorizeUrl`, `tokenUrl`, `userInfoUrl` | only for `custom` | the preset's |
+| `scopes` | no | the preset's |
+| `clientAuthMethod` | no | the preset's |
+| `timeoutMs` | no | `10000` (1 - 120000) |
+| `maxResponseBytes` | no | `262144` (1024 - 5242880) |
+| `fetch` | no | global `fetch` |
+
+Out-of-range values are rejected, not clamped.
+
+## What this package does not do
+
+- **No `id_token` verification.** `idToken` is passed through unparsed and
+  unverified. If you rely on its claims, verify the signature against the
+  provider's JWKS yourself.
+- **No implicit, password or client-credentials grant.** Authorization code
+  only, which is the only flow current guidance recommends for user login.
+- **No state or verifier storage.** Where you keep them between the two requests
+  is your decision; the package hands them to you and asks for them back.
+- **No account linking, user creation or session issuing.** Pair it with
+  `@zudojs/auth` for sessions and tokens.
+
+## Development
+
+```bash
+pnpm --filter @zudojs/auth-oauth typecheck   # both tsconfigs, full strictness
+pnpm --filter @zudojs/auth-oauth test
+pnpm --filter @zudojs/auth-oauth build
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @zudojs/auth-oauth
+ *
+ * A small, strict OAuth2 authorization-code client: PKCE `S256` by default,
+ * mandatory anti-CSRF `state` with a timing-safe check, an SSRF guard on
+ * every endpoint URL, a redirect-URI allowlist, size- and time-bounded
+ * provider requests, and defensive parsing of everything a provider returns.
+ *
+ * Depends on nothing but Node built-ins.
+ *
+ * @module @zudojs/auth-oauth
+ */
+export * from "./oauthTypes/index.js";
+export * from "./oauthErrors/index.js";
+export * from "./oauthSecurity/index.js";
+export * from "./oauthProviders/index.js";
+export * from "./oauthClient/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @zudojs/auth-oauth
+ *
+ * A small, strict OAuth2 authorization-code client: PKCE `S256` by default,
+ * mandatory anti-CSRF `state` with a timing-safe check, an SSRF guard on
+ * every endpoint URL, a redirect-URI allowlist, size- and time-bounded
+ * provider requests, and defensive parsing of everything a provider returns.
+ *
+ * Depends on nothing but Node built-ins.
+ *
+ * @module @zudojs/auth-oauth
+ */
+export * from "./oauthTypes/index.js";
+export * from "./oauthErrors/index.js";
+export * from "./oauthSecurity/index.js";
+export * from "./oauthProviders/index.js";
+export * from "./oauthClient/index.js";
+//# sourceMappingURL=index.js.map

package/dist/oauthClient/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The OAuth2 authorization-code client.
+ *
+ * @module oauthClient
+ */
+export { DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS, DEFAULT_MAX_RESPONSE_BYTES, MIN_MAX_RESPONSE_BYTES, MAX_MAX_RESPONSE_BYTES, type ResolvedOAuthConfig, resolveConfig, resolveAuthorizeUrl, resolveTokenUrl, resolveUserInfoUrl, assertRedirectUriAllowed, } from "./oauthConfig.resolve.js";
+export { createAuthorizationUrl } from "./oauthAuthorize.core.js";
+export { parseTokenResponse, exchangeCodeForToken, refreshAccessToken, } from "./oauthToken.core.js";
+export { fetchUserInfo } from "./oauthUserInfo.core.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/oauthClient/index.js

@@ -0,0 +1,10 @@
+/**
+ * The OAuth2 authorization-code client.
+ *
+ * @module oauthClient
+ */
+export { DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS, DEFAULT_MAX_RESPONSE_BYTES, MIN_MAX_RESPONSE_BYTES, MAX_MAX_RESPONSE_BYTES, resolveConfig, resolveAuthorizeUrl, resolveTokenUrl, resolveUserInfoUrl, assertRedirectUriAllowed, } from "./oauthConfig.resolve.js";
+export { createAuthorizationUrl } from "./oauthAuthorize.core.js";
+export { parseTokenResponse, exchangeCodeForToken, refreshAccessToken, } from "./oauthToken.core.js";
+export { fetchUserInfo } from "./oauthUserInfo.core.js";
+//# sourceMappingURL=index.js.map

package/dist/oauthClient/oauthAuthorize.core.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Authorization-request construction.
+ *
+ * @module oauthClient/oauthAuthorize
+ */
+import type { AuthorizationUrlOptions, AuthorizationUrlResult, OAuthConfig } from "../oauthTypes/index.js";
+/**
+ * Build the authorization-request URL for the authorization-code flow.
+ *
+ * Always emits `response_type=code`, a mandatory `state`, and PKCE with
+ * `code_challenge_method=S256`. There is no way to turn PKCE off and no
+ * `plain` fallback.
+ *
+ * The returned `codeVerifier` and `state` must be stored server-side against
+ * the user's session — the verifier is a secret and must never be sent to the
+ * browser in a readable form.
+ *
+ * @example
+ * ```ts
+ * const state = generateState();
+ * const { url, codeVerifier } = createAuthorizationUrl(config, {
+ *   state,
+ *   redirectUri: "https://app.example.com/auth/callback",
+ * });
+ * req.session.oauth = { state, codeVerifier };
+ * res.redirect(url);
+ * ```
+ *
+ * @throws {OAuthConfigurationError} If `state` is missing or the config is bad.
+ * @throws {OAuthRedirectUriError} If `redirectUri` is not allowlisted.
+ * @throws {OAuthEndpointNotAllowedError} If `authorizeUrl` fails the URL guard.
+ */
+export declare function createAuthorizationUrl(config: OAuthConfig, options: AuthorizationUrlOptions): AuthorizationUrlResult;
+//# sourceMappingURL=oauthAuthorize.core.d.ts.map

package/dist/oauthClient/oauthAuthorize.core.js

@@ -0,0 +1,93 @@
+/**
+ * Authorization-request construction.
+ *
+ * @module oauthClient/oauthAuthorize
+ */
+import { OAuthConfigurationError } from "../oauthErrors/index.js";
+import { assertValidCodeVerifier, deriveCodeChallenge, generateCodeVerifier, } from "../oauthSecurity/index.js";
+import { assertRedirectUriAllowed, resolveAuthorizeUrl, resolveConfig, } from "./oauthConfig.resolve.js";
+/** Parameters the caller may not override through `additionalParams`. */
+const RESERVED_PARAMS = new Set([
+    "response_type",
+    "client_id",
+    "client_secret",
+    "redirect_uri",
+    "scope",
+    "state",
+    "code_challenge",
+    "code_challenge_method",
+]);
+/**
+ * Build the authorization-request URL for the authorization-code flow.
+ *
+ * Always emits `response_type=code`, a mandatory `state`, and PKCE with
+ * `code_challenge_method=S256`. There is no way to turn PKCE off and no
+ * `plain` fallback.
+ *
+ * The returned `codeVerifier` and `state` must be stored server-side against
+ * the user's session — the verifier is a secret and must never be sent to the
+ * browser in a readable form.
+ *
+ * @example
+ * ```ts
+ * const state = generateState();
+ * const { url, codeVerifier } = createAuthorizationUrl(config, {
+ *   state,
+ *   redirectUri: "https://app.example.com/auth/callback",
+ * });
+ * req.session.oauth = { state, codeVerifier };
+ * res.redirect(url);
+ * ```
+ *
+ * @throws {OAuthConfigurationError} If `state` is missing or the config is bad.
+ * @throws {OAuthRedirectUriError} If `redirectUri` is not allowlisted.
+ * @throws {OAuthEndpointNotAllowedError} If `authorizeUrl` fails the URL guard.
+ */
+export function createAuthorizationUrl(config, options) {
+    const resolved = resolveConfig(config);
+    if (typeof options.state !== "string" || options.state.trim().length === 0) {
+        throw new OAuthConfigurationError("state is required: an authorization request without CSRF state is not supported.");
+    }
+    if (options.state.length < 16) {
+        throw new OAuthConfigurationError("state must be at least 16 characters of unguessable randomness.");
+    }
+    const redirectUri = assertRedirectUriAllowed(resolved, options.redirectUri);
+    const url = resolveAuthorizeUrl(resolved);
+    const codeVerifier = options.codeVerifier ?? generateCodeVerifier();
+    assertValidCodeVerifier(codeVerifier);
+    const codeChallenge = deriveCodeChallenge(codeVerifier);
+    const scopes = options.scopes !== undefined && options.scopes.length > 0
+        ? options.scopes
+        : resolved.scopes;
+    const params = new URLSearchParams(url.search);
+    for (const [key, value] of Object.entries(resolved.preset.authorizeParams ?? {})) {
+        params.set(key, value);
+    }
+    for (const [key, value] of Object.entries(options.additionalParams ?? {})) {
+        if (RESERVED_PARAMS.has(key)) {
+            throw new OAuthConfigurationError(`additionalParams may not override the reserved parameter "${key}".`);
+        }
+        if (typeof value !== "string") {
+            throw new OAuthConfigurationError("additionalParams values must be strings.");
+        }
+        params.set(key, value);
+    }
+    params.set("response_type", "code");
+    params.set("client_id", resolved.clientId);
+    params.set("redirect_uri", redirectUri);
+    if (scopes.length > 0)
+        params.set("scope", scopes.join(" "));
+    params.set("state", options.state);
+    params.set("code_challenge", codeChallenge);
+    params.set("code_challenge_method", "S256");
+    if (options.nonce !== undefined)
+        params.set("nonce", options.nonce);
+    url.search = params.toString();
+    return {
+        url: url.toString(),
+        state: options.state,
+        codeVerifier,
+        codeChallenge,
+    };
+}
+//# sourceMappingURL=oauthAuthorize.core.js.map

package/dist/oauthClient/oauthConfig.resolve.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Configuration resolution: preset merge, URL validation, redirect allowlist.
+ *
+ * @module oauthClient/oauthConfig
+ *
+ * Every public entry point resolves the config first, so a bad endpoint or a
+ * disallowed redirect URI is rejected before a single byte leaves the process.
+ */
+import { type OAuthProviderPreset } from "../oauthProviders/index.js";
+import type { ClientAuthMethod, FetchLike, OAuthConfig, OAuthProvider } from "../oauthTypes/index.js";
+/** Default per-request timeout. */
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+/** Upper bound accepted for `timeoutMs`. */
+export declare const MAX_TIMEOUT_MS = 120000;
+/** Default response-body cap: 256 KiB. */
+export declare const DEFAULT_MAX_RESPONSE_BYTES = 262144;
+/** Lower bound accepted for `maxResponseBytes`. */
+export declare const MIN_MAX_RESPONSE_BYTES = 1024;
+/** Upper bound accepted for `maxResponseBytes`: 5 MiB. */
+export declare const MAX_MAX_RESPONSE_BYTES = 5242880;
+/** A validated configuration. Endpoint URLs are resolved on demand. */
+export interface ResolvedOAuthConfig {
+    readonly provider: OAuthProvider;
+    readonly preset: OAuthProviderPreset;
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly scopes: readonly string[];
+    readonly clientAuth: ClientAuthMethod;
+    readonly timeoutMs: number;
+    readonly maxResponseBytes: number;
+    readonly fetchImpl: FetchLike;
+    readonly allowedRedirectUris: readonly string[];
+    readonly source: OAuthConfig;
+}
+/**
+ * Validate an `OAuthConfig` and merge it with its provider preset.
+ *
+ * @throws {OAuthConfigurationError} For a missing or out-of-range field.
+ * @throws {OAuthEndpointNotAllowedError} For an unacceptable redirect URI.
+ */
+export declare function resolveConfig(config: OAuthConfig): ResolvedOAuthConfig;
+/** The authorization endpoint, validated for browser use. */
+export declare function resolveAuthorizeUrl(resolved: ResolvedOAuthConfig): URL;
+/** The token endpoint, validated for server-side fetching. */
+export declare function resolveTokenUrl(resolved: ResolvedOAuthConfig): URL;
+/** The user-info endpoint, validated for server-side fetching. */
+export declare function resolveUserInfoUrl(resolved: ResolvedOAuthConfig): URL;
+/**
+ * Check a redirect URI against the caller's allowlist.
+ *
+ * The URI is parsed and canonicalised (scheme and host case-insensitive,
+ * fragment forbidden, path and query byte-exact) and must match an allowlist
+ * entry. An arbitrary redirect target is never reflected into the
+ * authorization request.
+ *
+ * @returns The canonical form to send as `redirect_uri`.
+ * @throws {OAuthRedirectUriError} If it is not allowlisted.
+ */
+export declare function assertRedirectUriAllowed(resolved: ResolvedOAuthConfig, redirectUri: string): string;
+//# sourceMappingURL=oauthConfig.resolve.d.ts.map

package/dist/oauthClient/oauthConfig.resolve.js

@@ -0,0 +1,140 @@
+/**
+ * Configuration resolution: preset merge, URL validation, redirect allowlist.
+ *
+ * @module oauthClient/oauthConfig
+ *
+ * Every public entry point resolves the config first, so a bad endpoint or a
+ * disallowed redirect URI is rejected before a single byte leaves the process.
+ */
+import { OAuthConfigurationError, OAuthRedirectUriError, } from "../oauthErrors/index.js";
+import { PROVIDER_PRESETS, } from "../oauthProviders/index.js";
+import { assertSafeUrl } from "../oauthSecurity/index.js";
+/** Default per-request timeout. */
+export const DEFAULT_TIMEOUT_MS = 10_000;
+/** Upper bound accepted for `timeoutMs`. */
+export const MAX_TIMEOUT_MS = 120_000;
+/** Default response-body cap: 256 KiB. */
+export const DEFAULT_MAX_RESPONSE_BYTES = 262_144;
+/** Lower bound accepted for `maxResponseBytes`. */
+export const MIN_MAX_RESPONSE_BYTES = 1_024;
+/** Upper bound accepted for `maxResponseBytes`: 5 MiB. */
+export const MAX_MAX_RESPONSE_BYTES = 5_242_880;
+function requireString(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new OAuthConfigurationError(`${field} is required and must be a non-empty string.`);
+    }
+    return value;
+}
+function boundedInt(value, fallback, min, max, field) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value)) {
+        throw new OAuthConfigurationError(`${field} must be an integer.`);
+    }
+    if (value < min || value > max) {
+        throw new OAuthConfigurationError(`${field} must be between ${min} and ${max}.`);
+    }
+    return value;
+}
+/**
+ * Strip a URL's fragment and normalise scheme/host casing for comparison.
+ */
+function canonicalRedirect(url) {
+    return `${url.protocol}//${url.host}${url.pathname}${url.search}`;
+}
+/**
+ * Validate an `OAuthConfig` and merge it with its provider preset.
+ *
+ * @throws {OAuthConfigurationError} For a missing or out-of-range field.
+ * @throws {OAuthEndpointNotAllowedError} For an unacceptable redirect URI.
+ */
+export function resolveConfig(config) {
+    if (config === null || typeof config !== "object") {
+        throw new OAuthConfigurationError("An OAuth configuration object is required.");
+    }
+    const preset = PROVIDER_PRESETS[config.provider];
+    if (preset === undefined) {
+        throw new OAuthConfigurationError("Unknown OAuth provider.");
+    }
+    const clientId = requireString(config.clientId, "clientId");
+    const clientSecret = requireString(config.clientSecret, "clientSecret");
+    const allowlist = config.allowedRedirectUris;
+    if (!Array.isArray(allowlist) || allowlist.length === 0) {
+        throw new OAuthConfigurationError("allowedRedirectUris must list at least one exact redirect URI.");
+    }
+    const allowedRedirectUris = allowlist.map((entry, index) => canonicalRedirect(assertSafeUrl(entry, `allowedRedirectUris[${index}]`, "browser")));
+    const scopes = config.scopes !== undefined && config.scopes.length > 0
+        ? config.scopes
+        : preset.defaultScopes;
+    for (const scope of scopes) {
+        if (typeof scope !== "string" || !/^[\x21\x23-\x5B\x5D-\x7E]+$/.test(scope)) {
+            throw new OAuthConfigurationError("Each scope must be a non-empty RFC 6749 scope-token.");
+        }
+    }
+    const fetchImpl = config.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+        throw new OAuthConfigurationError("No fetch implementation available; supply config.fetch.");
+    }
+    return {
+        provider: config.provider,
+        preset,
+        clientId,
+        clientSecret,
+        scopes,
+        clientAuth: config.clientAuthMethod ?? preset.clientAuth,
+        timeoutMs: boundedInt(config.timeoutMs, DEFAULT_TIMEOUT_MS, 1, MAX_TIMEOUT_MS, "timeoutMs"),
+        maxResponseBytes: boundedInt(config.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES, MIN_MAX_RESPONSE_BYTES, MAX_MAX_RESPONSE_BYTES, "maxResponseBytes"),
+        fetchImpl: fetchImpl,
+        allowedRedirectUris,
+        source: config,
+    };
+}
+/** The authorization endpoint, validated for browser use. */
+export function resolveAuthorizeUrl(resolved) {
+    const raw = resolved.source.authorizeUrl ?? resolved.preset.authorizeUrl;
+    if (raw === undefined) {
+        throw new OAuthConfigurationError("authorizeUrl is required for this provider.");
+    }
+    return assertSafeUrl(raw, "authorizeUrl", "browser");
+}
+/** The token endpoint, validated for server-side fetching. */
+export function resolveTokenUrl(resolved) {
+    const raw = resolved.source.tokenUrl ?? resolved.preset.tokenUrl;
+    if (raw === undefined) {
+        throw new OAuthConfigurationError("tokenUrl is required for this provider.");
+    }
+    return assertSafeUrl(raw, "tokenUrl", "fetch");
+}
+/** The user-info endpoint, validated for server-side fetching. */
+export function resolveUserInfoUrl(resolved) {
+    const raw = resolved.source.userInfoUrl ?? resolved.preset.userInfoUrl;
+    if (raw === undefined) {
+        throw new OAuthConfigurationError(resolved.provider === "apple"
+            ? "Apple has no user-info endpoint; read the profile from the id_token returned by the token exchange."
+            : "userInfoUrl is required for this provider.");
+    }
+    return assertSafeUrl(raw, "userInfoUrl", "fetch");
+}
+/**
+ * Check a redirect URI against the caller's allowlist.
+ *
+ * The URI is parsed and canonicalised (scheme and host case-insensitive,
+ * fragment forbidden, path and query byte-exact) and must match an allowlist
+ * entry. An arbitrary redirect target is never reflected into the
+ * authorization request.
+ *
+ * @returns The canonical form to send as `redirect_uri`.
+ * @throws {OAuthRedirectUriError} If it is not allowlisted.
+ */
+export function assertRedirectUriAllowed(resolved, redirectUri) {
+    const url = assertSafeUrl(redirectUri, "redirectUri", "browser");
+    if (url.hash !== "") {
+        throw new OAuthRedirectUriError("redirectUri must not contain a fragment.");
+    }
+    const canonical = canonicalRedirect(url);
+    if (!resolved.allowedRedirectUris.includes(canonical)) {
+        throw new OAuthRedirectUriError("redirectUri is not in the configured allowlist.");
+    }
+    return canonical;
+}
+//# sourceMappingURL=oauthConfig.resolve.js.map