@adcp/sdk 5.23.0

package/dist/lib/auth/oauth/authorization-required.js

@@ -0,0 +1,363 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NeedsAuthorizationError = void 0;
+exports.discoverAuthorizationRequirements = discoverAuthorizationRequirements;
+/**
+ * Zero-config OAuth discovery + actionable authorization errors.
+ *
+ * When a library consumer calls an OAuth-gated MCP agent without saved
+ * credentials, they get a `NeedsAuthorizationError` containing everything
+ * needed to either run an interactive flow or present a clear prompt — no
+ * re-probing required.
+ *
+ * Design note: this module only *discovers* — it never opens a browser or
+ * writes state. Interactive flow handling stays in the caller (CLI or a
+ * bespoke `OAuthFlowHandler`) so library behavior is predictable.
+ */
+const net_1 = require("../../net");
+const errors_1 = require("../../errors");
+const diagnostics_1 = require("./diagnostics");
+/**
+ * Maximum length of an individual server-supplied string we copy into the
+ * `AuthorizationRequirements` payload. Anything longer is truncated with a
+ * `…` suffix so hostile agents can't smuggle megabyte error-descriptions
+ * into operator-facing prompts and logs.
+ */
+const MAX_DISPLAY_STRING = 256;
+/**
+ * Maximum number of scope strings we copy into `scopesSupported`. RFC 8414
+ * allows an unbounded array; hostile servers have sent thousands.
+ */
+const MAX_SCOPES = 64;
+/**
+ * Maximum number of auth-params we preserve under `challenge.params`. Bounds
+ * memory pressure from hostile servers that pack the `WWW-Authenticate`
+ * header with unknown auth-params.
+ */
+const MAX_CHALLENGE_PARAMS = 32;
+/**
+ * Strip ASCII control characters (excluding TAB) from a server-supplied
+ * string that may be shown to a human. Defeats terminal-hijack tricks like
+ * `\x1b]0;pwned\x07` (rewrites terminal title), `\r` (overwrites prompt),
+ * and `\x1b[2J` (clears screen). Also truncates over-long values.
+ */
+function sanitizeDisplay(value) {
+    const stripped = value.replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
+    if (stripped.length <= MAX_DISPLAY_STRING)
+        return stripped;
+    return `${stripped.slice(0, MAX_DISPLAY_STRING - 1)}…`;
+}
+/**
+ * Sanitize the parsed `WWW-Authenticate` challenge before embedding it in a
+ * `NeedsAuthorizationError`. Consumers that render `requirements.challenge`
+ * to a terminal should never see control characters. Caps `params` count to
+ * bound hostile servers.
+ *
+ * The `scheme` is already lowercased + token-constrained by the parser.
+ * Param keys are also token-constrained so they're safe; only values need
+ * sanitizing.
+ */
+function sanitizeChallenge(c) {
+    const params = {};
+    for (const [k, v] of Object.entries(c.params)) {
+        if (Object.keys(params).length >= MAX_CHALLENGE_PARAMS)
+            break;
+        params[k] = sanitizeDisplay(v);
+    }
+    return {
+        scheme: c.scheme,
+        ...(c.realm !== undefined ? { realm: sanitizeDisplay(c.realm) } : {}),
+        ...(c.error !== undefined ? { error: sanitizeDisplay(c.error) } : {}),
+        ...(c.error_description !== undefined ? { error_description: sanitizeDisplay(c.error_description) } : {}),
+        ...(c.scope !== undefined ? { scope: sanitizeDisplay(c.scope) } : {}),
+        ...(c.resource_metadata !== undefined ? { resource_metadata: sanitizeDisplay(c.resource_metadata) } : {}),
+        params,
+    };
+}
+/**
+ * Error raised when an agent returns a 401 and we do not have credentials
+ * to satisfy it. Carries everything needed to run an interactive OAuth flow
+ * or show the operator an actionable prompt.
+ *
+ * Extends {@link AuthenticationRequiredError} so existing callers that catch
+ * `AuthenticationRequiredError` automatically receive the richer variant —
+ * they can downcast with `instanceof NeedsAuthorizationError` when they
+ * want walked discovery metadata.
+ *
+ * Note on `code` vs `subCode`:
+ *   The parent class declares `readonly code = 'AUTHENTICATION_REQUIRED'` as
+ *   a class field that re-initializes on every construction, so a child-side
+ *   override attempt is silently overwritten under `useDefineForClassFields`.
+ *   The narrow discriminator is exposed as `subCode` — prefer
+ *   `instanceof NeedsAuthorizationError` for type-narrowing and use `subCode`
+ *   only for structured-log keying.
+ *
+ * Note on `hasOAuth`:
+ *   The inherited getter returns `true` only when both `authorization_endpoint`
+ *   and `token_endpoint` were walked successfully. A partially-walked
+ *   requirements record (PRM reachable but AS metadata missing) still yields
+ *   `hasOAuth === false` even though `requirements.authorizationServer` is set.
+ *   Treat it as "we have enough to start a flow," not "server wants OAuth."
+ */
+class NeedsAuthorizationError extends errors_1.AuthenticationRequiredError {
+    /** Narrow discriminator for consumers that already know about this class. */
+    subCode = 'needs_authorization';
+    requirements;
+    constructor(requirements, message) {
+        super(requirements.agentUrl, synthesizeOAuthMetadata(requirements), message ?? defaultMessage(requirements));
+        this.name = 'NeedsAuthorizationError';
+        this.requirements = requirements;
+        // Extend the parent's `details` payload so structured-logging consumers
+        // that read `err.details` (via `extractErrorInfo` or equivalent) see the
+        // full walked chain, not just the synthesized one-hop oauthMetadata.
+        this.details = { ...this.details, requirements };
+    }
+}
+exports.NeedsAuthorizationError = NeedsAuthorizationError;
+/**
+ * Build an {@link OAuthMetadataInfo} for the base-class constructor so that
+ * legacy callers still see a non-empty `oauthMetadata` + working
+ * `hasOAuth`/`authorizationUrl` getters on the error. When discovery didn't
+ * yield enough info, return undefined and let the base class degrade
+ * gracefully.
+ */
+function synthesizeOAuthMetadata(req) {
+    if (!req.authorizationEndpoint || !req.tokenEndpoint)
+        return undefined;
+    return {
+        authorization_endpoint: req.authorizationEndpoint,
+        token_endpoint: req.tokenEndpoint,
+        ...(req.registrationEndpoint ? { registration_endpoint: req.registrationEndpoint } : {}),
+        ...(req.authorizationServer ? { issuer: req.authorizationServer } : {}),
+    };
+}
+function defaultMessage(req) {
+    const parts = [`Agent ${sanitizeDisplay(req.agentUrl)} requires OAuth authorization.`];
+    if (req.authorizationServer) {
+        parts.push(`Authorization server: ${req.authorizationServer}.`);
+    }
+    if (req.challenge.error_description) {
+        parts.push(`Server said: ${sanitizeDisplay(req.challenge.error_description)}.`);
+    }
+    parts.push('Provide an OAuthFlowHandler or run an interactive flow to complete authorization.');
+    return parts.join(' ');
+}
+/**
+ * Walk the OAuth discovery chain starting from an agent URL. Returns
+ * `AuthorizationRequirements` when the agent demands OAuth, or `null` when a
+ * `tools/list` call succeeds without credentials.
+ *
+ * Strategy:
+ *   1. POST `tools/list` to the agent with no `Authorization` header.
+ *   2. If 401 + `WWW-Authenticate: Bearer`: parse the challenge.
+ *   3. If the challenge carries `resource_metadata=…`: GET it and read
+ *      `resource` + `authorization_servers`.
+ *   4. For the first `authorization_servers[0]`: GET `/.well-known/oauth-authorization-server`
+ *      and read `authorization_endpoint`, `token_endpoint`, `registration_endpoint`,
+ *      `scopes_supported`.
+ *   5. Return a structured record.
+ *
+ * Anything missing from the chain surfaces as `undefined` on the result —
+ * callers can still present a partial picture without re-probing.
+ */
+async function discoverAuthorizationRequirements(agentUrl, options = {}) {
+    // `allowPrivateIp` authorizes the agent probe. Chain hops (PRM, AS
+    // metadata) inherit that trust ONLY when they share the agent's origin —
+    // a compromised agent that advertises a private-IP authorization server
+    // on a different origin would otherwise pivot a discovery walk into the
+    // host's internal network.
+    const allowPrivateIpOnAgent = options.allowPrivateIp ?? false;
+    const agentOrigin = originOf(agentUrl);
+    const allowPrivateIpForHop = (url) => allowPrivateIpOnAgent && agentOrigin !== undefined && originOf(url) === agentOrigin;
+    let challengeHeader = options.wwwAuthenticate;
+    if (!challengeHeader) {
+        const probe = await probeAgent401(agentUrl, allowPrivateIpOnAgent, options.timeoutMs);
+        if (probe.status !== 401) {
+            // 200, 403, 5xx, or network error — not an OAuth 401 we can act on.
+            return null;
+        }
+        challengeHeader = probe.wwwAuthenticate;
+    }
+    const challenge = (0, diagnostics_1.parseWWWAuthenticate)(challengeHeader ?? null);
+    if (!challenge || challenge.scheme !== 'bearer') {
+        // A 401 without a Bearer challenge isn't our kind of problem — let it propagate.
+        return null;
+    }
+    const requirements = {
+        agentUrl,
+        resourceMetadataUrl: challenge.resource_metadata ? sanitizeDisplay(challenge.resource_metadata) : undefined,
+        challengeScope: challenge.scope ? sanitizeDisplay(challenge.scope) : undefined,
+        challenge: sanitizeChallenge(challenge),
+    };
+    // Walk protected-resource metadata (RFC 9728 §3). Private-IP targets are
+    // only allowed when the hop's origin matches the agent's.
+    if (challenge.resource_metadata && isSafeHttpUrl(challenge.resource_metadata)) {
+        const prm = await fetchJson(challenge.resource_metadata, allowPrivateIpForHop(challenge.resource_metadata), options.timeoutMs);
+        if (prm && typeof prm === 'object') {
+            const resource = prm.resource;
+            const servers = prm.authorization_servers;
+            if (typeof resource === 'string')
+                requirements.resource = sanitizeDisplay(resource);
+            if (Array.isArray(servers)) {
+                const validServers = servers
+                    .filter((s) => typeof s === 'string' && isSafeHttpUrl(s))
+                    .map(sanitizeDisplay);
+                if (validServers.length > 0) {
+                    requirements.authorizationServers = validServers;
+                    requirements.authorizationServer = validServers[0];
+                }
+            }
+        }
+    }
+    // Walk authorization-server metadata using the first issuer. RFC 8414 §3
+    // first, then OIDC Discovery 1.0 fallback for AS deployments (Keycloak in
+    // OIDC mode, Ping, ADFS) that only publish at
+    // `{issuer}/.well-known/openid-configuration`.
+    if (requirements.authorizationServer) {
+        const asUrl = buildAuthorizationServerMetadataUrl(requirements.authorizationServer);
+        let md;
+        let source;
+        if (asUrl) {
+            const res = await fetchJson(asUrl, allowPrivateIpForHop(asUrl), options.timeoutMs);
+            if (res && typeof res === 'object') {
+                md = res;
+                source = 'rfc-8414';
+            }
+        }
+        if (!md) {
+            const oidcUrl = buildOidcDiscoveryUrl(requirements.authorizationServer);
+            if (oidcUrl) {
+                const res = await fetchJson(oidcUrl, allowPrivateIpForHop(oidcUrl), options.timeoutMs);
+                if (res && typeof res === 'object') {
+                    md = res;
+                    source = 'openid-configuration';
+                }
+            }
+        }
+        if (md) {
+            requirements.metadataSource = source;
+            if (typeof md.authorization_endpoint === 'string') {
+                requirements.authorizationEndpoint = sanitizeDisplay(md.authorization_endpoint);
+            }
+            if (typeof md.token_endpoint === 'string') {
+                requirements.tokenEndpoint = sanitizeDisplay(md.token_endpoint);
+            }
+            if (typeof md.registration_endpoint === 'string') {
+                requirements.registrationEndpoint = sanitizeDisplay(md.registration_endpoint);
+            }
+            if (Array.isArray(md.scopes_supported)) {
+                const scopes = md.scopes_supported
+                    .filter((s) => typeof s === 'string')
+                    .slice(0, MAX_SCOPES)
+                    .map(sanitizeDisplay);
+                if (scopes.length > 0)
+                    requirements.scopesSupported = scopes;
+            }
+            if (Array.isArray(md.grant_types_supported)) {
+                const grants = md.grant_types_supported
+                    .filter((g) => typeof g === 'string')
+                    .slice(0, 32)
+                    .map(sanitizeDisplay);
+                if (grants.length > 0)
+                    requirements.grantTypesSupported = grants;
+            }
+        }
+    }
+    return requirements;
+}
+/**
+ * Fire a single unauthenticated `tools/list` at the agent and return the
+ * status + `WWW-Authenticate` header. Used when the caller hasn't provided
+ * a cached 401 response.
+ */
+async function probeAgent401(agentUrl, allowPrivateIp, timeoutMs) {
+    const body = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' });
+    try {
+        const res = await (0, net_1.ssrfSafeFetch)(agentUrl, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json',
+            },
+            body,
+            allowPrivateIp,
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        });
+        return { status: res.status, wwwAuthenticate: res.headers['www-authenticate'] };
+    }
+    catch {
+        return { status: 0 };
+    }
+}
+/**
+ * Check a URL is an absolute `http:`/`https:` URL before we hand it to
+ * `ssrfSafeFetch`. Defeats `javascript:`, `file:`, `data:`, etc. the agent
+ * might echo back in PRM or AS metadata. `ssrfSafeFetch` refuses non-HTTP
+ * schemes too, but failing fast here gives a cleaner discovery flow and
+ * avoids surfacing scheme errors as mysterious discovery misses.
+ */
+function originOf(value) {
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isSafeHttpUrl(value) {
+    try {
+        const u = new URL(value);
+        return u.protocol === 'https:' || u.protocol === 'http:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build the authorization-server metadata URL for an issuer per RFC 8414 §3.
+ *
+ * For issuer `https://as.example.com/tenant1`, metadata lives at
+ * `https://as.example.com/.well-known/oauth-authorization-server/tenant1`
+ * (well-known prefix inserted BEFORE the issuer path, not after). This
+ * matches how the MCP SDK and most authorization servers advertise metadata.
+ */
+function buildAuthorizationServerMetadataUrl(issuer) {
+    if (!isSafeHttpUrl(issuer))
+        return undefined;
+    const u = new URL(issuer);
+    const pathname = u.pathname.endsWith('/') ? u.pathname.slice(0, -1) : u.pathname;
+    return `${u.origin}/.well-known/oauth-authorization-server${pathname}`;
+}
+/**
+ * OpenID Connect Discovery 1.0 fallback URL. Some authorization servers
+ * (Keycloak in OIDC mode, Ping, ADFS) only publish metadata at
+ * `{issuer}/.well-known/openid-configuration` — path *suffixed*, not
+ * prefixed. The OIDC discovery doc carries `token_endpoint`,
+ * `authorization_endpoint`, and `grant_types_supported` with the same
+ * semantics as RFC 8414, so it's a safe read-through when the RFC 8414
+ * probe misses.
+ */
+function buildOidcDiscoveryUrl(issuer) {
+    if (!isSafeHttpUrl(issuer))
+        return undefined;
+    const u = new URL(issuer);
+    const base = u.pathname.endsWith('/') ? `${u.origin}${u.pathname.slice(0, -1)}` : `${u.origin}${u.pathname}`;
+    return `${base}/.well-known/openid-configuration`;
+}
+async function fetchJson(url, allowPrivateIp, timeoutMs) {
+    try {
+        const res = await (0, net_1.ssrfSafeFetch)(url, {
+            method: 'GET',
+            headers: { accept: 'application/json' },
+            allowPrivateIp,
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        });
+        if (res.status !== 200)
+            return undefined;
+        return (0, net_1.decodeBodyAsJsonOrText)(res.body, res.headers['content-type']);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=authorization-required.js.map

package/dist/lib/auth/oauth/authorization-required.js.map

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

package/dist/lib/auth/oauth/diagnose.d.ts

@@ -0,0 +1,101 @@
+import type { AgentConfig } from './types';
+import type { DecodedAccessToken } from './diagnostics';
+/**
+ * Options for {@link runAuthDiagnosis}. Most callers pass an `AgentConfig` and
+ * accept the defaults.
+ */
+export interface DiagnoseOptions {
+    /** Allow http:// and private-IP probe targets. Default false. */
+    allowPrivateIp?: boolean;
+    /** Skip the `tools/call` probe (e.g. if the agent doesn't expose a no-op tool). */
+    skipToolCall?: boolean;
+    /**
+     * Name of the tool to exercise in the `tools/call` probe. Default: `get_products`.
+     * This default is AdCP-specific; for non-AdCP MCP agents, pass a tool name that exists.
+     */
+    probeToolName?: string;
+    /** Arguments to send with the probe tool call. Default: `{ brief: 'diagnose-auth probe' }`. */
+    probeToolArgs?: Record<string, unknown>;
+    /** Skip the token-refresh attempt even when a refresh_token is available. */
+    skipRefresh?: boolean;
+    /** Replace the default timeout for individual HTTP probes (ms). Default inherits from ssrfSafeFetch (10s). */
+    timeoutMs?: number;
+    /**
+     * Include raw access_token / refresh_token / id_token values in the report.
+     * Default false — tokens are replaced with `<redacted length=N>` markers so
+     * that `--json` output is safe to paste into bug reports and log aggregators.
+     */
+    includeTokens?: boolean;
+}
+/** Wire-level capture of a single HTTP probe. */
+export interface HttpCapture {
+    url: string;
+    method: string;
+    /** 0 if the request never left the client (DNS failure, SSRF refusal, …). */
+    status: number;
+    /** Response headers with lowercased keys. */
+    headers: Record<string, string>;
+    /** Parsed JSON body if `content-type` is JSON, raw text otherwise, or `null` on error. */
+    body: unknown;
+    /** Client-side error message, if any. */
+    error?: string;
+}
+/** One step of the diagnosis, in execution order. */
+export interface DiagnosisStep {
+    name: 'probe_protected_resource_metadata' | 'probe_authorization_server_metadata' | 'decode_current_token' | 'token_refresh_attempt' | 'decode_refreshed_token' | 'list_tools_probe' | 'tool_call_probe';
+    /** Present for HTTP steps. */
+    http?: HttpCapture;
+    /** Present for decode steps. Claims are unverified. */
+    decodedToken?: DecodedAccessToken | null;
+    /** Free-form notes attached by the step for hypothesis ranking. */
+    notes?: string[];
+    /** Step-level error (distinct from `http.error` — set when the step was skipped or could not run). */
+    error?: string;
+}
+/** Rank verdict for a hypothesis. Ordered most-to-least actionable. */
+export type HypothesisVerdict = 'likely' | 'possible' | 'ruled_out' | 'not_observed';
+/** One ranked hypothesis about what might be wrong. */
+export interface Hypothesis {
+    /**
+     * Stable ID. Currently `H1`, `H2`, `H4`, `H5`, `H6` — `H3` (session ID handling)
+     * is reserved for a future addition. Downstream consumers should treat this as
+     * an opaque string rather than exhaustively switching on it.
+     */
+    id: string;
+    /** Short human-readable title. */
+    title: string;
+    /** One-line summary, tailored with evidence from this run. */
+    summary: string;
+    verdict: HypothesisVerdict;
+    /** Supporting evidence extracted from the steps above. */
+    evidence: string[];
+}
+/**
+ * Report schema version. Bumped when breaking changes to the shape of
+ * {@link AuthDiagnosisReport} land. Dashboards and downstream consumers should
+ * check this before relying on specific fields.
+ */
+export declare const AUTH_DIAGNOSIS_SCHEMA_VERSION: 1;
+/** Full diagnosis report returned by {@link runAuthDiagnosis}. */
+export interface AuthDiagnosisReport {
+    /** See {@link AUTH_DIAGNOSIS_SCHEMA_VERSION}. */
+    schemaVersion: typeof AUTH_DIAGNOSIS_SCHEMA_VERSION;
+    /** Agent URL under test. */
+    agentUrl: string;
+    /** Alias from saved config, if one was provided. */
+    aliasId?: string;
+    /** Per-step wire captures, in execution order. */
+    steps: DiagnosisStep[];
+    /** Ranked hypotheses — `likely` first, then `possible`, then `ruled_out`. */
+    hypotheses: Hypothesis[];
+    /** Report generation timestamp (ISO-8601, UTC). */
+    generatedAt: string;
+}
+/**
+ * Run the full diagnosis. Pass an agent config with (optionally) saved
+ * `oauth_tokens` to exercise a realistic handshake. Returns a structured
+ * report — rendering is the caller's job (CLI renders a text summary;
+ * programmatic consumers typically serialize to JSON).
+ */
+export declare function runAuthDiagnosis(agent: AgentConfig, options?: DiagnoseOptions): Promise<AuthDiagnosisReport>;
+//# sourceMappingURL=diagnose.d.ts.map

package/dist/lib/auth/oauth/diagnose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose.d.ts","sourceRoot":"","sources":["../../../../src/lib/auth/oauth/diagnose.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mFAAmF;IACnF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+FAA+F;IAC/F,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8GAA8G;IAC9G,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,0FAA0F;IAC1F,IAAI,EAAE,OAAO,CAAC;IACd,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,IAAI,EACA,mCAAmC,GACnC,qCAAqC,GACrC,sBAAsB,GACtB,uBAAuB,GACvB,wBAAwB,GACxB,kBAAkB,GAClB,iBAAiB,CAAC;IACtB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,uDAAuD;IACvD,YAAY,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACzC,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,sGAAsG;IACtG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,cAAc,CAAC;AAErF,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAG,CAAU,CAAC;AAExD,kEAAkE;AAClE,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,aAAa,EAAE,OAAO,6BAA6B,CAAC;IACpD,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,6EAA6E;IAC7E,UAAU,EAAE,UAAU,EAAE,CAAC;IACzB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAgI9B"}