@onlineapps/service-common 1.0.19 → 1.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@onlineapps/service-common",
-  "version": "1.0.19",
-  "description": "Common utilities for both infrastructure services and business services",
+  "version": "1.1.1",
+  "description": "Common utilities for both infrastructure services and business services (JWT auth, Redis/Postgres clients, business errors, runtime config)",
   "main": "src/index.js",
   "scripts": {
     "test": "jest",
@@ -18,6 +18,7 @@
   "license": "MIT",
   "dependencies": {
     "@onlineapps/runtime-config": "1.0.2",
+    "jsonwebtoken": "^9.0.3",
     "nodemailer": "^6.9.8",
     "redis": "^4.6.0"
   },

package/src/index.js

@@ -45,6 +45,12 @@ const {
   businessErrorHandler,
   notFoundHandler
 } = require('./errors');
+const {
+  verifyAccessToken,
+  createJwtValidator,
+  extractTenantContext,
+  ROLES_VERSION_PREFIX
+} = require('./jwt');
 
 module.exports = {
   // Infrastructure readiness utilities (used by both infrastructure and business services)
@@ -85,7 +91,14 @@ module.exports = {
   isBusinessError,
   ERROR_TYPES,
   businessErrorHandler,
-  notFoundHandler
+  notFoundHandler,
+
+  // JWT validation utilities (shared across services that accept client HTTP/WS requests)
+  // See: docs/standards/JWT_AUTH.md
+  verifyAccessToken,
+  createJwtValidator,
+  extractTenantContext,
+  ROLES_VERSION_PREFIX
 };
 
 

package/src/jwt/createJwtValidator.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const { verifyAccessToken } = require('./verifyAccessToken');
+
+// See: docs/standards/JWT_AUTH.md §9.1 — forced refresh on role change
+const ROLES_VERSION_PREFIX = 'person:roles_version:';
+
+/**
+ * Create Express middleware that validates JWT Bearer tokens on incoming requests.
+ *
+ * On success: sets req.auth = { person_uuid, person_id, email, tenants }.
+ * On failure: responds with 401 JSON.
+ * Paths listed in excludePaths are skipped (transparent pass-through).
+ *
+ * @param {object} options
+ * @param {object} options.logger - Logger with .warn() method (required)
+ * @param {string[]} [options.excludePaths] - Paths to skip JWT validation
+ * @param {object} [options.redisClient] - Redis client for role version check (optional)
+ * @returns {Function} Express middleware (req, res, next)
+ */
+function createJwtValidator({ logger, excludePaths, redisClient }) {
+  if (!logger || typeof logger.warn !== 'function') {
+    throw new Error('[JWT] Logger is required - Expected object with warn() method');
+  }
+
+  const excluded = new Set(excludePaths || []);
+
+  return async function jwtValidator(req, res, next) {
+    if (excluded.has(req.path)) {
+      return next();
+    }
+
+    const authHeader = req.headers.authorization;
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return res.status(401).json({
+        error: 'Missing or invalid Authorization header - Expected: Bearer <token>'
+      });
+    }
+
+    const token = authHeader.slice(7);
+
+    try {
+      const decoded = verifyAccessToken(token);
+
+      if (redisClient && redisClient.isOpen && decoded.person_id) {
+        try {
+          const rolesVersion = await redisClient.get(`${ROLES_VERSION_PREFIX}${decoded.person_id}`);
+          if (rolesVersion) {
+            const versionTs = parseInt(rolesVersion, 10);
+            const tokenIat = decoded.iat * 1000;
+            if (!isNaN(versionTs) && tokenIat < versionTs) {
+              logger.warn('[JWT] Token stale — role changed after issuance', {
+                person_id: decoded.person_id,
+                token_iat: new Date(tokenIat).toISOString(),
+                roles_changed: new Date(versionTs).toISOString()
+              });
+              return res.status(401).json({
+                error: 'Token stale — your roles have changed, please refresh your access token',
+                code: 'TOKEN_STALE'
+              });
+            }
+          }
+        } catch (redisErr) {
+          logger.warn('[JWT] Redis role version check failed (non-blocking)', { error: redisErr.message });
+        }
+      }
+
+      req.auth = {
+        person_uuid: decoded.sub,
+        person_id: decoded.person_id,
+        email: decoded.email,
+        tenants: decoded.tenants || []
+      };
+
+      next();
+    } catch (err) {
+      if (err.name === 'TokenExpiredError') {
+        return res.status(401).json({ error: 'Token expired - refresh your access token' });
+      }
+      if (err.code === 'INVALID_TOKEN_TYPE') {
+        return res.status(401).json({ error: 'Invalid token type - Expected access token' });
+      }
+      logger.warn('[JWT] Token verification failed', { error: err.message });
+      return res.status(401).json({ error: 'Invalid token' });
+    }
+  };
+}
+
+module.exports = { createJwtValidator, ROLES_VERSION_PREFIX };

package/src/jwt/extractTenantContext.js

@@ -0,0 +1,82 @@
+'use strict';
+
+/**
+ * Extract tenant context from decoded JWT auth data and request headers.
+ *
+ * Pure function — no Express dependency. Callers (middleware) translate
+ * thrown errors into HTTP responses.
+ *
+ * Rules (per JWT_AUTH.md section 7):
+ *  - Single tenant: auto-pick, x-tenant-uuid header optional
+ *  - Multiple tenants: x-tenant-uuid header required
+ *  - workspace_id: required for direct API calls (x-workspace-id header),
+ *    optional for workflow submission (workspace is per-step in cookbook)
+ *
+ * @param {object} auth - req.auth from createJwtValidator: { person_uuid, person_id, email, tenants }
+ * @param {object} headers - HTTP request headers (lowercase keys)
+ * @param {object} [options] - { requireWorkspace: true } — set false for workflow submission
+ * @returns {object} { tenant_id, tenant_uuid, workspace_id, person_id, person_uuid, role }
+ * @throws {Error} with .statusCode = 400, 401, or 403
+ */
+// See: docs/standards/tenant-context-contract.md
+function extractTenantContext(auth, headers, options) {
+  const { requireWorkspace = true } = options || {};
+
+  if (!auth || !Array.isArray(auth.tenants)) {
+    const err = new Error('[TenantContext] Missing auth data - Expected auth object with tenants array');
+    err.statusCode = 401;
+    throw err;
+  }
+
+  const tenantUuid = headers['x-tenant-uuid'];
+  const rawWorkspaceId = headers['x-workspace-id'];
+
+  let workspaceId = null;
+  if (rawWorkspaceId) {
+    workspaceId = parseInt(rawWorkspaceId, 10);
+    if (isNaN(workspaceId) || workspaceId < 1) {
+      const err = new Error(`[TenantContext] Invalid x-workspace-id '${rawWorkspaceId}' - must be a positive integer`);
+      err.statusCode = 400;
+      throw err;
+    }
+  } else if (requireWorkspace) {
+    const err = new Error('[TenantContext] Missing x-workspace-id header - workspace is required for direct API calls');
+    err.statusCode = 400;
+    throw err;
+  }
+
+  if (tenantUuid) {
+    const membership = auth.tenants.find(t => t.tenant_uuid === tenantUuid);
+    if (!membership) {
+      const err = new Error('Access denied - No membership for specified tenant');
+      err.statusCode = 403;
+      throw err;
+    }
+    return {
+      tenant_id: membership.tenant_id,
+      tenant_uuid: membership.tenant_uuid,
+      workspace_id: workspaceId,
+      person_id: auth.person_id,
+      person_uuid: auth.person_uuid,
+      role: membership.role
+    };
+  }
+
+  if (auth.tenants.length === 1) {
+    const t = auth.tenants[0];
+    return {
+      tenant_id: t.tenant_id,
+      tenant_uuid: t.tenant_uuid,
+      workspace_id: workspaceId,
+      person_id: auth.person_id,
+      person_uuid: auth.person_uuid,
+      role: t.role
+    };
+  }
+
+  const err = new Error('Missing tenant context - Provide x-tenant-uuid header (multiple tenants available)');
+  err.statusCode = 400;
+  throw err;
+}
+
+module.exports = { extractTenantContext };

package/src/jwt/index.js

@@ -0,0 +1,12 @@
+'use strict';
+
+const { verifyAccessToken } = require('./verifyAccessToken');
+const { createJwtValidator, ROLES_VERSION_PREFIX } = require('./createJwtValidator');
+const { extractTenantContext } = require('./extractTenantContext');
+
+module.exports = {
+  verifyAccessToken,
+  createJwtValidator,
+  extractTenantContext,
+  ROLES_VERSION_PREFIX
+};

package/src/jwt/verifyAccessToken.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const jwt = require('jsonwebtoken');
+
+const ISSUER = 'oa-auth';
+const MIN_SECRET_LENGTH = 16;
+
+/**
+ * Resolve JWT_SECRET from environment. Fail-fast on missing/insecure value.
+ * @returns {string}
+ */
+function getJwtSecret() {
+  const secret = process.env.JWT_SECRET;
+  if (!secret || secret.length < MIN_SECRET_LENGTH) {
+    throw new Error(
+      `[JWT] Missing or insecure JWT_SECRET - Expected env var with at least ${MIN_SECRET_LENGTH} characters`
+    );
+  }
+  return secret;
+}
+
+/**
+ * Verify and decode an OA Drive access token.
+ *
+ * Validates: signature (HMAC-SHA256), issuer ('oa-auth'), expiry, type ('access').
+ * Returns the full decoded payload on success.
+ * Throws on any validation failure — callers decide how to handle.
+ *
+ * @param {string} token - Raw JWT string (without "Bearer " prefix)
+ * @returns {object} Decoded payload: { sub, person_id, email, tenants, type, iss, iat, exp }
+ * @throws {Error} TokenExpiredError, JsonWebTokenError, or type mismatch
+ */
+function verifyAccessToken(token) {
+  if (!token || typeof token !== 'string') {
+    throw new Error('[JWT] Token is required - Expected non-empty string');
+  }
+
+  const secret = getJwtSecret();
+  const decoded = jwt.verify(token, secret, { issuer: ISSUER });
+
+  if (decoded.type !== 'access') {
+    const err = new Error(`[JWT] Invalid token type - Expected 'access', got '${decoded.type}'`);
+    err.code = 'INVALID_TOKEN_TYPE';
+    throw err;
+  }
+
+  return decoded;
+}
+
+module.exports = { verifyAccessToken, getJwtSecret, ISSUER, MIN_SECRET_LENGTH };

package/tests/unit/BusinessError.test.js

@@ -1,171 +0,0 @@
-'use strict';
-
-const {
-  BusinessError,
-  NotFoundError,
-  ValidationError,
-  ConflictError,
-  BusinessRuleError,
-  AuthorizationError,
-  ServiceUnavailableError,
-  isBusinessError,
-  businessErrorHandler,
-  notFoundHandler
-} = require('../../src/errors');
-
-describe('BusinessError hierarchy', () => {
-  test('BusinessError has correct defaults', () => {
-    const err = new BusinessError('Something went wrong');
-    expect(err).toBeInstanceOf(Error);
-    expect(err).toBeInstanceOf(BusinessError);
-    expect(err.name).toBe('BusinessError');
-    expect(err.message).toBe('Something went wrong');
-    expect(err.statusCode).toBe(500);
-    expect(err.errorCode).toBe('INTERNAL_ERROR');
-    expect(err.type).toBe('BUSINESS');
-    expect(err.details).toEqual([]);
-  });
-
-  test('NotFoundError sets 404', () => {
-    const err = new NotFoundError('Document not found', {
-      details: ['UUID abc123 does not exist'],
-      operation: 'getDocument'
-    });
-    expect(err).toBeInstanceOf(BusinessError);
-    expect(err.statusCode).toBe(404);
-    expect(err.errorCode).toBe('RESOURCE_NOT_FOUND');
-    expect(err.type).toBe('BUSINESS');
-    expect(err.details).toEqual(['UUID abc123 does not exist']);
-    expect(err.operation).toBe('getDocument');
-  });
-
-  test('ValidationError sets 400', () => {
-    const err = new ValidationError('Invalid input', { details: ['field X is required'] });
-    expect(err.statusCode).toBe(400);
-    expect(err.errorCode).toBe('VALIDATION_FAILED');
-    expect(err.type).toBe('VALIDATION');
-  });
-
-  test('ConflictError sets 409', () => {
-    const err = new ConflictError('Duplicate');
-    expect(err.statusCode).toBe(409);
-    expect(err.errorCode).toBe('DUPLICATE_RESOURCE');
-  });
-
-  test('BusinessRuleError sets 422', () => {
-    const err = new BusinessRuleError('Cannot invoice draft');
-    expect(err.statusCode).toBe(422);
-    expect(err.errorCode).toBe('BUSINESS_RULE_VIOLATED');
-    expect(err.type).toBe('VALIDATION');
-  });
-
-  test('AuthorizationError sets 403', () => {
-    const err = new AuthorizationError('No access');
-    expect(err.statusCode).toBe(403);
-    expect(err.errorCode).toBe('FORBIDDEN');
-  });
-
-  test('ServiceUnavailableError sets 503', () => {
-    const err = new ServiceUnavailableError('DB down');
-    expect(err.statusCode).toBe(503);
-    expect(err.errorCode).toBe('SERVICE_UNAVAILABLE');
-    expect(err.type).toBe('TRANSIENT');
-  });
-
-  test('isBusinessError returns true for BusinessError subtypes', () => {
-    expect(isBusinessError(new NotFoundError('x'))).toBe(true);
-    expect(isBusinessError(new Error('x'))).toBe(false);
-    expect(isBusinessError(null)).toBe(false);
-  });
-
-  test('toJSON returns structured error', () => {
-    const err = new NotFoundError('Not found', {
-      details: ['detail1'],
-      operation: 'findDoc',
-      service: 'invoicing'
-    });
-    const json = err.toJSON();
-    expect(json).toEqual({
-      code: 'RESOURCE_NOT_FOUND',
-      message: 'Not found',
-      statusCode: 404,
-      details: ['detail1'],
-      service: 'invoicing',
-      operation: 'findDoc'
-    });
-  });
-
-  test('custom errorCode can be overridden', () => {
-    const err = new NotFoundError('Tenant missing', { errorCode: 'TENANT_NOT_FOUND' });
-    expect(err.errorCode).toBe('TENANT_NOT_FOUND');
-  });
-});
-
-describe('businessErrorHandler middleware', () => {
-  let req, res, next;
-
-  beforeEach(() => {
-    req = { method: 'GET', originalUrl: '/api/test', app: { locals: { logger: { warn: jest.fn(), error: jest.fn() } } } };
-    res = { status: jest.fn().mockReturnThis(), json: jest.fn().mockReturnThis(), headersSent: false };
-    next = jest.fn();
-  });
-
-  test('formats BusinessError as structured JSON', () => {
-    const err = new NotFoundError('Doc not found', { details: ['UUID 123'] });
-    businessErrorHandler(err, req, res, next);
-
-    expect(res.status).toHaveBeenCalledWith(404);
-    expect(res.json).toHaveBeenCalledWith({
-      error: {
-        code: 'RESOURCE_NOT_FOUND',
-        message: 'Doc not found',
-        statusCode: 404,
-        details: ['UUID 123'],
-        service: undefined,
-        operation: undefined
-      }
-    });
-  });
-
-  test('wraps generic Error as INTERNAL_ERROR 500', () => {
-    const err = new Error('kaboom');
-    businessErrorHandler(err, req, res, next);
-
-    expect(res.status).toHaveBeenCalledWith(500);
-    const body = res.json.mock.calls[0][0];
-    expect(body.error.code).toBe('INTERNAL_ERROR');
-    expect(body.error.statusCode).toBe(500);
-  });
-
-  test('does not leak stack in production', () => {
-    const origEnv = process.env.NODE_ENV;
-    process.env.NODE_ENV = 'production';
-
-    const err = new Error('secret details');
-    businessErrorHandler(err, req, res, next);
-
-    const body = res.json.mock.calls[0][0];
-    expect(body.error.message).toBe('Internal server error');
-
-    process.env.NODE_ENV = origEnv;
-  });
-
-  test('calls next() if headers already sent', () => {
-    res.headersSent = true;
-    const err = new Error('late');
-    businessErrorHandler(err, req, res, next);
-    expect(next).toHaveBeenCalledWith(err);
-    expect(res.status).not.toHaveBeenCalled();
-  });
-});
-
-describe('notFoundHandler middleware', () => {
-  test('returns ROUTE_NOT_FOUND 404', () => {
-    const req = { method: 'GET', originalUrl: '/unknown', app: { locals: { logger: { warn: jest.fn() } } } };
-    const res = { status: jest.fn().mockReturnThis(), json: jest.fn().mockReturnThis() };
-    notFoundHandler(req, res);
-
-    expect(res.status).toHaveBeenCalledWith(404);
-    expect(res.json.mock.calls[0][0].error.code).toBe('ROUTE_NOT_FOUND');
-  });
-});

package/tests/unit/defaults.test.js

@@ -1,48 +0,0 @@
-'use strict';
-
-const defaults = require('../../src/defaults');
-const { getCriticalConfigWithFallbacks, getInfrastructureHealthConfig } = require('../../src/runtime-config');
-const { buildRedisUrl } = require('../../src/redisClient');
-
-describe('@onlineapps/service-common defaults @unit', () => {
-  test('should export stable module-owned defaults', () => {
-    expect(defaults.infrastructureHealthQueueName).toBe('infrastructure.health.checks');
-    expect(defaults.infrastructureHealthPublishIntervalMs).toBe(5000);
-    expect(defaults.infrastructureHealthWaitMaxTimeMs).toBe(60000);
-    expect(defaults.infrastructureHealthWaitCheckIntervalMs).toBe(2000);
-    expect(defaults.infrastructureHealthTimeoutMs).toBe(15000);
-    expect(defaults.infrastructureHealthRedisTtlSeconds).toBe(30);
-    expect(defaults.infrastructureHealthCleanupIntervalMs).toBe(10000);
-    expect(defaults.infrastructureHealthQueueWaitMaxTimeMs).toBe(60000);
-    expect(defaults.infrastructureHealthQueueWaitCheckIntervalMs).toBe(2000);
-  });
-
-  test('getCriticalConfigWithFallbacks should fail-fast when env is missing (no topology defaults)', () => {
-    const oldRedis = process.env.REDIS_URL;
-    const oldRabbit = process.env.RABBITMQ_URL;
-    delete process.env.REDIS_URL;
-    delete process.env.RABBITMQ_URL;
-
-    expect(() => getCriticalConfigWithFallbacks()).toThrow(/Missing required config/i);
-
-    if (oldRedis !== undefined) process.env.REDIS_URL = oldRedis;
-    if (oldRabbit !== undefined) process.env.RABBITMQ_URL = oldRabbit;
-  });
-
-  test('getInfrastructureHealthConfig should default queue name from module defaults', () => {
-    const old = process.env.INFRASTRUCTURE_HEALTH_QUEUE;
-    delete process.env.INFRASTRUCTURE_HEALTH_QUEUE;
-
-    const cfg = getInfrastructureHealthConfig();
-    expect(cfg.queueName).toBe(defaults.infrastructureHealthQueueName);
-
-    if (old !== undefined) process.env.INFRASTRUCTURE_HEALTH_QUEUE = old;
-  });
-
-  test('buildRedisUrl should fall back to module defaults host/port', () => {
-    expect(() => buildRedisUrl({ env: {}, defaults: {} })).toThrow(/Missing required config/i);
-  });
-});
-
-
-

package/tests/unit/monitoringFallbackEmail.test.js

@@ -1,57 +0,0 @@
-'use strict';
-
-jest.mock('nodemailer', () => {
-  return {
-    createTransport: jest.fn(() => ({
-      sendMail: jest.fn().mockResolvedValue(true)
-    }))
-  };
-});
-
-describe('monitoringFallbackEmail', () => {
-  const ORIGINAL_ENV = process.env;
-
-  beforeEach(() => {
-    jest.resetModules();
-    process.env = { ...ORIGINAL_ENV };
-  });
-
-  afterEach(() => {
-    process.env = ORIGINAL_ENV;
-  });
-
-  function loadReporter() {
-    return require('../../src/reporting/monitoringFallbackEmail');
-  }
-
-  test('returns false when SMTP config missing', async () => {
-    delete process.env.INFRA_REPORT_SMTP_HOST;
-    const { sendMonitoringFailFallbackEmail } = loadReporter();
-    const result = await sendMonitoringFailFallbackEmail('t', 't', '<p>t</p>');
-    expect(result).toBe(false);
-  });
-
-  test('sends email when SMTP config provided', async () => {
-    process.env.INFRA_REPORT_SMTP_HOST = 'smtp.example.com';
-    process.env.INFRA_REPORT_SMTP_PORT = '587';
-    process.env.INFRA_REPORT_SMTP_SECURE = 'false';
-    process.env.INFRA_REPORT_SMTP_USER = 'user@example.com';
-    process.env.INFRA_REPORT_SMTP_PASS = 'secret';
-    process.env.INFRA_REPORT_FROM = 'infra@example.com';
-    process.env.INFRA_REPORT_TO = 'ops@example.com';
-
-    const nodemailer = require('nodemailer');
-    const transportMock = {
-      sendMail: jest.fn().mockResolvedValue(true)
-    };
-    nodemailer.createTransport.mockReturnValue(transportMock);
-
-    const { sendMonitoringFailFallbackEmail } = loadReporter();
-    const result = await sendMonitoringFailFallbackEmail('Subject', 'Body', '<p>Body</p>');
-
-    expect(result).toBe(true);
-    expect(transportMock.sendMail).toHaveBeenCalledTimes(1);
-  });
-});
-
-