@centient/secrets 0.5.0 → 0.7.0

package/dist/vault/file-lock.js

@@ -0,0 +1,143 @@
+/**
+ * File lock — native exclusive advisory lock for vault writes.
+ *
+ * Extracted from session-vault.ts (M3) so session-vault remains focused on
+ * orchestration. The lock itself is filesystem-level (O_EXCL create on a
+ * `.lock` file) and cooperative: it only protects against writers that call
+ * `acquireWriteLock` before mutating.
+ *
+ * The lock file contains the holding process's PID so stale-lock stealing can
+ * distinguish "our PID still owns it" from "the previous holder crashed." On
+ * steal we write-and-verify to avoid two racing processes both thinking they
+ * stole the same stale lock (M2).
+ */
+import { openSync, closeSync, writeFileSync, readFileSync, statSync, unlinkSync, } from "node:fs";
+import { VaultLockError } from "./session-vault-errors.js";
+/** Max time a writer will wait to acquire the file lock before giving up. */
+export const LOCK_TIMEOUT_MS = 5_000;
+/** Poll interval when waiting on a held lock. */
+export const LOCK_RETRY_INTERVAL_MS = 25;
+/** Stale-lock threshold — if a lock file is older than this, assume crash. */
+export const LOCK_STALE_MS = 30_000;
+/**
+ * Acquire an exclusive write lock via O_EXCL on `{vaultPath}.lock`. Yields
+ * the event loop between retries (no busy-spin) up to `LOCK_TIMEOUT_MS`.
+ * Locks older than `LOCK_STALE_MS` are considered orphaned (the holding
+ * process crashed) and stolen with a pid-verification handshake so two
+ * concurrent stealers can't both claim ownership.
+ *
+ * Returns a release function. Releasing is idempotent and swallows ENOENT
+ * (the lock file may have been stolen by another process after we already
+ * finished our critical section — that's fine; the lockfile, not the fd,
+ * is what matters).
+ */
+export async function acquireWriteLock(vaultPath) {
+    const lockPath = `${vaultPath}.lock`;
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    const ourPid = process.pid;
+    const ourToken = `${ourPid}`;
+    while (Date.now() < deadline) {
+        // Attempt the happy path: create-exclusive.
+        try {
+            const fd = openSync(lockPath, "wx");
+            try {
+                // Write our pid so stale-lock stealing can verify ownership.
+                writeFileSync(lockPath, ourToken);
+            }
+            catch {
+                // Best-effort; even if we can't write pid, we still hold the lock.
+            }
+            // closeSync can throw on exotic filesystems; the lockfile — not the fd —
+            // is what matters, so swallow errors here. The release closure unlinks
+            // the file regardless (M2).
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Non-fatal.
+            }
+            return () => {
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch {
+                    // Lock file may have been removed by stale-lock stealing in another
+                    // process; ignore — our critical section is over regardless.
+                }
+            };
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            // EEXIST: someone holds it. Check for staleness.
+            try {
+                const lockStat = statSync(lockPath);
+                if (Date.now() - lockStat.mtimeMs > LOCK_STALE_MS) {
+                    // Stale. Steal with a write-and-verify handshake so two racing
+                    // stealers can't both claim ownership. Whoever's token survives
+                    // the read-back wins.
+                    try {
+                        unlinkSync(lockPath);
+                    }
+                    catch {
+                        // Another process may have already stolen it; loop and retry.
+                        continue;
+                    }
+                    try {
+                        const fd = openSync(lockPath, "wx");
+                        try {
+                            writeFileSync(lockPath, ourToken);
+                        }
+                        catch {
+                            // Non-fatal; proceed to verification.
+                        }
+                        try {
+                            closeSync(fd);
+                        }
+                        catch {
+                            // Non-fatal.
+                        }
+                        // Verification: read back and confirm our token is there. If a
+                        // racer wrote first we'll see their token and back off.
+                        try {
+                            const recorded = readFileSync(lockPath, "utf8").trim();
+                            if (recorded !== ourToken) {
+                                // We lost the steal race; loop and retry normally.
+                                continue;
+                            }
+                        }
+                        catch {
+                            // Read failed — treat as loss and retry.
+                            continue;
+                        }
+                        return () => {
+                            try {
+                                unlinkSync(lockPath);
+                            }
+                            catch {
+                                // Same rationale as happy-path release.
+                            }
+                        };
+                    }
+                    catch (stealErr) {
+                        if (stealErr.code === "EEXIST") {
+                            // Another process stole it between our unlink and open; retry.
+                            continue;
+                        }
+                        throw stealErr;
+                    }
+                }
+            }
+            catch {
+                // statSync failed — lock was just released, or racing cleanup.
+                // Fall through to sleep-and-retry.
+            }
+            // Held by a non-stale writer. Yield the event loop — do NOT busy-spin
+            // (C1). This allows every other async task on this event loop to run
+            // while we wait.
+            await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_INTERVAL_MS));
+        }
+    }
+    throw new VaultLockError(`Timed out after ${LOCK_TIMEOUT_MS}ms waiting for vault write lock at ${lockPath}`);
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/vault/file-lock.js.map

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

package/dist/vault/session-vault-errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SessionVault error classes — extracted so helper modules (file-lock,
+ * sidecar) can throw them without creating an import cycle back into
+ * session-vault.ts.
+ *
+ * Each subclass restores the prototype chain with `Object.setPrototypeOf`
+ * so `instanceof VaultError` etc. remains robust when the class is consumed
+ * across an ES transpile boundary (L2 — matches the EngramError pattern in
+ * `packages/sdk/src/errors.ts`).
+ */
+/** Base class for SessionVault errors. */
+export declare class VaultError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Thrown when the master key can't be retrieved from the configured provider. */
+export declare class VaultUnlockError extends VaultError {
+    constructor(message: string);
+}
+/** Thrown when decryption fails — wrong key, corrupted file, or AAD mismatch. */
+export declare class VaultDecryptError extends VaultError {
+    constructor(message: string);
+}
+/** Thrown when rollback is detected and not explicitly accepted. */
+export declare class VaultRollbackError extends VaultError {
+    readonly expected: number;
+    readonly actual: number;
+    constructor(expected: number, actual: number);
+}
+/** Thrown when operations are attempted on a closed vault. */
+export declare class VaultClosedError extends VaultError {
+    constructor();
+}
+/** Thrown when the write-path file lock can't be acquired within the timeout. */
+export declare class VaultLockError extends VaultError {
+    constructor(message: string);
+}
+//# sourceMappingURL=session-vault-errors.d.ts.map

package/dist/vault/session-vault-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-vault-errors.d.ts","sourceRoot":"","sources":["../../src/vault/session-vault-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,0CAA0C;AAC1C,qBAAa,UAAW,SAAQ,KAAK;aACP,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1D;AAED,kFAAkF;AAClF,qBAAa,gBAAiB,SAAQ,UAAU;gBAClC,OAAO,EAAE,MAAM;CAK5B;AAED,iFAAiF;AACjF,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,OAAO,EAAE,MAAM;CAK5B;AAED,oEAAoE;AACpE,qBAAa,kBAAmB,SAAQ,UAAU;aAE9B,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM;gBADd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAWjC;AAED,8DAA8D;AAC9D,qBAAa,gBAAiB,SAAQ,UAAU;;CAM/C;AAED,iFAAiF;AACjF,qBAAa,cAAe,SAAQ,UAAU;gBAChC,OAAO,EAAE,MAAM;CAK5B"}

package/dist/vault/session-vault-errors.js

@@ -0,0 +1,67 @@
+/**
+ * SessionVault error classes — extracted so helper modules (file-lock,
+ * sidecar) can throw them without creating an import cycle back into
+ * session-vault.ts.
+ *
+ * Each subclass restores the prototype chain with `Object.setPrototypeOf`
+ * so `instanceof VaultError` etc. remains robust when the class is consumed
+ * across an ES transpile boundary (L2 — matches the EngramError pattern in
+ * `packages/sdk/src/errors.ts`).
+ */
+/** Base class for SessionVault errors. */
+export class VaultError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "VaultError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Thrown when the master key can't be retrieved from the configured provider. */
+export class VaultUnlockError extends VaultError {
+    constructor(message) {
+        super("VAULT_UNLOCK_FAILED", message);
+        this.name = "VaultUnlockError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Thrown when decryption fails — wrong key, corrupted file, or AAD mismatch. */
+export class VaultDecryptError extends VaultError {
+    constructor(message) {
+        super("VAULT_DECRYPT_FAILED", message);
+        this.name = "VaultDecryptError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Thrown when rollback is detected and not explicitly accepted. */
+export class VaultRollbackError extends VaultError {
+    expected;
+    actual;
+    constructor(expected, actual) {
+        super("VAULT_VERSION_ROLLBACK_DETECTED", `Vault version rollback detected: sidecar expects version >= ${expected}, ` +
+            `but vault file reports version ${actual}. If this is an intentional ` +
+            `restore, pass { acceptRollback: true } to openVault().`);
+        this.expected = expected;
+        this.actual = actual;
+        this.name = "VaultRollbackError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Thrown when operations are attempted on a closed vault. */
+export class VaultClosedError extends VaultError {
+    constructor() {
+        super("VAULT_CLOSED", "Vault has been closed; reopen with openVault() to continue.");
+        this.name = "VaultClosedError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Thrown when the write-path file lock can't be acquired within the timeout. */
+export class VaultLockError extends VaultError {
+    constructor(message) {
+        super("VAULT_LOCK_FAILED", message);
+        this.name = "VaultLockError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+//# sourceMappingURL=session-vault-errors.js.map

package/dist/vault/session-vault-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-vault-errors.js","sourceRoot":"","sources":["../../src/vault/session-vault-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,0CAA0C;AAC1C,MAAM,OAAO,UAAW,SAAQ,KAAK;IACP;IAA5B,YAA4B,IAAY,EAAE,OAAe;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QADW,SAAI,GAAJ,IAAI,CAAQ;QAEtC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,kFAAkF;AAClF,MAAM,OAAO,gBAAiB,SAAQ,UAAU;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,OAAO,iBAAkB,SAAQ,UAAU;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,oEAAoE;AACpE,MAAM,OAAO,kBAAmB,SAAQ,UAAU;IAE9B;IACA;IAFlB,YACkB,QAAgB,EAChB,MAAc;QAE9B,KAAK,CACH,iCAAiC,EACjC,+DAA+D,QAAQ,IAAI;YACzE,kCAAkC,MAAM,8BAA8B;YACtE,wDAAwD,CAC3D,CAAC;QARc,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAQ;QAQ9B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,8DAA8D;AAC9D,MAAM,OAAO,gBAAiB,SAAQ,UAAU;IAC9C;QACE,KAAK,CAAC,cAAc,EAAE,6DAA6D,CAAC,CAAC;QACrF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,OAAO,cAAe,SAAQ,UAAU;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF"}

package/dist/vault/session-vault.d.ts

@@ -0,0 +1,147 @@
+/**
+ * SessionVault — public session-backed envelope vault API.
+ *
+ * Opens the CLI's encrypted vault file once per session (one KeyProvider
+ * prompt), caches the decrypted contents in RAM, and serves reads without
+ * further prompts. External writes (e.g. the CLI in another shell) become
+ * visible via mtime-check coherence on every read.
+ *
+ * Addresses the per-item Keychain-prompt problem flagged in issue #40:
+ * long-running daemons (centient-labs/maintainer) holding N credentials
+ * across a long lifetime should not reach into the OS keychain on every
+ * access. Envelope encryption with a single master-key unlock matches
+ * industry standard (KMS, HashiCorp Vault, 1Password, Bitwarden).
+ *
+ * ## Threat model (what this protects and doesn't)
+ *
+ * - Protects against filesystem-read-only adversaries (ciphertext is AEAD
+ *   encrypted; forging plaintext requires the master key).
+ * - Protects against live-session and cold-start vault-file rollback by a
+ *   filesystem-write-only adversary via the combined in-payload
+ *   `vaultVersion` + sidecar-file `highestSeenVersion` scheme.
+ * - Does NOT protect against an adversary with **both** master-key access
+ *   and filesystem write — game over for any local envelope vault.
+ * - Does NOT protect against an adversary with write access to the vault
+ *   directory who chooses to downgrade both vault and sidecar in lockstep
+ *   — the sidecar lives next to the vault. If your threat model includes
+ *   adversarial writes to `~/.centient/secrets/`, use a secrets service
+ *   with remote attestation (HashiCorp Vault, AWS Secrets Manager,
+ *   1Password Connect) instead.
+ * - Session key is in process RAM for the full session lifetime. Any code
+ *   with execution in the process has access to all secrets in the vault.
+ *   Operators running daemons with this API SHOULD disable core dumps
+ *   (`ulimit -c 0` / `prlimit --core=0`) and disable the Node.js inspector
+ *   (`NODE_OPTIONS=--inspect` grants heap read to anyone on the inspector
+ *   socket — a full master-key compromise vector).
+ * - On macOS, a newly-started process will still prompt the user for
+ *   Keychain access even if another process holds the vault open.
+ *   Keychain ACLs are per-process, not per-vault-file.
+ */
+import type { KeyProviderType } from "../key-providers/types.js";
+import { VaultError, VaultUnlockError, VaultDecryptError, VaultRollbackError, VaultClosedError, VaultLockError } from "./session-vault-errors.js";
+export { VaultError, VaultUnlockError, VaultDecryptError, VaultRollbackError, VaultClosedError, VaultLockError, };
+/** Current payload schema version — bump requires a compat migration. */
+export declare const VAULT_SCHEMA_VERSION = 1;
+/** Default vault file location — same path the CLI uses, so they share state. */
+export declare const DEFAULT_VAULT_PATH: string;
+/** Default sidecar location — stores highest-ever-seen vault version. */
+export declare const DEFAULT_SIDECAR_PATH: string;
+/**
+ * AAD prefix — static byte header mixed into the vault ciphertext's
+ * Additional Authenticated Data. Binding this prefix into AAD means a
+ * ciphertext from some other AES-GCM user with the same key cannot be
+ * substituted into the vault. Exported so test fixtures can produce AAD
+ * consistent with the real implementation without duplicating the constant.
+ */
+export declare const VAULT_AAD_PREFIX = "centient-secrets-vault";
+/**
+ * Coherence strategy governs how the open vault reconciles in-memory state
+ * with concurrent external writes to the vault file.
+ */
+export type CoherenceStrategy = "mtime-check" | "strict" | "best-effort";
+/** Options for {@link openVault}. All fields are optional. */
+export interface OpenVaultOptions {
+    /** Alternate vault file path. Defaults to the same path the CLI uses. */
+    path?: string;
+    /** Alternate sidecar path. Defaults to vault directory + `vault.seen-version`. */
+    sidecarPath?: string;
+    /**
+     * Coherence strategy for concurrent external writes. Default `mtime-check`:
+     * stat on every read; re-decrypt if mtime advanced. `strict` throws on stale
+     * snapshot. `best-effort` keeps the in-memory snapshot until `reload()`.
+     */
+    coherence?: CoherenceStrategy;
+    /**
+     * Opt-in acceptance of a detected rollback (sidecar version > vault version).
+     * Emits a scary warning on stderr. Use only when the operator explicitly
+     * intends to restore an older vault (backup restore, etc.).
+     */
+    acceptRollback?: boolean;
+    /**
+     * Opt-in acceptance of a missing sidecar. Default behaviour (`false`) is to
+     * **refuse** to open the vault when the sidecar is absent — this enforces
+     * the security invariant that rollback protection is always in effect.
+     * Pass `true` for legitimate first-use contexts (fresh install, test
+     * fixtures, post-migration) to auto-initialize `seenVersion = vaultVersion`
+     * with a stderr warning. See docs/session-vault.md §Missing sidecar.
+     */
+    acceptMissingSidecar?: boolean;
+    /**
+     * Optional auto-close TTL in milliseconds. Not set by default — daemons run
+     * forever; forced re-auth undoes the point of a session vault. Useful for
+     * short-lived script consumers that want defense-in-depth.
+     */
+    ttlMs?: number;
+}
+/**
+ * A long-lived handle to an unlocked vault. Construct with {@link openVault};
+ * close with {@link SessionVault.close}. Operations are async so policy
+ * `before` hooks can await (e.g. remote attestation).
+ */
+export interface SessionVault {
+    /** Read a secret by name. Returns null if the name isn't in the vault. */
+    get(name: string): Promise<string | null>;
+    /** List all secret names, optionally prefix-filtered. Sorted ascending. */
+    list(prefix?: string): Promise<string[]>;
+    /** Write a secret. Re-encrypts and saves the vault file atomically. */
+    set(name: string, value: string): Promise<void>;
+    /** Delete a secret. Returns true if the name existed and was removed. */
+    delete(name: string): Promise<boolean>;
+    /** Force an immediate reload from disk regardless of coherence strategy. */
+    reload(): Promise<void>;
+    /** Release the session key and in-memory state. No-op if already closed. */
+    close(): void;
+    /** Diagnostic — the KeyProvider that unlocked this session. */
+    readonly provider: KeyProviderType;
+    /** Diagnostic — absolute path of the vault file. */
+    readonly path: string;
+    /** Diagnostic — the current in-memory vault version. */
+    readonly vaultVersion: number;
+}
+/**
+ * Open an encrypted session vault.
+ *
+ * Resolves the configured {@link KeyProvider} to obtain the master key,
+ * decrypts the vault file bound to its resolved real path (symlink-aware),
+ * checks rollback detection via the sidecar, and returns a long-lived
+ * {@link SessionVault} handle that serves reads from memory.
+ *
+ * @param opts - {@link OpenVaultOptions}. All fields are optional; defaults
+ *   use the same paths the `centient secrets` CLI uses.
+ * @returns An open {@link SessionVault}. Call `close()` when done.
+ * @throws {@link VaultError} `VAULT_NOT_FOUND` when the vault file is absent.
+ * @throws {@link VaultUnlockError} when the KeyProvider cannot return a key.
+ * @throws {@link VaultDecryptError} when decryption fails (wrong key, AAD
+ *   mismatch, corrupted payload).
+ * @throws {@link VaultRollbackError} when the sidecar indicates a rollback
+ *   and `acceptRollback` is not set.
+ *
+ * @example
+ * ```ts
+ * const vault = await openVault({ ttlMs: 60_000 });
+ * const apiKey = await vault.get("openai-api-key");
+ * vault.close();
+ * ```
+ */
+export declare function openVault(opts?: OpenVaultOptions): Promise<SessionVault>;
+//# sourceMappingURL=session-vault.d.ts.map

package/dist/vault/session-vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-vault.d.ts","sourceRoot":"","sources":["../../src/vault/session-vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAiBH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAejE,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACf,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,GACf,CAAC;AAMF,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,QAAuD,CAAC;AAEvF,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,QAKhC,CAAC;AAKF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,2BAA2B,CAAC;AA2BzD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEzE,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1C,2EAA2E;IAC3E,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,uEAAuE;IACvE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,yEAAyE;IACzE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,4EAA4E;IAC5E,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,4EAA4E;IAC5E,KAAK,IAAI,IAAI,CAAC;IACd,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AA2ED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,SAAS,CAAC,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,YAAY,CAAC,CAsJlF"}