signet-core 1.0.0

package/utils/dpop.ts

@@ -0,0 +1,174 @@
+/**
+ * DPoP (Distributed Proof of Possession) Utilities
+ * 
+ * This module provides functionality to generate DPoP tokens for secure API authentication.
+ * DPoP binds access tokens to a specific public key, preventing token theft and replay attacks.
+ */
+
+import * as crypto from 'crypto';
+import { SignJWT, jwtVerify, type JWK } from 'jose';
+
+export interface DPoPKeyPair {
+  privateKey: crypto.KeyObject;
+  publicKey: crypto.KeyObject;
+  jwk: JWK;
+  thumbprint: string;
+}
+
+export interface DPoPProofOptions {
+  method: string;
+  url: string;
+  accessToken?: string;
+  nonce?: string;
+  jti?: string;
+}
+
+/**
+ * Generate a new DPoP key pair
+ * @param algorithm - The algorithm to use (default: ES256)
+ * @returns A DPoP key pair with private key, public key, JWK, and thumbprint
+ */
+export async function generateDPoPKeyPair(algorithm: string = 'ES256'): Promise<DPoPKeyPair> {
+  let keyPair: crypto.KeyPairKeyObjectResult;
+  let jwk: JWK;
+
+  if (algorithm.startsWith('ES')) {
+    // ECDSA key pair
+    const curve = algorithm === 'ES256' ? 'P-256' : algorithm === 'ES384' ? 'P-384' : 'P-521';
+    keyPair = crypto.generateKeyPairSync('ec', {
+      namedCurve: curve,
+    });
+    
+    // Convert to JWK format
+    const publicKeyJwk = keyPair.publicKey.export({ format: 'jwk' });
+    jwk = {
+      kty: publicKeyJwk.kty!,
+      crv: publicKeyJwk.crv!,
+      x: publicKeyJwk.x!,
+      y: publicKeyJwk.y!,
+    };
+  } else {
+    throw new Error(`Unsupported algorithm: ${algorithm}. Only ES256, ES384, ES512 are supported.`);
+  }
+
+  // Calculate JWK thumbprint (RFC 7638)
+  const thumbprint = crypto
+    .createHash('sha256')
+    .update(JSON.stringify({ ...jwk, alg: algorithm }))
+    .digest('base64url');
+
+  return {
+    privateKey: keyPair.privateKey,
+    publicKey: keyPair.publicKey,
+    jwk,
+    thumbprint,
+  };
+}
+
+/**
+ * Generate a DPoP proof JWT
+ * @param keyPair - The DPoP key pair
+ * @param options - DPoP proof options (method, url, accessToken, nonce, jti)
+ * @param algorithm - The signing algorithm (default: ES256)
+ * @returns A signed DPoP proof JWT
+ */
+export async function generateDPoPProof(
+  keyPair: DPoPKeyPair,
+  options: DPoPProofOptions,
+  algorithm: string = 'ES256'
+): Promise<string> {
+  const now = Math.floor(Date.now() / 1000);
+  const jti = options.jti || crypto.randomBytes(16).toString('hex');
+
+  const payload: Record<string, unknown> = {
+    iat: now,
+    jti,
+    htu: options.url,
+    htm: options.method.toUpperCase(),
+  };
+
+  if (options.accessToken) {
+    payload.ath = crypto
+      .createHash('sha256')
+      .update(options.accessToken)
+      .digest('base64url');
+  }
+
+  if (options.nonce) {
+    payload.nonce = options.nonce;
+  }
+
+  const jwt = new SignJWT(payload)
+    .setProtectedHeader({
+      typ: 'dpop+jwt',
+      alg: algorithm,
+      jwk: keyPair.jwk,
+    })
+    .setIssuedAt(now)
+    .setJti(jti);
+
+  // Sign with the private key
+  const privateKeyPem = keyPair.privateKey.export({ format: 'pem', type: 'pkcs8' });
+  return await jwt.sign(crypto.createPrivateKey(privateKeyPem));
+}
+
+/**
+ * DPoP Manager class for managing DPoP keys and generating proofs
+ */
+export class DPoPManager {
+  private keyPair: DPoPKeyPair | null = null;
+  private algorithm: string;
+
+  constructor(algorithm: string = 'ES256') {
+    this.algorithm = algorithm;
+  }
+
+  /**
+   * Initialize or get the DPoP key pair
+   * @returns The DPoP key pair
+   */
+  async getKeyPair(): Promise<DPoPKeyPair> {
+    if (!this.keyPair) {
+      this.keyPair = await generateDPoPKeyPair(this.algorithm);
+    }
+    return this.keyPair;
+  }
+
+  /**
+   * Generate a DPoP proof for a request
+   * @param method - HTTP method
+   * @param url - Request URL
+   * @param accessToken - Optional access token to bind the proof to
+   * @param nonce - Optional nonce from the server
+   * @returns DPoP proof JWT
+   */
+  async generateProof(
+    method: string,
+    url: string,
+    accessToken?: string,
+    nonce?: string
+  ): Promise<string> {
+    const keyPair = await this.getKeyPair();
+    return generateDPoPProof(keyPair, { method, url, accessToken, nonce }, this.algorithm);
+  }
+
+  /**
+   * Get the public key JWK for registration/authentication
+   * @returns Public key JWK
+   */
+  async getPublicKeyJWK(): Promise<JWK> {
+    const keyPair = await this.getKeyPair();
+    return keyPair.jwk;
+  }
+
+  /**
+   * Get the JWK thumbprint
+   * @returns JWK thumbprint
+   */
+  async getThumbprint(): Promise<string> {
+    const keyPair = await this.getKeyPair();
+    return keyPair.thumbprint;
+  }
+}
+
+