@zudojs/auth-oauth 1.1.0

package/dist/oauthSecurity/oauthState.core.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Anti-CSRF `state` generation and timing-safe verification.
+ *
+ * @module oauthSecurity/oauthState
+ *
+ * Without `state`, an attacker can complete their own authorization at your
+ * provider and then feed the resulting `code` to a victim's callback, binding
+ * the victim's session to the attacker's identity. `state` is mandatory here,
+ * and the comparison is timing-safe so the value cannot be recovered a byte
+ * at a time.
+ */
+/**
+ * Generate a random `state` value (256 bits, base64url).
+ *
+ * @returns A 43-character URL-safe string.
+ */
+export declare function generateState(): string;
+/**
+ * Compare the issued `state` with the one returned on the callback, without
+ * leaking the answer through timing.
+ *
+ * Lengths are compared first (`timingSafeEqual` throws on unequal buffers);
+ * a length difference is not secret, the contents are. Empty or non-string
+ * inputs are always `false` — an absent `state` never passes.
+ *
+ * @param expected - The state you issued and stored.
+ * @param received - The `state` query parameter from the callback.
+ * @returns `true` only if both are non-empty strings with identical bytes.
+ */
+export declare function verifyState(expected: string, received: string): boolean;
+//# sourceMappingURL=oauthState.core.d.ts.map

package/dist/oauthSecurity/oauthState.core.js

@@ -0,0 +1,44 @@
+/**
+ * Anti-CSRF `state` generation and timing-safe verification.
+ *
+ * @module oauthSecurity/oauthState
+ *
+ * Without `state`, an attacker can complete their own authorization at your
+ * provider and then feed the resulting `code` to a victim's callback, binding
+ * the victim's session to the attacker's identity. `state` is mandatory here,
+ * and the comparison is timing-safe so the value cannot be recovered a byte
+ * at a time.
+ */
+import { randomBytes, timingSafeEqual } from "node:crypto";
+/**
+ * Generate a random `state` value (256 bits, base64url).
+ *
+ * @returns A 43-character URL-safe string.
+ */
+export function generateState() {
+    return randomBytes(32).toString("base64url");
+}
+/**
+ * Compare the issued `state` with the one returned on the callback, without
+ * leaking the answer through timing.
+ *
+ * Lengths are compared first (`timingSafeEqual` throws on unequal buffers);
+ * a length difference is not secret, the contents are. Empty or non-string
+ * inputs are always `false` — an absent `state` never passes.
+ *
+ * @param expected - The state you issued and stored.
+ * @param received - The `state` query parameter from the callback.
+ * @returns `true` only if both are non-empty strings with identical bytes.
+ */
+export function verifyState(expected, received) {
+    if (typeof expected !== "string" || typeof received !== "string")
+        return false;
+    if (expected.length === 0 || received.length === 0)
+        return false;
+    const a = Buffer.from(expected, "utf8");
+    const b = Buffer.from(received, "utf8");
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+//# sourceMappingURL=oauthState.core.js.map

package/dist/oauthSecurity/oauthUrl.guard.d.ts

@@ -0,0 +1,47 @@
+/**
+ * URL validation and SSRF guards.
+ *
+ * @module oauthSecurity/oauthUrl
+ *
+ * An `OAuthConfig` is frequently operator- or tenant-supplied, and the token
+ * and user-info URLs are fetched *by your server*. That makes them a
+ * server-side request forgery sink: an attacker who can set `tokenUrl` to
+ * `http://169.254.169.254/latest/meta-data/iam/...` would have your process
+ * fetch cloud credentials and hand the body back. Every URL is therefore
+ * checked before any request is made.
+ *
+ * Two policies:
+ *
+ * - **Browser-facing URLs** (`authorizeUrl`, redirect URIs) must be `https`,
+ *   or `http` when the host is exactly `localhost` / `127.0.0.1` / `[::1]`
+ *   (local development), and must not embed credentials.
+ * - **Server-fetched URLs** (`tokenUrl`, `userInfoUrl`) must additionally be
+ *   `https` unconditionally and resolve — by literal inspection — to a public
+ *   host: no loopback, private, carrier-grade-NAT, link-local, unique-local,
+ *   multicast, reserved or cloud-metadata address, and no `localhost`,
+ *   `*.local`, `*.internal` or `metadata.google.internal` name.
+ *
+ * **Known limit.** These checks are on the literal host in the URL. They do
+ * not resolve DNS, so a hostname that resolves to a private address (DNS
+ * rebinding) is not caught here. Pair this with network egress controls if
+ * you accept endpoint URLs from untrusted operators.
+ */
+/**
+ * Whether a host literal is one this package refuses to fetch from.
+ *
+ * Exported for the SSRF tests; not part of the supported surface.
+ */
+export declare function isBlockedFetchHost(hostname: string): boolean;
+/** What a URL is used for, which decides how strict the check is. */
+export type UrlUse = "browser" | "fetch";
+/**
+ * Validate a URL and return its parsed, normalised form.
+ *
+ * @param raw - The URL string from the configuration.
+ * @param label - Field name, used only in the (secret-free) error message.
+ * @param use - `browser` for redirect targets, `fetch` for endpoints your
+ *   server calls (adds the SSRF host policy and forbids `http` entirely).
+ * @throws {OAuthEndpointNotAllowedError} If the URL fails any check.
+ */
+export declare function assertSafeUrl(raw: string, label: string, use: UrlUse): URL;
+//# sourceMappingURL=oauthUrl.guard.d.ts.map

package/dist/oauthSecurity/oauthUrl.guard.js

@@ -0,0 +1,190 @@
+/**
+ * URL validation and SSRF guards.
+ *
+ * @module oauthSecurity/oauthUrl
+ *
+ * An `OAuthConfig` is frequently operator- or tenant-supplied, and the token
+ * and user-info URLs are fetched *by your server*. That makes them a
+ * server-side request forgery sink: an attacker who can set `tokenUrl` to
+ * `http://169.254.169.254/latest/meta-data/iam/...` would have your process
+ * fetch cloud credentials and hand the body back. Every URL is therefore
+ * checked before any request is made.
+ *
+ * Two policies:
+ *
+ * - **Browser-facing URLs** (`authorizeUrl`, redirect URIs) must be `https`,
+ *   or `http` when the host is exactly `localhost` / `127.0.0.1` / `[::1]`
+ *   (local development), and must not embed credentials.
+ * - **Server-fetched URLs** (`tokenUrl`, `userInfoUrl`) must additionally be
+ *   `https` unconditionally and resolve — by literal inspection — to a public
+ *   host: no loopback, private, carrier-grade-NAT, link-local, unique-local,
+ *   multicast, reserved or cloud-metadata address, and no `localhost`,
+ *   `*.local`, `*.internal` or `metadata.google.internal` name.
+ *
+ * **Known limit.** These checks are on the literal host in the URL. They do
+ * not resolve DNS, so a hostname that resolves to a private address (DNS
+ * rebinding) is not caught here. Pair this with network egress controls if
+ * you accept endpoint URLs from untrusted operators.
+ */
+import { OAuthEndpointNotAllowedError } from "../oauthErrors/index.js";
+/** Hostnames that are always refused for a server-fetched endpoint. */
+const BLOCKED_HOST_NAMES = new Set([
+    "localhost",
+    "metadata",
+    "metadata.google.internal",
+    "instance-data",
+]);
+/** Suffixes that are always refused for a server-fetched endpoint. */
+const BLOCKED_HOST_SUFFIXES = [
+    ".localhost",
+    ".local",
+    ".internal",
+    ".home.arpa",
+];
+/** Hosts for which plain `http` is tolerated on browser-facing URLs. */
+const LOCAL_DEV_HOSTS = new Set([
+    "localhost",
+    "127.0.0.1",
+    "[::1]",
+    "::1",
+]);
+/** Parse a dotted-quad IPv4 literal, or `undefined` if it is not one. */
+function parseIpv4(host) {
+    const parts = host.split(".");
+    if (parts.length !== 4)
+        return undefined;
+    const octets = [];
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part))
+            return undefined;
+        const value = Number(part);
+        if (!Number.isInteger(value) || value < 0 || value > 255)
+            return undefined;
+        octets.push(value);
+    }
+    return octets;
+}
+/** Whether an IPv4 literal is outside the publicly routable space. */
+function isNonPublicIpv4(octets) {
+    const a = octets[0] ?? 0;
+    const b = octets[1] ?? 0;
+    if (a === 0)
+        return true; // 0.0.0.0/8 "this network"
+    if (a === 10)
+        return true; // private
+    if (a === 127)
+        return true; // loopback
+    if (a === 169 && b === 254)
+        return true; // link-local, incl. 169.254.169.254
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // private
+    if (a === 192 && b === 168)
+        return true; // private
+    if (a === 192 && b === 0)
+        return true; // 192.0.0.0/24 IETF protocol assignments
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64.0.0/10 CGNAT
+    if (a === 198 && (b === 18 || b === 19))
+        return true; // benchmarking
+    if (a >= 224)
+        return true; // multicast + reserved + broadcast
+    return false;
+}
+/** Whether an IPv6 literal (already stripped of brackets) is non-public. */
+function isNonPublicIpv6(raw) {
+    const host = raw.toLowerCase();
+    if (host === "::" || host === "::1")
+        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;
+}
+/**
+ * Whether a host literal is one this package refuses to fetch from.
+ *
+ * Exported for the SSRF tests; not part of the supported surface.
+ */
+export function isBlockedFetchHost(hostname) {
+    const host = hostname.toLowerCase();
+    const bare = host.startsWith("[") && host.endsWith("]")
+        ? host.slice(1, -1)
+        : host;
+    if (BLOCKED_HOST_NAMES.has(bare))
+        return true;
+    for (const suffix of BLOCKED_HOST_SUFFIXES) {
+        if (bare.endsWith(suffix))
+            return true;
+    }
+    const octets = parseIpv4(bare);
+    if (octets !== undefined)
+        return isNonPublicIpv4(octets);
+    if (bare.includes(":"))
+        return isNonPublicIpv6(bare);
+    return false;
+}
+/**
+ * Validate a URL and return its parsed, normalised form.
+ *
+ * @param raw - The URL string from the configuration.
+ * @param label - Field name, used only in the (secret-free) error message.
+ * @param use - `browser` for redirect targets, `fetch` for endpoints your
+ *   server calls (adds the SSRF host policy and forbids `http` entirely).
+ * @throws {OAuthEndpointNotAllowedError} If the URL fails any check.
+ */
+export function assertSafeUrl(raw, label, use) {
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        throw new OAuthEndpointNotAllowedError(`${label} must be a non-empty URL.`);
+    }
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new OAuthEndpointNotAllowedError(`${label} is not a valid absolute URL.`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new OAuthEndpointNotAllowedError(`${label} must not embed credentials.`);
+    }
+    const isLocalDev = LOCAL_DEV_HOSTS.has(url.hostname.toLowerCase());
+    if (url.protocol === "http:") {
+        if (use === "fetch" || !isLocalDev) {
+            throw new OAuthEndpointNotAllowedError(use === "fetch"
+                ? `${label} must use https.`
+                : `${label} must use https (http is allowed only for localhost).`);
+        }
+    }
+    else if (url.protocol !== "https:") {
+        throw new OAuthEndpointNotAllowedError(`${label} must use https.`);
+    }
+    if (use === "fetch" && isBlockedFetchHost(url.hostname)) {
+        throw new OAuthEndpointNotAllowedError(`${label} resolves to a non-public host, which is not allowed.`);
+    }
+    return url;
+}
+//# sourceMappingURL=oauthUrl.guard.js.map

package/dist/oauthTypes/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Public types for `@zudojs/auth-oauth`.
+ *
+ * @module oauthTypes
+ */
+export { type OAuthProvider, type ClientAuthMethod, type FetchLike, type OAuthConfig, type AuthorizationUrlOptions, type AuthorizationUrlResult, type CodeExchangeOptions, type OAuthTokenSet, type OAuthUserInfo, } from "./oauth.type.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/oauthTypes/index.js

@@ -0,0 +1,7 @@
+/**
+ * Public types for `@zudojs/auth-oauth`.
+ *
+ * @module oauthTypes
+ */
+export {} from "./oauth.type.js";
+//# sourceMappingURL=index.js.map

package/dist/oauthTypes/oauth.type.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Public types for the OAuth2 authorization-code client.
+ *
+ * @module oauthTypes/oauth
+ */
+/**
+ * Supported OAuth2 provider identifiers.
+ *
+ * `custom` requires every endpoint URL to be supplied on the config; the
+ * named providers supply their own defaults (see the provider presets).
+ */
+export type OAuthProvider = "google" | "github" | "microsoft" | "apple" | "discord" | "custom";
+/**
+ * How the client authenticates itself at the token endpoint.
+ *
+ * - `basic` — HTTP Basic auth (`client_id:client_secret`), RFC 6749 §2.3.1.
+ * - `body` — `client_id` / `client_secret` form fields.
+ *
+ * Each preset picks whatever its provider actually expects; override only if
+ * you know your deployment differs.
+ */
+export type ClientAuthMethod = "basic" | "body";
+/**
+ * The `fetch` shape this package depends on.
+ *
+ * Defaults to the global `fetch`. Inject your own to add proxying, retries or
+ * to test without a network.
+ */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/**
+ * OAuth2 provider configuration.
+ *
+ * Endpoint URLs are optional for the named providers (the preset fills them
+ * in) and mandatory for `custom`. Every URL — supplied or preset — is
+ * validated before any network call; see {@link ../oauthSecurity/oauthUrl.guard}.
+ */
+export interface OAuthConfig {
+    /** Provider identifier. */
+    readonly provider: OAuthProvider;
+    /** OAuth2 client ID. */
+    readonly clientId: string;
+    /**
+     * OAuth2 client secret.
+     *
+     * For Apple this is the short-lived ES256 client-secret JWT you generate
+     * from your private key; this package does not mint it for you.
+     *
+     * Never logged, never placed in an error message or stack.
+     */
+    readonly clientSecret: string;
+    /** Authorization endpoint. Overrides the preset. */
+    readonly authorizeUrl?: string;
+    /** Token endpoint. Overrides the preset. */
+    readonly tokenUrl?: string;
+    /** User-info endpoint. Overrides the preset. */
+    readonly userInfoUrl?: string;
+    /**
+     * Exact redirect URIs this client is allowed to use.
+     *
+     * Every `redirectUri` passed to {@link createAuthorizationUrl} or
+     * {@link exchangeCodeForToken} must appear here verbatim (scheme and host
+     * compared case-insensitively, the rest byte-for-byte). At least one entry
+     * is required — an arbitrary redirect target is never reflected.
+     */
+    readonly allowedRedirectUris: readonly string[];
+    /** Requested scopes. Defaults to the preset's scopes. */
+    readonly scopes?: readonly string[];
+    /** Token-endpoint client authentication. Defaults to the preset's choice. */
+    readonly clientAuthMethod?: ClientAuthMethod;
+    /** Per-request timeout in milliseconds. Default 10000, max 120000. */
+    readonly timeoutMs?: number;
+    /**
+     * Hard cap on bytes read from a provider response body.
+     * Default 262144 (256 KiB), min 1024, max 5242880 (5 MiB).
+     */
+    readonly maxResponseBytes?: number;
+    /** `fetch` implementation. Defaults to the global `fetch`. */
+    readonly fetch?: FetchLike;
+}
+/** Options for {@link createAuthorizationUrl}. */
+export interface AuthorizationUrlOptions {
+    /**
+     * Anti-CSRF state. **Mandatory.** Persist it against the user's session and
+     * check it on the callback with {@link verifyState}.
+     */
+    readonly state: string;
+    /** Redirect URI. Must be present in `config.allowedRedirectUris`. */
+    readonly redirectUri: string;
+    /** Scopes for this request. Defaults to `config.scopes` / the preset. */
+    readonly scopes?: readonly string[];
+    /**
+     * Pre-generated PKCE code verifier (43-128 chars, unreserved alphabet).
+     * Omit to have one generated — which is what you should normally do.
+     */
+    readonly codeVerifier?: string;
+    /** OIDC `nonce`, echoed into the ID token by providers that support it. */
+    readonly nonce?: string;
+    /** Extra authorization parameters (e.g. `prompt`, `access_type`). */
+    readonly additionalParams?: Readonly<Record<string, string>>;
+}
+/** Result of {@link createAuthorizationUrl}. */
+export interface AuthorizationUrlResult {
+    /** The URL to send the user agent to. */
+    readonly url: string;
+    /** The state you supplied — persist it. */
+    readonly state: string;
+    /**
+     * The PKCE code verifier — persist it server-side (session, signed cookie)
+     * and pass it to {@link exchangeCodeForToken}. It is a secret.
+     */
+    readonly codeVerifier: string;
+    /** The `S256` challenge that was sent. Informational. */
+    readonly codeChallenge: string;
+}
+/** Options for {@link exchangeCodeForToken}. */
+export interface CodeExchangeOptions {
+    /** The `code` query parameter from the callback. */
+    readonly code: string;
+    /** The verifier returned by {@link createAuthorizationUrl}. */
+    readonly codeVerifier: string;
+    /** The same redirect URI used for the authorization request. */
+    readonly redirectUri: string;
+}
+/** A validated OAuth2 token response. */
+export interface OAuthTokenSet {
+    /** Access token. Always a non-empty string. */
+    readonly accessToken: string;
+    /** Token type as returned, defaulting to `Bearer`. */
+    readonly tokenType: string;
+    /** Lifetime in seconds, when the provider reported a numeric one. */
+    readonly expiresIn?: number;
+    /** Refresh token, when the provider issued one. */
+    readonly refreshToken?: string;
+    /** Granted scopes, split on whitespace. */
+    readonly scope?: readonly string[];
+    /** OIDC ID token, when present. Unverified — this package does not parse it. */
+    readonly idToken?: string;
+    /**
+     * The parsed response with prototype-polluting keys stripped.
+     * Contains the tokens themselves — treat as secret.
+     */
+    readonly raw: Readonly<Record<string, unknown>>;
+}
+/** Normalised user profile from a provider's user-info endpoint. */
+export interface OAuthUserInfo {
+    /** The provider's stable user identifier. */
+    readonly providerId: string;
+    /**
+     * Email address, when the provider returned one.
+     *
+     * Optional on purpose: GitHub omits it from `/user` when the address is
+     * private, and Discord omits it without the `email` scope. This package
+     * never invents one.
+     */
+    readonly email?: string;
+    /** Whether the provider stated the email is verified. */
+    readonly emailVerified?: boolean;
+    /** Display name. */
+    readonly name?: string;
+    /** Avatar URL. */
+    readonly avatarUrl?: string;
+    /** Raw provider payload, prototype-polluting keys stripped. */
+    readonly raw?: Readonly<Record<string, unknown>>;
+}
+//# sourceMappingURL=oauth.type.d.ts.map

package/dist/oauthTypes/oauth.type.js

@@ -0,0 +1,7 @@
+/**
+ * Public types for the OAuth2 authorization-code client.
+ *
+ * @module oauthTypes/oauth
+ */
+export {};
+//# sourceMappingURL=oauth.type.js.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@zudojs/auth-oauth",
+  "version": "1.1.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",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2",
+    "vitest": "^4.1.11",
+    "@types/node": "^26.4.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "zudojs",
+    "oauth2",
+    "oauth",
+    "pkce",
+    "authorization-code",
+    "social-login"
+  ],
+  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/auth-oauth"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}