@sempdev/semp 0.4.3

package/dist/delivery/policy_state.js

@@ -0,0 +1,293 @@
+/**
+ * Per-user authoritative policy view per DELIVERY.md §7.2.
+ *
+ * `applyPolicyMessage` takes a verified {@link UserPolicyMessage} and
+ * either applies every operation atomically (advancing
+ * `policy_version`) or rejects the whole message without mutating
+ * state. Atomicity is the §7.2 guarantee: a single unrecognized kind
+ * rejects the whole message; unrelated operations in the same
+ * message MUST NOT be applied.
+ *
+ * Apply does NOT verify the signature on the message — callers MUST
+ * run {@link verifyUserPolicyMessage} before invoking
+ * {@link PolicyState.apply}.
+ *
+ * @module
+ */
+import { PolicyKindAcceptedSender, PolicyKindBlock, PolicyKindFirstContact, validateUserPolicyMessage, } from "./user_policy.js";
+/** §7.3 default rule kinds for v1.0.0. */
+export function defaultPolicyKinds() {
+    return [PolicyKindBlock, PolicyKindAcceptedSender, PolicyKindFirstContact];
+}
+/** Typed error wrapping a structured policy rejection. */
+export class PolicyApplyError extends Error {
+    code;
+    details;
+    name = "PolicyApplyError";
+    constructor(code, details = {}) {
+        super(messageFor(code, details));
+        this.code = code;
+        this.details = details;
+    }
+}
+function messageFor(code, d) {
+    switch (code) {
+        case "policy_kind_unsupported":
+            return `delivery: policy operation[${d.opIndex ?? 0}] kind ${JSON.stringify(d.kind ?? "")} is not supported`;
+        case "policy_op_invalid":
+            return d.detail !== undefined && d.detail !== ""
+                ? `delivery: policy operation[${d.opIndex ?? 0}] is invalid: ${d.detail}`
+                : `delivery: policy operation[${d.opIndex ?? 0}] is invalid`;
+        case "policy_version_stale":
+            return `delivery: submitted policy_version ${d.submittedVersion ?? 0} is not greater than current ${d.currentVersion ?? 0}`;
+    }
+}
+/**
+ * Per-user policy state. Concurrency-safe within a single JS event
+ * loop (no async mutation between read-modify-write).
+ *
+ * Does NOT enforce DELIVERY.md §7.5 encrypted-at-rest storage —
+ * that is the persistence layer's responsibility.
+ */
+export class PolicyState {
+    userIdValue;
+    supportedKinds;
+    policyVersionValue = 0;
+    lastTimestampValue = "";
+    listEntriesMap = new Map();
+    singletonsMap = new Map();
+    /**
+     * @param userId - the account this state belongs to
+     * @param kinds - rule kinds to register; defaults to {@link defaultPolicyKinds}
+     */
+    constructor(userId, kinds) {
+        if (userId === "") {
+            throw new Error("delivery: policy state requires user_id");
+        }
+        const ks = kinds === undefined || kinds.length === 0 ? defaultPolicyKinds() : kinds;
+        this.userIdValue = userId;
+        this.supportedKinds = new Set();
+        for (const k of ks) {
+            if (k === "") {
+                throw new Error("delivery: policy state cannot register empty kind");
+            }
+            this.supportedKinds.add(k);
+        }
+    }
+    /** Account this state belongs to. */
+    userId() {
+        return this.userIdValue;
+    }
+    /** Current policy_version per §7.2. Zero before any message has been applied. */
+    currentVersion() {
+        return this.policyVersionValue;
+    }
+    /** Timestamp of the most recently applied message; `""` before any apply. */
+    lastTimestamp() {
+        return this.lastTimestampValue;
+    }
+    /** Whether `kind` is registered for this state. */
+    supportsKind(kind) {
+        return this.supportedKinds.has(kind);
+    }
+    /** Registered kinds, lexically sorted. */
+    registeredKinds() {
+        return Array.from(this.supportedKinds.values()).sort();
+    }
+    /**
+     * Apply `m` atomically per §7.2. On success advances
+     * `policy_version` and applies every operation. On any per-message
+     * failure throws a {@link PolicyApplyError} with structured
+     * details and leaves state unchanged.
+     *
+     * Caller MUST have run {@link verifyUserPolicyMessage} first.
+     */
+    apply(m) {
+        try {
+            validateUserPolicyMessage(m);
+        }
+        catch (err) {
+            // Translate per-op validate failures into a typed
+            // policy_op_invalid; structural failures propagate as-is.
+            const probe = classifyOpInvalid(err instanceof Error ? err.message : String(err), m);
+            if (probe !== null) {
+                throw new PolicyApplyError("policy_op_invalid", {
+                    kind: probe.kind,
+                    opIndex: probe.opIndex,
+                    detail: probe.detail,
+                });
+            }
+            throw err instanceof Error
+                ? new Error(`delivery: policy validate: ${err.message}`)
+                : new Error(`delivery: policy validate: ${String(err)}`);
+        }
+        if (m.user_id !== this.userIdValue) {
+            throw new Error(`delivery: policy message user_id ${JSON.stringify(m.user_id)} does not match state user_id ${JSON.stringify(this.userIdValue)}`);
+        }
+        // §7.2 ordering: monotonic policy_version with later-timestamp
+        // tie-break for equal versions. A submission whose (version,
+        // timestamp) is not strictly after the current state is stale.
+        const submittedTime = Date.parse(m.timestamp);
+        const lastTime = this.lastTimestampValue === ""
+            ? -Infinity
+            : Date.parse(this.lastTimestampValue);
+        if (m.policy_version < this.policyVersionValue ||
+            (m.policy_version === this.policyVersionValue && submittedTime <= lastTime)) {
+            throw new PolicyApplyError("policy_version_stale", {
+                submittedVersion: m.policy_version,
+                currentVersion: this.policyVersionValue,
+            });
+        }
+        // Pre-flight every op for unsupported-kind before mutating —
+        // §7.2 atomicity.
+        for (let i = 0; i < m.operations.length; i++) {
+            const op = m.operations[i];
+            if (!this.supportedKinds.has(op.kind)) {
+                throw new PolicyApplyError("policy_kind_unsupported", {
+                    kind: op.kind,
+                    opIndex: i,
+                });
+            }
+        }
+        // Apply.
+        for (const op of m.operations) {
+            this.applyOp(op);
+        }
+        this.policyVersionValue = m.policy_version;
+        this.lastTimestampValue = m.timestamp;
+    }
+    applyOp(op) {
+        if (op.kind === PolicyKindFirstContact) {
+            // Singleton: modify is upsert; add/remove rejected upstream.
+            this.singletonsMap.set(op.kind, deepClone(op.entry));
+            return;
+        }
+        // List-shaped kinds.
+        let bucket = this.listEntriesMap.get(op.kind);
+        if (bucket === undefined) {
+            bucket = new Map();
+            this.listEntriesMap.set(op.kind, bucket);
+        }
+        if (op.op === "add" || op.op === "modify") {
+            const id = entryIdFor(op);
+            if (id === "") {
+                // Skip silently rather than inserting under "" so callers
+                // see the no-op rather than a corrupted bucket.
+                return;
+            }
+            bucket.set(id, deepClone(op.entry));
+            return;
+        }
+        if (op.op === "remove") {
+            if (op.entry_id !== undefined && op.entry_id !== "") {
+                bucket.delete(op.entry_id);
+            }
+            return;
+        }
+    }
+    /** Deep copy of the entries currently held for `kind`, keyed by entry id. */
+    listEntries(kind) {
+        const src = this.listEntriesMap.get(kind);
+        const out = {};
+        if (src === undefined) {
+            return out;
+        }
+        for (const [id, v] of src) {
+            out[id] = deepClone(v);
+        }
+        return out;
+    }
+    /**
+     * Copy of the current singleton entry for `kind`, or `undefined`
+     * if none has been set.
+     */
+    singleton(kind) {
+        if (!this.singletonsMap.has(kind)) {
+            return undefined;
+        }
+        return deepClone(this.singletonsMap.get(kind));
+    }
+    /** Deep copy of all state for propagation / persistence. */
+    snapshot() {
+        const list = {};
+        for (const [kind, bucket] of this.listEntriesMap) {
+            const inner = {};
+            for (const [id, v] of bucket) {
+                inner[id] = deepClone(v);
+            }
+            list[kind] = inner;
+        }
+        const singletons = {};
+        for (const [kind, v] of this.singletonsMap) {
+            singletons[kind] = deepClone(v);
+        }
+        return {
+            user_id: this.userIdValue,
+            policy_version: this.policyVersionValue,
+            last_timestamp: this.lastTimestampValue,
+            list_entries: list,
+            singletons,
+        };
+    }
+}
+/**
+ * Extract the entry id from a list-shaped op. For remove/modify the
+ * op's own `entry_id` is authoritative; for add the spec puts the
+ * id inside the entry payload (`id` field, ULID RECOMMENDED per
+ * §7.3).
+ */
+function entryIdFor(op) {
+    if (op.entry_id !== undefined && op.entry_id !== "") {
+        return op.entry_id;
+    }
+    if (typeof op.entry === "object" &&
+        op.entry !== null &&
+        "id" in op.entry) {
+        const id = op.entry.id;
+        if (typeof id === "string") {
+            return id;
+        }
+    }
+    return "";
+}
+/**
+ * Heuristically map a `validateUserPolicyMessage` error to the
+ * triple (op_index, kind, detail) when it originates from a §7.3
+ * op-kind violation. Returns null for structural errors that are
+ * not specific op-kind violations.
+ *
+ * The mapping leans on the validator's stable error-string format
+ * (`delivery: user policy operations[N] ...`) — same approach as
+ * the semp-go reference.
+ */
+function classifyOpInvalid(msg, m) {
+    const prefix = "delivery: user policy operations[";
+    if (!msg.startsWith(prefix)) {
+        return null;
+    }
+    const rest = msg.slice(prefix.length);
+    const end = rest.indexOf("]");
+    if (end < 1) {
+        return null;
+    }
+    const idxStr = rest.slice(0, end);
+    if (!/^\d+$/.test(idxStr)) {
+        return null;
+    }
+    const idx = Number(idxStr);
+    if (idx < 0 || idx >= m.operations.length) {
+        return null;
+    }
+    let detail = rest.slice(end + 1);
+    if (detail.startsWith(" ")) {
+        detail = detail.slice(1);
+    }
+    return { opIndex: idx, kind: m.operations[idx].kind, detail };
+}
+function deepClone(v) {
+    if (v === undefined || v === null) {
+        return v;
+    }
+    return JSON.parse(JSON.stringify(v));
+}
+//# sourceMappingURL=policy_state.js.map

package/dist/delivery/policy_state.js.map

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

package/dist/delivery/queue.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Per-recipient queue state record per DELIVERY.md §2.5.
+ *
+ * The sending server maintains one record per (envelope_id,
+ * recipient) pair; the record is authoritative for what the
+ * sending client displays to the user.
+ *
+ * @module
+ */
+import type { ReasonCode } from "../reasoncodes.js";
+/** Lifecycle position per §2.5. */
+export type QueueRecordState = "queued" | "delivered" | "rejected" | "expired" | "canceled";
+/** Report whether a state is terminal (no further transitions). */
+export declare function isTerminalState(s: QueueRecordState): boolean;
+/** Per-recipient queue state record. */
+export interface QueueState {
+    envelope_id: string;
+    recipient: string;
+    state: QueueRecordState;
+    attempts: number;
+    /** ISO 8601 UTC, or null if never attempted. */
+    last_attempt_at: string | null;
+    /** "delivered" | "rejected" | "silent" | null. */
+    last_outcome: string | null;
+    last_reason_code: ReasonCode | null;
+    /** ISO 8601 UTC, or null on terminal records. */
+    next_attempt_at: string | null;
+    /** Effective deadline per §2.4. ISO 8601 UTC. */
+    deadline: string;
+    /**
+     * Internal-only: wall-clock at which `state` transitioned to a
+     * terminal value. Used by the §2.5 retention prune. Excluded from
+     * canonical wire bytes; serialize with a custom replacer if
+     * exporting.
+     */
+    terminal_at?: string;
+}
+/**
+ * Transition `q` to `state`, recording the transition wall-clock
+ * on `terminal_at` and clearing `next_attempt_at`. No-op when:
+ *
+ *  - `state` is non-terminal
+ *  - `q` is already terminal (the §2.7.2 "MUST NOT override a prior
+ *    terminal state" rule is the caller's responsibility)
+ */
+export declare function setTerminal(q: QueueState, state: QueueRecordState, now: Date): void;
+//# sourceMappingURL=queue.d.ts.map

package/dist/delivery/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/delivery/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,mCAAmC;AACnC,MAAM,MAAM,gBAAgB,GACxB,QAAQ,GACR,WAAW,GACX,UAAU,GACV,SAAS,GACT,UAAU,CAAC;AAEf,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAE5D;AAED,wCAAwC;AACxC,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kDAAkD;IAClD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gBAAgB,EAAE,UAAU,GAAG,IAAI,CAAC;IACpC,iDAAiD;IACjD,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,CAAC,EAAE,UAAU,EACb,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,IAAI,GACR,IAAI,CAUN"}

package/dist/delivery/queue.js

@@ -0,0 +1,33 @@
+/**
+ * Per-recipient queue state record per DELIVERY.md §2.5.
+ *
+ * The sending server maintains one record per (envelope_id,
+ * recipient) pair; the record is authoritative for what the
+ * sending client displays to the user.
+ *
+ * @module
+ */
+/** Report whether a state is terminal (no further transitions). */
+export function isTerminalState(s) {
+    return s !== "queued";
+}
+/**
+ * Transition `q` to `state`, recording the transition wall-clock
+ * on `terminal_at` and clearing `next_attempt_at`. No-op when:
+ *
+ *  - `state` is non-terminal
+ *  - `q` is already terminal (the §2.7.2 "MUST NOT override a prior
+ *    terminal state" rule is the caller's responsibility)
+ */
+export function setTerminal(q, state, now) {
+    if (!isTerminalState(state)) {
+        return;
+    }
+    if (isTerminalState(q.state)) {
+        return;
+    }
+    q.state = state;
+    q.next_attempt_at = null;
+    q.terminal_at = now.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+//# sourceMappingURL=queue.js.map

package/dist/delivery/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/delivery/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,mEAAmE;AACnE,MAAM,UAAU,eAAe,CAAC,CAAmB;IACjD,OAAO,CAAC,KAAK,QAAQ,CAAC;AACxB,CAAC;AA0BD;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,CAAa,EACb,KAAuB,EACvB,GAAS;IAET,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO;IACT,CAAC;IACD,IAAI,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO;IACT,CAAC;IACD,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC;IAChB,CAAC,CAAC,eAAe,GAAG,IAAI,CAAC;IACzB,CAAC,CAAC,WAAW,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AAC9D,CAAC"}

package/dist/delivery/receipt.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Signed delivery receipts per DELIVERY.md §1.1.1.
+ *
+ * Every `delivered` acknowledgment a recipient server returns to a
+ * sending server MUST carry a signed receipt. The receipt binds
+ * `(envelope_hash, recipient_domain, accepted_at)` under the recipient
+ * domain's Ed25519 signing key with the `SEMP-DELIVERY-RECEIPT:`
+ * domain-separation prefix. It is a portable, non-repudiable artifact
+ * the sending user can later export to a `.semp-receipt` file.
+ *
+ * This module provides:
+ *
+ *  - {@link computeEnvelopeHash}: SHA-256 over canonical envelope bytes
+ *    (the same canonical form `seal.signature` is computed over —
+ *    `signature` and `session_mac` blanked, `hop_count` and `padding`
+ *    omitted).
+ *  - {@link signDeliveryReceipt}: build + sign a receipt from
+ *    pre-sign inputs.
+ *  - {@link verifyDeliveryReceipt}: Ed25519-verify a receipt against
+ *    a recipient domain public key.
+ *  - {@link verifyEnvelopeBinding}: cross-check the receipt's
+ *    `envelope_hash.value` against a fresh canonical envelope hash.
+ *  - {@link validateReceipt}: structural checks per §1.1.1.2.
+ *
+ * The companion {@link "./receipt_store"} module holds receipts the
+ * sending server has issued to its sending users until at least one
+ * client device acknowledges the delivery event carrying it.
+ *
+ * @module
+ */
+/** Domain-separation prefix for the receipt signature, per ENVELOPE.md §4.3. */
+export declare const DeliveryReceiptPrefix = "SEMP-DELIVERY-RECEIPT:";
+/** `type` discriminator for the receipt JSON. */
+export declare const DeliveryReceiptType = "SEMP_DELIVERY_RECEIPT";
+/** Receipt schema version per §1.1.1.1. */
+export declare const DeliveryReceiptVersion = "1.0.0";
+/** Only digest algorithm defined for v1.0.0 receipts per §1.1.1.3. */
+export declare const EnvelopeHashAlgorithmSHA256 = "sha-256";
+/** Receipt signature algorithm. */
+export declare const ReceiptSignatureAlgorithmEd25519 = "ed25519";
+/**
+ * Receiver-side tolerance window per §1.1.1.5: "Verifiers MUST NOT
+ * reject a receipt solely because `accepted_at` is within 120 seconds
+ * of their own current time in either direction."
+ */
+export declare const ReceiptClockSkewToleranceSeconds = 120;
+/** Hash binding inside a {@link DeliveryReceipt} per §1.1.1.3. */
+export interface EnvelopeHash {
+    algorithm: string;
+    /** Base64-encoded digest. */
+    value: string;
+}
+/** Signature block per §1.1.1.4. */
+export interface ReceiptSignature {
+    algorithm: string;
+    /** Lowercase-hex SHA-256 fingerprint of the recipient domain pub. */
+    key_id: string;
+    /** Base64-encoded Ed25519 signature. Empty when blanked. */
+    value: string;
+}
+/**
+ * SEMP_DELIVERY_RECEIPT record per §1.1.1. The wire form is a JSON
+ * object with these exact field names; canonical bytes are produced
+ * by {@link "../canonical".marshal}.
+ */
+export interface DeliveryReceipt {
+    type: typeof DeliveryReceiptType;
+    version: string;
+    envelope_hash: EnvelopeHash;
+    recipient_domain: string;
+    /** ISO 8601 UTC timestamp, second precision. */
+    accepted_at: string;
+    signature: ReceiptSignature;
+}
+/** Inputs to {@link signDeliveryReceipt}. */
+export interface SignDeliveryReceiptInput {
+    /** Base64 SHA-256 of canonical envelope bytes per §1.1.1.3. */
+    envelopeHashB64: string;
+    /** Recipient server's domain. */
+    recipientDomain: string;
+    /** ISO 8601 UTC timestamp of the recipient's accept decision. */
+    acceptedAt: string;
+    /** Lowercase-hex SHA-256 fingerprint of the signing public key. */
+    domainKeyId: string;
+    /** 32-byte Ed25519 secret seed for the recipient domain signing key. */
+    domainSigningSeed: Uint8Array;
+}
+/** Result of a successful {@link signDeliveryReceipt} call. */
+export interface SignDeliveryReceiptResult {
+    /** Receipt with `signature.value` populated. */
+    receipt: DeliveryReceipt;
+    /** Bare base64 signature value (also present in `receipt.signature.value`). */
+    signatureB64: string;
+}
+/**
+ * SHA-256 of canonical envelope bytes, base64-encoded, per
+ * §1.1.1.3. The caller is responsible for producing the canonical
+ * bytes — typically via `envelope.canonicalEnvelopeFor(env)` which
+ * applies §4.3 elision (signature, session_mac, hop_count, padding).
+ */
+export declare function computeEnvelopeHash(canonicalEnvelopeBytes: Uint8Array): string;
+/**
+ * Build and Ed25519-sign a SEMP_DELIVERY_RECEIPT under the recipient
+ * domain's signing key, following §1.1.1.4.
+ */
+export declare function signDeliveryReceipt(input: SignDeliveryReceiptInput): SignDeliveryReceiptResult;
+/** Inputs to {@link verifyDeliveryReceipt}. */
+export interface VerifyDeliveryReceiptInput {
+    /** Receipt as received. */
+    receipt: DeliveryReceipt;
+    /** 32-byte Ed25519 public key for the recipient domain. */
+    domainPub: Uint8Array;
+}
+/**
+ * Ed25519-verify a delivery receipt's signature against the
+ * recipient domain public key. Returns true on success. Throws on
+ * structural validation failure (use {@link validateReceipt} ahead
+ * of time to surface those as boolean false instead).
+ *
+ * Does NOT cross-check `accepted_at` against the verifier's clock —
+ * that is a §1.1.1.5 caller-side decision and MUST be applied with
+ * the {@link ReceiptClockSkewToleranceSeconds} tolerance.
+ */
+export declare function verifyDeliveryReceipt(input: VerifyDeliveryReceiptInput): boolean;
+/**
+ * Cross-check that the receipt's `envelope_hash.value` matches the
+ * fresh hash of the supplied canonical envelope bytes per §1.1.1.7
+ * step 4. Returns true when the binding holds.
+ */
+export declare function verifyEnvelopeBinding(receipt: DeliveryReceipt, canonicalEnvelopeBytes: Uint8Array): boolean;
+/**
+ * Structural validation per §1.1.1.2. Throws on the first missing or
+ * malformed field. Callers that want a boolean outcome can wrap in
+ * try/catch.
+ */
+export declare function validateReceipt(r: DeliveryReceipt): void;
+//# sourceMappingURL=receipt.d.ts.map

package/dist/delivery/receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.d.ts","sourceRoot":"","sources":["../../src/delivery/receipt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AASH,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAE9D,iDAAiD;AACjD,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D,2CAA2C;AAC3C,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAE9C,sEAAsE;AACtE,eAAO,MAAM,2BAA2B,YAAY,CAAC;AAErD,mCAAmC;AACnC,eAAO,MAAM,gCAAgC,YAAY,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,mBAAmB,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,YAAY,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,gBAAgB,CAAC;CAC7B;AAED,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,iBAAiB,EAAE,UAAU,CAAC;CAC/B;AAED,+DAA+D;AAC/D,MAAM,WAAW,yBAAyB;IACxC,gDAAgD;IAChD,OAAO,EAAE,eAAe,CAAC;IACzB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,sBAAsB,EAAE,UAAU,GAAG,MAAM,CAG9E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,wBAAwB,GAC9B,yBAAyB,CAyC3B;AAED,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,2BAA2B;IAC3B,OAAO,EAAE,eAAe,CAAC;IACzB,2DAA2D;IAC3D,SAAS,EAAE,UAAU,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAYT;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EACxB,sBAAsB,EAAE,UAAU,GACjC,OAAO,CAMT;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,CA8BxD"}