@portaidentity/server 1.7.0

package/dist/rbac/role-service.js

@@ -0,0 +1,256 @@
+/**
+ * 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 { insertRole, findRoleById as repoFindRoleById, findRoleBySlug as repoFindRoleBySlug, updateRole as repoUpdateRole, deleteRole as repoDeleteRole, listRolesByApplication as repoListRolesByApplication, roleSlugExists, countUsersWithRole, } from './role-repository.js';
+import { assignPermissionsToRole as repoAssignPermissions, removePermissionsFromRole as repoRemovePermissions, getPermissionsForRole as repoGetPermissionsForRole, } from './mapping-repository.js';
+import { getCachedRole, setCachedRole, invalidateRoleCache, invalidateAllUserRbacCaches, } from './cache.js';
+import { generateRoleSlug, validateRoleSlug } from './slugs.js';
+import { RoleNotFoundError, RbacValidationError } from './errors.js';
+import { writeAuditLog } from '../lib/audit-log.js';
+// ---------------------------------------------------------------------------
+// Create
+// ---------------------------------------------------------------------------
+/**
+ * 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 async function createRole(input, actorId) {
+    // Generate slug from name if not provided
+    const slug = input.slug ?? generateRoleSlug(input.name);
+    // Validate slug format
+    if (!validateRoleSlug(slug)) {
+        throw new RbacValidationError(`Invalid role slug format: "${slug}". Must be 1-100 chars, lowercase alphanumeric and hyphens.`);
+    }
+    // Check slug uniqueness within the application
+    const exists = await roleSlugExists(input.applicationId, slug);
+    if (exists) {
+        throw new RbacValidationError(`Role slug "${slug}" already exists for this application.`);
+    }
+    // Insert with the validated slug
+    const role = await insertRole({ ...input, slug });
+    // Cache the new role
+    await setCachedRole(role);
+    // Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'role.created',
+        eventCategory: 'admin',
+        actorId,
+        metadata: { roleId: role.id, applicationId: role.applicationId, slug: role.slug },
+    });
+    return role;
+}
+// ---------------------------------------------------------------------------
+// Read
+// ---------------------------------------------------------------------------
+/**
+ * Find a role by ID. Cache-first, falls back to DB.
+ *
+ * @param id - Role UUID
+ * @returns Role or null if not found
+ */
+export async function findRoleById(id) {
+    // Try cache first
+    const cached = await getCachedRole(id);
+    if (cached)
+        return cached;
+    // Cache miss — query DB
+    const role = await repoFindRoleById(id);
+    if (role) {
+        // Cache for future lookups
+        await setCachedRole(role);
+    }
+    return role;
+}
+/**
+ * Find a role by application ID and slug.
+ *
+ * @param applicationId - Application UUID
+ * @param slug - Role slug
+ * @returns Role or null if not found
+ */
+export async function findRoleBySlug(applicationId, slug) {
+    return repoFindRoleBySlug(applicationId, slug);
+}
+/**
+ * List all roles for an application.
+ *
+ * @param applicationId - Application UUID
+ * @returns Array of roles
+ */
+export async function listRolesByApplication(applicationId) {
+    return repoListRolesByApplication(applicationId);
+}
+// ---------------------------------------------------------------------------
+// Update
+// ---------------------------------------------------------------------------
+/**
+ * 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 async function updateRole(id, input, actorId) {
+    // Verify role exists (needed for applicationId if slug is changing)
+    const existing = await repoFindRoleById(id);
+    if (!existing) {
+        throw new RoleNotFoundError(id);
+    }
+    // If slug is changing, validate format and uniqueness
+    if (input.slug !== undefined && input.slug !== existing.slug) {
+        if (!validateRoleSlug(input.slug)) {
+            throw new RbacValidationError(`Invalid role slug format: "${input.slug}". Must be 1-100 chars, lowercase alphanumeric and hyphens.`);
+        }
+        const slugTaken = await roleSlugExists(existing.applicationId, input.slug, id);
+        if (slugTaken) {
+            throw new RbacValidationError(`Role slug "${input.slug}" already exists for this application.`);
+        }
+    }
+    // Perform the update
+    const updated = await repoUpdateRole(id, input);
+    // Invalidate old cache and store updated role
+    await invalidateRoleCache(id);
+    await setCachedRole(updated);
+    // Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'role.updated',
+        eventCategory: 'admin',
+        actorId,
+        metadata: { roleId: id, changes: input },
+    });
+    return updated;
+}
+// ---------------------------------------------------------------------------
+// Delete
+// ---------------------------------------------------------------------------
+/**
+ * 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 async function deleteRole(id, force = false, actorId) {
+    // Verify role exists
+    const existing = await repoFindRoleById(id);
+    if (!existing) {
+        throw new RoleNotFoundError(id);
+    }
+    // Deletion guard: check for assigned users
+    if (!force) {
+        const userCount = await countUsersWithRole(id);
+        if (userCount > 0) {
+            throw new RbacValidationError(`Cannot delete role "${existing.slug}": ${userCount} user(s) still assigned. Use force=true to override.`);
+        }
+    }
+    // Delete the role (CASCADE handles related records)
+    await repoDeleteRole(id);
+    // Invalidate caches
+    await invalidateRoleCache(id);
+    // User caches may be stale if role had users (force=true case)
+    if (force) {
+        await invalidateAllUserRbacCaches();
+    }
+    // Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'role.deleted',
+        eventCategory: 'admin',
+        actorId,
+        metadata: { roleId: id, slug: existing.slug, force },
+    });
+}
+// ---------------------------------------------------------------------------
+// Role-Permission management
+// ---------------------------------------------------------------------------
+/**
+ * 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 async function assignPermissionsToRole(roleId, permissionIds, actorId) {
+    if (permissionIds.length === 0)
+        return;
+    await repoAssignPermissions(roleId, permissionIds);
+    // Invalidate all user RBAC caches — permissions through roles may have changed
+    await invalidateAllUserRbacCaches();
+    // Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'role.permissions.assigned',
+        eventCategory: 'admin',
+        actorId,
+        metadata: { roleId, permissionIds },
+    });
+}
+/**
+ * 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 async function removePermissionsFromRole(roleId, permissionIds, actorId) {
+    if (permissionIds.length === 0)
+        return;
+    await repoRemovePermissions(roleId, permissionIds);
+    // Invalidate all user RBAC caches
+    await invalidateAllUserRbacCaches();
+    // Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'role.permissions.removed',
+        eventCategory: 'admin',
+        actorId,
+        metadata: { roleId, permissionIds },
+    });
+}
+/**
+ * Get all permissions assigned to a role.
+ *
+ * @param roleId - Role UUID
+ * @returns Array of permissions
+ */
+export async function getPermissionsForRole(roleId) {
+    return repoGetPermissionsForRole(roleId);
+}
+//# sourceMappingURL=role-service.js.map

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

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

package/dist/rbac/slugs.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Slug generation and validation utilities for RBAC.
+ *
+ * Two types of slugs are used in the RBAC module:
+ *
+ * 1. **Role slugs** — kebab-case identifiers (e.g., "crm-editor").
+ *    Same format as organization/application slugs. Auto-generated
+ *    from role names or provided manually.
+ *
+ * 2. **Permission slugs** — colon-separated namespaced identifiers
+ *    following the `module:resource:action` format (e.g., "crm:contacts:read").
+ *    Each segment must be lowercase alphanumeric with hyphens.
+ *    Minimum 3 segments required.
+ *
+ * This module provides:
+ * - `generateRoleSlug(name)` — Derive a role slug from a role name
+ * - `validateRoleSlug(slug)` — Check role slug format (kebab-case, 1-100 chars)
+ * - `validatePermissionSlug(slug)` — Check permission slug follows module:resource:action
+ * - `parsePermissionSlug(slug)` — Decompose a permission slug into its parts
+ */
+/**
+ * Generate a URL-safe slug from a role name.
+ *
+ * Uses the same slugification logic as organizations/applications:
+ * 1. Convert to lowercase
+ * 2. Replace non-alphanumeric characters with hyphens
+ * 3. Collapse multiple consecutive hyphens into one
+ * 4. Trim leading and trailing hyphens
+ * 5. Truncate to 100 characters (trimming trailing hyphens after truncation)
+ *
+ * Returns an empty string for empty/whitespace-only input — the caller
+ * (service layer) is responsible for validation.
+ *
+ * @param name - Role name to derive a slug from
+ * @returns Generated slug string
+ *
+ * @example
+ * generateRoleSlug('CRM Editor')       // "crm-editor"
+ * generateRoleSlug('Invoice Approver') // "invoice-approver"
+ * generateRoleSlug('')                 // ""
+ */
+export declare function generateRoleSlug(name: string): string;
+/**
+ * Validate a role slug format.
+ *
+ * Rules:
+ * - 1–100 characters long
+ * - Lowercase alphanumeric characters and hyphens only
+ * - Cannot start or end with a hyphen
+ * - Empty strings are invalid
+ *
+ * Does NOT check uniqueness — that's the repository/service layer's job.
+ *
+ * @param slug - Role slug string to validate
+ * @returns true if the slug format is valid, false otherwise
+ *
+ * @example
+ * validateRoleSlug('crm-editor')  // true
+ * validateRoleSlug('admin')       // true
+ * validateRoleSlug('CRM Editor')  // false (spaces, uppercase)
+ * validateRoleSlug('')            // false (empty)
+ */
+export declare function validateRoleSlug(slug: string): boolean;
+/**
+ * Validate a permission slug follows the module:resource:action format.
+ *
+ * Rules:
+ * - Must have at least 3 segments separated by colons
+ * - Each segment must be lowercase alphanumeric with hyphens
+ * - Each segment must start and end with an alphanumeric character
+ * - Empty segments are not allowed
+ * - Total length must not exceed 150 characters (matches DB column)
+ *
+ * @param slug - Permission slug to validate
+ * @returns true if the slug format is valid, false otherwise
+ *
+ * @example
+ * validatePermissionSlug('crm:contacts:read')     // true
+ * validatePermissionSlug('admin:system:manage')    // true
+ * validatePermissionSlug('crm:sub-module:items:write') // true (4+ segments OK)
+ * validatePermissionSlug('contacts-read')          // false (no colons)
+ * validatePermissionSlug('a:b')                    // false (only 2 segments)
+ * validatePermissionSlug('')                       // false (empty)
+ */
+export declare function validatePermissionSlug(slug: string): boolean;
+/** Parsed components of a permission slug. */
+export interface ParsedPermissionSlug {
+    module: string;
+    resource: string;
+    action: string;
+}
+/**
+ * Parse a permission slug into its module, resource, and action components.
+ *
+ * The first segment is the module, the last segment is the action,
+ * and everything in between is joined as the resource. This supports
+ * both 3-segment slugs (crm:contacts:read) and 4+ segment slugs
+ * (crm:sub-module:items:write → module="crm", resource="sub-module:items", action="write").
+ *
+ * Returns null if the slug is invalid (fails validatePermissionSlug).
+ *
+ * @param slug - Permission slug to parse
+ * @returns Parsed components or null if invalid
+ *
+ * @example
+ * parsePermissionSlug('crm:contacts:read')
+ * // { module: 'crm', resource: 'contacts', action: 'read' }
+ *
+ * parsePermissionSlug('crm:sub:items:write')
+ * // { module: 'crm', resource: 'sub:items', action: 'write' }
+ *
+ * parsePermissionSlug('invalid')
+ * // null
+ */
+export declare function parsePermissionSlug(slug: string): ParsedPermissionSlug | null;
+//# sourceMappingURL=slugs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"slugs.d.ts","sourceRoot":"","sources":["../../src/rbac/slugs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA2BH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAgBrD;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOtD;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAgB5D;AAMD,8CAA8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAY7E"}

package/dist/rbac/slugs.js

@@ -0,0 +1,178 @@
+/**
+ * Slug generation and validation utilities for RBAC.
+ *
+ * Two types of slugs are used in the RBAC module:
+ *
+ * 1. **Role slugs** — kebab-case identifiers (e.g., "crm-editor").
+ *    Same format as organization/application slugs. Auto-generated
+ *    from role names or provided manually.
+ *
+ * 2. **Permission slugs** — colon-separated namespaced identifiers
+ *    following the `module:resource:action` format (e.g., "crm:contacts:read").
+ *    Each segment must be lowercase alphanumeric with hyphens.
+ *    Minimum 3 segments required.
+ *
+ * This module provides:
+ * - `generateRoleSlug(name)` — Derive a role slug from a role name
+ * - `validateRoleSlug(slug)` — Check role slug format (kebab-case, 1-100 chars)
+ * - `validatePermissionSlug(slug)` — Check permission slug follows module:resource:action
+ * - `parsePermissionSlug(slug)` — Decompose a permission slug into its parts
+ */
+// ---------------------------------------------------------------------------
+// Role slug format
+// ---------------------------------------------------------------------------
+/**
+ * Role slug format regex: 1–100 characters, lowercase alphanumeric + hyphens.
+ * Must start and end with an alphanumeric character (no leading/trailing hyphens).
+ * Single character slugs are allowed (unlike organization slugs which require 3+).
+ */
+const ROLE_SLUG_REGEX = /^[a-z0-9]([a-z0-9-]{0,98}[a-z0-9])?$/;
+// ---------------------------------------------------------------------------
+// Permission slug format
+// ---------------------------------------------------------------------------
+/**
+ * Each segment of a permission slug: lowercase alphanumeric + hyphens,
+ * must start and end with an alphanumeric character.
+ */
+const PERMISSION_SEGMENT_REGEX = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+// ---------------------------------------------------------------------------
+// Role slug generation
+// ---------------------------------------------------------------------------
+/**
+ * Generate a URL-safe slug from a role name.
+ *
+ * Uses the same slugification logic as organizations/applications:
+ * 1. Convert to lowercase
+ * 2. Replace non-alphanumeric characters with hyphens
+ * 3. Collapse multiple consecutive hyphens into one
+ * 4. Trim leading and trailing hyphens
+ * 5. Truncate to 100 characters (trimming trailing hyphens after truncation)
+ *
+ * Returns an empty string for empty/whitespace-only input — the caller
+ * (service layer) is responsible for validation.
+ *
+ * @param name - Role name to derive a slug from
+ * @returns Generated slug string
+ *
+ * @example
+ * generateRoleSlug('CRM Editor')       // "crm-editor"
+ * generateRoleSlug('Invoice Approver') // "invoice-approver"
+ * generateRoleSlug('')                 // ""
+ */
+export function generateRoleSlug(name) {
+    if (!name || !name.trim()) {
+        return '';
+    }
+    const slug = name
+        .toLowerCase()
+        // Replace any character that's not a-z, 0-9, or hyphen with a hyphen
+        .replace(/[^a-z0-9-]/g, '-')
+        // Collapse consecutive hyphens into a single hyphen
+        .replace(/-+/g, '-')
+        // Remove leading and trailing hyphens
+        .replace(/^-+|-+$/g, '');
+    // Truncate to 100 characters, then trim any trailing hyphen caused by truncation
+    return slug.slice(0, 100).replace(/-+$/, '');
+}
+// ---------------------------------------------------------------------------
+// Role slug validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate a role slug format.
+ *
+ * Rules:
+ * - 1–100 characters long
+ * - Lowercase alphanumeric characters and hyphens only
+ * - Cannot start or end with a hyphen
+ * - Empty strings are invalid
+ *
+ * Does NOT check uniqueness — that's the repository/service layer's job.
+ *
+ * @param slug - Role slug string to validate
+ * @returns true if the slug format is valid, false otherwise
+ *
+ * @example
+ * validateRoleSlug('crm-editor')  // true
+ * validateRoleSlug('admin')       // true
+ * validateRoleSlug('CRM Editor')  // false (spaces, uppercase)
+ * validateRoleSlug('')            // false (empty)
+ */
+export function validateRoleSlug(slug) {
+    // Must be 1–100 characters
+    if (!slug || slug.length > 100) {
+        return false;
+    }
+    return ROLE_SLUG_REGEX.test(slug);
+}
+// ---------------------------------------------------------------------------
+// Permission slug validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate a permission slug follows the module:resource:action format.
+ *
+ * Rules:
+ * - Must have at least 3 segments separated by colons
+ * - Each segment must be lowercase alphanumeric with hyphens
+ * - Each segment must start and end with an alphanumeric character
+ * - Empty segments are not allowed
+ * - Total length must not exceed 150 characters (matches DB column)
+ *
+ * @param slug - Permission slug to validate
+ * @returns true if the slug format is valid, false otherwise
+ *
+ * @example
+ * validatePermissionSlug('crm:contacts:read')     // true
+ * validatePermissionSlug('admin:system:manage')    // true
+ * validatePermissionSlug('crm:sub-module:items:write') // true (4+ segments OK)
+ * validatePermissionSlug('contacts-read')          // false (no colons)
+ * validatePermissionSlug('a:b')                    // false (only 2 segments)
+ * validatePermissionSlug('')                       // false (empty)
+ */
+export function validatePermissionSlug(slug) {
+    // Must be non-empty and within DB column limit (VARCHAR(150))
+    if (!slug || slug.length > 150) {
+        return false;
+    }
+    // Split on colons — need at least 3 segments
+    const segments = slug.split(':');
+    if (segments.length < 3) {
+        return false;
+    }
+    // Each segment must match the segment format
+    return segments.every((segment) => segment.length > 0 && PERMISSION_SEGMENT_REGEX.test(segment));
+}
+/**
+ * Parse a permission slug into its module, resource, and action components.
+ *
+ * The first segment is the module, the last segment is the action,
+ * and everything in between is joined as the resource. This supports
+ * both 3-segment slugs (crm:contacts:read) and 4+ segment slugs
+ * (crm:sub-module:items:write → module="crm", resource="sub-module:items", action="write").
+ *
+ * Returns null if the slug is invalid (fails validatePermissionSlug).
+ *
+ * @param slug - Permission slug to parse
+ * @returns Parsed components or null if invalid
+ *
+ * @example
+ * parsePermissionSlug('crm:contacts:read')
+ * // { module: 'crm', resource: 'contacts', action: 'read' }
+ *
+ * parsePermissionSlug('crm:sub:items:write')
+ * // { module: 'crm', resource: 'sub:items', action: 'write' }
+ *
+ * parsePermissionSlug('invalid')
+ * // null
+ */
+export function parsePermissionSlug(slug) {
+    if (!validatePermissionSlug(slug)) {
+        return null;
+    }
+    const segments = slug.split(':');
+    // First segment = module, last = action, middle = resource
+    const module = segments[0];
+    const action = segments[segments.length - 1];
+    const resource = segments.slice(1, -1).join(':');
+    return { module, resource, action };
+}
+//# sourceMappingURL=slugs.js.map

package/dist/rbac/slugs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slugs.js","sourceRoot":"","sources":["../../src/rbac/slugs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,eAAe,GAAG,sCAAsC,CAAC;AAE/D,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,wBAAwB,GAAG,iCAAiC,CAAC;AAEnE,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QAC1B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,IAAI,GAAG,IAAI;SACd,WAAW,EAAE;QACd,qEAAqE;SACpE,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;QAC5B,oDAAoD;SACnD,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;QACpB,sCAAsC;SACrC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAE3B,iFAAiF;IACjF,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,2BAA2B;IAC3B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,8EAA8E;AAC9E,6BAA6B;AAC7B,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,8DAA8D;IAC9D,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,6CAA6C;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,6CAA6C;IAC7C,OAAO,QAAQ,CAAC,KAAK,CACnB,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,wBAAwB,CAAC,IAAI,CAAC,OAAO,CAAC,CAC1E,CAAC;AACJ,CAAC;AAaD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,2DAA2D;IAC3D,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC3B,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEjD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AACtC,CAAC"}