@udibo/oauth2 0.8.0 → 0.9.1

package/README.md

@@ -5,9 +5,9 @@ Udibo's identity service, or host an authorization server for your own app. The
 package includes clients, authorization and resource servers, Hono middleware,
 React bindings, and optional login flows over your own database.
 
-**Udibo's managed identity service is in private beta.**
-[Join the waitlist](https://udibo.com). The self-hosted examples run locally
-without a hosted account.
+**Udibo's managed identity service is in private beta.** See
+[udibo.com](https://www.udibo.com/) for access. The self-hosted examples run
+locally without a hosted account.
 
 ## Choose your path
 
@@ -76,6 +76,11 @@ a browser app with a backend, start with the BFF guide.
 authorization server. The framework-independent core accepts standard `Request`
 and `Response` objects; Hono adapters add routing and middleware.
 
+For app-owned login, `CaptchaProvider` and `verifyCaptcha` let your route check
+a client-issued bot-challenge token before calling `IdentityService`. The
+package does not include a challenge provider; see the
+[CAPTCHA route example](docs/guides/add-login.md#captcha-at-the-route-boundary).
+
 ## Examples
 
 From a checkout of this repository:

package/esm/adapters/hono/bff/bff.js

@@ -51,6 +51,7 @@ import { Hono } from "hono";
 import { deleteCookie, getCookie, setCookie } from "hono/cookie";
 import { assertMaxBodyBytes, DEFAULT_MAX_BODY_BYTES, readBoundedBody, } from "../../../utils/_body.js";
 import { InvalidRequestError, InvalidTokenError, isOAuth2Error, TemporarilyUnavailableError, } from "../../../errors.js";
+import { defaultFetch } from "../../../utils/_default-fetch.js";
 import { timingSafeMatchIndex } from "../../../utils/_timing-safe.js";
 import { sha256Hash } from "../../../server/utils/hash.js";
 import { OAUTH2_CONTEXT_KEY } from "../_common.js";
@@ -1197,8 +1198,7 @@ export class HonoBff {
     proxy(target, options = {}) {
         const base = new URL(target);
         const allowedHeaders = resolveForwardHeaders(options.forwardHeaders, this.#csrf?.headerName);
-        const fetchImpl = options.fetch ??
-            ((input, init) => fetch(input, init));
+        const fetchImpl = options.fetch ?? defaultFetch;
         const retryOn401 = options.retryOn401 ?? true;
         const mountPrefix = (options.stripPrefix ?? "").endsWith("/")
             ? options.stripPrefix.slice(0, -1)

package/esm/client/_http.js

@@ -7,6 +7,7 @@
  * @module
  */
 import { AccessDeniedError, AuthorizationPendingError, ExpiredTokenError, InsufficientScopeError, InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, InvalidTokenError, OAuth2Error as OAuth2ErrorClass, ServerError, SlowDownError, TemporarilyUnavailableError, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, UnsupportedTokenTypeError, } from "../errors.js";
+import { packageDeadlineSignal } from "../utils/_default-fetch.js";
 import { sanitizeProviderText } from "../utils/text.js";
 /** Response bytes accepted from an endpoint before the call is refused. */
 export const MAX_RESPONSE_BYTES = 64 * 1024;
@@ -61,7 +62,7 @@ export async function sendGuarded(fetchImpl, url, init, what, options = {}) {
         res = await fetchImpl(url, {
             ...init,
             redirect: redirect === "refuse" ? "manual" : "follow",
-            signal: init.signal ? AbortSignal.any([init.signal, deadline]) : deadline,
+            signal: packageDeadlineSignal(deadline, init.signal),
         });
     }
     catch (error) {

package/esm/client/base.d.ts

@@ -38,6 +38,12 @@ export interface BaseOptions {
      *   an in-memory server. Preferred over stubbing `globalThis.fetch`,
      *   which would also intercept unrelated outbound requests the app may
      *   make.
+     *
+     * On Deno the default stops reusing a pooled HTTP/2 connection to a host
+     * once one of the client's own calls to it (discovery, token, revocation,
+     * userinfo, the session probe) misses its deadline; what the client's
+     * `fetch` method returns is the global `fetch`'s response, unaltered. An
+     * injected `fetch` manages its own connections.
      */
     fetch?: typeof fetch;
 }

package/esm/client/base.js

@@ -11,6 +11,7 @@
  *
  * @module
  */
+import { defaultFetch } from "../utils/_default-fetch.js";
 import { EventBus, } from "./events.js";
 /**
  * The headers a wrapped `fetch` should send for `(input, init)`: the ones
@@ -88,6 +89,6 @@ export class OAuth2ClientBase {
      * polyfilled global if the runtime installs one after construction.
      */
     fetchImpl(input, init) {
-        return (this.#customFetch ?? globalThis.fetch)(input, init);
+        return (this.#customFetch ?? defaultFetch)(input, init);
     }
 }

package/esm/client/check.d.ts

@@ -62,7 +62,9 @@ export interface CheckPermissionsOptions {
      * in tests. Defaults to the global `fetch`. Whichever is used, the call runs
      * under this package's deadline and response-size cap, and a redirect is
      * refused rather than followed so the bearer token never reaches the host
-     * it names.
+     * it names. On Deno the default stops reusing a pooled HTTP/2 connection to
+     * a host once a check request to it misses its deadline; an injected `fetch`
+     * manages its own connections.
      */
     fetch?: typeof fetch;
 }

package/esm/client/check.js

@@ -27,6 +27,7 @@
  * @module
  */
 import { ServerError, TemporarilyUnavailableError } from "../errors.js";
+import { defaultFetch } from "../utils/_default-fetch.js";
 import { receiveJson, sendGuarded } from "./_http.js";
 const CHECK_ENDPOINT = "check endpoint";
 /**
@@ -74,7 +75,7 @@ const CHECK_ENDPOINT = "check endpoint";
  * ```
  */
 export async function checkPermissions(options) {
-    const response = await sendGuarded(options.fetch ?? fetch, options.endpoint, {
+    const response = await sendGuarded(options.fetch ?? defaultFetch, options.endpoint, {
         method: "POST",
         headers: {
             authorization: `Bearer ${options.accessToken}`,

package/esm/identity/external/_token-exchange.js

@@ -8,6 +8,7 @@
  *
  * @module
  */
+import { packageDeadlineSignal } from "../../utils/_default-fetch.js";
 import { describeError, sanitizeProviderText } from "./_shared.js";
 import { ExternalAuthError } from "./errors.js";
 /** Response bytes accepted from a token endpoint before the exchange is refused. */
@@ -33,7 +34,7 @@ export async function runTokenExchange(input) {
             },
             body: input.body,
             redirect: "manual",
-            signal: AbortSignal.timeout(input.timeoutMs ?? TOKEN_EXCHANGE_TIMEOUT_MS),
+            signal: packageDeadlineSignal(AbortSignal.timeout(input.timeoutMs ?? TOKEN_EXCHANGE_TIMEOUT_MS)),
         });
     }
     catch (error) {

package/esm/identity/external/apple.js

@@ -17,6 +17,7 @@
  */
 import { toArrayBuffer } from "../../utils/_buffer.js";
 import { base64urlDecode } from "../../utils/crypto.js";
+import { defaultFetch } from "../../utils/_default-fetch.js";
 import { assertIdTokenClaims, describeError } from "./_shared.js";
 import { runTokenExchange } from "./_token-exchange.js";
 import { createAppleClientSecretFactory, } from "./apple-client-secret.js";
@@ -60,7 +61,7 @@ const SIGNATURE_NOT_VERIFIED = `Apple id_token signature did not verify against
  */
 export function appleProvider(options) {
     const id = "apple";
-    const fetchImpl = (input, init) => (options.fetch ?? globalThis.fetch)(input, init);
+    const fetchImpl = (input, init) => (options.fetch ?? defaultFetch)(input, init);
     const clientSecretFactory = options.clientSecret ??
         createAppleClientSecretFactory({
             providerId: id,

package/esm/identity/external/github.js

@@ -4,6 +4,7 @@
  *
  * @module
  */
+import { defaultFetch } from "../../utils/_default-fetch.js";
 import { describeError } from "./_shared.js";
 import { runTokenExchange } from "./_token-exchange.js";
 import { ExternalAuthError } from "./errors.js";
@@ -36,7 +37,7 @@ const GITHUB_EMAILS_URL = "https://api.github.com/user/emails";
  */
 export function githubProvider(options) {
     const id = "github";
-    const fetchImpl = (input, init) => (options.fetch ?? globalThis.fetch)(input, init);
+    const fetchImpl = (input, init) => (options.fetch ?? defaultFetch)(input, init);
     async function exchangeCode(input) {
         const { value } = await runTokenExchange({
             provider: id,

package/esm/identity/external/oauth2.js

@@ -7,6 +7,7 @@
  *
  * @module
  */
+import { defaultFetch } from "../../utils/_default-fetch.js";
 import { generateCodeChallenge } from "../../utils/pkce.js";
 import { describeError, readErrorBody } from "./_shared.js";
 import { runTokenExchange } from "./_token-exchange.js";
@@ -39,7 +40,7 @@ import { ExternalAuthError } from "./errors.js";
  */
 export function oauth2Provider(options) {
     const id = options.id;
-    const fetchImpl = (input, init) => (options.fetch ?? globalThis.fetch)(input, init);
+    const fetchImpl = (input, init) => (options.fetch ?? defaultFetch)(input, init);
     const scopeSeparator = options.scopeSeparator ?? " ";
     async function exchangeCode(input) {
         const body = new URLSearchParams({

package/esm/identity/external/oidc.js

@@ -7,6 +7,7 @@
 import { DirectClient } from "../../client/direct-client.js";
 import { MemoryAuthRequestStorage } from "../../client/storage.js";
 import { isOAuth2Error } from "../../errors.js";
+import { defaultFetch } from "../../utils/_default-fetch.js";
 import { generateCodeChallenge } from "../../utils/pkce.js";
 import { assertIdTokenClaims, describeError, stripTrailingSlash, } from "./_shared.js";
 import { ExternalAuthError } from "./errors.js";
@@ -53,7 +54,7 @@ export function oidcProvider(options) {
     const defaultScopes = options.scopes ?? ["openid", "email", "profile"];
     const fetchImpl = (input, init) => {
         assertSecureIssuer(id, input instanceof Request ? input.url : String(input));
-        return (options.fetch ?? globalThis.fetch)(input, {
+        return (options.fetch ?? defaultFetch)(input, {
             ...init,
             redirect: "error",
         });

package/esm/identity/hibp.js

@@ -18,6 +18,7 @@
  * @module
  */
 import { encodeHex } from "../deps/jsr.io/@std/encoding/1.0.11/hex.js";
+import { defaultFetch, packageDeadlineSignal, } from "../utils/_default-fetch.js";
 import { dispatchIdentityEvent } from "./events.js";
 const DEFAULT_BASE_URL = "https://api.pwnedpasswords.com/range/";
 const VALIDATOR_NAME = "breached_password";
@@ -44,7 +45,7 @@ export function breachedPasswordValidator(options = {}) {
     const threshold = options.threshold ?? 1;
     const failOpen = options.failOpen ?? true;
     const timeoutMs = options.timeoutMs ?? 3000;
-    const fetchImpl = options.fetch ?? fetch;
+    const fetchImpl = options.fetch ?? defaultFetch;
     const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
     const onEvent = options.onEvent;
     return async (password) => {
@@ -54,7 +55,7 @@ export function breachedPasswordValidator(options = {}) {
             const suffix = hash.slice(5);
             const response = await fetchImpl(`${baseUrl}${prefix}`, {
                 headers: { "Add-Padding": "true" },
-                signal: AbortSignal.timeout(timeoutMs),
+                signal: packageDeadlineSignal(AbortSignal.timeout(timeoutMs)),
             });
             if (!response.ok) {
                 await response.body?.cancel();

package/esm/server/authorization-server.d.ts

@@ -63,9 +63,19 @@ export interface EndSessionContext<Client extends ClientInterface> {
 }
 /** What an app's {@link EndSessionFn} may ask the server to do afterwards. */
 export interface EndSessionResult {
+    /**
+     * The app refused this logout (for example, the verified `id_token_hint`
+     * names a different person than the current session). Ignore the caller's
+     * redirect and all `headers`, including any `Set-Cookie`, so the response
+     * neither sends the browser to the RP nor clears the current session.
+     * Answer at `fallback` if supplied, otherwise 204. Omit or set `false` to
+     * preserve the normal logout behavior.
+     */
+    refused?: boolean;
     /**
      * Headers to merge into the response — the session-clearing `Set-Cookie`,
-     * typically. The server owns `Location`; anything else is yours.
+     * typically. The server owns `Location`; anything else is yours. Ignored
+     * when `refused` is true.
      */
     headers?: HeadersInit;
     /**

package/esm/server/authorization-server.js

@@ -580,8 +580,10 @@ export class AuthorizationServer extends ResourceServer {
                 subject: params.subject,
                 logoutHint: params.logoutHint,
             }) ?? {};
-            const headers = new Headers(result.headers);
-            const authorized = this.#postLogoutRedirect(client, params);
+            const headers = new Headers(result.refused ? undefined : result.headers);
+            const authorized = result.refused
+                ? undefined
+                : this.#postLogoutRedirect(client, params);
             const target = authorized ?? result.fallback;
             if (!target)
                 return new Response(null, { status: 204, headers });

package/esm/server/introspection-token-reader.d.ts

@@ -70,7 +70,10 @@ export interface IntrospectionTokenReaderOptions<Client extends ClientInterface,
     /**
      * `fetch` implementation used to call the introspection endpoint. Defaults
      * to the global `fetch`. Inject it to route through a custom client (mTLS,
-     * timeouts, retries) or to stub the network in tests.
+     * timeouts, retries) or to stub the network in tests. On Deno the default
+     * stops reusing a pooled HTTP/2 connection to a host once a request to it
+     * misses {@linkcode fetchTimeoutMs}; an injected `fetch` manages its own
+     * connections.
      */
     fetch?: typeof fetch;
 }

package/esm/server/introspection-token-reader.js

@@ -12,6 +12,7 @@
 import { ServerError, TemporarilyUnavailableError } from "../errors.js";
 import { BasicScope } from "../models/scope.js";
 import { encodeBasicAuth } from "../utils/basic-auth.js";
+import { defaultFetch, packageDeadlineSignal, } from "../utils/_default-fetch.js";
 /**
  * Validates tokens by calling an OAuth2 introspection endpoint (RFC 7662).
  *
@@ -127,9 +128,9 @@ export class IntrospectionTokenReader {
         };
     }
     async #introspect(accessToken) {
-        const fetchImpl = this.customFetch ?? globalThis.fetch;
+        const fetchImpl = this.customFetch ?? defaultFetch;
         const controller = new AbortController();
-        const deadline = setTimeout(() => controller.abort(), this.fetchTimeoutMs);
+        const deadline = setTimeout(() => controller.abort(new DOMException("token introspection timed out", "TimeoutError")), this.fetchTimeoutMs);
         try {
             let response;
             try {
@@ -140,7 +141,7 @@ export class IntrospectionTokenReader {
                         "Authorization": encodeBasicAuth(this.clientId, this.clientSecret),
                     },
                     body: new URLSearchParams({ token: accessToken }),
-                    signal: controller.signal,
+                    signal: packageDeadlineSignal(controller.signal),
                 });
             }
             catch (cause) {

package/esm/server/jwks-token-reader.d.ts

@@ -167,7 +167,10 @@ export interface JwksTokenReaderOptions<Client extends ClientInterface, User, S
     /**
      * `fetch` implementation used for JWKS and discovery requests. Defaults to
      * the global `fetch`. Inject it to route through a custom client (mTLS,
-     * timeouts, retries) or to stub the network in tests.
+     * timeouts, retries) or to stub the network in tests. On Deno the default
+     * stops reusing a pooled HTTP/2 connection to a host once a request to it
+     * misses {@linkcode fetchTimeoutMs}; an injected `fetch` manages its own
+     * connections.
      */
     fetch?: typeof fetch;
 }

package/esm/server/jwks-token-reader.js

@@ -16,6 +16,7 @@ import { ServerError, TemporarilyUnavailableError } from "../errors.js";
 import { BasicScope } from "../models/scope.js";
 import { toArrayBuffer } from "../utils/_buffer.js";
 import { base64urlDecode } from "../utils/crypto.js";
+import { defaultFetch, packageDeadlineSignal, } from "../utils/_default-fetch.js";
 const ALGORITHMS = {
     ES256: {
         kty: "EC",
@@ -472,15 +473,15 @@ export class JwksTokenReader {
         throw transientError ?? lastError ?? new ServerError("discovery failed");
     }
     async #fetchJson(url, label) {
-        const fetchImpl = this.#customFetch ?? globalThis.fetch;
+        const fetchImpl = this.#customFetch ?? defaultFetch;
         const controller = new AbortController();
-        const deadline = setTimeout(() => controller.abort(), this.#fetchTimeoutMs);
+        const deadline = setTimeout(() => controller.abort(new DOMException(`${label} request timed out`, "TimeoutError")), this.#fetchTimeoutMs);
         try {
             let response;
             try {
                 response = await fetchImpl(url, {
                     headers: { "Accept": "application/json" },
-                    signal: controller.signal,
+                    signal: packageDeadlineSignal(controller.signal),
                 });
             }
             catch (cause) {

package/esm/utils/_default-fetch.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Not part of the public API. The `fetch` the package sends with when its
+ * caller injects none: the global `fetch`, resolved at call time, except that
+ * on Deno, once a request to an `https` origin misses a deadline the package
+ * set (see {@link packageDeadlineSignal}) before its response has fully
+ * arrived, later requests to that origin each use a connection of their own
+ * instead of the pooled HTTP/2 connection, which may be stalled.
+ *
+ * @module
+ */
+/**
+ * The signal to send a request with when the package bounds it by its own
+ * `deadline`; it also aborts when the caller's `signal` does. Only a request
+ * whose signal came from here can move its origin off the pooled connection,
+ * and only when `deadline` is what aborted it.
+ */
+export declare function packageDeadlineSignal(deadline: AbortSignal, signal?: AbortSignal | null): AbortSignal;
+/** The package's default `fetch`; see the module documentation. */
+export declare const defaultFetch: typeof fetch;

package/esm/utils/_default-fetch.js

@@ -0,0 +1,114 @@
+/**
+ * Not part of the public API. The `fetch` the package sends with when its
+ * caller injects none: the global `fetch`, resolved at call time, except that
+ * on Deno, once a request to an `https` origin misses a deadline the package
+ * set (see {@link packageDeadlineSignal}) before its response has fully
+ * arrived, later requests to that origin each use a connection of their own
+ * instead of the pooled HTTP/2 connection, which may be stalled.
+ *
+ * @module
+ */
+const NULL_BODY_STATUSES = new Set([204, 205, 304]);
+const abandonedOrigins = new Set();
+const packageDeadlines = new WeakMap();
+/**
+ * The signal to send a request with when the package bounds it by its own
+ * `deadline`; it also aborts when the caller's `signal` does. Only a request
+ * whose signal came from here can move its origin off the pooled connection,
+ * and only when `deadline` is what aborted it.
+ */
+export function packageDeadlineSignal(deadline, signal) {
+    const combined = signal ? AbortSignal.any([signal, deadline]) : deadline;
+    packageDeadlines.set(combined, deadline);
+    return combined;
+}
+/** The package's default `fetch`; see the module documentation. */
+export const defaultFetch = async (input, init) => {
+    const createHttpClient = denoCreateHttpClient();
+    const origin = createHttpClient ? httpsOrigin(input) : undefined;
+    if (!createHttpClient || origin === undefined) {
+        return await globalThis.fetch(input, init);
+    }
+    if (abandonedOrigins.has(origin)) {
+        return await fetchOnOwnConnection(createHttpClient, input, init);
+    }
+    const signal = init?.signal;
+    const deadline = signal ? packageDeadlines.get(signal) : undefined;
+    if (!signal || !deadline)
+        return await globalThis.fetch(input, init);
+    const abandonIfDeadlineMissed = () => {
+        if (deadline.aborted && signal.reason === deadline.reason) {
+            abandonedOrigins.add(origin);
+        }
+    };
+    let response;
+    try {
+        response = await globalThis.fetch(input, init);
+    }
+    catch (error) {
+        abandonIfDeadlineMissed();
+        throw error;
+    }
+    return watchBody(response, abandonIfDeadlineMissed);
+};
+function denoCreateHttpClient() {
+    const deno = globalThis.Deno;
+    const create = deno?.createHttpClient;
+    return typeof create === "function"
+        ? (options) => create.call(deno, options)
+        : undefined;
+}
+function httpsOrigin(input) {
+    try {
+        const url = new URL(input instanceof Request ? input.url : input);
+        return url.protocol === "https:" ? url.origin : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function fetchOnOwnConnection(createHttpClient, input, init) {
+    let client;
+    try {
+        client = createHttpClient({});
+    }
+    catch {
+        return await globalThis.fetch(input, init);
+    }
+    try {
+        return await globalThis.fetch(input, { ...init, client });
+    }
+    finally {
+        client.close();
+    }
+}
+function watchBody(response, onError) {
+    const { body: source, status } = response;
+    if (!source || status < 200 || status > 599 || NULL_BODY_STATUSES.has(status)) {
+        return response;
+    }
+    const reader = source.getReader();
+    const body = new ReadableStream({
+        async pull(controller) {
+            let chunk;
+            try {
+                chunk = await reader.read();
+            }
+            catch (error) {
+                onError();
+                controller.error(error);
+                return;
+            }
+            if (chunk.done)
+                controller.close();
+            else
+                controller.enqueue(chunk.value);
+        },
+        cancel: (reason) => reader.cancel(reason),
+    });
+    return new Response(body, {
+        status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "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",