@onlineapps/service-common 1.0.19 → 1.1.0

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.0",
+  "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/jwt/createJwtValidator.test.js

@@ -0,0 +1,170 @@
+'use strict';
+
+const jwt = require('jsonwebtoken');
+
+const TEST_SECRET = 'test-jwt-secret-at-least-16-chars';
+
+function createValidAccessToken(overrides = {}) {
+  const payload = {
+    sub: 'u_person-uuid',
+    person_id: 42,
+    email: 'test@example.com',
+    tenants: [{ tenant_uuid: 'a_t1', tenant_id: 1, role: 'OWNER' }],
+    type: 'access',
+    ...overrides
+  };
+  return jwt.sign(payload, TEST_SECRET, { issuer: 'oa-auth', expiresIn: '15m' });
+}
+
+function mockRes() {
+  const res = {
+    statusCode: null,
+    body: null,
+    status(code) { res.statusCode = code; return res; },
+    json(data) { res.body = data; return res; }
+  };
+  return res;
+}
+
+describe('createJwtValidator @unit', () => {
+  const originalEnv = process.env.JWT_SECRET;
+
+  beforeEach(() => {
+    process.env.JWT_SECRET = TEST_SECRET;
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.JWT_SECRET = originalEnv;
+    } else {
+      delete process.env.JWT_SECRET;
+    }
+  });
+
+  function loadModule() {
+    return require('../../../src/jwt/createJwtValidator');
+  }
+
+  const logger = { info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn() };
+
+  it('throws if logger is missing', () => {
+    const { createJwtValidator } = loadModule();
+    expect(() => createJwtValidator({ logger: null })).toThrow('Logger is required');
+  });
+
+  it('returns 401 when Authorization header is missing', () => {
+    const { createJwtValidator } = loadModule();
+    const middleware = createJwtValidator({ logger });
+    const req = { path: '/test', headers: {} };
+    const res = mockRes();
+    const next = jest.fn();
+
+    middleware(req, res, next);
+
+    expect(res.statusCode).toBe(401);
+    expect(res.body.error).toContain('Missing or invalid Authorization header');
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('returns 401 when Authorization header has no Bearer prefix', () => {
+    const { createJwtValidator } = loadModule();
+    const middleware = createJwtValidator({ logger });
+    const req = { path: '/test', headers: { authorization: 'Basic abc123' } };
+    const res = mockRes();
+    const next = jest.fn();
+
+    middleware(req, res, next);
+
+    expect(res.statusCode).toBe(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('sets req.auth and calls next() for valid token', () => {
+    const { createJwtValidator } = loadModule();
+    const middleware = createJwtValidator({ logger });
+    const token = createValidAccessToken();
+    const req = { path: '/test', headers: { authorization: `Bearer ${token}` } };
+    const res = mockRes();
+    const next = jest.fn();
+
+    middleware(req, res, next);
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(req.auth).toBeDefined();
+    expect(req.auth.person_uuid).toBe('u_person-uuid');
+    expect(req.auth.person_id).toBe(42);
+    expect(req.auth.email).toBe('test@example.com');
+    expect(req.auth.tenants).toHaveLength(1);
+  });
+
+  it('returns 401 with refresh instruction for expired token', () => {
+    const { createJwtValidator } = loadModule();
+    const middleware = createJwtValidator({ logger });
+    const token = jwt.sign(
+      { sub: 'u_test', person_id: 1, type: 'access' },
+      TEST_SECRET,
+      { issuer: 'oa-auth', expiresIn: '0s' }
+    );
+    const req = { path: '/test', headers: { authorization: `Bearer ${token}` } };
+    const res = mockRes();
+    const next = jest.fn();
+
+    middleware(req, res, next);
+
+    expect(res.statusCode).toBe(401);
+    expect(res.body.error).toContain('expired');
+    expect(res.body.error).toContain('refresh');
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('returns 401 for refresh token (wrong type)', () => {
+    const { createJwtValidator } = loadModule();
+    const middleware = createJwtValidator({ logger });
+    const token = jwt.sign(
+      { sub: 'u_test', person_id: 1, type: 'refresh' },
+      TEST_SECRET,
+      { issuer: 'oa-auth', expiresIn: '7d' }
+    );
+    const req = { path: '/test', headers: { authorization: `Bearer ${token}` } };
+    const res = mockRes();
+    const next = jest.fn();
+
+    middleware(req, res, next);
+
+    expect(res.statusCode).toBe(401);
+    expect(res.body.error).toContain('Invalid token type');
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('skips validation for excluded paths', () => {
+    const { createJwtValidator } = loadModule();
+    const middleware = createJwtValidator({ logger, excludePaths: ['/health', '/public'] });
+    const req = { path: '/health', headers: {} };
+    const res = mockRes();
+    const next = jest.fn();
+
+    middleware(req, res, next);
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(res.statusCode).toBeNull();
+  });
+
+  it('logs warning on invalid token', () => {
+    const { createJwtValidator } = loadModule();
+    const warnFn = jest.fn();
+    const testLogger = { ...logger, warn: warnFn };
+    const middleware = createJwtValidator({ logger: testLogger });
+    const req = { path: '/test', headers: { authorization: 'Bearer invalid.token.here' } };
+    const res = mockRes();
+    const next = jest.fn();
+
+    middleware(req, res, next);
+
+    expect(warnFn).toHaveBeenCalledWith(
+      '[JWT] Token verification failed',
+      expect.objectContaining({ error: expect.any(String) })
+    );
+    expect(res.statusCode).toBe(401);
+  });
+});

package/tests/unit/jwt/extractTenantContext.test.js

@@ -0,0 +1,148 @@
+'use strict';
+
+describe('extractTenantContext @unit', () => {
+  function loadModule() {
+    return require('../../../src/jwt/extractTenantContext');
+  }
+
+  const singleTenantAuth = {
+    person_uuid: 'u_person1',
+    person_id: 42,
+    email: 'test@example.com',
+    tenants: [
+      { tenant_uuid: 'a_tenant1', tenant_id: 10, role: 'OWNER' }
+    ]
+  };
+
+  const multiTenantAuth = {
+    person_uuid: 'u_person1',
+    person_id: 42,
+    email: 'test@example.com',
+    tenants: [
+      { tenant_uuid: 'a_tenant1', tenant_id: 10, role: 'OWNER' },
+      { tenant_uuid: 'a_tenant2', tenant_id: 20, role: 'EDITOR' }
+    ]
+  };
+
+  it('throws 400 for single tenant without workspace header (requireWorkspace: true)', () => {
+    const { extractTenantContext } = loadModule();
+    expect(() => extractTenantContext(singleTenantAuth, {})).toThrow('Missing x-workspace-id');
+  });
+
+  it('auto-picks single tenant without workspace when requireWorkspace: false', () => {
+    const { extractTenantContext } = loadModule();
+    const ctx = extractTenantContext(singleTenantAuth, {}, { requireWorkspace: false });
+
+    expect(ctx).toEqual({
+      tenant_id: 10,
+      tenant_uuid: 'a_tenant1',
+      workspace_id: null,
+      person_id: 42,
+      person_uuid: 'u_person1',
+      role: 'OWNER'
+    });
+  });
+
+  it('uses workspace from header when provided', () => {
+    const { extractTenantContext } = loadModule();
+    const ctx = extractTenantContext(singleTenantAuth, { 'x-workspace-id': '5' });
+
+    expect(ctx.workspace_id).toBe(5);
+  });
+
+  it('picks correct tenant when x-tenant-uuid is provided', () => {
+    const { extractTenantContext } = loadModule();
+    const ctx = extractTenantContext(multiTenantAuth, { 'x-tenant-uuid': 'a_tenant2', 'x-workspace-id': '1' });
+
+    expect(ctx.tenant_id).toBe(20);
+    expect(ctx.tenant_uuid).toBe('a_tenant2');
+    expect(ctx.role).toBe('EDITOR');
+    expect(ctx.workspace_id).toBe(1);
+  });
+
+  it('picks correct tenant with custom workspace', () => {
+    const { extractTenantContext } = loadModule();
+    const ctx = extractTenantContext(multiTenantAuth, {
+      'x-tenant-uuid': 'a_tenant1',
+      'x-workspace-id': '3'
+    });
+
+    expect(ctx.tenant_id).toBe(10);
+    expect(ctx.workspace_id).toBe(3);
+  });
+
+  it('throws 400 when multiple tenants and no x-tenant-uuid (requireWorkspace: false)', () => {
+    const { extractTenantContext } = loadModule();
+
+    expect(() => extractTenantContext(multiTenantAuth, {}, { requireWorkspace: false })).toThrow('Missing tenant context');
+    try {
+      extractTenantContext(multiTenantAuth, {}, { requireWorkspace: false });
+    } catch (err) {
+      expect(err.statusCode).toBe(400);
+    }
+  });
+
+  it('throws 403 when x-tenant-uuid does not match any membership', () => {
+    const { extractTenantContext } = loadModule();
+
+    expect(() => extractTenantContext(singleTenantAuth, { 'x-tenant-uuid': 'a_nonexistent', 'x-workspace-id': '1' }))
+      .toThrow('No membership for specified tenant');
+    try {
+      extractTenantContext(singleTenantAuth, { 'x-tenant-uuid': 'a_nonexistent', 'x-workspace-id': '1' });
+    } catch (err) {
+      expect(err.statusCode).toBe(403);
+    }
+  });
+
+  it('parses workspace header as integer', () => {
+    const { extractTenantContext } = loadModule();
+    const ctx = extractTenantContext(singleTenantAuth, { 'x-workspace-id': '42' });
+
+    expect(ctx.workspace_id).toBe(42);
+    expect(typeof ctx.workspace_id).toBe('number');
+  });
+
+  it('throws 401 when auth is null', () => {
+    const { extractTenantContext } = loadModule();
+
+    expect(() => extractTenantContext(null, {})).toThrow('Missing auth data');
+    try {
+      extractTenantContext(null, {});
+    } catch (err) {
+      expect(err.statusCode).toBe(401);
+    }
+  });
+
+  it('throws 401 when auth.tenants is not an array', () => {
+    const { extractTenantContext } = loadModule();
+
+    expect(() => extractTenantContext({ person_id: 1 }, {})).toThrow('Missing auth data');
+  });
+
+  it('single tenant with only x-workspace-id header (no x-tenant-uuid)', () => {
+    const { extractTenantContext } = loadModule();
+    const ctx = extractTenantContext(singleTenantAuth, { 'x-workspace-id': '7' });
+
+    expect(ctx.tenant_id).toBe(10);
+    expect(ctx.workspace_id).toBe(7);
+  });
+
+  it('multiple tenants with only x-workspace-id header throws 400', () => {
+    const { extractTenantContext } = loadModule();
+
+    expect(() => extractTenantContext(multiTenantAuth, { 'x-workspace-id': '2' }))
+      .toThrow('Missing tenant context');
+  });
+
+  it('workspace_id null when requireWorkspace false and no header', () => {
+    const { extractTenantContext } = loadModule();
+    const ctx = extractTenantContext(singleTenantAuth, {}, { requireWorkspace: false });
+    expect(ctx.workspace_id).toBeNull();
+  });
+
+  it('workspace_id from header even when requireWorkspace false', () => {
+    const { extractTenantContext } = loadModule();
+    const ctx = extractTenantContext(singleTenantAuth, { 'x-workspace-id': '9' }, { requireWorkspace: false });
+    expect(ctx.workspace_id).toBe(9);
+  });
+});

package/tests/unit/jwt/verifyAccessToken.test.js

@@ -0,0 +1,137 @@
+'use strict';
+
+const jwt = require('jsonwebtoken');
+
+const TEST_SECRET = 'test-jwt-secret-at-least-16-chars';
+const WRONG_SECRET = 'wrong-secret-also-16-chars-long';
+
+function createValidAccessToken(overrides = {}) {
+  const payload = {
+    sub: 'u_test-person-uuid',
+    person_id: 42,
+    email: 'test@example.com',
+    tenants: [{ tenant_uuid: 'a_tenant1', tenant_id: 1, role: 'OWNER' }],
+    type: 'access',
+    ...overrides
+  };
+  return jwt.sign(payload, TEST_SECRET, { issuer: 'oa-auth', expiresIn: '15m' });
+}
+
+describe('verifyAccessToken @unit', () => {
+  const originalEnv = process.env.JWT_SECRET;
+
+  beforeEach(() => {
+    process.env.JWT_SECRET = TEST_SECRET;
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.JWT_SECRET = originalEnv;
+    } else {
+      delete process.env.JWT_SECRET;
+    }
+  });
+
+  function loadModule() {
+    return require('../../../src/jwt/verifyAccessToken');
+  }
+
+  it('returns decoded payload for valid access token', () => {
+    const { verifyAccessToken } = loadModule();
+    const token = createValidAccessToken();
+    const decoded = verifyAccessToken(token);
+
+    expect(decoded.sub).toBe('u_test-person-uuid');
+    expect(decoded.person_id).toBe(42);
+    expect(decoded.email).toBe('test@example.com');
+    expect(decoded.tenants).toHaveLength(1);
+    expect(decoded.type).toBe('access');
+    expect(decoded.iss).toBe('oa-auth');
+  });
+
+  it('throws on expired token', () => {
+    const { verifyAccessToken } = loadModule();
+    const token = jwt.sign(
+      { sub: 'u_test', person_id: 1, type: 'access' },
+      TEST_SECRET,
+      { issuer: 'oa-auth', expiresIn: '0s' }
+    );
+
+    expect(() => verifyAccessToken(token)).toThrow();
+    try {
+      verifyAccessToken(token);
+    } catch (err) {
+      expect(err.name).toBe('TokenExpiredError');
+    }
+  });
+
+  it('throws on invalid signature (wrong secret)', () => {
+    const { verifyAccessToken } = loadModule();
+    const token = jwt.sign(
+      { sub: 'u_test', person_id: 1, type: 'access' },
+      WRONG_SECRET,
+      { issuer: 'oa-auth' }
+    );
+
+    expect(() => verifyAccessToken(token)).toThrow('invalid signature');
+  });
+
+  it('throws when JWT_SECRET is missing', () => {
+    delete process.env.JWT_SECRET;
+    const { verifyAccessToken } = loadModule();
+    const token = createValidAccessToken();
+
+    expect(() => verifyAccessToken(token)).toThrow('JWT_SECRET');
+  });
+
+  it('throws when JWT_SECRET is too short', () => {
+    process.env.JWT_SECRET = 'short';
+    const { verifyAccessToken } = loadModule();
+    const token = createValidAccessToken();
+
+    expect(() => verifyAccessToken(token)).toThrow('at least 16 characters');
+  });
+
+  it('throws on refresh token (type != access)', () => {
+    const { verifyAccessToken } = loadModule();
+    const token = jwt.sign(
+      { sub: 'u_test', person_id: 1, type: 'refresh' },
+      TEST_SECRET,
+      { issuer: 'oa-auth', expiresIn: '7d' }
+    );
+
+    expect(() => verifyAccessToken(token)).toThrow('Invalid token type');
+    try {
+      verifyAccessToken(token);
+    } catch (err) {
+      expect(err.code).toBe('INVALID_TOKEN_TYPE');
+    }
+  });
+
+  it('throws on wrong issuer', () => {
+    const { verifyAccessToken } = loadModule();
+    const token = jwt.sign(
+      { sub: 'u_test', person_id: 1, type: 'access' },
+      TEST_SECRET,
+      { issuer: 'wrong-issuer' }
+    );
+
+    expect(() => verifyAccessToken(token)).toThrow();
+  });
+
+  it('throws on empty token', () => {
+    const { verifyAccessToken } = loadModule();
+
+    expect(() => verifyAccessToken('')).toThrow('Token is required');
+    expect(() => verifyAccessToken(null)).toThrow('Token is required');
+    expect(() => verifyAccessToken(undefined)).toThrow('Token is required');
+  });
+
+  it('throws on non-string token', () => {
+    const { verifyAccessToken } = loadModule();
+
+    expect(() => verifyAccessToken(12345)).toThrow('Token is required');
+    expect(() => verifyAccessToken({})).toThrow('Token is required');
+  });
+});