@forjio/engine-auth 0.1.0

package/src/__tests__/middleware.test.ts

@@ -0,0 +1,220 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createMockReq, createMockRes, createMockNext } from './helpers/express-mock';
+import { authenticateToken, requireApiKey, requireRole } from '../middleware';
+import { signAccessToken } from '../jwt';
+import { AuthConfig, ApiKey } from '../types';
+
+const TEST_CONFIG: AuthConfig = {
+  jwtSecret: 'test-middleware-secret',
+  jwtRefreshSecret: 'test-middleware-refresh-secret',
+};
+
+const TEST_PAYLOAD = {
+  userId: 'user-789',
+  email: 'mw@example.com',
+  role: 'admin',
+  subscriptionTier: 'enterprise',
+};
+
+describe('authenticateToken', () => {
+  const middleware = authenticateToken(TEST_CONFIG);
+
+  it('should call next() with valid Bearer token', () => {
+    const token = signAccessToken(TEST_PAYLOAD, TEST_CONFIG);
+    const req = createMockReq({
+      headers: { authorization: `Bearer ${token}` },
+    });
+    const res = createMockRes();
+    const next = createMockNext();
+
+    middleware(req, res, next);
+
+    expect(next).toHaveBeenCalled();
+    expect(res.status).not.toHaveBeenCalled();
+  });
+
+  it('should set req.authUser with payload', () => {
+    const token = signAccessToken(TEST_PAYLOAD, TEST_CONFIG);
+    const req = createMockReq({
+      headers: { authorization: `Bearer ${token}` },
+    });
+    const res = createMockRes();
+    const next = createMockNext();
+
+    middleware(req, res, next);
+
+    expect(req.authUser).toBeDefined();
+    expect(req.authUser.userId).toBe('user-789');
+    expect(req.authUser.email).toBe('mw@example.com');
+    expect(req.authUser.role).toBe('admin');
+  });
+
+  it('should return 401 for missing Authorization header', () => {
+    const req = createMockReq({ headers: {} });
+    const res = createMockRes();
+    const next = createMockNext();
+
+    middleware(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({ error: expect.any(String) })
+    );
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('should return 401 for invalid token', () => {
+    const req = createMockReq({
+      headers: { authorization: 'Bearer invalid-token-here' },
+    });
+    const res = createMockRes();
+    const next = createMockNext();
+
+    middleware(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('should return 401 for Authorization header without Bearer prefix', () => {
+    const token = signAccessToken(TEST_PAYLOAD, TEST_CONFIG);
+    const req = createMockReq({
+      headers: { authorization: token },
+    });
+    const res = createMockRes();
+    const next = createMockNext();
+
+    middleware(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+});
+
+describe('requireApiKey', () => {
+  const mockApiKey: ApiKey = {
+    id: 'key-1',
+    key: 'ek_hashed',
+    userId: 'user-1',
+    productSlug: 'portal',
+    scopes: ['read', 'write'],
+    expiresAt: null,
+    lastUsedAt: null,
+    createdAt: new Date(),
+  };
+
+  it('should call next() when X-API-Key is valid', async () => {
+    const validateKey = vi.fn().mockResolvedValue(mockApiKey);
+    const middleware = requireApiKey(validateKey);
+
+    const req = createMockReq({
+      headers: { 'x-api-key': 'ek_some_key' },
+    });
+    const res = createMockRes();
+    const next = createMockNext();
+
+    await middleware(req, res, next);
+
+    expect(validateKey).toHaveBeenCalledWith('ek_some_key');
+    expect(next).toHaveBeenCalled();
+    expect(req.apiKey).toEqual(mockApiKey);
+  });
+
+  it('should return 401 when no API key provided', async () => {
+    const validateKey = vi.fn();
+    const middleware = requireApiKey(validateKey);
+
+    const req = createMockReq({ headers: {} });
+    const res = createMockRes();
+    const next = createMockNext();
+
+    await middleware(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('should return 401 when API key validation fails', async () => {
+    const validateKey = vi.fn().mockResolvedValue(null);
+    const middleware = requireApiKey(validateKey);
+
+    const req = createMockReq({
+      headers: { 'x-api-key': 'ek_invalid' },
+    });
+    const res = createMockRes();
+    const next = createMockNext();
+
+    await middleware(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('should return 401 for expired API key', async () => {
+    const expiredKey: ApiKey = {
+      ...mockApiKey,
+      expiresAt: new Date('2020-01-01'),
+    };
+    const validateKey = vi.fn().mockResolvedValue(expiredKey);
+    const middleware = requireApiKey(validateKey);
+
+    const req = createMockReq({
+      headers: { 'x-api-key': 'ek_expired' },
+    });
+    const res = createMockRes();
+    const next = createMockNext();
+
+    await middleware(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+});
+
+describe('requireRole', () => {
+  it('should allow matching role', () => {
+    const middleware = requireRole('admin');
+    const req = createMockReq({ authUser: { role: 'admin' } });
+    const res = createMockRes();
+    const next = createMockNext();
+
+    middleware(req, res, next);
+
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('should reject non-matching role', () => {
+    const middleware = requireRole('admin');
+    const req = createMockReq({ authUser: { role: 'user' } });
+    const res = createMockRes();
+    const next = createMockNext();
+
+    middleware(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('should accept any of multiple allowed roles', () => {
+    const middleware = requireRole('admin', 'moderator');
+    const req = createMockReq({ authUser: { role: 'moderator' } });
+    const res = createMockRes();
+    const next = createMockNext();
+
+    middleware(req, res, next);
+
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('should return 401 when no authUser is present', () => {
+    const middleware = requireRole('admin');
+    const req = createMockReq({});
+    const res = createMockRes();
+    const next = createMockNext();
+
+    middleware(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/session.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { RedisMock } from './helpers/redis-mock';
+import { SessionData } from '../types';
+
+// Mock ioredis before importing session module
+const redisMock = new RedisMock();
+vi.mock('ioredis', () => ({
+  default: vi.fn(() => redisMock),
+}));
+
+// Import after mock is set up
+import { createSessionStore, SessionStore } from '../session';
+
+const TEST_SESSION: SessionData = {
+  userId: 'user-456',
+  email: 'session@example.com',
+  role: 'user',
+  productSlug: 'portal',
+  expiresAt: Date.now() + 3600_000, // 1 hour from now
+};
+
+describe('session store', () => {
+  let store: SessionStore;
+
+  beforeEach(() => {
+    redisMock.clear();
+    store = createSessionStore('redis://localhost:6379');
+  });
+
+  describe('create', () => {
+    it('should create session and return session ID', async () => {
+      const sessionId = await store.create(TEST_SESSION);
+
+      expect(sessionId).toBeDefined();
+      expect(typeof sessionId).toBe('string');
+      expect(sessionId.length).toBeGreaterThan(0);
+    });
+
+    it('should store session data retrievable by ID', async () => {
+      const sessionId = await store.create(TEST_SESSION);
+      const retrieved = await store.get(sessionId);
+
+      expect(retrieved).not.toBeNull();
+      expect(retrieved!.userId).toBe('user-456');
+      expect(retrieved!.email).toBe('session@example.com');
+      expect(retrieved!.role).toBe('user');
+    });
+  });
+
+  describe('get', () => {
+    it('should return session data for valid ID', async () => {
+      const sessionId = await store.create(TEST_SESSION);
+      const session = await store.get(sessionId);
+
+      expect(session).not.toBeNull();
+      expect(session!.userId).toBe(TEST_SESSION.userId);
+      expect(session!.productSlug).toBe(TEST_SESSION.productSlug);
+    });
+
+    it('should return null for non-existent ID', async () => {
+      const session = await store.get('non-existent-id');
+      expect(session).toBeNull();
+    });
+
+    it('should return null for logically expired session', async () => {
+      const expiredSession: SessionData = {
+        ...TEST_SESSION,
+        expiresAt: Date.now() - 1000, // already expired
+      };
+
+      const sessionId = await store.create(expiredSession);
+      const session = await store.get(sessionId);
+
+      expect(session).toBeNull();
+    });
+  });
+
+  describe('destroy', () => {
+    it('should remove session', async () => {
+      const sessionId = await store.create(TEST_SESSION);
+
+      // Verify it exists first
+      expect(await store.get(sessionId)).not.toBeNull();
+
+      await store.destroy(sessionId);
+
+      expect(await store.get(sessionId)).toBeNull();
+    });
+  });
+
+  describe('destroyAllForUser', () => {
+    it('should remove all sessions for a user', async () => {
+      const id1 = await store.create(TEST_SESSION);
+      const id2 = await store.create({ ...TEST_SESSION, productSlug: 'other' });
+
+      // Both should exist
+      expect(await store.get(id1)).not.toBeNull();
+      expect(await store.get(id2)).not.toBeNull();
+
+      await store.destroyAllForUser(TEST_SESSION.userId);
+
+      expect(await store.get(id1)).toBeNull();
+      expect(await store.get(id2)).toBeNull();
+    });
+
+    it('should not affect other users sessions', async () => {
+      const id1 = await store.create(TEST_SESSION);
+      const otherSession: SessionData = {
+        ...TEST_SESSION,
+        userId: 'other-user',
+      };
+      const id2 = await store.create(otherSession);
+
+      await store.destroyAllForUser(TEST_SESSION.userId);
+
+      expect(await store.get(id1)).toBeNull();
+      expect(await store.get(id2)).not.toBeNull();
+    });
+  });
+});

package/src/api-keys.ts

@@ -0,0 +1,56 @@
+import crypto from 'crypto';
+
+const API_KEY_PREFIX = 'ek_';
+const API_KEY_BYTES = 32;
+const EXPECTED_KEY_LENGTH = API_KEY_PREFIX.length + API_KEY_BYTES * 2; // hex encoding
+
+export interface CreateApiKeyInput {
+  userId: string;
+  productSlug: string;
+  scopes: string[];
+  expiresAt?: Date | null;
+}
+
+export interface ApiKeyWithHash {
+  plainKey: string;
+  hashedKey: string;
+}
+
+/**
+ * Generates a new API key with the `ek_` prefix.
+ * Optionally accepts a custom prefix that replaces the default.
+ */
+export function generateApiKey(prefix?: string): string {
+  const keyPrefix = prefix || API_KEY_PREFIX;
+  const randomPart = crypto.randomBytes(API_KEY_BYTES).toString('hex');
+  return `${keyPrefix}${randomPart}`;
+}
+
+/**
+ * Creates a SHA-256 hash of an API key for secure storage.
+ * Only the hash should be persisted — never store the plain key.
+ */
+export function hashApiKey(key: string): string {
+  return crypto.createHash('sha256').update(key).digest('hex');
+}
+
+/**
+ * Validates that a key matches the expected `ek_` format and length.
+ */
+export function validateApiKeyFormat(key: string): boolean {
+  if (!key.startsWith(API_KEY_PREFIX)) return false;
+  if (key.length !== EXPECTED_KEY_LENGTH) return false;
+
+  // Verify the hex portion is valid
+  const hexPart = key.slice(API_KEY_PREFIX.length);
+  return /^[a-f0-9]+$/.test(hexPart);
+}
+
+/**
+ * Generates a new API key and returns both the plain key and its hash.
+ */
+export function createApiKeyPair(prefix?: string): ApiKeyWithHash {
+  const plainKey = generateApiKey(prefix);
+  const hashedKey = hashApiKey(plainKey);
+  return { plainKey, hashedKey };
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+// Types
+export type {
+  EngineUser,
+  ApiKey,
+  SessionData,
+  JwtPayload,
+  AuthConfig,
+} from './types';
+
+// JWT utilities
+export {
+  signAccessToken,
+  signRefreshToken,
+  signRememberMeToken,
+  verifyAccessToken,
+  verifyRefreshToken,
+} from './jwt';
+
+// Session store
+export { createSessionStore } from './session';
+export type { SessionStore } from './session';
+
+// API key utilities
+export {
+  generateApiKey,
+  hashApiKey,
+  validateApiKeyFormat,
+  createApiKeyPair,
+} from './api-keys';
+export type { CreateApiKeyInput, ApiKeyWithHash } from './api-keys';
+
+// OAuth strategies
+export {
+  configureGoogleStrategy,
+  configureGithubStrategy,
+  setupOAuth,
+} from './oauth';
+export type { OAuthProfile, FindOrCreateUser } from './oauth';
+
+// Express middleware
+export {
+  authenticateToken,
+  requireApiKey,
+  requireProduct,
+  requireRole,
+} from './middleware';

package/src/jwt.ts

@@ -0,0 +1,61 @@
+import jwt from 'jsonwebtoken';
+import { JwtPayload, AuthConfig } from './types';
+
+// Expiry values in seconds to satisfy jsonwebtoken's type requirements
+const DEFAULT_ACCESS_EXPIRY = 15 * 60; // 15 minutes
+const DEFAULT_REFRESH_EXPIRY = 7 * 24 * 60 * 60; // 7 days
+const REMEMBER_ME_EXPIRY = 30 * 24 * 60 * 60; // 30 days
+
+function parseExpiry(value: string | undefined, fallback: number): number {
+  if (!value) return fallback;
+  // Parse simple duration strings: "15m", "7d", "30d", "1h"
+  const match = value.match(/^(\d+)(s|m|h|d)$/);
+  if (!match) return fallback;
+  const num = parseInt(match[1], 10);
+  const unit = match[2];
+  switch (unit) {
+    case 's': return num;
+    case 'm': return num * 60;
+    case 'h': return num * 3600;
+    case 'd': return num * 86400;
+    default: return fallback;
+  }
+}
+
+export function signAccessToken(payload: JwtPayload, config: AuthConfig): string {
+  return jwt.sign(payload, config.jwtSecret, {
+    expiresIn: parseExpiry(config.jwtExpiresIn, DEFAULT_ACCESS_EXPIRY),
+  });
+}
+
+export function signRefreshToken(payload: JwtPayload, config: AuthConfig): string {
+  return jwt.sign(payload, config.jwtRefreshSecret, {
+    expiresIn: parseExpiry(config.jwtRefreshExpiresIn, DEFAULT_REFRESH_EXPIRY),
+  });
+}
+
+export function signRememberMeToken(payload: JwtPayload, config: AuthConfig): string {
+  return jwt.sign(payload, config.jwtRefreshSecret, {
+    expiresIn: REMEMBER_ME_EXPIRY,
+  });
+}
+
+export function verifyAccessToken(token: string, config: AuthConfig): JwtPayload {
+  const decoded = jwt.verify(token, config.jwtSecret) as jwt.JwtPayload & JwtPayload;
+  return {
+    userId: decoded.userId,
+    email: decoded.email,
+    role: decoded.role,
+    subscriptionTier: decoded.subscriptionTier,
+  };
+}
+
+export function verifyRefreshToken(token: string, config: AuthConfig): JwtPayload {
+  const decoded = jwt.verify(token, config.jwtRefreshSecret) as jwt.JwtPayload & JwtPayload;
+  return {
+    userId: decoded.userId,
+    email: decoded.email,
+    role: decoded.role,
+    subscriptionTier: decoded.subscriptionTier,
+  };
+}

package/src/middleware.ts

@@ -0,0 +1,113 @@
+import { Request, Response, NextFunction } from 'express';
+import { verifyAccessToken } from './jwt';
+import { AuthConfig, JwtPayload, ApiKey } from './types';
+
+// Extend Express Request to carry auth data via module augmentation
+declare module 'express-serve-static-core' {
+  interface Request {
+    authUser?: JwtPayload;
+    apiKey?: ApiKey;
+  }
+}
+
+/**
+ * Middleware that validates a Bearer token from the Authorization header.
+ * On success, attaches the decoded JwtPayload to `req.user`.
+ */
+export function authenticateToken(config: AuthConfig) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const authHeader = req.headers.authorization;
+
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      res.status(401).json({ error: 'Missing or invalid Authorization header' });
+      return;
+    }
+
+    const token = authHeader.slice(7);
+
+    try {
+      const payload = verifyAccessToken(token, config);
+      req.authUser = payload;
+      next();
+    } catch {
+      res.status(401).json({ error: 'Invalid or expired token' });
+    }
+  };
+}
+
+/**
+ * Middleware that validates an API key from the X-API-Key header.
+ * The `validateKey` callback should look up the hashed key in your DB.
+ */
+export function requireApiKey(
+  validateKey: (key: string) => Promise<ApiKey | null>
+) {
+  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    const apiKey = req.headers['x-api-key'] as string | undefined;
+
+    if (!apiKey) {
+      res.status(401).json({ error: 'Missing X-API-Key header' });
+      return;
+    }
+
+    try {
+      const keyRecord = await validateKey(apiKey);
+
+      if (!keyRecord) {
+        res.status(401).json({ error: 'Invalid API key' });
+        return;
+      }
+
+      // Check expiration
+      if (keyRecord.expiresAt && new Date(keyRecord.expiresAt) < new Date()) {
+        res.status(401).json({ error: 'API key has expired' });
+        return;
+      }
+
+      req.apiKey = keyRecord;
+      next();
+    } catch {
+      res.status(500).json({ error: 'Failed to validate API key' });
+    }
+  };
+}
+
+/**
+ * Middleware that ensures the API key is scoped to a specific product.
+ * Must be used after `requireApiKey`.
+ */
+export function requireProduct(productSlug: string) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    if (!req.apiKey) {
+      res.status(401).json({ error: 'No API key context' });
+      return;
+    }
+
+    if (req.apiKey.productSlug !== productSlug) {
+      res.status(403).json({ error: `API key not authorized for product: ${productSlug}` });
+      return;
+    }
+
+    next();
+  };
+}
+
+/**
+ * Middleware that restricts access to specific user roles.
+ * Must be used after `authenticateToken`.
+ */
+export function requireRole(...roles: string[]) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    if (!req.authUser) {
+      res.status(401).json({ error: 'Not authenticated' });
+      return;
+    }
+
+    if (!roles.includes(req.authUser.role)) {
+      res.status(403).json({ error: 'Insufficient permissions' });
+      return;
+    }
+
+    next();
+  };
+}