convex-cms 0.0.1

package/dist/component/authorization.js

@@ -0,0 +1,464 @@
+/**
+ * Authorization Module
+ *
+ * Core permission checking logic that evaluates user roles against requested
+ * actions and resources. This module is called internally by all CMS operations
+ * to enforce access control.
+ *
+ * Key concepts:
+ * - Users are mapped to roles via the getUserRole hook (configured in ComponentConfig)
+ * - Roles have permissions that define what actions can be performed on resources
+ * - Permissions can be scoped to "all" (any resource) or "own" (resources created by the user)
+ *
+ * @example
+ * ```typescript
+ * import { requirePermission, checkPermission, UnauthorizedError } from './authorization';
+ *
+ * // In a mutation handler:
+ * const userRole = await getUserRole(userId);
+ * await requirePermission({
+ *   userId,
+ *   role: userRole,
+ *   resource: 'contentEntries',
+ *   action: 'update',
+ *   resourceOwnerId: entry.createdBy,
+ * });
+ *
+ * // Throws UnauthorizedError if permission denied
+ * ```
+ */
+import { hasPermission, getRole, } from "./roles.js";
+/**
+ * Error thrown when a user lacks permission to perform an action.
+ *
+ * Includes detailed context about the failed authorization check,
+ * making it easy to understand why access was denied.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await requirePermission({ ... });
+ * } catch (error) {
+ *   if (error instanceof UnauthorizedError) {
+ *     console.log(error.code);      // 'PERMISSION_DENIED'
+ *     console.log(error.resource);  // 'contentEntries'
+ *     console.log(error.action);    // 'delete'
+ *     console.log(error.message);   // Human-readable message
+ *   }
+ * }
+ * ```
+ */
+export class UnauthorizedError extends Error {
+    /** Machine-readable error code for classification */
+    code;
+    /** The resource being accessed (if applicable) */
+    resource;
+    /** The action being attempted (if applicable) */
+    action;
+    /** The user's role (if known) */
+    role;
+    /** The user ID (if provided) */
+    userId;
+    /** The scope that was required but not granted */
+    requiredScope;
+    constructor(message, options) {
+        super(message);
+        this.name = "UnauthorizedError";
+        this.code = options.code;
+        this.resource = options.resource;
+        this.action = options.action;
+        this.role = options.role;
+        this.userId = options.userId;
+        this.requiredScope = options.requiredScope;
+        // Maintains proper stack trace in V8 environments
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, UnauthorizedError);
+        }
+    }
+    /**
+     * Create a JSON-serializable representation of the error.
+     * Useful for logging or API responses.
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            resource: this.resource,
+            action: this.action,
+            role: this.role,
+            userId: this.userId,
+            requiredScope: this.requiredScope,
+        };
+    }
+}
+/**
+ * Get a human-readable label for a resource.
+ */
+function getResourceLabel(resource) {
+    const labels = {
+        contentTypes: "content types",
+        contentEntries: "content entries",
+        mediaItems: "media items",
+        settings: "settings",
+    };
+    return labels[resource] ?? resource;
+}
+/**
+ * Get a human-readable label for an action.
+ */
+function getActionLabel(action) {
+    const labels = {
+        create: "create",
+        read: "view",
+        update: "update",
+        delete: "delete",
+        publish: "publish",
+        unpublish: "unpublish",
+        restore: "restore",
+        manage: "manage",
+        move: "move",
+    };
+    return labels[action] ?? action;
+}
+/**
+ * Generate a descriptive error message for a permission denial.
+ */
+function generateDenialMessage(options) {
+    const { code, role, resource, action, requiredScope: _requiredScope } = options;
+    const resourceLabel = getResourceLabel(resource);
+    const actionLabel = getActionLabel(action);
+    switch (code) {
+        case "NO_ROLE":
+            return `Access denied: No role assigned. You need a valid role to ${actionLabel} ${resourceLabel}.`;
+        case "UNKNOWN_ROLE":
+            return `Access denied: Unknown role "${role}". Contact an administrator to fix your role assignment.`;
+        case "PERMISSION_DENIED":
+            return `Access denied: The "${role}" role does not have permission to ${actionLabel} ${resourceLabel}.`;
+        case "OWNERSHIP_REQUIRED":
+            return `Access denied: The "${role}" role can only ${actionLabel} their own ${resourceLabel}. ` +
+                `You can only perform this action on items you created.`;
+        case "INVALID_RESOURCE":
+            return `Invalid resource type: "${resource}". This is a system error.`;
+        case "INVALID_ACTION":
+            return `Invalid action type: "${action}". This is a system error.`;
+        default:
+            return `Access denied: Cannot ${actionLabel} ${resourceLabel}.`;
+    }
+}
+/**
+ * Check if a user has permission to perform an action on a resource.
+ *
+ * This is the core permission evaluation function. It returns a result object
+ * indicating whether the permission was granted or denied, with details about
+ * why.
+ *
+ * The function checks permissions in the following order:
+ * 1. Validates that the user has a role assigned
+ * 2. Validates that the role exists (in default or custom roles)
+ * 3. Checks if the role has the required permission
+ * 4. For "own" scope permissions, validates ownership if resourceOwnerId is provided
+ *
+ * @param options - The permission check configuration
+ * @returns Result indicating whether permission was granted or denied
+ *
+ * @example
+ * ```typescript
+ * // Check if an editor can update any content entry
+ * const result = checkPermission({
+ *   role: 'editor',
+ *   resource: 'contentEntries',
+ *   action: 'update',
+ * });
+ * if (result.allowed) {
+ *   console.log('Permission granted with scope:', result.grantedScope);
+ * }
+ *
+ * // Check if an author can update their own content entry
+ * const result = checkPermission({
+ *   userId: 'user123',
+ *   role: 'author',
+ *   resource: 'contentEntries',
+ *   action: 'update',
+ *   resourceOwnerId: 'user123', // Same as userId - ownership verified
+ * });
+ * ```
+ */
+export function checkPermission(options) {
+    const { userId, role, resource, action, resourceOwnerId, customRoles } = options;
+    // Check 1: User must have a role assigned
+    if (role === null || role === undefined) {
+        return {
+            allowed: false,
+            reason: "No role assigned to user",
+            code: "NO_ROLE",
+        };
+    }
+    // Check 2: Role must exist
+    const roleDefinition = getRole(role, customRoles);
+    if (!roleDefinition) {
+        return {
+            allowed: false,
+            reason: `Unknown role: ${role}`,
+            code: "UNKNOWN_ROLE",
+        };
+    }
+    // Check 3: Check if role has permission with "all" scope
+    if (hasPermission(role, { resource, action, scope: "all" }, customRoles)) {
+        return {
+            allowed: true,
+            grantedScope: "all",
+            ownershipVerified: false,
+        };
+    }
+    // Check 4: Check if role has permission with "own" scope
+    if (hasPermission(role, { resource, action, scope: "own" }, customRoles)) {
+        // If no resourceOwnerId provided, we cannot verify ownership - deny access
+        // for defense-in-depth (callers must always provide resourceOwnerId for
+        // ownership-scoped operations)
+        if (resourceOwnerId === undefined) {
+            return {
+                allowed: false,
+                reason: "Ownership cannot be verified: resourceOwnerId not provided",
+                code: "OWNERSHIP_REQUIRED",
+            };
+        }
+        // Verify ownership: user must own the resource
+        if (userId !== undefined && resourceOwnerId === userId) {
+            return {
+                allowed: true,
+                grantedScope: "own",
+                ownershipVerified: true,
+            };
+        }
+        // User has "own" permission but doesn't own this resource
+        return {
+            allowed: false,
+            reason: `Ownership required: user does not own this resource`,
+            code: "OWNERSHIP_REQUIRED",
+        };
+    }
+    // No matching permission found
+    return {
+        allowed: false,
+        reason: `Role "${role}" does not have ${action} permission on ${resource}`,
+        code: "PERMISSION_DENIED",
+    };
+}
+/**
+ * Require that a user has permission to perform an action.
+ *
+ * This is the throwing version of `checkPermission`. It's designed to be used
+ * at the start of mutation/query handlers to enforce access control. If the
+ * permission check fails, it throws an UnauthorizedError with a descriptive
+ * message.
+ *
+ * @param options - The permission check configuration
+ * @returns The granted permission details (if allowed)
+ * @throws UnauthorizedError if the permission is denied
+ *
+ * @example
+ * ```typescript
+ * // In a content entry update mutation:
+ * export const updateEntry = mutation({
+ *   args: { id: v.id("contentEntries"), data: v.any() },
+ *   handler: async (ctx, { id, data }) => {
+ *     const entry = await ctx.db.get(id);
+ *     if (!entry) throw new Error("Entry not found");
+ *
+ *     // Check authorization before proceeding
+ *     const userRole = await getUserRole(ctx.auth.userId);
+ *     await requirePermission({
+ *       userId: ctx.auth.userId,
+ *       role: userRole,
+ *       resource: 'contentEntries',
+ *       action: 'update',
+ *       resourceOwnerId: entry.createdBy,
+ *     });
+ *
+ *     // If we get here, the user is authorized
+ *     await ctx.db.patch(id, data);
+ *   },
+ * });
+ * ```
+ */
+export function requirePermission(options) {
+    const result = checkPermission(options);
+    if (!result.allowed) {
+        // Type narrowing: result is PermissionDenied when allowed is false
+        const denied = result;
+        throw new UnauthorizedError(generateDenialMessage({
+            code: denied.code,
+            role: options.role,
+            resource: options.resource,
+            action: options.action,
+        }), {
+            code: denied.code,
+            resource: options.resource,
+            action: options.action,
+            role: options.role ?? undefined,
+            userId: options.userId,
+        });
+    }
+    return result;
+}
+/**
+ * Check if a user owns a resource.
+ *
+ * This is a simple helper for ownership checks without full permission validation.
+ * Use this when you've already verified the permission and just need to check
+ * ownership for scope enforcement.
+ *
+ * @param userId - The ID of the user performing the action
+ * @param resourceOwnerId - The ID of the user who created/owns the resource
+ * @returns True if the user owns the resource
+ *
+ * @example
+ * ```typescript
+ * // Check ownership before allowing a delete
+ * if (!isResourceOwner(currentUserId, entry.createdBy)) {
+ *   throw new UnauthorizedError(
+ *     'You can only delete your own content entries',
+ *     { code: 'OWNERSHIP_REQUIRED', resource: 'contentEntries', action: 'delete' }
+ *   );
+ * }
+ * ```
+ */
+export function isResourceOwner(userId, resourceOwnerId) {
+    // Both must be defined and equal for ownership to be verified
+    if (userId === undefined || resourceOwnerId === undefined) {
+        return false;
+    }
+    return userId === resourceOwnerId;
+}
+/**
+ * Require that a user owns a resource.
+ *
+ * Throws an UnauthorizedError if the user doesn't own the resource.
+ * Use this when you need to enforce "own" scope on a resource.
+ *
+ * @param userId - The ID of the user performing the action
+ * @param resourceOwnerId - The ID of the user who created/owns the resource
+ * @param options - Additional context for the error message
+ * @throws UnauthorizedError if the user doesn't own the resource
+ *
+ * @example
+ * ```typescript
+ * // Require ownership before allowing update
+ * requireResourceOwnership(currentUserId, entry.createdBy, {
+ *   resource: 'contentEntries',
+ *   action: 'update',
+ *   role: userRole,
+ * });
+ * ```
+ */
+export function requireResourceOwnership(userId, resourceOwnerId, options) {
+    if (!isResourceOwner(userId, resourceOwnerId)) {
+        throw new UnauthorizedError(generateDenialMessage({
+            code: "OWNERSHIP_REQUIRED",
+            role: options.role ?? null,
+            resource: options.resource,
+            action: options.action,
+        }), {
+            code: "OWNERSHIP_REQUIRED",
+            resource: options.resource,
+            action: options.action,
+            role: options.role,
+            userId: userId,
+            requiredScope: "own",
+        });
+    }
+}
+/**
+ * Create an authorization context for a user.
+ *
+ * This is a convenience function for building the context object used by
+ * authorization functions. It validates that the user has a role assigned.
+ *
+ * @param userId - The user's ID
+ * @param role - The user's role (from getUserRole hook)
+ * @param customRoles - Optional custom role definitions
+ * @returns Authorization context for permission checks
+ * @throws UnauthorizedError if the user has no role assigned
+ *
+ * @example
+ * ```typescript
+ * // At the start of a mutation handler:
+ * const userRole = await getUserRole({ userId });
+ * const authCtx = createAuthContext(userId, userRole);
+ *
+ * // Later, check permissions with the context:
+ * requirePermission({
+ *   ...authCtx,
+ *   resource: 'contentEntries',
+ *   action: 'create',
+ * });
+ * ```
+ */
+export function createAuthContext(userId, role, customRoles) {
+    if (role === null) {
+        throw new UnauthorizedError("No CMS role assigned. Contact an administrator to get access.", {
+            code: "NO_ROLE",
+            userId,
+        });
+    }
+    const roleDefinition = getRole(role, customRoles);
+    if (!roleDefinition) {
+        throw new UnauthorizedError(`Unknown role "${role}". Contact an administrator to fix your role assignment.`, {
+            code: "UNKNOWN_ROLE",
+            role,
+            userId,
+        });
+    }
+    return {
+        userId,
+        role,
+        customRoles,
+    };
+}
+/**
+ * Check if a user can perform an action using an authorization context.
+ *
+ * This is a convenience wrapper around checkPermission that uses a pre-built
+ * authorization context.
+ *
+ * @param authCtx - The authorization context
+ * @param resource - The resource type being accessed
+ * @param action - The action being performed
+ * @param resourceOwnerId - Optional owner ID for ownership validation
+ * @returns Permission check result
+ */
+export function canPerform(authCtx, resource, action, resourceOwnerId) {
+    return checkPermission({
+        userId: authCtx.userId,
+        role: authCtx.role,
+        resource,
+        action,
+        resourceOwnerId,
+        customRoles: authCtx.customRoles,
+    });
+}
+/**
+ * Require that a user can perform an action using an authorization context.
+ *
+ * This is a convenience wrapper around requirePermission that uses a pre-built
+ * authorization context.
+ *
+ * @param authCtx - The authorization context
+ * @param resource - The resource type being accessed
+ * @param action - The action being performed
+ * @param resourceOwnerId - Optional owner ID for ownership validation
+ * @returns The granted permission details
+ * @throws UnauthorizedError if permission is denied
+ */
+export function mustPerform(authCtx, resource, action, resourceOwnerId) {
+    return requirePermission({
+        userId: authCtx.userId,
+        role: authCtx.role,
+        resource,
+        action,
+        resourceOwnerId,
+        customRoles: authCtx.customRoles,
+    });
+}
+//# sourceMappingURL=authorization.js.map

package/dist/component/authorization.js.map

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

package/dist/component/authorizationHooks.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Authorization Hooks Execution Module
+ *
+ * This module provides the infrastructure for executing authorization hooks
+ * that enable custom permission logic beyond the built-in RBAC system.
+ *
+ * Authorization hooks allow parent applications to:
+ * - Implement custom authorization logic (team-based, subscription-based, etc.)
+ * - Add additional restrictions beyond RBAC
+ * - Override RBAC decisions in special cases
+ * - Log and audit authorization decisions
+ *
+ * Hook execution order:
+ * 1. beforeRbac hook (can reject early or skip RBAC)
+ * 2. Built-in RBAC permission check (if not skipped)
+ * 3. afterRbac hook (additional restrictions)
+ * 4. Operation-specific hook (fine-grained control)
+ * 5. onDeny hook (if denied, can override)
+ *
+ * @example
+ * ```typescript
+ * import { executeAuthorizationHooks } from './authorizationHooks';
+ *
+ * // In a mutation handler
+ * const authResult = await executeAuthorizationHooks({
+ *   hooks: config.authorizationHooks,
+ *   context: {
+ *     operation: 'contentEntries.create',
+ *     userId: args.createdBy,
+ *     role: userRole,
+ *     contentTypeId: args.contentTypeId,
+ *     operationData: args,
+ *   },
+ *   rbacCheck: () => checkPermission({ role: userRole, ... }),
+ *   skipRbac: config.skipRbac,
+ * });
+ *
+ * if (!authResult.allowed) {
+ *   throw new UnauthorizedError(authResult.reason ?? 'Access denied', { ... });
+ * }
+ * ```
+ */
+import type { AuthorizationHooks, AuthorizationHookContext, CmsOperation } from "../client/types.js";
+import { type PermissionCheckOptions, type PermissionCheckResult } from "./authorization.js";
+import type { Resource, Action, RoleDefinition } from "./roles.js";
+/**
+ * Options for executing the authorization hook chain.
+ */
+export interface ExecuteAuthorizationOptions {
+    /**
+     * The authorization hooks configuration from ComponentConfig.
+     */
+    hooks?: AuthorizationHooks;
+    /**
+     * The context for this authorization check.
+     */
+    context: AuthorizationHookContext;
+    /**
+     * Options for the built-in RBAC permission check.
+     * If not provided, RBAC is skipped.
+     */
+    rbacOptions?: PermissionCheckOptions;
+    /**
+     * Whether to skip built-in RBAC checks entirely.
+     * From ComponentConfig.skipRbac
+     */
+    skipRbac?: boolean;
+    /**
+     * Custom role definitions to use for RBAC checks.
+     */
+    customRoles?: Record<string, RoleDefinition>;
+}
+/**
+ * Result from executing the authorization hook chain.
+ */
+export interface AuthorizationResult {
+    /**
+     * Whether the operation is allowed.
+     */
+    allowed: boolean;
+    /**
+     * The reason for denial (if denied).
+     */
+    reason?: string;
+    /**
+     * Modified operation data from hooks (if any).
+     */
+    modifiedData?: Record<string, unknown>;
+    /**
+     * Which check denied the operation.
+     */
+    deniedBy?: "beforeRbac" | "rbac" | "authorize" | "afterRbac" | "operationHook";
+    /**
+     * The RBAC check result (if RBAC was run).
+     */
+    rbacResult?: PermissionCheckResult;
+}
+/**
+ * Maps a CMS operation to an RBAC resource and action.
+ */
+export declare function operationToRbac(operation: CmsOperation): {
+    resource: Resource;
+    action: Action;
+} | null;
+/**
+ * Execute the full authorization hook chain for an operation.
+ *
+ * This function orchestrates the execution of all authorization hooks and the
+ * built-in RBAC check in the correct order:
+ *
+ * 1. **beforeRbac hook**: Can reject early or skip RBAC
+ * 2. **Built-in RBAC**: Standard role-based permission check
+ * 3. **authorize hook**: Receives RBAC decision, can override allow/deny
+ * 4. **afterRbac hook**: Additional restrictions after authorize passes
+ * 5. **Operation hook**: Operation-specific restrictions
+ * 6. **onDeny hook**: Can override denials
+ *
+ * @param options - Configuration for the authorization execution
+ * @returns AuthorizationResult indicating if the operation is allowed
+ *
+ * @example
+ * ```typescript
+ * const result = await executeAuthorizationHooks({
+ *   hooks: config.authorizationHooks,
+ *   context: {
+ *     operation: 'contentEntries.publish',
+ *     userId: currentUser,
+ *     role: 'editor',
+ *     resourceId: entryId,
+ *     resourceOwnerId: entry.createdBy,
+ *   },
+ *   rbacOptions: {
+ *     role: 'editor',
+ *     resource: 'contentEntries',
+ *     action: 'publish',
+ *     userId: currentUser,
+ *     resourceOwnerId: entry.createdBy,
+ *   },
+ * });
+ *
+ * if (!result.allowed) {
+ *   throw new Error(result.reason ?? 'Operation not allowed');
+ * }
+ * ```
+ */
+export declare function executeAuthorizationHooks(options: ExecuteAuthorizationOptions): Promise<AuthorizationResult>;
+/**
+ * Create an authorization context for a content entry operation.
+ *
+ * @param operation - The CMS operation being performed
+ * @param userId - The user performing the operation
+ * @param role - The user's CMS role
+ * @param entry - The content entry (if available)
+ * @param contentType - The content type (if available)
+ * @param operationData - Additional operation data (args)
+ * @returns AuthorizationHookContext
+ */
+export declare function createContentEntryAuthContext(operation: CmsOperation, userId: string | undefined, role: string | null | undefined, entry?: {
+    _id: unknown;
+    createdBy?: string;
+    contentTypeId: unknown;
+}, contentType?: {
+    _id: unknown;
+    name: string;
+}, operationData?: Record<string, unknown>): Omit<AuthorizationHookContext, "ctx">;
+/**
+ * Create RBAC options from an authorization context.
+ *
+ * @param context - The authorization context
+ * @returns PermissionCheckOptions for the RBAC check
+ */
+export declare function contextToRbacOptions(context: AuthorizationHookContext): PermissionCheckOptions | null;
+/**
+ * Execute authorization for an operation and throw if denied.
+ *
+ * This is a convenience wrapper that executes hooks and throws
+ * UnauthorizedError if the operation is not allowed.
+ *
+ * @param options - Authorization execution options
+ * @throws UnauthorizedError if the operation is denied
+ * @returns The authorization result (if allowed)
+ */
+export declare function requireAuthorization(options: ExecuteAuthorizationOptions): Promise<AuthorizationResult>;
+//# sourceMappingURL=authorizationHooks.d.ts.map

package/dist/component/authorizationHooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorizationHooks.d.ts","sourceRoot":"","sources":["../../src/component/authorizationHooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,wBAAwB,EAGxB,YAAY,EACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAE3B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAkBnE;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAE3B;;OAEG;IACH,OAAO,EAAE,wBAAwB,CAAC;IAElC;;;OAGG;IACH,WAAW,CAAC,EAAE,sBAAsB,CAAC;IAErC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,EAAE,YAAY,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,eAAe,CAAC;IAE/E;;OAEG;IACH,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,YAAY,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA+BtG;AAkED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,mBAAmB,CAAC,CA2R9B;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,YAAY,EACvB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,KAAK,CAAC,EAAE;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAAE,EACpE,WAAW,CAAC,EAAE;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAC5C,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,IAAI,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAWvC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,wBAAwB,GAChC,sBAAsB,GAAG,IAAI,CAa/B;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,mBAAmB,CAAC,CA2B9B"}