@valentine-efagene/qshelter-common 2.0.87 → 2.0.89

package/dist/generated/client/models/UserRole.d.ts

@@ -2,7 +2,8 @@ import type * as runtime from "@prisma/client/runtime/client";
 import type * as Prisma from "../internal/prismaNamespace.js";
 /**
  * Model UserRole
- *
+ * Legacy: Direct user-role assignment (global, not tenant-scoped)
+ * @deprecated Use TenantMembership for tenant-scoped role assignments
  */
 export type UserRoleModel = runtime.Types.Result.DefaultSelection<Prisma.$UserRolePayload>;
 export type AggregateUserRole = {

package/dist/generated/client/models/index.d.ts

@@ -12,6 +12,7 @@ export * from './ContractTermination';
 export * from './DeviceEndpoint';
 export * from './DocumentRequirementRule';
 export * from './DocumentTemplate';
+export * from './DocumentationPhase';
 export * from './DocumentationStep';
 export * from './DocumentationStepApproval';
 export * from './DocumentationStepDocument';
@@ -26,7 +27,9 @@ export * from './OfferLetter';
 export * from './PasswordReset';
 export * from './PaymentMethodChangeRequest';
 export * from './PaymentMethodPhaseDocument';
+export * from './PaymentMethodPhaseField';
 export * from './PaymentMethodPhaseStep';
+export * from './PaymentPhase';
 export * from './PaymentPlan';
 export * from './Permission';
 export * from './Property';
@@ -41,6 +44,8 @@ export * from './PropertyUnit';
 export * from './PropertyVariant';
 export * from './PropertyVariantAmenity';
 export * from './PropertyVariantMedia';
+export * from './QuestionnaireField';
+export * from './QuestionnairePhase';
 export * from './RefreshToken';
 export * from './Role';
 export * from './RolePermission';

package/dist/generated/client/models/index.js

@@ -12,6 +12,7 @@ export * from './ContractTermination';
 export * from './DeviceEndpoint';
 export * from './DocumentRequirementRule';
 export * from './DocumentTemplate';
+export * from './DocumentationPhase';
 export * from './DocumentationStep';
 export * from './DocumentationStepApproval';
 export * from './DocumentationStepDocument';
@@ -26,7 +27,9 @@ export * from './OfferLetter';
 export * from './PasswordReset';
 export * from './PaymentMethodChangeRequest';
 export * from './PaymentMethodPhaseDocument';
+export * from './PaymentMethodPhaseField';
 export * from './PaymentMethodPhaseStep';
+export * from './PaymentPhase';
 export * from './PaymentPlan';
 export * from './Permission';
 export * from './Property';
@@ -41,6 +44,8 @@ export * from './PropertyUnit';
 export * from './PropertyVariant';
 export * from './PropertyVariantAmenity';
 export * from './PropertyVariantMedia';
+export * from './QuestionnaireField';
+export * from './QuestionnairePhase';
 export * from './RefreshToken';
 export * from './Role';
 export * from './RolePermission';

package/dist/generated/client/models.d.ts

@@ -3,6 +3,7 @@ export type * from './models/Role.js';
 export type * from './models/Permission.js';
 export type * from './models/RolePermission.js';
 export type * from './models/UserRole.js';
+export type * from './models/TenantMembership.js';
 export type * from './models/Tenant.js';
 export type * from './models/ApiKey.js';
 export type * from './models/RefreshToken.js';

package/dist/src/events/index.d.ts

@@ -3,5 +3,7 @@ export * from './notifications/notification-event';
 export * from './notifications/event-publisher';
 export * from './payments/payment-event';
 export * from './payments/payment-publisher';
+export * from './policies/policy-event';
+export * from './policies/policy-publisher';
 export * from './bus/event-bus.types';
 export * from './bus/event-bus.service';

package/dist/src/events/index.js

@@ -5,6 +5,9 @@ export * from './notifications/event-publisher';
 // Payment events and publisher (SNS-based)
 export * from './payments/payment-event';
 export * from './payments/payment-publisher';
+// Policy sync events and publisher (SNS-based)
+export * from './policies/policy-event';
+export * from './policies/policy-publisher';
 // Event bus (multi-transport delivery)
 export * from './bus/event-bus.types';
 export * from './bus/event-bus.service';

package/dist/src/events/policies/index.d.ts

@@ -0,0 +1,2 @@
+export * from './policy-event';
+export * from './policy-publisher';

package/dist/src/events/policies/index.js

@@ -0,0 +1,2 @@
+export * from './policy-event';
+export * from './policy-publisher';

package/dist/src/events/policies/policy-event.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Policy Sync Event Types
+ *
+ * These events are published when role/permission data changes in RDS,
+ * triggering synchronization to DynamoDB for the authorizer.
+ */
+export declare enum PolicyEventType {
+    ROLE_CREATED = "POLICY.ROLE_CREATED",
+    ROLE_UPDATED = "POLICY.ROLE_UPDATED",
+    ROLE_DELETED = "POLICY.ROLE_DELETED",
+    PERMISSION_CREATED = "POLICY.PERMISSION_CREATED",
+    PERMISSION_UPDATED = "POLICY.PERMISSION_UPDATED",
+    PERMISSION_DELETED = "POLICY.PERMISSION_DELETED",
+    ROLE_PERMISSION_ASSIGNED = "POLICY.ROLE_PERMISSION_ASSIGNED",
+    ROLE_PERMISSION_REVOKED = "POLICY.ROLE_PERMISSION_REVOKED",
+    FULL_SYNC_REQUESTED = "POLICY.FULL_SYNC_REQUESTED"
+}
+export interface RoleData {
+    id: string;
+    name: string;
+    description?: string | null;
+}
+export interface PermissionData {
+    id: string;
+    name: string;
+    description?: string | null;
+    resource: string;
+    action: string;
+}
+export interface RolePermissionData {
+    roleId: string;
+    roleName: string;
+    permissions: Array<{
+        id: string;
+        resource: string;
+        action: string;
+    }>;
+}
+export interface PolicyEventMeta {
+    source: string;
+    timestamp: string;
+    correlationId?: string;
+    userId?: string;
+    tenantId?: string;
+}
+export interface PolicyEvent<T = unknown> {
+    eventType: PolicyEventType;
+    eventId: string;
+    timestamp: string;
+    tenantId?: string;
+    source: string;
+    data: T;
+    metadata?: Record<string, unknown>;
+}
+export interface RoleCreatedEvent extends PolicyEvent<RoleData> {
+    eventType: PolicyEventType.ROLE_CREATED;
+}
+export interface RoleUpdatedEvent extends PolicyEvent<RoleData> {
+    eventType: PolicyEventType.ROLE_UPDATED;
+}
+export interface RoleDeletedEvent extends PolicyEvent<{
+    roleId: string;
+    roleName: string;
+}> {
+    eventType: PolicyEventType.ROLE_DELETED;
+}
+export interface PermissionCreatedEvent extends PolicyEvent<PermissionData> {
+    eventType: PolicyEventType.PERMISSION_CREATED;
+}
+export interface PermissionUpdatedEvent extends PolicyEvent<PermissionData> {
+    eventType: PolicyEventType.PERMISSION_UPDATED;
+}
+export interface PermissionDeletedEvent extends PolicyEvent<{
+    permissionId: string;
+}> {
+    eventType: PolicyEventType.PERMISSION_DELETED;
+}
+export interface RolePermissionAssignedEvent extends PolicyEvent<RolePermissionData> {
+    eventType: PolicyEventType.ROLE_PERMISSION_ASSIGNED;
+}
+export interface RolePermissionRevokedEvent extends PolicyEvent<RolePermissionData> {
+    eventType: PolicyEventType.ROLE_PERMISSION_REVOKED;
+}
+export interface FullSyncRequestedEvent extends PolicyEvent<{
+    requestedBy: string;
+}> {
+    eventType: PolicyEventType.FULL_SYNC_REQUESTED;
+}
+export type AnyPolicyEvent = RoleCreatedEvent | RoleUpdatedEvent | RoleDeletedEvent | PermissionCreatedEvent | PermissionUpdatedEvent | PermissionDeletedEvent | RolePermissionAssignedEvent | RolePermissionRevokedEvent | FullSyncRequestedEvent;

package/dist/src/events/policies/policy-event.js

@@ -0,0 +1,22 @@
+/**
+ * Policy Sync Event Types
+ *
+ * These events are published when role/permission data changes in RDS,
+ * triggering synchronization to DynamoDB for the authorizer.
+ */
+export var PolicyEventType;
+(function (PolicyEventType) {
+    // Role events
+    PolicyEventType["ROLE_CREATED"] = "POLICY.ROLE_CREATED";
+    PolicyEventType["ROLE_UPDATED"] = "POLICY.ROLE_UPDATED";
+    PolicyEventType["ROLE_DELETED"] = "POLICY.ROLE_DELETED";
+    // Permission events
+    PolicyEventType["PERMISSION_CREATED"] = "POLICY.PERMISSION_CREATED";
+    PolicyEventType["PERMISSION_UPDATED"] = "POLICY.PERMISSION_UPDATED";
+    PolicyEventType["PERMISSION_DELETED"] = "POLICY.PERMISSION_DELETED";
+    // Role-Permission association events
+    PolicyEventType["ROLE_PERMISSION_ASSIGNED"] = "POLICY.ROLE_PERMISSION_ASSIGNED";
+    PolicyEventType["ROLE_PERMISSION_REVOKED"] = "POLICY.ROLE_PERMISSION_REVOKED";
+    // Bulk sync events
+    PolicyEventType["FULL_SYNC_REQUESTED"] = "POLICY.FULL_SYNC_REQUESTED";
+})(PolicyEventType || (PolicyEventType = {}));

package/dist/src/events/policies/policy-publisher.d.ts

@@ -0,0 +1,60 @@
+import { PolicyEventType, PolicyEventMeta, RoleData, PermissionData, RolePermissionData } from './policy-event';
+/**
+ * Configuration for the policy event publisher
+ */
+interface PolicyPublisherConfig {
+    region?: string;
+    endpoint?: string;
+    topicArn?: string;
+}
+/**
+ * Policy Event Publisher for sending policy sync events to SNS
+ * Used by user-service to notify policy-sync-service of changes
+ */
+export declare class PolicyEventPublisher {
+    private readonly snsClient;
+    private readonly topicArn;
+    private readonly serviceName;
+    constructor(serviceName: string, config?: PolicyPublisherConfig);
+    /**
+     * Publish a policy event to SNS
+     */
+    publish<T>(eventType: PolicyEventType, data: T, meta?: Partial<PolicyEventMeta>): Promise<string>;
+    /**
+     * Publish role created event
+     */
+    publishRoleCreated(role: RoleData, meta?: Partial<PolicyEventMeta>): Promise<string>;
+    /**
+     * Publish role updated event
+     */
+    publishRoleUpdated(role: RoleData, meta?: Partial<PolicyEventMeta>): Promise<string>;
+    /**
+     * Publish role deleted event
+     */
+    publishRoleDeleted(roleId: string, roleName: string, meta?: Partial<PolicyEventMeta>): Promise<string>;
+    /**
+     * Publish permission created event
+     */
+    publishPermissionCreated(permission: PermissionData, meta?: Partial<PolicyEventMeta>): Promise<string>;
+    /**
+     * Publish permission updated event
+     */
+    publishPermissionUpdated(permission: PermissionData, meta?: Partial<PolicyEventMeta>): Promise<string>;
+    /**
+     * Publish permission deleted event
+     */
+    publishPermissionDeleted(permissionId: string, meta?: Partial<PolicyEventMeta>): Promise<string>;
+    /**
+     * Publish role permission assigned event
+     */
+    publishRolePermissionAssigned(data: RolePermissionData, meta?: Partial<PolicyEventMeta>): Promise<string>;
+    /**
+     * Publish role permission revoked event
+     */
+    publishRolePermissionRevoked(data: RolePermissionData, meta?: Partial<PolicyEventMeta>): Promise<string>;
+    /**
+     * Publish full sync requested event
+     */
+    publishFullSyncRequested(requestedBy: string, meta?: Partial<PolicyEventMeta>): Promise<string>;
+}
+export {};

package/dist/src/events/policies/policy-publisher.js

@@ -0,0 +1,128 @@
+import { SNSClient, PublishCommand } from '@aws-sdk/client-sns';
+import { PolicyEventType, } from './policy-event';
+/**
+ * Get SNS client configured for LocalStack or AWS
+ */
+function createSNSClient(config) {
+    const endpoint = config.endpoint || process.env.LOCALSTACK_ENDPOINT;
+    const region = config.region || process.env.AWS_REGION || 'us-east-1';
+    const clientConfig = { region };
+    // For LocalStack, set custom endpoint
+    if (endpoint) {
+        clientConfig.endpoint = endpoint;
+    }
+    return new SNSClient(clientConfig);
+}
+/**
+ * Policy Event Publisher for sending policy sync events to SNS
+ * Used by user-service to notify policy-sync-service of changes
+ */
+export class PolicyEventPublisher {
+    snsClient;
+    topicArn;
+    serviceName;
+    constructor(serviceName, config) {
+        this.serviceName = serviceName;
+        this.snsClient = createSNSClient(config || {});
+        // Topic ARN can be passed directly or constructed from env vars
+        const stage = process.env.STAGE || process.env.NODE_ENV || 'test';
+        const region = config?.region || process.env.AWS_REGION || 'us-east-1';
+        const accountId = process.env.AWS_ACCOUNT_ID || '000000000000';
+        this.topicArn = config?.topicArn ||
+            process.env.POLICY_SYNC_TOPIC_ARN ||
+            `arn:aws:sns:${region}:${accountId}:qshelter-${stage}-policy-sync`;
+    }
+    /**
+     * Publish a policy event to SNS
+     */
+    async publish(eventType, data, meta) {
+        const eventId = crypto.randomUUID();
+        const event = {
+            eventType,
+            eventId,
+            timestamp: new Date().toISOString(),
+            source: this.serviceName,
+            tenantId: meta?.tenantId,
+            data,
+            metadata: {
+                correlationId: meta?.correlationId || eventId,
+                userId: meta?.userId,
+            },
+        };
+        const command = new PublishCommand({
+            TopicArn: this.topicArn,
+            Message: JSON.stringify(event),
+            MessageAttributes: {
+                eventType: {
+                    DataType: 'String',
+                    StringValue: eventType,
+                },
+                source: {
+                    DataType: 'String',
+                    StringValue: this.serviceName,
+                },
+            },
+        });
+        const result = await this.snsClient.send(command);
+        console.log(`[PolicyEventPublisher] Published ${eventType} event to SNS`, {
+            topicArn: this.topicArn,
+            messageId: result.MessageId,
+            eventId,
+        });
+        return result.MessageId || '';
+    }
+    /**
+     * Publish role created event
+     */
+    async publishRoleCreated(role, meta) {
+        return this.publish(PolicyEventType.ROLE_CREATED, role, meta);
+    }
+    /**
+     * Publish role updated event
+     */
+    async publishRoleUpdated(role, meta) {
+        return this.publish(PolicyEventType.ROLE_UPDATED, role, meta);
+    }
+    /**
+     * Publish role deleted event
+     */
+    async publishRoleDeleted(roleId, roleName, meta) {
+        return this.publish(PolicyEventType.ROLE_DELETED, { roleId, roleName }, meta);
+    }
+    /**
+     * Publish permission created event
+     */
+    async publishPermissionCreated(permission, meta) {
+        return this.publish(PolicyEventType.PERMISSION_CREATED, permission, meta);
+    }
+    /**
+     * Publish permission updated event
+     */
+    async publishPermissionUpdated(permission, meta) {
+        return this.publish(PolicyEventType.PERMISSION_UPDATED, permission, meta);
+    }
+    /**
+     * Publish permission deleted event
+     */
+    async publishPermissionDeleted(permissionId, meta) {
+        return this.publish(PolicyEventType.PERMISSION_DELETED, { permissionId }, meta);
+    }
+    /**
+     * Publish role permission assigned event
+     */
+    async publishRolePermissionAssigned(data, meta) {
+        return this.publish(PolicyEventType.ROLE_PERMISSION_ASSIGNED, data, meta);
+    }
+    /**
+     * Publish role permission revoked event
+     */
+    async publishRolePermissionRevoked(data, meta) {
+        return this.publish(PolicyEventType.ROLE_PERMISSION_REVOKED, data, meta);
+    }
+    /**
+     * Publish full sync requested event
+     */
+    async publishFullSyncRequested(requestedBy, meta) {
+        return this.publish(PolicyEventType.FULL_SYNC_REQUESTED, { requestedBy }, meta);
+    }
+}

package/dist/src/prisma/tenant.js

@@ -9,16 +9,18 @@
  * These models either:
  * - Don't have a tenantId field (system tables)
  * - Have optional tenantId but are designed to work across tenants (User)
+ * - Are cross-tenant lookup/join tables (TenantMembership)
  */
 const GLOBAL_MODELS = [
-    // User can exist across tenants or without a tenant
+    // User can exist across tenants or without a tenant (federated)
     "user",
+    // TenantMembership is the user-tenant join table (queries by userId or tenantId)
+    "tenantMembership",
     // System/infrastructure tables without tenantId
     "tenant",
-    "role",
-    "permission",
-    "rolePermission",
+    // Legacy role assignment (global, not tenant-scoped)
     "userRole",
+    "rolePermission",
     "refreshToken",
     "passwordReset",
     "wallet",
@@ -29,7 +31,13 @@ const GLOBAL_MODELS = [
  * These can be global templates (tenantId = null) or tenant-specific.
  * Queries will return both global AND tenant-specific records.
  */
-const OPTIONAL_TENANT_MODELS = ["paymentPlan"];
+const OPTIONAL_TENANT_MODELS = [
+    "paymentPlan",
+    // Role can be global template (tenantId = null) or tenant-specific
+    "role",
+    // Permission can be global template or tenant-specific
+    "permission",
+];
 function isGlobalModel(model) {
     return GLOBAL_MODELS.includes(model);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentine-efagene/qshelter-common",
-  "version": "2.0.87",
+  "version": "2.0.89",
   "description": "Shared database schemas and utilities for QShelter services",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

package/prisma/schema.prisma

@@ -292,29 +292,39 @@ enum ExecutionStatus {
   SKIPPED
 }
 
+/// Permission effect (Allow/Deny)
+enum PermissionEffect {
+  ALLOW
+  DENY
+}
+
 // =============================================================================
 // USER & AUTH DOMAIN
 // =============================================================================
 
 model User {
-  id                     String            @id @default(cuid())
-  email                  String            @unique
+  id                     String             @id @default(cuid())
+  email                  String             @unique
   password               String?
-  phone                  String?           @unique
+  phone                  String?            @unique
   firstName              String?
   lastName               String?
-  isActive               Boolean           @default(true)
-  isEmailVerified        Boolean           @default(false)
+  isActive               Boolean            @default(true)
+  isEmailVerified        Boolean            @default(false)
   googleId               String?
   avatar                 String?
+  // Legacy: Optional direct tenant association (for backward compatibility)
+  // New: Use tenantMemberships for multi-tenant federation
   tenantId               String?
-  tenant                 Tenant?           @relation(fields: [tenantId], references: [id], onDelete: SetNull)
-  // Support multiple roles via explicit join table `UserRole`
+  tenant                 Tenant?            @relation(fields: [tenantId], references: [id], onDelete: SetNull)
+  // Federated: User can belong to multiple tenants with different roles
+  tenantMemberships      TenantMembership[]
+  // Legacy: Support multiple roles via explicit join table `UserRole`
   userRoles              UserRole[]
-  walletId               String?           @unique
-  wallet                 Wallet?           @relation(fields: [walletId], references: [id])
-  createdAt              DateTime          @default(now())
-  updatedAt              DateTime          @updatedAt
+  walletId               String?            @unique
+  wallet                 Wallet?            @relation(fields: [walletId], references: [id])
+  createdAt              DateTime           @default(now())
+  updatedAt              DateTime           @updatedAt
   emailVerifiedAt        DateTime?
   emailVerificationToken String?
   lastLoginAt            DateTime?
@@ -368,29 +378,51 @@ model User {
 }
 
 model Role {
-  id          String           @id @default(cuid())
-  name        String           @unique
+  id          String             @id @default(cuid())
+  name        String
   description String?
+  // Tenant-scoping: NULL = global template, set = tenant-specific role
+  tenantId    String?
+  tenant      Tenant?            @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  // System roles cannot be deleted (admin, user, etc.)
+  isSystem    Boolean            @default(false)
+  isActive    Boolean            @default(true)
+  // Legacy: UserRole for backward compatibility
   userRoles   UserRole[]
+  // New: TenantMembership for federated users
+  memberships TenantMembership[]
   permissions RolePermission[]
-  createdAt   DateTime         @default(now())
-  updatedAt   DateTime         @updatedAt
+  createdAt   DateTime           @default(now())
+  updatedAt   DateTime           @updatedAt
 
+  @@unique([name, tenantId]) // Unique name per tenant (null tenantId = global)
+  @@index([tenantId])
   @@map("roles")
 }
 
+/// Permission defines a path pattern + HTTP methods + effect
+/// Supports path-based authorization matching the authorizer's policy structure
 model Permission {
   id          String           @id @default(cuid())
-  name        String           @unique
+  name        String // Descriptive name: "Read Users", "Manage Properties"
   description String?
-  resource    String
-  action      String
+  // Path pattern: /users, /users/:id, /properties/*, etc.
+  path        String
+  // HTTP methods: ["GET"], ["GET", "POST"], ["*"] - stored as JSON
+  methods     Json             @default("[]")
+  // Allow or Deny this path/methods
+  effect      PermissionEffect @default(ALLOW)
+  // Tenant-scoping: NULL = global template, set = tenant-specific
+  tenantId    String?
+  tenant      Tenant?          @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  // System permissions cannot be deleted
+  isSystem    Boolean          @default(false)
   roles       RolePermission[]
   createdAt   DateTime         @default(now())
   updatedAt   DateTime         @updatedAt
 
-  @@unique([resource, action])
-  @@index([resource])
+  @@unique([path, tenantId]) // Unique path per tenant
+  @@index([tenantId])
   @@map("permissions")
 }
 
@@ -405,6 +437,8 @@ model RolePermission {
   @@map("role_permissions")
 }
 
+/// Legacy: Direct user-role assignment (global, not tenant-scoped)
+/// @deprecated Use TenantMembership for tenant-scoped role assignments
 model UserRole {
   userId    String
   roleId    String
@@ -416,6 +450,30 @@ model UserRole {
   @@map("user_roles")
 }
 
+/// Tenant Membership: Links users to tenants with specific roles
+/// Enables federated users across multiple tenants with different roles per tenant
+model TenantMembership {
+  id        String   @id @default(cuid())
+  userId    String
+  tenantId  String
+  roleId    String
+  // Whether this membership is active
+  isActive  Boolean  @default(true)
+  // Whether this is the user's default tenant (for login without specifying tenant)
+  isDefault Boolean  @default(false)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  user   User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+  tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  role   Role   @relation(fields: [roleId], references: [id], onDelete: Restrict)
+
+  @@unique([userId, tenantId]) // User can only have one membership per tenant
+  @@index([tenantId])
+  @@index([userId])
+  @@map("tenant_memberships")
+}
+
 model Tenant {
   id        String   @id @default(cuid())
   name      String
@@ -431,6 +489,12 @@ model Tenant {
   paymentMethods PropertyPaymentMethod[]
   contracts      Contract[]
 
+  // RBAC: Tenant-scoped roles and permissions
+  roles       Role[]
+  permissions Permission[]
+  // Federated user memberships
+  memberships TenantMembership[]
+
   // Payment method changes
   paymentMethodChangeRequests PaymentMethodChangeRequest[]
   documentRequirementRules    DocumentRequirementRule[]