@rudderjs/auth 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleiman Shahbari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# @rudderjs/auth
+
+Native authentication for RudderJS. Laravel-style guards, user providers, and Auth facade.
+
+## Installation
+
+```bash
+pnpm add @rudderjs/auth @rudderjs/hash @rudderjs/session
+```
+
+## Setup
+
+```ts
+// config/auth.ts
+import { User } from '../app/Models/User.js'
+
+export default {
+  defaults: {
+    guard: 'web',
+  },
+  guards: {
+    web: { driver: 'session', provider: 'users' },
+  },
+  providers: {
+    users: { driver: 'eloquent', model: User },
+  },
+}
+
+// bootstrap/providers.ts
+import { session } from '@rudderjs/session'
+import { hash } from '@rudderjs/hash'
+import { auth } from '@rudderjs/auth'
+
+export default [
+  session(configs.session),
+  hash(configs.hash),
+  auth(configs.auth),
+]
+```
+
+## Usage
+
+### Auth Facade
+
+```ts
+import { Auth } from '@rudderjs/auth'
+
+// Attempt login
+const success = await Auth.attempt({ email, password })
+
+// Manual login/logout
+Auth.login(user)
+Auth.logout()
+
+// Current user
+const user = await Auth.user()    // Authenticatable | null
+const id = await Auth.id()        // string | null
+const ok = await Auth.check()     // boolean
+const no = await Auth.guest()     // boolean
+
+// Switch guard
+Auth.guard('api').user()
+```
+
+### Middleware
+
+```ts
+import { AuthMiddleware, RequireAuth } from '@rudderjs/auth'
+
+// Attach user to request (non-blocking)
+Route.get('/profile', handler, [AuthMiddleware()])
+
+// Require authentication (returns 401 if not logged in)
+Route.post('/posts', handler, [RequireAuth()])
+```
+
+### Authenticatable Contract
+
+Your User model must implement:
+
+```ts
+interface Authenticatable {
+  getAuthIdentifier(): string
+  getAuthPassword(): string
+  getRememberToken(): string | null
+  setRememberToken(token: string): void
+}
+```
+
+The `EloquentUserProvider` auto-wraps ORM model records with these methods (mapping `id`, `password`, `rememberToken` fields).
+
+## Architecture
+
+- **Guards** determine *how* users are authenticated (session cookies, API tokens)
+- **User Providers** determine *where* users are retrieved from (Eloquent model, raw DB)
+- **Auth facade** delegates to the current guard via `AsyncLocalStorage`
+- **AuthManager** creates guards + providers from config, one per request
+
+### Built-in Guards
+
+| Guard | Driver | Description |
+|-------|--------|-------------|
+| Session | `session` | Cookie-based auth via `@rudderjs/session` |
+
+### Built-in Providers
+
+| Provider | Driver | Description |
+|----------|--------|-------------|
+| Eloquent | `eloquent` | Uses `@rudderjs/orm` Model class |

package/boost/guidelines.md

@@ -0,0 +1,137 @@
+# @rudderjs/auth
+
+## Overview
+
+Full-featured authentication and authorization package for RudderJS. Provides session-based guards, an Eloquent user provider, password reset broker, email verification, and a Laravel-style Gate/Policy authorization system. Uses `AsyncLocalStorage` for request-scoped auth context, integrates with `@rudderjs/hash` for password checking and `@rudderjs/session` for cookie-based sessions.
+
+## Key Patterns
+
+### Authentication Guards
+
+Guards implement the `Guard` contract (`user()`, `check()`, `attempt()`, `login()`, `logout()`). The `SessionGuard` is the built-in driver that stores `auth_user_id` in the session.
+
+```ts
+// config/auth.ts
+export default {
+  defaults: { guard: 'web' },
+  guards: {
+    web: { driver: 'session', provider: 'users' },
+  },
+  providers: {
+    users: { driver: 'eloquent', model: User },
+  },
+} satisfies AuthConfig
+```
+
+Use `AuthMiddleware()` to populate `req.user` without blocking, or `RequireAuth()` to return 401 for unauthenticated requests:
+
+```ts
+router.get('/profile', RequireAuth(), async (req, res) => {
+  res.json(req.user) // AuthUser — id, name, email + extra fields
+})
+```
+
+Use the `Auth` facade inside route handlers (request-scoped via AsyncLocalStorage):
+
+```ts
+const success = await Auth.attempt({ email, password })
+await Auth.login(user)
+await Auth.logout()
+const user = await Auth.user()
+```
+
+### Password Hashing
+
+Auth delegates hashing to `@rudderjs/hash`. The hash provider **must** be registered before auth in the provider array:
+
+```ts
+// bootstrap/providers.ts
+export default [hash(configs.hash), auth(configs.auth), ...]
+```
+
+The `EloquentUserProvider` calls `hashCheck(plain, hashed)` internally during `validateCredentials()`.
+
+### Email Verification
+
+Implement `MustVerifyEmail` on your User model:
+
+```ts
+class User extends Model implements Authenticatable, MustVerifyEmail {
+  hasVerifiedEmail() { return this.emailVerifiedAt !== null }
+  markEmailAsVerified() { this.emailVerifiedAt = new Date().toISOString(); return Promise.resolve() }
+  getEmailForVerification() { return this.email }
+}
+```
+
+Use the middleware and helpers:
+
+```ts
+router.get('/dashboard', RequireAuth(), EnsureEmailIsVerified(), handler)
+
+// Generate a signed verification URL (requires @rudderjs/router)
+const url = verificationUrl(user)
+
+// Handle verification in the route
+await handleEmailVerification(req.params.id, req.params.hash, (id) => User.find(id))
+```
+
+### Authorization (Gates/Policies)
+
+Define abilities and policies, then check them anywhere:
+
+```ts
+// In a provider's boot()
+Gate.define('edit-post', (user, post) => user.id === post.authorId)
+Gate.policy(Post, PostPolicy)
+Gate.before((user) => user.isAdmin ? true : undefined)
+
+// In a handler
+await Gate.authorize('edit-post', post) // throws AuthorizationError (403)
+if (await Gate.allows('edit-post', post)) { ... }
+
+// Scoped to a specific user
+await Gate.forUser(user).allows('edit-post', post)
+```
+
+Policies are classes with method names matching ability names:
+
+```ts
+class PostPolicy extends Policy {
+  before(user: Authenticatable) { return user.isAdmin ? true : undefined }
+  update(user: Authenticatable, post: Post) { return user.id === post.authorId }
+  delete(user: Authenticatable, post: Post) { return user.id === post.authorId }
+}
+```
+
+## Common Pitfalls
+
+- **Provider order matters**: `hash()` must come before `auth()` in the providers array, or boot throws.
+- **Missing session**: `@rudderjs/session` is a required peer dep. The session middleware must run before `AuthMiddleware`.
+- **Auth outside middleware context**: `Auth.user()` / `Gate.allows()` only work inside the `AuthMiddleware` scope (AsyncLocalStorage). Outside that scope you get "No auth context" errors.
+- **Password stripped from AuthUser**: The `userToPlain()` helper removes `password` from `req.user` automatically.
+- **Gate.reset()**: Only for testing. Gate state is static/global.
+
+## Key Imports
+
+```ts
+// Provider factory
+import { auth } from '@rudderjs/auth'
+
+// Middleware
+import { AuthMiddleware, RequireAuth, EnsureEmailIsVerified } from '@rudderjs/auth'
+
+// Facades & managers
+import { Auth, Gate, Policy, AuthorizationError } from '@rudderjs/auth'
+
+// Password reset
+import { PasswordBroker, MemoryTokenRepository } from '@rudderjs/auth'
+
+// Email verification
+import { verificationUrl, handleEmailVerification, mustVerifyEmail } from '@rudderjs/auth'
+
+// User provider
+import { EloquentUserProvider, toAuthenticatable } from '@rudderjs/auth'
+
+// Types
+import type { Authenticatable, AuthUser, Guard, UserProvider, AuthConfig, MustVerifyEmail } from '@rudderjs/auth'
+```

package/dist/auth-manager.d.ts

@@ -0,0 +1,40 @@
+import type { Authenticatable, Guard } from './contracts.js';
+import { type SessionStore } from './session-guard.js';
+export interface AuthGuardConfig {
+    driver: 'session';
+    provider: string;
+}
+export interface AuthProviderConfig {
+    driver: 'eloquent';
+    model: unknown;
+}
+export interface AuthConfig {
+    defaults: {
+        guard: string;
+    };
+    guards: Record<string, AuthGuardConfig>;
+    providers: Record<string, AuthProviderConfig>;
+}
+export declare class AuthManager {
+    private readonly config;
+    private readonly hashCheck;
+    private readonly getSession;
+    private readonly _guards;
+    constructor(config: AuthConfig, hashCheck: (plain: string, hashed: string) => Promise<boolean>, getSession: () => SessionStore);
+    guard(name?: string): Guard;
+    private createProvider;
+}
+export declare function runWithAuth<T>(manager: AuthManager, fn: () => T): T;
+export declare function currentAuth(): AuthManager;
+export declare class Auth {
+    private static g;
+    static guard(name: string): Guard;
+    static attempt(credentials: Record<string, unknown>, remember?: boolean): Promise<boolean>;
+    static login(user: Authenticatable, remember?: boolean): Promise<void>;
+    static logout(): Promise<void>;
+    static user(): Promise<Authenticatable | null>;
+    static id(): Promise<string | null>;
+    static check(): Promise<boolean>;
+    static guest(): Promise<boolean>;
+}
+//# sourceMappingURL=auth-manager.d.ts.map

package/dist/auth-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-manager.d.ts","sourceRoot":"","sources":["../src/auth-manager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,KAAK,EAAgB,MAAM,gBAAgB,CAAA;AAC1E,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAKpE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,SAAS,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,UAAU,CAAA;IAClB,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE;QACR,KAAK,EAAE,MAAM,CAAA;KACd,CAAA;IACD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IACvC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;CAC9C;AAID,qBAAa,WAAW;IAIpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAL7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;gBAGhC,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EAC9D,UAAU,EAAE,MAAM,YAAY;IAGjD,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK;IAqB3B,OAAO,CAAC,cAAc;CAavB;AAMD,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEnE;AAED,wBAAgB,WAAW,IAAI,WAAW,CAIzC;AAID,qBAAa,IAAI;IACf,OAAO,CAAC,MAAM,CAAC,CAAC;IAIhB,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK;IAIjC,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAI1F,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAItE,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B,MAAM,CAAC,IAAI,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAI9C,MAAM,CAAC,EAAE,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAInC,MAAM,CAAC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAIhC,MAAM,CAAC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;CAGjC"}

package/dist/auth-manager.js

@@ -0,0 +1,85 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { SessionGuard } from './session-guard.js';
+import { EloquentUserProvider } from './providers.js';
+// ─── Auth Manager ─────────────────────────────────────────
+export class AuthManager {
+    config;
+    hashCheck;
+    getSession;
+    _guards = new Map();
+    constructor(config, hashCheck, getSession) {
+        this.config = config;
+        this.hashCheck = hashCheck;
+        this.getSession = getSession;
+    }
+    guard(name) {
+        const guardName = name ?? this.config.defaults.guard;
+        const existing = this._guards.get(guardName);
+        if (existing)
+            return existing;
+        const guardConfig = this.config.guards[guardName];
+        if (!guardConfig)
+            throw new Error(`[RudderJS Auth] Guard "${guardName}" is not defined.`);
+        const provider = this.createProvider(guardConfig.provider);
+        let guard;
+        if (guardConfig.driver === 'session') {
+            guard = new SessionGuard(provider, this.getSession());
+        }
+        else {
+            throw new Error(`[RudderJS Auth] Guard driver "${guardConfig.driver}" is not supported.`);
+        }
+        this._guards.set(guardName, guard);
+        return guard;
+    }
+    createProvider(name) {
+        const providerConfig = this.config.providers[name];
+        if (!providerConfig)
+            throw new Error(`[RudderJS Auth] User provider "${name}" is not defined.`);
+        if (providerConfig.driver === 'eloquent') {
+            return new EloquentUserProvider(providerConfig.model, this.hashCheck);
+        }
+        throw new Error(`[RudderJS Auth] Provider driver "${providerConfig.driver}" is not supported.`);
+    }
+}
+// ─── Request-scoped Auth (AsyncLocalStorage) ──────────────
+const _als = new AsyncLocalStorage();
+export function runWithAuth(manager, fn) {
+    return _als.run(manager, fn);
+}
+export function currentAuth() {
+    const m = _als.getStore();
+    if (!m)
+        throw new Error('[RudderJS Auth] No auth context. Use AuthMiddleware.');
+    return m;
+}
+// ─── Auth Facade ──────────────────────────────────────────
+export class Auth {
+    static g(name) {
+        return currentAuth().guard(name);
+    }
+    static guard(name) {
+        return currentAuth().guard(name);
+    }
+    static attempt(credentials, remember) {
+        return this.g().attempt(credentials, remember);
+    }
+    static login(user, remember) {
+        return this.g().login(user, remember);
+    }
+    static logout() {
+        return this.g().logout();
+    }
+    static user() {
+        return this.g().user();
+    }
+    static id() {
+        return this.g().id();
+    }
+    static check() {
+        return this.g().check();
+    }
+    static guest() {
+        return this.g().guest();
+    }
+}
+//# sourceMappingURL=auth-manager.js.map

package/dist/auth-manager.js.map

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

package/dist/contracts.d.ts

@@ -0,0 +1,27 @@
+export interface Authenticatable {
+    getAuthIdentifier(): string;
+    getAuthPassword(): string;
+    getRememberToken(): string | null;
+    setRememberToken(token: string): void;
+}
+export interface AuthUser {
+    id: string;
+    name: string;
+    email: string;
+    [key: string]: unknown;
+}
+export interface UserProvider {
+    retrieveById(id: string): Promise<Authenticatable | null>;
+    retrieveByCredentials(credentials: Record<string, unknown>): Promise<Authenticatable | null>;
+    validateCredentials(user: Authenticatable, credentials: Record<string, unknown>): Promise<boolean>;
+}
+export interface Guard {
+    user(): Promise<Authenticatable | null>;
+    id(): Promise<string | null>;
+    check(): Promise<boolean>;
+    guest(): Promise<boolean>;
+    attempt(credentials: Record<string, unknown>, remember?: boolean): Promise<boolean>;
+    login(user: Authenticatable, remember?: boolean): Promise<void>;
+    logout(): Promise<void>;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe;IAC9B,iBAAiB,IAAI,MAAM,CAAA;IAC3B,eAAe,IAAI,MAAM,CAAA;IACzB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAAA;IACjC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACtC;AAID,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAID,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAA;IACzD,qBAAqB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAA;IAC5F,mBAAmB,CAAC,IAAI,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACnG;AAID,MAAM,WAAW,KAAK;IACpB,IAAI,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAA;IACvC,EAAE,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAC5B,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IACzB,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IACzB,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACnF,KAAK,CAAC,IAAI,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/D,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACxB"}

package/dist/contracts.js

@@ -0,0 +1,3 @@
+// ─── Authenticatable Contract ─────────────────────────────
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA,6DAA6D"}

package/dist/gate.d.ts

@@ -0,0 +1,49 @@
+import type { Authenticatable } from './contracts.js';
+type AbilityCallback = (user: Authenticatable, ...args: unknown[]) => boolean | Promise<boolean>;
+type BeforeCallback = (user: Authenticatable, ability: string) => boolean | null | undefined | Promise<boolean | null | undefined>;
+export declare abstract class Policy {
+    /**
+     * Run before any other check. Return true/false to short-circuit,
+     * or null/undefined to fall through to the specific method.
+     */
+    before?(_user: Authenticatable): boolean | null | undefined | Promise<boolean | null | undefined>;
+}
+type PolicyClass = new () => Policy;
+type ModelClass = abstract new (...args: any[]) => unknown;
+export declare class Gate {
+    private static _abilities;
+    private static _policies;
+    private static _beforeCallbacks;
+    static define(ability: string, callback: AbilityCallback): void;
+    static before(callback: BeforeCallback): void;
+    static policy(model: ModelClass, policy: PolicyClass): void;
+    static allows(ability: string, ...args: unknown[]): Promise<boolean>;
+    static denies(ability: string, ...args: unknown[]): Promise<boolean>;
+    /**
+     * Check ability — throw 403 if denied.
+     */
+    static authorize(ability: string, ...args: unknown[]): Promise<void>;
+    static forUser(user: Authenticatable): GateForUser;
+    private static resolveUser;
+    private static _check;
+    private static findPolicy;
+    private static callPolicy;
+    /** @internal — reset all definitions. Used for testing. */
+    static reset(): void;
+}
+declare class GateForUser {
+    private readonly user;
+    private readonly abilities;
+    private readonly policies;
+    private readonly beforeCallbacks;
+    constructor(user: Authenticatable, abilities: Map<string, AbilityCallback>, policies: Map<ModelClass, PolicyClass>, beforeCallbacks: BeforeCallback[]);
+    allows(ability: string, ...args: unknown[]): Promise<boolean>;
+    denies(ability: string, ...args: unknown[]): Promise<boolean>;
+    authorize(ability: string, ...args: unknown[]): Promise<void>;
+}
+export declare class AuthorizationError extends Error {
+    readonly status = 403;
+    constructor(message?: string);
+}
+export {};
+//# sourceMappingURL=gate.d.ts.map

package/dist/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAKrD,KAAK,eAAe,GAAG,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAChG,KAAK,cAAc,GAAG,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;AAIlI,8BAAsB,MAAM;IAC1B;;;OAGG;IACH,MAAM,CAAC,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;CAClG;AAED,KAAK,WAAW,GAAG,UAAU,MAAM,CAAA;AAEnC,KAAK,UAAU,GAAG,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAA;AAI1D,qBAAa,IAAI;IACf,OAAO,CAAC,MAAM,CAAC,UAAU,CAAqC;IAC9D,OAAO,CAAC,MAAM,CAAC,SAAS,CAAqC;IAC7D,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAuB;IAItD,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI;IAI/D,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAI7C,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;WAM9C,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;WAM7D,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAI1E;;OAEG;WACU,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ1E,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW;mBAM7B,WAAW;mBASX,MAAM;IAuB3B,OAAO,CAAC,MAAM,CAAC,UAAU;mBAiBJ,UAAU;IAqB/B,2DAA2D;IAC3D,MAAM,CAAC,KAAK,IAAI,IAAI;CAKrB;AAID,cAAM,WAAW;IAEb,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,eAAe;gBAHf,IAAI,EAAE,eAAe,EACrB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,EACvC,QAAQ,EAAE,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,EACtC,eAAe,EAAE,cAAc,EAAE;IAG9C,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAkC7D,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAI7D,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAKpE;AAID,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,MAAM,OAAM;gBAET,OAAO,SAAiC;CAIrD"}