@xivdyetools/auth 1.0.0

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * @xivdyetools/auth
+ *
+ * Shared authentication utilities for the xivdyetools ecosystem.
+ *
+ * @example
+ * ```typescript
+ * import { verifyJWT, verifyDiscordRequest, timingSafeEqual } from '@xivdyetools/auth';
+ *
+ * // Verify JWT
+ * const payload = await verifyJWT(token, env.JWT_SECRET);
+ *
+ * // Verify Discord request
+ * const result = await verifyDiscordRequest(request, env.DISCORD_PUBLIC_KEY);
+ *
+ * // Timing-safe comparison
+ * const isValid = await timingSafeEqual(provided, expected);
+ * ```
+ *
+ * @module @xivdyetools/auth
+ */
+
+// JWT utilities
+export {
+  verifyJWT,
+  verifyJWTSignatureOnly,
+  decodeJWT,
+  isJWTExpired,
+  getJWTTimeToExpiry,
+  type JWTPayload,
+} from './jwt.js';
+
+// HMAC utilities
+export {
+  createHmacKey,
+  hmacSign,
+  hmacSignHex,
+  hmacVerify,
+  hmacVerifyHex,
+  verifyBotSignature,
+  type BotSignatureOptions,
+} from './hmac.js';
+
+// Timing-safe utilities
+export { timingSafeEqual, timingSafeEqualBytes } from './timing.js';
+
+// Discord verification
+export {
+  verifyDiscordRequest,
+  unauthorizedResponse,
+  badRequestResponse,
+  type DiscordVerificationResult,
+  type DiscordVerifyOptions,
+} from './discord.js';

package/src/jwt.test.ts

@@ -0,0 +1,337 @@
+/**
+ * Tests for JWT Verification Utilities
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  decodeJWT,
+  verifyJWT,
+  verifyJWTSignatureOnly,
+  isJWTExpired,
+  getJWTTimeToExpiry,
+  type JWTPayload,
+} from './jwt.js';
+import { base64UrlEncode, base64UrlEncodeBytes } from '@xivdyetools/crypto';
+import { createHmacKey } from './hmac.js';
+
+// Helper to create a valid JWT for testing
+async function createTestJWT(
+  payload: JWTPayload,
+  secret: string,
+  algorithm = 'HS256'
+): Promise<string> {
+  const header = { alg: algorithm, typ: 'JWT' };
+  const headerB64 = base64UrlEncode(JSON.stringify(header));
+  const payloadB64 = base64UrlEncode(JSON.stringify(payload));
+
+  const signatureInput = `${headerB64}.${payloadB64}`;
+  const key = await createHmacKey(secret, 'sign');
+  const signature = await crypto.subtle.sign(
+    'HMAC',
+    key,
+    new TextEncoder().encode(signatureInput)
+  );
+  const signatureB64 = base64UrlEncodeBytes(new Uint8Array(signature));
+
+  return `${headerB64}.${payloadB64}.${signatureB64}`;
+}
+
+describe('jwt.ts', () => {
+  const secret = 'test-jwt-secret-key-123';
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2024-01-15T12:00:00Z'));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('decodeJWT', () => {
+    it('should decode a valid JWT payload', async () => {
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        type: 'access',
+        username: 'testuser',
+      };
+      const token = await createTestJWT(payload, secret);
+
+      const decoded = decodeJWT(token);
+
+      expect(decoded).not.toBeNull();
+      expect(decoded?.sub).toBe('123456789');
+      expect(decoded?.type).toBe('access');
+      expect(decoded?.username).toBe('testuser');
+    });
+
+    it('should return null for invalid token format', () => {
+      const decoded = decodeJWT('not.a.valid.token.format');
+      expect(decoded).toBeNull();
+    });
+
+    it('should return null for malformed base64', () => {
+      const decoded = decodeJWT('not-base64.also-not.valid');
+      expect(decoded).toBeNull();
+    });
+
+    it('should return null for invalid JSON payload', () => {
+      const headerB64 = base64UrlEncode('{"alg":"HS256","typ":"JWT"}');
+      const payloadB64 = base64UrlEncodeBytes(
+        new TextEncoder().encode('not-json')
+      );
+      const decoded = decodeJWT(`${headerB64}.${payloadB64}.signature`);
+      expect(decoded).toBeNull();
+    });
+  });
+
+  describe('verifyJWT', () => {
+    it('should verify a valid token', async () => {
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        type: 'access',
+      };
+      const token = await createTestJWT(payload, secret);
+
+      const verified = await verifyJWT(token, secret);
+
+      expect(verified).not.toBeNull();
+      expect(verified?.sub).toBe('123456789');
+    });
+
+    it('should return null for expired token', async () => {
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000) - 7200,
+        exp: Math.floor(Date.now() / 1000) - 3600, // Expired 1 hour ago
+        type: 'access',
+      };
+      const token = await createTestJWT(payload, secret);
+
+      const verified = await verifyJWT(token, secret);
+
+      expect(verified).toBeNull();
+    });
+
+    it('should return null for wrong secret', async () => {
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        type: 'access',
+      };
+      const token = await createTestJWT(payload, secret);
+
+      const verified = await verifyJWT(token, 'wrong-secret');
+
+      expect(verified).toBeNull();
+    });
+
+    it('should return null for tampered payload', async () => {
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        type: 'access',
+      };
+      const token = await createTestJWT(payload, secret);
+
+      // Tamper with the payload
+      const parts = token.split('.');
+      const tamperedPayload = { ...payload, sub: 'tampered-id' };
+      parts[1] = base64UrlEncode(JSON.stringify(tamperedPayload));
+      const tamperedToken = parts.join('.');
+
+      const verified = await verifyJWT(tamperedToken, secret);
+
+      expect(verified).toBeNull();
+    });
+
+    it('should reject non-HS256 algorithm (security)', async () => {
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        type: 'access',
+      };
+      // Create token with different algorithm in header
+      const token = await createTestJWT(payload, secret, 'none');
+
+      const verified = await verifyJWT(token, secret);
+
+      expect(verified).toBeNull();
+    });
+
+    it('should return null for malformed token', async () => {
+      const verified = await verifyJWT('not-a-jwt', secret);
+      expect(verified).toBeNull();
+    });
+
+    it('should handle token without exp claim', async () => {
+      // Create a token without exp - should still work if signature is valid
+      const header = { alg: 'HS256', typ: 'JWT' };
+      const payload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000),
+        type: 'access',
+      };
+      const headerB64 = base64UrlEncode(JSON.stringify(header));
+      const payloadB64 = base64UrlEncode(JSON.stringify(payload));
+      const signatureInput = `${headerB64}.${payloadB64}`;
+      const key = await createHmacKey(secret, 'sign');
+      const signature = await crypto.subtle.sign(
+        'HMAC',
+        key,
+        new TextEncoder().encode(signatureInput)
+      );
+      const signatureB64 = base64UrlEncodeBytes(new Uint8Array(signature));
+      const token = `${headerB64}.${payloadB64}.${signatureB64}`;
+
+      const verified = await verifyJWT(token, secret);
+
+      // Should pass since no exp means no expiration check
+      expect(verified).not.toBeNull();
+    });
+  });
+
+  describe('verifyJWTSignatureOnly', () => {
+    it('should verify signature even for expired token', async () => {
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000) - 7200,
+        exp: Math.floor(Date.now() / 1000) - 3600, // Expired
+        type: 'refresh',
+      };
+      const token = await createTestJWT(payload, secret);
+
+      const verified = await verifyJWTSignatureOnly(token, secret);
+
+      expect(verified).not.toBeNull();
+      expect(verified?.sub).toBe('123456789');
+    });
+
+    it('should return null for invalid signature', async () => {
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        type: 'refresh',
+      };
+      const token = await createTestJWT(payload, secret);
+
+      const verified = await verifyJWTSignatureOnly(token, 'wrong-secret');
+
+      expect(verified).toBeNull();
+    });
+
+    it('should reject non-HS256 algorithm (security)', async () => {
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        type: 'refresh',
+      };
+      const token = await createTestJWT(payload, secret, 'HS384');
+
+      const verified = await verifyJWTSignatureOnly(token, secret);
+
+      expect(verified).toBeNull();
+    });
+
+    it('should respect maxAgeMs parameter', async () => {
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000) - 7200, // 2 hours ago
+        exp: Math.floor(Date.now() / 1000) - 3600,
+        type: 'refresh',
+      };
+      const token = await createTestJWT(payload, secret);
+
+      // Should fail with 1 hour max age
+      const verified = await verifyJWTSignatureOnly(token, secret, 3600 * 1000);
+
+      expect(verified).toBeNull();
+    });
+
+    it('should accept token within maxAgeMs', async () => {
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000) - 1800, // 30 minutes ago
+        exp: Math.floor(Date.now() / 1000) - 900, // Expired 15 minutes ago
+        type: 'refresh',
+      };
+      const token = await createTestJWT(payload, secret);
+
+      // Should pass with 1 hour max age
+      const verified = await verifyJWTSignatureOnly(token, secret, 3600 * 1000);
+
+      expect(verified).not.toBeNull();
+    });
+  });
+
+  describe('isJWTExpired', () => {
+    it('should return false for valid non-expired token', async () => {
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        type: 'access',
+      };
+      const token = await createTestJWT(payload, secret);
+
+      expect(isJWTExpired(token)).toBe(false);
+    });
+
+    it('should return true for expired token', async () => {
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000) - 7200,
+        exp: Math.floor(Date.now() / 1000) - 3600,
+        type: 'access',
+      };
+      const token = await createTestJWT(payload, secret);
+
+      expect(isJWTExpired(token)).toBe(true);
+    });
+
+    it('should return true for malformed token', () => {
+      expect(isJWTExpired('not-a-jwt')).toBe(true);
+    });
+  });
+
+  describe('getJWTTimeToExpiry', () => {
+    it('should return correct time to expiry', async () => {
+      const expiresIn = 3600; // 1 hour
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + expiresIn,
+        type: 'access',
+      };
+      const token = await createTestJWT(payload, secret);
+
+      const ttl = getJWTTimeToExpiry(token);
+
+      expect(ttl).toBe(expiresIn);
+    });
+
+    it('should return 0 for expired token', async () => {
+      const payload: JWTPayload = {
+        sub: '123456789',
+        iat: Math.floor(Date.now() / 1000) - 7200,
+        exp: Math.floor(Date.now() / 1000) - 3600,
+        type: 'access',
+      };
+      const token = await createTestJWT(payload, secret);
+
+      expect(getJWTTimeToExpiry(token)).toBe(0);
+    });
+
+    it('should return 0 for malformed token', () => {
+      expect(getJWTTimeToExpiry('not-a-jwt')).toBe(0);
+    });
+  });
+});

package/src/jwt.ts

@@ -0,0 +1,267 @@
+/**
+ * JWT Verification Utilities
+ *
+ * Provides JWT verification using HMAC-SHA256 (HS256) with the Web Crypto API.
+ * Intentionally does NOT include JWT creation - that stays in the oauth service.
+ *
+ * Security features:
+ * - Algorithm validation (rejects non-HS256 tokens)
+ * - Expiration checking
+ * - Timing-safe signature comparison
+ *
+ * @module jwt
+ */
+
+import {
+  base64UrlEncodeBytes,
+  base64UrlDecode,
+  base64UrlDecodeBytes,
+} from '@xivdyetools/crypto';
+import { createHmacKey } from './hmac.js';
+
+/**
+ * JWT payload structure
+ *
+ * Re-exported from @xivdyetools/types for convenience.
+ * Consumers should import from here rather than directly from types.
+ */
+export interface JWTPayload {
+  /** Subject - Discord user ID */
+  sub: string;
+  /** Issued at timestamp (seconds) */
+  iat: number;
+  /** Expiration timestamp (seconds) */
+  exp: number;
+  /** Token type: 'access' or 'refresh' */
+  type: 'access' | 'refresh';
+  /** Discord username */
+  username?: string;
+  /** Discord avatar hash */
+  avatar?: string | null;
+}
+
+/**
+ * JWT header structure
+ */
+interface JWTHeader {
+  alg: string;
+  typ: string;
+}
+
+/**
+ * Decode a JWT without verifying the signature.
+ *
+ * WARNING: Only use this for debugging or when you'll verify separately.
+ * For production use, always use `verifyJWT()`.
+ *
+ * @param token - The JWT string
+ * @returns Decoded payload or null if malformed
+ *
+ * @example
+ * ```typescript
+ * const payload = decodeJWT(token);
+ * console.log('Token expires:', new Date(payload.exp * 1000));
+ * ```
+ */
+export function decodeJWT(token: string): JWTPayload | null {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+      return null;
+    }
+
+    const payloadJson = base64UrlDecode(parts[1]);
+    return JSON.parse(payloadJson) as JWTPayload;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Verify a JWT and return the payload if valid.
+ *
+ * Performs full verification:
+ * 1. Validates token structure (3 parts)
+ * 2. Validates algorithm is HS256 (prevents confusion attacks)
+ * 3. Verifies HMAC-SHA256 signature
+ * 4. Checks expiration time
+ *
+ * @param token - The JWT string
+ * @param secret - The HMAC secret used to sign the token
+ * @returns Verified payload or null if invalid/expired
+ *
+ * @example
+ * ```typescript
+ * const payload = await verifyJWT(token, env.JWT_SECRET);
+ * if (!payload) {
+ *   return new Response('Unauthorized', { status: 401 });
+ * }
+ * ```
+ */
+export async function verifyJWT(
+  token: string,
+  secret: string
+): Promise<JWTPayload | null> {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+      return null;
+    }
+
+    const [headerB64, payloadB64, signatureB64] = parts;
+
+    // Decode and validate header
+    const headerJson = base64UrlDecode(headerB64);
+    const header: JWTHeader = JSON.parse(headerJson);
+
+    // SECURITY: Reject non-HS256 algorithms (prevents algorithm confusion attacks)
+    if (header.alg !== 'HS256') {
+      return null;
+    }
+
+    // Verify signature
+    const signatureInput = `${headerB64}.${payloadB64}`;
+    const key = await createHmacKey(secret, 'both');
+    const encoder = new TextEncoder();
+
+    const expectedSignature = await crypto.subtle.sign(
+      'HMAC',
+      key,
+      encoder.encode(signatureInput)
+    );
+    const expectedSignatureB64 = base64UrlEncodeBytes(
+      new Uint8Array(expectedSignature)
+    );
+
+    // Compare signatures (using string comparison - both are base64url)
+    if (signatureB64 !== expectedSignatureB64) {
+      return null;
+    }
+
+    // Decode payload
+    const payloadJson = base64UrlDecode(payloadB64);
+    const payload: JWTPayload = JSON.parse(payloadJson);
+
+    // Check expiration
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.exp && payload.exp < now) {
+      return null;
+    }
+
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Verify JWT signature only, ignoring expiration.
+ *
+ * Used for refresh tokens where we want to verify authenticity
+ * but allow some grace period past expiration.
+ *
+ * @param token - The JWT string
+ * @param secret - The HMAC secret
+ * @param maxAgeMs - Optional maximum age in milliseconds (from iat)
+ * @returns Payload if signature valid, null otherwise
+ *
+ * @example
+ * ```typescript
+ * // Allow refresh tokens up to 7 days old
+ * const payload = await verifyJWTSignatureOnly(
+ *   refreshToken,
+ *   env.JWT_SECRET,
+ *   7 * 24 * 60 * 60 * 1000
+ * );
+ * ```
+ */
+export async function verifyJWTSignatureOnly(
+  token: string,
+  secret: string,
+  maxAgeMs?: number
+): Promise<JWTPayload | null> {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+      return null;
+    }
+
+    const [headerB64, payloadB64, signatureB64] = parts;
+
+    // Decode and validate header
+    const headerJson = base64UrlDecode(headerB64);
+    const header: JWTHeader = JSON.parse(headerJson);
+
+    // SECURITY: Still reject non-HS256 algorithms
+    if (header.alg !== 'HS256') {
+      return null;
+    }
+
+    // Verify signature
+    const signatureInput = `${headerB64}.${payloadB64}`;
+    const key = await createHmacKey(secret, 'both');
+    const encoder = new TextEncoder();
+
+    const expectedSignature = await crypto.subtle.sign(
+      'HMAC',
+      key,
+      encoder.encode(signatureInput)
+    );
+    const expectedSignatureB64 = base64UrlEncodeBytes(
+      new Uint8Array(expectedSignature)
+    );
+
+    if (signatureB64 !== expectedSignatureB64) {
+      return null;
+    }
+
+    // Decode payload
+    const payloadJson = base64UrlDecode(payloadB64);
+    const payload: JWTPayload = JSON.parse(payloadJson);
+
+    // Check max age if specified
+    if (maxAgeMs !== undefined && payload.iat) {
+      const now = Date.now();
+      const tokenAge = now - payload.iat * 1000;
+      if (tokenAge > maxAgeMs) {
+        return null;
+      }
+    }
+
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a JWT is expired without full verification.
+ *
+ * Useful for quick checks before making API calls.
+ *
+ * @param token - The JWT string
+ * @returns true if token is expired or malformed
+ */
+export function isJWTExpired(token: string): boolean {
+  const payload = decodeJWT(token);
+  if (!payload || !payload.exp) {
+    return true;
+  }
+  const now = Math.floor(Date.now() / 1000);
+  return payload.exp < now;
+}
+
+/**
+ * Get time until JWT expiration.
+ *
+ * @param token - The JWT string
+ * @returns Seconds until expiration, or 0 if expired/invalid
+ */
+export function getJWTTimeToExpiry(token: string): number {
+  const payload = decodeJWT(token);
+  if (!payload || !payload.exp) {
+    return 0;
+  }
+  const now = Math.floor(Date.now() / 1000);
+  return Math.max(0, payload.exp - now);
+}