DPoP for JavaScript Runtimes

Common errors

• TypeError: DPoP.generateKeyPair is not a function

  cause Attempting to call functions as properties of a default import, but `dpop` uses named exports since v2.0.0.
  fix Change your import from `import DPoP from 'dpop';` to `import * as DPoP from 'dpop';` or `import { generateKeyPair } from 'dpop';`.

• ReferenceError: generateKeyPair is not defined

  cause Trying to use a named export function without importing it explicitly or via a namespace import.
  fix Ensure `generateKeyPair` is properly imported: `import { generateKeyPair } from 'dpop';` or accessed via a namespace: `import * as DPoP from 'dpop'; DPoP.generateKeyPair(...)`.

• Error: 'modulusLength' option is not supported for key generation.

  cause Using the `modulusLength` option in `generateKeyPair` after it was removed in v2.0.0.
  fix Remove the `modulusLength` option from your `generateKeyPair` call. The library no longer supports it.

Warnings

• breaking Version 2.0.0 removed default exports in favor of named exports. All functions must now be imported via destructuring (e.g., `import { generateKeyPair } from 'dpop';`) or by importing all as a namespace (e.g., `import * as DPoP from 'dpop';`).
  Fix: Update your import statements: change `import DPoP from 'dpop';` to `import * as DPoP from 'dpop';` or `import { functionName } from 'dpop';`.
• breaking The `modulusLength` option for key generation has been removed in v2.0.0. This option was specific to RSA keys and its removal streamlines the API, focusing on more modern and recommended algorithms.
  Fix: Remove the `modulusLength` option from your `generateKeyPair` calls. If you need RSA keys with specific modulus lengths, consider generating them externally and importing them, or use algorithms like ES256, Ed25519.
• breaking Support for the deprecated EdDSA algorithm was removed in v2.0.0. The library now supports the fully-specified Ed25519 JWS Algorithm.
  Fix: Migrate any usage of the deprecated EdDSA algorithm to Ed25519 or another supported algorithm like ES256.
• gotcha Node.js v20.x or higher is required as a baseline runtime environment for `dpop` v2.x. This is due to the library's reliance on modern Web API globals and standard built-in objects.
  Fix: Ensure your Node.js environment is version 20.x or newer. Use a version manager like `nvm` to upgrade if necessary.

Install

• npm install dpop npm
• yarn add dpop yarn
• pnpm add dpop pnpm

Imports

• DPoP
  wrong:

  const DPoP = require('dpop');

  correct:

  import * as DPoP from 'dpop';

  Since v2.0.0, the package primarily uses named exports. Using `import * as DPoP` is the recommended way to import all functionalities. CommonJS `require('dpop')` is only fully supported in Node.js versions where `require(esm)` is enabled by default (e.g., ^20.19.0 || ^22.12.0 || >= 23.0.0).
• generateKeyPair, generateProof
  wrong:

  import DPoP, { generateKeyPair, generateProof } from 'dpop';

  correct:

  import { generateKeyPair, generateProof } from 'dpop';

  As of v2.0.0, the library moved to named exports exclusively. Functions like `generateKeyPair` and `generateProof` must be destructured from the 'dpop' module. Attempting a default import will result in `undefined`.
• calculateThumbprint
  wrong:

  import * as DPoP from 'dpop'; const dpop_jkt = await DPoP.dpop_jkt(publicKey);

  correct:

  import { calculateThumbprint } from 'dpop';

  The `calculateThumbprint` function, introduced in v2.1.0, is specifically for computing the `dpop_jkt`. It is a named export and should be imported directly or accessed via `DPoP.calculateThumbprint` after a `* as DPoP` import. There is no top-level `dpop_jkt` function.

Quickstart

Demonstrates DPoP key pair generation, dpop_jkt calculation, and DPoP proof generation for both Authorization Server token requests and Resource Server API calls.

import * as DPoP from 'dpop';

async function runDPoPExample() {
  console.log('Starting DPoP example...');

  // 1. Generate a DPoP Key Pair (e.g., ES256 algorithm)
  // The 'extractable: false' option is good practice for non-exportable keys
  const keyPair = await DPoP.generateKeyPair('ES256', { extractable: false });
  console.log('DPoP Key Pair generated using ES256.');

  // 2. Calculate the dpop_jkt (Key Thumbprint) for authorization code binding
  // This identifies the public key associated with the DPoP proof
  const dpop_jkt = await DPoP.calculateThumbprint(keyPair.publicKey);
  console.log('Calculated dpop_jkt:', dpop_jkt);

  // 3. Generate a DPoP proof for an Authorization Server (AS) token request
  // This proof is sent with the token request to the AS
  const asTokenUrl = 'https://as.example.com/token';
  const asProof = await DPoP.generateProof(keyPair, asTokenUrl, 'POST');
  console.log('DPoP Proof for AS Token Request:', asProof.slice(0, 100), '...'); // Truncate for display

  // 4. Simulate an Access Token from the AS and generate a DPoP proof for a Resource Server (RS) API request
  // The access token is bound to the DPoP key when making requests to the RS
  const rsApiUrl = 'https://rs.example.com/api/data';
  const accessToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJhY2Nlc3NfdG9rZW4iOnRydWV9.SflKxwRJSMeKKF2F8DGD_dPOk_W5dZg_qkX-zHjN_W0'; // Example dummy token
  const nonceFromRS = undefined; // In a real scenario, this might come from a 'DPoP-Nonce' header
  const rsProof = await DPoP.generateProof(
    keyPair,
    rsApiUrl,
    'GET',
    nonceFromRS,
    accessToken
  );
  console.log('DPoP Proof for RS API Request:', rsProof.slice(0, 100), '...'); // Truncate for display
}

runDPoPExample().catch(console.error);