@adcp/sdk 6.6.0 → 6.7.0

package/dist/lib/signing/agent-resolver/index.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Brand-JSON-URL agent resolver — bootstraps from an agent URL to its
+ * signing keys via the 8-step algorithm in `security.mdx` §"Discovering
+ * an agent's signing keys via `brand_json_url`".
+ *
+ * Public exports for `@adcp/client`:
+ *
+ *   - `resolveAgent(url, opts)`       — full chain + per-step trace
+ *   - `getAgentJwks(url, opts)`       — JWKS-only fast path (stage 4)
+ *   - `createAgentJwksSet(url, opts)` — JOSE-compatible JWTVerifyGetKey factory (stage 4)
+ *   - `AgentResolverError`            — typed error with `request_signature_*` codes
+ *   - `attackerInfluencedFields`      — names of `detail` fields admin UIs MUST escape
+ *
+ * Pure-function primitives (`eTldPlusOne`, `canonicalizeOrigin`,
+ * `selectAgentByUrl`, etc.) are exported under `agent-resolver/primitives`
+ * for callers building bespoke verification flows on top of this module.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readIdentityPosture = exports.readBrandJsonUrl = exports.attackerInfluencedFields = exports.ATTACKER_INFLUENCED = exports.AgentResolverError = exports.createAgentJwksSet = exports.getAgentJwks = exports.resolveAgent = void 0;
+var resolve_agent_1 = require("./resolve-agent");
+Object.defineProperty(exports, "resolveAgent", { enumerable: true, get: function () { return resolve_agent_1.resolveAgent; } });
+var jwks_set_1 = require("./jwks-set");
+Object.defineProperty(exports, "getAgentJwks", { enumerable: true, get: function () { return jwks_set_1.getAgentJwks; } });
+Object.defineProperty(exports, "createAgentJwksSet", { enumerable: true, get: function () { return jwks_set_1.createAgentJwksSet; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "AgentResolverError", { enumerable: true, get: function () { return errors_1.AgentResolverError; } });
+Object.defineProperty(exports, "ATTACKER_INFLUENCED", { enumerable: true, get: function () { return errors_1.ATTACKER_INFLUENCED; } });
+Object.defineProperty(exports, "attackerInfluencedFields", { enumerable: true, get: function () { return errors_1.attackerInfluencedFields; } });
+var capabilities_types_1 = require("./capabilities-types");
+Object.defineProperty(exports, "readBrandJsonUrl", { enumerable: true, get: function () { return capabilities_types_1.readBrandJsonUrl; } });
+Object.defineProperty(exports, "readIdentityPosture", { enumerable: true, get: function () { return capabilities_types_1.readIdentityPosture; } });
+//# sourceMappingURL=index.js.map

package/dist/lib/signing/agent-resolver/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAEH,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AAQrB,uCAA8D;AAArD,wGAAA,YAAY,OAAA;AAAE,8GAAA,kBAAkB,OAAA;AAEzC,mCAMkB;AALhB,4GAAA,kBAAkB,OAAA;AAClB,6GAAA,mBAAmB,OAAA;AACnB,kHAAA,wBAAwB,OAAA;AAW1B,2DAA6E;AAApE,sHAAA,gBAAgB,OAAA;AAAE,yHAAA,mBAAmB,OAAA"}

package/dist/lib/signing/agent-resolver/jwks-set.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Convenience surfaces over `resolveAgent`:
+ *
+ *   - `getAgentJwks(url, opts)` — JWKS-only fast path. Skips the trace
+ *     assembly the full resolver returns; callers who only need keys for
+ *     a verifier don't have to filter the larger record.
+ *
+ *   - `createAgentJwksSet(url, opts)` — returns a `JWTVerifyGetKey`-shaped
+ *     async function compatible with `jose.jwtVerify`'s `getKey` parameter.
+ *     Caches the resolved JWKS per `cacheMaxAgeSeconds`; refetches on a
+ *     `kid` miss subject to the spec's 30-second cooldown
+ *     (security.mdx §"Verifier checklist (requests)" step 7's refetch
+ *     guidance). Enforces the caller-supplied algorithm allowlist at JWKS
+ *     import time AND on the verify call — defense-in-depth against the
+ *     "alg: HS256" confusion vector. The allowlist is REQUIRED; there is
+ *     no library default.
+ */
+import { type JWTVerifyGetKey } from 'jose';
+import { type ResolveAgentOptions } from './resolve-agent';
+export type GetAgentJwksOptions = Pick<ResolveAgentOptions, 'protocol' | 'fetchCapabilities' | 'allowPrivateIp' | 'timeoutMs' | 'now'>;
+export interface AgentJwksResult {
+    agentUrl: string;
+    brandJsonUrl: string;
+    jwksUri: string;
+    jwks: {
+        keys: ReadonlyArray<Record<string, unknown>>;
+    };
+    cacheControl?: string;
+    fetchedAt: number;
+}
+/**
+ * Fast path: returns the JWKS plus the URIs that produced it. Skips the
+ * trace + freshness aggregate the full `resolveAgent` returns. Errors
+ * propagate as `AgentResolverError` with the same `request_signature_*`
+ * codes — the JWKS fast path is not a separate trust chain.
+ */
+export declare function getAgentJwks(agentUrl: string, options?: GetAgentJwksOptions): Promise<AgentJwksResult>;
+export interface CreateAgentJwksSetOptions extends Pick<ResolveAgentOptions, 'protocol' | 'fetchCapabilities' | 'allowPrivateIp' | 'timeoutMs' | 'now'> {
+    /**
+     * Algorithm allowlist enforced at JWKS-import time AND surfaced to
+     * `jose.jwtVerify`'s `algorithms` option. Required — there is no default.
+     * The classic confusion vector is `alg: HS256` against a public-key JWK,
+     * which jose's verifier would reject — but a library that pre-imports
+     * keys without an allowlist still leaves the door open to JWKs whose
+     * declared `alg` doesn't match the verifier's expectation. Requiring the
+     * caller to name the algorithms closes the door at every layer.
+     *
+     * Use a tight set: `["EdDSA"]` for Ed25519-only deployments;
+     * `["EdDSA", "ES256"]` for the AdCP request-signing default pair.
+     */
+    allowedAlgs: readonly string[];
+    /**
+     * Max age in seconds before a forced refetch of the JWKS. Default 300s
+     * (5 minutes). Bound this above by your operator's revocation polling
+     * interval — a longer cache mask key rotation; a shorter cache costs
+     * extra fetches without buying you anything.
+     */
+    cacheMaxAgeSeconds?: number;
+    /**
+     * Minimum interval between JWKS refetches when a `kid` miss triggers a
+     * refresh. Default 30s — matches the spec's cooldown rule for the
+     * verifier checklist's step-7 refetch.
+     */
+    kidMissCooldownSeconds?: number;
+}
+/**
+ * Build a `JWTVerifyGetKey` that runs the brand_json_url discovery chain on
+ * first use, caches the resolved JWKS, refetches on cache expiry, and
+ * refetches once on a `kid` miss subject to a 30s cooldown. Imports each
+ * JWK and rejects any whose `alg` (when declared) is outside `allowedAlgs`.
+ *
+ * The returned function is compatible with `jose.jwtVerify` — pass it as
+ * `getKey` and pair with `algorithms: opts.allowedAlgs` on the verify call.
+ */
+export declare function createAgentJwksSet(agentUrl: string, options: CreateAgentJwksSetOptions): JWTVerifyGetKey;
+//# sourceMappingURL=jwks-set.d.ts.map

package/dist/lib/signing/agent-resolver/jwks-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks-set.d.ts","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/jwks-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAA+B,KAAK,eAAe,EAAE,MAAM,MAAM,CAAC;AAGzE,OAAO,EAAsC,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE/F,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,mBAAmB,EACnB,UAAU,GAAG,mBAAmB,GAAG,gBAAgB,GAAG,WAAW,GAAG,KAAK,CAC1E,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE;QAAE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,eAAe,CAAC,CAUhH;AAED,MAAM,WAAW,yBAA0B,SAAQ,IAAI,CACrD,mBAAmB,EACnB,UAAU,GAAG,mBAAmB,GAAG,gBAAgB,GAAG,WAAW,GAAG,KAAK,CAC1E;IACC;;;;;;;;;;;OAWG;IACH,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAYD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,GAAG,eAAe,CAqDxG"}

package/dist/lib/signing/agent-resolver/jwks-set.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Convenience surfaces over `resolveAgent`:
+ *
+ *   - `getAgentJwks(url, opts)` — JWKS-only fast path. Skips the trace
+ *     assembly the full resolver returns; callers who only need keys for
+ *     a verifier don't have to filter the larger record.
+ *
+ *   - `createAgentJwksSet(url, opts)` — returns a `JWTVerifyGetKey`-shaped
+ *     async function compatible with `jose.jwtVerify`'s `getKey` parameter.
+ *     Caches the resolved JWKS per `cacheMaxAgeSeconds`; refetches on a
+ *     `kid` miss subject to the spec's 30-second cooldown
+ *     (security.mdx §"Verifier checklist (requests)" step 7's refetch
+ *     guidance). Enforces the caller-supplied algorithm allowlist at JWKS
+ *     import time AND on the verify call — defense-in-depth against the
+ *     "alg: HS256" confusion vector. The allowlist is REQUIRED; there is
+ *     no library default.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAgentJwks = getAgentJwks;
+exports.createAgentJwksSet = createAgentJwksSet;
+const jose_1 = require("jose");
+const errors_1 = require("./errors");
+const resolve_agent_1 = require("./resolve-agent");
+/**
+ * Fast path: returns the JWKS plus the URIs that produced it. Skips the
+ * trace + freshness aggregate the full `resolveAgent` returns. Errors
+ * propagate as `AgentResolverError` with the same `request_signature_*`
+ * codes — the JWKS fast path is not a separate trust chain.
+ */
+async function getAgentJwks(agentUrl, options = {}) {
+    const resolution = await (0, resolve_agent_1.resolveAgent)(agentUrl, options);
+    return {
+        agentUrl: resolution.agentUrl,
+        brandJsonUrl: resolution.brandJsonUrl,
+        jwksUri: resolution.jwksUri,
+        jwks: resolution.jwks,
+        ...(resolution.jwksCacheControl !== undefined && { cacheControl: resolution.jwksCacheControl }),
+        fetchedAt: resolution.freshness.jwksFetchedAt,
+    };
+}
+const DEFAULT_CACHE_MAX_AGE_SECONDS = 300;
+const DEFAULT_KID_MISS_COOLDOWN_SECONDS = 30;
+/**
+ * Build a `JWTVerifyGetKey` that runs the brand_json_url discovery chain on
+ * first use, caches the resolved JWKS, refetches on cache expiry, and
+ * refetches once on a `kid` miss subject to a 30s cooldown. Imports each
+ * JWK and rejects any whose `alg` (when declared) is outside `allowedAlgs`.
+ *
+ * The returned function is compatible with `jose.jwtVerify` — pass it as
+ * `getKey` and pair with `algorithms: opts.allowedAlgs` on the verify call.
+ */
+function createAgentJwksSet(agentUrl, options) {
+    if (!options.allowedAlgs || options.allowedAlgs.length === 0) {
+        throw new TypeError(`createAgentJwksSet requires non-empty allowedAlgs — refusing to verify against an open algorithm set`);
+    }
+    const allowedAlgs = new Set(options.allowedAlgs);
+    const cacheMaxAge = options.cacheMaxAgeSeconds ?? DEFAULT_CACHE_MAX_AGE_SECONDS;
+    const kidCooldown = options.kidMissCooldownSeconds ?? DEFAULT_KID_MISS_COOLDOWN_SECONDS;
+    const now = options.now ?? (() => Math.floor(Date.now() / 1000));
+    let cache;
+    let lastRefetchAt = 0;
+    let inFlight;
+    const refresh = async () => {
+        if (inFlight)
+            return inFlight;
+        inFlight = (async () => {
+            const resolution = await (0, resolve_agent_1.resolveAgent)(agentUrl, options);
+            assertAllJwksAllowed(resolution.jwks, allowedAlgs, agentUrl);
+            const filtered = filterJwksToAllowedAlgs(resolution.jwks, allowedAlgs);
+            const getKey = (0, jose_1.createLocalJWKSet)({ keys: filtered });
+            cache = { resolution, fetchedAt: now(), getKey };
+            lastRefetchAt = cache.fetchedAt;
+            return cache;
+        })().finally(() => {
+            inFlight = undefined;
+        });
+        return inFlight;
+    };
+    const ensureFresh = async () => {
+        if (!cache || now() - cache.fetchedAt >= cacheMaxAge) {
+            return refresh();
+        }
+        return cache;
+    };
+    const getKey = async (protectedHeader, token) => {
+        const fresh = await ensureFresh();
+        try {
+            return await fresh.getKey(protectedHeader, token);
+        }
+        catch (err) {
+            // Likely cause: kid miss (key rotated). Subject to the cooldown,
+            // refetch once and retry — same logic the spec's verifier checklist
+            // applies between the agent-URL preamble and the kid resolution.
+            if (now() - lastRefetchAt < kidCooldown)
+                throw err;
+            const refreshed = await refresh();
+            return refreshed.getKey(protectedHeader, token);
+        }
+    };
+    return getKey;
+}
+/**
+ * Reject every JWK whose declared `alg` is outside the allowlist. This is
+ * the import-time half of the defense-in-depth pair against alg-confusion
+ * attacks; the verify-time half is the caller passing `algorithms` to
+ * `jose.jwtVerify`. Malformed-JWK detection is left to `createLocalJWKSet`
+ * + `jose.jwtVerify` at verify time — running an async smoke-import here
+ * would be fire-and-forget and swallow rejections.
+ */
+function assertAllJwksAllowed(jwks, allowedAlgs, agentUrl) {
+    for (const jwk of jwks.keys) {
+        const declared = jwk.alg;
+        if (typeof declared === 'string' && !allowedAlgs.has(declared)) {
+            throw new errors_1.AgentResolverError('request_signature_jwks_alg_disallowed', `Agent JWKS contains key with alg=${declared} not in allowedAlgs`, { agent_url: agentUrl }, ['agent_url']);
+        }
+    }
+}
+function filterJwksToAllowedAlgs(jwks, allowedAlgs) {
+    // Keep keys without a declared `alg` (jose still gates by the verifier's
+    // `algorithms` option) and keys whose declared `alg` is in the allowlist.
+    return jwks.keys.filter(jwk => typeof jwk.alg !== 'string' || allowedAlgs.has(jwk.alg));
+}
+//# sourceMappingURL=jwks-set.js.map

package/dist/lib/signing/agent-resolver/jwks-set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks-set.js","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/jwks-set.ts"],"names":[],"mappings":"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"}

package/dist/lib/signing/agent-resolver/resolve-agent.d.ts

@@ -0,0 +1,123 @@
+/**
+ * `resolveAgent` — implementation of the 8-step brand_json_url discovery
+ * algorithm defined in `security.mdx` §"Discovering an agent's signing
+ * keys via `brand_json_url`". Given an agent URL `A` and (optionally)
+ * the protocol it speaks, returns the resolved brand.json document, the
+ * matched `agents[]` entry, the JWKS URI, the JWKS itself, and a per-step
+ * trace.
+ *
+ * Composition with existing pieces:
+ *   - Step 1 (capabilities fetch) goes through `ProtocolClient` via the
+ *     `createMCPClient` / `createA2AClient` factories — never a raw HTTP
+ *     GET on the agent URL. The spec is explicit: the agent URL is the
+ *     protocol endpoint, not a JSON capabilities document.
+ *   - Steps 4 / 8 (brand.json / JWKS fetches) go through `ssrfSafeFetch`
+ *     with `maxRedirects: 0` (the spec forbids redirects on the
+ *     bootstrap fetch — the `authoritative_location` carve-out is scoped
+ *     to webhook receivers and MUST NOT be inherited here) and the
+ *     strict-JSON parser (duplicate-key + prototype-property rejection).
+ *
+ * Error mapping:
+ *   - All wire-shape rejections surface as `AgentResolverError` with a
+ *     `request_signature_*` code matching the spec's rejection-code table.
+ *   - Counterparty-controlled detail fields (`brand_json_url`,
+ *     `matched_entries`, `parse_error`) are marked
+ *     `attackerInfluencedFields` so admin-UI renderers know to escape.
+ *   - SSRF refusals translate to a coarse `dns_error` classification —
+ *     never the resolved IP or hostname-to-address mapping the underlying
+ *     `SsrfRefusedError` carries.
+ */
+import type { IdentityKeyOriginPurpose, IdentityPosture } from './capabilities-types';
+import { type ConsistencyResult } from './consistency';
+import { type AgentResolverErrorDetail } from './errors';
+import { type AgentEntry } from './select-agent';
+export type AgentProtocol = 'mcp' | 'a2a';
+export interface FetchCapabilitiesFn {
+    (agentUrl: string): Promise<unknown>;
+}
+export interface ResolveAgentOptions {
+    /** Default `'mcp'`. Ignored when `fetchCapabilities` is supplied. */
+    protocol?: AgentProtocol;
+    /**
+     * Override the capabilities-fetch step entirely. Tests pass a fake; production
+     * callers who already hold a configured protocol client can wire it through
+     * here rather than letting the resolver build a fresh transport.
+     */
+    fetchCapabilities?: FetchCapabilitiesFn;
+    /**
+     * Allow `http://` and private/loopback targets. Default false.
+     *
+     * Refused outside `{NODE_ENV=test, NODE_ENV=development}` unless the
+     * adopter sets `ADCP_RESOLVER_ALLOW_PRIVATE_IP=1` as an explicit ops
+     * acknowledgment — a security-critical entry point should fail closed
+     * when the carve-out gets wired from a misconfigured env var. Matches
+     * the project pattern around `createAdcpServer`'s in-memory-state and
+     * `tenant-registry`'s NODE_ENV allowlist.
+     */
+    allowPrivateIp?: boolean;
+    /**
+     * Body caps for the brand.json + JWKS fetches. Default: brand.json 256 KiB,
+     * JWKS 64 KiB — the budgets recommended by `security.mdx` §"Quickstart".
+     * The capabilities-fetch cap is enforced upstream by `ProtocolClient`'s
+     * own response-size limit; it is not configurable here.
+     */
+    bodyCaps?: {
+        brandJsonBytes?: number;
+        jwksBytes?: number;
+    };
+    /** Total per-fetch timeout in ms. Default 10_000. */
+    timeoutMs?: number;
+    /**
+     * Purposes the caller knows the agent is signing for but that aren't
+     * inferable from a generic capabilities walk (governance-signing,
+     * TMP-signing). Joined with the auto-detected set before the
+     * `key_origins` missing check.
+     */
+    declaredPurposes?: readonly IdentityKeyOriginPurpose[];
+    /**
+     * Sell-side webhook publisher pin marker — when `webhook_signing` is
+     * `true`, the step-7 origin-consistency check is skipped for the
+     * webhook-signing purpose only (operator-side webhook-signing remains
+     * checked). Buyer-side / receive-side verifiers MUST leave this unset.
+     */
+    publisherPinned?: {
+        webhook_signing?: boolean;
+    };
+    /** Override the current time (epoch seconds) — for deterministic tests. */
+    now?: () => number;
+}
+export interface TraceStep {
+    step: number;
+    name: string;
+    ok: boolean;
+    fetchedAt?: number;
+    ageSeconds?: number;
+    url?: string;
+    detail?: Record<string, unknown> | AgentResolverErrorDetail;
+}
+export interface AgentResolution {
+    agentUrl: string;
+    brandJsonUrl: string;
+    agentEntry: AgentEntry;
+    jwksUri: string;
+    jwks: {
+        keys: ReadonlyArray<Record<string, unknown>>;
+    };
+    identityPosture: IdentityPosture | undefined;
+    consistency: {
+        ok: true;
+    } | {
+        ok: false;
+        results: ReadonlyArray<ConsistencyResult>;
+    };
+    freshness: {
+        capabilitiesFetchedAt: number;
+        brandJsonFetchedAt: number;
+        jwksFetchedAt: number;
+    };
+    /** `Cache-Control` header from the JWKS fetch, when the response carried one. */
+    jwksCacheControl?: string;
+    trace: ReadonlyArray<TraceStep>;
+}
+export declare function resolveAgent(agentUrl: string, options?: ResolveAgentOptions): Promise<AgentResolution>;
+//# sourceMappingURL=resolve-agent.d.ts.map

package/dist/lib/signing/agent-resolver/resolve-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-agent.d.ts","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/resolve-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAK,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGtF,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAsB,KAAK,wBAAwB,EAAE,MAAM,UAAU,CAAC;AAI7E,OAAO,EAAE,KAAK,UAAU,EAAwC,MAAM,gBAAgB,CAAC;AAEvF,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,KAAK,CAAC;AAE1C,MAAM,WAAW,mBAAmB;IAClC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACvD;;;;;OAKG;IACH,eAAe,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAChD,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,wBAAwB,CAAC;CAC7D;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE;QAAE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;IACvD,eAAe,EAAE,eAAe,GAAG,SAAS,CAAC;IAC7C,WAAW,EACP;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GACZ;QACE,EAAE,EAAE,KAAK,CAAC;QACV,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;KAC3C,CAAC;IACN,SAAS,EAAE;QACT,qBAAqB,EAAE,MAAM,CAAC;QAC9B,kBAAkB,EAAE,MAAM,CAAC;QAC3B,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;CACjC;AAID,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,eAAe,CAAC,CAwShH"}