@udibo/oauth2 0.1.0

package/esm/utils/pkce.js

@@ -0,0 +1,179 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities for OAuth2.
+ *
+ * Implements RFC 7636 for preventing authorization code interception attacks.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7636
+ * @module
+ */
+import { encodeBase64Url } from "../deps/jsr.io/@std/encoding/1.0.11/base64url.js";
+/**
+ * Minimum length for code verifier per RFC 7636 Section 4.1.
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+ */
+export const CODE_VERIFIER_MIN_LENGTH = 43;
+/**
+ * Maximum length for code verifier per RFC 7636 Section 4.1.
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+ */
+export const CODE_VERIFIER_MAX_LENGTH = 128;
+/**
+ * Pattern for valid code verifier characters per RFC 7636 Section 4.1.
+ * Allowed characters: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+ */
+export const CODE_VERIFIER_PATTERN = /^[A-Za-z0-9\-._~]+$/;
+/**
+ * The default allowed PKCE code challenge methods.
+ *
+ * Per RFC 7636 and OAuth 2.1, clients SHOULD use the S256 method.
+ * The "plain" method is NOT included by default as it provides
+ * weaker security guarantees.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.2
+ * @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-2.1.1
+ */
+export const challengeMethods = {
+    S256: async (verifier) => {
+        const data = new TextEncoder().encode(verifier);
+        const buffer = await crypto.subtle.digest("SHA-256", data);
+        return encodeBase64Url(new Uint8Array(buffer));
+    },
+};
+/**
+ * Validates a code verifier per RFC 7636 Section 4.1.
+ *
+ * The code verifier must:
+ * - Be between 43 and 128 characters long
+ * - Contain only unreserved characters: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+ *
+ * @param verifier The code verifier to validate
+ * @returns true if the verifier is valid
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+ */
+export function validateCodeVerifier(verifier) {
+    if (verifier.length < CODE_VERIFIER_MIN_LENGTH ||
+        verifier.length > CODE_VERIFIER_MAX_LENGTH) {
+        return false;
+    }
+    return CODE_VERIFIER_PATTERN.test(verifier);
+}
+/**
+ * Generates a random code verifier with a minimum of 256 bits of entropy.
+ *
+ * This is done by generating a random 32-octet sequence then base64url encoding it
+ * to produce a 43 character URL-safe string.
+ *
+ * @returns A cryptographically random code verifier
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-7.1
+ */
+export function generateCodeVerifier() {
+    const sequence = new Uint8Array(32);
+    crypto.getRandomValues(sequence);
+    return encodeBase64Url(sequence);
+}
+/**
+ * Generates a code challenge from a code verifier using the S256 method.
+ *
+ * The S256 challenge is: BASE64URL(SHA256(ASCII(code_verifier)))
+ *
+ * @param verifier The code verifier to transform
+ * @returns The code challenge
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.2
+ */
+export async function generateCodeChallenge(verifier) {
+    return await challengeMethods.S256(verifier);
+}
+/**
+ * Validates a `code_challenge` per RFC 7636 Section 4.2, for the challenge
+ * methods whose output shape that section fixes.
+ *
+ * `S256` and `plain` are the only methods the PKCE registry defines, and both
+ * produce a challenge drawn from the same 43-128 unreserved characters as a
+ * code verifier, so an authorization endpoint can reject a malformed challenge
+ * before it is ever stored. Any other `method` — one a server registered in its
+ * own {@link ChallengeMethods} map — may legitimately produce any shape, so
+ * this returns `true` for it rather than imposing a format its author never
+ * agreed to. Check the name is allowed with {@linkcode getChallengeMethod}
+ * first; this answers only for the format.
+ *
+ * @param challenge The client-supplied `code_challenge`
+ * @param method The client-supplied `code_challenge_method`; defaults to `S256`
+ * @returns true when the challenge is acceptable for that method
+ * @example
+ * ```ts
+ * validateCodeChallenge("a".repeat(43));                 // → true
+ * validateCodeChallenge("short");                        // → false
+ * validateCodeChallenge("short", "custom-method");       // → true
+ * ```
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.2
+ */
+export function validateCodeChallenge(challenge, method) {
+    const name = method ?? "S256";
+    if (name !== "S256" && name !== "plain")
+        return true;
+    return validateCodeVerifier(challenge);
+}
+/**
+ * Resolves a client-supplied `code_challenge_method` name against the methods
+ * a server allows.
+ *
+ * Reach for this instead of indexing a {@link ChallengeMethods} map directly.
+ * The name comes off the wire, and a map written as a plain object literal
+ * also inherits `toString`, `valueOf`, `constructor` and friends from
+ * `Object.prototype` — a bare lookup hands those back as if the server had
+ * allowed them, which downgrades PKCE to a value any verifier satisfies. Only
+ * own, callable properties of `methods` resolve here; every other name is
+ * `undefined`, including names inherited from a prototype.
+ *
+ * @param methods The challenge methods the server allows
+ * @param method The client-supplied method name; defaults to `S256`
+ * @returns The transform for that method, or `undefined` when it is not allowed
+ * @example
+ * ```ts
+ * getChallengeMethod(challengeMethods, "S256");       // → the S256 transform
+ * getChallengeMethod(challengeMethods);               // → the S256 transform
+ * getChallengeMethod(challengeMethods, "toString");   // → undefined
+ * getChallengeMethod(challengeMethods, "__proto__");  // → undefined
+ * ```
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.3
+ */
+export function getChallengeMethod(methods, method) {
+    const name = method ?? "S256";
+    if (!Object.hasOwn(methods, name))
+        return undefined;
+    const challengeMethod = methods[name];
+    return typeof challengeMethod === "function" ? challengeMethod : undefined;
+}
+/**
+ * Verifies that a code verifier matches a code challenge.
+ *
+ * Fails closed against the default {@link challengeMethods} map only: a
+ * `method` that map does not hold — `"plain"`, a name inherited from
+ * `Object.prototype` such as `"toString"`, or one registered on a grant via
+ * its own `challengeMethods` — resolves `false` rather than throwing, so it is
+ * indistinguishable from a mismatched verifier.
+ *
+ * @param verifier The code verifier provided by the client
+ * @param challenge The code challenge stored from the authorization request
+ * @param method The challenge method used (defaults to S256)
+ * @returns true if the verifier matches the challenge
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.6
+ */
+export async function verifyCodeChallenge(verifier, challenge, method = "S256") {
+    const challengeMethod = getChallengeMethod(challengeMethods, method);
+    if (!challengeMethod)
+        return false;
+    const expected = await challengeMethod(verifier);
+    return expected === challenge;
+}
+/**
+ * Generates a random state parameter for CSRF protection.
+ *
+ * @returns A random UUID to use as the state parameter
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-10.12
+ */
+export function generateState() {
+    return crypto.randomUUID();
+}

package/esm/utils/text.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Bounding and flattening for text a remote server chose.
+ *
+ * Lives in `utils/` rather than beside either caller because both ladders that
+ * turn a server's bytes into an error message — the client's `_http.ts` and
+ * the connectors' `_token-exchange.ts` — must sanitize identically, and the
+ * client cannot reach up into `identity/external/`.
+ *
+ * @module
+ */
+/** Characters of remote-supplied text kept in an error message. */
+export declare const PROVIDER_TEXT_MAX_LENGTH = 200;
+/**
+ * Bounds and flattens a remote-supplied string for inclusion in an error
+ * message. Control characters become spaces so a hostile `error_description`
+ * cannot forge a log line or inject an ANSI escape in a consumer's console,
+ * the result is capped at {@link PROVIDER_TEXT_MAX_LENGTH}, and a surrogate
+ * pair split by that cap is repaired rather than left lone. Use this on
+ * every byte a remote server chose that reaches a message.
+ *
+ * @param value The remote-supplied text.
+ * @returns The flattened, capped, well-formed text.
+ */
+export declare function sanitizeProviderText(value: string): string;

package/esm/utils/text.js

@@ -0,0 +1,28 @@
+/**
+ * Bounding and flattening for text a remote server chose.
+ *
+ * Lives in `utils/` rather than beside either caller because both ladders that
+ * turn a server's bytes into an error message — the client's `_http.ts` and
+ * the connectors' `_token-exchange.ts` — must sanitize identically, and the
+ * client cannot reach up into `identity/external/`.
+ *
+ * @module
+ */
+/** Characters of remote-supplied text kept in an error message. */
+export const PROVIDER_TEXT_MAX_LENGTH = 200;
+/**
+ * Bounds and flattens a remote-supplied string for inclusion in an error
+ * message. Control characters become spaces so a hostile `error_description`
+ * cannot forge a log line or inject an ANSI escape in a consumer's console,
+ * the result is capped at {@link PROVIDER_TEXT_MAX_LENGTH}, and a surrogate
+ * pair split by that cap is repaired rather than left lone. Use this on
+ * every byte a remote server chose that reaches a message.
+ *
+ * @param value The remote-supplied text.
+ * @returns The flattened, capped, well-formed text.
+ */
+export function sanitizeProviderText(value) {
+    // deno-lint-ignore no-control-regex
+    const flattened = value.replace(/[\u0000-\u001F\u007F-\u009F]+/g, " ");
+    return flattened.trim().slice(0, PROVIDER_TEXT_MAX_LENGTH).toWellFormed();
+}

package/esm/utils/url.d.ts

@@ -0,0 +1,66 @@
+/**
+ * URL safety helpers.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+/**
+ * Open-redirect guard for a `return_to` / redirect target.
+ *
+ * Returns `value` only when it is a safe in-app destination: a path beginning
+ * with a single `/` that still resolves to the current origin. This rejects
+ * absolute URLs, protocol-relative `//evil.com`, backslash `/\evil.com` tricks
+ * that some browsers resolve as a host, and any value containing a C0 control
+ * character or `DEL` — browsers strip TAB/CR/LF before parsing a URL, so
+ * `/<TAB>/evil.com` would otherwise navigate to `evil.com`. Anything else
+ * collapses to `fallback` (default `/`).
+ *
+ * Percent-encoded control characters (`/%09/x`) are safe and pass through: a
+ * browser does not decode them before parsing, so they stay on the origin.
+ *
+ * Use this anywhere a user-influenced value — a `return_to` / `redirect` query
+ * param or form field — is fed into a redirect `Location`, so a crafted
+ * absolute target can't turn the (often post-authentication) redirect into an
+ * open redirect.
+ *
+ * @example
+ * ```ts
+ * safeReturnTo("/dashboard");        // → "/dashboard"
+ * safeReturnTo("https://evil.com");  // → "/"
+ * safeReturnTo("//evil.com");        // → "/"
+ * safeReturnTo("/\\evil.com");       // → "/"
+ * safeReturnTo("/\t/evil.com");      // → "/"
+ * safeReturnTo(undefined, "/home");  // → "/home"
+ * ```
+ */
+export declare function safeReturnTo(value: string | null | undefined, fallback?: string): string;
+/** Options for {@link loginContinuation}. */
+export interface LoginContinuationOptions {
+    /**
+     * The authorization endpoint (absolute URL or path). When `returnTo` points at
+     * it, the flow is **resumed** (the in-flight authorize request already has a
+     * PKCE `state`). Omit it and every `returnTo` starts a fresh login.
+     */
+    authorizeEndpoint?: string;
+    /** The login path to start a fresh login. Defaults to `"/auth/login"`. */
+    loginPath?: string;
+    /** Fallback when `returnTo` is missing/unsafe. Defaults to `"/"`. */
+    defaultReturnTo?: string;
+}
+/**
+ * The URL that (re)starts sign-in toward `returnTo`, for an app that owns its
+ * login surface and needs to hand back to the OAuth2/BFF flow after it
+ * authenticates a user.
+ *
+ * - When `returnTo` is an **in-flight authorize URL** (its path equals
+ *   `authorizeEndpoint`'s path — the user was bounced mid-authorize with `state`
+ *   already minted), it is returned unchanged so the flow **resumes** without a
+ *   redundant login hop.
+ * - Otherwise it returns `${loginPath}?return_to=<returnTo>` to **start** a fresh
+ *   login.
+ *
+ * Pure and client-safe — the same logic behind `HonoBff.loginContinuation`
+ * (server) and `BffClient.loginContinuation` (browser). `returnTo` is
+ * open-redirect-guarded via {@link safeReturnTo}.
+ */
+export declare function loginContinuation(returnTo: string | null | undefined, options?: LoginContinuationOptions): string;

package/esm/utils/url.js

@@ -0,0 +1,90 @@
+/**
+ * URL safety helpers.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+const RESOLUTION_ORIGIN = "http://safe-return-to.invalid";
+function hasControlCharacter(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/**
+ * Open-redirect guard for a `return_to` / redirect target.
+ *
+ * Returns `value` only when it is a safe in-app destination: a path beginning
+ * with a single `/` that still resolves to the current origin. This rejects
+ * absolute URLs, protocol-relative `//evil.com`, backslash `/\evil.com` tricks
+ * that some browsers resolve as a host, and any value containing a C0 control
+ * character or `DEL` — browsers strip TAB/CR/LF before parsing a URL, so
+ * `/<TAB>/evil.com` would otherwise navigate to `evil.com`. Anything else
+ * collapses to `fallback` (default `/`).
+ *
+ * Percent-encoded control characters (`/%09/x`) are safe and pass through: a
+ * browser does not decode them before parsing, so they stay on the origin.
+ *
+ * Use this anywhere a user-influenced value — a `return_to` / `redirect` query
+ * param or form field — is fed into a redirect `Location`, so a crafted
+ * absolute target can't turn the (often post-authentication) redirect into an
+ * open redirect.
+ *
+ * @example
+ * ```ts
+ * safeReturnTo("/dashboard");        // → "/dashboard"
+ * safeReturnTo("https://evil.com");  // → "/"
+ * safeReturnTo("//evil.com");        // → "/"
+ * safeReturnTo("/\\evil.com");       // → "/"
+ * safeReturnTo("/\t/evil.com");      // → "/"
+ * safeReturnTo(undefined, "/home");  // → "/home"
+ * ```
+ */
+export function safeReturnTo(value, fallback = "/") {
+    if (!value || !value.startsWith("/"))
+        return fallback;
+    if (hasControlCharacter(value))
+        return fallback;
+    let resolved;
+    try {
+        resolved = new URL(value, RESOLUTION_ORIGIN);
+    }
+    catch {
+        return fallback;
+    }
+    if (resolved.origin !== RESOLUTION_ORIGIN)
+        return fallback;
+    if (resolved.pathname.startsWith("//"))
+        return fallback;
+    return value;
+}
+/**
+ * The URL that (re)starts sign-in toward `returnTo`, for an app that owns its
+ * login surface and needs to hand back to the OAuth2/BFF flow after it
+ * authenticates a user.
+ *
+ * - When `returnTo` is an **in-flight authorize URL** (its path equals
+ *   `authorizeEndpoint`'s path — the user was bounced mid-authorize with `state`
+ *   already minted), it is returned unchanged so the flow **resumes** without a
+ *   redundant login hop.
+ * - Otherwise it returns `${loginPath}?return_to=<returnTo>` to **start** a fresh
+ *   login.
+ *
+ * Pure and client-safe — the same logic behind `HonoBff.loginContinuation`
+ * (server) and `BffClient.loginContinuation` (browser). `returnTo` is
+ * open-redirect-guarded via {@link safeReturnTo}.
+ */
+export function loginContinuation(returnTo, options = {}) {
+    const safe = safeReturnTo(returnTo, options.defaultReturnTo ?? "/");
+    if (options.authorizeEndpoint) {
+        // Compare path only so the in-flight authorize query (client_id, state, …)
+        // is preserved; the base lets absolute and relative inputs both resolve.
+        const base = "http://login.continuation.local";
+        const authorizePath = new URL(options.authorizeEndpoint, base).pathname;
+        if (new URL(safe, base).pathname === authorizePath)
+            return safe;
+    }
+    return `${options.loginPath ?? "/auth/login"}?return_to=${encodeURIComponent(safe)}`;
+}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@udibo/oauth2",
+  "version": "0.1.0",
+  "description": "A flexible OAuth2 toolkit: framework-agnostic authorization & resource servers, a typed client, Hono adapters (including a backend-for-frontend), and React bindings.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/udibo/oauth2.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/udibo/oauth2/issues"
+  },
+  "module": "./esm/server/mod.js",
+  "exports": {
+    "./server": {
+      "import": "./esm/server/mod.js"
+    },
+    "./server/authorization": {
+      "import": "./esm/server/authorization-server.js"
+    },
+    "./server/resource": {
+      "import": "./esm/server/resource-server.js"
+    },
+    "./server/public-suffix": {
+      "import": "./esm/server/public-suffix/mod.js"
+    },
+    "./client": {
+      "import": "./esm/client/mod.js"
+    },
+    "./identity": {
+      "import": "./esm/identity/mod.js"
+    },
+    "./identity/external": {
+      "import": "./esm/identity/external/mod.js"
+    },
+    "./identity/mfa": {
+      "import": "./esm/identity/mfa/mod.js"
+    },
+    "./identity/migration": {
+      "import": "./esm/identity/migration.js"
+    },
+    "./hono/resource-server": {
+      "import": "./esm/adapters/hono/resource-server.js"
+    },
+    "./hono/authorization-server": {
+      "import": "./esm/adapters/hono/authorization-server.js"
+    },
+    "./hono/bff": {
+      "import": "./esm/adapters/hono/bff/mod.js"
+    },
+    "./hono/bff/testing": {
+      "import": "./esm/adapters/hono/bff/testing.js"
+    },
+    "./hono/identity": {
+      "import": "./esm/adapters/hono/identity.js"
+    },
+    "./hono/log": {
+      "import": "./esm/adapters/hono/log.js"
+    },
+    "./react": {
+      "import": "./esm/react/mod.js"
+    },
+    "./react/components": {
+      "import": "./esm/react/components/mod.js"
+    },
+    "./react/testing": {
+      "import": "./esm/react/testing.js"
+    },
+    "./testing": {
+      "import": "./esm/testing/mod.js"
+    },
+    "./testing/contract": {
+      "import": "./esm/testing/contract/mod.js"
+    },
+    "./crypto": {
+      "import": "./esm/utils/crypto.js"
+    },
+    "./url": {
+      "import": "./esm/utils/url.js"
+    }
+  },
+  "scripts": {},
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@types/react": "^19.2.17",
+    "hono": "^4.7.0",
+    "react": "^19.0.0"
+  },
+  "_generatedBy": "dnt@0.43.2"
+}