@dotdo/postgres 0.1.0

package/dist/worker/auth-rate-limiter.js

@@ -0,0 +1,332 @@
+/**
+ * Authentication Rate Limiter Module
+ *
+ * Provides rate limiting specifically for authentication failures to prevent
+ * brute force and credential stuffing attacks.
+ *
+ * Features:
+ * - Sliding window rate limiting per token prefix
+ * - Exponential backoff for repeated failures
+ * - Memory-bounded storage with LRU-style eviction
+ * - Lazy cleanup to work well with Cloudflare Workers
+ *
+ * @module @dotdo/postgres/worker/auth-rate-limiter
+ *
+ * @example
+ * ```typescript
+ * import { AuthRateLimiter } from './auth-rate-limiter'
+ *
+ * const rateLimiter = new AuthRateLimiter()
+ *
+ * // Check if request should be rate limited
+ * if (rateLimiter.isRateLimited(tokenPrefix)) {
+ *   return new Response('Too many attempts', { status: 429 })
+ * }
+ *
+ * // Record a failure after failed authentication
+ * rateLimiter.recordFailure(tokenPrefix)
+ * ```
+ */
+/**
+ * Default rate limiter configuration.
+ */
+export const DEFAULT_AUTH_RATE_LIMITER_CONFIG = {
+    windowMs: 60000,
+    maxFailures: 10,
+    maxEntries: 10000,
+    cleanupIntervalMs: 300000,
+    keyLength: 20,
+    keyPrefix: 'token:',
+    maxBackoffPower: 10,
+};
+// ============================================================================
+// AuthRateLimiter Class
+// ============================================================================
+/**
+ * Rate limiter for authentication failures.
+ *
+ * Implements a sliding window algorithm with exponential backoff to prevent
+ * brute force and credential stuffing attacks.
+ *
+ * @security This is a simple in-memory rate limiter. In production with
+ *           multiple Workers, consider using Durable Objects or external
+ *           storage for distributed rate limiting.
+ *
+ * Memory bounds:
+ * - Max entries: configurable (default 10,000)
+ * - Periodic cleanup: configurable (default every 5 minutes)
+ * - LRU-style eviction when at capacity
+ *
+ * @example
+ * ```typescript
+ * const rateLimiter = new AuthRateLimiter({
+ *   windowMs: 60000,     // 1 minute window
+ *   maxFailures: 5,      // 5 failures per window
+ *   maxEntries: 5000,    // Max 5000 tracked keys
+ * })
+ *
+ * // Generate key from token
+ * const key = rateLimiter.generateKey(token)
+ *
+ * // Check before processing authentication
+ * if (rateLimiter.isRateLimited(key)) {
+ *   return { error: 'RATE_LIMITED' }
+ * }
+ *
+ * // After failed authentication
+ * const isValid = await validateCredentials(...)
+ * if (!isValid) {
+ *   rateLimiter.recordFailure(key)
+ * }
+ * ```
+ */
+export class AuthRateLimiter {
+    config;
+    entries;
+    lastCleanupTime;
+    lastCleanupCount;
+    /**
+     * Creates a new AuthRateLimiter instance.
+     *
+     * @param config - Optional configuration overrides
+     */
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_AUTH_RATE_LIMITER_CONFIG, ...config };
+        this.entries = new Map();
+        this.lastCleanupTime = Date.now();
+        this.lastCleanupCount = 0;
+    }
+    /**
+     * Generates a rate limit key from a token.
+     *
+     * Uses the token prefix to identify unique tokens without storing
+     * full tokens in memory for rate limiting.
+     *
+     * @param token - The full authentication token
+     * @returns The rate limit key
+     */
+    generateKey(token) {
+        return this.config.keyPrefix + token.slice(0, this.config.keyLength);
+    }
+    /**
+     * Checks if a request should be rate limited based on prior failures.
+     *
+     * Uses a sliding window algorithm with exponential backoff:
+     * 1. If no entry exists or window expired, allow the request
+     * 2. Check if enough time has passed since the last failure (exponential backoff)
+     * 3. If not enough time has passed, rate limit
+     * 4. Check if failure count exceeds threshold
+     *
+     * NOTE: This method only CHECKS the rate limit state, it does NOT increment
+     * the failure count. Call recordFailure() to record a failure.
+     *
+     * @param key - Rate limit key (from generateKey)
+     * @returns true if the request should be rate limited, false otherwise
+     *
+     * @security Prevents brute force attacks by limiting authentication attempts.
+     *           Attack vector: Attacker tries many passwords/tokens in rapid succession.
+     *           Mitigation: After failures, exponential backoff is applied (2^N seconds).
+     */
+    isRateLimited(key) {
+        const now = Date.now();
+        // Lazy cleanup: run periodically during normal operations
+        // This avoids needing a timer which doesn't work well in Workers
+        if (now - this.lastCleanupTime > this.config.cleanupIntervalMs) {
+            this.cleanup();
+        }
+        const entry = this.entries.get(key);
+        // No prior failures for this key
+        if (!entry) {
+            return false;
+        }
+        // Window expired - reset and allow
+        if (now - entry.windowStart > this.config.windowMs) {
+            this.entries.delete(key);
+            return false;
+        }
+        // SECURITY: Exponential backoff - require increasing delays between attempts
+        const requiredDelay = this.calculateExponentialBackoff(entry.count);
+        if (now - entry.lastAttempt < requiredDelay) {
+            // Not enough time has passed since last attempt - rate limited
+            return true;
+        }
+        // Check if failure count exceeds threshold
+        return entry.count >= this.config.maxFailures;
+    }
+    /**
+     * Records an authentication failure for rate limiting purposes.
+     *
+     * @param key - Rate limit key (from generateKey)
+     *
+     * @security Only call this when authentication actually fails. Do not call
+     *           on successful authentications or when rate limiting has already
+     *           blocked the request.
+     */
+    recordFailure(key) {
+        const now = Date.now();
+        // Check if we need to evict before adding a new entry
+        if (!this.entries.has(key) && this.entries.size >= this.config.maxEntries) {
+            this.evictOldestEntries();
+        }
+        const entry = this.entries.get(key);
+        if (!entry || now - entry.windowStart > this.config.windowMs) {
+            // Start a new window
+            this.entries.set(key, { count: 1, windowStart: now, lastAttempt: now });
+            return;
+        }
+        // Increment failure count in existing window
+        entry.count++;
+        entry.lastAttempt = now;
+    }
+    /**
+     * Returns current rate limiter statistics for monitoring.
+     *
+     * @returns Statistics about the current rate limiter state
+     */
+    getStats() {
+        return {
+            size: this.entries.size,
+            maxSize: this.config.maxEntries,
+            lastCleanupTime: this.lastCleanupTime,
+            lastCleanupCount: this.lastCleanupCount,
+        };
+    }
+    /**
+     * Clears all rate limit state.
+     *
+     * @security In production, this should never be exposed to external callers.
+     *           Only intended for testing or administrative use.
+     */
+    clear() {
+        this.entries.clear();
+        this.lastCleanupTime = Date.now();
+        this.lastCleanupCount = 0;
+    }
+    /**
+     * Gets the entry for a specific key (for testing/debugging).
+     *
+     * @param key - Rate limit key
+     * @returns The entry if it exists, undefined otherwise
+     */
+    getEntry(key) {
+        return this.entries.get(key);
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    /**
+     * Calculates exponential backoff delay based on failure count.
+     *
+     * @security Exponential backoff makes brute force attacks increasingly expensive.
+     *           After N failures, attacker must wait 2^N seconds before the next attempt.
+     *
+     * @param failureCount - Number of consecutive failures
+     * @returns Required delay in milliseconds before next attempt is allowed
+     */
+    calculateExponentialBackoff(failureCount) {
+        // Cap at configured power to prevent integer overflow
+        const cappedCount = Math.min(failureCount, this.config.maxBackoffPower);
+        return Math.pow(2, cappedCount) * 1000;
+    }
+    /**
+     * Performs cleanup of expired rate limit entries.
+     *
+     * @security This prevents memory leaks from accumulated expired entries.
+     *           Uses lazy cleanup during normal operations instead of a timer
+     *           to work better with Cloudflare Workers' event-driven model.
+     *
+     * @returns Number of entries removed
+     */
+    cleanup() {
+        const now = Date.now();
+        let removed = 0;
+        // Remove entries older than the rate limit window
+        for (const [key, entry] of this.entries) {
+            if (now - entry.windowStart > this.config.windowMs) {
+                this.entries.delete(key);
+                removed++;
+            }
+        }
+        this.lastCleanupTime = now;
+        this.lastCleanupCount = removed;
+        return removed;
+    }
+    /**
+     * Evicts oldest entries when rate limiter is at capacity.
+     * Uses Map iteration order (insertion order) for LRU-like eviction.
+     *
+     * @security Prevents memory exhaustion from attackers creating many unique
+     *           rate limit keys. Evicts 10% of entries to amortize eviction cost.
+     */
+    evictOldestEntries() {
+        // Evict 10% of max entries to amortize eviction overhead
+        const evictCount = Math.ceil(this.config.maxEntries / 10);
+        let evicted = 0;
+        for (const key of this.entries.keys()) {
+            if (evicted >= evictCount)
+                break;
+            this.entries.delete(key);
+            evicted++;
+        }
+    }
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Creates a new AuthRateLimiter instance with the given configuration.
+ *
+ * @param config - Optional configuration overrides
+ * @returns A new AuthRateLimiter instance
+ *
+ * @example
+ * ```typescript
+ * import { createAuthRateLimiter } from './auth-rate-limiter'
+ *
+ * const rateLimiter = createAuthRateLimiter({
+ *   windowMs: 30000,   // 30 second window
+ *   maxFailures: 5,    // 5 failures per window
+ * })
+ * ```
+ */
+export function createAuthRateLimiter(config = {}) {
+    return new AuthRateLimiter(config);
+}
+// ============================================================================
+// Default Instance (for backwards compatibility)
+// ============================================================================
+/**
+ * Default rate limiter instance for module-level use.
+ *
+ * @deprecated Prefer creating instances with createAuthRateLimiter() for better
+ *             testability and isolation. This is provided for backwards compatibility.
+ *
+ * @internal
+ */
+let defaultRateLimiter = null;
+/**
+ * Gets or creates the default rate limiter instance.
+ *
+ * @returns The default AuthRateLimiter instance
+ *
+ * @internal
+ */
+export function getDefaultRateLimiter() {
+    if (!defaultRateLimiter) {
+        defaultRateLimiter = new AuthRateLimiter();
+    }
+    return defaultRateLimiter;
+}
+/**
+ * Resets the default rate limiter instance.
+ * Primarily for testing purposes.
+ *
+ * @internal
+ */
+export function resetDefaultRateLimiter() {
+    if (defaultRateLimiter) {
+        defaultRateLimiter.clear();
+    }
+    defaultRateLimiter = null;
+}
+//# sourceMappingURL=auth-rate-limiter.js.map

package/dist/worker/auth-rate-limiter.js.map

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

package/dist/worker/auth.d.ts

@@ -0,0 +1,345 @@
+/**
+ * Authentication middleware for PostgresDO Worker routes
+ * Integrates with oauth.do for token validation and user-scoped database access
+ *
+ * Security features:
+ * - JWT structure validation (3 segments)
+ * - Algorithm validation (rejects alg:none)
+ * - Token expiration checking (exp/nbf claims)
+ * - Empty signature rejection
+ * - Rate limiting for auth failures
+ * - SQL injection prevention in database IDs
+ * - Token length limits (DoS prevention)
+ */
+import type { Context, MiddlewareHandler } from 'hono';
+export type { Env } from './types';
+import { type TokenCacheConfig, type CacheStats, type AuthenticatedUser, type AuthTokenValidationResult as TokenValidationResult, extractBearerToken } from '@dotdo/postgres-shared';
+export type { AuthenticatedUser, TokenValidationResult };
+/**
+ * Standardized error codes for authentication failures.
+ * These codes are exposed in API responses to help clients understand failures.
+ */
+export declare const AUTH_ERROR_CODES: {
+    /** No token provided */
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    /** Token failed validation */
+    readonly INVALID_TOKEN: "INVALID_TOKEN";
+    /** Too many failed attempts */
+    readonly RATE_LIMITED: "RATE_LIMITED";
+};
+export type AuthErrorCode = (typeof AUTH_ERROR_CODES)[keyof typeof AUTH_ERROR_CODES];
+/**
+ * Standardized error messages for authentication failures.
+ * Consistent messages improve security by not leaking implementation details.
+ */
+export declare const AUTH_ERROR_MESSAGES: {
+    readonly UNAUTHORIZED: "Missing authentication token";
+    readonly INVALID_TOKEN: "Invalid authentication token";
+    readonly RATE_LIMITED: "Too many authentication failures. Please try again later.";
+};
+/**
+ * Performs a timing-safe comparison of two strings.
+ *
+ * @security This function uses constant-time comparison to prevent timing attacks.
+ *           Timing attacks can leak information about the secret by measuring
+ *           how long the comparison takes.
+ *
+ * @param a - First string to compare
+ * @param b - Second string to compare
+ * @returns true if strings are equal, false otherwise
+ */
+export declare function timingSafeEqual(a: string, b: string): boolean;
+/**
+ * Clears all rate limit state. Intended for testing only.
+ *
+ * @security In production, this should never be exposed to external callers.
+ *           Only exported for use in test cleanup between test cases.
+ */
+export declare function clearRateLimitState(): void;
+/**
+ * Get rate limiter statistics for monitoring.
+ *
+ * @returns Current rate limiter stats including size and last cleanup time
+ */
+export declare function getRateLimiterStats(): {
+    size: number;
+    maxSize: number;
+    lastCleanupTime: number;
+};
+/**
+ * Generates a safe, deterministic database identifier from a user ID.
+ *
+ * @security This function provides defense-in-depth sanitization before
+ *           generating the database ID. Even though validateJWTSecurity
+ *           already checks for SQL injection, this ensures any user ID
+ *           that reaches the database layer is safe.
+ *
+ * Sanitization rules:
+ * - `--` -> `_` : Prevents SQL comment injection
+ * - `/*` -> `_` : Prevents block comment start
+ * - `* /`-> `_` : Prevents block comment end
+ * - `;`  -> `_` : Prevents statement chaining
+ * - `'`  -> `_` : Prevents string delimiter attacks
+ * - `"`  -> `_` : Prevents identifier injection
+ *
+ * @param userId - User identifier from JWT sub claim
+ * @returns Safe database identifier in format "user_{sanitized_id}"
+ *
+ * @example
+ * ```typescript
+ * generateDatabaseId("user123")           // "user_user123"
+ * generateDatabaseId("admin'--")          // "user_admin___"
+ * generateDatabaseId("test@example.com")  // "user_test_example_com"
+ * ```
+ */
+export declare function generateDatabaseId(userId: string): string;
+/**
+ * Configuration for the token validation cache.
+ *
+ * @security Caching reduces load on the OAuth provider but introduces a
+ *           window where revoked tokens may still be accepted. Balance
+ *           TTL based on your security requirements.
+ */
+export interface AuthTokenCacheConfig {
+    /** Maximum number of tokens to cache (default: 1000) */
+    maxSize?: number;
+    /** Cache TTL in milliseconds (default: 60000 = 1 minute) */
+    ttl?: number;
+    /** Interval for cleanup of expired entries in ms (default: 60000) */
+    cleanupInterval?: number;
+}
+/**
+ * Configuration options for the authentication middleware.
+ *
+ * @security Review all options carefully - incorrect configuration can
+ *           create security vulnerabilities.
+ */
+export interface AuthConfig {
+    /**
+     * OAuth provider URL for token validation.
+     * @default 'https://oauth.do'
+     */
+    oauthUrl?: string;
+    /**
+     * How long to cache valid tokens in milliseconds.
+     * @default 60000 (1 minute)
+     * @security Lower values improve security (faster revocation) at cost of
+     *           more OAuth provider requests. Higher values improve performance
+     *           but delay token revocation.
+     */
+    tokenCacheTTL?: number;
+    /**
+     * Advanced cache configuration options.
+     * Overrides tokenCacheTTL if ttl is specified.
+     */
+    cacheConfig?: AuthTokenCacheConfig;
+    /**
+     * Custom token validation function.
+     * Use this to integrate with custom OAuth providers or add additional validation.
+     *
+     * @security Your validator MUST verify the cryptographic signature.
+     *           Returning valid:true without signature verification is a
+     *           critical vulnerability.
+     */
+    validateToken?: (token: string) => Promise<TokenValidationResult>;
+    /**
+     * Allow requests without authentication tokens.
+     * @default false
+     * @security Only enable if your application explicitly handles anonymous users.
+     *           Anonymous users should have minimal permissions.
+     */
+    allowAnonymous?: boolean;
+    /**
+     * Paths that bypass authentication entirely.
+     * @default ['/ping', '/health']
+     * @security Keep this list minimal. Only include endpoints that expose
+     *           no sensitive data and are needed for infrastructure (health checks).
+     */
+    publicPaths?: string[];
+    /**
+     * Custom handler for unauthorized requests.
+     * Use to customize error responses or redirect to login pages.
+     */
+    onUnauthorized?: (c: Context) => Response;
+}
+/**
+ * Authentication context available in request handlers.
+ *
+ * Access via `getAuth(c)` or `c.get('auth')`.
+ */
+export interface AuthContext {
+    /** Authenticated user info, null if not authenticated */
+    user: AuthenticatedUser | null;
+    /** Raw JWT token, null if not provided */
+    token: string | null;
+    /** True if user is authenticated */
+    isAuthenticated: boolean;
+    /** Database ID for this user's isolated database, null if not authenticated */
+    databaseId: string | null;
+}
+/**
+ * Reconfigures the global token cache with new settings.
+ * Disposes the existing cache and creates a new one.
+ *
+ * @param config - New cache configuration
+ *
+ * @example
+ * ```typescript
+ * configureTokenCache({
+ *   maxSize: 5000,      // More entries for high-traffic apps
+ *   defaultTTL: 30000,  // 30 second TTL for faster revocation
+ * })
+ * ```
+ */
+export declare function configureTokenCache(config: TokenCacheConfig): void;
+/**
+ * Returns current token cache statistics for monitoring.
+ *
+ * @returns Cache stats including hits, misses, and size
+ */
+export declare function getTokenCacheStats(): CacheStats;
+/**
+ * Clears all cached tokens. Intended for testing only.
+ *
+ * @security In production, avoid clearing the cache as it will cause
+ *           a thundering herd to the OAuth provider.
+ */
+export declare function clearTokenCache(): void;
+export { extractBearerToken };
+/**
+ * Creates a Hono middleware handler that validates JWT tokens.
+ *
+ * This middleware:
+ * 1. Skips authentication for public paths
+ * 2. Extracts Bearer token from Authorization header
+ * 3. Applies rate limiting for failed attempts
+ * 4. Validates JWT structure and security claims
+ * 5. Validates token with OAuth provider (with caching)
+ * 6. Sets authenticated user context
+ *
+ * @security The middleware applies multiple layers of validation in order
+ *           of computational cost - cheap checks first (structure, rate limit)
+ *           before expensive checks (OAuth provider validation).
+ *
+ * @param config - Authentication configuration options
+ * @returns Hono middleware handler
+ *
+ * @example
+ * ```typescript
+ * const app = new Hono()
+ * app.use('*', createAuthMiddleware({
+ *   publicPaths: ['/ping', '/health', '/docs'],
+ *   tokenCacheTTL: 30000, // 30 second cache
+ * }))
+ * ```
+ */
+export declare function createAuthMiddleware(config?: AuthConfig): MiddlewareHandler;
+/**
+ * Creates a middleware that enforces authentication.
+ *
+ * Use this on routes that MUST have an authenticated user.
+ * For routes that work with optional authentication, use
+ * createAuthMiddleware with allowAnonymous:true instead.
+ *
+ * @returns Hono middleware handler
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/private', requireAuth(), (c) => {
+ *   const user = requireUser(c)
+ *   return c.json({ userId: user.id })
+ * })
+ * ```
+ */
+export declare function requireAuth(): MiddlewareHandler;
+/**
+ * Retrieves the authentication context from a request.
+ *
+ * Returns a default unauthenticated context if none is set.
+ * This is safe to call on any route, even those without auth middleware.
+ *
+ * @param c - Hono context
+ * @returns Authentication context
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/data', (c) => {
+ *   const auth = getAuth(c)
+ *   if (auth.isAuthenticated) {
+ *     return c.json({ user: auth.user })
+ *   }
+ *   return c.json({ guest: true })
+ * })
+ * ```
+ */
+export declare function getAuth(c: Context): AuthContext;
+/**
+ * Retrieves the authenticated user or throws an error.
+ *
+ * Use this in routes protected by requireAuth() where you need
+ * the user object and want TypeScript to know it's non-null.
+ *
+ * @param c - Hono context
+ * @returns Authenticated user
+ * @throws Error if user is not authenticated
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/profile', requireAuth(), (c) => {
+ *   const user = requireUser(c) // Type: AuthenticatedUser (not null)
+ *   return c.json({ email: user.email })
+ * })
+ * ```
+ */
+export declare function requireUser(c: Context): AuthenticatedUser;
+/**
+ * Retrieves the database ID for the authenticated user or throws an error.
+ *
+ * The database ID is a sanitized, deterministic identifier derived from
+ * the user ID. Use this to access the user's isolated database.
+ *
+ * @param c - Hono context
+ * @returns Database ID string (e.g., "user_abc123")
+ * @throws Error if user is not authenticated
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/data', requireAuth(), (c) => {
+ *   const dbId = getDatabaseId(c)
+ *   const db = await getDatabase(dbId)
+ *   // ...
+ * })
+ * ```
+ */
+export declare function getDatabaseId(c: Context): string;
+/**
+ * Gets the Durable Object ID for a user's database.
+ *
+ * @param namespace - Durable Object namespace binding
+ * @param userId - User identifier from JWT
+ * @returns Durable Object ID for the user's database
+ *
+ * @example
+ * ```typescript
+ * const doId = getUserDOId(env.POSTGRES_DO, user.id)
+ * const stub = env.POSTGRES_DO.get(doId)
+ * ```
+ */
+export declare function getUserDOId(namespace: DurableObjectNamespace, userId: string): DurableObjectId;
+/**
+ * Gets a Durable Object stub for a user's database.
+ *
+ * Convenience function that combines getUserDOId and namespace.get().
+ *
+ * @param namespace - Durable Object namespace binding
+ * @param userId - User identifier from JWT
+ * @returns Durable Object stub for the user's database
+ *
+ * @example
+ * ```typescript
+ * const stub = getUserDOStub(env.POSTGRES_DO, user.id)
+ * const response = await stub.fetch(request)
+ * ```
+ */
+export declare function getUserDOStub(namespace: DurableObjectNamespace, userId: string): DurableObjectStub;
+//# sourceMappingURL=auth.d.ts.map

package/dist/worker/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/worker/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,OAAO,EAAQ,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAG5D,YAAY,EAAE,GAAG,EAAE,MAAM,SAAS,CAAA;AAClC,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAEf,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,IAAI,qBAAqB,EACvD,kBAAkB,EAKnB,MAAM,wBAAwB,CAAA;AAG/B,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,CAAA;AAmFxD;;;GAGG;AACH,eAAO,MAAM,gBAAgB;IAC3B,wBAAwB;;IAExB,8BAA8B;;IAE9B,+BAA+B;;CAEvB,CAAA;AAEV,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAA;AAEpF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;CAItB,CAAA;AAEV;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAe7D;AA8ID;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAMhG;AA+OD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAiCzD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;;OAGG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAA;IAElC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;IAEjE;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IAExB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IAEtB;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,QAAQ,CAAA;CAC1C;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAC9B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,oCAAoC;IACpC,eAAe,EAAE,OAAO,CAAA;IACxB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAsBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAMlE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,UAAU,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED,OAAO,EAAE,kBAAkB,EAAE,CAAA;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,GAAE,UAAe,GAAG,iBAAiB,CAgI/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,CAiB/C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,GAAG,WAAW,CAU/C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,iBAAiB,CAMzD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAMhD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,CAG9F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,sBAAsB,EACjC,MAAM,EAAE,MAAM,GACb,iBAAiB,CAGnB"}