@portaidentity/server 1.7.0

package/dist/rbac/types.d.ts

@@ -0,0 +1,187 @@
+/**
+ * RBAC types and interfaces.
+ *
+ * Defines the data structures for roles, permissions, and user-role
+ * assignments. Includes full database record interfaces, input types
+ * for create/update, pagination helpers, and mapping functions to
+ * convert snake_case database rows to camelCase TypeScript objects.
+ *
+ * These types are the foundation that all other RBAC modules depend
+ * on (repository, cache, service, routes).
+ *
+ * Database tables: roles, permissions, role_permissions, user_roles
+ * (see migrations 006_roles_permissions.sql)
+ */
+/**
+ * Full role record as stored in the database.
+ * Maps to the `roles` table columns (see migration 006).
+ * Roles are defined globally per application — assigned to users via user_roles.
+ */
+export interface Role {
+    id: string;
+    applicationId: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Raw database row from the roles table (snake_case columns).
+ * Used by the repository layer; mapped to Role via mapRowToRole().
+ */
+export interface RoleRow {
+    id: string;
+    application_id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    created_at: Date;
+    updated_at: Date;
+}
+/**
+ * Input for creating a new role.
+ * Slug is auto-generated from name if not provided.
+ */
+export interface CreateRoleInput {
+    applicationId: string;
+    name: string;
+    slug?: string;
+    description?: string;
+}
+/**
+ * Input for updating an existing role (partial).
+ * Only provided fields are updated.
+ */
+export interface UpdateRoleInput {
+    name?: string;
+    slug?: string;
+    description?: string | null;
+}
+/**
+ * Full permission record as stored in the database.
+ * Maps to the `permissions` table columns (see migration 006).
+ * Permissions are defined globally per application, optionally scoped
+ * to a module. The slug follows the module:resource:action format
+ * (e.g., "crm:contacts:read").
+ */
+export interface Permission {
+    id: string;
+    applicationId: string;
+    moduleId: string | null;
+    name: string;
+    slug: string;
+    description: string | null;
+    createdAt: Date;
+}
+/**
+ * Raw database row from the permissions table (snake_case columns).
+ * Used by the repository layer; mapped to Permission via mapRowToPermission().
+ */
+export interface PermissionRow {
+    id: string;
+    application_id: string;
+    module_id: string | null;
+    name: string;
+    slug: string;
+    description: string | null;
+    created_at: Date;
+}
+/**
+ * Input for creating a new permission.
+ * The slug must follow the module:resource:action format and is
+ * validated by the service layer before insert.
+ */
+export interface CreatePermissionInput {
+    applicationId: string;
+    moduleId?: string;
+    name: string;
+    slug: string;
+    description?: string;
+}
+/**
+ * Input for updating an existing permission (partial).
+ * Note: slug is NOT updatable — it is the permission's identity.
+ */
+export interface UpdatePermissionInput {
+    name?: string;
+    description?: string | null;
+}
+/**
+ * User-role assignment record.
+ * Maps to the `user_roles` join table (see migration 006).
+ * Tracks which user has which role, and who assigned it.
+ */
+export interface UserRole {
+    userId: string;
+    roleId: string;
+    assignedBy: string | null;
+    createdAt: Date;
+}
+/**
+ * Raw database row from the user_roles table (snake_case columns).
+ * Used by the repository layer; mapped to UserRole via mapRowToUserRole().
+ */
+export interface UserRoleRow {
+    user_id: string;
+    role_id: string;
+    assigned_by: string | null;
+    created_at: Date;
+}
+/**
+ * Role with its assigned permissions — result of a joined query.
+ * Used when fetching a role with all its permission details.
+ */
+export interface RoleWithPermissions extends Role {
+    permissions: Permission[];
+}
+/** Options for listing roles (paginated). */
+export interface ListRolesOptions {
+    applicationId: string;
+    page: number;
+    pageSize: number;
+    search?: string;
+    sortBy?: 'name' | 'created_at';
+    sortOrder?: 'asc' | 'desc';
+}
+/** Options for listing permissions (paginated). */
+export interface ListPermissionsOptions {
+    applicationId: string;
+    page: number;
+    pageSize: number;
+    moduleId?: string;
+    search?: string;
+    sortBy?: 'name' | 'created_at';
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Map a database row to a Role object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties.
+ *
+ * @param row - Raw database row from the roles table
+ * @returns Mapped Role object with camelCase properties
+ */
+export declare function mapRowToRole(row: RoleRow): Role;
+/**
+ * Map a database row to a Permission object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties.
+ *
+ * @param row - Raw database row from the permissions table
+ * @returns Mapped Permission object with camelCase properties
+ */
+export declare function mapRowToPermission(row: PermissionRow): Permission;
+/**
+ * Map a database row to a UserRole object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties.
+ *
+ * @param row - Raw database row from the user_roles table
+ * @returns Mapped UserRole object with camelCase properties
+ */
+export declare function mapRowToUserRole(row: UserRoleRow): UserRole;
+//# sourceMappingURL=types.d.ts.map

package/dist/rbac/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/rbac/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH;;;;GAIG;AACH,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,IAAI,CAAC;IACjB,UAAU,EAAE,IAAI,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,IAAI,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAMD;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,IAAI,CAAC;CAClB;AAMD;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,IAAI;IAC/C,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAMD,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC/B,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CAC5B;AAED,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC/B,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CAC5B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAU/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,UAAU,CAUjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,QAAQ,CAO3D"}

package/dist/rbac/types.js

@@ -0,0 +1,75 @@
+/**
+ * RBAC types and interfaces.
+ *
+ * Defines the data structures for roles, permissions, and user-role
+ * assignments. Includes full database record interfaces, input types
+ * for create/update, pagination helpers, and mapping functions to
+ * convert snake_case database rows to camelCase TypeScript objects.
+ *
+ * These types are the foundation that all other RBAC modules depend
+ * on (repository, cache, service, routes).
+ *
+ * Database tables: roles, permissions, role_permissions, user_roles
+ * (see migrations 006_roles_permissions.sql)
+ */
+// ---------------------------------------------------------------------------
+// Database row mapping functions
+// ---------------------------------------------------------------------------
+/**
+ * Map a database row to a Role object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties.
+ *
+ * @param row - Raw database row from the roles table
+ * @returns Mapped Role object with camelCase properties
+ */
+export function mapRowToRole(row) {
+    return {
+        id: row.id,
+        applicationId: row.application_id,
+        name: row.name,
+        slug: row.slug,
+        description: row.description,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+/**
+ * Map a database row to a Permission object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties.
+ *
+ * @param row - Raw database row from the permissions table
+ * @returns Mapped Permission object with camelCase properties
+ */
+export function mapRowToPermission(row) {
+    return {
+        id: row.id,
+        applicationId: row.application_id,
+        moduleId: row.module_id,
+        name: row.name,
+        slug: row.slug,
+        description: row.description,
+        createdAt: row.created_at,
+    };
+}
+/**
+ * Map a database row to a UserRole object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties.
+ *
+ * @param row - Raw database row from the user_roles table
+ * @returns Mapped UserRole object with camelCase properties
+ */
+export function mapRowToUserRole(row) {
+    return {
+        userId: row.user_id,
+        roleId: row.role_id,
+        assignedBy: row.assigned_by,
+        createdAt: row.created_at,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/rbac/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/rbac/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAiLH,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,aAAa,EAAE,GAAG,CAAC,cAAc;QACjC,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAkB;IACnD,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,aAAa,EAAE,GAAG,CAAC,cAAc;QACjC,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAgB;IAC/C,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,UAAU,EAAE,GAAG,CAAC,WAAW;QAC3B,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC"}

package/dist/rbac/user-role-service.d.ts

@@ -0,0 +1,101 @@
+/**
+ * User-role service — user role assignment and claims building.
+ *
+ * Handles assigning/removing roles to/from users, retrieving user
+ * roles and permissions, and building the claims arrays that get
+ * injected into OIDC tokens.
+ *
+ * The claims-building functions (buildRoleClaims, buildPermissionClaims)
+ * are the token hot path — they use cache-first resolution to minimize
+ * database queries during token issuance.
+ *
+ * Cache strategy for claims:
+ * 1. Check Redis for cached slug arrays
+ * 2. On cache hit → return immediately (fast path)
+ * 3. On cache miss → query DB, cache result, return
+ *
+ * @see mapping-repository.ts — Database operations for user-role join table
+ * @see cache.ts — Redis cache for role/permission slug arrays
+ */
+import type { Role, Permission, UserRole } from './types.js';
+/**
+ * Assign roles to a user (bulk).
+ *
+ * Uses ON CONFLICT DO NOTHING for idempotent assignment. Invalidates
+ * the user's RBAC cache since their effective permissions may change.
+ *
+ * @param userId - User UUID
+ * @param roleIds - Array of role UUIDs to assign
+ * @param assignedBy - Optional UUID of the admin performing the assignment
+ */
+export declare function assignRolesToUser(userId: string, roleIds: string[], assignedBy?: string): Promise<void>;
+/**
+ * Remove roles from a user (bulk).
+ *
+ * Invalidates the user's RBAC cache since their effective permissions
+ * may change.
+ *
+ * @param userId - User UUID
+ * @param roleIds - Array of role UUIDs to remove
+ * @param actorId - Optional UUID of the admin performing the action
+ */
+export declare function removeRolesFromUser(userId: string, roleIds: string[], actorId?: string): Promise<void>;
+/**
+ * Get all roles assigned to a user.
+ *
+ * @param userId - User UUID
+ * @returns Array of Role objects
+ */
+export declare function getUserRoles(userId: string): Promise<Role[]>;
+/**
+ * Get all permissions for a user (resolved through roles).
+ *
+ * @param userId - User UUID
+ * @returns Deduplicated array of Permission objects
+ */
+export declare function getUserPermissions(userId: string): Promise<Permission[]>;
+/**
+ * List users with a specific role within an organization.
+ *
+ * Supports pagination for admin UI views.
+ *
+ * @param roleId - Role UUID
+ * @param orgId - Organization UUID
+ * @param options - Pagination options
+ * @returns Paginated user-role assignments and total count
+ */
+export declare function getUsersWithRole(roleId: string, orgId: string, options?: {
+    page?: number;
+    pageSize?: number;
+}): Promise<{
+    rows: UserRole[];
+    total: number;
+}>;
+/**
+ * Build role claims for a user's token.
+ *
+ * Returns an array of role slugs (e.g., ["crm-editor", "invoice-approver"])
+ * for inclusion in the token's custom claims.
+ *
+ * Cache-first: checks Redis for cached role slugs. On cache miss,
+ * resolves from DB and caches the result for future token issuances.
+ *
+ * @param userId - User UUID
+ * @returns Array of role slug strings
+ */
+export declare function buildRoleClaims(userId: string): Promise<string[]>;
+/**
+ * Build permission claims for a user's token.
+ *
+ * Returns an array of permission slugs (e.g., ["crm:contacts:read",
+ * "crm:deals:write"]) for inclusion in the token's custom claims.
+ *
+ * Cache-first: checks Redis for cached permission slugs. On cache miss,
+ * resolves through the full user → roles → permissions chain from DB
+ * and caches the result.
+ *
+ * @param userId - User UUID
+ * @returns Array of permission slug strings
+ */
+export declare function buildPermissionClaims(userId: string): Promise<string[]>;
+//# sourceMappingURL=user-role-service.d.ts.map

package/dist/rbac/user-role-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-role-service.d.ts","sourceRoot":"","sources":["../../src/rbac/user-role-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAiBH,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAM7D;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EAAE,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAgBf;AAMD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAElE;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAE9E;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,OAAO,CAAC;IAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAK9C;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAevE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAe7E"}

package/dist/rbac/user-role-service.js

@@ -0,0 +1,166 @@
+/**
+ * User-role service — user role assignment and claims building.
+ *
+ * Handles assigning/removing roles to/from users, retrieving user
+ * roles and permissions, and building the claims arrays that get
+ * injected into OIDC tokens.
+ *
+ * The claims-building functions (buildRoleClaims, buildPermissionClaims)
+ * are the token hot path — they use cache-first resolution to minimize
+ * database queries during token issuance.
+ *
+ * Cache strategy for claims:
+ * 1. Check Redis for cached slug arrays
+ * 2. On cache hit → return immediately (fast path)
+ * 3. On cache miss → query DB, cache result, return
+ *
+ * @see mapping-repository.ts — Database operations for user-role join table
+ * @see cache.ts — Redis cache for role/permission slug arrays
+ */
+import { assignRolesToUser as repoAssignRoles, removeRolesFromUser as repoRemoveRoles, getRolesForUser as repoGetRolesForUser, getPermissionsForUser as repoGetPermissionsForUser, getUsersWithRole as repoGetUsersWithRole, } from './mapping-repository.js';
+import { getCachedUserRoles, setCachedUserRoles, getCachedUserPermissions, setCachedUserPermissions, invalidateUserRbacCache, } from './cache.js';
+import { writeAuditLog } from '../lib/audit-log.js';
+// ---------------------------------------------------------------------------
+// Assignment management
+// ---------------------------------------------------------------------------
+/**
+ * Assign roles to a user (bulk).
+ *
+ * Uses ON CONFLICT DO NOTHING for idempotent assignment. Invalidates
+ * the user's RBAC cache since their effective permissions may change.
+ *
+ * @param userId - User UUID
+ * @param roleIds - Array of role UUIDs to assign
+ * @param assignedBy - Optional UUID of the admin performing the assignment
+ */
+export async function assignRolesToUser(userId, roleIds, assignedBy) {
+    if (roleIds.length === 0)
+        return;
+    await repoAssignRoles(userId, roleIds, assignedBy);
+    // Invalidate user's cached roles and permissions
+    await invalidateUserRbacCache(userId);
+    // Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'user.roles.assigned',
+        eventCategory: 'admin',
+        userId,
+        actorId: assignedBy,
+        metadata: { roleIds },
+    });
+}
+/**
+ * Remove roles from a user (bulk).
+ *
+ * Invalidates the user's RBAC cache since their effective permissions
+ * may change.
+ *
+ * @param userId - User UUID
+ * @param roleIds - Array of role UUIDs to remove
+ * @param actorId - Optional UUID of the admin performing the action
+ */
+export async function removeRolesFromUser(userId, roleIds, actorId) {
+    if (roleIds.length === 0)
+        return;
+    await repoRemoveRoles(userId, roleIds);
+    // Invalidate user's cached roles and permissions
+    await invalidateUserRbacCache(userId);
+    // Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'user.roles.removed',
+        eventCategory: 'admin',
+        userId,
+        actorId,
+        metadata: { roleIds },
+    });
+}
+// ---------------------------------------------------------------------------
+// Query operations
+// ---------------------------------------------------------------------------
+/**
+ * Get all roles assigned to a user.
+ *
+ * @param userId - User UUID
+ * @returns Array of Role objects
+ */
+export async function getUserRoles(userId) {
+    return repoGetRolesForUser(userId);
+}
+/**
+ * Get all permissions for a user (resolved through roles).
+ *
+ * @param userId - User UUID
+ * @returns Deduplicated array of Permission objects
+ */
+export async function getUserPermissions(userId) {
+    return repoGetPermissionsForUser(userId);
+}
+/**
+ * List users with a specific role within an organization.
+ *
+ * Supports pagination for admin UI views.
+ *
+ * @param roleId - Role UUID
+ * @param orgId - Organization UUID
+ * @param options - Pagination options
+ * @returns Paginated user-role assignments and total count
+ */
+export async function getUsersWithRole(roleId, orgId, options) {
+    const page = options?.page ?? 1;
+    const pageSize = options?.pageSize ?? 20;
+    return repoGetUsersWithRole(roleId, orgId, page, pageSize);
+}
+// ---------------------------------------------------------------------------
+// Token claims building (hot path)
+// ---------------------------------------------------------------------------
+/**
+ * Build role claims for a user's token.
+ *
+ * Returns an array of role slugs (e.g., ["crm-editor", "invoice-approver"])
+ * for inclusion in the token's custom claims.
+ *
+ * Cache-first: checks Redis for cached role slugs. On cache miss,
+ * resolves from DB and caches the result for future token issuances.
+ *
+ * @param userId - User UUID
+ * @returns Array of role slug strings
+ */
+export async function buildRoleClaims(userId) {
+    // 1. Check cache for user role slugs
+    const cached = await getCachedUserRoles(userId);
+    if (cached !== null) {
+        return cached;
+    }
+    // 2. Cache miss — resolve from DB
+    const roles = await repoGetRolesForUser(userId);
+    const slugs = roles.map((role) => role.slug);
+    // 3. Cache the slugs for future requests
+    await setCachedUserRoles(userId, slugs);
+    return slugs;
+}
+/**
+ * Build permission claims for a user's token.
+ *
+ * Returns an array of permission slugs (e.g., ["crm:contacts:read",
+ * "crm:deals:write"]) for inclusion in the token's custom claims.
+ *
+ * Cache-first: checks Redis for cached permission slugs. On cache miss,
+ * resolves through the full user → roles → permissions chain from DB
+ * and caches the result.
+ *
+ * @param userId - User UUID
+ * @returns Array of permission slug strings
+ */
+export async function buildPermissionClaims(userId) {
+    // 1. Check cache for user permission slugs
+    const cached = await getCachedUserPermissions(userId);
+    if (cached !== null) {
+        return cached;
+    }
+    // 2. Cache miss — resolve from DB (through roles)
+    const permissions = await repoGetPermissionsForUser(userId);
+    const slugs = permissions.map((perm) => perm.slug);
+    // 3. Cache the slugs for future requests
+    await setCachedUserPermissions(userId, slugs);
+    return slugs;
+}
+//# sourceMappingURL=user-role-service.js.map

package/dist/rbac/user-role-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-role-service.js","sourceRoot":"","sources":["../../src/rbac/user-role-service.ts"],"names":[],"mappings":"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"}

package/dist/routes/applications.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Application management API routes.
+ *
+ * All routes are under `/api/admin/applications` and require
+ * admin authentication (Bearer JWT). Provides CRUD for applications,
+ * status lifecycle (activate, deactivate, archive), and nested
+ * module management (CRUD, deactivate).
+ *
+ * Route structure:
+ *   POST   /                                — Create a new application
+ *   GET    /                                — List applications (paginated)
+ *   GET    /:id                             — Get application by ID
+ *   PUT    /:id                             — Update application
+ *   POST   /:id/archive                     — Archive application
+ *   POST   /:id/activate                    — Activate application
+ *   POST   /:id/deactivate                  — Deactivate application
+ *   POST   /:id/modules                     — Create module
+ *   GET    /:id/modules                     — List modules
+ *   PUT    /:id/modules/:moduleId           — Update module
+ *   POST   /:id/modules/:moduleId/deactivate — Deactivate module
+ *
+ * Error mapping:
+ *   ApplicationNotFoundError → 404
+ *   ApplicationValidationError → 400
+ *   ZodError → 400 with validation details
+ */
+import Router from '@koa/router';
+/**
+ * Create the application management router.
+ *
+ * All routes require admin authentication (Bearer JWT via requireAdminAuth).
+ * Provides full CRUD for applications and nested modules, plus status
+ * lifecycle actions.
+ *
+ * Prefix: /api/admin/applications
+ *
+ * @returns Configured Koa Router
+ */
+export declare function createApplicationRouter(): Router;
+//# sourceMappingURL=applications.d.ts.map

package/dist/routes/applications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applications.d.ts","sourceRoot":"","sources":["../../src/routes/applications.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AA0FjC;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAsLhD"}