@sempdev/semp 0.4.3

package/dist/transparency/sign.js

@@ -0,0 +1,140 @@
+/**
+ * STH signing + verification + freshness checks per
+ * TRANSPARENCY.md §2.3.
+ *
+ * @module
+ */
+import { signSignedDoc, verifySignedDoc } from "../keys/index.js";
+import { MaxSTHFreshnessMs, } from "./types.js";
+/** Domain-separation prefix per ENVELOPE.md §4.3. */
+export const TransparencySTHPrefix = "SEMP-TRANSPARENCY-STH:";
+/** Only signature algorithm defined for STH signatures. */
+export const SignatureAlgorithmEd25519 = "ed25519";
+/**
+ * Build and Ed25519-sign an STH per §2.3. Pre-populates
+ * `signature.{algorithm,key_id}` so the canonical bytes cover them
+ * (defense against algorithm/issuer downgrade).
+ */
+export function signSTH(input) {
+    if (input.domainKeyId === "") {
+        throw new Error("transparency: empty domain key_id");
+    }
+    validateSTH(input.sth);
+    const preSign = {
+        ...input.sth,
+        signature: {
+            algorithm: SignatureAlgorithmEd25519,
+            key_id: input.domainKeyId,
+            value: "",
+        },
+    };
+    const { signedJSON, signatureB64 } = signSignedDoc({
+        preSignJSON: preSign,
+        seed: input.domainSigningSeed,
+        signaturePath: "signature.value",
+        prefix: TransparencySTHPrefix,
+    });
+    return {
+        sth: signedJSON,
+        signatureB64,
+    };
+}
+/**
+ * Ed25519-verify an STH's signature against `domainPub`. Returns
+ * true on success. Does NOT enforce staleness; pair with
+ * {@link checkSTHFresh} for the §2.3 1-hour bound.
+ */
+export function verifySTH(sth, domainPub) {
+    validateSTH(sth);
+    if (sth.signature.value === "") {
+        return false;
+    }
+    const { ok } = verifySignedDoc({
+        signedJSON: sth,
+        publicKey: domainPub,
+        signaturePath: "signature.value",
+        prefix: TransparencySTHPrefix,
+    });
+    return ok;
+}
+/**
+ * Enforce §2.3 freshness: reject STHs whose timestamp is more than
+ * {@link MaxSTHFreshnessMs} old. Returns true when the STH is
+ * fresh under the supplied `now`.
+ */
+export function checkSTHFresh(sth, now) {
+    const ts = Date.parse(sth.timestamp);
+    if (Number.isNaN(ts)) {
+        return false;
+    }
+    return now.getTime() - ts <= MaxSTHFreshnessMs;
+}
+/** Structural validation of `sth` per §2.3. Throws on first violation. */
+export function validateSTH(sth) {
+    if (!Number.isInteger(sth.log_size) || sth.log_size < 0) {
+        throw new Error(`transparency: STH log_size ${sth.log_size} MUST be >= 0`);
+    }
+    if (typeof sth.root_hash !== "string" || sth.root_hash === "") {
+        throw new Error("transparency: STH missing root_hash");
+    }
+    if (typeof sth.timestamp !== "string" || sth.timestamp === "") {
+        throw new Error("transparency: STH missing timestamp");
+    }
+    if (Number.isNaN(Date.parse(sth.timestamp))) {
+        throw new Error("transparency: STH timestamp is not ISO 8601");
+    }
+    if (typeof sth.signature?.algorithm !== "string") {
+        throw new Error("transparency: STH missing signature.algorithm");
+    }
+    if (typeof sth.signature?.key_id !== "string") {
+        throw new Error("transparency: STH missing signature.key_id");
+    }
+    if (typeof sth.signature?.value !== "string") {
+        throw new Error("transparency: STH signature.value must be a string");
+    }
+}
+/** Structural validation of a {@link LogEntry} per §2.2. Throws on first violation. */
+export function validateLogEntry(e) {
+    if (e.event !== "publish" && e.event !== "rotate" && e.event !== "revoke") {
+        throw new Error(`transparency: log entry event ${JSON.stringify(e.event)} is invalid`);
+    }
+    for (const f of ["user_id", "key_id", "algorithm", "public_key"]) {
+        if (typeof e[f] !== "string" || e[f] === "") {
+            throw new Error(`transparency: log entry missing ${f}`);
+        }
+    }
+    if (e.key_type !== "identity" && e.key_type !== "encryption") {
+        throw new Error(`transparency: log entry key_type ${JSON.stringify(e.key_type)} is invalid`);
+    }
+    if (typeof e.created !== "string" || e.created === "" || Number.isNaN(Date.parse(e.created))) {
+        throw new Error("transparency: log entry missing or invalid created");
+    }
+    if (typeof e.log_timestamp !== "string" ||
+        e.log_timestamp === "" ||
+        Number.isNaN(Date.parse(e.log_timestamp))) {
+        throw new Error("transparency: log entry missing or invalid log_timestamp");
+    }
+    switch (e.event) {
+        case "rotate":
+            if (e.supersedes === undefined || e.supersedes === null || e.supersedes === "") {
+                throw new Error("transparency: rotate event MUST set supersedes");
+            }
+            break;
+        case "publish":
+            if (e.supersedes !== undefined && e.supersedes !== null && e.supersedes !== "") {
+                throw new Error("transparency: publish event MUST NOT set supersedes");
+            }
+            break;
+        case "revoke":
+            if (e.revoked_at === undefined || e.revoked_at === null || e.revoked_at === "") {
+                throw new Error("transparency: revoke event MUST set revoked_at");
+            }
+            if (e.revoked_reason === undefined ||
+                e.revoked_reason === null ||
+                e.revoked_reason === "") {
+                throw new Error("transparency: revoke event MUST set revoked_reason");
+            }
+            break;
+    }
+}
+//# sourceMappingURL=sign.js.map

package/dist/transparency/sign.js.map

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

package/dist/transparency/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Wire-record types for SEMP key transparency per TRANSPARENCY.md.
+ *
+ * A domain supporting key transparency maintains a single
+ * append-only RFC 6962 Merkle tree of key events. Clients fetching
+ * keys augment the response with a Signed Tree Head (STH) and an
+ * inclusion proof so a third party can verify the published key
+ * matches the same key the domain has shown to every other client.
+ *
+ * @module
+ */
+/** Wire format version for log entries. */
+export declare const LogEntryVersion = "1.0.0";
+/** Wire format version for signed tree heads. */
+export declare const SignedTreeHeadVersion = "1.0.0";
+/** RFC 6962 leaf domain-separation byte. */
+export declare const LeafPrefix = 0;
+/** RFC 6962 interior-node domain-separation byte. */
+export declare const InteriorPrefix = 1;
+/**
+ * STH staleness ceiling per §2.3 — verifiers reject STHs whose
+ * timestamp is more than this old.
+ */
+export declare const MaxSTHFreshnessMs: number;
+/** Kind of key event recorded as a leaf, per §2.2. */
+export type LogEntryEvent = "publish" | "rotate" | "revoke";
+/** SEMP key kind being recorded, per §2.2 + KEY.md §1. */
+export type LogKeyType = "identity" | "encryption";
+/**
+ * One leaf of the transparency Merkle tree per §2.2. Insertion
+ * order is the leaf's position; the log MUST NOT remove or
+ * reorder leaves.
+ */
+export interface LogEntry {
+    event: LogEntryEvent;
+    user_id: string;
+    key_id: string;
+    key_type: LogKeyType;
+    algorithm: string;
+    /** Base64-encoded public key. */
+    public_key: string;
+    /** ISO 8601 UTC timestamp. */
+    created: string;
+    /** ISO 8601 UTC; nullable. */
+    expires?: string | null;
+    /** Populated only on `revoke`. */
+    revoked_at?: string | null;
+    /** Populated only on `revoke`. */
+    revoked_reason?: string | null;
+    /** Populated only on `rotate` — names the key being rotated out. */
+    supersedes?: string | null;
+    /** ISO 8601 UTC; the log's timestamp for this insertion. */
+    log_timestamp: string;
+}
+/** Reusable signature block per §2.3. */
+export interface TransparencySignature {
+    algorithm: string;
+    key_id: string;
+    /** Base64 signature. */
+    value: string;
+}
+/**
+ * Periodic published commitment per §2.3. Domains MUST publish a
+ * fresh STH at least every hour; verifiers reject STHs older than
+ * {@link MaxSTHFreshnessMs}.
+ */
+export interface SignedTreeHead {
+    log_size: number;
+    /** Base64 of the 32-byte SHA-256 root. */
+    root_hash: string;
+    /** ISO 8601 UTC timestamp. */
+    timestamp: string;
+    signature: TransparencySignature;
+}
+/**
+ * §3.1 proof that `leaf_hash` sits at `leaf_index` in a tree of
+ * size `log_size` whose root is published by an STH.
+ */
+export interface InclusionProof {
+    log_size: number;
+    /** Base64 of 32-byte SHA-256 leaf hash. */
+    leaf_hash: string;
+    leaf_index: number;
+    /** Base64 sibling hashes, root-ward order. */
+    path: string[];
+}
+/**
+ * §3.2 proof that the tree of size `from_size` is a prefix of the
+ * tree of size `to_size`.
+ */
+export interface ConsistencyProof {
+    from_size: number;
+    to_size: number;
+    /** Base64 hashes per RFC 6962 §2.1.2. */
+    path: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/transparency/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/transparency/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,2CAA2C;AAC3C,eAAO,MAAM,eAAe,UAAU,CAAC;AAEvC,iDAAiD;AACjD,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAE7C,4CAA4C;AAC5C,eAAO,MAAM,UAAU,IAAO,CAAC;AAE/B,qDAAqD;AACrD,eAAO,MAAM,cAAc,IAAO,CAAC;AAEnC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAAiB,CAAC;AAEhD,sDAAsD;AACtD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5D,0DAA0D;AAC1D,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,YAAY,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,UAAU,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kCAAkC;IAClC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,yCAAyC;AACzC,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,qBAAqB,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB"}

package/dist/transparency/types.js

@@ -0,0 +1,25 @@
+/**
+ * Wire-record types for SEMP key transparency per TRANSPARENCY.md.
+ *
+ * A domain supporting key transparency maintains a single
+ * append-only RFC 6962 Merkle tree of key events. Clients fetching
+ * keys augment the response with a Signed Tree Head (STH) and an
+ * inclusion proof so a third party can verify the published key
+ * matches the same key the domain has shown to every other client.
+ *
+ * @module
+ */
+/** Wire format version for log entries. */
+export const LogEntryVersion = "1.0.0";
+/** Wire format version for signed tree heads. */
+export const SignedTreeHeadVersion = "1.0.0";
+/** RFC 6962 leaf domain-separation byte. */
+export const LeafPrefix = 0x00;
+/** RFC 6962 interior-node domain-separation byte. */
+export const InteriorPrefix = 0x01;
+/**
+ * STH staleness ceiling per §2.3 — verifiers reject STHs whose
+ * timestamp is more than this old.
+ */
+export const MaxSTHFreshnessMs = 60 * 60 * 1000;
+//# sourceMappingURL=types.js.map

package/dist/transparency/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/transparency/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,2CAA2C;AAC3C,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC;AAEvC,iDAAiD;AACjD,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC;AAE7C,4CAA4C;AAC5C,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC;AAE/B,qDAAqD;AACrD,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;AAEnC;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC"}

package/dist/transport/h2.d.ts

@@ -0,0 +1,163 @@
+/**
+ * HTTP/2 transport binding per TRANSPORT.md §4.2.
+ *
+ * Unlike WebSocket — which gives us a single bidirectional pipe —
+ * the SEMP HTTP/2 binding is a collection of HTTP endpoints with
+ * path-based routing:
+ *
+ *  - `POST /v1/discovery`     — discovery lookup
+ *  - `POST /v1/keys`          — key request
+ *  - `POST /v1/handshake`     — handshake step
+ *  - `POST /v1/envelope`      — envelope submit
+ *  - `POST /v1/session/{id}`  — long-lived bidirectional session
+ *                                stream (server pushes via SSE,
+ *                                client posts additional messages
+ *                                to the same URL)
+ *
+ * This module exposes:
+ *
+ *  - {@link h2Post}: a typed JSON POST helper for the four
+ *    request/response endpoints. Surfaces the `Semp-Session-Id`
+ *    response header to the caller.
+ *  - {@link dialH2Session}: opens a long-lived POST to
+ *    `/v1/session/{id}` and returns a {@link Transport} whose
+ *    `receive()` reads SSE events from the open stream and `send()`
+ *    POSTs additional messages to the same URL.
+ *  - {@link encodeSSE} / {@link decodeSSE}: encode/decode helpers
+ *    for callers that want to roll their own.
+ *
+ * @module
+ */
+import type { DialOptions, Transport } from "./transport.js";
+/** Header name the server sets on its response to handshake init. */
+export declare const SempSessionIdHeader = "Semp-Session-Id";
+/**
+ * Minimal subset of the WHATWG fetch surface this module depends on.
+ * Both Node 22+ and browsers ship `fetch` matching this shape. Tests
+ * pass a fake to drive deterministic responses.
+ */
+export type H2FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: Uint8Array | string;
+    signal?: AbortSignal;
+}) => Promise<H2Response>;
+/** Minimal Response surface this module consumes. */
+export interface H2Response {
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    /** Returns the full body as bytes. Used for one-shot request/response calls. */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /**
+     * Async byte stream. Used for long-lived SSE session streams. May be
+     * undefined for stub responses; in production it is the
+     * `Response.body` `ReadableStream<Uint8Array>` (Node 22+ + browsers
+     * support `for await` on this directly).
+     */
+    body?: AsyncIterable<Uint8Array> | {
+        getReader(): {
+            read(): Promise<{
+                done: boolean;
+                value?: Uint8Array;
+            }>;
+        };
+    } | null;
+}
+/** Inputs to {@link h2Post}. */
+export interface H2PostOptions extends DialOptions {
+    /** Override the fetch implementation. Defaults to `globalThis.fetch`. */
+    fetchImpl?: H2FetchLike;
+    /**
+     * `Semp-Session-Id` header to include on the request. Set on
+     * subsequent handshake steps so the server can correlate them with
+     * the session it minted in step 1.
+     */
+    sessionId?: string;
+    /** Additional headers to merge in. */
+    headers?: Record<string, string>;
+}
+/** Result of a successful {@link h2Post}. */
+export interface H2PostResult {
+    /** Decoded response body. */
+    body: Uint8Array;
+    /** HTTP status (always 2xx for `h2Post` resolutions). */
+    status: number;
+    /** `Semp-Session-Id` response header, if any. */
+    sessionId: string | null;
+}
+/**
+ * POST a SEMP message to one of the request/response endpoints
+ * (`/v1/handshake`, `/v1/keys`, `/v1/envelope`, `/v1/discovery`).
+ * Resolves with the response body and the `Semp-Session-Id` header.
+ *
+ * Translates HTTP status codes per §4.2.2:
+ *  - 2xx: resolves successfully.
+ *  - 400, 413, 429, 503: rejects with a structured error.
+ *  - other non-2xx: rejects with the status as the message.
+ */
+export declare function h2Post(url: string, message: Uint8Array, opts?: H2PostOptions): Promise<H2PostResult>;
+/** Inputs to {@link dialH2Session}. */
+export interface DialH2SessionOptions extends DialOptions {
+    /** Override the fetch implementation. Defaults to `globalThis.fetch`. */
+    fetchImpl?: H2FetchLike;
+    /**
+     * URL of the session endpoint, including the session id segment —
+     * for example `https://semp.example.com/v1/session/01J...`. The
+     * caller composes this from the configuration's
+     * `endpoints.client.h2` base + the session id.
+     */
+    sessionUrl: string;
+    /**
+     * Optional initial body for the long-lived POST. Per §4.2.4 the
+     * client opens a POST to `/v1/session/{id}`; the body is empty by
+     * default but the caller MAY pass a stream of pre-buffered messages.
+     */
+    initialBody?: Uint8Array;
+}
+/**
+ * Open a long-lived POST to the session URL and return a
+ * {@link Transport} whose `receive()` reads SSE events from that
+ * response and `send()` POSTs additional messages to the same URL.
+ *
+ * Per TRANSPORT.md §4.2.4: each `data:` line in the response carries
+ * a complete SEMP JSON message; blank lines delimit events.
+ */
+export declare function dialH2Session(opts: DialH2SessionOptions): Promise<Transport>;
+/**
+ * Encode a single SEMP message as an SSE event. Each line in the
+ * message body produces a `data:` line; the event is terminated with
+ * a single blank line.
+ *
+ * The encoder normalizes CR / CRLF line terminators to LF before
+ * emitting each `data:` line. SEMP payloads are JSON documents whose
+ * control bytes are escaped (`\r`, `\n`), so the wire form never
+ * actually carries a literal CR or LF — but be defensive.
+ */
+export declare function encodeSSE(message: string): string;
+/**
+ * Decode SSE events from a string buffer. Each call returns the next
+ * complete event's `data` payload (or `null` if no complete event is
+ * buffered yet). Stateful — the buffer accumulates partial input.
+ */
+export declare class SSEDecoder {
+    private buffer;
+    private dataLines;
+    /** Append more bytes to the buffer. */
+    push(chunk: string): void;
+    /**
+     * Return the data payload of the next complete event, or `null` if
+     * none is buffered. Repeatedly call until `null` to drain.
+     */
+    next(): string | null;
+    /**
+     * Flush any pending data lines as a final event. Called on EOF when
+     * the underlying stream ends without a trailing blank line.
+     */
+    flush(): string | null;
+}
+/** Decode all events present in a complete (already-buffered) SSE blob. */
+export declare function decodeSSE(blob: string): string[];
+//# sourceMappingURL=h2.d.ts.map

package/dist/transport/h2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"h2.d.ts","sourceRoot":"","sources":["../../src/transport/h2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE7D,qEAAqE;AACrE,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KACE,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB,qDAAqD;AACrD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC9C,gFAAgF;IAChF,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IACpC;;;;;OAKG;IACH,IAAI,CAAC,EACD,aAAa,CAAC,UAAU,CAAC,GACzB;QAAE,SAAS,IAAI;YAAE,IAAI,IAAI,OAAO,CAAC;gBAAE,IAAI,EAAE,OAAO,CAAC;gBAAC,KAAK,CAAC,EAAE,UAAU,CAAA;aAAE,CAAC,CAAA;SAAE,CAAA;KAAE,GAC3E,IAAI,CAAC;CACV;AAKD,gCAAgC;AAChC,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,yEAAyE;IACzE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,6BAA6B;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,MAAM,CAC1B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,UAAU,EACnB,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,YAAY,CAAC,CAsCvB;AAoBD,uCAAuC;AACvC,MAAM,WAAW,oBAAqB,SAAQ,WAAW;IACvD,yEAAyE;IACzE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,UAAU,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,SAAS,CAAC,CAmFpB;AAKD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQjD;AA0BD;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,SAAS,CAAgB;IAEjC,uCAAuC;IACvC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIzB;;;OAGG;IACH,IAAI,IAAI,MAAM,GAAG,IAAI;IA6CrB;;;OAGG;IACH,KAAK,IAAI,MAAM,GAAG,IAAI;CAQvB;AAED,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAgBhD"}