@kaiz11/stack-client 0.0.14

package/dist/auth/server/middleware.js

@@ -0,0 +1,405 @@
+import { verifyToken, extractBearerToken, createJWKS, VerifyError, } from "./verify.js";
+import { PLATFORM_TENANT_ID } from "../../types.js";
+import { fetchAnonKeyCached } from "../../lib/keys.js";
+/**
+ * Create auth middleware for Hono
+ *
+ * Automatically constructs the JWKS URL from the base URL and optional tenant ID,
+ * and verifies JWT tokens signed by the GoTrue instance.
+ *
+ * ## Token Handling
+ *
+ * | Token Type    | Result                                          |
+ * |---------------|-------------------------------------------------|
+ * | No token      | 401 Unauthorized                                |
+ * | Invalid token | 401 Unauthorized                                |
+ * | Anon JWT      | ✅ Passes, `user.role = "anon"`                 |
+ * | Auth JWT      | ✅ Passes, `user.role = "authenticated"`        |
+ * | Service JWT   | ✅ Passes, `user.role = "service_role"`         |
+ *
+ * **Note:** This middleware requires a valid JWT. In Supabase's model, even
+ * "public" requests use the anon key. If you want to allow requests without
+ * any token, use `optionalStackAuthMiddleware` instead.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from "hono";
+ * import { createStackAuthMiddleware } from "@kaiz11/stack-client/auth/server";
+ *
+ * const app = new Hono();
+ *
+ * // Platform (default)
+ * app.use("*", createStackAuthMiddleware({
+ *   baseUrl: "https://stack.zenku.app",
+ *   excludePaths: [/^\/health$/],
+ * }));
+ *
+ * // Tenant
+ * app.use("*", createStackAuthMiddleware({
+ *   baseUrl: "https://stack.zenku.app",
+ *   tenantId: "acme-corp",
+ *   excludePaths: [/^\/health$/],
+ * }));
+ *
+ * app.get("/api/me", (c) => {
+ *   const user = c.get("user") as AuthUser;
+ *   return c.json({ user });
+ * });
+ * ```
+ */
+export function createStackAuthMiddleware(config) {
+    const tenantId = config.tenantId ?? PLATFORM_TENANT_ID;
+    const keyGetter = createJWKS(config.baseUrl, tenantId);
+    return createAuthMiddleware({
+        keyGetter,
+        options: config.options,
+        excludePaths: config.excludePaths,
+        onError: config.onError,
+    });
+}
+/**
+ * Create auth middleware for Hono (advanced)
+ *
+ * Use this when you need to provide a custom JWKS key getter.
+ * For most cases, prefer `createStackAuthMiddleware`.
+ *
+ * ## Token Handling
+ *
+ * | Token Type    | Result                                          |
+ * |---------------|-------------------------------------------------|
+ * | No token      | 401 Unauthorized                                |
+ * | Invalid token | 401 Unauthorized                                |
+ * | Anon JWT      | ✅ Passes, `user.role = "anon"`                 |
+ * | Auth JWT      | ✅ Passes, `user.role = "authenticated"`        |
+ * | Service JWT   | ✅ Passes, `user.role = "service_role"`         |
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from "hono";
+ * import { createAuthMiddleware, createLocalJWKS } from "@kaiz11/stack-client/auth/server";
+ *
+ * const app = new Hono();
+ *
+ * // For testing with local keys
+ * const keyGetter = createLocalJWKS(testJWKS);
+ *
+ * app.use("*", createAuthMiddleware({
+ *   keyGetter,
+ *   excludePaths: [/^\/health$/],
+ * }));
+ * ```
+ */
+export function createAuthMiddleware(config) {
+    const { keyGetter, options, excludePaths = [], onError } = config;
+    return async (c, next) => {
+        // Check if path is excluded
+        const path = c.req.path;
+        for (const pattern of excludePaths) {
+            if (pattern.test(path)) {
+                return next();
+            }
+        }
+        // Extract and verify token
+        const authHeader = c.req.raw.headers.get("authorization");
+        const token = extractBearerToken(authHeader);
+        if (!token) {
+            const error = VerifyError.missingToken();
+            if (onError) {
+                return onError(error);
+            }
+            return c.json({ error: error.message, code: error.code }, 401);
+        }
+        try {
+            const payload = await verifyToken(token, keyGetter, options);
+            const user = {
+                id: payload.sub,
+                email: payload.email ?? null,
+                phone: payload.phone ?? null,
+                role: payload.role,
+                aal: payload.aal || "aal1",
+                appMetadata: payload.app_metadata ?? {},
+                userMetadata: payload.user_metadata ?? {},
+            };
+            // Attach to context
+            c.set("user", user);
+            c.set("tokenPayload", payload);
+            c.set("accessToken", token);
+            return next();
+        }
+        catch (error) {
+            if (error instanceof VerifyError) {
+                if (onError) {
+                    return onError(error);
+                }
+                return c.json({ error: error.message, code: error.code }, error.statusCode);
+            }
+            throw error;
+        }
+    };
+}
+/**
+ * Create role guard middleware for Hono
+ *
+ * Use after `createStackAuthMiddleware` to require specific roles.
+ *
+ * ## Token Handling (assuming auth middleware already ran)
+ *
+ * | Token Type    | `requireRoleMiddleware("authenticated")` | `requireRoleMiddleware("service_role")` |
+ * |---------------|------------------------------------------|----------------------------------------|
+ * | Anon JWT      | 403 Forbidden                            | 403 Forbidden                          |
+ * | Auth JWT      | ✅ Passes                                | 403 Forbidden                          |
+ * | Service JWT   | 403 Forbidden                            | ✅ Passes                              |
+ *
+ * **Common patterns:**
+ * - `requireRoleMiddleware("authenticated")` — Reject anon, allow logged-in users
+ * - `requireRoleMiddleware("service_role")` — Admin/server-only endpoints
+ *
+ * @example
+ * ```typescript
+ * import { createStackAuthMiddleware, requireRoleMiddleware } from "@kaiz11/stack-client/auth/server";
+ *
+ * app.use("*", createStackAuthMiddleware({ baseUrl: "https://stack.zenku.app" }));
+ *
+ * // Reject anon tokens, require actual login
+ * app.use("/api/user/*", requireRoleMiddleware("authenticated"));
+ *
+ * // Admin routes require service_role
+ * app.use("/admin/*", requireRoleMiddleware("service_role"));
+ * ```
+ */
+export function requireRoleMiddleware(role) {
+    return async (c, next) => {
+        const user = c.get("user");
+        if (!user) {
+            return c.json({ error: "Authentication required", code: "missing_auth" }, 401);
+        }
+        if (user.role !== role) {
+            return c.json({
+                error: `Insufficient role: required ${role}, got ${user.role}`,
+                code: "insufficient_role",
+            }, 403);
+        }
+        return next();
+    };
+}
+/**
+ * Create MFA guard middleware for Hono
+ *
+ * Requires AAL2 (two-factor authentication verified in current session).
+ *
+ * ## Token Handling (assuming auth middleware already ran)
+ *
+ * | Token Type       | AAL Level | Result                              |
+ * |------------------|-----------|-------------------------------------|
+ * | Anon JWT         | aal1      | 403 MFA required                    |
+ * | Auth JWT         | aal1      | 403 MFA required                    |
+ * | Auth JWT + MFA   | aal2      | ✅ Passes                           |
+ * | Service JWT      | aal1      | 403 MFA required                    |
+ *
+ * **Note:** Service role tokens typically have aal1. If you need service role
+ * access to MFA-protected routes, check the role explicitly instead.
+ *
+ * @example
+ * ```typescript
+ * // Sensitive routes require MFA
+ * app.use("/settings/security/*", requireMfaMiddleware());
+ *
+ * // Or combine with role check for admin bypass
+ * app.use("/settings/security/*", async (c, next) => {
+ *   const user = c.get("user") as AuthUser;
+ *   if (user.role === "service_role") return next(); // Admin bypass
+ *   return requireMfaMiddleware()(c, next);
+ * });
+ * ```
+ */
+export function requireMfaMiddleware() {
+    return async (c, next) => {
+        const user = c.get("user");
+        const payload = c.get("tokenPayload");
+        if (!user || !payload) {
+            return c.json({ error: "Authentication required", code: "missing_auth" }, 401);
+        }
+        const aal = payload.aal || "aal1";
+        if (aal !== "aal2") {
+            return c.json({
+                error: "MFA verification required",
+                code: "mfa_required",
+                currentAal: aal,
+                requiredAal: "aal2",
+            }, 403);
+        }
+        return next();
+    };
+}
+/**
+ * Optional auth middleware for Hono
+ *
+ * Attaches user info if token is present. When no token is provided,
+ * automatically fetches the tenant's anon key (default behavior).
+ *
+ * ## Token Handling (default, autoFetchAnon = true)
+ *
+ * | Token Type    | Result                                          |
+ * |---------------|-------------------------------------------------|
+ * | No token      | ✅ Auto-fetches anon key, `user.role = "anon"`  |
+ * | Invalid token | ✅ Falls back to anon key, `user.role = "anon"` |
+ * | Anon JWT      | ✅ Continues, `user.role = "anon"`              |
+ * | Auth JWT      | ✅ Continues, `user.role = "authenticated"`     |
+ * | Service JWT   | ✅ Continues, `user.role = "service_role"`      |
+ *
+ * ## Token Handling (autoFetchAnon = false)
+ *
+ * | Token Type    | Result                                          |
+ * |---------------|-------------------------------------------------|
+ * | No token      | ✅ Continues, `user = undefined`                |
+ * | Invalid token | ✅ Continues, `user = undefined`                |
+ * | Anon JWT      | ✅ Continues, `user.role = "anon"`              |
+ * | Auth JWT      | ✅ Continues, `user.role = "authenticated"`     |
+ * | Service JWT   | ✅ Continues, `user.role = "service_role"`      |
+ *
+ * **Note:** Unlike `createStackAuthMiddleware`, this never returns 401.
+ * Invalid tokens fall back to anon (default) or are silently ignored.
+ *
+ * @example
+ * ```typescript
+ * import { optionalStackAuthMiddleware } from "@kaiz11/stack-client/auth/server";
+ *
+ * // Default: user is always set (auto-fetches anon if no token)
+ * app.use("*", optionalStackAuthMiddleware({
+ *   baseUrl: "https://stack.zenku.app",
+ *   tenantId: "acme-corp",
+ * }));
+ *
+ * // Disable auto-fetch: user may be undefined if no token
+ * app.use("*", optionalStackAuthMiddleware({
+ *   baseUrl: "https://stack.zenku.app",
+ *   tenantId: "acme-corp",
+ *   autoFetchAnon: false,
+ * }));
+ *
+ * app.get("/api/feed", (c) => {
+ *   const user = c.get("user") as AuthUser;
+ *   if (user.role === "authenticated") {
+ *     // Logged in user
+ *   } else {
+ *     // Anonymous access (anon token or auto-fetched)
+ *   }
+ * });
+ * ```
+ */
+export function optionalStackAuthMiddleware(config) {
+    const tenantId = config.tenantId ?? PLATFORM_TENANT_ID;
+    const keyGetter = createJWKS(config.baseUrl, tenantId);
+    const { baseUrl } = config;
+    const autoFetchAnon = config.autoFetchAnon ?? true;
+    return async (c, next) => {
+        const authHeader = c.req.raw.headers.get("authorization");
+        let token = extractBearerToken(authHeader);
+        // Auto-fetch anon key if no token and autoFetchAnon is enabled
+        if (!token && autoFetchAnon) {
+            try {
+                token = await fetchAnonKeyCached(baseUrl, tenantId);
+            }
+            catch {
+                // Failed to fetch anon key, continue without auth
+            }
+        }
+        if (token) {
+            try {
+                const payload = await verifyToken(token, keyGetter, config.options);
+                const user = {
+                    id: payload.sub,
+                    email: payload.email ?? null,
+                    phone: payload.phone ?? null,
+                    role: payload.role,
+                    aal: payload.aal || "aal1",
+                    appMetadata: payload.app_metadata ?? {},
+                    userMetadata: payload.user_metadata ?? {},
+                };
+                c.set("user", user);
+                c.set("tokenPayload", payload);
+                c.set("accessToken", token);
+            }
+            catch {
+                // Invalid token - try to fall back to anon if autoFetchAnon
+                if (autoFetchAnon) {
+                    try {
+                        const anonToken = await fetchAnonKeyCached(baseUrl, tenantId);
+                        const payload = await verifyToken(anonToken, keyGetter, config.options);
+                        const user = {
+                            id: payload.sub,
+                            email: payload.email ?? null,
+                            phone: payload.phone ?? null,
+                            role: payload.role,
+                            aal: payload.aal || "aal1",
+                            appMetadata: payload.app_metadata ?? {},
+                            userMetadata: payload.user_metadata ?? {},
+                        };
+                        c.set("user", user);
+                        c.set("tokenPayload", payload);
+                        c.set("accessToken", anonToken);
+                    }
+                    catch {
+                        // Failed to use anon fallback, continue without auth
+                    }
+                }
+            }
+        }
+        return next();
+    };
+}
+/**
+ * Optional auth middleware for Hono (advanced)
+ *
+ * Attaches user info if token is present, but doesn't require it.
+ * Use this when you need a custom JWKS key getter.
+ *
+ * ## Token Handling
+ *
+ * | Token Type    | Result                                          |
+ * |---------------|-------------------------------------------------|
+ * | No token      | ✅ Continues, `user = undefined`                |
+ * | Invalid token | ✅ Continues, `user = undefined`                |
+ * | Anon JWT      | ✅ Continues, `user.role = "anon"`              |
+ * | Auth JWT      | ✅ Continues, `user.role = "authenticated"`     |
+ * | Service JWT   | ✅ Continues, `user.role = "service_role"`      |
+ *
+ * @example
+ * ```typescript
+ * import { optionalAuthMiddleware, createLocalJWKS } from "@kaiz11/stack-client/auth/server";
+ *
+ * // For testing with local keys
+ * const keyGetter = createLocalJWKS(testJWKS);
+ *
+ * app.use("*", optionalAuthMiddleware({ keyGetter }));
+ * ```
+ */
+export function optionalAuthMiddleware(config) {
+    const { keyGetter, options } = config;
+    return async (c, next) => {
+        const authHeader = c.req.raw.headers.get("authorization");
+        const token = extractBearerToken(authHeader);
+        if (token) {
+            try {
+                const payload = await verifyToken(token, keyGetter, options);
+                const user = {
+                    id: payload.sub,
+                    email: payload.email ?? null,
+                    phone: payload.phone ?? null,
+                    role: payload.role,
+                    aal: payload.aal || "aal1",
+                    appMetadata: payload.app_metadata ?? {},
+                    userMetadata: payload.user_metadata ?? {},
+                };
+                c.set("user", user);
+                c.set("tokenPayload", payload);
+                c.set("accessToken", token);
+            }
+            catch {
+                // Invalid token, continue without auth
+            }
+        }
+        return next();
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/auth/server/middleware.js.map

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

package/dist/auth/server/verify.d.ts

@@ -0,0 +1,184 @@
+import * as jose from "jose";
+/**
+ * JWT payload structure from GoTrue
+ */
+export interface TokenPayload {
+    /** User ID */
+    sub: string;
+    /** Email address */
+    email?: string;
+    /** Phone number */
+    phone?: string;
+    /** User role (authenticated, anon, service_role) */
+    role: string;
+    /** Audience */
+    aud?: string;
+    /** Expiration time (Unix timestamp) */
+    exp?: number;
+    /** Issued at (Unix timestamp) */
+    iat?: number;
+    /** Authenticator assurance level */
+    aal?: "aal1" | "aal2";
+    /** App metadata */
+    app_metadata?: {
+        provider?: string;
+        providers?: string[];
+    };
+    /** User metadata */
+    user_metadata?: Record<string, unknown>;
+}
+/**
+ * Verification options
+ */
+export interface VerifyOptions {
+    /** Expected audience (optional) */
+    audience?: string;
+    /** Clock tolerance in seconds (default: 0) */
+    clockTolerance?: number;
+    /** Required role (optional) */
+    requiredRole?: string;
+    /** Required AAL level (optional) */
+    requiredAal?: "aal1" | "aal2";
+}
+/**
+ * Key getter function type (returned by createRemoteJWKS or createLocalJWKS)
+ */
+export type JWKSKeyGetter = ReturnType<typeof jose.createRemoteJWKSet>;
+/**
+ * Verification error
+ */
+export declare class VerifyError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    constructor(message: string, code: string, statusCode?: number);
+    static invalidToken(reason?: string): VerifyError;
+    static tokenExpired(): VerifyError;
+    static insufficientRole(required: string, actual: string): VerifyError;
+    static insufficientAal(required: string, actual: string): VerifyError;
+    static missingToken(): VerifyError;
+}
+/**
+ * Get the JWKS URL for a tenant
+ *
+ * @param baseUrl - The stack base URL (e.g., "https://stack.zenku.app")
+ * @param tenantId - The tenant identifier (default: "_platform")
+ * @returns The JWKS URL
+ *
+ * @example
+ * ```typescript
+ * getJWKSUrl("https://stack.zenku.app")
+ * // → "https://stack.zenku.app/auth/_platform/.well-known/jwks.json"
+ *
+ * getJWKSUrl("https://stack.zenku.app", "acme-corp")
+ * // → "https://stack.zenku.app/auth/acme-corp/.well-known/jwks.json"
+ * ```
+ */
+export declare function getJWKSUrl(baseUrl: string, tenantId?: string): string;
+/**
+ * Create a JWKS key getter
+ *
+ * Automatically constructs the JWKS URL from the base URL and optional tenant ID.
+ *
+ * @param baseUrl - The stack base URL (e.g., "https://stack.zenku.app")
+ * @param tenantId - The tenant identifier (default: "_platform")
+ * @returns A key getter function for use with verifyToken
+ *
+ * @example
+ * ```typescript
+ * import { createJWKS, verifyToken } from "@kaiz11/stack-client/auth/server";
+ *
+ * // Platform (default)
+ * const getKey = createJWKS("https://stack.zenku.app");
+ *
+ * // Tenant
+ * const getKey = createJWKS("https://stack.zenku.app", "acme-corp");
+ *
+ * const payload = await verifyToken(token, getKey);
+ * ```
+ */
+export declare function createJWKS(baseUrl: string, tenantId?: string): JWKSKeyGetter;
+/**
+ * Create a JWKS key getter from a URL
+ *
+ * Fetches and caches the JWKS from the GoTrue /.well-known/jwks.json endpoint.
+ * Uses jose's built-in caching and refresh logic.
+ *
+ * For most use cases, prefer `createPlatformJWKS` or `createTenantJWKS` which
+ * automatically construct the URL.
+ *
+ * @param jwksUrl - The JWKS endpoint URL
+ * @returns A key getter function for use with verifyToken
+ *
+ * @example
+ * ```typescript
+ * import { createRemoteJWKS, verifyToken } from "@kaiz11/stack-client/auth/server";
+ *
+ * const getKey = createRemoteJWKS("https://stack.zenku.app/auth/_platform/.well-known/jwks.json");
+ * const payload = await verifyToken(token, getKey);
+ * ```
+ */
+export declare function createRemoteJWKS(jwksUrl: string): JWKSKeyGetter;
+/**
+ * Create a JWKS key getter from a local JWKS object
+ *
+ * Useful for testing without making network requests.
+ *
+ * @param jwks - The JWKS object containing keys
+ * @returns A key getter function for use with verifyToken
+ *
+ * @example
+ * ```typescript
+ * import { createLocalJWKS, verifyToken } from "@kaiz11/stack-client/auth/server";
+ *
+ * const jwks = { keys: [{ kty: "EC", crv: "P-256", ... }] };
+ * const getKey = createLocalJWKS(jwks);
+ * const payload = await verifyToken(token, getKey);
+ * ```
+ */
+export declare function createLocalJWKS(jwks: jose.JSONWebKeySet): JWKSKeyGetter;
+/**
+ * Clear the JWKS cache (useful for testing or key rotation)
+ */
+export declare function clearJWKSCache(): void;
+/**
+ * Verify a JWT and extract the payload using ES256 (ECDSA P-256)
+ *
+ * @param token - The JWT access token to verify
+ * @param keyGetter - JWKS key getter (from createRemoteJWKS or createLocalJWKS)
+ * @param options - Optional verification options
+ * @returns The token payload if valid
+ * @throws VerifyError if the token is invalid or expired
+ *
+ * @example
+ * ```typescript
+ * import { createRemoteJWKS, verifyToken } from "@kaiz11/stack-client/auth/server";
+ *
+ * // Create key getter once (cached)
+ * const getKey = createRemoteJWKS(process.env.JWKS_URL!);
+ *
+ * // Verify tokens
+ * const payload = await verifyToken(token, getKey);
+ * console.log("User ID:", payload.sub);
+ * console.log("Email:", payload.email);
+ * console.log("Role:", payload.role);
+ * ```
+ */
+export declare function verifyToken(token: string, keyGetter: JWKSKeyGetter, options?: VerifyOptions): Promise<TokenPayload>;
+/**
+ * Extract bearer token from Authorization header
+ *
+ * @param authHeader - The Authorization header value
+ * @returns The token string or null if not a valid Bearer token
+ *
+ * @example
+ * ```typescript
+ * import { extractBearerToken } from "@kaiz11/stack-client/auth/server";
+ *
+ * const token = extractBearerToken(request.headers.get("Authorization"));
+ * if (token) {
+ *   const payload = await verifyToken(token, secret);
+ * }
+ * ```
+ */
+export declare function extractBearerToken(authHeader: string | null): string | null;
+//# sourceMappingURL=verify.d.ts.map

package/dist/auth/server/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/auth/server/verify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAG7B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,cAAc;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,eAAe;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,mBAAmB;IACnB,YAAY,CAAC,EAAE;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;KACtB,CAAC;IACF,oBAAoB;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,IAAI,CAAC,kBAAkB,CAAC,CAAC;AAEvE;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAGlB,IAAI,EAAE,MAAM;aACZ,UAAU,EAAE,MAAM;gBAFlC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAY;IAM1C,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW;IAQjD,MAAM,CAAC,YAAY,IAAI,WAAW;IAIlC,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW;IAQtE,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW;IAQrE,MAAM,CAAC,YAAY,IAAI,WAAW;CAGnC;AAKD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAA2B,GACpC,MAAM,CAER;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAA2B,GACpC,aAAa,CAEf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAgB/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,aAAa,GAAG,aAAa,CAEvE;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,aAAa,EACxB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CA6CvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAK3E"}