@agenticprimitives/a2a 0.0.0-alpha.3 → 0.0.0-alpha.30

package/dist/auth.d.ts

@@ -1,16 +1,41 @@
 import { type Address, type Hex } from 'viem';
+import { decodeTimestampTerms, decodeAllowedTargetsTerms, decodeAllowedMethodsTerms } from '@agenticprimitives/delegation';
 import type { Delegation } from '@agenticprimitives/delegation';
 import type { A2aMessage } from './types.js';
 import { type A2aEnforcers } from './grant.js';
-/** Decode the deployed enforcers' term formats (must mirror delegation's encoders byte-for-byte). */
-export declare function decodeTimestampTerms(terms: Hex): {
-    validAfter: bigint;
-    validUntil: bigint;
-};
-export declare function decodeAllowedTargetsTerms(terms: Hex): readonly Address[];
-export declare function decodeAllowedMethodsTerms(terms: Hex): readonly Hex[];
+export { decodeTimestampTerms, decodeAllowedTargetsTerms, decodeAllowedMethodsTerms };
 /** Canonical hash the SENDER signs for an inbound message (A2A-INV-01). Binds id + sender + skill + body. */
 export declare function hashA2aMessage(m: Pick<A2aMessage, 'messageId' | 'sender' | 'skill' | 'bodyHash' | 'createdAt'>): Hex;
+/** AUDIT NEW-A2A-2: canonical digest the CALLER signs for a read/control request (tasks/get | cancel |
+ *  pushNotificationConfig/set). Authorization for these ops previously trusted a `caller` param the client
+ *  supplied — any attacker who knew a taskId could impersonate a party. The caller now PROVES control of
+ *  `caller` by signing this digest (verified via `OnChainChecks.verifyCallerSignature`). Bound to the
+ *  method (can't replay a `get` signature as a `cancel`), the taskId, the verifying agent, and the chain
+ *  (no cross-deployment replay). The agent re-derives it server-side — a client-supplied digest is never
+ *  trusted. */
+export declare function hashA2aTaskRequest(r: {
+    method: string;
+    taskId: Hex;
+    agentSA: Address;
+    chainId: number;
+    /** N-1 (seam audit): hash of the method-specific parameters that MUST be bound into the signature so
+     *  they can't be swapped on replay. For `pushNotificationConfig/set` this is
+     *  `hashPushConfigParams(url, token)` — without it a captured `set` signature could be replayed with an
+     *  ATTACKER url, redirecting the task's terminal push envelope (leaking taskId/state/artifacts + the push
+     *  token). Absent (zero) for parameter-less ops (tasks/get, tasks/cancel). */
+    paramsHash?: Hex;
+    /** N-2 (seam audit): the caller's signing time (unix seconds), folded into the digest so a captured
+     *  read/control signature is bounded to a freshness window (the agent rejects a stale one) instead of
+     *  being replayable for the life of the task. Absent (0) preserves the legacy unbounded digest. */
+    issuedAt?: number;
+}): Hex;
+/** Bind the requested ARTIFACT into the `tasks/artifact` signature, so a captured signature cannot be
+ *  replayed to fetch a DIFFERENT artifact of the same task. Same role `hashPushConfigParams` plays
+ *  for the push url. */
+export declare function hashArtifactParams(artifactId: Hex): Hex;
+/** N-1: bind the push-notification target (url + optional token) into the `set` request signature so it
+ *  cannot be replayed with a different url. The server re-derives this from the presented url/token. */
+export declare function hashPushConfigParams(url: string, token?: string): Hex;
 /** On-chain + crypto verdicts injected by the consumer (viem-backed). All fail-closed. */
 export interface OnChainChecks {
     /** DelegationManager.isRevoked(hashDelegation(d)) — MUST throw or return true to deny. */
@@ -19,18 +44,54 @@ export interface OnChainChecks {
     verifyDelegationSignature(delegation: Delegation): Promise<boolean>;
     /** ERC-1271: the sender SA signed `hashA2aMessage(message)`. */
     verifyMessageSignature(message: A2aMessage, digest: Hex): Promise<boolean>;
+    /** AUDIT NEW-A2A-2 — ERC-1271: `caller` SA signed `hashA2aTaskRequest(...)`. Proves the read/control
+     *  caller controls the address it claims, so `caller` can no longer be spoofed. Fail-closed (throw/false). */
+    verifyCallerSignature(caller: Address, digest: Hex, signature: Hex): Promise<boolean>;
+}
+/** A reserved single-use message-id (spec 290 §3). Mirrors delegation's `JtiReservation`: a reservation is
+ *  IN-FLIGHT (it still serves as the replay guard) until the caller either commits it (the task was durably
+ *  created) or releases it (a pre-acceptance rejection). */
+export interface MessageIdReservation {
+    /** Finalize — the id is permanently consumed; a later replay is rejected. */
+    commit(): Promise<void>;
+    /** Free the IN-FLIGHT reservation WITHOUT consuming the id, so a legitimate retry of the SAME message
+     *  may re-reserve. Called on any pre-durable-acceptance rejection so a failed submit never burns the
+     *  nonce (spec 290 §3 — a post-verify reject must not consume the authorization). */
+    release(): Promise<void>;
 }
-/** Single-use reservation seam (the TaskStore provides this; FR-4.3). */
+/** Single-use reservation seam (the TaskStore provides this; FR-4.3). Two-phase per spec 290 §3. */
 export interface MessageIdReserver {
-    reserveMessageId(messageId: Hex, ttlSec: number): Promise<boolean>;
+    /** Reserve the id IN-FLIGHT (replay guard). Returns a reservation to `commit` (durable accept) or
+     *  `release` (pre-acceptance reject); `null` if the id is already in-flight or consumed (replay → deny). */
+    reserveMessageId(messageId: Hex, ttlSec: number): Promise<MessageIdReservation | null>;
+    /** A2A-4 (seam audit): OPTIONAL cheap read-only "is this id already consumed/in-flight?" peek. When
+     *  provided, authorizeA2aMessage checks it FIRST and rejects a definite replay BEFORE the 3 on-chain
+     *  reads (isRevoked + two ERC-1271 verifies) — so replaying a consumed messageId can't amplify RPC load.
+     *  It is only an optimization: the atomic reserve-LAST remains the source of truth for the genuine race
+     *  (a false `false` here just falls through to the normal path). Omit ⇒ unchanged behavior. */
+    peekConsumed?(messageId: Hex): Promise<boolean>;
 }
 export type AuthorizeResult = {
     ok: true;
     principal: Address;
+    messageIdReservation: MessageIdReservation;
 } | {
     ok: false;
     reason: string;
 };
+/**
+ * OPTIONAL scope-class resolver for FR-4.2 (spec 341 §5.1c). By default an `allowedTargets` entry is
+ * an exact agent address. A deployment may inject this to give SOME entries set semantics — e.g. "an
+ * org SA means its current members", "the naming registry means any named agent". Consulted ONLY when
+ * the exact-address check already failed, with the full target list, the delegation's delegator (the
+ * person the grant speaks for) and the requested skill — so the app can, and should, restrict class
+ * semantics to specific skills. Absent, throwing, or returning false all deny (fail-closed).
+ */
+export type ScopeCovers = (i: {
+    targets: readonly Address[];
+    sender: Address;
+    skill: string;
+}) => Promise<boolean>;
 /**
  * Authorize an inbound A2A message. Returns the principal (delegation.delegator) the sender acts for, or
  * a rejection reason. Fail-closed throughout; no task is created on `ok: false`. The message-id is
@@ -51,5 +112,7 @@ export declare function authorizeA2aMessage(args: {
     now: number;
     /** Message-id reservation TTL (seconds). Default 600. */
     replayTtlSec?: number;
+    /** FR-4.2 scope classes — see `ScopeCovers`. Omit ⇒ exact-address matching only. */
+    scopeCovers?: ScopeCovers;
 }): Promise<AuthorizeResult>;
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAQA,OAAO,EAAgE,KAAK,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAC5G,OAAO,KAAK,EAAE,UAAU,EAAU,MAAM,+BAA+B,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAgC,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7E,qGAAqG;AACrG,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,GAAG,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAG3F;AACD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,GAAG,GAAG,SAAS,OAAO,EAAE,CAGxE;AACD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,GAAG,GAAG,SAAS,GAAG,EAAE,CAGpE;AAED,6GAA6G;AAC7G,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,WAAW,CAAC,GAAG,GAAG,CAOpH;AAED,0FAA0F;AAC1F,MAAM,WAAW,aAAa;IAC5B,0FAA0F;IAC1F,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,yDAAyD;IACzD,yBAAyB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,gEAAgE;IAChE,sBAAsB,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5E;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpE;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAMlC;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,UAAU,CAAC;IACpB,2EAA2E;IAC3E,WAAW,EAAE,OAAO,CAAC;IACrB,wFAAwF;IACxF,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,YAAY,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,iBAAiB,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,eAAe,CAAC,CA6D3B"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/auth.js

@@ -6,25 +6,45 @@
 //   FR-4.3 single-use message-id (inbound replay guard).
 //   FR-4.4 the inbound message is signed by the sender.
 // On-chain reads are INJECTED (the package stays transport-agnostic); the consumer wires viem.
-import { decodeAbiParameters, keccak256, encodeAbiParameters, toBytes } from 'viem';
+import { keccak256, encodeAbiParameters, toBytes } from 'viem';
+import { decodeTimestampTerms, decodeAllowedTargetsTerms, decodeAllowedMethodsTerms, } from '@agenticprimitives/delegation';
 import { skillSelector, A2A_ANY_SKILL } from './grant.js';
-/** Decode the deployed enforcers' term formats (must mirror delegation's encoders byte-for-byte). */
-export function decodeTimestampTerms(terms) {
-    const [validAfter, validUntil] = decodeAbiParameters([{ type: 'uint256' }, { type: 'uint256' }], terms);
-    return { validAfter, validUntil };
-}
-export function decodeAllowedTargetsTerms(terms) {
-    const [targets] = decodeAbiParameters([{ type: 'address[]' }], terms);
-    return targets;
-}
-export function decodeAllowedMethodsTerms(terms) {
-    const [selectors] = decodeAbiParameters([{ type: 'bytes4[]' }], terms);
-    return selectors;
-}
+// Term decoders now live in `delegation`, beside the encoders that produce the bytes. Imported for
+// local use AND re-exported so existing a2a consumers are unaffected — one implementation, and it
+// cannot drift from the encoder without the compiler noticing.
+export { decodeTimestampTerms, decodeAllowedTargetsTerms, decodeAllowedMethodsTerms };
 /** Canonical hash the SENDER signs for an inbound message (A2A-INV-01). Binds id + sender + skill + body. */
 export function hashA2aMessage(m) {
     return keccak256(encodeAbiParameters([{ type: 'bytes32' }, { type: 'address' }, { type: 'bytes32' }, { type: 'bytes32' }, { type: 'uint256' }], [m.messageId, m.sender, keccak256(toBytes(m.skill)), m.bodyHash, BigInt(m.createdAt)]));
 }
+/** AUDIT NEW-A2A-2: canonical digest the CALLER signs for a read/control request (tasks/get | cancel |
+ *  pushNotificationConfig/set). Authorization for these ops previously trusted a `caller` param the client
+ *  supplied — any attacker who knew a taskId could impersonate a party. The caller now PROVES control of
+ *  `caller` by signing this digest (verified via `OnChainChecks.verifyCallerSignature`). Bound to the
+ *  method (can't replay a `get` signature as a `cancel`), the taskId, the verifying agent, and the chain
+ *  (no cross-deployment replay). The agent re-derives it server-side — a client-supplied digest is never
+ *  trusted. */
+export function hashA2aTaskRequest(r) {
+    return keccak256(encodeAbiParameters([{ type: 'bytes32' }, { type: 'bytes32' }, { type: 'address' }, { type: 'uint256' }, { type: 'bytes32' }, { type: 'uint256' }], [
+        keccak256(toBytes(`a2a:request:${r.method}`)),
+        r.taskId,
+        r.agentSA,
+        BigInt(r.chainId),
+        r.paramsHash ?? `0x${'00'.repeat(32)}`,
+        BigInt(r.issuedAt ?? 0),
+    ]));
+}
+/** Bind the requested ARTIFACT into the `tasks/artifact` signature, so a captured signature cannot be
+ *  replayed to fetch a DIFFERENT artifact of the same task. Same role `hashPushConfigParams` plays
+ *  for the push url. */
+export function hashArtifactParams(artifactId) {
+    return keccak256(encodeAbiParameters([{ type: 'bytes32' }], [artifactId]));
+}
+/** N-1: bind the push-notification target (url + optional token) into the `set` request signature so it
+ *  cannot be replayed with a different url. The server re-derives this from the presented url/token. */
+export function hashPushConfigParams(url, token) {
+    return keccak256(encodeAbiParameters([{ type: 'string' }, { type: 'string' }], [url, token ?? '']));
+}
 const eq = (a, b) => a.toLowerCase() === b.toLowerCase();
 const findCaveat = (caveats, enforcer) => caveats.find((c) => eq(c.enforcer, enforcer));
 /**
@@ -40,6 +60,12 @@ export async function authorizeA2aMessage(args) {
         return { ok: false, reason: 'delegate != requester' };
     if (!eq(message.sender, args.requester))
         return { ok: false, reason: 'message sender != requester' };
+    // A2A-4 — cheap replay peek BEFORE the on-chain reads: a replayed (already-consumed) messageId is
+    // rejected here rather than after isRevoked + two ERC-1271 verifies, bounding RPC amplification. The
+    // atomic reserve-last below still handles the genuine race; this only short-circuits definite replays.
+    if (args.store.peekConsumed && (await args.store.peekConsumed(message.messageId))) {
+        return { ok: false, reason: 'message replay (already consumed)' };
+    }
     // FR-4.1 — timestamp window (off-chain decode; the enforcer would check the same on-chain).
     const tsCav = findCaveat(d.caveats, enforcers.timestamp);
     if (!tsCav)
@@ -54,7 +80,9 @@ export async function authorizeA2aMessage(args) {
     const nowSec = BigInt(Math.floor(args.now / 1000));
     if (nowSec < win.validAfter || nowSec >= win.validUntil)
         return { ok: false, reason: 'grant outside timestamp window' };
-    // FR-4.2 — recipient scoping: allowedTargets MUST include this agent.
+    // FR-4.2 — recipient scoping: allowedTargets MUST cover this agent. Exact address first; then, and
+    // only if the deployment injected class semantics, the scope resolver. One caveat, one verdict —
+    // this is set membership in a single authorization, not a second mechanism after a failed first.
     const atCav = findCaveat(d.caveats, enforcers.allowedTargets);
     if (!atCav)
         return { ok: false, reason: 'missing allowedTargets caveat (FR-4.2)' };
@@ -65,8 +93,19 @@ export async function authorizeA2aMessage(args) {
     catch {
         return { ok: false, reason: 'bad allowedTargets terms' };
     }
-    if (!targets.some((t) => eq(t, args.thisAgentSA)))
-        return { ok: false, reason: 'grant not scoped to this agent (allowedTargets)' };
+    if (!targets.some((t) => eq(t, args.thisAgentSA))) {
+        let classCovered = false;
+        if (args.scopeCovers) {
+            try {
+                classCovered = await args.scopeCovers({ targets, sender: d.delegator, skill: args.skill });
+            }
+            catch {
+                classCovered = false;
+            }
+        }
+        if (!classCovered)
+            return { ok: false, reason: 'grant not scoped to this agent (allowedTargets)' };
+    }
     // FR-4.2 — skill scoping: allowedMethods MUST include the skill selector (or the any-sentinel).
     const amCav = findCaveat(d.caveats, enforcers.allowedMethods);
     if (!amCav)
@@ -108,9 +147,13 @@ export async function authorizeA2aMessage(args) {
         return { ok: false, reason: `message signature check failed: ${e instanceof Error ? e.message : e}` };
     }
     // FR-4.3 — single-use message id (reserve last; a replay of a valid message hits the reserved id).
-    if (!(await args.store.reserveMessageId(message.messageId, args.replayTtlSec ?? 600))) {
+    // Two-phase (spec 290 §3): the reservation marks the id IN-FLIGHT; the caller commits it ONLY after the
+    // task is durably created, and releases it on any pre-acceptance rejection — so a post-verify failure
+    // (bad bodyHash, budget exhausted, a throwing store) never burns the nonce.
+    const messageIdReservation = await args.store.reserveMessageId(message.messageId, args.replayTtlSec ?? 600);
+    if (!messageIdReservation) {
         return { ok: false, reason: 'message id already used (replay)' };
     }
-    return { ok: true, principal: d.delegator };
+    return { ok: true, principal: d.delegator, messageIdReservation };
 }
 //# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,6FAA6F;AAC7F,yGAAyG;AACzG,+FAA+F;AAC/F,iGAAiG;AACjG,yDAAyD;AACzD,wDAAwD;AACxD,+FAA+F;AAC/F,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,mBAAmB,EAAE,OAAO,EAA0B,MAAM,MAAM,CAAC;AAG5G,OAAO,EAAE,aAAa,EAAE,aAAa,EAAqB,MAAM,YAAY,CAAC;AAE7E,qGAAqG;AACrG,MAAM,UAAU,oBAAoB,CAAC,KAAU;IAC7C,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,GAAG,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IACxG,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;AACpC,CAAC;AACD,MAAM,UAAU,yBAAyB,CAAC,KAAU;IAClD,MAAM,CAAC,OAAO,CAAC,GAAG,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IACtE,OAAO,OAA6B,CAAC;AACvC,CAAC;AACD,MAAM,UAAU,yBAAyB,CAAC,KAAU;IAClD,MAAM,CAAC,SAAS,CAAC,GAAG,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IACvE,OAAO,SAA2B,CAAC;AACrC,CAAC;AAED,6GAA6G;AAC7G,MAAM,UAAU,cAAc,CAAC,CAAgF;IAC7G,OAAO,SAAS,CACd,mBAAmB,CACjB,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EACzG,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CACtF,CACF,CAAC;AACJ,CAAC;AAqBD,MAAM,EAAE,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;AACzE,MAAM,UAAU,GAAG,CAAC,OAA0B,EAAE,QAAiB,EAAsB,EAAE,CACvF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAczC;IACC,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAE3D,0CAA0C;IAC1C,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAC3F,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,6BAA6B,EAAE,CAAC;IAErG,4FAA4F;IAC5F,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IACzD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;IACrE,IAAI,GAA+C,CAAC;IACpD,IAAI,CAAC;QAAC,GAAG,GAAG,oBAAoB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAAC,CAAC;IAC/G,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC;IACnD,IAAI,MAAM,GAAG,GAAG,CAAC,UAAU,IAAI,MAAM,IAAI,GAAG,CAAC,UAAU;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gCAAgC,EAAE,CAAC;IAExH,sEAAsE;IACtE,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,cAAc,CAAC,CAAC;IAC9D,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wCAAwC,EAAE,CAAC;IACnF,IAAI,OAA2B,CAAC;IAChC,IAAI,CAAC;QAAC,OAAO,GAAG,yBAAyB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;IAAC,CAAC;IAC7H,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iDAAiD,EAAE,CAAC;IAEnI,gGAAgG;IAChG,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,cAAc,CAAC,CAAC;IAC9D,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wCAAwC,EAAE,CAAC;IACnF,IAAI,SAAyB,CAAC;IAC9B,IAAI,CAAC;QAAC,SAAS,GAAG,yBAAyB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;IAAC,CAAC;IAC/H,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC;QAChE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iDAAiD,EAAE,CAAC;IAClF,CAAC;IAED,+DAA+D;IAC/D,IAAI,CAAC;QACH,IAAI,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IACpF,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iCAAiC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACtG,CAAC;IAED,yCAAyC;IACzC,IAAI,CAAC;QACH,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,8BAA8B,EAAE,CAAC;IACjH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,sCAAsC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAC3G,CAAC;IAED,iDAAiD;IACjD,IAAI,CAAC;QACH,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,sBAAsB,CAAC,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAC;QAC5D,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mCAAmC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACxG,CAAC;IAED,mGAAmG;IACnG,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,YAAY,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC;QACtF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,kCAAkC,EAAE,CAAC;IACnE,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/authority-extension.d.ts

@@ -0,0 +1,58 @@
+/** The extension URI. Versioned in the path: a change to what the authority model REQUIRES is a new
+ *  URI, not a silent redefinition of this one — a peer must be able to detect the difference. */
+export declare const AP_AUTHORITY_EXTENSION_URI = "https://agenticprimitives.org/a2a/authority/v1";
+/** The activation header stock A2A defines for extensions; clients opt in by naming the URI. */
+export declare const A2A_EXTENSIONS_HEADER = "X-A2A-Extensions";
+/**
+ * How a caller proves it may invoke a skill. Both forms resolve to the SAME question — "does the
+ * principal SA authorize this actor for this selector, right now?" — and neither is a bearer grant.
+ */
+export type ApAuthorityMethod = 
+/** A signed, caveated delegation naming the acting agent, verified against the principal SA
+ *  (ERC-1271 / 6492 / ECDSA / WebAuthn via UniversalSignatureValidator). */
+'delegation'
+/** A Home-issued session wire bound to the person SA — custody-scoped, not a peer grant. */
+ | 'session-wire'
+/** A signed mandate: a scoped delegation plus an explicit, signed statement of intent. Used where a
+ *  human decision must be attributable, not merely permitted. */
+ | 'mandate';
+export interface ApAuthorityExtensionParams {
+    /** Which proof forms this deployment accepts. Order is not precedence — the server decides. */
+    methods: readonly ApAuthorityMethod[];
+    /** CAIP-2 chain the principal SA and its delegations live on, so a peer resolves against the right
+     *  chain rather than guessing from an address. */
+    chain: string;
+    /** Whether activation is required to call ANY skill. Almost always false: peer-callable skills are
+     *  the point, and a required extension excludes clients that could otherwise interoperate. */
+    required?: boolean;
+}
+export interface ApAuthorityExtension {
+    uri: string;
+    required: boolean;
+    description: string;
+    /** Machine-readable params. A peer MUST be able to act on this without parsing prose. */
+    params: {
+        methods: readonly ApAuthorityMethod[];
+        chain: string;
+        /** Stated explicitly so no client infers otherwise from the presence of a bearer envelope. */
+        bearerIsEnvelopeOnly: true;
+        /** Authority is re-checked at the moment of acting; a prior success is not a durable capability. */
+        reEvaluatedPerCall: true;
+    };
+}
+/**
+ * Build the Card's authority extension.
+ *
+ * `bearerIsEnvelopeOnly` and `reEvaluatedPerCall` are literal `true` in the type, not booleans a
+ * deployment can set. They are not configuration — a deployment that wanted to say otherwise would be
+ * describing a different system, and the type refuses to let it say so on our Card (ADR-0041).
+ */
+export declare function apAuthorityExtension(params: ApAuthorityExtensionParams): ApAuthorityExtension;
+/** Whether a client activated the extension, per the stock `X-A2A-Extensions` header.
+ *
+ *  NOTE: activation is a CLIENT HINT and nothing more. It reports which extensions the caller
+ *  understands; it does not authorize, and a server MUST NOT treat activation as a reason to relax any
+ *  check. A caller that activates nothing still faces the same authority decision — the extension is
+ *  documentation of the question, not a way to change the answer. */
+export declare function activatesApAuthority(header: string | null | undefined): boolean;
+//# sourceMappingURL=authority-extension.d.ts.map

package/dist/authority-extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authority-extension.d.ts","sourceRoot":"","sources":["../src/authority-extension.ts"],"names":[],"mappings":"AAuBA;iGACiG;AACjG,eAAO,MAAM,0BAA0B,mDAAmD,CAAC;AAE3F,gGAAgG;AAChG,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,iBAAiB;AAC3B;4EAC4E;AAC1E,YAAY;AACd,4FAA4F;GAC1F,cAAc;AAChB;iEACiE;GAC/D,SAAS,CAAC;AAEd,MAAM,WAAW,0BAA0B;IACzC,+FAA+F;IAC/F,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACtC;sDACkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd;kGAC8F;IAC9F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,MAAM,EAAE;QACN,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;QACtC,KAAK,EAAE,MAAM,CAAC;QACd,8FAA8F;QAC9F,oBAAoB,EAAE,IAAI,CAAC;QAC3B,oGAAoG;QACpG,kBAAkB,EAAE,IAAI,CAAC;KAC1B,CAAC;CACH;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,0BAA0B,GAAG,oBAAoB,CAqB7F;AAED;;;;;qEAKqE;AACrE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAM/E"}

package/dist/authority-extension.js

@@ -0,0 +1,70 @@
+// The AP authority extension for the Agent Card (ADR-0059 / spec 341 §2.1).
+//
+// THE PROBLEM IT SOLVES. The Card declares no `securitySchemes` — not a wrong one, none. A peer reading
+// it learns which skills exist and nothing about how to be allowed to call them. Every caller therefore
+// needs out-of-band knowledge, which is the definition of a private RPC surface wearing a protocol's
+// clothes. Declaring the authority model is what makes the difference between a protocol and skill-RPC
+// cosplay, and it is the thing that lets an EXTERNAL agent use the same skills the Home uses — spec
+// 341's actual success test.
+//
+// WHY AN EXTENSION AND NOT A `securityScheme`. Stock A2A's security schemes are OAuth2 / OIDC / API-key
+// / mTLS — all of them bearer-shaped, all of them "the issuer says you may". Declaring one of those
+// would assert something false about this substrate: here the grant is an ERC-4337-SA-bound,
+// signature-verified, on-chain-revocable **delegation**, re-evaluated at the moment of acting, and a
+// bearer token is at most an envelope carrying a reference to it (ADR-0041). Picking the nearest stock
+// scheme to look compliant would invert the exact property that distinguishes this system, so the
+// authority model is declared as a first-class `AgentExtension` instead — the same mechanism this
+// package already ships for x402 pricing.
+//
+// WHAT THIS EXTENSION IS NOT. It is not authority. Advertising it grants nothing, and a caller that
+// activates it is not thereby authorized; it tells a peer WHICH question will be asked of it, never
+// what the answer will be. The decision still happens server-side against the principal SA, at the
+// moment of acting, every time (ADR-0041, ADR-0043).
+/** The extension URI. Versioned in the path: a change to what the authority model REQUIRES is a new
+ *  URI, not a silent redefinition of this one — a peer must be able to detect the difference. */
+export const AP_AUTHORITY_EXTENSION_URI = 'https://agenticprimitives.org/a2a/authority/v1';
+/** The activation header stock A2A defines for extensions; clients opt in by naming the URI. */
+export const A2A_EXTENSIONS_HEADER = 'X-A2A-Extensions';
+/**
+ * Build the Card's authority extension.
+ *
+ * `bearerIsEnvelopeOnly` and `reEvaluatedPerCall` are literal `true` in the type, not booleans a
+ * deployment can set. They are not configuration — a deployment that wanted to say otherwise would be
+ * describing a different system, and the type refuses to let it say so on our Card (ADR-0041).
+ */
+export function apAuthorityExtension(params) {
+    if (params.methods.length === 0) {
+        // An authority extension that accepts nothing is not a lean Card, it is a broken one: it tells a
+        // peer to authorize and gives it no way to. Fail loudly at build time (ADR-0013 — empty is an
+        // answer, and here it is the wrong one).
+        throw new Error('apAuthorityExtension: at least one authority method must be declared');
+    }
+    return {
+        uri: AP_AUTHORITY_EXTENSION_URI,
+        required: params.required ?? false,
+        description: 'Authorization is an on-chain delegation decision against the principal Smart Agent, verified by ' +
+            'signature and re-evaluated at the moment of acting. A bearer token is a transport envelope only ' +
+            'and never the grant.',
+        params: {
+            methods: params.methods,
+            chain: params.chain,
+            bearerIsEnvelopeOnly: true,
+            reEvaluatedPerCall: true,
+        },
+    };
+}
+/** Whether a client activated the extension, per the stock `X-A2A-Extensions` header.
+ *
+ *  NOTE: activation is a CLIENT HINT and nothing more. It reports which extensions the caller
+ *  understands; it does not authorize, and a server MUST NOT treat activation as a reason to relax any
+ *  check. A caller that activates nothing still faces the same authority decision — the extension is
+ *  documentation of the question, not a way to change the answer. */
+export function activatesApAuthority(header) {
+    if (!header)
+        return false;
+    return header
+        .split(',')
+        .map((s) => s.trim())
+        .includes(AP_AUTHORITY_EXTENSION_URI);
+}
+//# sourceMappingURL=authority-extension.js.map

package/dist/authority-extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authority-extension.js","sourceRoot":"","sources":["../src/authority-extension.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,wGAAwG;AACxG,wGAAwG;AACxG,qGAAqG;AACrG,uGAAuG;AACvG,oGAAoG;AACpG,6BAA6B;AAC7B,EAAE;AACF,wGAAwG;AACxG,oGAAoG;AACpG,6FAA6F;AAC7F,qGAAqG;AACrG,uGAAuG;AACvG,kGAAkG;AAClG,kGAAkG;AAClG,0CAA0C;AAC1C,EAAE;AACF,oGAAoG;AACpG,oGAAoG;AACpG,mGAAmG;AACnG,qDAAqD;AAErD;iGACiG;AACjG,MAAM,CAAC,MAAM,0BAA0B,GAAG,gDAAgD,CAAC;AAE3F,gGAAgG;AAChG,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAC;AA0CxD;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAkC;IACrE,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,iGAAiG;QACjG,8FAA8F;QAC9F,yCAAyC;QACzC,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO;QACL,GAAG,EAAE,0BAA0B;QAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,KAAK;QAClC,WAAW,EACT,kGAAkG;YAClG,kGAAkG;YAClG,sBAAsB;QACxB,MAAM,EAAE;YACN,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,oBAAoB,EAAE,IAAI;YAC1B,kBAAkB,EAAE,IAAI;SACzB;KACF,CAAC;AACJ,CAAC;AAED;;;;;qEAKqE;AACrE,MAAM,UAAU,oBAAoB,CAAC,MAAiC;IACpE,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,OAAO,MAAM;SACV,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,QAAQ,CAAC,0BAA0B,CAAC,CAAC;AAC1C,CAAC"}

package/dist/card-audience.d.ts

@@ -0,0 +1,87 @@
+import { type VerifiedPeerContextV1 } from '@agenticprimitives/types';
+import type { AgentCardAudience } from './agent.js';
+/** What a requester presents to claim a wider card audience. All fields required to get past `public`. */
+export interface CardAudienceClaim {
+    /** Claimed canonical id (CAIP-10) or address. Unverified until the signature checks out. */
+    requester?: string;
+    /** A nonce issued by THIS host. Single-use. */
+    challengeNonce?: string;
+    signature?: `0x${string}`;
+    issuedAt?: string;
+    /** The view being asked for. Never granted on its own — this is a request, not a grant. */
+    requestedView?: string;
+}
+/** The body a requester signs. Binds the host and the view so a proof is not portable. */
+export interface CardChallengeBody {
+    requester: string;
+    challengeNonce: string;
+    /** This host's origin — a proof for one agent's card must not work at another's. */
+    cardOrigin: string;
+    requestedView: 'authenticated' | 'private';
+    issuedAt: string;
+}
+/** Injected signature verification — satisfied by a `chain-state` reader wrapper. */
+export type CardSignatureVerifier = (args: {
+    requester: string;
+    body: CardChallengeBody;
+    signature: `0x${string}`;
+}) => Promise<boolean>;
+/** Single-use nonce consumption. Returns false if already spent or unknown to this host. */
+export type CardNonceConsumer = (nonce: string, cardOrigin: string) => Promise<boolean>;
+export interface CardAudienceResolverOptions {
+    /** This host's canonical origin. A proof bound to another origin is refused. */
+    cardOrigin: string;
+    verifySignature: CardSignatureVerifier;
+    consumeNonce: CardNonceConsumer;
+    now: () => string;
+    /** Maximum age of a claim. Default 2 minutes. */
+    maxClaimAgeMs?: number;
+    /**
+     * Decides whether a VERIFIED requester may see the `private` view, and is the only place a private
+     * audience can be granted. Omit ⇒ a verified requester reaches `authenticated` and no further.
+     *
+     * Kept separate from signature verification because they answer different questions: the signature
+     * says *who* is asking; this says *what that party is entitled to see*.
+     */
+    privateViewPolicy?: (requester: string) => Promise<boolean>;
+    /** Local-only diagnostics. Never surfaced to the requester. */
+    observe?: (o: {
+        granted: AgentCardAudience['audience'];
+        reason?: string;
+    }) => void;
+}
+/**
+ * When the TRANSPORT already authenticated the peer (spec 338 W5-b), a separate card challenge is
+ * redundant — the connection itself proved who is asking.
+ *
+ * Accepted ONLY at `strength: 'agent'` (`isAgentAuthenticatedPeer`). Web PKI authenticates a
+ * hostname and SPIFFE a workload; neither is a Smart Agent, and treating either as one is exactly
+ * the conflation `VerifiedPeerContextV1` exists to prevent.
+ *
+ * NOTE this does not imply relay resistance: without a channel binding an active relay could be the
+ * party on the connection. Hosts that need that guarantee should require a channel-bound peer at the
+ * edge rather than loosening anything here.
+ */
+export interface PeerBackedAudienceInput {
+    peerContext?: VerifiedPeerContextV1;
+}
+/** The public audience — the floor, and the answer to every failed claim. */
+export declare const PUBLIC_AUDIENCE: AgentCardAudience;
+/**
+ * Build the resolver a card route calls to turn a request into an audience.
+ *
+ * Never throws. Never returns an audience wider than the claim proved.
+ */
+export declare function createCardAudienceResolver(opts: CardAudienceResolverOptions): (claim: CardAudienceClaim, peer?: PeerBackedAudienceInput) => Promise<AgentCardAudience>;
+/**
+ * Read a claim from standard request inputs.
+ *
+ * The signature and nonce come from HEADERS, never the query string: a query parameter lands in
+ * access logs, `Referer` headers, and browser history, and a proof that leaks that way is a replay
+ * waiting to happen. `view` stays in the query because it is a request, not a secret.
+ */
+export declare function readCardAudienceClaim(input: {
+    query: (k: string) => string | undefined;
+    header: (k: string) => string | undefined;
+}): CardAudienceClaim;
+//# sourceMappingURL=card-audience.d.ts.map

package/dist/card-audience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-audience.d.ts","sourceRoot":"","sources":["../src/card-audience.ts"],"names":[],"mappings":"AAoBA,OAAO,EAA4B,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,0GAA0G;AAC1G,MAAM,WAAW,iBAAiB;IAChC,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,0FAA0F;AAC1F,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,eAAe,GAAG,SAAS,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qFAAqF;AACrF,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,iBAAiB,CAAC;IACxB,SAAS,EAAE,KAAK,MAAM,EAAE,CAAC;CAC1B,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvB,4FAA4F;AAC5F,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAExF,MAAM,WAAW,2BAA2B;IAC1C,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,qBAAqB,CAAC;IACvC,YAAY,EAAE,iBAAiB,CAAC;IAChC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5D,+DAA+D;IAC/D,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,OAAO,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACpF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC;AAID,6EAA6E;AAC7E,eAAO,MAAM,eAAe,EAAE,iBAA0C,CAAC;AAMzE;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,2BAA2B,WAEjE,iBAAiB,SACjB,uBAAuB,KAC7B,OAAO,CAAC,iBAAiB,CAAC,CAsF9B;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACzC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAC3C,GAAG,iBAAiB,CAQpB"}