@zudojs/auth-oauth 1.1.1 → 1.2.1

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
@@ -84,7 +92,9 @@ app.get("/auth/callback", async (req, res) => {
   const profile = await fetchUserInfo(config, tokens.accessToken);
 
   if (profile.email === undefined) {
-    return res.status(400).send("This provider did not release an email address.");
+    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
@@ -107,29 +117,29 @@ const fresh = await refreshAccessToken(config, storedRefreshToken);
 
 ## 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. |
+| 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 | |
+| 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.
@@ -140,7 +150,7 @@ same validation.
 
 - **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
+  `/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.
 
@@ -165,11 +175,15 @@ Every one of these is covered by a test in `tests/`.
   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*
+  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
+  / `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
@@ -179,7 +193,7 @@ Every one of these is covered by a test in `tests/`.
   `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
+- **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
@@ -198,31 +212,34 @@ 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.
-
-| 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 |
+`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 |
+| ------------------------------ | --------------------------------- | ------ | ------- |
+| `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` |
+| 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.
 

package/dist/oauthClient/oauthConfig.resolve.js

@@ -28,7 +28,9 @@ function requireString(value, field) {
 function boundedInt(value, fallback, min, max, field) {
     if (value === undefined)
         return fallback;
-    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value)) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        !Number.isInteger(value)) {
         throw new OAuthConfigurationError(`${field} must be an integer.`);
     }
     if (value < min || value > max) {
@@ -50,7 +52,8 @@ export function assertScopes(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)) {
+        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.");
         }
     }

package/dist/oauthClient/oauthHttp.core.js

@@ -20,7 +20,9 @@ const SAFE_ERROR_CODE = /^[A-Za-z0-9_.:-]{1,64}$/;
 /** Read a response body, refusing to buffer more than `maxBytes`. */
 async function readCappedText(response, maxBytes) {
     const declared = response.headers.get("content-length");
-    if (declared !== null && /^\d+$/.test(declared) && Number(declared) > maxBytes) {
+    if (declared !== null &&
+        /^\d+$/.test(declared) &&
+        Number(declared) > maxBytes) {
         throw new OAuthResponseTooLargeError(maxBytes);
     }
     const body = response.body;

package/dist/oauthClient/oauthUserInfo.core.js

@@ -7,7 +7,7 @@ import { OAuthResponseError } from "../oauthErrors/index.js";
 import { normalizeUserInfo } from "../oauthProviders/index.js";
 import { assertSafeUrl } from "../oauthSecurity/index.js";
 import { resolveConfig, resolveUserInfoUrl, } from "./oauthConfig.resolve.js";
-import { requestProviderJson, requestProviderValue, } from "./oauthHttp.core.js";
+import { requestProviderJson, requestProviderValue } from "./oauthHttp.core.js";
 /**
  * GitHub's `/user` omits `email` whenever the address is private — which is
  * the default for new accounts. When `user:email` was granted we ask

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/oauthProviders/oauthProvider.presets.js

@@ -62,7 +62,13 @@ export const PROVIDER_PRESETS = {
         authorizeUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
         tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
         userInfoUrl: "https://graph.microsoft.com/v1.0/me",
-        defaultScopes: ["openid", "email", "profile", "offline_access", "User.Read"],
+        defaultScopes: [
+            "openid",
+            "email",
+            "profile",
+            "offline_access",
+            "User.Read",
+        ],
         clientAuth: "body",
         supportsRefresh: true,
     },

package/dist/oauthSecurity/oauthJson.sanitize.js

@@ -59,7 +59,9 @@ export function sanitizeJsonValue(value) {
  */
 export function parseJsonObject(text, label) {
     const sanitized = parseJsonValue(text, label);
-    if (sanitized === null || typeof sanitized !== "object" || Array.isArray(sanitized)) {
+    if (sanitized === null ||
+        typeof sanitized !== "object" ||
+        Array.isArray(sanitized)) {
         throw new OAuthResponseError(`${label} did not return a JSON object.`);
     }
     return sanitized;

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,7 @@ function isNonPublicIpv6(raw) {
  */
 export function isBlockedFetchHost(hostname) {
     const host = hostname.toLowerCase();
-    const unbracketed = host.startsWith("[") && host.endsWith("]")
-        ? host.slice(1, -1)
-        : host;
+    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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/auth-oauth",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "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.2.0",
+    "@zudojs/security": "1.2.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",