@portaidentity/server 1.7.0

package/dist/rbac/cache.js

@@ -0,0 +1,271 @@
+/**
+ * RBAC cache — Redis-backed fast lookup layer.
+ *
+ * Provides get/set/invalidate operations for RBAC data stored in Redis:
+ *   - `rbac:role:{id}` — Individual role objects (for admin lookups)
+ *   - `rbac:user-roles:{userId}` — User's role slugs (for token claims)
+ *   - `rbac:user-perms:{userId}` — User's permission slugs (for token claims)
+ *
+ * The user-roles and user-permissions caches store slug arrays (string[])
+ * rather than full objects because token claims only need slugs. This
+ * reduces cache memory usage and serialization overhead on the hot path.
+ *
+ * All Redis errors are caught and logged — cache failures never propagate
+ * to callers. The system gracefully degrades to direct database lookups
+ * when Redis is unavailable.
+ *
+ * TTL: 5 minutes (balance between freshness and performance).
+ *
+ * Invalidation triggers:
+ * - Role updated/deleted → invalidateRoleCache()
+ * - Role-permission mapping changed → invalidateAllUserRbacCaches()
+ * - User-role assignment changed → invalidateUserRbacCache()
+ */
+import { getRedis } from '../lib/redis.js';
+import { logger } from '../lib/logger.js';
+import { afterDatabaseCommit } from '../lib/database.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Cache TTL in seconds (5 minutes) */
+const CACHE_TTL = 300;
+/** Key prefix for role objects by ID */
+const ROLE_PREFIX = 'rbac:role:';
+/** Key prefix for user role slugs */
+const USER_ROLES_PREFIX = 'rbac:user-roles:';
+/** Key prefix for user permission slugs */
+const USER_PERMISSIONS_PREFIX = 'rbac:user-perms:';
+// ---------------------------------------------------------------------------
+// Role cache
+// ---------------------------------------------------------------------------
+/**
+ * Get a cached role by ID.
+ *
+ * Returns null on cache miss, invalid JSON, or Redis error.
+ * Callers should fall back to the database on null.
+ *
+ * @param id - Role UUID
+ * @returns Cached role or null
+ */
+export async function getCachedRole(id) {
+    try {
+        const redis = getRedis();
+        const data = await redis.get(`${ROLE_PREFIX}${id}`);
+        if (!data)
+            return null;
+        return deserializeRole(data);
+    }
+    catch {
+        // Graceful degradation — log and return null so caller falls back to DB
+        logger.warn({ event: 'rbac-cache-read-failed' }, 'RBAC cache read failed');
+        return null;
+    }
+}
+/**
+ * Cache a role by ID.
+ *
+ * Stores the full Role object as JSON with a 5-minute TTL.
+ * Date fields are serialized to ISO 8601 strings automatically.
+ *
+ * @param role - Role to cache
+ */
+export async function setCachedRole(role) {
+    await afterDatabaseCommit(async () => {
+        try {
+            const redis = getRedis();
+            await redis.set(`${ROLE_PREFIX}${role.id}`, JSON.stringify(role), 'EX', CACHE_TTL);
+        }
+        catch {
+            // Graceful degradation — cache write failure is non-fatal
+            logger.warn({ event: 'rbac-cache-write-failed' }, 'RBAC cache write failed');
+        }
+    });
+}
+/**
+ * Invalidate a cached role.
+ *
+ * Should be called after any role update or deletion.
+ *
+ * @param id - Role UUID
+ */
+export async function invalidateRoleCache(id) {
+    await afterDatabaseCommit(async () => {
+        try {
+            const redis = getRedis();
+            await redis.del(`${ROLE_PREFIX}${id}`);
+        }
+        catch {
+            // Graceful degradation — cache invalidation failure is non-fatal
+            logger.warn({ event: 'rbac-cache-invalidation-failed' }, 'RBAC cache invalidation failed');
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// User roles cache (slug arrays for token claims)
+// ---------------------------------------------------------------------------
+/**
+ * Get cached user role slugs (for token claims).
+ *
+ * Returns null on cache miss, indicating the caller should resolve
+ * from the database and cache the result.
+ *
+ * @param userId - User UUID
+ * @returns Cached array of role slugs, or null on miss
+ */
+export async function getCachedUserRoles(userId) {
+    try {
+        const redis = getRedis();
+        const data = await redis.get(`${USER_ROLES_PREFIX}${userId}`);
+        if (!data)
+            return null;
+        return JSON.parse(data);
+    }
+    catch {
+        logger.warn({ event: 'rbac-cache-read-failed' }, 'RBAC cache read failed');
+        return null;
+    }
+}
+/**
+ * Cache user role slugs.
+ *
+ * Stores the slug array as JSON with a 5-minute TTL.
+ *
+ * @param userId - User UUID
+ * @param roleSlugs - Array of role slug strings
+ */
+export async function setCachedUserRoles(userId, roleSlugs) {
+    await afterDatabaseCommit(async () => {
+        try {
+            const redis = getRedis();
+            await redis.set(`${USER_ROLES_PREFIX}${userId}`, JSON.stringify(roleSlugs), 'EX', CACHE_TTL);
+        }
+        catch {
+            logger.warn({ event: 'rbac-cache-write-failed' }, 'RBAC cache write failed');
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// User permissions cache (slug arrays for token claims)
+// ---------------------------------------------------------------------------
+/**
+ * Get cached user permission slugs (for token claims).
+ *
+ * Returns null on cache miss, indicating the caller should resolve
+ * from the database and cache the result.
+ *
+ * @param userId - User UUID
+ * @returns Cached array of permission slugs, or null on miss
+ */
+export async function getCachedUserPermissions(userId) {
+    try {
+        const redis = getRedis();
+        const data = await redis.get(`${USER_PERMISSIONS_PREFIX}${userId}`);
+        if (!data)
+            return null;
+        return JSON.parse(data);
+    }
+    catch {
+        logger.warn({ event: 'rbac-cache-read-failed' }, 'RBAC cache read failed');
+        return null;
+    }
+}
+/**
+ * Cache user permission slugs.
+ *
+ * Stores the slug array as JSON with a 5-minute TTL.
+ *
+ * @param userId - User UUID
+ * @param permissionSlugs - Array of permission slug strings
+ */
+export async function setCachedUserPermissions(userId, permissionSlugs) {
+    await afterDatabaseCommit(async () => {
+        try {
+            const redis = getRedis();
+            await redis.set(`${USER_PERMISSIONS_PREFIX}${userId}`, JSON.stringify(permissionSlugs), 'EX', CACHE_TTL);
+        }
+        catch {
+            logger.warn({ event: 'rbac-cache-write-failed' }, 'RBAC cache write failed');
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Invalidation
+// ---------------------------------------------------------------------------
+/**
+ * Invalidate all user-related RBAC cache (roles + permissions).
+ *
+ * Called when a user's role assignments change. Deletes both the
+ * role slugs cache and permission slugs cache for the user.
+ *
+ * @param userId - User UUID
+ */
+export async function invalidateUserRbacCache(userId) {
+    await afterDatabaseCommit(async () => {
+        try {
+            const redis = getRedis();
+            await redis.del(`${USER_ROLES_PREFIX}${userId}`, `${USER_PERMISSIONS_PREFIX}${userId}`);
+        }
+        catch {
+            logger.warn({ event: 'rbac-cache-invalidation-failed' }, 'RBAC cache invalidation failed');
+        }
+    });
+}
+/**
+ * Invalidate all user RBAC caches (roles + permissions) for all users.
+ *
+ * Called when role-permission mappings change, since we cannot easily
+ * enumerate which users have a specific role from Redis alone. Uses
+ * SCAN to find and delete matching keys without blocking Redis.
+ *
+ * This is a relatively expensive operation but role-permission changes
+ * are infrequent admin operations, so the trade-off is acceptable.
+ */
+export async function invalidateAllUserRbacCaches() {
+    await afterDatabaseCommit(async () => {
+        try {
+            const redis = getRedis();
+            // Use SCAN to find and delete user RBAC cache keys
+            // SCAN is non-blocking unlike KEYS which can lock Redis
+            const patterns = [`${USER_ROLES_PREFIX}*`, `${USER_PERMISSIONS_PREFIX}*`];
+            for (const pattern of patterns) {
+                let cursor = '0';
+                do {
+                    const [nextCursor, keys] = await redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+                    cursor = nextCursor;
+                    if (keys.length > 0) {
+                        await redis.del(...keys);
+                    }
+                } while (cursor !== '0');
+            }
+        }
+        catch {
+            logger.warn({ event: 'rbac-cache-invalidation-failed' }, 'RBAC cache invalidation failed');
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Serialization helpers
+// ---------------------------------------------------------------------------
+/**
+ * Deserialize a JSON string from Redis into a Role object.
+ *
+ * Converts ISO 8601 date strings back to Date objects for the
+ * createdAt and updatedAt fields.
+ *
+ * @param data - JSON string from Redis
+ * @returns Role object with proper Date instances, or null if parse fails
+ */
+function deserializeRole(data) {
+    try {
+        const parsed = JSON.parse(data);
+        // Restore Date objects from ISO string serialization
+        parsed.createdAt = new Date(parsed.createdAt);
+        parsed.updatedAt = new Date(parsed.updatedAt);
+        return parsed;
+    }
+    catch {
+        logger.warn('Failed to parse cached role JSON');
+        return null;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/rbac/cache.js.map

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

package/dist/rbac/errors.d.ts

@@ -0,0 +1,34 @@
+/**
+ * RBAC domain error types.
+ *
+ * Custom error classes for RBAC-specific business rule violations.
+ * API routes map these to appropriate HTTP status codes:
+ *   - RoleNotFoundError       → 404
+ *   - PermissionNotFoundError → 404
+ *   - RbacValidationError     → 400
+ */
+/**
+ * Thrown when a role cannot be found by ID or slug.
+ * Maps to HTTP 404 in route handlers.
+ */
+export declare class RoleNotFoundError extends Error {
+    constructor(identifier: string);
+}
+/**
+ * Thrown when a permission cannot be found by ID or slug.
+ * Maps to HTTP 404 in route handlers.
+ */
+export declare class PermissionNotFoundError extends Error {
+    constructor(identifier: string);
+}
+/**
+ * Thrown when an RBAC operation violates business rules.
+ * Examples: duplicate slug in same application, invalid permission
+ * slug format, role still has assigned users (deletion guard),
+ * permission still assigned to roles (deletion guard).
+ * Maps to HTTP 400 in route handlers.
+ */
+export declare class RbacValidationError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/rbac/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,UAAU,EAAE,MAAM,EAG7B;CACF;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,YAAY,UAAU,EAAE,MAAM,EAG7B;CACF;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF"}

package/dist/rbac/errors.js

@@ -0,0 +1,43 @@
+/**
+ * RBAC domain error types.
+ *
+ * Custom error classes for RBAC-specific business rule violations.
+ * API routes map these to appropriate HTTP status codes:
+ *   - RoleNotFoundError       → 404
+ *   - PermissionNotFoundError → 404
+ *   - RbacValidationError     → 400
+ */
+/**
+ * Thrown when a role cannot be found by ID or slug.
+ * Maps to HTTP 404 in route handlers.
+ */
+export class RoleNotFoundError extends Error {
+    constructor(identifier) {
+        super(`Role not found: ${identifier}`);
+        this.name = 'RoleNotFoundError';
+    }
+}
+/**
+ * Thrown when a permission cannot be found by ID or slug.
+ * Maps to HTTP 404 in route handlers.
+ */
+export class PermissionNotFoundError extends Error {
+    constructor(identifier) {
+        super(`Permission not found: ${identifier}`);
+        this.name = 'PermissionNotFoundError';
+    }
+}
+/**
+ * Thrown when an RBAC operation violates business rules.
+ * Examples: duplicate slug in same application, invalid permission
+ * slug format, role still has assigned users (deletion guard),
+ * permission still assigned to roles (deletion guard).
+ * Maps to HTTP 400 in route handlers.
+ */
+export class RbacValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RbacValidationError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/rbac/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/rbac/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,UAAkB;QAC5B,KAAK,CAAC,mBAAmB,UAAU,EAAE,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,YAAY,UAAkB;QAC5B,KAAK,CAAC,yBAAyB,UAAU,EAAE,CAAC,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF"}

package/dist/rbac/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * RBAC module — public API barrel export.
+ *
+ * Re-exports the types, error classes, slug utilities, and service
+ * functions that other modules need. Internal implementation details
+ * (repository, cache) are NOT exported — they are consumed only by
+ * the service layer.
+ */
+export type { Role, RoleRow, CreateRoleInput, UpdateRoleInput, Permission, PermissionRow, CreatePermissionInput, UpdatePermissionInput, UserRole, UserRoleRow, RoleWithPermissions, ListRolesOptions, ListPermissionsOptions, } from './types.js';
+export { mapRowToRole, mapRowToPermission, mapRowToUserRole, } from './types.js';
+export { RoleNotFoundError, PermissionNotFoundError, RbacValidationError, } from './errors.js';
+export { generateRoleSlug, validateRoleSlug, validatePermissionSlug, parsePermissionSlug, } from './slugs.js';
+export type { ParsedPermissionSlug } from './slugs.js';
+export { createRole, findRoleById, findRoleBySlug, updateRole, deleteRole, listRolesByApplication, assignPermissionsToRole, removePermissionsFromRole, getPermissionsForRole, } from './role-service.js';
+export { createPermission, findPermissionById, findPermissionBySlug, updatePermission, deletePermission, listPermissionsByApplication, getRolesWithPermission, } from './permission-service.js';
+export { assignRolesToUser, removeRolesFromUser, getUserRoles, getUserPermissions, getUsersWithRole, buildRoleClaims, buildPermissionClaims, } from './user-role-service.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rbac/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EACV,IAAI,EACJ,OAAO,EACP,eAAe,EACf,eAAe,EACf,UAAU,EACV,aAAa,EACb,qBAAqB,EACrB,qBAAqB,EACrB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGvD,OAAO,EACL,UAAU,EACV,YAAY,EACZ,cAAc,EACd,UAAU,EACV,UAAU,EACV,sBAAsB,EACtB,uBAAuB,EACvB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,qBAAqB,GACtB,MAAM,wBAAwB,CAAC"}

package/dist/rbac/index.js

@@ -0,0 +1,21 @@
+/**
+ * RBAC module — public API barrel export.
+ *
+ * Re-exports the types, error classes, slug utilities, and service
+ * functions that other modules need. Internal implementation details
+ * (repository, cache) are NOT exported — they are consumed only by
+ * the service layer.
+ */
+// Row mappers
+export { mapRowToRole, mapRowToPermission, mapRowToUserRole, } from './types.js';
+// Error types
+export { RoleNotFoundError, PermissionNotFoundError, RbacValidationError, } from './errors.js';
+// Slug utilities
+export { generateRoleSlug, validateRoleSlug, validatePermissionSlug, parsePermissionSlug, } from './slugs.js';
+// Role service
+export { createRole, findRoleById, findRoleBySlug, updateRole, deleteRole, listRolesByApplication, assignPermissionsToRole, removePermissionsFromRole, getPermissionsForRole, } from './role-service.js';
+// Permission service
+export { createPermission, findPermissionById, findPermissionBySlug, updatePermission, deletePermission, listPermissionsByApplication, getRolesWithPermission, } from './permission-service.js';
+// User-role service
+export { assignRolesToUser, removeRolesFromUser, getUserRoles, getUserPermissions, getUsersWithRole, buildRoleClaims, buildPermissionClaims, } from './user-role-service.js';
+//# sourceMappingURL=index.js.map

package/dist/rbac/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rbac/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmBH,cAAc;AACd,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,cAAc;AACd,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,iBAAiB;AACjB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAKpB,eAAe;AACf,OAAO,EACL,UAAU,EACV,YAAY,EACZ,cAAc,EACd,UAAU,EACV,UAAU,EACV,sBAAsB,EACtB,uBAAuB,EACvB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,qBAAqB;AACrB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,oBAAoB;AACpB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,qBAAqB,GACtB,MAAM,wBAAwB,CAAC"}

package/dist/rbac/mapping-repository.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Mapping repository — PostgreSQL data access for RBAC join tables.
+ *
+ * Handles the role_permissions and user_roles join tables that link:
+ * - Roles ↔ Permissions (which permissions a role grants)
+ * - Users ↔ Roles (which roles a user has)
+ *
+ * Key patterns:
+ * - Bulk INSERT with ON CONFLICT DO NOTHING for idempotent assignment
+ * - Multi-table JOINs for permission resolution through roles
+ * - DISTINCT for deduplicated permission lists across multiple roles
+ * - Parameterized bulk VALUES lists for safe multi-row operations
+ *
+ * The permission resolution query (getPermissionsForUser) is the hot path
+ * for token claims — it resolves user → roles → permissions in a single query.
+ *
+ * Database tables: role_permissions, user_roles (see migration 006_roles_permissions.sql)
+ */
+import type { Role, Permission, UserRole } from './types.js';
+/**
+ * Assign multiple permissions to a role (bulk insert).
+ *
+ * Uses ON CONFLICT DO NOTHING to make the operation idempotent —
+ * already-assigned permissions are silently skipped. This allows
+ * callers to assign without checking for existing assignments first.
+ *
+ * @param roleId - Role UUID
+ * @param permissionIds - Array of permission UUIDs to assign
+ */
+export declare function assignPermissionsToRole(roleId: string, permissionIds: string[]): Promise<void>;
+/**
+ * Remove multiple permissions from a role.
+ *
+ * Silently succeeds if any of the permission IDs are not currently
+ * assigned to the role.
+ *
+ * @param roleId - Role UUID
+ * @param permissionIds - Array of permission UUIDs to remove
+ */
+export declare function removePermissionsFromRole(roleId: string, permissionIds: string[]): Promise<void>;
+/**
+ * Get all permissions assigned to a role.
+ *
+ * JOINs role_permissions with permissions table to return full
+ * Permission objects, ordered by slug for consistent output.
+ *
+ * @param roleId - Role UUID
+ * @returns Array of permissions assigned to the role
+ */
+export declare function getPermissionsForRole(roleId: string): Promise<Permission[]>;
+/**
+ * Get all roles that have a specific permission assigned.
+ *
+ * JOINs role_permissions with roles table to return full Role objects,
+ * ordered by name for consistent output.
+ *
+ * @param permissionId - Permission UUID
+ * @returns Array of roles that have this permission
+ */
+export declare function getRolesWithPermission(permissionId: string): Promise<Role[]>;
+/**
+ * Assign multiple roles to a user (bulk insert).
+ *
+ * Uses ON CONFLICT DO NOTHING to make the operation idempotent —
+ * already-assigned roles are silently skipped. Tracks who performed
+ * the assignment via the optional assignedBy parameter.
+ *
+ * @param userId - User UUID
+ * @param roleIds - Array of role UUIDs to assign
+ * @param assignedBy - Optional UUID of the admin who performed the assignment
+ */
+export declare function assignRolesToUser(userId: string, roleIds: string[], assignedBy?: string): Promise<void>;
+/**
+ * Remove multiple roles from a user.
+ *
+ * Silently succeeds if any of the role IDs are not currently
+ * assigned to the user.
+ *
+ * @param userId - User UUID
+ * @param roleIds - Array of role UUIDs to remove
+ */
+export declare function removeRolesFromUser(userId: string, roleIds: string[]): Promise<void>;
+/**
+ * Get all roles assigned to a user.
+ *
+ * JOINs user_roles with roles table to return full Role objects,
+ * ordered by name for consistent output.
+ *
+ * @param userId - User UUID
+ * @returns Array of roles assigned to the user
+ */
+export declare function getRolesForUser(userId: string): Promise<Role[]>;
+/**
+ * Get all permissions for a user, resolved through their assigned roles.
+ *
+ * This is the hot path for token claims — it resolves the full chain:
+ * user_roles → roles → role_permissions → permissions
+ * in a single query. Results are deduplicated (DISTINCT) since a user
+ * may have the same permission through multiple roles.
+ *
+ * @param userId - User UUID
+ * @returns Deduplicated array of permissions the user has through their roles
+ */
+export declare function getPermissionsForUser(userId: string): Promise<Permission[]>;
+/**
+ * List user-role assignments for a specific role within an organization.
+ *
+ * Supports pagination for admin UI views showing which users have a
+ * particular role. JOINs with users table to filter by organization.
+ *
+ * @param roleId - Role UUID
+ * @param orgId - Organization UUID (to scope users)
+ * @param page - Page number (1-based)
+ * @param pageSize - Number of results per page
+ * @returns Paginated user-role assignments and total count
+ */
+export declare function getUsersWithRole(roleId: string, orgId: string, page: number, pageSize: number): Promise<{
+    rows: UserRole[];
+    total: number;
+}>;
+//# sourceMappingURL=mapping-repository.d.ts.map

package/dist/rbac/mapping-repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapping-repository.d.ts","sourceRoot":"","sources":["../../src/rbac/mapping-repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAW,UAAU,EAAiB,QAAQ,EAAe,MAAM,YAAY,CAAC;AAOlG;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EAAE,GACtB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EAAE,GACtB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAajF;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAalF;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EAAE,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAarE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAcjF;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CA6B9C"}