w3home-utils 1.0.0

package/README.md

@@ -0,0 +1,193 @@
+# w3home-utils
+
+W3Home Utilities - Authorization, Activity Logging, and Authentication utilities for HomePay services.
+
+## Installation
+
+```bash
+npm install w3home-utils
+```
+
+## Usage
+
+```javascript
+const {
+  // Authentication
+  getIndetifiers,
+  getUser,
+  getUserType,
+  decodeIdToken,
+  
+  // Authorization
+  authorize,
+  withAuthorization,
+  authorizeBuyer,
+  authorizeBackofficeProject,
+  ROLES,
+  UserType,
+  
+  // Activity Logging
+  logActivity,
+  logPostActivity,
+  withActivityLogging,
+  
+  // Common
+  corsHeaders
+} = require('w3home-utils');
+```
+
+## Authentication
+
+### Get User Identifiers from Request Headers
+
+```javascript
+const { getIndetifiers } = require('w3home-utils');
+
+const handler = async (event) => {
+  const { userId } = await getIndetifiers(event.headers);
+  if (!userId) {
+    return { statusCode: 401, body: JSON.stringify({ error: 'Unauthorized' }) };
+  }
+  // ... continue with userId
+};
+```
+
+### Get User Details
+
+```javascript
+const { getUser, getUserType } = require('w3home-utils');
+
+const handler = async (event) => {
+  const { userId } = await getIndetifiers(event.headers);
+  const user = await getUser(userId);
+  const userType = getUserType(user); // 'BUYER' | 'BACKOFFICE_USER' | 'BACKOFFICE_ADMIN'
+  // ...
+};
+```
+
+## Authorization
+
+### Using withAuthorization Wrapper
+
+```javascript
+const { withAuthorization, getUser } = require('w3home-utils');
+
+const myHandler = async (event, context) => {
+  // event.authContext contains authorization result
+  const { authorized, role, permissions } = event.authContext;
+  // ...
+};
+
+module.exports.handler = withAuthorization(myHandler, {
+  resource: 'projects',
+  getResourceId: (event) => event.pathParameters?.projectId,
+  getUser: (userId) => getUser(userId)
+});
+```
+
+### Manual Authorization Check
+
+```javascript
+const { authorize, getUserType } = require('w3home-utils');
+
+const handler = async (event) => {
+  const { userId } = await getIndetifiers(event.headers);
+  const user = await getUser(userId);
+  
+  const authResult = await authorize({
+    userId,
+    userType: getUserType(user),
+    resource: 'projects',
+    action: 'READ',
+    resourceId: event.pathParameters?.projectId,
+    user
+  });
+  
+  if (!authResult.authorized) {
+    return { statusCode: 403, body: JSON.stringify({ error: 'Forbidden' }) };
+  }
+  // ...
+};
+```
+
+## Activity Logging
+
+### Using withActivityLogging Wrapper
+
+```javascript
+const { withActivityLogging, getIndetifiers } = require('w3home-utils');
+
+const myHandler = async (event, context) => {
+  // Your handler logic
+  return { statusCode: 200, body: JSON.stringify({ success: true }) };
+};
+
+module.exports.handler = withActivityLogging(myHandler, {
+  resource: 'payments',
+  extractUserId: async (event) => {
+    const { userId } = await getIndetifiers(event.headers);
+    return userId;
+  }
+});
+```
+
+### Manual Activity Logging
+
+```javascript
+const { logPostActivity } = require('w3home-utils');
+
+const handler = async (event, context) => {
+  const { userId } = await getIndetifiers(event.headers);
+  
+  // ... perform action ...
+  
+  logPostActivity({
+    event,
+    userId,
+    action: 'CREATE',
+    resource: 'payments',
+    statusCode: 200,
+    context
+  });
+};
+```
+
+## Roles & Permissions
+
+```javascript
+const { ROLES, UserType, hasPermission } = require('w3home-utils');
+
+// Check if user has permission
+const canRead = await hasPermission(userId, 'projects', 'READ');
+
+// Get role definitions
+console.log(ROLES.BACKOFFICE_ADMIN);
+// { id: 'BACKOFFICE_ADMIN', permissions: [...] }
+
+// User types
+console.log(UserType.BUYER);         // 'BUYER'
+console.log(UserType.BACKOFFICE_USER); // 'BACKOFFICE_USER'
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `USERS_TABLE` | `w3HomeUsers` | DynamoDB table for users |
+| `ROLES_TABLE` | `w3home-roles` | DynamoDB table for roles |
+| `CONFIG_TABLE` | `w3home-config` | DynamoDB table for config |
+| `STAGE` | `dev` | Environment stage |
+
+## Peer Dependencies
+
+This package requires `aws-sdk` as a peer dependency. In Lambda, this is already available. For local development:
+
+```bash
+npm install aws-sdk --save-dev
+```
+
+## License
+
+UNLICENSED - HomePay Internal Use Only
+
+

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "w3home-utils",
+  "version": "1.0.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",
+    "prepublishOnly": "npm test",
+    "seed:dev": "node seed-tables.js dev",
+    "seed:prd": "node seed-tables.js prd"
+  },
+  "dependencies": {
+    "jsonwebtoken": "^9.0.2"
+  },
+  "peerDependencies": {
+    "aws-sdk": "^2.1000.0"
+  },
+  "devDependencies": {
+    "aws-sdk": "^2.1692.0"
+  },
+  "keywords": [
+    "authorization",
+    "authentication",
+    "activity-logging",
+    "w3home",
+    "homepay",
+    "lambda",
+    "aws"
+  ],
+  "author": "HomePay",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/homepay/w3home-utils.git"
+  }
+}

package/w3home-utils/activityLogger.js

@@ -0,0 +1,129 @@
+/**
+ * Activity Logger Module
+ */
+
+const LOG_PREFIX = 'ACTIVITY_LOG';
+
+function extractIdentifiers(event, userId) {
+  const identifiers = { userId, projectId: null, apartmentId: null, customerId: null, paymentId: null };
+
+  if (event.pathParameters) {
+    identifiers.projectId = event.pathParameters.projectId || null;
+    identifiers.apartmentId = event.pathParameters.apartmentId || null;
+    identifiers.customerId = event.pathParameters.customerId || null;
+    identifiers.paymentId = event.pathParameters.paymentId || null;
+  }
+
+  if (!identifiers.projectId || !identifiers.apartmentId) {
+    try {
+      const body = typeof event.body === 'string' ? JSON.parse(event.body) : event.body;
+      if (body) {
+        identifiers.projectId = identifiers.projectId || body.projectId || null;
+        identifiers.apartmentId = identifiers.apartmentId || body.apartmentId || null;
+        identifiers.customerId = identifiers.customerId || body.customerId || null;
+        identifiers.paymentId = identifiers.paymentId || body.paymentId || null;
+      }
+    } catch {}
+  }
+
+  return identifiers;
+}
+
+function extractRequestContext(event) {
+  const httpContext = event.requestContext?.http || event.requestContext || {};
+  return {
+    method: httpContext.method || event.httpMethod || 'UNKNOWN',
+    path: event.rawPath || event.path || httpContext.path || 'UNKNOWN',
+    sourceIp: httpContext.sourceIp || event.requestContext?.identity?.sourceIp || null,
+    userAgent: httpContext.userAgent || event.headers?.['user-agent'] || event.headers?.['User-Agent'] || null
+  };
+}
+
+function logActivity({ event, userId, 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,
+    projectId: identifiers.projectId,
+    apartmentId: identifiers.apartmentId,
+    action,
+    resource,
+    statusCode,
+    method: requestContext.method,
+    path: requestContext.path,
+    sourceIp: requestContext.sourceIp,
+    userAgent: requestContext.userAgent,
+    requestId: context?.awsRequestId || null,
+    functionName: context?.functionName || null,
+    stage: process.env.STAGE || 'dev',
+    body: event.body,
+    metadata
+  };
+
+  console.log(JSON.stringify(activityLog));
+}
+
+function logPostActivity(params) {
+  logActivity(params);
+}
+
+function logReadActivity(params) {
+  logActivity({ ...params, action: params.action || 'READ' });
+}
+
+function withActivityLogging(handler, config = {}) {
+  return async (event, context) => {
+    const resource = config.resource || 'unknown';
+    let userId = null;
+    let action = 'CREATE';
+    let statusCode = null;
+    let metadata = {};
+
+    try {
+      if (config.extractUserId) userId = await config.extractUserId(event);
+      
+      if (config.extractAction) {
+        action = await config.extractAction(event);
+      } else {
+        const method = event.httpMethod || event.requestContext?.http?.method || 'POST';
+        const mapping = { 'GET': 'READ', 'POST': 'CREATE', 'PUT': 'UPDATE', 'PATCH': 'UPDATE', 'DELETE': 'DELETE' };
+        action = mapping[method] || 'CREATE';
+      }
+
+      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 });
+
+      return result;
+    } catch (error) {
+      statusCode = 500;
+      metadata = { error: error.message };
+      logActivity({ event, userId, action, resource, statusCode, metadata, context });
+      throw error;
+    }
+  };
+}
+
+function createResourceLogger(resource) {
+  return {
+    log: (params) => logActivity({ ...params, resource }),
+    logPost: (params) => logPostActivity({ ...params, resource }),
+    logRead: (params) => logReadActivity({ ...params, resource })
+  };
+}
+
+module.exports = {
+  logActivity,
+  logPostActivity,
+  logReadActivity,
+  withActivityLogging,
+  createResourceLogger,
+  extractIdentifiers,
+  LOG_PREFIX
+};
+

package/w3home-utils/authUtils.js

@@ -0,0 +1,118 @@
+/**
+ * Authentication Utilities
+ */
+
+const jwt = require('jsonwebtoken');
+const AWS = require('aws-sdk');
+
+const USERS_TABLE = process.env.USERS_TABLE || 'w3HomeUsers';
+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;
+  }
+}
+
+async function getIndetifiers(headers) {
+  let authorizationToken = '';
+  
+  if (headers['Authorization']) {
+    const parts = headers['Authorization'].split(' ');
+    authorizationToken = parts.length > 1 ? parts[1] : parts[0];
+  }
+  if (!authorizationToken && headers['Token']) {
+    authorizationToken = headers['Token'];
+  }
+  if (!authorizationToken && headers['authorization']) {
+    const parts = headers['authorization'].split(' ');
+    authorizationToken = parts.length > 1 ? parts[1] : parts[0];
+  }
+  if (!authorizationToken && headers['token']) {
+    authorizationToken = headers['token'];
+  }
+  
+  if (authorizationToken) {
+    const sub = decodeIdToken(authorizationToken);
+    if (sub) return { userId: sub };
+  }
+  
+  return { userId: null };
+}
+
+async function getUser(userId, options = {}, noCredentials = false) {
+  if (!userId) return null;
+  
+  const useCache = !options.noCache && !noCredentials;
+  const now = Date.now();
+  
+  if (useCache) {
+    const cached = userCache.get(userId);
+    if (cached && cached.expiry > now) return cached.user;
+  }
+  
+  try {
+    const result = await dynamodb.get({
+      TableName: USERS_TABLE,
+      Key: { id: userId }
+    }).promise();
+    
+    if (!result.Item) return null;
+    
+    if (useCache) {
+      userCache.set(userId, { user: result.Item, expiry: now + USER_CACHE_TTL });
+    }
+    
+    return result.Item;
+  } catch (error) {
+    console.error('Error fetching user:', error.message);
+    return null;
+  }
+}
+
+function getUserType(user) {
+  if (!user) return null;
+  if (user.userType) return user.userType;
+  
+  const role = user.role;
+  if (role === 'ADMIN' || role === 'BACKOFFICE_ADMIN') return 'BACKOFFICE_ADMIN';
+  if (role === 'USER' || role === 'BACKOFFICE_USER') return 'BACKOFFICE_USER';
+  if (user.customerUserId || (!user.institutionId && !user.institutionIds)) return 'BUYER';
+  
+  return 'BACKOFFICE_USER';
+}
+
+function clearUserCache(userId) {
+  userId ? userCache.delete(userId) : userCache.clear();
+}
+
+function getUserInstitutionId(user) {
+  if (!user) return null;
+  return user.primaryInstitutionId || user.institutionId || (user.institutionIds?.[0]) || null;
+}
+
+function getUserInstitutionIds(user) {
+  if (!user) return [];
+  if (user.institutionIds && Array.isArray(user.institutionIds)) return user.institutionIds;
+  if (user.institutionId) return [user.institutionId];
+  return [];
+}
+
+module.exports = {
+  decodeIdToken,
+  getIndetifiers,
+  getUser,
+  getUserType,
+  clearUserCache,
+  getUserInstitutionId,
+  getUserInstitutionIds,
+  USER_CACHE_TTL
+};
+

package/w3home-utils/authorization/backofficeAuthorization.js

@@ -0,0 +1,154 @@
+/**
+ * Backoffice Authorization
+ */
+
+const AWS = require('aws-sdk');
+
+const PROJECT_TABLE = process.env.PROJECT_TABLE || process.env.PROJECTS_TABLE || 'w3HomeProjects';
+const dynamodb = new AWS.DynamoDB.DocumentClient({ region: 'eu-west-1' });
+
+async function getProjectById(projectId) {
+  try {
+    const result = await dynamodb.get({
+      TableName: PROJECT_TABLE,
+      Key: { id: projectId }
+    }).promise();
+    return result.Item || null;
+  } catch (error) {
+    console.error('Error fetching project:', error);
+    return null;
+  }
+}
+
+function getUserOrganizations(user) {
+  if (user.institutionIds && Array.isArray(user.institutionIds) && user.institutionIds.length > 0) {
+    return user.institutionIds;
+  }
+  if (user.institutionId) return [user.institutionId];
+  return [];
+}
+
+function getProjectOrganizations(project) {
+  return [
+    project.financialInstitution,
+    project.insuranceInstitution,
+    project.constructorInstitution,
+    project.constructorInstitution2
+  ].filter(Boolean);
+}
+
+async function authorizeBackofficeProject(user, projectId) {
+  const project = await getProjectById(projectId);
+  
+  if (!project) {
+    return { authorized: false, error: 'PROJECT_NOT_FOUND', message: 'Project does not exist' };
+  }
+  
+  const userOrgs = getUserOrganizations(user);
+  if (userOrgs.length === 0) {
+    return { authorized: false, error: 'NO_ORGANIZATION', message: 'User is not associated with any organization' };
+  }
+  
+  const projectOrgs = getProjectOrganizations(project);
+  const matchingOrg = userOrgs.find(orgId => projectOrgs.includes(orgId));
+  
+  if (!matchingOrg) {
+    return { authorized: false, error: 'ORG_NOT_IN_PROJECT', message: 'User organization does not participate in this project' };
+  }
+  
+  const isProjectOwner = project.creatorInstitutionId === matchingOrg || project.userId === user.id;
+  const userRole = user.role || 'USER';
+  const isAdmin = userRole === 'ADMIN' || userRole === 'BACKOFFICE_ADMIN';
+  
+  const basePermissions = isProjectOwner ? ['READ', 'CREATE', 'UPDATE', 'DELETE'] : ['READ', 'CREATE', 'UPDATE'];
+  const permissions = isAdmin ? [...basePermissions, 'MANAGE_USERS'] : basePermissions;
+  
+  return {
+    authorized: true,
+    accessLevel: isProjectOwner ? 'OWNER' : 'PARTICIPANT',
+    organizationId: matchingOrg,
+    role: userRole,
+    isAdmin,
+    permissions,
+    projectId
+  };
+}
+
+async function getAccessibleProjects(user) {
+  const userOrgs = getUserOrganizations(user);
+  if (userOrgs.length === 0) return [];
+  
+  const allProjects = [];
+  const seenIds = new Set();
+  
+  const indexes = [
+    { indexName: 'constructorInstitution-index', attributeName: 'constructorInstitution' },
+    { indexName: 'financialInstitution-index', attributeName: 'financialInstitution' },
+    { indexName: 'insuranceInstitution-index', attributeName: 'insuranceInstitution' }
+  ];
+  
+  for (const orgId of userOrgs) {
+    for (const { indexName, attributeName } of indexes) {
+      try {
+        const result = await dynamodb.query({
+          TableName: PROJECT_TABLE,
+          IndexName: indexName,
+          KeyConditionExpression: `#inst = :orgId`,
+          ExpressionAttributeNames: { '#inst': attributeName },
+          ExpressionAttributeValues: { ':orgId': orgId }
+        }).promise();
+        
+        for (const project of (result.Items || [])) {
+          if (!seenIds.has(project.id)) {
+            allProjects.push(project);
+            seenIds.add(project.id);
+          }
+        }
+      } catch {}
+    }
+  }
+  
+  return allProjects;
+}
+
+function canManageUsers(user) {
+  const role = user.role || 'USER';
+  return role === 'ADMIN' || role === 'BACKOFFICE_ADMIN';
+}
+
+async function authorizeUserManagement(actor, targetUserId, action) {
+  if (!canManageUsers(actor)) {
+    return { authorized: false, error: 'NOT_ADMIN', message: 'Only administrators can manage users' };
+  }
+  if (action === 'DELETE' && actor.id === targetUserId) {
+    return { authorized: false, error: 'CANNOT_DELETE_SELF', message: 'Cannot delete your own account' };
+  }
+  if (action === 'CHANGE_ROLE' && actor.id === targetUserId) {
+    return { authorized: false, error: 'CANNOT_CHANGE_OWN_ROLE', message: 'Cannot change your own role' };
+  }
+  return { authorized: true, permissions: ['CREATE_USER', 'UPDATE_USER', 'DELETE_USER', 'CHANGE_ROLE'] };
+}
+
+async function validateUserAccessToProject(apartment, user) {
+  if (!apartment.projectId) return false;
+  const result = await authorizeBackofficeProject(user, apartment.projectId);
+  return result.authorized;
+}
+
+async function authorizeBackofficeAction(user, projectId, resource, action) {
+  const projectAuth = await authorizeBackofficeProject(user, projectId);
+  if (!projectAuth.authorized) return projectAuth;
+  
+  if (!projectAuth.permissions.includes(action.toUpperCase())) {
+    return { authorized: false, error: 'ACTION_NOT_ALLOWED', message: `No permission to ${action}` };
+  }
+  
+  if (resource === 'user' && !canManageUsers(user)) {
+    return { authorized: false, error: 'NOT_ADMIN', message: 'Only administrators can manage users' };
+  }
+  
+  return { authorized: true, ...projectAuth, resource, action };
+}
+
+module.exports = { authorizeBackofficeProject, getAccessibleProjects, canManageUsers, authorizeUserManagement, validateUserAccessToProject, authorizeBackofficeAction, getUserOrganizations, getProjectOrganizations };
+

package/w3home-utils/authorization/buyerAuthorization.js

@@ -0,0 +1,97 @@
+/**
+ * Buyer Authorization
+ */
+
+const AWS = require('aws-sdk');
+
+const CUSTOMERS_TABLE = process.env.CUSTOMERS_TABLE || 'w3HomeCustomers';
+const dynamodb = new AWS.DynamoDB.DocumentClient({ region: 'eu-west-1' });
+
+async function getCustomersByUserId(userId) {
+  try {
+    const result = await dynamodb.query({
+      TableName: CUSTOMERS_TABLE,
+      IndexName: 'customerUserId-index',
+      KeyConditionExpression: 'customerUserId = :userId',
+      ExpressionAttributeValues: { ':userId': userId }
+    }).promise();
+    return result.Items || [];
+  } catch (error) {
+    console.error('Error fetching customers:', error);
+    return [];
+  }
+}
+
+async function getCustomerByUserIdAndApartment(userId, apartmentId) {
+  const customers = await getCustomersByUserId(userId);
+  return customers.find(c => c.apartmentId === apartmentId) || null;
+}
+
+async function validateBuyerAccess(userId, apartmentId) {
+  const customer = await getCustomerByUserIdAndApartment(userId, apartmentId);
+  if (!customer) return false;
+  if (customer.status && customer.status !== 'ACTIVE') return false;
+  return true;
+}
+
+async function authorizeBuyer(userId, apartmentId) {
+  const customers = await getCustomersByUserId(userId);
+  
+  if (!customers || customers.length === 0) {
+    return { authorized: false, error: 'NO_CUSTOMER_RECORD', message: 'User is not registered as a customer' };
+  }
+  
+  const linkedCustomer = customers.find(c => c.apartmentId === apartmentId && (!c.status || c.status === 'ACTIVE'));
+  
+  if (!linkedCustomer) {
+    return { authorized: false, error: 'NOT_LINKED_TO_APARTMENT', message: 'User is not linked to this apartment' };
+  }
+  
+  return {
+    authorized: true,
+    customerId: linkedCustomer.id,
+    apartmentId: linkedCustomer.apartmentId,
+    projectId: linkedCustomer.projectId,
+    permissions: ['READ_APARTMENT', 'READ_PAYMENTS', 'READ_VOUCHERS', 'READ_DOCUMENTS', 'UPDATE_SELF']
+  };
+}
+
+async function getBuyerAccessibleApartments(userId) {
+  const customers = await getCustomersByUserId(userId);
+  return customers
+    .filter(c => !c.status || c.status === 'ACTIVE')
+    .map(c => ({ apartmentId: c.apartmentId, projectId: c.projectId, customerId: c.id }));
+}
+
+async function authorizeBuyerAction(userId, apartmentId, resource, action, context = {}) {
+  const accessResult = await authorizeBuyer(userId, apartmentId);
+  if (!accessResult.authorized) return accessResult;
+  
+  const buyerPermissions = {
+    apartment: ['READ'],
+    payment: ['READ'],
+    voucher: ['READ'],
+    document: ['READ'],
+    customer: ['READ', 'UPDATE']
+  };
+  
+  const resourcePerms = buyerPermissions[resource.toLowerCase()];
+  if (!resourcePerms) {
+    return { authorized: false, error: 'RESOURCE_NOT_ALLOWED', message: `Buyers cannot access resource: ${resource}` };
+  }
+  
+  if (!resourcePerms.includes(action.toUpperCase())) {
+    return { authorized: false, error: 'ACTION_NOT_ALLOWED', message: `Buyers cannot perform ${action} on ${resource}` };
+  }
+  
+  if (resource.toLowerCase() === 'customer' && action.toUpperCase() === 'UPDATE') {
+    if (context.customerId && context.customerId !== accessResult.customerId) {
+      return { authorized: false, error: 'NOT_OWNER', message: 'Buyers can only update their own profile' };
+    }
+  }
+  
+  return { authorized: true, ...accessResult, resource, action };
+}
+
+module.exports = { authorizeBuyer, getBuyerAccessibleApartments, validateBuyerAccess, authorizeBuyerAction, getCustomersByUserId, getCustomerByUserIdAndApartment };
+

package/w3home-utils/authorization/index.js

@@ -0,0 +1,87 @@
+/**
+ * Authorization Module
+ */
+
+const { authorizeBuyer, getBuyerAccessibleApartments, validateBuyerAccess, authorizeBuyerAction } = require('./buyerAuthorization');
+const { authorizeBackofficeProject, getAccessibleProjects, canManageUsers, authorizeUserManagement, validateUserAccessToProject, authorizeBackofficeAction } = require('./backofficeAuthorization');
+const { getRoles, getRole, hasPermission, invalidateCache, invalidateRolesCache, getCacheStats } = require('./rolesLoader');
+const { UserType, BackofficeRole, Actions, Resources, ROLES, getRoleById, roleHasPermission, getRolePermissions } = require('./roles');
+
+async function authorize(params) {
+  const { userId, userType, resource, action, resourceId, context = {}, user } = params;
+  
+  if (!userId && !user) return { authorized: false, error: 'USER_NOT_FOUND' };
+  
+  switch (userType) {
+    case 'BUYER':
+      return await authorizeBuyerAction(userId, resourceId, resource, action, context);
+    case 'BACKOFFICE_ADMIN':
+    case 'ADMIN':
+      return { authorized: true, accessLevel: 'FULL', role: 'ADMIN', isAdmin: true, permissions: ['READ', 'CREATE', 'UPDATE', 'DELETE', 'MANAGE_USERS'] };
+    case 'BACKOFFICE_USER':
+    case 'USER':
+      if (!user) return { authorized: false, error: 'USER_OBJECT_REQUIRED' };
+      return await authorizeBackofficeAction(user, resourceId, resource, action);
+    default:
+      return { authorized: false, error: 'UNKNOWN_USER_TYPE' };
+  }
+}
+
+function mapHttpMethodToAction(method) {
+  return { 'GET': 'READ', 'POST': 'CREATE', 'PUT': 'UPDATE', 'PATCH': 'UPDATE', 'DELETE': 'DELETE' }[method] || 'READ';
+}
+
+function withAuthorization(handler, config) {
+  return async (event, context) => {
+    const { userType, resource, getResourceId, getUser } = config;
+    const userId = event.requestContext?.authorizer?.claims?.sub;
+    
+    if (!userId) return { statusCode: 401, body: JSON.stringify({ error: 'UNAUTHORIZED' }), headers: { 'Access-Control-Allow-Origin': '*' } };
+    
+    const resourceId = getResourceId ? getResourceId(event) : null;
+    let user = null;
+    if (getUser) {
+      user = await getUser(userId);
+      if (!user) return { statusCode: 401, body: JSON.stringify({ error: 'UNAUTHORIZED' }), headers: { 'Access-Control-Allow-Origin': '*' } };
+    }
+    
+    const action = mapHttpMethodToAction(event.httpMethod || event.requestContext?.http?.method);
+    const authResult = await authorize({ userId, userType: userType || user?.userType, resource, action, resourceId, user });
+    
+    if (!authResult.authorized) return { statusCode: 403, body: JSON.stringify({ error: 'FORBIDDEN', message: authResult.message }), headers: { 'Access-Control-Allow-Origin': '*' } };
+    
+    event.authContext = authResult;
+    return handler(event, context);
+  };
+}
+
+module.exports = {
+  authorize,
+  withAuthorization,
+  mapHttpMethodToAction,
+  authorizeBuyer,
+  getBuyerAccessibleApartments,
+  validateBuyerAccess,
+  authorizeBuyerAction,
+  authorizeBackofficeProject,
+  getAccessibleProjects,
+  canManageUsers,
+  authorizeUserManagement,
+  validateUserAccessToProject,
+  authorizeBackofficeAction,
+  ROLES,
+  UserType,
+  BackofficeRole,
+  Actions,
+  Resources,
+  getRoleById,
+  roleHasPermission,
+  getRolePermissions,
+  getRoles,
+  getRole,
+  hasPermission,
+  invalidateCache,
+  invalidateRolesCache,
+  getCacheStats
+};
+

package/w3home-utils/authorization/roles.js

@@ -0,0 +1,75 @@
+/**
+ * Roles & Permissions
+ */
+
+const UserType = { BACKOFFICE_ADMIN: 'BACKOFFICE_ADMIN', BACKOFFICE_USER: 'BACKOFFICE_USER', BUYER: 'BUYER' };
+const BackofficeRole = { ADMIN: 'ADMIN', USER: 'USER' };
+const Actions = { READ: 'READ', CREATE: 'CREATE', UPDATE: 'UPDATE', DELETE: 'DELETE', MANAGE: 'MANAGE' };
+const Resources = { PROJECT: 'project', APARTMENT: 'apartment', PAYMENT: 'payment', VOUCHER: 'voucher', CUSTOMER: 'customer', DOCUMENT: 'document', USER: 'user', INSTITUTION: 'institution' };
+
+const ROLES = {
+  BACKOFFICE_ADMIN: {
+    id: 'BACKOFFICE_ADMIN',
+    name: 'System Administrator',
+    userType: UserType.BACKOFFICE_ADMIN,
+    permissions: [
+      { resource: Resources.PROJECT, actions: [Actions.READ, Actions.CREATE, Actions.UPDATE, Actions.DELETE] },
+      { resource: Resources.APARTMENT, actions: [Actions.READ, Actions.CREATE, Actions.UPDATE, Actions.DELETE] },
+      { resource: Resources.PAYMENT, actions: [Actions.READ, Actions.CREATE, Actions.UPDATE, Actions.DELETE] },
+      { resource: Resources.CUSTOMER, actions: [Actions.READ, Actions.CREATE, Actions.UPDATE, Actions.DELETE] },
+      { resource: Resources.DOCUMENT, actions: [Actions.READ, Actions.CREATE, Actions.UPDATE, Actions.DELETE] },
+      { resource: Resources.USER, actions: [Actions.READ, Actions.CREATE, Actions.UPDATE, Actions.DELETE, Actions.MANAGE] }
+    ]
+  },
+  BACKOFFICE_USER: {
+    id: 'BACKOFFICE_USER',
+    name: 'Organization User',
+    userType: UserType.BACKOFFICE_USER,
+    permissions: [
+      { resource: Resources.PROJECT, actions: [Actions.READ, Actions.CREATE, Actions.UPDATE] },
+      { resource: Resources.APARTMENT, actions: [Actions.READ, Actions.CREATE, Actions.UPDATE] },
+      { resource: Resources.PAYMENT, actions: [Actions.READ, Actions.CREATE, Actions.UPDATE, Actions.DELETE] },
+      { resource: Resources.CUSTOMER, actions: [Actions.READ, Actions.CREATE, Actions.UPDATE] },
+      { resource: Resources.DOCUMENT, actions: [Actions.READ, Actions.CREATE, Actions.UPDATE, Actions.DELETE] }
+    ]
+  },
+  BUYER: {
+    id: 'BUYER',
+    name: 'Apartment Buyer',
+    userType: UserType.BUYER,
+    permissions: [
+      { resource: Resources.APARTMENT, actions: [Actions.READ] },
+      { resource: Resources.PAYMENT, actions: [Actions.READ] },
+      { resource: Resources.DOCUMENT, actions: [Actions.READ] },
+      { resource: Resources.CUSTOMER, actions: [Actions.READ, Actions.UPDATE] }
+    ]
+  }
+};
+
+const ROLE_ALIASES = { 'ADMIN': 'BACKOFFICE_ADMIN', 'USER': 'BACKOFFICE_USER' };
+
+function getRoleById(roleId) {
+  return ROLES[ROLE_ALIASES[roleId] || roleId] || null;
+}
+
+function roleHasPermission(roleId, resource, action) {
+  const role = getRoleById(roleId);
+  if (!role) return false;
+  const perm = role.permissions.find(p => p.resource === resource);
+  return perm ? perm.actions.includes(action) : false;
+}
+
+function getRolePermissions(roleId) {
+  const role = getRoleById(roleId);
+  if (!role) return [];
+  const permissions = [];
+  for (const perm of role.permissions) {
+    for (const action of perm.actions) {
+      permissions.push(`${perm.resource}:${action.toLowerCase()}`);
+    }
+  }
+  return permissions;
+}
+
+module.exports = { UserType, BackofficeRole, Actions, Resources, ROLES, ROLE_ALIASES, getRoleById, roleHasPermission, getRolePermissions };
+

package/w3home-utils/authorization/rolesLoader.js

@@ -0,0 +1,138 @@
+/**
+ * Roles Loader with Caching
+ */
+
+const AWS = require('aws-sdk');
+const { ROLES, getRoleById, roleHasPermission } = require('./roles');
+
+const ROLES_TABLE = process.env.ROLES_TABLE || 'w3home-roles';
+const CONFIG_TABLE = process.env.CONFIG_TABLE || 'w3home-config';
+const CACHE_TTL = 5 * 60 * 1000;
+const VERSION_CHECK_INTERVAL = 30 * 1000;
+
+const dynamodb = new AWS.DynamoDB.DocumentClient({ region: 'eu-west-1' });
+
+let rolesCache = null;
+let rolesCacheExpiry = 0;
+let permissionsMap = null;
+let cachedVersion = 0;
+let lastVersionCheck = 0;
+
+async function loadRolesFromDB() {
+  try {
+    const result = await dynamodb.scan({
+      TableName: ROLES_TABLE,
+      FilterExpression: 'SK = :sk',
+      ExpressionAttributeValues: { ':sk': 'METADATA' }
+    }).promise();
+    
+    const roles = {};
+    for (const item of (result.Items || [])) {
+      roles[item.id] = item;
+    }
+    return Object.keys(roles).length > 0 ? roles : ROLES;
+  } catch (error) {
+    console.error('Error loading roles:', error.message);
+    return ROLES;
+  }
+}
+
+function buildPermissionsMap(roles) {
+  const map = {};
+  for (const [roleId, role] of Object.entries(roles)) {
+    if (!role.permissions) continue;
+    for (const permission of role.permissions) {
+      if (typeof permission === 'string') {
+        if (permission.endsWith(':*')) {
+          const resource = permission.replace(':*', '');
+          ['read', 'create', 'update', 'delete'].forEach(action => { map[`${roleId}:${resource}:${action}`] = true; });
+        } else {
+          map[`${roleId}:${permission}`] = true;
+        }
+      } else if (permission.resource && permission.actions) {
+        for (const action of permission.actions) {
+          map[`${roleId}:${permission.resource}:${action.toLowerCase()}`] = true;
+        }
+      }
+    }
+  }
+  return map;
+}
+
+async function getCurrentVersion() {
+  try {
+    const result = await dynamodb.get({
+      TableName: CONFIG_TABLE,
+      Key: { PK: 'CONFIG', SK: 'ROLES_VERSION' }
+    }).promise();
+    return result.Item?.version || 0;
+  } catch { return cachedVersion; }
+}
+
+async function getRoles() {
+  const now = Date.now();
+  
+  if (rolesCache && now - lastVersionCheck > VERSION_CHECK_INTERVAL) {
+    try {
+      const currentVersion = await getCurrentVersion();
+      lastVersionCheck = now;
+      if (currentVersion !== cachedVersion && currentVersion > 0) {
+        rolesCache = null;
+        permissionsMap = null;
+        cachedVersion = currentVersion;
+      }
+    } catch {}
+  }
+  
+  if (rolesCache && now < rolesCacheExpiry) return rolesCache;
+  
+  rolesCache = await loadRolesFromDB();
+  permissionsMap = buildPermissionsMap(rolesCache);
+  rolesCacheExpiry = now + CACHE_TTL;
+  
+  return rolesCache;
+}
+
+async function getRole(roleId) {
+  const roles = await getRoles();
+  return roles[roleId] || getRoleById(roleId);
+}
+
+async function hasPermission(roleId, resource, action) {
+  if (!permissionsMap) await getRoles();
+  const key = `${roleId}:${resource}:${action.toLowerCase()}`;
+  return permissionsMap[key] === true || roleHasPermission(roleId, resource, action);
+}
+
+function invalidateCache() {
+  rolesCache = null;
+  permissionsMap = null;
+  rolesCacheExpiry = 0;
+}
+
+async function invalidateRolesCache() {
+  try {
+    await dynamodb.update({
+      TableName: CONFIG_TABLE,
+      Key: { PK: 'CONFIG', SK: 'ROLES_VERSION' },
+      UpdateExpression: 'ADD version :inc',
+      ExpressionAttributeValues: { ':inc': 1 }
+    }).promise();
+  } catch {}
+  invalidateCache();
+  cachedVersion = 0;
+  lastVersionCheck = 0;
+}
+
+function getCacheStats() {
+  return {
+    hasCachedRoles: !!rolesCache,
+    cachedRolesCount: rolesCache ? Object.keys(rolesCache).length : 0,
+    cacheExpiry: rolesCacheExpiry,
+    cachedVersion,
+    hasPermissionsMap: !!permissionsMap
+  };
+}
+
+module.exports = { getRoles, getRole, hasPermission, invalidateCache, invalidateRolesCache, getCacheStats, CACHE_TTL, VERSION_CHECK_INTERVAL };
+

package/w3home-utils/index.js

@@ -0,0 +1,111 @@
+/**
+ * w3home-utils - Common Utilities
+ */
+
+const {
+  decodeIdToken,
+  getIndetifiers,
+  getUser,
+  getUserType,
+  clearUserCache,
+  getUserInstitutionId,
+  getUserInstitutionIds
+} = require('./authUtils');
+
+const {
+  authorize,
+  withAuthorization,
+  mapHttpMethodToAction,
+  authorizeBuyer,
+  getBuyerAccessibleApartments,
+  validateBuyerAccess,
+  authorizeBuyerAction,
+  authorizeBackofficeProject,
+  getAccessibleProjects,
+  canManageUsers,
+  authorizeUserManagement,
+  validateUserAccessToProject,
+  authorizeBackofficeAction,
+  ROLES,
+  UserType,
+  BackofficeRole,
+  Actions,
+  Resources,
+  getRoleById,
+  roleHasPermission,
+  getRolePermissions,
+  getRoles,
+  getRole,
+  hasPermission,
+  invalidateCache,
+  invalidateRolesCache,
+  getCacheStats
+} = require('./authorization');
+
+const {
+  logActivity,
+  logPostActivity,
+  logReadActivity,
+  withActivityLogging,
+  createResourceLogger,
+  LOG_PREFIX
+} = require('./activityLogger');
+
+const corsHeaders = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Credentials': true,
+  'Access-Control-Allow-Headers': 'Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token',
+  'Access-Control-Allow-Methods': 'GET,POST,PUT,PATCH,DELETE,OPTIONS'
+};
+
+module.exports = {
+  // Auth
+  decodeIdToken,
+  getIndetifiers,
+  getUser,
+  getUserType,
+  clearUserCache,
+  getUserInstitutionId,
+  getUserInstitutionIds,
+  
+  // Authorization
+  authorize,
+  withAuthorization,
+  mapHttpMethodToAction,
+  authorizeBuyer,
+  getBuyerAccessibleApartments,
+  validateBuyerAccess,
+  authorizeBuyerAction,
+  authorizeBackofficeProject,
+  getAccessibleProjects,
+  canManageUsers,
+  authorizeUserManagement,
+  validateUserAccessToProject,
+  authorizeBackofficeAction,
+  ROLES,
+  UserType,
+  BackofficeRole,
+  Actions,
+  Resources,
+  getRoleById,
+  roleHasPermission,
+  getRolePermissions,
+  getRoles,
+  getRole,
+  hasPermission,
+  invalidateCache,
+  invalidateRolesCache,
+  getCacheStats,
+  
+  // Activity Logging
+  logActivity,
+  logPostActivity,
+  logReadActivity,
+  withActivityLogging,
+  createResourceLogger,
+  LOG_PREFIX,
+  
+  // Common
+  corsHeaders
+};
+