@zudojs/auth-oauth 1.1.1 → 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/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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/auth-oauth",
-  "version": "1.1.1",
+  "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": {
@@ -52,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",