@xivdyetools/auth 1.0.0

package/src/discord.ts

@@ -0,0 +1,143 @@
+/**
+ * Discord Request Verification
+ *
+ * Wraps the `discord-interactions` library's Ed25519 signature verification
+ * with additional security checks (body size limits, header validation).
+ *
+ * @see https://discord.com/developers/docs/interactions/receiving-and-responding#security-and-authorization
+ * @module discord
+ */
+
+import { verifyKey } from 'discord-interactions';
+
+/**
+ * Result of Discord request verification
+ */
+export interface DiscordVerificationResult {
+  /** Whether the signature is valid */
+  isValid: boolean;
+  /** The raw request body (needed for parsing after verification) */
+  body: string;
+  /** Error message if verification failed */
+  error?: string;
+}
+
+/**
+ * Options for Discord verification
+ */
+export interface DiscordVerifyOptions {
+  /** Maximum request body size in bytes (default: 100KB) */
+  maxBodySize?: number;
+}
+
+/** Default maximum body size (100KB) */
+const DEFAULT_MAX_BODY_SIZE = 100_000;
+
+/**
+ * Verify that a request came from Discord using Ed25519 signature verification.
+ *
+ * Security features:
+ * - Content-Length header check (before reading body)
+ * - Actual body size validation (Content-Length can be spoofed)
+ * - Required header validation (X-Signature-Ed25519, X-Signature-Timestamp)
+ *
+ * @param request - The incoming HTTP request
+ * @param publicKey - Your Discord application's public key
+ * @param options - Verification options
+ * @returns Verification result with the request body
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyDiscordRequest(request, env.DISCORD_PUBLIC_KEY);
+ * if (!result.isValid) {
+ *   return new Response(result.error, { status: 401 });
+ * }
+ * const interaction = JSON.parse(result.body);
+ * ```
+ */
+export async function verifyDiscordRequest(
+  request: Request,
+  publicKey: string,
+  options: DiscordVerifyOptions = {}
+): Promise<DiscordVerificationResult> {
+  const maxBodySize = options.maxBodySize ?? DEFAULT_MAX_BODY_SIZE;
+
+  // Check Content-Length header first (if present) to reject obviously large requests
+  const contentLength = request.headers.get('Content-Length');
+  if (contentLength && parseInt(contentLength, 10) > maxBodySize) {
+    return {
+      isValid: false,
+      body: '',
+      error: 'Request body too large',
+    };
+  }
+
+  // Get required headers
+  const signature = request.headers.get('X-Signature-Ed25519');
+  const timestamp = request.headers.get('X-Signature-Timestamp');
+
+  if (!signature || !timestamp) {
+    return {
+      isValid: false,
+      body: '',
+      error: 'Missing signature headers',
+    };
+  }
+
+  // Get the raw body
+  const body = await request.text();
+
+  // Verify actual body size (Content-Length can be spoofed)
+  if (body.length > maxBodySize) {
+    return {
+      isValid: false,
+      body: '',
+      error: 'Request body too large',
+    };
+  }
+
+  // Verify the signature using discord-interactions library
+  try {
+    const isValid = await verifyKey(body, signature, timestamp, publicKey);
+
+    return {
+      isValid,
+      body,
+      error: isValid ? undefined : 'Invalid signature',
+    };
+  } catch (error) {
+    return {
+      isValid: false,
+      body,
+      error: error instanceof Error ? error.message : 'Verification failed',
+    };
+  }
+}
+
+/**
+ * Creates a 401 Unauthorized response for failed verification.
+ *
+ * @param message - Error message (default: 'Invalid request signature')
+ * @returns Response object
+ */
+export function unauthorizedResponse(
+  message = 'Invalid request signature'
+): Response {
+  return new Response(JSON.stringify({ error: message }), {
+    status: 401,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+/**
+ * Creates a 400 Bad Request response.
+ *
+ * @param message - Error message
+ * @returns Response object
+ */
+export function badRequestResponse(message: string): Response {
+  return new Response(JSON.stringify({ error: message }), {
+    status: 400,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}

package/src/hmac.test.ts

@@ -0,0 +1,325 @@
+/**
+ * Tests for HMAC Signing Utilities
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  createHmacKey,
+  hmacSign,
+  hmacSignHex,
+  hmacVerify,
+  hmacVerifyHex,
+  verifyBotSignature,
+} from './hmac.js';
+
+describe('hmac.ts', () => {
+  describe('createHmacKey', () => {
+    it('should create a CryptoKey for signing', async () => {
+      const key = await createHmacKey('test-secret', 'sign');
+      expect(key).toBeDefined();
+      expect(key.algorithm.name).toBe('HMAC');
+    });
+
+    it('should create a CryptoKey for verification', async () => {
+      const key = await createHmacKey('test-secret', 'verify');
+      expect(key).toBeDefined();
+      expect(key.algorithm.name).toBe('HMAC');
+    });
+
+    it('should create a CryptoKey for both operations', async () => {
+      const key = await createHmacKey('test-secret', 'both');
+      expect(key).toBeDefined();
+    });
+
+    it('should default to both operations', async () => {
+      const key = await createHmacKey('test-secret');
+      expect(key).toBeDefined();
+    });
+  });
+
+  describe('hmacSign', () => {
+    it('should return a base64url-encoded signature', async () => {
+      const signature = await hmacSign('test-data', 'test-secret');
+      expect(signature).toBeDefined();
+      expect(typeof signature).toBe('string');
+      // Base64URL should not contain + or /
+      expect(signature).not.toMatch(/[+/]/);
+    });
+
+    it('should produce consistent signatures for same input', async () => {
+      const sig1 = await hmacSign('test-data', 'test-secret');
+      const sig2 = await hmacSign('test-data', 'test-secret');
+      expect(sig1).toBe(sig2);
+    });
+
+    it('should produce different signatures for different data', async () => {
+      const sig1 = await hmacSign('data1', 'test-secret');
+      const sig2 = await hmacSign('data2', 'test-secret');
+      expect(sig1).not.toBe(sig2);
+    });
+
+    it('should produce different signatures for different secrets', async () => {
+      const sig1 = await hmacSign('test-data', 'secret1');
+      const sig2 = await hmacSign('test-data', 'secret2');
+      expect(sig1).not.toBe(sig2);
+    });
+  });
+
+  describe('hmacSignHex', () => {
+    it('should return a hex-encoded signature', async () => {
+      const signature = await hmacSignHex('test-data', 'test-secret');
+      expect(signature).toBeDefined();
+      expect(typeof signature).toBe('string');
+      // Should only contain hex characters
+      expect(signature).toMatch(/^[0-9a-f]+$/);
+    });
+
+    it('should produce consistent signatures', async () => {
+      const sig1 = await hmacSignHex('test-data', 'test-secret');
+      const sig2 = await hmacSignHex('test-data', 'test-secret');
+      expect(sig1).toBe(sig2);
+    });
+  });
+
+  describe('hmacVerify', () => {
+    it('should return true for valid signature', async () => {
+      const data = 'test-data';
+      const secret = 'test-secret';
+      const signature = await hmacSign(data, secret);
+      const isValid = await hmacVerify(data, signature, secret);
+      expect(isValid).toBe(true);
+    });
+
+    it('should return false for invalid signature', async () => {
+      const isValid = await hmacVerify('test-data', 'invalid-signature', 'test-secret');
+      expect(isValid).toBe(false);
+    });
+
+    it('should return false for wrong secret', async () => {
+      const data = 'test-data';
+      const signature = await hmacSign(data, 'secret1');
+      const isValid = await hmacVerify(data, signature, 'secret2');
+      expect(isValid).toBe(false);
+    });
+
+    it('should return false for tampered data', async () => {
+      const signature = await hmacSign('original-data', 'test-secret');
+      const isValid = await hmacVerify('tampered-data', signature, 'test-secret');
+      expect(isValid).toBe(false);
+    });
+  });
+
+  describe('hmacVerifyHex', () => {
+    it('should return true for valid hex signature', async () => {
+      const data = 'test-data';
+      const secret = 'test-secret';
+      const signature = await hmacSignHex(data, secret);
+      const isValid = await hmacVerifyHex(data, signature, secret);
+      expect(isValid).toBe(true);
+    });
+
+    it('should return false for invalid hex signature', async () => {
+      const isValid = await hmacVerifyHex('test-data', 'deadbeef', 'test-secret');
+      expect(isValid).toBe(false);
+    });
+
+    it('should return false for malformed hex', async () => {
+      const isValid = await hmacVerifyHex('test-data', 'not-hex!', 'test-secret');
+      expect(isValid).toBe(false);
+    });
+  });
+
+  describe('verifyBotSignature', () => {
+    const secret = 'bot-signing-secret';
+
+    beforeEach(() => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date('2024-01-15T12:00:00Z'));
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('should return true for valid signature', async () => {
+      const timestamp = Math.floor(Date.now() / 1000).toString();
+      const userId = '123456789';
+      const userName = 'testuser';
+      const message = `${timestamp}:${userId}:${userName}`;
+      const signature = await hmacSignHex(message, secret);
+
+      const isValid = await verifyBotSignature(
+        signature,
+        timestamp,
+        userId,
+        userName,
+        secret
+      );
+      expect(isValid).toBe(true);
+    });
+
+    it('should return false for missing signature', async () => {
+      const isValid = await verifyBotSignature(
+        undefined,
+        '1234567890',
+        '123456789',
+        'testuser',
+        secret
+      );
+      expect(isValid).toBe(false);
+    });
+
+    it('should return false for missing timestamp', async () => {
+      const isValid = await verifyBotSignature(
+        'somesignature',
+        undefined,
+        '123456789',
+        'testuser',
+        secret
+      );
+      expect(isValid).toBe(false);
+    });
+
+    it('should return false for missing userId', async () => {
+      const isValid = await verifyBotSignature(
+        'somesignature',
+        '1234567890',
+        undefined,
+        'testuser',
+        secret
+      );
+      expect(isValid).toBe(false);
+    });
+
+    it('should return false for missing userName', async () => {
+      const isValid = await verifyBotSignature(
+        'somesignature',
+        '1234567890',
+        '123456789',
+        undefined,
+        secret
+      );
+      expect(isValid).toBe(false);
+    });
+
+    it('should return false for expired signature', async () => {
+      // Create signature from 10 minutes ago (default max age is 5 minutes)
+      const oldTimestamp = Math.floor(Date.now() / 1000) - 600;
+      const userId = '123456789';
+      const userName = 'testuser';
+      const message = `${oldTimestamp}:${userId}:${userName}`;
+      const signature = await hmacSignHex(message, secret);
+
+      const isValid = await verifyBotSignature(
+        signature,
+        oldTimestamp.toString(),
+        userId,
+        userName,
+        secret
+      );
+      expect(isValid).toBe(false);
+    });
+
+    it('should return false for future timestamp beyond clock skew', async () => {
+      // Create signature 2 minutes in the future (default clock skew is 1 minute)
+      const futureTimestamp = Math.floor(Date.now() / 1000) + 120;
+      const userId = '123456789';
+      const userName = 'testuser';
+      const message = `${futureTimestamp}:${userId}:${userName}`;
+      const signature = await hmacSignHex(message, secret);
+
+      const isValid = await verifyBotSignature(
+        signature,
+        futureTimestamp.toString(),
+        userId,
+        userName,
+        secret
+      );
+      expect(isValid).toBe(false);
+    });
+
+    it('should accept signature within clock skew tolerance', async () => {
+      // Create signature 30 seconds in the future (within default 1 minute clock skew)
+      const futureTimestamp = Math.floor(Date.now() / 1000) + 30;
+      const userId = '123456789';
+      const userName = 'testuser';
+      const message = `${futureTimestamp}:${userId}:${userName}`;
+      const signature = await hmacSignHex(message, secret);
+
+      const isValid = await verifyBotSignature(
+        signature,
+        futureTimestamp.toString(),
+        userId,
+        userName,
+        secret
+      );
+      expect(isValid).toBe(true);
+    });
+
+    it('should return false for invalid timestamp format', async () => {
+      const isValid = await verifyBotSignature(
+        'somesignature',
+        'not-a-number',
+        '123456789',
+        'testuser',
+        secret
+      );
+      expect(isValid).toBe(false);
+    });
+
+    it('should return false for wrong signature', async () => {
+      const timestamp = Math.floor(Date.now() / 1000).toString();
+      const userId = '123456789';
+      const userName = 'testuser';
+
+      const isValid = await verifyBotSignature(
+        'wrongsignature',
+        timestamp,
+        userId,
+        userName,
+        secret
+      );
+      expect(isValid).toBe(false);
+    });
+
+    it('should respect custom maxAgeMs option', async () => {
+      // Create signature from 2 minutes ago
+      const oldTimestamp = Math.floor(Date.now() / 1000) - 120;
+      const userId = '123456789';
+      const userName = 'testuser';
+      const message = `${oldTimestamp}:${userId}:${userName}`;
+      const signature = await hmacSignHex(message, secret);
+
+      // Should fail with default 5 minute max age... wait, 2 minutes is within 5 minutes
+      // Let's use 1 minute max age instead
+      const isValid = await verifyBotSignature(
+        signature,
+        oldTimestamp.toString(),
+        userId,
+        userName,
+        secret,
+        { maxAgeMs: 60 * 1000 } // 1 minute
+      );
+      expect(isValid).toBe(false);
+    });
+
+    it('should respect custom clockSkewMs option', async () => {
+      // Create signature 30 seconds in the future
+      const futureTimestamp = Math.floor(Date.now() / 1000) + 30;
+      const userId = '123456789';
+      const userName = 'testuser';
+      const message = `${futureTimestamp}:${userId}:${userName}`;
+      const signature = await hmacSignHex(message, secret);
+
+      // Should fail with 10 second clock skew tolerance
+      const isValid = await verifyBotSignature(
+        signature,
+        futureTimestamp.toString(),
+        userId,
+        userName,
+        secret,
+        { clockSkewMs: 10 * 1000 } // 10 seconds
+      );
+      expect(isValid).toBe(false);
+    });
+  });
+});

package/src/hmac.ts

@@ -0,0 +1,213 @@
+/**
+ * HMAC Signing Utilities
+ *
+ * Provides HMAC-SHA256 signing and verification using the Web Crypto API.
+ * Used for JWT signing and bot request authentication.
+ *
+ * @module hmac
+ */
+
+import {
+  base64UrlEncodeBytes,
+  bytesToHex,
+  hexToBytes,
+} from '@xivdyetools/crypto';
+
+/**
+ * Options for bot signature verification
+ */
+export interface BotSignatureOptions {
+  /** Maximum age of signature in milliseconds (default: 5 minutes) */
+  maxAgeMs?: number;
+  /** Allowed clock skew in milliseconds (default: 1 minute) */
+  clockSkewMs?: number;
+}
+
+/**
+ * Create an HMAC-SHA256 CryptoKey from a secret string.
+ *
+ * @param secret - The secret string to use as key material
+ * @param usage - Key usage: 'sign', 'verify', or 'both'
+ * @returns CryptoKey for HMAC operations
+ *
+ * @example
+ * ```typescript
+ * const key = await createHmacKey(process.env.JWT_SECRET, 'verify');
+ * ```
+ */
+export async function createHmacKey(
+  secret: string,
+  usage: 'sign' | 'verify' | 'both' = 'both'
+): Promise<CryptoKey> {
+  const encoder = new TextEncoder();
+  const keyData = encoder.encode(secret);
+
+  const keyUsages: ('sign' | 'verify')[] =
+    usage === 'both' ? ['sign', 'verify'] : [usage];
+
+  return crypto.subtle.importKey(
+    'raw',
+    keyData,
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    keyUsages
+  );
+}
+
+/**
+ * Sign data with HMAC-SHA256 and return base64url-encoded signature.
+ *
+ * @param data - The data to sign
+ * @param secret - The secret key
+ * @returns Base64URL-encoded signature
+ *
+ * @example
+ * ```typescript
+ * const signature = await hmacSign('header.payload', jwtSecret);
+ * ```
+ */
+export async function hmacSign(data: string, secret: string): Promise<string> {
+  const key = await createHmacKey(secret, 'sign');
+  const encoder = new TextEncoder();
+  const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(data));
+  return base64UrlEncodeBytes(new Uint8Array(signature));
+}
+
+/**
+ * Sign data with HMAC-SHA256 and return hex-encoded signature.
+ *
+ * @param data - The data to sign
+ * @param secret - The secret key
+ * @returns Hex-encoded signature
+ *
+ * @example
+ * ```typescript
+ * const signature = await hmacSignHex('timestamp:userId:userName', secret);
+ * ```
+ */
+export async function hmacSignHex(
+  data: string,
+  secret: string
+): Promise<string> {
+  const key = await createHmacKey(secret, 'sign');
+  const encoder = new TextEncoder();
+  const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(data));
+  return bytesToHex(new Uint8Array(signature));
+}
+
+/**
+ * Verify HMAC-SHA256 signature (base64url-encoded).
+ *
+ * @param data - The original data that was signed
+ * @param signature - Base64URL-encoded signature to verify
+ * @param secret - The secret key
+ * @returns true if signature is valid
+ */
+export async function hmacVerify(
+  data: string,
+  signature: string,
+  secret: string
+): Promise<boolean> {
+  try {
+    const expectedSignature = await hmacSign(data, secret);
+    // Use timing-safe comparison
+    return expectedSignature === signature;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Verify HMAC-SHA256 signature (hex-encoded).
+ *
+ * @param data - The original data that was signed
+ * @param signature - Hex-encoded signature to verify
+ * @param secret - The secret key
+ * @returns true if signature is valid
+ */
+export async function hmacVerifyHex(
+  data: string,
+  signature: string,
+  secret: string
+): Promise<boolean> {
+  try {
+    const key = await createHmacKey(secret, 'verify');
+    const encoder = new TextEncoder();
+    const signatureBytes = hexToBytes(signature);
+
+    return crypto.subtle.verify(
+      'HMAC',
+      key,
+      signatureBytes,
+      encoder.encode(data)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Verify a bot request signature.
+ *
+ * Bot signatures use the format: `${timestamp}:${userDiscordId}:${userName}`
+ * Signatures are hex-encoded HMAC-SHA256.
+ *
+ * @param signature - Hex-encoded signature
+ * @param timestamp - Unix timestamp string (seconds)
+ * @param userDiscordId - Discord user ID
+ * @param userName - Discord username
+ * @param secret - The signing secret
+ * @param options - Verification options
+ * @returns true if signature is valid and not expired
+ *
+ * @example
+ * ```typescript
+ * const isValid = await verifyBotSignature(
+ *   request.headers.get('X-Signature'),
+ *   request.headers.get('X-Timestamp'),
+ *   request.headers.get('X-User-Id'),
+ *   request.headers.get('X-User-Name'),
+ *   env.BOT_SIGNING_SECRET
+ * );
+ * ```
+ */
+export async function verifyBotSignature(
+  signature: string | undefined,
+  timestamp: string | undefined,
+  userDiscordId: string | undefined,
+  userName: string | undefined,
+  secret: string,
+  options: BotSignatureOptions = {}
+): Promise<boolean> {
+  const { maxAgeMs = 5 * 60 * 1000, clockSkewMs = 60 * 1000 } = options;
+
+  // Validate required fields
+  if (!signature || !timestamp || !userDiscordId || !userName) {
+    return false;
+  }
+
+  // Validate timestamp format
+  const timestampNum = parseInt(timestamp, 10);
+  if (isNaN(timestampNum)) {
+    return false;
+  }
+
+  // Check timestamp age (with clock skew tolerance)
+  const now = Date.now();
+  const signatureTime = timestampNum * 1000; // Convert to milliseconds
+  const age = now - signatureTime;
+
+  // Reject if too old
+  if (age > maxAgeMs) {
+    return false;
+  }
+
+  // Reject if too far in the future (clock skew protection)
+  if (signatureTime > now + clockSkewMs) {
+    return false;
+  }
+
+  // Verify the signature
+  const message = `${timestamp}:${userDiscordId}:${userName}`;
+  return hmacVerifyHex(message, signature, secret);
+}