keri-ts 2.1.0 → 2.2.1

package/types/app/ipex/presenting.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Runtime-owned operations for single-signature v2 IPEX presentation.
+ *
+ * `present` is the user's one explicit consent: it selects the credential view, signs the Offer, Grant,
+ * Apply, Agree or Spurn (a Grant may also anchor its presentation proof under that same consent), takes
+ * the signed exchange into local authenticated intake and queues it. It returns after local commit and
+ * never waits for the peer. `PresentationOperations.processOnce` is the only worker: it delivers the
+ * already signed bytes, retries a failed delivery with a doubling delay until the exchange's deadline
+ * and ends the operation at the Grant's original exchange deadline. It never signs.
+ *
+ * There is no operation store. The signed exchange is itself durable (the accepted exchange and its
+ * signatures), and `resendPresentation` rebuilds its wire from those stored factors, signing nothing, so
+ * a process that ended before or during delivery can deliver again on the user's explicit request. Nothing
+ * is sent after a restart on its own.
+ *
+ * Status is the live table plus what the stores prove. Delivery itself leaves no protocol record, so
+ * only the peer's stored answer proves it:
+ *
+ * | stores prove                                              | status                                       |
+ * | --------------------------------------------------------- | -------------------------------------------- |
+ * | the peer's answer is stored (`erpy`)                      | `done`, with the `response`                  |
+ * | signed exchange accepted, deadline passed, no answer      | `expired`                                    |
+ * | signed exchange accepted, no answer, not live             | `interrupted`: `resendPresentation` delivers |
+ *
+ * Lost on reload, by design: the delivery attempts and the last transport failure, the `abandoned` and
+ * `failed` end states with their reasons, the delivery destinations, and the fact of a delivery nobody
+ * answered (it reads `done` in the process that delivered it and `interrupted` after a reload; sending it
+ * again is harmless, the peer deduplicates by SAID).
+ *
+ * Workflow-contract shape (`app/runtime/workflow-contract.ts`): `present` returns after local commit,
+ * `presentationStatus` is a pure read, `waitForPresentation` only observes and returns a `WaitResult`, and
+ * `abandonPresentation` is local. A host that wants only the signed bytes (a file, a QR code) uses
+ * `preparePresentation`, which commits locally and queues nothing.
+ *
+ * Group identifiers are refused here: a group presents through {@link proposeGroupPresentation}, which hands the
+ * frozen Grant to the group IPEX owner (`group-ipex.ts`) for member approval.
+ */
+import { type SerderKERI } from "cesr-ts";
+import { type Operation } from "effection";
+import { type DerivedUpdateStore } from "../../acdc/custody.js";
+import type { Regery } from "../../acdc/registraring.js";
+import type { Exchanger } from "../exchanges/exchanging.js";
+import type { Hab, Habery } from "../identity/habbing.js";
+import { type CounselInputs } from "../multisig/counseling.js";
+import type { ProtocolProcessor } from "../protocol/protocol-processing.js";
+import type { Reactor } from "../protocol/reactor.js";
+import { type DeliveryFailure, DeliveryOutbox } from "../runtime/delivery-outbox.js";
+import type { RetryPolicy } from "../runtime/retry-backoff.js";
+import type { RuntimeClock } from "../runtime/runtime-clock.js";
+import { type ChangeSink, type WaitResult } from "../runtime/workflow-contract.js";
+import type { Receiptor, WitnessAuthMap } from "../witness/receipting.js";
+import { type GroupIpexBegun, type GroupIpexOperations } from "./group-ipex.js";
+import type { IpexV2BodyOptions } from "./ipex-building.js";
+import { type CredentialViews, type DisclosureSelection } from "./ipex-discloser.js";
+import type { IssuanceDelivery } from "./issuance.js";
+/** How long delivery failures may last on an exchange with no deadline (an Apply, an Agree) before it reads `failed`. */
+export declare const PRESENTATION_RETRY_BOUND_MS = 600000;
+/** The signed IPEX message a presentation operation sends. */
+export type PresentationVerb = "apply" | "offer" | "agree" | "spurn" | "grant";
+/** Terminal states that are not delivery; each carries a reason. */
+export type PresentationEndState = "abandoned" | "interrupted" | "expired" | "failed";
+/** The peer's stored answer to a delivered exchange, read from the retained response index. */
+export interface PresentationResponse {
+    said: string;
+    route: string | null;
+}
+/** Status of one presentation, discriminated on `state`. A pure read. */
+export type PresentationStatus = {
+    state: "active";
+    verb: PresentationVerb;
+    phase: "delivering";
+    deadline?: string;
+    /** Present while a delivery is failing and being retried with a doubling delay. */
+    failure?: DeliveryFailure;
+} | {
+    state: "done";
+    verb: PresentationVerb;
+    phase: "delivered";
+    /** Where the transport reached; known only to the process that delivered it. */
+    deliveries?: readonly string[];
+    response?: PresentationResponse;
+} | {
+    state: PresentationEndState;
+    verb: PresentationVerb;
+    reason: string;
+};
+/** Narrow collaborators of the presentation owner. Hosts adapt their runtime to this once. */
+export interface PresentationDeps {
+    readonly hby: Habery;
+    /** Registry environment: its public store and the local presentation registries by name. */
+    readonly rgy: Pick<Regery, "store" | "registryByName">;
+    readonly exc: Exchanger;
+    /** Receipt collector for an anchored exchange; its genus selects the witness protocol version. */
+    readonly receiptor: Receiptor;
+    /** Local intake of what this identifier signs. */
+    readonly reactor: Pick<Reactor, "processBytes">;
+    readonly protocol: Pick<ProtocolProcessor, "processEscrowsOnce">;
+    readonly delivery: IssuanceDelivery;
+    /** Delivery retry delays; the production policy when absent. */
+    readonly retry?: Readonly<RetryPolicy>;
+    /** Same clock the exchanger was composed with. */
+    readonly clock: RuntimeClock;
+    /** Embedder inventory for selecting an issued credential or a retained Grant. */
+    readonly views?: CredentialViews;
+    /** Derivation coordinates, needed only for a selection with `derive`. */
+    readonly derived?: DerivedUpdateStore;
+    readonly changes?: ChangeSink;
+}
+/** Body options of a selecting message, plus the presentation registry that carries a Grant's proof. */
+export interface PresentationOptions extends IpexV2BodyOptions {
+    priorSaid?: string;
+    auths?: WitnessAuthMap;
+    /** Alias of a local registry whose presented-state update this Grant anchors. */
+    presentationRegistry?: string;
+}
+/** What the user presents. Selecting verbs name a credential view; replies name the exchange they answer. */
+export type PresentationInput = {
+    verb: "offer";
+    hab: Hab;
+    selection: DisclosureSelection;
+    options: PresentationOptions;
+} | {
+    verb: "grant";
+    hab: Hab;
+    selection: DisclosureSelection;
+    options: PresentationOptions;
+} | {
+    verb: "apply";
+    hab: Hab;
+    options: IpexV2BodyOptions;
+} | {
+    verb: "agree" | "spurn";
+    hab: Hab;
+    /** SAID of the accepted, authenticated exchange being answered. */
+    prior: string;
+    message?: string;
+    recipient?: string;
+    auths?: WitnessAuthMap;
+};
+/** A signed exchange accepted locally, with the bytes in delivery order. */
+export interface PreparedPresentation {
+    exn: SerderKERI;
+    /** Sender KEL, proof support and the exchange. */
+    wire: Uint8Array;
+    recipient: string;
+}
+/** What `present` selected. */
+export interface PresentationBegun {
+    said: string;
+    recipient: string;
+    /** The signed bytes, for a host that also wants to file them. */
+    wire: Uint8Array;
+}
+/** A signed exchange to deliver: what the sender, the recipient and the transport need. */
+interface QueuedPresentation {
+    /** SAID of the signed exchange. */
+    readonly said: string;
+    readonly verb: PresentationVerb;
+    readonly hab: Hab;
+    /** The identifier whose endpoint sends it: the sender, or a group's local member. */
+    readonly src?: string;
+    readonly recipient: string;
+    readonly wire: Uint8Array;
+    /** The exchange's original deadline (ISO 8601), for an exchange that has one. */
+    readonly deadline?: string;
+}
+/** One delivery in progress; exists only while it is live in this process. */
+interface LivePresentation extends QueuedPresentation {
+    readonly expires: bigint | null;
+    /** The signed bytes, delivered with retry; a failure waits for a later pass instead of ending the delivery. */
+    readonly outbox: DeliveryOutbox;
+    /** A delivery is running; overlapping `processOnce` calls skip it. */
+    busy: boolean;
+}
+/** What a presentation that ended or delivered in this process reports until the process ends. */
+type SettledPresentation = {
+    verb: PresentationVerb;
+    state: PresentationEndState;
+    reason: string;
+} | {
+    verb: PresentationVerb;
+    state: "done";
+    deliveries: readonly string[];
+};
+/** The live deliveries table and its driver. One per host runtime; every identifier may present through it. */
+export declare class PresentationOperations {
+    readonly deps: PresentationDeps;
+    /** Deliveries live in this process. Internal to this module's functions. */
+    readonly live: Map<string, LivePresentation>;
+    /** Presentations that delivered or ended in this process; not durable, see the module doc. */
+    readonly settled: Map<string, SettledPresentation>;
+    constructor(deps: PresentationDeps);
+    /** Whether the live presentation `said` still holds a message the transport has not taken. */
+    owes(said: string): boolean;
+    /** Whether a delivery is live. */
+    active(): boolean;
+    /** Advance every live delivery by one pass. */
+    processOnce(): Operation<void>;
+    /** End a live delivery: drop it, remember why until the process ends, tell the sink. */
+    end(op: LivePresentation, state: PresentationEndState, reason: string): void;
+    /** Resolves only when the deadline passes; never resolves for an exchange without one. */
+    private timer;
+    /**
+     * One attempt: a failure keeps the bytes and is retried after a doubling delay until the exchange's deadline,
+     * or, for an exchange with none, until failures have lasted {@link PRESENTATION_RETRY_BOUND_MS}.
+     */
+    private deliver;
+}
+/**
+ * Sign the selected message and take it into local authenticated intake, without recording an operation or
+ * delivering. This is the whole consent: the returned bytes are final.
+ *
+ * @throws ValidationError for a group identifier, an unknown presentation registry, a selection the discloser
+ * refuses, or an exchange that does not reach authenticated intake.
+ */
+export declare function preparePresentation(deps: PresentationDeps, input: PresentationInput): Operation<PreparedPresentation>;
+/** What a group presents and how: the view, the Grant body options and the registry update's counseling. */
+export interface GroupPresentationInput {
+    hab: Hab;
+    selection: DisclosureSelection;
+    options: PresentationOptions;
+    /** False when the caller takes the completed Grant itself (a file) and the lead must not send it. */
+    deliver?: boolean;
+    /** Counseling choices for the registry update's anchor. */
+    counsel?: CounselInputs;
+}
+/**
+ * A group's consent to present an accepted Grant or credential view: freezes the Grant body once (selection and
+ * authorization) and proposes it as a group-authored message, so the other members list and approve it with
+ * `approveGroupIpex` and the elected lead delivers the completed Grant. Returns after local commit.
+ *
+ * With `options.presentationRegistry` the Grant carries a presented-state proof: this member also proposes the
+ * registry update that anchors it (`proposeRegistryEvent`; the other members approve that proposal with
+ * `approveGroupProposal`), and the owner signs this member's contribution to the Grant once the group has accepted
+ * the update, under this same consent.
+ *
+ * @throws ValidationError for an identifier that is not a local group, an unknown presentation registry, a
+ * selection the discloser refuses, or a message awaiting authenticating dependencies.
+ */
+export declare function proposeGroupPresentation(deps: PresentationDeps, groupIpex: GroupIpexOperations, { hab, selection, options, deliver, counsel }: GroupPresentationInput): Operation<GroupIpexBegun>;
+/** A completed prepared Grant ready for the elected lead to deliver. */
+export interface PreparedGrantDelivery {
+    hab: Hab;
+    said: string;
+    /** Proof support and the completed Grant, in delivery order. */
+    delivery: Uint8Array;
+}
+/**
+ * Deliver a group's completed prepared Grant ({@link resumePresentationFile}): queues the delivery bytes for
+ * `processOnce` when the local member is the elected lead, with the retry and deadline of any presentation. Signs
+ * nothing. Returns null for a member that is not the lead.
+ */
+export declare function deliverPreparedGrant(ops: PresentationOperations, { hab, said, delivery }: PreparedGrantDelivery): PresentationBegun | null;
+/**
+ * The user's consent to present: signs and takes the message into local intake ({@link preparePresentation}),
+ * records the operation and queues the signed bytes for `processOnce` to deliver. Returns after local commit.
+ */
+export declare function present(ops: PresentationOperations, input: PresentationInput): Operation<PresentationBegun>;
+/**
+ * Pure read of one presentation: the live table, what ended or delivered in this process, and what the stored
+ * exchanges prove (the peer's answer, when one was stored; see the module doc for what a reload loses). A
+ * signed exchange no live delivery holds and nobody answered reads `interrupted`, or `expired` past its
+ * deadline; that is a statement, not a write.
+ *
+ * @throws ValidationError when `said` is not a presentation exchange a local identifier signed.
+ */
+export declare function presentationStatus(ops: PresentationOperations, said: string): PresentationStatus;
+/** Options for {@link waitForPresentation}. */
+export interface PresentationWaitOptions {
+    /** Wall-clock budget. */
+    timeoutMs: number;
+    clock?: RuntimeClock;
+    /** Settle on this instead of any non-active state. */
+    until?: (status: PresentationStatus) => boolean;
+}
+/**
+ * Observe until the presentation is delivered or ended, or the budget expires. Starts no worker and drives
+ * nothing: someone else must call `processOnce`.
+ */
+export declare function waitForPresentation(ops: PresentationOperations, said: string, { timeoutMs, clock, until }: PresentationWaitOptions): Operation<WaitResult<PresentationStatus>>;
+/**
+ * Local abandon: stop delivering and read `abandoned` until the process ends. Does not message the peer and
+ * does not retract an exchange already delivered. Does nothing to a presentation that is already delivered
+ * or ended.
+ *
+ * @throws ValidationError when `said` is not a presentation exchange a local identifier signed.
+ */
+export declare function abandonPresentation(ops: PresentationOperations, said: string, reason?: string): void;
+/**
+ * Deliver a presentation again after a restart, or after delivery failed or was abandoned: rebuilds the wire
+ * of the stored signed exchange from its retained signatures or source seal and nests, so the bytes are the
+ * ones first delivered and nothing is signed. Queues them like `present`, with a fresh outbox; return
+ * is after the queueing, not after delivery.
+ *
+ * @throws ValidationError for an exchange no local identifier signed, one the peer already answered, one past
+ * its deadline, one already being delivered, or one whose retained factors no longer authenticate.
+ */
+export declare function resendPresentation(ops: PresentationOperations, said: string): Operation<PresentationBegun>;
+export {};
+//# sourceMappingURL=presenting.d.ts.map

package/types/app/ipex/presenting.d.ts.map

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

package/types/app/ipex/receive-issuance.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The holder's side of a credential, as workflows a host calls instead of sequencing the library itself.
+ *
+ * - {@link admitAndDeliver}: the Admit consent, the host's one step between accepting the Admit and sending it
+ *   (`onAdmitted`: a wallet records its consent in its inventory there), and delivery within a budget. It
+ *   works for any accepted v2 Grant, so a host that never ran the DH exchange uses it alone.
+ * - {@link receiveIssuance}: the whole individual path for a pending Grant: approve the DH exchange, wait for the
+ *   issuer to finish it, then {@link admitAndDeliver}. Calling it again for a Grant that timed out resumes at
+ *   the step it reached.
+ *
+ * Both follow the workflow contract: they may sign (the consents), never wait on a remote without a budget, and
+ * return remote and time-driven outcomes as values. Group identifiers use the group paths in `group-issuance.ts`.
+ */
+import type { Versionage } from "cesr-ts";
+import type { Operation } from "effection";
+import type { WitnessAuthMap } from "../witness/receipting.js";
+import { type AdmitDeps, type IssuanceAdmit, type IssuanceEndState, type IssuanceOperations, type IssuanceStatus } from "./issuance.js";
+/** Default budget of delivering an Admit, in milliseconds. */
+export declare const ADMIT_DELIVERY_TIMEOUT_MS = 30000;
+/** The host's step between accepting the Admit locally and delivering it. It runs once, before delivery. */
+export type OnAdmitted = (admitted: IssuanceAdmit) => Operation<void>;
+/** Whether the Admit reached the issuer. The Admit is accepted locally either way. */
+export type AdmitDeliveryOutcome = {
+    state: "delivered";
+    to: string[];
+} | {
+    state: "undelivered";
+    reason: string;
+};
+/** Inputs of {@link admitAndDeliver}. */
+export interface AdmitAndDeliverInput {
+    /** SAID of the accepted Grant; the holder is its recipient. */
+    grant: string;
+    message?: string;
+    gvrsn?: Versionage;
+    auths?: WitnessAuthMap;
+    /** False when the caller takes the signed bytes itself (a file) and nothing is sent. Default true. */
+    deliver?: boolean;
+    /** Budget of the delivery. Default {@link ADMIT_DELIVERY_TIMEOUT_MS}. */
+    deliveryTimeoutMs?: number;
+    onAdmitted?: OnAdmitted;
+}
+/** What {@link admitAndDeliver} reports: the signed Admit and what delivery did. */
+export interface AdmitAndDeliverOutcome {
+    admitted: IssuanceAdmit;
+    /** `undelivered` with the reason when delivery was not asked for, failed or ran out of budget. */
+    delivery: AdmitDeliveryOutcome;
+}
+/**
+ * Sign and accept the Admit, run `onAdmitted`, then deliver within the budget. A failed or expired delivery is a
+ * value; the Admit stays accepted and `rebuildIssuanceAdmit` can send it again.
+ *
+ * @throws ValidationError as {@link admitIssuance} does, and whatever `onAdmitted` throws.
+ */
+export declare function admitAndDeliver(deps: AdmitDeps, input: AdmitAndDeliverInput): Operation<AdmitAndDeliverOutcome>;
+/** Inputs of {@link receiveIssuance}. */
+export interface ReceiveIssuanceInput extends AdmitAndDeliverInput {
+    /** Budget of the wait for the issuer to finish the exchange. */
+    timeoutMs: number;
+}
+/** A terminal state of an issuance other than completion. */
+export type EndedIssuanceStatus = Extract<IssuanceStatus, {
+    state: IssuanceEndState;
+}>;
+/** Result of {@link receiveIssuance}. */
+export type ReceiveIssuanceOutcome = AdmittedIssuance | EndedIssuance | TimedOutIssuance;
+/**
+ * The credential is admitted. `admit` is the Admit's SAID. `admitted` carries the signed bytes of this call's
+ * Admit, and is absent when an earlier call admitted the Grant (then `delivery` is `undelivered` and says so).
+ */
+export interface AdmittedIssuance {
+    outcome: "admitted";
+    grant: string;
+    admit: string;
+    admitted?: IssuanceAdmit;
+    delivery: AdmitDeliveryOutcome;
+}
+/** The exchange stopped before an Admit. */
+export interface EndedIssuance {
+    outcome: "ended";
+    grant: string;
+    status: EndedIssuanceStatus;
+}
+/** The issuer has not finished within `timeoutMs`; the operation is live and calling again resumes it. */
+export interface TimedOutIssuance {
+    outcome: "timed-out";
+    grant: string;
+    timeoutMs: number;
+    status: IssuanceStatus;
+}
+/**
+ * The individual holder's whole path for a Grant addressed to a local identifier: approve the DH exchange when it is pending,
+ * wait for the issuer to finish it, then admit and deliver ({@link admitAndDeliver}).
+ *
+ * @throws ValidationError for a Grant that is not addressed to a local identifier, one this runtime issued, or a
+ * group identifier.
+ */
+export declare function receiveIssuance(ops: IssuanceOperations, input: ReceiveIssuanceInput): Operation<ReceiveIssuanceOutcome>;
+//# sourceMappingURL=receive-issuance.d.ts.map

package/types/app/ipex/receive-issuance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receive-issuance.d.ts","sourceRoot":"","sources":["../../../src/app/ipex/receive-issuance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAI3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EACL,KAAK,SAAS,EAId,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EAGpB,MAAM,eAAe,CAAC;AAEvB,8DAA8D;AAC9D,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD,4GAA4G;AAC5G,MAAM,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,aAAa,KAAK,SAAS,CAAC,IAAI,CAAC,CAAC;AAEtE,sFAAsF;AACtF,MAAM,MAAM,oBAAoB,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnH,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,sGAAsG;IACtG,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,oFAAoF;AACpF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,aAAa,CAAC;IACxB,kGAAkG;IAClG,QAAQ,EAAE,oBAAoB,CAAC;CAChC;AAKD;;;;;GAKG;AACH,wBAAiB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,oBAAoB,GAAG,SAAS,CAAC,sBAAsB,CAAC,CA0BhH;AAED,yCAAyC;AACzC,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB;IAChE,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,6DAA6D;AAC7D,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,cAAc,EAAE;IAAE,KAAK,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAAC;AAEvF,yCAAyC;AACzC,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,GAAG,aAAa,GAAG,gBAAgB,CAAC;AAEzF;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,EAAE,oBAAoB,CAAC;CAChC;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,0GAA0G;AAC1G,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAiB,eAAe,CAC9B,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,oBAAoB,GAC1B,SAAS,CAAC,sBAAsB,CAAC,CA6BnC"}