@portaidentity/server 1.7.0

package/dist/rbac/mapping-repository.js

@@ -0,0 +1,224 @@
+/**
+ * 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 { getPool } from '../lib/database.js';
+import { mapRowToRole, mapRowToPermission, mapRowToUserRole } from './types.js';
+// ===========================================================================
+// Role-Permission Mapping
+// ===========================================================================
+/**
+ * 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 async function assignPermissionsToRole(roleId, permissionIds) {
+    if (permissionIds.length === 0)
+        return;
+    const pool = getPool();
+    // Build parameterized VALUES list: ($1, $2), ($1, $3), ($1, $4), ...
+    // $1 is always the roleId, subsequent params are permission IDs
+    const valuesList = [];
+    const params = [roleId];
+    for (let i = 0; i < permissionIds.length; i++) {
+        params.push(permissionIds[i]);
+        valuesList.push(`($1, $${i + 2})`);
+    }
+    await pool.query(`INSERT INTO role_permissions (role_id, permission_id)
+     VALUES ${valuesList.join(', ')}
+     ON CONFLICT DO NOTHING`, params);
+}
+/**
+ * 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 async function removePermissionsFromRole(roleId, permissionIds) {
+    if (permissionIds.length === 0)
+        return;
+    const pool = getPool();
+    // Build parameterized IN list: $2, $3, $4, ...
+    const placeholders = permissionIds.map((_, i) => `$${i + 2}`).join(', ');
+    const params = [roleId, ...permissionIds];
+    await pool.query(`DELETE FROM role_permissions WHERE role_id = $1 AND permission_id IN (${placeholders})`, params);
+}
+/**
+ * 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 async function getPermissionsForRole(roleId) {
+    const pool = getPool();
+    const result = await pool.query(`SELECT p.*
+     FROM role_permissions rp
+     JOIN permissions p ON p.id = rp.permission_id
+     WHERE rp.role_id = $1
+     ORDER BY p.slug ASC`, [roleId]);
+    return result.rows.map(mapRowToPermission);
+}
+/**
+ * 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 async function getRolesWithPermission(permissionId) {
+    const pool = getPool();
+    const result = await pool.query(`SELECT r.*
+     FROM role_permissions rp
+     JOIN roles r ON r.id = rp.role_id
+     WHERE rp.permission_id = $1
+     ORDER BY r.name ASC`, [permissionId]);
+    return result.rows.map(mapRowToRole);
+}
+// ===========================================================================
+// User-Role Mapping
+// ===========================================================================
+/**
+ * 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 async function assignRolesToUser(userId, roleIds, assignedBy) {
+    if (roleIds.length === 0)
+        return;
+    const pool = getPool();
+    // Build parameterized VALUES list
+    // $1 = userId, $2 = assignedBy (or null), subsequent params = roleIds
+    const valuesList = [];
+    const params = [userId, assignedBy ?? null];
+    for (let i = 0; i < roleIds.length; i++) {
+        params.push(roleIds[i]);
+        valuesList.push(`($1, $${i + 3}, $2)`);
+    }
+    await pool.query(`INSERT INTO user_roles (user_id, role_id, assigned_by)
+     VALUES ${valuesList.join(', ')}
+     ON CONFLICT DO NOTHING`, params);
+}
+/**
+ * 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 async function removeRolesFromUser(userId, roleIds) {
+    if (roleIds.length === 0)
+        return;
+    const pool = getPool();
+    // Build parameterized IN list: $2, $3, $4, ...
+    const placeholders = roleIds.map((_, i) => `$${i + 2}`).join(', ');
+    const params = [userId, ...roleIds];
+    await pool.query(`DELETE FROM user_roles WHERE user_id = $1 AND role_id IN (${placeholders})`, params);
+}
+/**
+ * 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 async function getRolesForUser(userId) {
+    const pool = getPool();
+    const result = await pool.query(`SELECT r.*
+     FROM user_roles ur
+     JOIN roles r ON r.id = ur.role_id
+     WHERE ur.user_id = $1
+     ORDER BY r.name ASC`, [userId]);
+    return result.rows.map(mapRowToRole);
+}
+/**
+ * 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 async function getPermissionsForUser(userId) {
+    const pool = getPool();
+    const result = await pool.query(`SELECT DISTINCT p.*
+     FROM user_roles ur
+     JOIN role_permissions rp ON rp.role_id = ur.role_id
+     JOIN permissions p ON p.id = rp.permission_id
+     WHERE ur.user_id = $1
+     ORDER BY p.slug ASC`, [userId]);
+    return result.rows.map(mapRowToPermission);
+}
+/**
+ * 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 async function getUsersWithRole(roleId, orgId, page, pageSize) {
+    const pool = getPool();
+    const offset = (page - 1) * pageSize;
+    // Count total matching assignments
+    const countResult = await pool.query(`SELECT COUNT(*)::int as count
+     FROM user_roles ur
+     JOIN users u ON u.id = ur.user_id
+     WHERE ur.role_id = $1 AND u.organization_id = $2`, [roleId, orgId]);
+    const total = parseInt(countResult.rows[0].count, 10);
+    // Fetch paginated data
+    const dataResult = await pool.query(`SELECT ur.*
+     FROM user_roles ur
+     JOIN users u ON u.id = ur.user_id
+     WHERE ur.role_id = $1 AND u.organization_id = $2
+     ORDER BY ur.created_at DESC
+     LIMIT $3 OFFSET $4`, [roleId, orgId, pageSize, offset]);
+    return {
+        rows: dataResult.rows.map(mapRowToUserRole),
+        total,
+    };
+}
+//# sourceMappingURL=mapping-repository.js.map

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

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

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

@@ -0,0 +1,100 @@
+/**
+ * Permission repository — PostgreSQL data access layer.
+ *
+ * Provides CRUD operations for the `permissions` table using parameterized
+ * queries. Each function acquires the pool via `getPool()` and returns
+ * mapped Permission objects via `mapRowToPermission()`.
+ *
+ * Permissions are scoped to an application (application_id FK) with a
+ * unique slug per application enforced by DB constraint UNIQUE(application_id, slug).
+ * Permissions may optionally be linked to an application module (module_id FK).
+ *
+ * Key patterns:
+ * - Slug is immutable after creation (only name and description can be updated)
+ * - List supports optional module filter for scoped permission views
+ * - Role count for deletion guard (prevent deleting permissions assigned to roles)
+ *
+ * Database table: permissions (see migration 006_roles_permissions.sql)
+ */
+import type { Permission, CreatePermissionInput, UpdatePermissionInput } from './types.js';
+/**
+ * Insert a new permission 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 - Permission data to insert
+ * @returns The newly created permission
+ * @throws If (application_id, slug) already exists (unique constraint violation)
+ */
+export declare function insertPermission(input: CreatePermissionInput): Promise<Permission>;
+/**
+ * Find a permission by its UUID.
+ *
+ * @param id - Permission UUID
+ * @returns Permission or null if not found
+ */
+export declare function findPermissionById(id: string): Promise<Permission | null>;
+/**
+ * Find a permission by application ID and slug.
+ *
+ * @param applicationId - Application UUID
+ * @param slug - Permission slug (unique within application)
+ * @returns Permission or null if not found
+ */
+export declare function findPermissionBySlug(applicationId: string, slug: string): Promise<Permission | null>;
+/**
+ * Update a permission by ID (name and description only — slug is immutable).
+ *
+ * Only explicitly provided fields (not undefined) are included in the
+ * UPDATE statement. Null is a valid value for description (clears it).
+ *
+ * @param id - Permission UUID
+ * @param input - Fields to update (name, description only)
+ * @returns Updated permission
+ * @throws Error if permission not found or no fields provided
+ */
+export declare function updatePermission(id: string, input: UpdatePermissionInput): Promise<Permission>;
+/**
+ * Delete a permission by ID.
+ *
+ * Returns true if a row was deleted, false if the permission didn't exist.
+ * CASCADE constraints will automatically remove related role_permissions entries.
+ *
+ * @param id - Permission UUID
+ * @returns true if deleted, false if not found
+ */
+export declare function deletePermission(id: string): Promise<boolean>;
+/**
+ * List permissions for an application, optionally filtered by module.
+ *
+ * Returns a simple array ordered by slug ascending. When moduleId is
+ * provided, only permissions linked to that module are returned.
+ *
+ * @param applicationId - Application UUID
+ * @param moduleId - Optional module UUID to filter by
+ * @returns Array of permissions
+ */
+export declare function listPermissionsByApplication(applicationId: string, moduleId?: string): Promise<Permission[]>;
+/**
+ * Check if a permission slug already exists for a given application.
+ *
+ * Used for uniqueness validation before insert. Permission slugs are
+ * immutable, so no excludeId parameter is needed (unlike roles).
+ *
+ * @param applicationId - Application UUID
+ * @param slug - Slug to check
+ * @returns true if the slug already exists
+ */
+export declare function permissionSlugExists(applicationId: string, slug: string): Promise<boolean>;
+/**
+ * Count roles that have a specific permission assigned.
+ *
+ * Used by the service layer as a deletion guard: if roles have this
+ * permission, it cannot be deleted without force=true.
+ *
+ * @param permissionId - Permission UUID
+ * @returns Number of roles with this permission
+ */
+export declare function countRolesWithPermission(permissionId: string): Promise<number>;
+//# sourceMappingURL=permission-repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"permission-repository.d.ts","sourceRoot":"","sources":["../../src/rbac/permission-repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAiB,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAO1G;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC,CAiBxF;AAMD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAU/E;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAU5B;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,UAAU,CAAC,CA+BrB;AAMD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASnE;AAMD;;;;;;;;;GASG;AACH,wBAAsB,4BAA4B,CAChD,aAAa,EAAE,MAAM,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,EAAE,CAAC,CAgBvB;AAMD;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC,CAQlB;AAMD;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CASpF"}

package/dist/rbac/permission-repository.js

@@ -0,0 +1,190 @@
+/**
+ * Permission repository — PostgreSQL data access layer.
+ *
+ * Provides CRUD operations for the `permissions` table using parameterized
+ * queries. Each function acquires the pool via `getPool()` and returns
+ * mapped Permission objects via `mapRowToPermission()`.
+ *
+ * Permissions are scoped to an application (application_id FK) with a
+ * unique slug per application enforced by DB constraint UNIQUE(application_id, slug).
+ * Permissions may optionally be linked to an application module (module_id FK).
+ *
+ * Key patterns:
+ * - Slug is immutable after creation (only name and description can be updated)
+ * - List supports optional module filter for scoped permission views
+ * - Role count for deletion guard (prevent deleting permissions assigned to roles)
+ *
+ * Database table: permissions (see migration 006_roles_permissions.sql)
+ */
+import { getPool } from '../lib/database.js';
+import { mapRowToPermission } from './types.js';
+// ---------------------------------------------------------------------------
+// Insert
+// ---------------------------------------------------------------------------
+/**
+ * Insert a new permission 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 - Permission data to insert
+ * @returns The newly created permission
+ * @throws If (application_id, slug) already exists (unique constraint violation)
+ */
+export async function insertPermission(input) {
+    const pool = getPool();
+    const result = await pool.query(`INSERT INTO permissions (application_id, module_id, name, slug, description)
+     VALUES ($1, $2, $3, $4, $5)
+     RETURNING *`, [
+        input.applicationId,
+        input.moduleId ?? null,
+        input.name,
+        input.slug,
+        input.description ?? null,
+    ]);
+    return mapRowToPermission(result.rows[0]);
+}
+// ---------------------------------------------------------------------------
+// Find
+// ---------------------------------------------------------------------------
+/**
+ * Find a permission by its UUID.
+ *
+ * @param id - Permission UUID
+ * @returns Permission or null if not found
+ */
+export async function findPermissionById(id) {
+    const pool = getPool();
+    const result = await pool.query('SELECT * FROM permissions WHERE id = $1', [id]);
+    if (result.rows.length === 0)
+        return null;
+    return mapRowToPermission(result.rows[0]);
+}
+/**
+ * Find a permission by application ID and slug.
+ *
+ * @param applicationId - Application UUID
+ * @param slug - Permission slug (unique within application)
+ * @returns Permission or null if not found
+ */
+export async function findPermissionBySlug(applicationId, slug) {
+    const pool = getPool();
+    const result = await pool.query('SELECT * FROM permissions WHERE application_id = $1 AND slug = $2', [applicationId, slug]);
+    if (result.rows.length === 0)
+        return null;
+    return mapRowToPermission(result.rows[0]);
+}
+// ---------------------------------------------------------------------------
+// Update
+// ---------------------------------------------------------------------------
+/**
+ * Update a permission by ID (name and description only — slug is immutable).
+ *
+ * Only explicitly provided fields (not undefined) are included in the
+ * UPDATE statement. Null is a valid value for description (clears it).
+ *
+ * @param id - Permission UUID
+ * @param input - Fields to update (name, description only)
+ * @returns Updated permission
+ * @throws Error if permission not found or no fields provided
+ */
+export async function updatePermission(id, input) {
+    const pool = getPool();
+    // Build dynamic SET clause — only name and description are updatable
+    const setClauses = [];
+    const values = [id]; // $1 is always the ID
+    let paramIndex = 2;
+    if (input.name !== undefined) {
+        setClauses.push(`name = $${paramIndex}`);
+        values.push(input.name);
+        paramIndex++;
+    }
+    if (input.description !== undefined) {
+        setClauses.push(`description = $${paramIndex}`);
+        values.push(input.description);
+    }
+    if (setClauses.length === 0) {
+        throw new Error('No fields to update');
+    }
+    const sql = `UPDATE permissions SET ${setClauses.join(', ')} WHERE id = $1 RETURNING *`;
+    const result = await pool.query(sql, values);
+    if (result.rows.length === 0) {
+        throw new Error('Permission not found');
+    }
+    return mapRowToPermission(result.rows[0]);
+}
+// ---------------------------------------------------------------------------
+// Delete
+// ---------------------------------------------------------------------------
+/**
+ * Delete a permission by ID.
+ *
+ * Returns true if a row was deleted, false if the permission didn't exist.
+ * CASCADE constraints will automatically remove related role_permissions entries.
+ *
+ * @param id - Permission UUID
+ * @returns true if deleted, false if not found
+ */
+export async function deletePermission(id) {
+    const pool = getPool();
+    const result = await pool.query('DELETE FROM permissions WHERE id = $1', [id]);
+    return (result.rowCount ?? 0) > 0;
+}
+// ---------------------------------------------------------------------------
+// List
+// ---------------------------------------------------------------------------
+/**
+ * List permissions for an application, optionally filtered by module.
+ *
+ * Returns a simple array ordered by slug ascending. When moduleId is
+ * provided, only permissions linked to that module are returned.
+ *
+ * @param applicationId - Application UUID
+ * @param moduleId - Optional module UUID to filter by
+ * @returns Array of permissions
+ */
+export async function listPermissionsByApplication(applicationId, moduleId) {
+    const pool = getPool();
+    if (moduleId) {
+        const result = await pool.query('SELECT * FROM permissions WHERE application_id = $1 AND module_id = $2 ORDER BY slug ASC', [applicationId, moduleId]);
+        return result.rows.map(mapRowToPermission);
+    }
+    const result = await pool.query('SELECT * FROM permissions WHERE application_id = $1 ORDER BY slug ASC', [applicationId]);
+    return result.rows.map(mapRowToPermission);
+}
+// ---------------------------------------------------------------------------
+// Slug existence check
+// ---------------------------------------------------------------------------
+/**
+ * Check if a permission slug already exists for a given application.
+ *
+ * Used for uniqueness validation before insert. Permission slugs are
+ * immutable, so no excludeId parameter is needed (unlike roles).
+ *
+ * @param applicationId - Application UUID
+ * @param slug - Slug to check
+ * @returns true if the slug already exists
+ */
+export async function permissionSlugExists(applicationId, slug) {
+    const pool = getPool();
+    const result = await pool.query('SELECT EXISTS(SELECT 1 FROM permissions WHERE application_id = $1 AND slug = $2) as exists', [applicationId, slug]);
+    return result.rows[0].exists;
+}
+// ---------------------------------------------------------------------------
+// Role count (deletion guard)
+// ---------------------------------------------------------------------------
+/**
+ * Count roles that have a specific permission assigned.
+ *
+ * Used by the service layer as a deletion guard: if roles have this
+ * permission, it cannot be deleted without force=true.
+ *
+ * @param permissionId - Permission UUID
+ * @returns Number of roles with this permission
+ */
+export async function countRolesWithPermission(permissionId) {
+    const pool = getPool();
+    const result = await pool.query('SELECT COUNT(*)::int as count FROM role_permissions WHERE permission_id = $1', [permissionId]);
+    return parseInt(result.rows[0].count, 10);
+}
+//# sourceMappingURL=permission-repository.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"permission-repository.js","sourceRoot":"","sources":["../../src/rbac/permission-repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAA4B;IACjE,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B;;iBAEa,EACb;QACE,KAAK,CAAC,aAAa;QACnB,KAAK,CAAC,QAAQ,IAAI,IAAI;QACtB,KAAK,CAAC,IAAI;QACV,KAAK,CAAC,IAAI;QACV,KAAK,CAAC,WAAW,IAAI,IAAI;KAC1B,CACF,CAAC;IAEF,OAAO,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,8EAA8E;AAC9E,OAAO;AACP,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EAAU;IACjD,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,yCAAyC,EACzC,CAAC,EAAE,CAAC,CACL,CAAC;IAEF,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,aAAqB,EACrB,IAAY;IAEZ,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,mEAAmE,EACnE,CAAC,aAAa,EAAE,IAAI,CAAC,CACtB,CAAC;IAEF,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,EAAU,EACV,KAA4B;IAE5B,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,qEAAqE;IACrE,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,MAAM,MAAM,GAAc,CAAC,EAAE,CAAC,CAAC,CAAC,sBAAsB;IACtD,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,UAAU,CAAC,IAAI,CAAC,WAAW,UAAU,EAAE,CAAC,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,UAAU,EAAE,CAAC;IACf,CAAC;IAED,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACpC,UAAU,CAAC,IAAI,CAAC,kBAAkB,UAAU,EAAE,CAAC,CAAC;QAChD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACzC,CAAC;IAED,MAAM,GAAG,GAAG,0BAA0B,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,4BAA4B,CAAC;IACxF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAgB,GAAG,EAAE,MAAM,CAAC,CAAC;IAE5D,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,EAAU;IAC/C,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,uCAAuC,EACvC,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;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,aAAqB,EACrB,QAAiB;IAEjB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,0FAA0F,EAC1F,CAAC,aAAa,EAAE,QAAQ,CAAC,CAC1B,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,uEAAuE,EACvE,CAAC,aAAa,CAAC,CAChB,CAAC;IACF,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAC7C,CAAC;AAED,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,aAAqB,EACrB,IAAY;IAEZ,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,4FAA4F,EAC5F,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,wBAAwB,CAAC,YAAoB;IACjE,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,8EAA8E,EAC9E,CAAC,YAAY,CAAC,CACf,CAAC;IAEF,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAC5C,CAAC"}

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

@@ -0,0 +1,85 @@
+/**
+ * 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 type { Permission, Role, CreatePermissionInput, UpdatePermissionInput } from './types.js';
+/**
+ * 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 declare function createPermission(input: CreatePermissionInput, actorId?: string): Promise<Permission>;
+/**
+ * Find a permission by ID.
+ *
+ * @param id - Permission UUID
+ * @returns Permission or null if not found
+ */
+export declare function findPermissionById(id: string): Promise<Permission | null>;
+/**
+ * Find a permission by application ID and slug.
+ *
+ * @param applicationId - Application UUID
+ * @param slug - Permission slug
+ * @returns Permission or null if not found
+ */
+export declare function findPermissionBySlug(applicationId: string, slug: string): Promise<Permission | null>;
+/**
+ * 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 declare function listPermissionsByApplication(applicationId: string, moduleId?: string): Promise<Permission[]>;
+/**
+ * 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 declare function updatePermission(id: string, input: UpdatePermissionInput, actorId?: string): Promise<Permission>;
+/**
+ * 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 declare function deletePermission(id: string, force?: boolean, actorId?: string): Promise<void>;
+/**
+ * Get all roles that have a specific permission assigned.
+ *
+ * @param permissionId - Permission UUID
+ * @returns Array of roles with this permission
+ */
+export declare function getRolesWithPermission(permissionId: string): Promise<Role[]>;
+//# sourceMappingURL=permission-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"permission-service.d.ts","sourceRoot":"","sources":["../../src/rbac/permission-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAiBH,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAMjG;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,qBAAqB,EAC5B,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,CAAC,CAgCrB;AAMD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAE/E;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAE5B;AAED;;;;;;GAMG;AACH,wBAAsB,4BAA4B,CAChD,aAAa,EAAE,MAAM,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,EAAE,CAAC,CAEvB;AAMD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,qBAAqB,EAC5B,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,CAAC,CAmBrB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,MAAM,EACV,KAAK,GAAE,OAAe,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAgCf;AAMD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAElF"}