@onlineapps/infrastructure-tools 1.0.70 → 1.1.1

package/README.md

@@ -92,6 +92,34 @@ await storage.ensureBucket('workflow');
 await storage.putObject('workflow', 'path/to/file', buffer);
 ```
 
+### JWT Validation
+
+Shared JWT validation for infrastructure services accepting client requests (gateway, delivery endpoint, meta).
+Standard: [docs/standards/JWT_AUTH.md](/docs/standards/JWT_AUTH.md).
+
+```javascript
+const {
+  createJwtValidator,
+  verifyAccessToken,
+  extractTenantContext
+} = require('@onlineapps/infrastructure-tools');
+
+// Express middleware: validates Bearer token, sets req.auth
+app.use('/api', createJwtValidator({
+  logger,
+  excludePaths: ['/health']
+}));
+
+// Pure function: verify token outside Express context (e.g. WebSocket handshake)
+const decoded = verifyAccessToken(rawToken);
+
+// Pure function: extract tenant context from auth + headers
+const ctx = extractTenantContext(req.auth, req.headers);
+// => { tenant_id, tenant_uuid, workspace_id, person_id, person_uuid, role }
+```
+
+**Env:** `JWT_SECRET` (min 16 chars, HMAC-SHA256). Fail-fast if missing.
+
 ## API
 
 ### `waitForInfrastructureReady(options)`
@@ -142,6 +170,46 @@ Creates health publisher adapter for BaseClient (from mq-client-core).
 
 Creates health publisher adapter for amqplib (direct connection + channel).
 
+### `verifyAccessToken(token)`
+
+Verify and decode an OA Drive access token (pure function).
+
+**Parameters:**
+- `token` (string): Raw JWT string (without "Bearer " prefix)
+
+**Returns:** Decoded payload `{ sub, person_id, email, tenants, type, iss, iat, exp }`
+
+**Throws:**
+- `TokenExpiredError` (from jsonwebtoken) if token is expired
+- `JsonWebTokenError` if signature or issuer invalid
+- `Error` with `code: 'INVALID_TOKEN_TYPE'` if token type is not `access`
+- `Error` if `JWT_SECRET` env var is missing or too short
+
+### `createJwtValidator({ logger, excludePaths })`
+
+Create Express middleware that validates JWT Bearer tokens.
+
+**Options:**
+- `logger` (Object): Logger with `.warn()` method (required)
+- `excludePaths` (string[]): Paths to skip validation (default: `[]`)
+
+**Behavior:** Sets `req.auth = { person_uuid, person_id, email, tenants }` on success. Returns 401 JSON on failure.
+
+### `extractTenantContext(auth, headers)`
+
+Extract tenant context from JWT auth data and request headers (pure function).
+
+**Parameters:**
+- `auth` (Object): `req.auth` from `createJwtValidator`: `{ person_uuid, person_id, email, tenants }`
+- `headers` (Object): HTTP request headers (lowercase keys)
+
+**Returns:** `{ tenant_id, tenant_uuid, workspace_id, person_id, person_uuid, role }`
+
+**Throws:**
+- `Error` with `statusCode: 400` if multiple tenants and `x-tenant-uuid` header missing
+- `Error` with `statusCode: 403` if specified tenant not in memberships
+- `Error` with `statusCode: 401` if auth data is missing
+
 ### `StorageCore`
 
 Re-exported from `@onlineapps/storage-core` for infrastructure services.
@@ -162,6 +230,7 @@ See [@onlineapps/storage-core](../storage/storage-core/README.md) for full API d
 - `@onlineapps/mq-client-core` - For queue configuration
 - `@onlineapps/service-common` - For `waitForInfrastructureReady` (shared utility)
 - `@onlineapps/storage-core` - For core MinIO storage operations
+- `jsonwebtoken` - For JWT verification (HMAC-SHA256)
 
 ## Related Libraries
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/infrastructure-tools",
-  "version": "1.0.70",
+  "version": "1.1.1",
   "description": "Infrastructure orchestration utilities for OA Drive infrastructure services (health tracking, queue initialization, service discovery)",
   "main": "src/index.js",
   "scripts": {
@@ -18,11 +18,12 @@
   "author": "OnlineApps",
   "license": "MIT",
   "dependencies": {
+    "@onlineapps/infra-logger": "1.0.0",
     "@onlineapps/mq-client-core": "1.0.80",
     "@onlineapps/service-common": "1.0.17",
     "@onlineapps/storage-core": "1.0.12",
-    "uuid": "^9.0.1",
-    "@onlineapps/infra-logger": "1.0.0"
+    "jsonwebtoken": "^9.0.3",
+    "uuid": "^9.0.1"
   },
   "devDependencies": {
     "jest": "^29.7.0"

package/src/index.js

@@ -52,6 +52,9 @@ const {
 } = require('./health/healthPublisher');
 const { sendQueueMismatchAlert } = require('./monitoring/queueMismatchReporter');
 
+// JWT validation utilities (shared across infrastructure services that accept client requests)
+const { verifyAccessToken, createJwtValidator, extractTenantContext } = require('./jwt');
+
 module.exports = {
   // MQ Client Core (re-exported for convenience)
   BaseClient,
@@ -95,6 +98,11 @@ module.exports = {
   sendQueueMismatchAlert,
   
   // Storage utilities (re-exported - infrastructure services should use infrastructure-tools, not storage-core directly)
-  StorageCore
+  StorageCore,
+  
+  // JWT validation utilities (for infrastructure services accepting client HTTP/WS requests)
+  verifyAccessToken,
+  createJwtValidator,
+  extractTenantContext
 };
 

package/src/jwt/createJwtValidator.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { verifyAccessToken } = require('./verifyAccessToken');
+
+/**
+ * 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
+ * @returns {Function} Express middleware (req, res, next)
+ */
+function createJwtValidator({ logger, excludePaths }) {
+  if (!logger || typeof logger.warn !== 'function') {
+    throw new Error('[JWT] Logger is required - Expected object with warn() method');
+  }
+
+  const excluded = new Set(excludePaths || []);
+
+  return 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);
+
+      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 };

package/src/jwt/extractTenantContext.js

@@ -0,0 +1,64 @@
+'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 defaults to 1 if header absent
+ *
+ * @param {object} auth - req.auth from createJwtValidator: { person_uuid, person_id, email, tenants }
+ * @param {object} headers - HTTP request headers (lowercase keys)
+ * @returns {object} { tenant_id, tenant_uuid, workspace_id, person_id, person_uuid, role }
+ * @throws {Error} with .statusCode = 400 or 403
+ */
+function extractTenantContext(auth, headers) {
+  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'];
+  const workspaceId = rawWorkspaceId ? parseInt(rawWorkspaceId, 10) : 1;
+
+  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,11 @@
+'use strict';
+
+const { verifyAccessToken } = require('./verifyAccessToken');
+const { createJwtValidator } = require('./createJwtValidator');
+const { extractTenantContext } = require('./extractTenantContext');
+
+module.exports = {
+  verifyAccessToken,
+  createJwtValidator,
+  extractTenantContext
+};

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 };