@portaidentity/server 1.7.0

package/dist/rbac/permission-service.js

@@ -0,0 +1,179 @@
+/**
+ * Permission service — business logic for permission management.
+ *
+ * Orchestrates permission CRUD operations with slug format validation,
+ * uniqueness checks, deletion guards, cache management, and audit logging.
+ *
+ * Permission slugs follow the module:resource:action format (e.g.,
+ * "crm:contacts:read") and are immutable after creation — only name
+ * and description can be updated.
+ *
+ * All write operations follow the pattern:
+ *   validate → DB operation → cache invalidate → audit log
+ *
+ * @see permission-repository.ts — Database operations
+ * @see mapping-repository.ts — Role-permission lookups
+ * @see cache.ts — Redis cache operations
+ */
+import { insertPermission, findPermissionById as repoFindPermissionById, findPermissionBySlug as repoFindPermissionBySlug, updatePermission as repoUpdatePermission, deletePermission as repoDeletePermission, listPermissionsByApplication as repoListPermissionsByApplication, permissionSlugExists, countRolesWithPermission, } from './permission-repository.js';
+import { getRolesWithPermission as repoGetRolesWithPermission } from './mapping-repository.js';
+import { invalidateAllUserRbacCaches } from './cache.js';
+import { validatePermissionSlug } from './slugs.js';
+import { PermissionNotFoundError, RbacValidationError } from './errors.js';
+import { writeAuditLog } from '../lib/audit-log.js';
+// ---------------------------------------------------------------------------
+// Create
+// ---------------------------------------------------------------------------
+/**
+ * Create a new permission for an application.
+ *
+ * Validates that the slug follows the module:resource:action format
+ * and ensures uniqueness within the application.
+ *
+ * @param input - Permission creation data
+ * @param actorId - Optional UUID of the admin performing the action
+ * @returns The newly created permission
+ * @throws RbacValidationError if slug format is invalid or already exists
+ */
+export async function createPermission(input, actorId) {
+    // Validate permission slug format (module:resource:action)
+    if (!validatePermissionSlug(input.slug)) {
+        throw new RbacValidationError(`Invalid permission slug format: "${input.slug}". Must follow module:resource:action pattern with at least 3 colon-separated segments.`);
+    }
+    // Check slug uniqueness within the application
+    const exists = await permissionSlugExists(input.applicationId, input.slug);
+    if (exists) {
+        throw new RbacValidationError(`Permission slug "${input.slug}" already exists for this application.`);
+    }
+    // Insert the permission
+    const permission = await insertPermission(input);
+    // Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'permission.created',
+        eventCategory: 'admin',
+        actorId,
+        metadata: {
+            permissionId: permission.id,
+            applicationId: permission.applicationId,
+            slug: permission.slug,
+        },
+    });
+    return permission;
+}
+// ---------------------------------------------------------------------------
+// Read
+// ---------------------------------------------------------------------------
+/**
+ * Find a permission by ID.
+ *
+ * @param id - Permission UUID
+ * @returns Permission or null if not found
+ */
+export async function findPermissionById(id) {
+    return repoFindPermissionById(id);
+}
+/**
+ * Find a permission by application ID and slug.
+ *
+ * @param applicationId - Application UUID
+ * @param slug - Permission slug
+ * @returns Permission or null if not found
+ */
+export async function findPermissionBySlug(applicationId, slug) {
+    return repoFindPermissionBySlug(applicationId, slug);
+}
+/**
+ * List permissions for an application, optionally filtered by module.
+ *
+ * @param applicationId - Application UUID
+ * @param moduleId - Optional module UUID to filter by
+ * @returns Array of permissions
+ */
+export async function listPermissionsByApplication(applicationId, moduleId) {
+    return repoListPermissionsByApplication(applicationId, moduleId);
+}
+// ---------------------------------------------------------------------------
+// Update
+// ---------------------------------------------------------------------------
+/**
+ * Update a permission by ID (name and description only — slug is immutable).
+ *
+ * @param id - Permission UUID
+ * @param input - Fields to update (name, description only)
+ * @param actorId - Optional UUID of the admin performing the action
+ * @returns Updated permission
+ * @throws PermissionNotFoundError if permission doesn't exist
+ */
+export async function updatePermission(id, input, actorId) {
+    // Verify permission exists
+    const existing = await repoFindPermissionById(id);
+    if (!existing) {
+        throw new PermissionNotFoundError(id);
+    }
+    // Perform the update (slug is not updatable at the repository level)
+    const updated = await repoUpdatePermission(id, input);
+    // Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'permission.updated',
+        eventCategory: 'admin',
+        actorId,
+        metadata: { permissionId: id, changes: input },
+    });
+    return updated;
+}
+// ---------------------------------------------------------------------------
+// Delete
+// ---------------------------------------------------------------------------
+/**
+ * Delete a permission by ID.
+ *
+ * By default (force=false), refuses to delete permissions that are
+ * assigned to any role. Pass force=true to delete regardless —
+ * CASCADE will remove role_permissions entries.
+ *
+ * @param id - Permission UUID
+ * @param force - If true, delete even if assigned to roles
+ * @param actorId - Optional UUID of the admin performing the action
+ * @throws PermissionNotFoundError if permission doesn't exist
+ * @throws RbacValidationError if assigned to roles and force is false
+ */
+export async function deletePermission(id, force = false, actorId) {
+    // Verify permission exists
+    const existing = await repoFindPermissionById(id);
+    if (!existing) {
+        throw new PermissionNotFoundError(id);
+    }
+    // Deletion guard: check for assigned roles
+    if (!force) {
+        const roleCount = await countRolesWithPermission(id);
+        if (roleCount > 0) {
+            throw new RbacValidationError(`Cannot delete permission "${existing.slug}": assigned to ${roleCount} role(s). Use force=true to override.`);
+        }
+    }
+    // Delete the permission (CASCADE handles related records)
+    await repoDeletePermission(id);
+    // Invalidate user caches — permissions may have changed for users who had this
+    if (force) {
+        await invalidateAllUserRbacCaches();
+    }
+    // Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'permission.deleted',
+        eventCategory: 'admin',
+        actorId,
+        metadata: { permissionId: id, slug: existing.slug, force },
+    });
+}
+// ---------------------------------------------------------------------------
+// Role lookups
+// ---------------------------------------------------------------------------
+/**
+ * Get all roles that have a specific permission assigned.
+ *
+ * @param permissionId - Permission UUID
+ * @returns Array of roles with this permission
+ */
+export async function getRolesWithPermission(permissionId) {
+    return repoGetRolesWithPermission(permissionId);
+}
+//# sourceMappingURL=permission-service.js.map

package/dist/rbac/permission-service.js.map

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

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

@@ -0,0 +1,104 @@
+/**
+ * Role repository — PostgreSQL data access layer.
+ *
+ * Provides CRUD operations for the `roles` table using parameterized
+ * queries. Each function acquires the pool via `getPool()` and returns
+ * mapped Role objects via `mapRowToRole()`.
+ *
+ * Roles are scoped to an application (application_id FK) with a unique
+ * slug per application enforced by the DB constraint UNIQUE(application_id, slug).
+ *
+ * Key patterns:
+ * - Dynamic UPDATE query builder for partial updates (name, slug, description)
+ * - Simple list by application (no pagination — typically <100 roles per app)
+ * - Slug existence check with optional excludeId for update scenarios
+ * - User count for deletion guard (prevent deleting roles with assigned users)
+ *
+ * Database table: roles (see migration 006_roles_permissions.sql)
+ */
+import type { Role, CreateRoleInput, UpdateRoleInput } from './types.js';
+/**
+ * Insert a new role into the database.
+ *
+ * Uses RETURNING * to get the full row back in a single round trip.
+ * The (application_id, slug) pair must be unique (enforced by DB constraint).
+ *
+ * @param input - Role data to insert
+ * @returns The newly created role
+ * @throws If (application_id, slug) already exists (unique constraint violation)
+ */
+export declare function insertRole(input: CreateRoleInput): Promise<Role>;
+/**
+ * Find a role by its UUID.
+ *
+ * @param id - Role UUID
+ * @returns Role or null if not found
+ */
+export declare function findRoleById(id: string): Promise<Role | null>;
+/**
+ * Find a role by application ID and slug.
+ *
+ * @param applicationId - Application UUID
+ * @param slug - Role slug (unique within application)
+ * @returns Role or null if not found
+ */
+export declare function findRoleBySlug(applicationId: string, slug: string): Promise<Role | null>;
+/**
+ * Update a role's fields using a dynamic SET clause.
+ *
+ * Only explicitly provided fields (not undefined) are included in the
+ * UPDATE statement. This allows partial updates without overwriting
+ * fields that weren't specified. Null is a valid value for description
+ * (clears it).
+ *
+ * @param id - Role UUID
+ * @param input - Fields to update (only non-undefined fields are applied)
+ * @returns Updated role
+ * @throws Error if role not found or no fields provided
+ */
+export declare function updateRole(id: string, input: UpdateRoleInput): Promise<Role>;
+/**
+ * Delete a role by ID.
+ *
+ * Returns true if a row was deleted, false if the role didn't exist.
+ * CASCADE constraints will automatically remove related role_permissions
+ * and user_roles entries.
+ *
+ * @param id - Role UUID
+ * @returns true if deleted, false if not found
+ */
+export declare function deleteRole(id: string): Promise<boolean>;
+/**
+ * List all roles for an application, ordered by name ascending.
+ *
+ * Returns a simple array (no pagination) since applications typically
+ * have a manageable number of roles (<100).
+ *
+ * @param applicationId - Application UUID
+ * @returns Array of roles for the application
+ */
+export declare function listRolesByApplication(applicationId: string): Promise<Role[]>;
+/**
+ * Check if a role slug already exists for a given application.
+ *
+ * Used for uniqueness validation before insert or update. The optional
+ * excludeId parameter allows excluding a specific role (for updates —
+ * a role's own current slug should not block the update).
+ *
+ * @param applicationId - Application UUID
+ * @param slug - Slug to check
+ * @param excludeId - Optional role ID to exclude from the check
+ * @returns true if the slug already exists
+ */
+export declare function roleSlugExists(applicationId: string, slug: string, excludeId?: string): Promise<boolean>;
+/**
+ * Count users assigned to a role.
+ *
+ * Used by the service layer as a deletion guard: if users are assigned,
+ * the role cannot be deleted without force=true.
+ *
+ * @param roleId - Role UUID
+ * @returns Number of users with this role
+ */
+export declare function countUsersWithRole(roleId: string): Promise<number>;
+//# sourceMappingURL=role-repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"role-repository.d.ts","sourceRoot":"","sources":["../../src/rbac/role-repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAW,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAOlF;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBtE;AAMD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAUnE;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAU9F;AAgBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BlF;AAMD;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAS7D;AAMD;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CASnF;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAMD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CASxE"}

package/dist/rbac/role-repository.js

@@ -0,0 +1,202 @@
+/**
+ * Role repository — PostgreSQL data access layer.
+ *
+ * Provides CRUD operations for the `roles` table using parameterized
+ * queries. Each function acquires the pool via `getPool()` and returns
+ * mapped Role objects via `mapRowToRole()`.
+ *
+ * Roles are scoped to an application (application_id FK) with a unique
+ * slug per application enforced by the DB constraint UNIQUE(application_id, slug).
+ *
+ * Key patterns:
+ * - Dynamic UPDATE query builder for partial updates (name, slug, description)
+ * - Simple list by application (no pagination — typically <100 roles per app)
+ * - Slug existence check with optional excludeId for update scenarios
+ * - User count for deletion guard (prevent deleting roles with assigned users)
+ *
+ * Database table: roles (see migration 006_roles_permissions.sql)
+ */
+import { getPool } from '../lib/database.js';
+import { mapRowToRole } from './types.js';
+// ---------------------------------------------------------------------------
+// Insert
+// ---------------------------------------------------------------------------
+/**
+ * Insert a new role into the database.
+ *
+ * Uses RETURNING * to get the full row back in a single round trip.
+ * The (application_id, slug) pair must be unique (enforced by DB constraint).
+ *
+ * @param input - Role data to insert
+ * @returns The newly created role
+ * @throws If (application_id, slug) already exists (unique constraint violation)
+ */
+export async function insertRole(input) {
+    const pool = getPool();
+    const result = await pool.query(`INSERT INTO roles (application_id, name, slug, description)
+     VALUES ($1, $2, $3, $4)
+     RETURNING *`, [
+        input.applicationId,
+        input.name,
+        input.slug ?? null,
+        input.description ?? null,
+    ]);
+    return mapRowToRole(result.rows[0]);
+}
+// ---------------------------------------------------------------------------
+// Find
+// ---------------------------------------------------------------------------
+/**
+ * Find a role by its UUID.
+ *
+ * @param id - Role UUID
+ * @returns Role or null if not found
+ */
+export async function findRoleById(id) {
+    const pool = getPool();
+    const result = await pool.query('SELECT * FROM roles WHERE id = $1', [id]);
+    if (result.rows.length === 0)
+        return null;
+    return mapRowToRole(result.rows[0]);
+}
+/**
+ * Find a role by application ID and slug.
+ *
+ * @param applicationId - Application UUID
+ * @param slug - Role slug (unique within application)
+ * @returns Role or null if not found
+ */
+export async function findRoleBySlug(applicationId, slug) {
+    const pool = getPool();
+    const result = await pool.query('SELECT * FROM roles WHERE application_id = $1 AND slug = $2', [applicationId, slug]);
+    if (result.rows.length === 0)
+        return null;
+    return mapRowToRole(result.rows[0]);
+}
+// ---------------------------------------------------------------------------
+// Update
+// ---------------------------------------------------------------------------
+/**
+ * Mapping from UpdateRoleInput keys to database column names.
+ * Used by the dynamic query builder to construct SET clauses.
+ */
+const FIELD_TO_COLUMN = {
+    name: 'name',
+    slug: 'slug',
+    description: 'description',
+};
+/**
+ * Update a role's fields using a dynamic SET clause.
+ *
+ * Only explicitly provided fields (not undefined) are included in the
+ * UPDATE statement. This allows partial updates without overwriting
+ * fields that weren't specified. Null is a valid value for description
+ * (clears it).
+ *
+ * @param id - Role UUID
+ * @param input - Fields to update (only non-undefined fields are applied)
+ * @returns Updated role
+ * @throws Error if role not found or no fields provided
+ */
+export async function updateRole(id, input) {
+    const pool = getPool();
+    // Build dynamic SET clause from provided fields
+    const setClauses = [];
+    const values = [id]; // $1 is always the ID
+    let paramIndex = 2;
+    for (const [field, column] of Object.entries(FIELD_TO_COLUMN)) {
+        const value = input[field];
+        // Include the field if it's explicitly set (including null for clearing)
+        if (value !== undefined) {
+            setClauses.push(`${column} = $${paramIndex}`);
+            values.push(value);
+            paramIndex++;
+        }
+    }
+    if (setClauses.length === 0) {
+        throw new Error('No fields to update');
+    }
+    const sql = `UPDATE roles SET ${setClauses.join(', ')} WHERE id = $1 RETURNING *`;
+    const result = await pool.query(sql, values);
+    if (result.rows.length === 0) {
+        throw new Error('Role not found');
+    }
+    return mapRowToRole(result.rows[0]);
+}
+// ---------------------------------------------------------------------------
+// Delete
+// ---------------------------------------------------------------------------
+/**
+ * Delete a role by ID.
+ *
+ * Returns true if a row was deleted, false if the role didn't exist.
+ * CASCADE constraints will automatically remove related role_permissions
+ * and user_roles entries.
+ *
+ * @param id - Role UUID
+ * @returns true if deleted, false if not found
+ */
+export async function deleteRole(id) {
+    const pool = getPool();
+    const result = await pool.query('DELETE FROM roles WHERE id = $1', [id]);
+    return (result.rowCount ?? 0) > 0;
+}
+// ---------------------------------------------------------------------------
+// List
+// ---------------------------------------------------------------------------
+/**
+ * List all roles for an application, ordered by name ascending.
+ *
+ * Returns a simple array (no pagination) since applications typically
+ * have a manageable number of roles (<100).
+ *
+ * @param applicationId - Application UUID
+ * @returns Array of roles for the application
+ */
+export async function listRolesByApplication(applicationId) {
+    const pool = getPool();
+    const result = await pool.query('SELECT * FROM roles WHERE application_id = $1 ORDER BY name ASC', [applicationId]);
+    return result.rows.map(mapRowToRole);
+}
+// ---------------------------------------------------------------------------
+// Slug existence check
+// ---------------------------------------------------------------------------
+/**
+ * Check if a role slug already exists for a given application.
+ *
+ * Used for uniqueness validation before insert or update. The optional
+ * excludeId parameter allows excluding a specific role (for updates —
+ * a role's own current slug should not block the update).
+ *
+ * @param applicationId - Application UUID
+ * @param slug - Slug to check
+ * @param excludeId - Optional role ID to exclude from the check
+ * @returns true if the slug already exists
+ */
+export async function roleSlugExists(applicationId, slug, excludeId) {
+    const pool = getPool();
+    if (excludeId) {
+        const result = await pool.query('SELECT EXISTS(SELECT 1 FROM roles WHERE application_id = $1 AND slug = $2 AND id != $3) as exists', [applicationId, slug, excludeId]);
+        return result.rows[0].exists;
+    }
+    const result = await pool.query('SELECT EXISTS(SELECT 1 FROM roles WHERE application_id = $1 AND slug = $2) as exists', [applicationId, slug]);
+    return result.rows[0].exists;
+}
+// ---------------------------------------------------------------------------
+// User count (deletion guard)
+// ---------------------------------------------------------------------------
+/**
+ * Count users assigned to a role.
+ *
+ * Used by the service layer as a deletion guard: if users are assigned,
+ * the role cannot be deleted without force=true.
+ *
+ * @param roleId - Role UUID
+ * @returns Number of users with this role
+ */
+export async function countUsersWithRole(roleId) {
+    const pool = getPool();
+    const result = await pool.query('SELECT COUNT(*)::int as count FROM user_roles WHERE role_id = $1', [roleId]);
+    return parseInt(result.rows[0].count, 10);
+}
+//# sourceMappingURL=role-repository.js.map

package/dist/rbac/role-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-repository.js","sourceRoot":"","sources":["../../src/rbac/role-repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAsB;IACrD,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B;;iBAEa,EACb;QACE,KAAK,CAAC,aAAa;QACnB,KAAK,CAAC,IAAI;QACV,KAAK,CAAC,IAAI,IAAI,IAAI;QAClB,KAAK,CAAC,WAAW,IAAI,IAAI;KAC1B,CACF,CAAC;IAEF,OAAO,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACtC,CAAC;AAED,8EAA8E;AAC9E,OAAO;AACP,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,EAAU;IAC3C,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,mCAAmC,EACnC,CAAC,EAAE,CAAC,CACL,CAAC;IAEF,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,aAAqB,EAAE,IAAY;IACtE,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,6DAA6D,EAC7D,CAAC,aAAa,EAAE,IAAI,CAAC,CACtB,CAAC;IAEF,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACtC,CAAC;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,eAAe,GAA2B;IAC9C,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,aAAa;CAC3B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,EAAU,EAAE,KAAsB;IACjE,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,gDAAgD;IAChD,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,MAAM,MAAM,GAAc,CAAC,EAAE,CAAC,CAAC,CAAC,sBAAsB;IACtD,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;QAC9D,MAAM,KAAK,GAAG,KAAK,CAAC,KAA8B,CAAC,CAAC;QACpD,yEAAyE;QACzE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,UAAU,CAAC,IAAI,CAAC,GAAG,MAAM,OAAO,UAAU,EAAE,CAAC,CAAC;YAC9C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,UAAU,EAAE,CAAC;QACf,CAAC;IACH,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACzC,CAAC;IAED,MAAM,GAAG,GAAG,oBAAoB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,4BAA4B,CAAC;IAClF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAU,GAAG,EAAE,MAAM,CAAC,CAAC;IAEtD,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACtC,CAAC;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,EAAU;IACzC,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,iCAAiC,EACjC,CAAC,EAAE,CAAC,CACL,CAAC;IAEF,OAAO,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,8EAA8E;AAC9E,OAAO;AACP,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,aAAqB;IAChE,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,iEAAiE,EACjE,CAAC,aAAa,CAAC,CAChB,CAAC;IAEF,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AACvC,CAAC;AAED,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,aAAqB,EACrB,IAAY,EACZ,SAAkB;IAElB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,mGAAmG,EACnG,CAAC,aAAa,EAAE,IAAI,EAAE,SAAS,CAAC,CACjC,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,sFAAsF,EACtF,CAAC,aAAa,EAAE,IAAI,CAAC,CACtB,CAAC;IACF,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AAC/B,CAAC;AAED,8EAA8E;AAC9E,8BAA8B;AAC9B,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAc;IACrD,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,kEAAkE,EAClE,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAC5C,CAAC"}

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

@@ -0,0 +1,111 @@
+/**
+ * Role service — business logic for role management.
+ *
+ * Orchestrates role CRUD operations with slug validation, uniqueness
+ * checks, deletion guards, cache management, and audit logging.
+ * Also handles role-permission assignment operations.
+ *
+ * All write operations follow the pattern:
+ *   validate → DB operation → cache invalidate/re-cache → audit log
+ *
+ * Uses fire-and-forget audit logging — audit failures never block
+ * the primary operation.
+ *
+ * @see role-repository.ts — Database operations
+ * @see mapping-repository.ts — Role-permission join table operations
+ * @see cache.ts — Redis cache operations
+ */
+import type { Role, Permission, CreateRoleInput, UpdateRoleInput } from './types.js';
+/**
+ * Create a new role for an application.
+ *
+ * Auto-generates a slug from the name if not explicitly provided.
+ * Validates slug format and ensures uniqueness within the application.
+ *
+ * @param input - Role creation data
+ * @param actorId - Optional UUID of the admin performing the action
+ * @returns The newly created role
+ * @throws RbacValidationError if slug is invalid or already exists
+ */
+export declare function createRole(input: CreateRoleInput, actorId?: string): Promise<Role>;
+/**
+ * Find a role by ID. Cache-first, falls back to DB.
+ *
+ * @param id - Role UUID
+ * @returns Role or null if not found
+ */
+export declare function findRoleById(id: string): Promise<Role | null>;
+/**
+ * Find a role by application ID and slug.
+ *
+ * @param applicationId - Application UUID
+ * @param slug - Role slug
+ * @returns Role or null if not found
+ */
+export declare function findRoleBySlug(applicationId: string, slug: string): Promise<Role | null>;
+/**
+ * List all roles for an application.
+ *
+ * @param applicationId - Application UUID
+ * @returns Array of roles
+ */
+export declare function listRolesByApplication(applicationId: string): Promise<Role[]>;
+/**
+ * Update a role by ID.
+ *
+ * If the slug is being changed, validates the new slug format and
+ * checks uniqueness within the application. Invalidates and re-caches
+ * the role after update.
+ *
+ * @param id - Role UUID
+ * @param input - Fields to update
+ * @param actorId - Optional UUID of the admin performing the action
+ * @returns Updated role
+ * @throws RoleNotFoundError if role doesn't exist
+ * @throws RbacValidationError if new slug is invalid or already exists
+ */
+export declare function updateRole(id: string, input: UpdateRoleInput, actorId?: string): Promise<Role>;
+/**
+ * Delete a role by ID.
+ *
+ * By default (force=false), refuses to delete roles that have users
+ * assigned. Pass force=true to delete regardless — CASCADE will
+ * remove user_roles and role_permissions entries.
+ *
+ * @param id - Role UUID
+ * @param force - If true, delete even if users are assigned
+ * @param actorId - Optional UUID of the admin performing the action
+ * @throws RoleNotFoundError if role doesn't exist
+ * @throws RbacValidationError if users are assigned and force is false
+ */
+export declare function deleteRole(id: string, force?: boolean, actorId?: string): Promise<void>;
+/**
+ * Assign permissions to a role.
+ *
+ * Delegates to the mapping repository for bulk insert. Invalidates
+ * all user RBAC caches since user permissions may have changed.
+ *
+ * @param roleId - Role UUID
+ * @param permissionIds - Array of permission UUIDs to assign
+ * @param actorId - Optional UUID of the admin performing the action
+ */
+export declare function assignPermissionsToRole(roleId: string, permissionIds: string[], actorId?: string): Promise<void>;
+/**
+ * Remove permissions from a role.
+ *
+ * Delegates to the mapping repository. Invalidates all user RBAC
+ * caches since user permissions may have changed.
+ *
+ * @param roleId - Role UUID
+ * @param permissionIds - Array of permission UUIDs to remove
+ * @param actorId - Optional UUID of the admin performing the action
+ */
+export declare function removePermissionsFromRole(roleId: string, permissionIds: string[], actorId?: string): Promise<void>;
+/**
+ * Get all permissions assigned to a role.
+ *
+ * @param roleId - Role UUID
+ * @returns Array of permissions
+ */
+export declare function getPermissionsForRole(roleId: string): Promise<Permission[]>;
+//# sourceMappingURL=role-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"role-service.d.ts","sourceRoot":"","sources":["../../src/rbac/role-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA0BH,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAMrF;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkCxF;AAMD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAanE;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAE9F;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAEnF;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAuCf;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,MAAM,EACV,KAAK,GAAE,OAAe,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAkCf;AAMD;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EAAE,EACvB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EAAE,EACvB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAEjF"}