@pawells/nestjs-auth 1.0.0-dev.4c8c698

package/build/admin/services/keycloak-admin.service.js

@@ -0,0 +1,152 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var KeycloakAdminService_1;
+import { Injectable } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { KeycloakClient } from '../client/client.js';
+import { AppLogger, getErrorMessage } from '@pawells/nestjs-shared/common';
+import { KEYCLOAK_ADMIN_CONFIG_TOKEN } from '../keycloak.constants.js';
+import { KEYCLOAK_DEFAULT_SCOPES } from '../permissions/keycloak-admin.permissions.js';
+let KeycloakAdminService = KeycloakAdminService_1 = class KeycloakAdminService {
+    logger;
+    client = null;
+    grantedScopes = new Set(KEYCLOAK_DEFAULT_SCOPES);
+    Module;
+    get Config() {
+        return this.Module.get(KEYCLOAK_ADMIN_CONFIG_TOKEN, { strict: false });
+    }
+    get AppLogger() {
+        return this.Module.get(AppLogger);
+    }
+    constructor(module) {
+        this.Module = module;
+        this.logger = new AppLogger(undefined, KeycloakAdminService_1.name);
+    }
+    async onModuleInit() {
+        if (!this.Config.enabled) {
+            this.logger.info('Keycloak admin client is disabled, skipping initialization');
+            return;
+        }
+        try {
+            this.logger.info('Initializing Keycloak admin client...');
+            // Build and validate permission scopes
+            const scopes = this.Config.permissions ?? [...KEYCLOAK_DEFAULT_SCOPES];
+            this.grantedScopes = new Set(scopes);
+            if (!this.Config.permissions) {
+                this.logger.warn('KeycloakAdminModule: no permissions configured — defaulting to read-only scopes. ' +
+                    'To grant write access, set the permissions array in KeycloakAdminModule.forRoot() config.');
+            }
+            const { type: _type, ...credentialsWithoutType } = this.Config.credentials;
+            this.client = new KeycloakClient({
+                baseUrl: this.Config.baseUrl,
+                realmName: this.Config.realmName,
+                credentials: credentialsWithoutType,
+                timeout: this.Config.timeout,
+                retry: this.Config.retry,
+            }, this.grantedScopes);
+            await this.client.authenticate();
+            this.logger.info('Keycloak admin client initialized successfully');
+        }
+        catch (error) {
+            this.logger.error(`Failed to initialize Keycloak admin client: ${getErrorMessage(error)}`);
+            // Re-throw if Keycloak is enabled, so startup fails loudly instead of silently
+            if (this.Config.enabled) {
+                throw error;
+            }
+        }
+    }
+    getClient() {
+        return this.client;
+    }
+    isEnabled() {
+        return this.Config.enabled;
+    }
+    isAuthenticated() {
+        return this.client?.isAuthenticated() ?? false;
+    }
+    // Proxy methods to client services
+    get users() {
+        if (!this.client)
+            throw new Error('Keycloak client not initialized');
+        return this.client.Users;
+    }
+    get realms() {
+        if (!this.client)
+            throw new Error('Keycloak client not initialized');
+        return this.client.Realms;
+    }
+    get clients() {
+        if (!this.client)
+            throw new Error('Keycloak client not initialized');
+        return this.client.Clients;
+    }
+    get roles() {
+        if (!this.client)
+            throw new Error('Keycloak client not initialized');
+        return this.client.Roles;
+    }
+    get groups() {
+        if (!this.client)
+            throw new Error('Keycloak client not initialized');
+        return this.client.Groups;
+    }
+    get identityProviders() {
+        if (!this.client)
+            throw new Error('Keycloak client not initialized');
+        return this.client.IdentityProviders;
+    }
+    get authentication() {
+        if (!this.client)
+            throw new Error('Keycloak client not initialized');
+        return this.client.Authentication;
+    }
+    /**
+     * Get the federated identity service for managing identity provider links
+     *
+     * Provides methods to list, link, and unlink external identity providers for users.
+     *
+     * @returns FederatedIdentityService instance
+     * @throws {Error} If Keycloak client is not initialized
+     *
+     * @example
+     * ```typescript
+     * const links = await keycloakAdmin.federatedIdentity.list(userId);
+     * ```
+     */
+    get federatedIdentity() {
+        if (!this.client)
+            throw new Error('Keycloak client not initialized');
+        return this.client.FederatedIdentities;
+    }
+    /**
+     * Get the event service for querying realm events
+     *
+     * Provides methods to query administrative and access events for audit logging and monitoring.
+     *
+     * @returns EventService instance
+     * @throws {Error} If Keycloak client is not initialized
+     *
+     * @example
+     * ```typescript
+     * const events = await keycloakAdmin.events.getAdminEvents({ max: 100 });
+     * ```
+     */
+    get events() {
+        if (!this.client)
+            throw new Error('Keycloak client not initialized');
+        return this.client.Events;
+    }
+};
+KeycloakAdminService = KeycloakAdminService_1 = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [ModuleRef])
+], KeycloakAdminService);
+export { KeycloakAdminService };
+//# sourceMappingURL=keycloak-admin.service.js.map

package/build/admin/services/keycloak-admin.service.js.map

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

package/build/decorators/auth-decorators.d.ts

@@ -0,0 +1,217 @@
+import { ContextOptions } from './context-utils.js';
+/**
+ * Authentication Decorators for NestJS
+ *
+ * This module provides base authentication decorators that work across different
+ * NestJS contexts (HTTP, GraphQL, WebSockets). These decorators use standardized
+ * metadata keys and can be extended by context-specific packages.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Metadata key for public access routes/resolvers
+ * Used by guards to determine if authentication is required
+ */
+export declare const IS_PUBLIC_KEY = "isPublic";
+/**
+ * Metadata key for role-based access control
+ * Used by guards to check user permissions
+ */
+export declare const ROLES_KEY = "roles";
+/**
+ * Metadata key for permission-based access control
+ * Used by guards to check user permissions
+ */
+export declare const PERMISSIONS_KEY = "permissions";
+/**
+ * Decorator to mark routes/resolvers as public (no authentication required)
+ *
+ * This decorator sets the IS_PUBLIC_KEY metadata to true, signaling to
+ * authentication guards that the decorated endpoint should be accessible
+ * without authentication.
+ *
+ * @returns Method decorator that marks the endpoint as public
+ *
+ * @example
+ * ```typescript
+ * @Public()
+ * @Get('health')
+ * checkHealth() {
+ *   return { status: 'ok' };
+ * }
+ * ```
+ *
+ * @example GraphQL
+ * ```typescript
+ * @Public()
+ * @Query(() => String)
+ * async getHealth(): Promise<string> {
+ *   return 'OK';
+ * }
+ * ```
+ */
+export declare const Public: () => MethodDecorator;
+/**
+ * Decorator to mark routes/resolvers as requiring authentication
+ *
+ * This decorator sets the IS_PUBLIC_KEY metadata to false, ensuring that
+ * authentication guards will require valid credentials for the decorated endpoint.
+ *
+ * @returns Method decorator that marks the endpoint as requiring authentication
+ *
+ * @example
+ * ```typescript
+ * @Auth()
+ * @Get('profile')
+ * getProfile() {
+ *   // This endpoint requires authentication
+ * }
+ * ```
+ *
+ * @example GraphQL
+ * ```typescript
+ * @Auth()
+ * @Query(() => User)
+ * async getCurrentUser(@CurrentUser() user: User): Promise<User> {
+ *   return user;
+ * }
+ * ```
+ */
+export declare const Auth: () => MethodDecorator;
+/**
+ * Decorator to specify required roles for routes/resolvers
+ *
+ * This decorator sets the ROLES_KEY metadata with an array of required roles.
+ * Role guards will check that the authenticated user has at least one of the
+ * specified roles before allowing access.
+ *
+ * @param roles - Array of role names required for access
+ * @returns Method decorator that specifies role requirements
+ *
+ * @example
+ * ```typescript
+ * @Roles('admin', 'moderator')
+ * @Post('admin-action')
+ * adminAction() {
+ *   // Only users with 'admin' or 'moderator' roles can access
+ * }
+ * ```
+ *
+ * @example GraphQL
+ * ```typescript
+ * @Roles('admin')
+ * @Mutation(() => User)
+ * async updateUser(@Args('input') input: UpdateUserInput): Promise<User> {
+ *   // Only admin users can update other users
+ * }
+ * ```
+ */
+export declare const Roles: (...roles: string[]) => MethodDecorator;
+/**
+ * Decorator to specify required permissions for routes/resolvers
+ *
+ * This decorator sets the PERMISSIONS_KEY metadata with an array of required permissions.
+ * Permission guards check that the authenticated user has at least one of the specified
+ * permissions (OR logic). Uses roles-as-permissions semantics — permission strings are
+ * matched against user role names.
+ *
+ * @param permissions - Array of permission names required for access
+ * @returns Method decorator that specifies permission requirements
+ *
+ * @example
+ * ```typescript
+ * @Permissions('user.create', 'user.update')
+ * @Post('users')
+ * createUser(@Body() data: CreateUserDto) {
+ *   // Only users with 'user.create' OR 'user.update' role can access (roles-as-permissions)
+ * }
+ * ```
+ *
+ * @example GraphQL
+ * ```typescript
+ * @Permissions('user.delete')
+ * @Mutation(() => Boolean)
+ * async deleteUser(@Args('id') id: string): Promise<boolean> {
+ *   // Only users with 'user.delete' role can delete users
+ * }
+ * ```
+ */
+export declare const Permissions: (...permissions: string[]) => MethodDecorator;
+export type { ContextOptions } from './context-utils.js';
+export { detectContextType, extractRequestFromContext, extractUserFromContext, extractAuthTokenFromContext } from './context-utils.js';
+/**
+ * Parameter decorator to extract the current authenticated user
+ *
+ * This decorator injects the authenticated user object from the request context
+ * into method parameters. The user object is typically populated by authentication
+ * guards during the request processing pipeline.
+ *
+ * Supports both HTTP and GraphQL contexts with automatic detection or explicit specification.
+ *
+ * @param property - Optional property path to extract from the user object (e.g., 'id', 'profile.name')
+ * @param options - Context options for controlling extraction behavior
+ * @returns Parameter decorator that injects the current user or user property
+ *
+ * @example HTTP context (auto-detected)
+ * ```typescript
+ * @Get('profile')
+ * getProfile(@CurrentUser() user: User) {
+ *   return user;
+ * }
+ * ```
+ *
+ * @example With property access
+ * ```typescript
+ * @Get('profile')
+ * getProfile(@CurrentUser('id') userId: string) {
+ *   return this.userService.findById(userId);
+ * }
+ * ```
+ *
+ * @example GraphQL context (explicit)
+ * ```typescript
+ * @Query(() => User)
+ * async getCurrentUser(@CurrentUser(undefined, { contextType: 'graphql' }) user: User): Promise<User> {
+ *   return user;
+ * }
+ * ```
+ *
+ * @example Auto-detect context
+ * ```typescript
+ * @UseGuards(AuthGuard)
+ * getData(@CurrentUser() user: User) {
+ *   // Works in both HTTP and GraphQL contexts
+ * }
+ * ```
+ */
+export declare function CurrentUser(property?: string, options?: ContextOptions): ParameterDecorator;
+/**
+ * Parameter decorator to extract the authorization token from request headers
+ *
+ * This decorator injects the raw authorization token from the request headers
+ * into method parameters. Useful for custom token validation or when you need
+ * access to the raw token string.
+ *
+ * Supports both HTTP and GraphQL contexts with automatic detection or explicit specification.
+ *
+ * @param options - Context options for controlling extraction behavior
+ * @returns Parameter decorator that injects the authorization token
+ *
+ * @example HTTP context (auto-detected)
+ * ```typescript
+ * @Get('validate-token')
+ * validateToken(@AuthToken() token: string) {
+ *   return this.authService.validateToken(token);
+ * }
+ * ```
+ *
+ * @example GraphQL context (explicit)
+ * ```typescript
+ * @Query(() => Boolean)
+ * async validateToken(@AuthToken({ contextType: 'graphql' }) token: string): Promise<boolean> {
+ *   return this.authService.validateToken(token);
+ * }
+ * ```
+ */
+export declare function AuthToken(options?: ContextOptions): ParameterDecorator;
+//# sourceMappingURL=auth-decorators.d.ts.map

package/build/decorators/auth-decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-decorators.d.ts","sourceRoot":"","sources":["../../src/decorators/auth-decorators.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAA6B,MAAM,oBAAoB,CAAC;AAE/E;;;;;;;;GAQG;AAEH;;;GAGG;AACH,eAAO,MAAM,aAAa,aAAa,CAAC;AAExC;;;GAGG;AACH,eAAO,MAAM,SAAS,UAAU,CAAC;AAEjC;;;GAGG;AACH,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,MAAM,QAAO,eAGxB,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,IAAI,QAAO,eAGtB,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,KAAK,GAAI,GAAG,OAAO,MAAM,EAAE,KAAG,eAGzC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,aAAa,MAAM,EAAE,KAAG,eAGrD,CAAC;AAGH,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAEvI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,kBAAkB,CAa3F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,kBAAkB,CAkBtE"}

package/build/decorators/auth-decorators.js

@@ -0,0 +1,251 @@
+import { createParamDecorator } from '@nestjs/common';
+import { createConditionalDecorator } from '@pawells/nestjs-shared/common';
+import { ExtractRequestFromContext } from './context-utils.js';
+/**
+ * Authentication Decorators for NestJS
+ *
+ * This module provides base authentication decorators that work across different
+ * NestJS contexts (HTTP, GraphQL, WebSockets). These decorators use standardized
+ * metadata keys and can be extended by context-specific packages.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Metadata key for public access routes/resolvers
+ * Used by guards to determine if authentication is required
+ */
+export const IS_PUBLIC_KEY = 'isPublic';
+/**
+ * Metadata key for role-based access control
+ * Used by guards to check user permissions
+ */
+export const ROLES_KEY = 'roles';
+/**
+ * Metadata key for permission-based access control
+ * Used by guards to check user permissions
+ */
+export const PERMISSIONS_KEY = 'permissions';
+/**
+ * Decorator to mark routes/resolvers as public (no authentication required)
+ *
+ * This decorator sets the IS_PUBLIC_KEY metadata to true, signaling to
+ * authentication guards that the decorated endpoint should be accessible
+ * without authentication.
+ *
+ * @returns Method decorator that marks the endpoint as public
+ *
+ * @example
+ * ```typescript
+ * @Public()
+ * @Get('health')
+ * checkHealth() {
+ *   return { status: 'ok' };
+ * }
+ * ```
+ *
+ * @example GraphQL
+ * ```typescript
+ * @Public()
+ * @Query(() => String)
+ * async getHealth(): Promise<string> {
+ *   return 'OK';
+ * }
+ * ```
+ */
+export const Public = () => createConditionalDecorator({
+    key: IS_PUBLIC_KEY,
+    value: true,
+});
+/**
+ * Decorator to mark routes/resolvers as requiring authentication
+ *
+ * This decorator sets the IS_PUBLIC_KEY metadata to false, ensuring that
+ * authentication guards will require valid credentials for the decorated endpoint.
+ *
+ * @returns Method decorator that marks the endpoint as requiring authentication
+ *
+ * @example
+ * ```typescript
+ * @Auth()
+ * @Get('profile')
+ * getProfile() {
+ *   // This endpoint requires authentication
+ * }
+ * ```
+ *
+ * @example GraphQL
+ * ```typescript
+ * @Auth()
+ * @Query(() => User)
+ * async getCurrentUser(@CurrentUser() user: User): Promise<User> {
+ *   return user;
+ * }
+ * ```
+ */
+export const Auth = () => createConditionalDecorator({
+    key: IS_PUBLIC_KEY,
+    value: false,
+});
+/**
+ * Decorator to specify required roles for routes/resolvers
+ *
+ * This decorator sets the ROLES_KEY metadata with an array of required roles.
+ * Role guards will check that the authenticated user has at least one of the
+ * specified roles before allowing access.
+ *
+ * @param roles - Array of role names required for access
+ * @returns Method decorator that specifies role requirements
+ *
+ * @example
+ * ```typescript
+ * @Roles('admin', 'moderator')
+ * @Post('admin-action')
+ * adminAction() {
+ *   // Only users with 'admin' or 'moderator' roles can access
+ * }
+ * ```
+ *
+ * @example GraphQL
+ * ```typescript
+ * @Roles('admin')
+ * @Mutation(() => User)
+ * async updateUser(@Args('input') input: UpdateUserInput): Promise<User> {
+ *   // Only admin users can update other users
+ * }
+ * ```
+ */
+export const Roles = (...roles) => createConditionalDecorator({
+    key: ROLES_KEY,
+    value: roles,
+});
+/**
+ * Decorator to specify required permissions for routes/resolvers
+ *
+ * This decorator sets the PERMISSIONS_KEY metadata with an array of required permissions.
+ * Permission guards check that the authenticated user has at least one of the specified
+ * permissions (OR logic). Uses roles-as-permissions semantics — permission strings are
+ * matched against user role names.
+ *
+ * @param permissions - Array of permission names required for access
+ * @returns Method decorator that specifies permission requirements
+ *
+ * @example
+ * ```typescript
+ * @Permissions('user.create', 'user.update')
+ * @Post('users')
+ * createUser(@Body() data: CreateUserDto) {
+ *   // Only users with 'user.create' OR 'user.update' role can access (roles-as-permissions)
+ * }
+ * ```
+ *
+ * @example GraphQL
+ * ```typescript
+ * @Permissions('user.delete')
+ * @Mutation(() => Boolean)
+ * async deleteUser(@Args('id') id: string): Promise<boolean> {
+ *   // Only users with 'user.delete' role can delete users
+ * }
+ * ```
+ */
+export const Permissions = (...permissions) => createConditionalDecorator({
+    key: PERMISSIONS_KEY,
+    value: permissions,
+});
+export { detectContextType, extractRequestFromContext, extractUserFromContext, extractAuthTokenFromContext } from './context-utils.js';
+/**
+ * Parameter decorator to extract the current authenticated user
+ *
+ * This decorator injects the authenticated user object from the request context
+ * into method parameters. The user object is typically populated by authentication
+ * guards during the request processing pipeline.
+ *
+ * Supports both HTTP and GraphQL contexts with automatic detection or explicit specification.
+ *
+ * @param property - Optional property path to extract from the user object (e.g., 'id', 'profile.name')
+ * @param options - Context options for controlling extraction behavior
+ * @returns Parameter decorator that injects the current user or user property
+ *
+ * @example HTTP context (auto-detected)
+ * ```typescript
+ * @Get('profile')
+ * getProfile(@CurrentUser() user: User) {
+ *   return user;
+ * }
+ * ```
+ *
+ * @example With property access
+ * ```typescript
+ * @Get('profile')
+ * getProfile(@CurrentUser('id') userId: string) {
+ *   return this.userService.findById(userId);
+ * }
+ * ```
+ *
+ * @example GraphQL context (explicit)
+ * ```typescript
+ * @Query(() => User)
+ * async getCurrentUser(@CurrentUser(undefined, { contextType: 'graphql' }) user: User): Promise<User> {
+ *   return user;
+ * }
+ * ```
+ *
+ * @example Auto-detect context
+ * ```typescript
+ * @UseGuards(AuthGuard)
+ * getData(@CurrentUser() user: User) {
+ *   // Works in both HTTP and GraphQL contexts
+ * }
+ * ```
+ */
+export function CurrentUser(property, options) {
+    return createParamDecorator((_data, ctx) => {
+        const request = ExtractRequestFromContext(ctx, options);
+        const user = request?.user;
+        if (property !== undefined && user) {
+            return user[property];
+        }
+        return user;
+    })();
+}
+/**
+ * Parameter decorator to extract the authorization token from request headers
+ *
+ * This decorator injects the raw authorization token from the request headers
+ * into method parameters. Useful for custom token validation or when you need
+ * access to the raw token string.
+ *
+ * Supports both HTTP and GraphQL contexts with automatic detection or explicit specification.
+ *
+ * @param options - Context options for controlling extraction behavior
+ * @returns Parameter decorator that injects the authorization token
+ *
+ * @example HTTP context (auto-detected)
+ * ```typescript
+ * @Get('validate-token')
+ * validateToken(@AuthToken() token: string) {
+ *   return this.authService.validateToken(token);
+ * }
+ * ```
+ *
+ * @example GraphQL context (explicit)
+ * ```typescript
+ * @Query(() => Boolean)
+ * async validateToken(@AuthToken({ contextType: 'graphql' }) token: string): Promise<boolean> {
+ *   return this.authService.validateToken(token);
+ * }
+ * ```
+ */
+export function AuthToken(options) {
+    return createParamDecorator((_data, ctx) => {
+        const request = ExtractRequestFromContext(ctx, options);
+        if (!request?.headers) {
+            return undefined;
+        }
+        const authHeader = request.headers.authorization ?? request.headers.Authorization;
+        if (typeof authHeader === 'string') {
+            return authHeader.replace(/^Bearer\s+/i, '');
+        }
+        return undefined;
+    })();
+}
+//# sourceMappingURL=auth-decorators.js.map

package/build/decorators/auth-decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-decorators.js","sourceRoot":"","sources":["../../src/decorators/auth-decorators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAoB,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAkB,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAE/E;;;;;;;;GAQG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;AAExC;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,OAAO,CAAC;AAEjC;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,GAAoB,EAAE,CAAC,0BAA0B,CAAC;IACvE,GAAG,EAAE,aAAa;IAClB,KAAK,EAAE,IAAI;CACX,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,GAAoB,EAAE,CAAC,0BAA0B,CAAC;IACrE,GAAG,EAAE,aAAa;IAClB,KAAK,EAAE,KAAK;CACZ,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,GAAG,KAAe,EAAmB,EAAE,CAAC,0BAA0B,CAAC;IACxF,GAAG,EAAE,SAAS;IACd,KAAK,EAAE,KAAK;CACZ,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAG,WAAqB,EAAmB,EAAE,CAAC,0BAA0B,CAAC;IACpG,GAAG,EAAE,eAAe;IACpB,KAAK,EAAE,WAAW;CAClB,CAAC,CAAC;AAIH,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAEvI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,UAAU,WAAW,CAAC,QAAiB,EAAE,OAAwB;IACtE,OAAO,oBAAoB,CAC1B,CAAC,KAAc,EAAE,GAAqB,EAAE,EAAE;QACzC,MAAM,OAAO,GAAG,yBAAyB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,CAAC;QAE3B,IAAI,QAAQ,KAAK,SAAS,IAAI,IAAI,EAAE,CAAC;YACpC,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC;QAED,OAAO,IAAI,CAAC;IACb,CAAC,CACD,EAAE,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,SAAS,CAAC,OAAwB;IACjD,OAAO,oBAAoB,CAC1B,CAAC,KAAc,EAAE,GAAqB,EAAE,EAAE;QACzC,MAAM,OAAO,GAAG,yBAAyB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAExD,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC;YACvB,OAAO,SAAS,CAAC;QAClB,CAAC;QAED,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC;QAElF,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;YACpC,OAAO,UAAU,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;QAC9C,CAAC;QAED,OAAO,SAAS,CAAC;IAClB,CAAC,CACD,EAAE,CAAC;AACL,CAAC"}