@agentic-passport/next 0.3.0

package/dist/next-adapter.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Next.js adapter for AgentPassport (works on Next 14, 15, and 16).
+ *
+ * Architecture: middleware NEVER imports crypto. It only sniffs headers and
+ * decides whether to bypass Clerk's redirect-to-signin. The actual protocol
+ * work (verifying signatures, minting tokens, etc.) happens in dedicated
+ * route handlers under `app/agent/*` and `app/.well-known/agent-passport`, which
+ * the vendor wires up with the factories below. Each of those routes
+ * declares `export const runtime = 'nodejs'` so node:crypto works freely.
+ *
+ * Usage in middleware.ts:
+ *
+ *   import { isAgentRequest } from '@agentic-passport/next';
+ *   import { clerkMiddleware } from '@clerk/nextjs/server';
+ *   import { NextResponse } from 'next/server';
+ *
+ *   const clerk = clerkMiddleware();
+ *   export default async function middleware(req, evt) {
+ *     const headers = Object.fromEntries(req.headers);
+ *     if (isAgentRequest({ headers })) return NextResponse.next();
+ *     return clerk(req, evt);
+ *   }
+ *
+ * That's the whole middleware. No imports from this package's handler.ts.
+ * Edge-safe.
+ */
+import type { AgentPassportInstance } from './handler.js';
+/** @deprecated Use the global `Request` type. Kept as an alias for back-compat with 0.0.2. */
+export type MinimalNextRequest = Request;
+/**
+ * Canonical agent identity, derived from the verified handshake. Use this
+ * in `onAgentSignup` to provision the agent into your auth provider —
+ * vendors shouldn't be inventing emails, names, or metadata shapes for
+ * agents. The SDK returns the right fields.
+ *
+ *   onAgentSignup: async (ctx) => {
+ *     const identity = agentIdentity(ctx);
+ *     const user = await clerkClient.users.createUser({
+ *       ...identity,                  // externalId, emailAddress, firstName, lastName, publicMetadata
+ *       skipPasswordRequirement: true,
+ *     });
+ *     return { allow: true, principal: { userId: user.id, grantedScopes: identity.grantedScopes } };
+ *   }
+ *
+ * Email format: `agent-<safe-id>@agents.invalid` — RFC 6761-reserved TLD,
+ * never deliverable, no domain owner can claim it. When AgentPassport has a
+ * canonical brand domain this default will move; the shape stays the same.
+ *
+ * The `publicMetadata` shape is canonical across vendors so that a tool
+ * looking up an "agent user" in Clerk (or any auth provider) finds the
+ * same fields regardless of which vendor provisioned it. Filterable on
+ * `publicMetadata.agent === true`.
+ */
+import type { AgentSignupContext } from './types.js';
+export type CanonicalAgentIdentity = {
+    externalId: string;
+    emailAddress: [string];
+    firstName: string;
+    lastName: string;
+    publicMetadata: {
+        agentpassport: {
+            schema: 'agentpassport/v1';
+            agentId: string;
+            actor: string | null;
+            task: string;
+            mandate: {
+                jti: string;
+                issuer: string;
+                expiresAt: number;
+            };
+            scopes: readonly string[];
+        };
+    };
+    /** Convenience: scopes the SDK has verified the agent can use. */
+    grantedScopes: string[];
+};
+export declare function agentIdentity(ctx: AgentSignupContext): CanonicalAgentIdentity;
+/**
+ * Discovery doc handler.
+ *
+ *   // app/.well-known/agent-passport/route.ts
+ *   export const runtime = 'nodejs';
+ *   export const dynamic = 'force-dynamic';
+ *   export const GET = createDiscoveryHandler(getGate);
+ *
+ * Accepts either an AgentPassportInstance or a Promise/factory for one.
+ */
+export declare function createDiscoveryHandler(gateOrFactory: AgentPassportInstance | (() => Promise<AgentPassportInstance>)): () => Promise<Response>;
+/**
+ * Register handler.
+ *
+ *   // app/agent/register/route.ts
+ *   export const runtime = 'nodejs';
+ *   export const dynamic = 'force-dynamic';
+ *   export const POST = createRegisterHandler(getGate);
+ */
+export declare function createRegisterHandler(gateOrFactory: AgentPassportInstance | (() => Promise<AgentPassportInstance>)): (req: Request) => Promise<Response>;
+/**
+ * Authorize handler.
+ *
+ *   // app/agent/authorize/route.ts
+ *   export const runtime = 'nodejs';
+ *   export const dynamic = 'force-dynamic';
+ *   export const POST = createAuthorizeHandler(getGate);
+ */
+export declare function createAuthorizeHandler(gateOrFactory: AgentPassportInstance | (() => Promise<AgentPassportInstance>)): (req: Request) => Promise<Response>;
+/**
+ * Audit log handler. Gate behind your own auth in production (Clerk session,
+ * API key, etc.) — audit data is sensitive.
+ *
+ *   // app/agent/audit/route.ts
+ *   export const runtime = 'nodejs';
+ *   export const dynamic = 'force-dynamic';
+ *   export const GET = createAuditHandler(getGate);
+ */
+export declare function createAuditHandler(gateOrFactory: AgentPassportInstance | (() => Promise<AgentPassportInstance>)): () => Promise<Response>;
+/**
+ * Catch-all dispatcher for all AgentPassport protocol endpoints.
+ *
+ * Mount this once and you don't need separate route files for register,
+ * authorize, audit, or the discovery doc. The gate routes internally based
+ * on the request URL.
+ *
+ * Two route files cover the four protocol surfaces:
+ *
+ *   // app/agent/[...agentauth]/route.ts
+ *   import { handleAgentPassport } from '@agentic-passport/next';
+ *   import { getGate } from '@/lib/agent-gate';
+ *   export const runtime = 'nodejs';
+ *   export const dynamic = 'force-dynamic';
+ *   export const GET = (r: Request) => handleAgentPassport(r, getGate);
+ *   export const POST = (r: Request) => handleAgentPassport(r, getGate);
+ *
+ *   // app/.well-known/agent-passport/route.ts
+ *   export const runtime = 'nodejs';
+ *   export const dynamic = 'force-dynamic';
+ *   export const GET = (r: Request) => handleAgentPassport(r, getGate);
+ *
+ * (Next.js does not allow a single catch-all to cover both `/agent/*` and
+ * `/.well-known/agent-passport` — the well-known route lives outside `/agent`.
+ * Two files; one line each.)
+ */
+export declare function handleAgentPassport(req: Request, gateOrFactory: AgentPassportInstance | (() => Promise<AgentPassportInstance>)): Promise<Response>;
+/**
+ * Wrap a vendor API route handler so it verifies the agent's signed request +
+ * DPoP-bound access token + required scope before running. The wrapped handler
+ * receives the verified principal as its second argument.
+ *
+ *   // app/api/keyword-search/route.ts  (or whatever the vendor's endpoint is)
+ *   export const runtime = 'nodejs';
+ *   export const dynamic = 'force-dynamic';
+ *
+ *   export async function GET(req: NextRequest) {
+ *     if (isAgentRequest({ headers: Object.fromEntries(req.headers) })) {
+ *       return withAgent(getGate, 'keyword.search', async (r, principal) => {
+ *         return Response.json(await searchKeywords(r, principal.agentId));
+ *       })(req);
+ *     }
+ *     // Existing human flow stays exactly as-is:
+ *     const { userId } = await auth();
+ *     if (!userId) return new Response('unauthorized', { status: 401 });
+ *     return Response.json(await searchKeywords(req, userId));
+ *   }
+ */
+export declare function withAgent<T>(gateOrFactory: AgentPassportInstance | (() => Promise<AgentPassportInstance>), requiredScope: string, handler: (req: Request, principal: {
+    agentId: string;
+    scopes: readonly string[];
+    mandateJti: string;
+}) => Promise<T>): (req: Request) => Promise<Response>;
+/**
+ * Discriminated principal: agent (verified via AgentPassport) or human
+ * (verified via the vendor's own auth provider). Both carry a `userId`
+ * the vendor's business logic can branch on.
+ *
+ * The `mandateJti` and `scopes` fields only exist for agents — humans
+ * don't carry a mandate. Vendor route handlers should narrow on `type`
+ * before reading them.
+ */
+export type AgentSessionPrincipal = {
+    type: 'agent';
+    userId: string;
+    agentId: string;
+    scopes: readonly string[];
+    mandateJti: string;
+};
+export type HumanSessionPrincipal = {
+    type: 'human';
+    userId: string;
+};
+export type SessionPrincipal = AgentSessionPrincipal | HumanSessionPrincipal;
+/**
+ * Resolve the request's principal — agent OR human OR none — without
+ * bridging cookies. This is the recommended way to write a vendor route
+ * that should be reachable by both.
+ *
+ * Behavior:
+ *   1. Agent path. If the request carries AgentPassport headers (signature
+ *      + DPoP-bound token), verify them via `gate.authorizeApiCall` and
+ *      return an `AgentSessionPrincipal`. Scope is verified iff
+ *      `opts.requireScope` is provided.
+ *   2. Human path. If not an agent, and `opts.humanAuth` is provided,
+ *      call it. If it returns `{ userId }`, return a `HumanSessionPrincipal`.
+ *   3. Otherwise return null.
+ *
+ *   // app/api/account/route.ts
+ *   import { getSession } from '@agentic-passport/next';
+ *   import { auth } from '@clerk/nextjs/server';
+ *
+ *   export async function GET(req: Request) {
+ *     const principal = await getSession(req, {
+ *       gate: getGate,
+ *       humanAuth: async () => {
+ *         const { userId } = await auth();
+ *         return userId ? { userId } : null;
+ *       },
+ *     });
+ *     if (!principal) return new Response('unauthorized', { status: 401 });
+ *     // Same code path for agent and human. Branch only if you need to:
+ *     //   if (principal.type === 'agent') ...
+ *     return Response.json({ user: principal.userId });
+ *   }
+ */
+export declare function getSession(req: Request, opts: {
+    gate: AgentPassportInstance | (() => Promise<AgentPassportInstance>);
+    humanAuth?: () => Promise<{
+        userId: string;
+    } | null>;
+    requireScope?: string;
+}): Promise<SessionPrincipal | null>;
+//# sourceMappingURL=next-adapter.d.ts.map

package/dist/next-adapter.d.ts.map

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

package/dist/next-adapter.js

@@ -0,0 +1,270 @@
+/**
+ * Next.js adapter for AgentPassport (works on Next 14, 15, and 16).
+ *
+ * Architecture: middleware NEVER imports crypto. It only sniffs headers and
+ * decides whether to bypass Clerk's redirect-to-signin. The actual protocol
+ * work (verifying signatures, minting tokens, etc.) happens in dedicated
+ * route handlers under `app/agent/*` and `app/.well-known/agent-passport`, which
+ * the vendor wires up with the factories below. Each of those routes
+ * declares `export const runtime = 'nodejs'` so node:crypto works freely.
+ *
+ * Usage in middleware.ts:
+ *
+ *   import { isAgentRequest } from '@agentic-passport/next';
+ *   import { clerkMiddleware } from '@clerk/nextjs/server';
+ *   import { NextResponse } from 'next/server';
+ *
+ *   const clerk = clerkMiddleware();
+ *   export default async function middleware(req, evt) {
+ *     const headers = Object.fromEntries(req.headers);
+ *     if (isAgentRequest({ headers })) return NextResponse.next();
+ *     return clerk(req, evt);
+ *   }
+ *
+ * That's the whole middleware. No imports from this package's handler.ts.
+ * Edge-safe.
+ */
+async function toNormalized(req) {
+    const headers = {};
+    req.headers.forEach((v, k) => { headers[k.toLowerCase()] = v; });
+    const ab = await req.arrayBuffer();
+    // Buffer.from on a Uint8Array is fine on Node; on Edge there's no Buffer
+    // but this code path is never reached on Edge (only Node-runtime routes
+    // import this module).
+    return { method: req.method, url: req.url, headers, body: Buffer.from(ab) };
+}
+function toResponse(res) {
+    return new Response(new Uint8Array(res.body), { status: res.status, headers: res.headers });
+}
+// example.com is RFC 2606 reserved (never deliverable), AND passes
+// auth providers' email-format validators (Clerk accepts; agents.invalid
+// is rejected because .invalid is too obviously synthetic). When the SDK
+// has its own canonical domain (agents.<brand>.dev or similar), this
+// constant moves; the canonical shape doesn't.
+const AGENTS_EMAIL_DOMAIN = 'example.com';
+export function agentIdentity(ctx) {
+    const { agentId, mandate } = ctx;
+    const safe = agentId.replace(/[^a-zA-Z0-9._-]/g, '-').toLowerCase();
+    return {
+        externalId: `agent:${agentId}`,
+        emailAddress: [`agent-${safe}@${AGENTS_EMAIL_DOMAIN}`],
+        firstName: 'Agent',
+        lastName: agentId,
+        publicMetadata: {
+            agentpassport: {
+                schema: 'agentpassport/v1',
+                agentId,
+                actor: mandate.actor ?? null,
+                task: mandate.task,
+                mandate: {
+                    jti: mandate.jti,
+                    issuer: mandate.iss,
+                    expiresAt: mandate.exp,
+                },
+                scopes: mandate.scope_hints,
+            },
+        },
+        grantedScopes: [...mandate.scope_hints],
+    };
+}
+/**
+ * Discovery doc handler.
+ *
+ *   // app/.well-known/agent-passport/route.ts
+ *   export const runtime = 'nodejs';
+ *   export const dynamic = 'force-dynamic';
+ *   export const GET = createDiscoveryHandler(getGate);
+ *
+ * Accepts either an AgentPassportInstance or a Promise/factory for one.
+ */
+export function createDiscoveryHandler(gateOrFactory) {
+    return async () => {
+        const gate = typeof gateOrFactory === 'function' ? await gateOrFactory() : gateOrFactory;
+        return new Response(JSON.stringify(gate.discoveryDoc()), { headers: { 'content-type': 'application/json' } });
+    };
+}
+/**
+ * Register handler.
+ *
+ *   // app/agent/register/route.ts
+ *   export const runtime = 'nodejs';
+ *   export const dynamic = 'force-dynamic';
+ *   export const POST = createRegisterHandler(getGate);
+ */
+export function createRegisterHandler(gateOrFactory) {
+    return async (req) => {
+        const gate = typeof gateOrFactory === 'function' ? await gateOrFactory() : gateOrFactory;
+        return toResponse(await gate.handle(await toNormalized(req)));
+    };
+}
+/**
+ * Authorize handler.
+ *
+ *   // app/agent/authorize/route.ts
+ *   export const runtime = 'nodejs';
+ *   export const dynamic = 'force-dynamic';
+ *   export const POST = createAuthorizeHandler(getGate);
+ */
+export function createAuthorizeHandler(gateOrFactory) {
+    return async (req) => {
+        const gate = typeof gateOrFactory === 'function' ? await gateOrFactory() : gateOrFactory;
+        return toResponse(await gate.handle(await toNormalized(req)));
+    };
+}
+/**
+ * Audit log handler. Gate behind your own auth in production (Clerk session,
+ * API key, etc.) — audit data is sensitive.
+ *
+ *   // app/agent/audit/route.ts
+ *   export const runtime = 'nodejs';
+ *   export const dynamic = 'force-dynamic';
+ *   export const GET = createAuditHandler(getGate);
+ */
+export function createAuditHandler(gateOrFactory) {
+    return async () => {
+        const gate = typeof gateOrFactory === 'function' ? await gateOrFactory() : gateOrFactory;
+        return new Response(JSON.stringify({ entries: gate.auditEntries() }), { headers: { 'content-type': 'application/json' } });
+    };
+}
+/**
+ * Catch-all dispatcher for all AgentPassport protocol endpoints.
+ *
+ * Mount this once and you don't need separate route files for register,
+ * authorize, audit, or the discovery doc. The gate routes internally based
+ * on the request URL.
+ *
+ * Two route files cover the four protocol surfaces:
+ *
+ *   // app/agent/[...agentauth]/route.ts
+ *   import { handleAgentPassport } from '@agentic-passport/next';
+ *   import { getGate } from '@/lib/agent-gate';
+ *   export const runtime = 'nodejs';
+ *   export const dynamic = 'force-dynamic';
+ *   export const GET = (r: Request) => handleAgentPassport(r, getGate);
+ *   export const POST = (r: Request) => handleAgentPassport(r, getGate);
+ *
+ *   // app/.well-known/agent-passport/route.ts
+ *   export const runtime = 'nodejs';
+ *   export const dynamic = 'force-dynamic';
+ *   export const GET = (r: Request) => handleAgentPassport(r, getGate);
+ *
+ * (Next.js does not allow a single catch-all to cover both `/agent/*` and
+ * `/.well-known/agent-passport` — the well-known route lives outside `/agent`.
+ * Two files; one line each.)
+ */
+export async function handleAgentPassport(req, gateOrFactory) {
+    const gate = typeof gateOrFactory === 'function' ? await gateOrFactory() : gateOrFactory;
+    return toResponse(await gate.handle(await toNormalized(req)));
+}
+/**
+ * Wrap a vendor API route handler so it verifies the agent's signed request +
+ * DPoP-bound access token + required scope before running. The wrapped handler
+ * receives the verified principal as its second argument.
+ *
+ *   // app/api/keyword-search/route.ts  (or whatever the vendor's endpoint is)
+ *   export const runtime = 'nodejs';
+ *   export const dynamic = 'force-dynamic';
+ *
+ *   export async function GET(req: NextRequest) {
+ *     if (isAgentRequest({ headers: Object.fromEntries(req.headers) })) {
+ *       return withAgent(getGate, 'keyword.search', async (r, principal) => {
+ *         return Response.json(await searchKeywords(r, principal.agentId));
+ *       })(req);
+ *     }
+ *     // Existing human flow stays exactly as-is:
+ *     const { userId } = await auth();
+ *     if (!userId) return new Response('unauthorized', { status: 401 });
+ *     return Response.json(await searchKeywords(req, userId));
+ *   }
+ */
+export function withAgent(gateOrFactory, requiredScope, handler) {
+    return async (req) => {
+        const gate = typeof gateOrFactory === 'function' ? await gateOrFactory() : gateOrFactory;
+        const normalized = await toNormalized(req);
+        const result = await gate.authorizeApiCall(normalized, requiredScope);
+        if (!result.ok) {
+            const status = result.code === 'SCOPE_NOT_GRANTED' ? 403 : 401;
+            const headers = { 'content-type': 'application/json' };
+            if (status === 401) {
+                const origin = gate.config.vendorOrigin.replace(/\/$/, '');
+                headers['www-authenticate'] = [
+                    'AgentPassport',
+                    `realm="${origin}"`,
+                    `discovery="${origin}/.well-known/agent-passport"`,
+                    `quickstart="${origin}/.well-known/agent-passport/quickstart.md"`,
+                    `spec="${origin}/.well-known/agent-passport/spec.md"`,
+                ].join(' ');
+            }
+            return new Response(JSON.stringify({ error: 'agent_passport_error', error_code: result.code }), { status, headers });
+        }
+        const value = await handler(req, {
+            agentId: result.principal.agentId,
+            scopes: result.principal.scopes,
+            mandateJti: result.principal.mandateJti,
+        });
+        if (value instanceof Response)
+            return value;
+        return new Response(JSON.stringify(value), { headers: { 'content-type': 'application/json' } });
+    };
+}
+/**
+ * Resolve the request's principal — agent OR human OR none — without
+ * bridging cookies. This is the recommended way to write a vendor route
+ * that should be reachable by both.
+ *
+ * Behavior:
+ *   1. Agent path. If the request carries AgentPassport headers (signature
+ *      + DPoP-bound token), verify them via `gate.authorizeApiCall` and
+ *      return an `AgentSessionPrincipal`. Scope is verified iff
+ *      `opts.requireScope` is provided.
+ *   2. Human path. If not an agent, and `opts.humanAuth` is provided,
+ *      call it. If it returns `{ userId }`, return a `HumanSessionPrincipal`.
+ *   3. Otherwise return null.
+ *
+ *   // app/api/account/route.ts
+ *   import { getSession } from '@agentic-passport/next';
+ *   import { auth } from '@clerk/nextjs/server';
+ *
+ *   export async function GET(req: Request) {
+ *     const principal = await getSession(req, {
+ *       gate: getGate,
+ *       humanAuth: async () => {
+ *         const { userId } = await auth();
+ *         return userId ? { userId } : null;
+ *       },
+ *     });
+ *     if (!principal) return new Response('unauthorized', { status: 401 });
+ *     // Same code path for agent and human. Branch only if you need to:
+ *     //   if (principal.type === 'agent') ...
+ *     return Response.json({ user: principal.userId });
+ *   }
+ */
+export async function getSession(req, opts) {
+    const headersRecord = {};
+    req.headers.forEach((v, k) => { headersRecord[k.toLowerCase()] = v; });
+    const looksLikeAgent = !!(headersRecord['signature'] && headersRecord['signature-agent']);
+    if (looksLikeAgent) {
+        const gate = typeof opts.gate === 'function' ? await opts.gate() : opts.gate;
+        const normalized = await toNormalized(req);
+        const result = await gate.authorizeApiCall(normalized, opts.requireScope ?? null);
+        if (!result.ok)
+            return null;
+        // Resolve the agent's vendor-side userId from the gate's store.
+        const agentRecord = await gate.store.getAgent(result.principal.agentId);
+        const userId = agentRecord?.user_id ?? `shadow:${result.principal.agentId}`;
+        return {
+            type: 'agent',
+            userId,
+            agentId: result.principal.agentId,
+            scopes: result.principal.scopes,
+            mandateJti: result.principal.mandateJti,
+        };
+    }
+    if (opts.humanAuth) {
+        const human = await opts.humanAuth();
+        if (human)
+            return { type: 'human', userId: human.userId };
+    }
+    return null;
+}
+//# sourceMappingURL=next-adapter.js.map

package/dist/next-adapter.js.map

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

package/dist/stores.d.ts

@@ -0,0 +1,35 @@
+/**
+ * State store implementations.
+ *   - inMemoryStore() — default; per-instance Map-backed; fine for tests + single-isolate dev
+ *   - kvStore(kv)     — Cloudflare Workers KV-backed; works across isolates
+ */
+import type { AgentStateStore } from './types.js';
+export declare function inMemoryStore(): AgentStateStore;
+/** Minimal KV shape we depend on. Cloudflare's KVNamespace satisfies it. */
+export interface MinimalKV {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, opts?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+}
+type KvStoreOpts = {
+    /** Used for keys + agents + revocation list (persistent across requests). */
+    state: MinimalKV;
+    /** Used for nonces, mandate jtis, dpop jtis, rate-limit counters (short-lived). */
+    cache?: MinimalKV;
+};
+/**
+ * KV-backed state store. Use on Cloudflare Workers / Pages.
+ *
+ * Two namespaces are recommended:
+ *   - state: persistent (keys, agents, revocation)
+ *   - cache: ephemeral (nonces, jtis, rate-limit) — falls back to `state` if omitted
+ *
+ * Limits to be aware of:
+ *   - KV writes are eventually consistent (≤60s globally). v0 demo: same-region requests
+ *     usually see fresh writes within ~1s. For multi-region production, consider Durable Objects.
+ *   - Each operation = 1 KV op = real cost / rate limit.
+ */
+export declare function kvStore(opts: KvStoreOpts): AgentStateStore;
+export {};
+//# sourceMappingURL=stores.d.ts.map

package/dist/stores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.d.ts","sourceRoot":"","sources":["../src/stores.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,YAAY,CAAC;AAM/D,wBAAgB,aAAa,IAAI,eAAe,CA+D/C;AAID,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnF;AAED,KAAK,WAAW,GAAG;IACjB,6EAA6E;IAC7E,KAAK,EAAE,SAAS,CAAC;IACjB,mFAAmF;IACnF,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB,CAAC;AAYF;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,CA0E1D"}