@zudojs/auth-oauth 1.1.0 → 1.2.0

package/README.md

@@ -5,7 +5,15 @@ 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`).
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-auth-oauth](https://zudojs.oyinlola.site/docs/packages-auth-oauth) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-auth-oauth.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
+Built on Node built-ins (`node:crypto` and the global `fetch`), plus
+`@zudojs/errors` (the error base classes) and `@zudojs/security` (the IPv6
+helpers behind the SSRF guard).
 
 ```bash
 pnpm add @zudojs/auth-oauth
@@ -169,7 +177,11 @@ Every one of these is covered by a test in `tests/`.
   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
+  / `metadata.google.internal` name. IPv6 literals that embed an IPv4
+  address (`[::127.0.0.1]`, `[::ffff:0:a9fe:a9fe]`, NAT64
+  `[64:ff9b::169.254.169.254]`, 6to4 `2002::/16`) are judged as that IPv4
+  address, and the local-use NAT64 prefix `64:ff9b:1::/48` is refused.
+  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
@@ -198,6 +210,9 @@ Every one of these is covered by a test in `tests/`.
 
 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.
+`OAuthError` extends the shared `OAuthError` from `@zudojs/errors`, so every
+class below is also a `BaseError`, and its codes equal the shared
+`ErrorCode.OAUTH_*` members.
 
 | Class | Code | Status | Exposed |
 | --- | --- | --- | --- |

package/dist/oauthClient/oauthAuthorize.core.js

@@ -5,7 +5,7 @@
  */
 import { OAuthConfigurationError } from "../oauthErrors/index.js";
 import { assertValidCodeVerifier, deriveCodeChallenge, generateCodeVerifier, } from "../oauthSecurity/index.js";
-import { assertRedirectUriAllowed, resolveAuthorizeUrl, resolveConfig, } from "./oauthConfig.resolve.js";
+import { assertRedirectUriAllowed, assertScopes, resolveAuthorizeUrl, resolveConfig, } from "./oauthConfig.resolve.js";
 /** Parameters the caller may not override through `additionalParams`. */
 const RESERVED_PARAMS = new Set([
     "response_type",
@@ -56,9 +56,11 @@ export function createAuthorizationUrl(config, options) {
     const codeVerifier = options.codeVerifier ?? generateCodeVerifier();
     assertValidCodeVerifier(codeVerifier);
     const codeChallenge = deriveCodeChallenge(codeVerifier);
-    const scopes = options.scopes !== undefined && options.scopes.length > 0
-        ? options.scopes
-        : resolved.scopes;
+    let scopes = resolved.scopes;
+    if (options.scopes !== undefined && options.scopes.length > 0) {
+        assertScopes(options.scopes);
+        scopes = options.scopes;
+    }
     const params = new URLSearchParams(url.search);
     for (const [key, value] of Object.entries(resolved.preset.authorizeParams ?? {})) {
         params.set(key, value);

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

@@ -32,6 +32,16 @@ export interface ResolvedOAuthConfig {
     readonly allowedRedirectUris: readonly string[];
     readonly source: OAuthConfig;
 }
+/**
+ * Reject anything that is not a list of RFC 6749 §3.3 scope-tokens.
+ *
+ * Applied to `config.scopes` and to the per-request `scopes` override on
+ * {@link createAuthorizationUrl}, which previously skipped it — so a blank
+ * or space-containing entry reached the `scope` parameter untouched.
+ *
+ * @throws {OAuthConfigurationError} On a non-string or malformed entry.
+ */
+export declare function assertScopes(scopes: readonly unknown[]): void;
 /**
  * Validate an `OAuthConfig` and merge it with its provider preset.
  *

package/dist/oauthClient/oauthConfig.resolve.js

@@ -36,6 +36,25 @@ function boundedInt(value, fallback, min, max, field) {
     }
     return value;
 }
+/**
+ * Reject anything that is not a list of RFC 6749 §3.3 scope-tokens.
+ *
+ * Applied to `config.scopes` and to the per-request `scopes` override on
+ * {@link createAuthorizationUrl}, which previously skipped it — so a blank
+ * or space-containing entry reached the `scope` parameter untouched.
+ *
+ * @throws {OAuthConfigurationError} On a non-string or malformed entry.
+ */
+export function assertScopes(scopes) {
+    if (!Array.isArray(scopes)) {
+        throw new OAuthConfigurationError("scopes must be an array of scope-tokens.");
+    }
+    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.");
+        }
+    }
+}
 /**
  * Strip a URL's fragment and normalise scheme/host casing for comparison.
  */
@@ -66,11 +85,7 @@ export function resolveConfig(config) {
     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.");
-        }
-    }
+    assertScopes(scopes);
     const fetchImpl = config.fetch ?? globalThis.fetch;
     if (typeof fetchImpl !== "function") {
         throw new OAuthConfigurationError("No fetch implementation available; supply config.fetch.");

package/dist/oauthClient/oauthHttp.core.js

@@ -13,7 +13,7 @@
  * - **Reach** — `redirect: "manual"`, so a 3xx cannot walk the request to a
  *   host that never passed the SSRF guard.
  */
-import { OAuthNetworkError, OAuthProviderError, OAuthResponseError, OAuthResponseTooLargeError, } from "../oauthErrors/index.js";
+import { OAuthError, OAuthNetworkError, OAuthProviderError, OAuthResponseError, OAuthResponseTooLargeError, } from "../oauthErrors/index.js";
 import { parseJsonObject, parseJsonValue } from "../oauthSecurity/index.js";
 /** Provider `error` codes are echoed only if they look like OAuth error codes. */
 const SAFE_ERROR_CODE = /^[A-Za-z0-9_.:-]{1,64}$/;
@@ -94,16 +94,23 @@ export async function requestProviderValue(resolved, request) {
         });
     }
     catch (cause) {
-        const name = cause instanceof Error ? cause.name : "";
-        const timedOut = name === "TimeoutError" || name === "AbortError";
-        throw new OAuthNetworkError(timedOut
-            ? `The ${request.label} request timed out after ${resolved.timeoutMs}ms.`
-            : `The ${request.label} request could not be completed.`, { cause });
+        throw toNetworkError(cause, request.label, resolved.timeoutMs);
     }
     if (response.status >= 300 && response.status < 400) {
         throw new OAuthProviderError(`The ${request.label} endpoint returned an unexpected redirect.`, { providerStatus: response.status });
     }
-    const text = await readCappedText(response, resolved.maxResponseBytes);
+    let text;
+    try {
+        text = await readCappedText(response, resolved.maxResponseBytes);
+    }
+    catch (cause) {
+        // The timeout signal also aborts the body stream, and a transport can
+        // fail mid-body. Both surfaced here as a raw `DOMException` /
+        // transport error rather than the documented `OAuthNetworkError`.
+        if (cause instanceof OAuthError)
+            throw cause;
+        throw toNetworkError(cause, request.label, resolved.timeoutMs);
+    }
     if (!response.ok) {
         let code;
         try {
@@ -128,6 +135,14 @@ export async function requestProviderValue(resolved, request) {
     }
     return payload;
 }
+/** Wrap a transport or timeout failure in the documented error type. */
+function toNetworkError(cause, label, timeoutMs) {
+    const name = cause instanceof Error ? cause.name : "";
+    const timedOut = name === "TimeoutError" || name === "AbortError";
+    return new OAuthNetworkError(timedOut
+        ? `The ${label} request timed out after ${timeoutMs}ms.`
+        : `The ${label} request could not be completed.`, { cause });
+}
 /** Build the `Authorization: Basic` header for client authentication. */
 export function basicAuthHeader(clientId, clientSecret) {
     // RFC 6749 §2.3.1: both halves are form-urlencoded before base64.

package/dist/oauthErrors/oauthError.base.d.ts

@@ -3,8 +3,10 @@
  *
  * @module oauthErrors/oauthError
  *
- * These are defined locally rather than extending `@zudojs/errors` so the
- * package has no `@zudojs/*` dependency at all.
+ * `OAuthError` builds on the shared `OAuthError` in `@zudojs/errors`, so
+ * every class here is a `BaseError` (structured `toJSON`, metadata
+ * redaction, `category`/`severity`). `OAuthErrorCode` values equal the
+ * shared `ErrorCode.OAUTH_*` members.
  *
  * **Secret hygiene.** No constructor here ever interpolates a client secret,
  * an access token, a refresh token or a code verifier into `message`. The
@@ -13,6 +15,7 @@
  * so a provider cannot echo a secret back into your logs. `message` is the
  * first line of `stack`, so keeping it clean keeps the stack clean.
  */
+import { OAuthError as SharedOAuthError } from "@zudojs/errors";
 /** Stable, machine-readable error codes. */
 export declare const OAuthErrorCode: {
     /** The config is unusable: missing field, bad URL, unsupported operation. */
@@ -48,16 +51,12 @@ export interface OAuthErrorOptions {
  *
  * `expose` says whether the message is safe to hand to an end user; it is
  * `true` for request-caused failures and `false` for configuration ones
- * (which describe your deployment, not the request).
+ * (which describe your deployment, not the request). Defaults: 400,
+ * exposed, code `OAUTH_PROVIDER_REJECTED`.
  */
-export declare class OAuthError extends Error {
-    readonly name: string;
+export declare class OAuthError extends SharedOAuthError {
     /** Machine-readable code. */
     readonly code: OAuthErrorCode;
-    /** Suggested HTTP status for a handler that surfaces this. */
-    readonly statusCode: number;
-    /** Whether `message` is safe to return to a client verbatim. */
-    readonly expose: boolean;
     constructor(message: string, options?: OAuthErrorOptions);
 }
 /** The configuration is missing something or is structurally unusable. */

package/dist/oauthErrors/oauthError.base.js

@@ -3,8 +3,10 @@
  *
  * @module oauthErrors/oauthError
  *
- * These are defined locally rather than extending `@zudojs/errors` so the
- * package has no `@zudojs/*` dependency at all.
+ * `OAuthError` builds on the shared `OAuthError` in `@zudojs/errors`, so
+ * every class here is a `BaseError` (structured `toJSON`, metadata
+ * redaction, `category`/`severity`). `OAuthErrorCode` values equal the
+ * shared `ErrorCode.OAUTH_*` members.
  *
  * **Secret hygiene.** No constructor here ever interpolates a client secret,
  * an access token, a refresh token or a code verifier into `message`. The
@@ -13,6 +15,7 @@
  * so a provider cannot echo a secret back into your logs. `message` is the
  * first line of `stack`, so keeping it clean keeps the stack clean.
  */
+import { OAuthError as SharedOAuthError } from "@zudojs/errors";
 /** Stable, machine-readable error codes. */
 export const OAuthErrorCode = {
     /** The config is unusable: missing field, bad URL, unsupported operation. */
@@ -39,21 +42,12 @@ export const OAuthErrorCode = {
  *
  * `expose` says whether the message is safe to hand to an end user; it is
  * `true` for request-caused failures and `false` for configuration ones
- * (which describe your deployment, not the request).
+ * (which describe your deployment, not the request). Defaults: 400,
+ * exposed, code `OAUTH_PROVIDER_REJECTED`.
  */
-export class OAuthError extends Error {
-    name = "OAuthError";
-    /** Machine-readable code. */
-    code;
-    /** Suggested HTTP status for a handler that surfaces this. */
-    statusCode;
-    /** Whether `message` is safe to return to a client verbatim. */
-    expose;
+export class OAuthError extends SharedOAuthError {
     constructor(message, options) {
-        super(message, options?.cause !== undefined ? { cause: options.cause } : {});
-        this.code = options?.code ?? OAuthErrorCode.PROVIDER_REJECTED;
-        this.statusCode = options?.statusCode ?? 400;
-        this.expose = options?.expose ?? true;
+        super(message, options);
     }
 }
 /** The configuration is missing something or is structurally unusable. */

package/dist/oauthSecurity/oauthUrl.guard.js

@@ -26,6 +26,7 @@
  * rebinding) is not caught here. Pair this with network egress controls if
  * you accept endpoint URLs from untrusted operators.
  */
+import { embeddedIpv4, expandIpv6, isNonPublicIpv6Range, } from "@zudojs/security";
 import { OAuthEndpointNotAllowedError } from "../oauthErrors/index.js";
 /** Hostnames that are always refused for a server-fetched endpoint. */
 const BLOCKED_HOST_NAMES = new Set([
@@ -90,40 +91,22 @@ function isNonPublicIpv4(octets) {
         return true; // multicast + reserved + broadcast
     return false;
 }
-/** Whether an IPv6 literal (already stripped of brackets) is non-public. */
+/**
+ * Whether an IPv6 literal (already stripped of brackets) is non-public.
+ *
+ * Any form embedding an IPv4 address (compatible `::/96`, mapped, translated,
+ * NAT64 `64:ff9b::/96`, 6to4) is judged as that IPv4 address. The WHATWG
+ * parser serialises `[::127.0.0.1]` as `[::7f00:1]`, which the old
+ * dotted-form regex never matched. An unparseable literal fails closed.
+ */
 function isNonPublicIpv6(raw) {
-    const host = raw.toLowerCase();
-    if (host === "::" || host === "::1")
+    const groups = expandIpv6(raw);
+    if (!groups)
         return true;
-    // IPv4-mapped / -compatible: judge the embedded IPv4 address.
-    const mapped = /^::(?:ffff:)?(\d{1,3}(?:\.\d{1,3}){3})$/.exec(host);
-    const embedded = mapped?.[1];
-    if (embedded !== undefined) {
-        const octets = parseIpv4(embedded);
-        return octets === undefined ? true : isNonPublicIpv4(octets);
-    }
-    // The WHATWG URL parser rewrites `::ffff:127.0.0.1` as `::ffff:7f00:1`,
-    // so the hex form has to be decoded back to its embedded IPv4 address.
-    const hexMapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
-    const high = hexMapped?.[1];
-    const low = hexMapped?.[2];
-    if (high !== undefined && low !== undefined) {
-        const word1 = Number.parseInt(high, 16);
-        const word2 = Number.parseInt(low, 16);
-        return isNonPublicIpv4([
-            (word1 >> 8) & 0xff,
-            word1 & 0xff,
-            (word2 >> 8) & 0xff,
-            word2 & 0xff,
-        ]);
-    }
-    if (/^f[cd][0-9a-f]{2}:/.test(host))
-        return true; // fc00::/7 unique local
-    if (/^fe[89ab][0-9a-f]:/.test(host))
-        return true; // fe80::/10 link-local
-    if (/^ff[0-9a-f]{2}:/.test(host))
-        return true; // ff00::/8 multicast
-    return false;
+    const embedded = embeddedIpv4(groups);
+    if (embedded)
+        return isNonPublicIpv4(embedded);
+    return isNonPublicIpv6Range(groups);
 }
 /**
  * Whether a host literal is one this package refuses to fetch from.
@@ -132,9 +115,15 @@ function isNonPublicIpv6(raw) {
  */
 export function isBlockedFetchHost(hostname) {
     const host = hostname.toLowerCase();
-    const bare = host.startsWith("[") && host.endsWith("]")
+    const unbracketed = host.startsWith("[") && host.endsWith("]")
         ? host.slice(1, -1)
         : host;
+    // A trailing dot marks a fully-qualified name (`localhost.`,
+    // `metadata.google.internal.`). DNS resolves it to the same address as
+    // the undotted form, but the WHATWG parser keeps the dot on domain
+    // hosts, so without stripping it every name-based rule below was one
+    // character away from being bypassed.
+    const bare = unbracketed.replace(/\.+$/, "");
     if (BLOCKED_HOST_NAMES.has(bare))
         return true;
     for (const suffix of BLOCKED_HOST_SUFFIXES) {

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/auth-oauth",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "OAuth2 authorization-code client for the Zudojs framework — PKCE S256, mandatory state, SSRF-guarded endpoints, and provider presets for Google, GitHub, Microsoft, Apple and Discord.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -48,6 +52,10 @@
     "url": "https://github.com/oyinlola-tech/zudo",
     "directory": "packages/auth-oauth"
   },
+  "dependencies": {
+    "@zudojs/errors": "1.1.0",
+    "@zudojs/security": "1.1.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",