w3home-utils 1.0.0 → 1.1.0

package/README.md

@@ -14,10 +14,21 @@ npm install w3home-utils
 const {
   // Authentication
   getIndetifiers,
+  getIndetifiersCognito,
+  verifyW3JWT,
   getUser,
   getUserType,
   decodeIdToken,
-  
+  clearUserCache,
+
+  // W3 User Mapping
+  resolveW3UserToHomepayUser,
+  clearMappingCache,
+
+  // Redis/JWKS Cache (advanced)
+  getRedisClient,
+  getCachedJWKS,
+
   // Authorization
   authorize,
   withAuthorization,
@@ -25,12 +36,12 @@ const {
   authorizeBackofficeProject,
   ROLES,
   UserType,
-  
+
   // Activity Logging
   logActivity,
   logPostActivity,
   withActivityLogging,
-  
+
   // Common
   corsHeaders
 } = require('w3home-utils');
@@ -38,13 +49,22 @@ const {
 
 ## Authentication
 
+### Dual-Auth Support (W3 Platform + Cognito)
+
+**w3home-utils v1.1.0** supports dual authentication via the `AUTH_MODE` environment variable:
+
+- `cognito` (default): Legacy Cognito JWT decode
+- `w3`: W3 Platform JWT validation with user mapping
+- `dual`: Try W3 first, fall back to Cognito on failure
+
 ### Get User Identifiers from Request Headers
 
 ```javascript
 const { getIndetifiers } = require('w3home-utils');
 
 const handler = async (event) => {
-  const { userId } = await getIndetifiers(event.headers);
+  // Returns: { userId: string|null, w3Sub: string|null, authType?: 'w3'|'cognito' }
+  const { userId, w3Sub, authType } = await getIndetifiers(event.headers);
   if (!userId) {
     return { statusCode: 401, body: JSON.stringify({ error: 'Unauthorized' }) };
   }
@@ -52,6 +72,11 @@ const handler = async (event) => {
 };
 ```
 
+**Return shape:**
+- `userId`: Homepay user ID (always present for authenticated users)
+- `w3Sub`: W3 platform user ID (present only for W3-authenticated users)
+- `authType`: `'w3'` or `'cognito'` (indicates which auth backend was used)
+
 ### Get User Details
 
 ```javascript
@@ -171,6 +196,8 @@ console.log(UserType.BACKOFFICE_USER); // 'BACKOFFICE_USER'
 
 ## Environment Variables
 
+### Core Configuration
+
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `USERS_TABLE` | `w3HomeUsers` | DynamoDB table for users |
@@ -178,6 +205,36 @@ console.log(UserType.BACKOFFICE_USER); // 'BACKOFFICE_USER'
 | `CONFIG_TABLE` | `w3home-config` | DynamoDB table for config |
 | `STAGE` | `dev` | Environment stage |
 
+### Authentication Mode (v1.1.0+)
+
+| Variable | Values | Description |
+|----------|--------|-------------|
+| `AUTH_MODE` | `cognito` (default), `w3`, `dual` | Authentication backend selector |
+
+**Auth modes:**
+- `cognito`: Legacy Cognito JWT decode (backward compatible)
+- `w3`: W3 Platform JWT validation + user mapping lookup
+- `dual`: Try W3 first, fall back to Cognito on failure (recommended for migration)
+
+### W3 Platform Configuration (required when `AUTH_MODE=w3` or `dual`)
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `W3_JWKS_URL` | Yes | - | W3 platform JWKS endpoint URL |
+| `W3_ISSUER` | Yes | - | W3 platform issuer (iss claim) |
+| `W3_USER_MAPPING_TABLE` | No | `w3UserMapping` | DynamoDB table for w3UserId → homepayUserId mapping |
+
+### Redis Configuration (required for W3 JWKS caching)
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `REDIS_HOST` | Yes | - | Redis host for JWKS cache |
+| `REDIS_PORT` | No | `6379` | Redis port |
+| `REDIS_PASSWORD` | Yes* | - | Redis password (*required for production) |
+| `REDIS_TLS` | No | `false` | Enable TLS for Redis connection |
+
+**JWKS cache TTL:** 10 minutes (reduces load on W3 platform JWKS endpoint)
+
 ## Peer Dependencies
 
 This package requires `aws-sdk` as a peer dependency. In Lambda, this is already available. For local development:
@@ -186,6 +243,53 @@ This package requires `aws-sdk` as a peer dependency. In Lambda, this is already
 npm install aws-sdk --save-dev
 ```
 
+## Migration Guide
+
+### Migrating to W3 Platform Authentication (v1.1.0)
+
+**Step 1: Update w3home-utils**
+
+```bash
+npm update w3home-utils
+```
+
+**Step 2: Enable dual-auth mode**
+
+Add to your Lambda environment variables:
+
+```bash
+AUTH_MODE=dual
+W3_JWKS_URL=https://api.w3mcp.ai/.well-known/jwks.json
+W3_ISSUER=https://api.w3mcp.ai
+W3_USER_MAPPING_TABLE=w3UserMapping  # Optional, defaults to this
+REDIS_HOST=your-redis-host
+REDIS_PORT=6379
+REDIS_PASSWORD=your-redis-password
+REDIS_TLS=true  # For production
+```
+
+**Step 3: No code changes needed!**
+
+`getIndetifiers()` now returns `{ userId, w3Sub, authType }`. The `userId` field works exactly as before.
+
+**Optional:** Use `w3Sub` for enhanced audit trails:
+
+```javascript
+const { userId, w3Sub, authType } = await getIndetifiers(event.headers);
+logActivity({
+  event,
+  userId,
+  w3Sub,  // Now captured in activity logs
+  action: 'READ',
+  resource: 'projects',
+  statusCode: 200
+});
+```
+
+**Rollback:** Set `AUTH_MODE=cognito` to instantly revert to Cognito-only auth.
+
+**Cutover:** Once all users migrated to W3 platform, set `AUTH_MODE=w3` for W3-only validation (no Cognito fallback).
+
 ## License
 
 UNLICENSED - HomePay Internal Use Only

package/package.json

@@ -1,25 +1,30 @@
 {
   "name": "w3home-utils",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "W3Home Utilities - Authorization, Activity Logging, Auth Utilities",
   "main": "w3home-utils/index.js",
   "files": [
     "w3home-utils/**/*.js"
   ],
   "scripts": {
-    "test": "echo \"No tests specified\" && exit 0",
+    "test": "jest --coverage --passWithNoTests",
+    "test:watch": "jest --watch",
     "prepublishOnly": "npm test",
     "seed:dev": "node seed-tables.js dev",
     "seed:prd": "node seed-tables.js prd"
   },
   "dependencies": {
+    "ioredis": "^5.10.0",
+    "jose": "^5.10.0",
     "jsonwebtoken": "^9.0.2"
   },
   "peerDependencies": {
     "aws-sdk": "^2.1000.0"
   },
   "devDependencies": {
-    "aws-sdk": "^2.1692.0"
+    "aws-sdk": "^2.1692.0",
+    "aws-sdk-mock": "^6.2.2",
+    "jest": "^29.7.0"
   },
   "keywords": [
     "authorization",

package/w3home-utils/activityLogger.js

@@ -39,14 +39,16 @@ function extractRequestContext(event) {
   };
 }
 
-function logActivity({ event, userId, action, resource, statusCode, metadata = {}, context }) {
+function logActivity({ event, userId, w3Sub, action, resource, statusCode, metadata = {}, context }) {
   const identifiers = extractIdentifiers(event, userId);
   const requestContext = extractRequestContext(event);
-  
+
   const activityLog = {
     logType: LOG_PREFIX,
     timestamp: new Date().toISOString(),
     userId: identifiers.userId,
+    w3Sub: w3Sub || null,
+    authMode: process.env.AUTH_MODE || 'cognito',
     projectId: identifiers.projectId,
     apartmentId: identifiers.apartmentId,
     action,
@@ -78,13 +80,23 @@ function withActivityLogging(handler, config = {}) {
   return async (event, context) => {
     const resource = config.resource || 'unknown';
     let userId = null;
+    let w3Sub = null;
     let action = 'CREATE';
     let statusCode = null;
     let metadata = {};
 
     try {
-      if (config.extractUserId) userId = await config.extractUserId(event);
-      
+      if (config.extractUserId) {
+        const userIdResult = await config.extractUserId(event);
+        // Support both string and object return values
+        if (typeof userIdResult === 'object' && userIdResult !== null) {
+          userId = userIdResult.userId || null;
+          w3Sub = userIdResult.w3Sub || null;
+        } else {
+          userId = userIdResult;
+        }
+      }
+
       if (config.extractAction) {
         action = await config.extractAction(event);
       } else {
@@ -95,15 +107,15 @@ function withActivityLogging(handler, config = {}) {
 
       const result = await handler(event, context);
       statusCode = result.statusCode || 200;
-      
+
       if (config.extractMetadata) metadata = config.extractMetadata(result, event);
-      logActivity({ event, userId, action, resource, statusCode, metadata, context });
+      logActivity({ event, userId, w3Sub, action, resource, statusCode, metadata, context });
 
       return result;
     } catch (error) {
       statusCode = 500;
       metadata = { error: error.message };
-      logActivity({ event, userId, action, resource, statusCode, metadata, context });
+      logActivity({ event, userId, w3Sub, action, resource, statusCode, metadata, context });
       throw error;
     }
   };

package/w3home-utils/authUtils.cognito.js

@@ -0,0 +1,42 @@
+/**
+ * Cognito Authentication Utilities
+ *
+ * Extracted from authUtils.js for dual-auth support.
+ * Handles legacy Cognito JWT decode flow (no verification, just decode).
+ */
+
+const jwt = require('jsonwebtoken');
+
+/**
+ * Decode Cognito JWT token (no verification - backward compatible)
+ * @param {string} idToken - Cognito JWT token
+ * @returns {string|null} - Cognito sub claim or null
+ */
+function decodeIdToken(idToken) {
+  try {
+    const decoded = jwt.decode(idToken);
+    return decoded?.sub || null;
+  } catch (error) {
+    console.error('Error decoding Cognito token:', error.message);
+    return null;
+  }
+}
+
+/**
+ * Get identifiers using Cognito flow (legacy)
+ * @param {string} token - JWT token
+ * @returns {Promise<{userId: string|null, w3Sub: null, authType: 'cognito'}>}
+ */
+async function getIndetifiersCognito(token) {
+  const sub = decodeIdToken(token);
+  return {
+    userId: sub,
+    w3Sub: null,
+    authType: 'cognito'
+  };
+}
+
+module.exports = {
+  getIndetifiersCognito,
+  decodeIdToken
+};

package/w3home-utils/authUtils.js

@@ -1,9 +1,17 @@
 /**
  * Authentication Utilities
+ *
+ * Supports dual-auth mode: Cognito (legacy) and W3 Platform JWT
+ * Routing controlled via AUTH_MODE environment variable:
+ *   - 'cognito' (default): Legacy Cognito JWT decode
+ *   - 'w3': W3 Platform JWT validation + user mapping
+ *   - 'dual': Try W3 first, fall back to Cognito on failure
  */
 
-const jwt = require('jsonwebtoken');
 const AWS = require('aws-sdk');
+const { getIndetifiersCognito, decodeIdToken } = require('./authUtils.cognito');
+const { verifyW3JWT } = require('./authUtils.w3');
+const { resolveW3UserToHomepayUser } = require('./mappingUtils');
 
 const USERS_TABLE = process.env.USERS_TABLE || 'w3HomeUsers';
 const dynamodb = new AWS.DynamoDB.DocumentClient({ region: 'eu-west-1' });
@@ -11,40 +19,84 @@ const dynamodb = new AWS.DynamoDB.DocumentClient({ region: 'eu-west-1' });
 const USER_CACHE_TTL = 5 * 60 * 1000;
 const userCache = new Map();
 
-function decodeIdToken(idToken) {
-  try {
-    const decoded = jwt.decode(idToken);
-    return decoded?.sub || null;
-  } catch (error) {
-    console.error('Error decoding token:', error.message);
-    return null;
-  }
-}
+/**
+ * Extract token from various header formats
+ * @param {Object} headers - Request headers
+ * @returns {string|null} - Extracted token or null
+ */
+function extractToken(headers) {
+  let token = '';
 
-async function getIndetifiers(headers) {
-  let authorizationToken = '';
-  
   if (headers['Authorization']) {
     const parts = headers['Authorization'].split(' ');
-    authorizationToken = parts.length > 1 ? parts[1] : parts[0];
+    token = parts.length > 1 ? parts[1] : parts[0];
   }
-  if (!authorizationToken && headers['Token']) {
-    authorizationToken = headers['Token'];
+  if (!token && headers['Token']) {
+    token = headers['Token'];
   }
-  if (!authorizationToken && headers['authorization']) {
+  if (!token && headers['authorization']) {
     const parts = headers['authorization'].split(' ');
-    authorizationToken = parts.length > 1 ? parts[1] : parts[0];
+    token = parts.length > 1 ? parts[1] : parts[0];
   }
-  if (!authorizationToken && headers['token']) {
-    authorizationToken = headers['token'];
+  if (!token && headers['token']) {
+    token = headers['token'];
   }
-  
-  if (authorizationToken) {
-    const sub = decodeIdToken(authorizationToken);
-    if (sub) return { userId: sub };
+
+  return token || null;
+}
+
+/**
+ * Get identifiers with W3 Platform JWT validation
+ * @param {string} token - JWT token
+ * @returns {Promise<{userId: string, w3Sub: string, authType: 'w3'}>}
+ */
+async function getIndetifiersW3(token) {
+  const payload = await verifyW3JWT(token);
+  const homepayUserId = await resolveW3UserToHomepayUser(payload.sub);
+
+  return {
+    userId: homepayUserId,
+    w3Sub: payload.sub,
+    authType: 'w3'
+  };
+}
+
+/**
+ * Get identifiers with dual-auth routing
+ * @param {Object} headers - Request headers
+ * @returns {Promise<{userId: string|null, w3Sub: string|null, authType?: string}>}
+ */
+async function getIndetifiers(headers) {
+  const token = extractToken(headers);
+
+  if (!token) {
+    return { userId: null, w3Sub: null };
+  }
+
+  const authMode = process.env.AUTH_MODE || 'cognito';
+
+  switch (authMode) {
+    case 'cognito':
+      return await getIndetifiersCognito(token);
+
+    case 'w3':
+      return await getIndetifiersW3(token);
+
+    case 'dual':
+      // Try W3 first, fall back to Cognito on failure
+      try {
+        return await getIndetifiersW3(token);
+      } catch (error) {
+        console.warn(
+          'Dual auth: W3 validation failed, falling back to Cognito.',
+          `Error: ${error.message}`
+        );
+        return await getIndetifiersCognito(token);
+      }
+
+    default:
+      throw new Error(`Invalid AUTH_MODE: ${authMode}`);
   }
-  
-  return { userId: null };
 }
 
 async function getUser(userId, options = {}, noCredentials = false) {
@@ -106,7 +158,7 @@ function getUserInstitutionIds(user) {
 }
 
 module.exports = {
-  decodeIdToken,
+  decodeIdToken, // Re-exported from authUtils.cognito for backward compatibility
   getIndetifiers,
   getUser,
   getUserType,

package/w3home-utils/authUtils.w3.js

@@ -0,0 +1,62 @@
+/**
+ * W3 Platform JWT Authentication Utilities
+ *
+ * Validates W3 platform JWTs using jose library with RS256 signature verification.
+ * Uses Redis-cached JWKS to reduce remote fetches.
+ */
+
+const { createLocalJWKSet, jwtVerify } = require('jose');
+const { getCachedJWKS } = require('./cacheUtils');
+
+/**
+ * Verify W3 platform JWT
+ *
+ * @param {string} token - JWT token to verify
+ * @returns {Promise<Object>} Decoded payload with { sub, iss, exp, iat, org, fullPayload }
+ * @throws {Error} If token is invalid, expired, or signature verification fails
+ */
+async function verifyW3JWT(token) {
+  const issuer = process.env.W3_ISSUER;
+
+  if (!issuer) {
+    throw new Error('W3_ISSUER environment variable not set');
+  }
+
+  try {
+    // Get JWKS (from Redis cache or fetch)
+    const jwks = await getCachedJWKS();
+
+    // Create local JWK Set for signature verification
+    const JWKS = createLocalJWKSet(jwks);
+
+    // Verify JWT with RS256 algorithm, issuer validation, and 5-minute clock tolerance
+    const { payload } = await jwtVerify(token, JWKS, {
+      issuer,
+      clockTolerance: 300, // 5 minutes (300 seconds)
+      algorithms: ['RS256']
+    });
+
+    // Return extracted claims plus full payload
+    return {
+      sub: payload.sub,
+      iss: payload.iss,
+      exp: payload.exp,
+      iat: payload.iat,
+      org: payload.org,
+      fullPayload: payload
+    };
+  } catch (error) {
+    // Log error details for debugging
+    console.error('W3 JWT verification failed:', {
+      code: error.code,
+      message: error.message
+    });
+
+    // Re-throw for caller to handle
+    throw error;
+  }
+}
+
+module.exports = {
+  verifyW3JWT
+};

package/w3home-utils/cacheUtils.js

@@ -0,0 +1,101 @@
+/**
+ * Cache Utilities for W3 JWT Authentication
+ *
+ * Provides Redis singleton client and JWKS caching layer.
+ */
+
+const Redis = require('ioredis');
+
+// Redis singleton instance
+let redisClient = null;
+
+/**
+ * Get Redis client singleton
+ *
+ * @returns {Redis} Singleton Redis client instance
+ */
+function getRedisClient() {
+  if (!redisClient) {
+    const redisConfig = {
+      host: process.env.REDIS_HOST || process.env.CACHE_URL || 'localhost',
+      port: parseInt(process.env.REDIS_PORT || process.env.CACHE_PORT || '6379', 10),
+      lazyConnect: true,
+      enableOfflineQueue: true,
+      maxRetriesPerRequest: 3,
+      retryStrategy(times) {
+        const delay = Math.min(times * 50, 2000);
+        return delay;
+      }
+    };
+
+    // Enable TLS if configured
+    if (process.env.REDIS_TLS === 'true') {
+      redisConfig.tls = {};
+    }
+
+    redisClient = new Redis(redisConfig);
+
+    // Event handlers
+    redisClient.on('error', (err) => {
+      console.error('Redis error:', err.message);
+    });
+
+    redisClient.on('reconnecting', () => {
+      console.log('Redis reconnecting...');
+    });
+  }
+
+  return redisClient;
+}
+
+/**
+ * Get cached JWKS from Redis or fetch from W3 platform
+ *
+ * @returns {Promise<Object>} JWKS object with keys array
+ * @throws {Error} If fetch fails (does not throw on Redis errors - falls back to fetch)
+ */
+async function getCachedJWKS() {
+  const CACHE_KEY = 'w3:jwks:v1';
+  const CACHE_TTL = 600; // 10 minutes
+  const jwksUrl = process.env.W3_JWKS_URL;
+
+  if (!jwksUrl) {
+    throw new Error('W3_JWKS_URL environment variable not set');
+  }
+
+  try {
+    const redis = getRedisClient();
+    const cached = await redis.get(CACHE_KEY);
+
+    if (cached) {
+      return JSON.parse(cached);
+    }
+  } catch (redisError) {
+    console.error('Redis cache read failed, falling back to direct fetch:', redisError.message);
+  }
+
+  // Cache miss or Redis error - fetch from URL
+  const response = await fetch(jwksUrl);
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch JWKS from ${jwksUrl}: ${response.status} ${response.statusText}`);
+  }
+
+  const jwks = await response.json();
+
+  // Cache in Redis (fire-and-forget - don't wait or throw on error)
+  try {
+    const redis = getRedisClient();
+    await redis.setex(CACHE_KEY, CACHE_TTL, JSON.stringify(jwks));
+  } catch (cacheWriteError) {
+    console.error('Failed to cache JWKS in Redis:', cacheWriteError.message);
+    // Continue - we have the JWKS from fetch
+  }
+
+  return jwks;
+}
+
+module.exports = {
+  getRedisClient,
+  getCachedJWKS
+};

package/w3home-utils/index.js

@@ -12,6 +12,11 @@ const {
   getUserInstitutionIds
 } = require('./authUtils');
 
+const { verifyW3JWT } = require('./authUtils.w3');
+const { getIndetifiersCognito, decodeIdToken: decodeIdTokenCognito } = require('./authUtils.cognito');
+const { resolveW3UserToHomepayUser, clearMappingCache } = require('./mappingUtils');
+const { getRedisClient, getCachedJWKS } = require('./cacheUtils');
+
 const {
   authorize,
   withAuthorization,
@@ -59,7 +64,7 @@ const corsHeaders = {
 };
 
 module.exports = {
-  // Auth
+  // Auth (Legacy Cognito)
   decodeIdToken,
   getIndetifiers,
   getUser,
@@ -67,7 +72,15 @@ module.exports = {
   clearUserCache,
   getUserInstitutionId,
   getUserInstitutionIds,
-  
+
+  // W3 Platform Auth (New)
+  verifyW3JWT,
+  getIndetifiersCognito,
+  resolveW3UserToHomepayUser,
+  clearMappingCache,
+  getRedisClient,
+  getCachedJWKS,
+
   // Authorization
   authorize,
   withAuthorization,