Low-Level OAuth 2 / OpenID Connect Client API

Common errors

• TypeError: require is not a function

  cause Attempting to use `require('oauth4webapi')` in an ES Module context, or in a Node.js project configured for ESM when the library only exports ESM.
  fix Change your import statement to `import * as oauth from 'oauth4webapi'`. If your project is CommonJS, consider setting `"type": "module"` in `package.json` or use `import('oauth4webapi')` dynamically.

• ReferenceError: crypto is not defined

  cause The runtime environment (e.g., older Node.js versions or specific browser environments) does not provide a global `crypto` object with the Web Cryptography API.
  fix Ensure you are running in a modern JavaScript runtime (Node.js >= 15, modern browsers, Deno, Bun, Cloudflare Workers). For older Node.js, you might need a polyfill, though it's generally recommended to upgrade.

• TypeError: subtle.generateKeyPair is not a function

  cause The `crypto.subtle` object is available, but the specific Web Cryptography API method required (e.g., `generateKeyPair` for DPoP) is not implemented or is not available in the current context (e.g., secure contexts only in browsers).
  fix Verify that your runtime fully supports the Web Cryptography API methods used by oauth4webapi. In browser contexts, ensure your application is served over HTTPS. If in Node.js, ensure sufficient version.

• Error: DPoP nonce caching caveats with customFetch

  cause When providing a custom `fetch` implementation, DPoP nonces might not be correctly handled or cached, leading to replay protection issues or failed requests.
  fix Review the DPoP nonce handling in your custom `fetch` implementation. Ensure it correctly processes `DPoP-Nonce` headers and updates the nonce accordingly, or consider using the library's default fetch behavior if possible. (Addressed in v3.8.2 with a workaround, but custom fetch still needs care.)

Warnings

• breaking oauth4webapi is an ESM-only package. Projects requiring CommonJS must use dynamic import() or transpile their code to ESM. Direct `require()` statements will result in runtime errors.
  Fix: Migrate your project to use ES Modules, or use `import()` for dynamic loading in CommonJS contexts. Ensure your `package.json` specifies `"type": "module"` if using Node.js ESM.
• gotcha The library relies heavily on the Web Cryptography API, which may have varying levels of support or specific quirks across different JavaScript runtimes (e.g., Node.js, Deno, Bun, Cloudflare Workers, browsers). While efforts are made for compatibility, edge cases can arise.
  Fix: Thoroughly test cryptographic operations in your target runtime environments. Consult runtime-specific documentation for Web Cryptography API differences. Ensure environments provide `crypto.subtle`.
• gotcha As a low-level client, oauth4webapi requires developers to manage the entire OAuth/OIDC flow, including PKCE verifiers, nonces, state parameters, and cookie/session management. Errors in handling these can lead to security vulnerabilities.
  Fix: Always store and retrieve PKCE code verifiers, nonces, and state parameters securely for validation. Never expose sensitive client secrets on the client-side. Follow the examples and best practices outlined in the documentation meticulously.
• deprecated Older, less secure OAuth 2.0 flows or patterns without PKCE are discouraged. While the library supports various profiles, it promotes the latest Security Best Current Practices (BCP) and FAPI 2.0 standards.
  Fix: Always implement the Authorization Code Flow with PKCE (Proof Key for Code Exchange) as per OAuth 2.1 and current BCPs for public clients. Avoid implicit flow entirely. Review the FAPI 2.0 examples.
• gotcha A recent refactor in v3.8.5 accounts for an upcoming Web Cryptography change, which might subtly affect existing integrations relying on specific Web Crypto behaviors, though it's likely a forward-compatibility fix.
  Fix: Monitor for any unexpected behavior related to cryptographic operations (e.g., `generateKeyPair`, `sign`, `verify`) after updating to v3.8.5 or later. If issues arise, consult the upstream Web Cryptography specification changes.

Install

• npm install oauth4webapi npm
• yarn add oauth4webapi yarn
• pnpm add oauth4webapi pnpm

Imports

• oauth
  wrong:

  const oauth = require('oauth4webapi')

  correct:

  import * as oauth from 'oauth4webapi'

  oauth4webapi is an ESM-only package. Direct CommonJS 'require' is not supported. Use dynamic import for CJS contexts or ensure your environment supports ESM.
• discover
  wrong:

  import oauth from 'oauth4webapi'; oauth.discover(...)

  correct:

  import { discover } from 'oauth4webapi'

  While the library is often imported as a namespace, individual functions like `discover` can be destructured for tree-shaking and clearer usage.
• generatePKCE

  import { generatePKCE } from 'oauth4webapi'

  Utilities for PKCE (Proof Key for Code Exchange) are directly exportable. This is a common pattern for specific cryptographic operations.

Quickstart

This quickstart demonstrates a basic OpenID Connect Authorization Code Flow with PKCE, covering discovery, authorization URL generation, and code exchange for tokens using Google as the IdP. It highlights key functions like `discover`, `generatePKCE`, `authorizationUrl`, and `exchangeCode`.

import { discover, calculatePKCEChallenge, generatePKCE, authorizationUrl, processAuthorizationResponse, exchangeCode, Issuer, Client, TokenEndpointResponse, JWKS } from 'oauth4webapi';

const as = await discover(new URL('https://accounts.google.com/.well-known/openid-configuration'));

const client: Client = {
  client_id: process.env.GOOGLE_CLIENT_ID ?? '',
  client_secret: process.env.GOOGLE_CLIENT_SECRET ?? '',
  token_endpoint_auth_method: 'client_secret_post'
};

const redirect_uri = 'http://localhost:3000/callback';

async function initiateOAuthFlow() {
  const pkce = generatePKCE();
  const code_challenge = await calculatePKCEChallenge(pkce);

  const authUrl = new URL(authorizationUrl(as, client, {
    redirect_uri,
    scope: 'openid email profile',
    response_type: 'code',
    code_challenge,
    code_challenge_method: 'S256',
    nonce: 'some-random-nonce'
  }));
  console.log('Please visit this URL to authenticate:', authUrl.toString());
  // In a real application, you would redirect the user to authUrl.
  // For this example, you'd manually visit and get the code from the callback.
}

async function handleCallback(requestUrl: string) {
  const currentUrl = new URL(requestUrl);
  const params = oauth.validateAuthResponse(as, client, currentUrl);

  if (oauth.is= (params instanceof Error)) {
    console.error('Authorization response error:', params);
    return;
  }

  const response = await exchangeCode(as, client, params.code, {
    redirect_uri,
    code_verifier: 'your_pkce_code_verifier_here' // Replace with actual verifier from initiateOAuthFlow
  });

  if (response instanceof Error) {
    console.error('Token exchange error:', response);
    return;
  }

  console.log('Access Token:', response.access_token);
  console.log('ID Token:', response.id_token);

  // Further validation and usage of tokens would follow
}

// Example usage (simplified for quickstart)
initiateOAuthFlow();
// To test handleCallback, you'd simulate a redirect after authentication
// handleCallback('http://localhost:3000/callback?code=YOUR_CODE_HERE&state=YOUR_STATE_HERE');