@clef-sh/core 0.1.27 → 0.2.0

package/dist/sops/client.d.ts

@@ -1,18 +1,39 @@
-import { ClefManifest, DecryptedFile, EncryptionBackend, SopsMetadata, SubprocessRunner } from "../types";
+import { DecryptedFile, MergeDecrypter, SopsMetadata, SubprocessRunner } from "../types";
+import type { EncryptionBackend, EncryptionContext, RotateOptions } from "../source/encryption-backend";
 /**
- * Wraps the `sops` binary for encryption, decryption, re-encryption, and metadata extraction.
- * All decrypt/encrypt operations are piped via stdin/stdout — plaintext never touches disk.
+ * Wraps the `sops` binary for encryption, decryption, rotation, and metadata
+ * extraction. All blob operations are piped via stdin/stdout — plaintext
+ * never touches disk.
+ *
+ * `SopsClient` implements {@link EncryptionBackend} directly — pass it
+ * straight to `composeSecretSource(storage, client, manifest)` without
+ * any adapter. The legacy file-path methods (`encrypt(filePath, ...)`,
+ * `addRecipient`, `removeRecipient`, `reEncrypt`,
+ * `validateEncryption(filePath)`, `getMetadata(filePath)`) were removed
+ * in Phase 7. The only remaining file-path entry point is
+ * {@link decryptFile}, kept for the merge driver which receives temp
+ * file paths from git — the contract for that surface is
+ * {@link MergeDecrypter}.
  *
  * @example
  * ```ts
  * const client = new SopsClient(runner, "/home/user/.age/key.txt");
- * const decrypted = await client.decrypt("secrets/production.enc.yaml");
+ * const source = composeSecretSource(
+ *   new FilesystemStorageBackend(manifest, repoRoot),
+ *   client,
+ *   manifest,
+ * );
+ * const cell = await source.readCell({ namespace: "db", environment: "prod" });
  * ```
  */
-export declare class SopsClient implements EncryptionBackend {
+export declare class SopsClient implements EncryptionBackend, MergeDecrypter {
     private readonly runner;
     private readonly ageKeyFile?;
     private readonly ageKey?;
+    /** {@link EncryptionBackend} identifier. */
+    readonly id = "sops";
+    /** {@link EncryptionBackend} short description (used by `clef doctor`). */
+    readonly description = "SOPS-based encryption via the bundled `sops` binary";
     private readonly sopsCommand;
     private readonly keyserviceArgs;
     /**
@@ -36,77 +57,81 @@ export declare class SopsClient implements EncryptionBackend {
     constructor(runner: SubprocessRunner, ageKeyFile?: string | undefined, ageKey?: string | undefined, sopsPath?: string, keyserviceAddr?: string);
     private buildSopsEnv;
     /**
-     * Decrypt a SOPS-encrypted file and return its values and metadata.
+     * Decrypt a SOPS-encrypted file by path. The only remaining file-path
+     * entry point on this class — kept for the merge driver, which
+     * receives temp filesystem paths from git that don't map onto a
+     * `CellRef`. Production `SecretSource` consumers should call
+     * `source.readCell` instead.
      *
      * @param filePath - Path to the `.enc.yaml` or `.enc.json` file.
      * @returns {@link DecryptedFile} with plaintext values in memory only.
      * @throws {@link SopsKeyNotFoundError} If no matching decryption key is available.
      * @throws {@link SopsDecryptionError} On any other decryption failure.
      */
-    decrypt(filePath: string): Promise<DecryptedFile>;
+    decryptFile(filePath: string): Promise<DecryptedFile>;
     /**
-     * Encrypt a key/value map and write it to an encrypted SOPS file.
+     * Determine whether a decrypt failure is caused by a missing/mismatched key (vs. some other
+     * SOPS error) without relying on stderr message text.
      *
-     * @param filePath - Destination path for the encrypted file.
-     * @param values - Flat key/value map to encrypt.
-     * @param manifest - Manifest used to determine the encryption backend and key configuration.
-     * @param environment - Optional environment name. When provided, per-env backend overrides
-     *   are resolved from the manifest. When omitted, the global `sops.default_backend` is used.
-     * @throws {@link SopsEncryptionError} On encryption or write failure.
+     * For age backends: reads the file's recipient list and checks whether any of the configured
+     * private keys derive to a matching public key. For non-age backends (pgp, kms) we cannot
+     * perform an equivalent check, so those always return "other".
      */
-    encrypt(filePath: string, values: Record<string, string>, manifest: ClefManifest, environment?: string): Promise<void>;
+    private classifyDecryptError;
+    private parseMetadataFromFile;
     /**
-     * Rotate encryption by adding a new age recipient key to an existing SOPS file.
-     *
-     * @param filePath - Path to the encrypted file to re-encrypt.
-     * @param newKey - New age public key to add as a recipient.
-     * @throws {@link SopsEncryptionError} On failure.
+     * Parse SOPS metadata from a string (no IO). Used by both
+     * `parseMetadataFromFile` (after reading from disk) and the blob-shaped
+     * `getMetadataFromBlob` (which receives ciphertext directly from a
+     * BlobStore). The `label` is woven into error messages so callers can
+     * include the file path or cell ref the content came from.
      */
-    reEncrypt(filePath: string, newKey: string): Promise<void>;
+    private parseMetadataFromContent;
+    private detectBackend;
+    private extractRecipients;
+    private buildEncryptArgs;
     /**
-     * Add an age recipient to an existing SOPS file.
-     *
-     * @param filePath - Path to the encrypted file.
-     * @param key - age public key to add as a recipient.
-     * @throws {@link SopsEncryptionError} On failure.
+     * {@link EncryptionBackend.decrypt} — decrypt SOPS-encrypted bytes (e.g.
+     * read from a `StorageBackend`) and return plaintext values + metadata.
+     * Plaintext lives only in memory.
      */
-    addRecipient(filePath: string, key: string): Promise<void>;
+    decrypt(blob: string, ctx: EncryptionContext): Promise<DecryptedFile>;
     /**
-     * Remove an age recipient from an existing SOPS file.
-     *
-     * @param filePath - Path to the encrypted file.
-     * @param key - age public key to remove.
-     * @throws {@link SopsEncryptionError} On failure.
+     * {@link EncryptionBackend.encrypt} — encrypt plaintext values into a
+     * SOPS-formatted ciphertext blob. Returns the bytes as a string;
+     * caller (typically a `StorageBackend`) decides where to put them.
+     * Plaintext is piped via stdin only.
      */
-    removeRecipient(filePath: string, key: string): Promise<void>;
+    encrypt(values: Record<string, string>, ctx: EncryptionContext): Promise<string>;
     /**
-     * Check whether a file contains valid SOPS encryption metadata.
+     * {@link EncryptionBackend.rotate} — add or remove recipients from an
+     * encrypted SOPS blob via stdin/stdout. Drops the in-place `-i` flag
+     * the deleted file-path-shaped methods used, so SOPS writes the
+     * rotated ciphertext to stdout instead of back to a file. Plaintext
+     * stays inside the SOPS subprocess; no plaintext window exists in
+     * this Node process.
      *
-     * @param filePath - Path to the file to check.
-     * @returns `true` if valid SOPS metadata is present; `false` otherwise. Never throws.
+     * Single SOPS invocation can both add and remove recipients
+     * simultaneously (matches the CLI flag set).
      */
-    validateEncryption(filePath: string): Promise<boolean>;
+    rotate(blob: string, opts: RotateOptions, ctx: EncryptionContext): Promise<string>;
     /**
-     * Extract SOPS metadata (backend, recipients, last-modified timestamp) from an encrypted file
-     * without decrypting its values.
-     *
-     * @param filePath - Path to the encrypted file.
-     * @returns {@link SopsMetadata} parsed from the file's `sops:` block.
-     * @throws {@link SopsDecryptionError} If the file cannot be read or parsed.
+     * {@link EncryptionBackend.getMetadata} — extract SOPS metadata from a
+     * ciphertext blob without decrypting. Pure parser, no IO, no
+     * subprocess.
      */
-    getMetadata(filePath: string): Promise<SopsMetadata>;
+    getMetadata(content: string): SopsMetadata;
     /**
-     * Determine whether a decrypt failure is caused by a missing/mismatched key (vs. some other
-     * SOPS error) without relying on stderr message text.
-     *
-     * For age backends: reads the file's recipient list and checks whether any of the configured
-     * private keys derive to a matching public key. For non-age backends (pgp, kms) we cannot
-     * perform an equivalent check, so those always return "other".
+     * {@link EncryptionBackend.validateEncryption} — whether `content` is a
+     * valid SOPS-encrypted blob (parses + has the `sops:` metadata
+     * block). Never throws.
      */
-    private classifyDecryptError;
-    private parseMetadataFromFile;
-    private detectBackend;
-    private extractRecipients;
-    private buildEncryptArgs;
+    validateEncryption(content: string): boolean;
+    /**
+     * Blob-shaped variant of `classifyDecryptError`. Same logic as the
+     * file-path version but reads metadata from the in-memory ciphertext
+     * instead of disk.
+     */
+    private classifyDecryptErrorFromContent;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/sops/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/sops/client.ts"],"names":[],"mappings":"AAiBA,OAAO,EAEL,YAAY,EACZ,aAAa,EACb,iBAAiB,EAIjB,YAAY,EACZ,gBAAgB,EAGjB,MAAM,UAAU,CAAC;AA0ClB;;;;;;;;;GASG;AACH,qBAAa,UAAW,YAAW,iBAAiB;IAuBhD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAxB1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoB;IAEnD;;;;;;;;;;;;;;;;;OAiBG;gBAEgB,MAAM,EAAE,gBAAgB,EACxB,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,MAAM,CAAC,EAAE,MAAM,YAAA,EAChC,QAAQ,CAAC,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM;IAQzB,OAAO,CAAC,YAAY;IAWpB;;;;;;;OAOG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA6CvD;;;;;;;;;OASG;IACG,OAAO,CACX,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,QAAQ,EAAE,YAAY,EACtB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC;IAuEhB;;;;;;OAMG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE;;;;;;OAMG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBhE;;;;;;OAMG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBnE;;;;;OAKG;IACG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAU5D;;;;;;;OAOG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAgB1D;;;;;;;OAOG;YACW,oBAAoB;IAsClC,OAAO,CAAC,qBAAqB;IAuC7B,OAAO,CAAC,aAAa;IAoBrB,OAAO,CAAC,iBAAiB;IA6CzB,OAAO,CAAC,gBAAgB;CA+DzB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/sops/client.ts"],"names":[],"mappings":"AAgBA,OAAO,EAGL,aAAa,EACb,cAAc,EAId,YAAY,EACZ,gBAAgB,EAGjB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACd,MAAM,8BAA8B,CAAC;AAsEtC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,UAAW,YAAW,iBAAiB,EAAE,cAAc;IA4BhE,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IA7B1B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,UAAU;IACrB,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,yDAAyD;IAE7E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoB;IAEnD;;;;;;;;;;;;;;;;;OAiBG;gBAEgB,MAAM,EAAE,gBAAgB,EACxB,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,MAAM,CAAC,EAAE,MAAM,YAAA,EAChC,QAAQ,CAAC,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM;IAQzB,OAAO,CAAC,YAAY;IAWpB;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAiD3D;;;;;;;OAOG;YACW,oBAAoB;IAsClC,OAAO,CAAC,qBAAqB;IAa7B;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IA6BhC,OAAO,CAAC,aAAa;IAoBrB,OAAO,CAAC,iBAAiB;IA6CzB,OAAO,CAAC,gBAAgB;IAoExB;;;;OAIG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAmD3E;;;;;OAKG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAwCtF;;;;;;;;;;OAUG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAiDxF;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY;IAI1C;;;;OAIG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAS5C;;;;OAIG;YACW,+BAA+B;CAmC9C"}

package/dist/sops/linux-stdin-fifo.d.ts

@@ -0,0 +1,31 @@
+import type { SubprocessRunner } from "../types";
+/**
+ * On Linux, libuv creates pipes for child stdio. SOPS (Go) translates
+ * `/dev/stdin` through `/proc/self/fd/0` and tries to re-open it by path,
+ * which fails with ENXIO ("no such device or address") because pipes
+ * cannot be re-opened by path.
+ *
+ * Workaround: when SopsClient asks the runner to spawn `sops` with
+ * `/dev/stdin` in the args AND content piped via the runner's stdin,
+ * substitute a Linux FIFO (named pipe). FIFOs are openable by path —
+ * the bytes still live in an in-memory kernel buffer (not on disk), so
+ * the no-plaintext-to-disk invariant is preserved.
+ *
+ * Gated on `process.platform === "linux"` and the absence of
+ * `JEST_WORKER_ID` — unit tests mock `SubprocessRunner` and never
+ * spawn a real SOPS binary, so the FIFO machinery would only add
+ * subprocess overhead with no benefit. Callers that genuinely need the
+ * workaround inside a Jest-spawned child (e.g. the CDK pack-helper
+ * subprocess) must scrub `JEST_WORKER_ID` from the child's env so this
+ * gate fires correctly.
+ */
+export declare function shouldUseLinuxStdinFifo(): boolean;
+/**
+ * Wrap a `SubprocessRunner` so that any call carrying both `/dev/stdin`
+ * in `args` and a non-empty `opts.stdin` payload is rewritten to use a
+ * Linux FIFO. On platforms where the workaround isn't needed (or in
+ * unit tests), returns the input runner unchanged so the wrapper costs
+ * nothing.
+ */
+export declare function wrapWithLinuxStdinFifo(runner: SubprocessRunner): SubprocessRunner;
+//# sourceMappingURL=linux-stdin-fifo.d.ts.map

package/dist/sops/linux-stdin-fifo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linux-stdin-fifo.d.ts","sourceRoot":"","sources":["../../src/sops/linux-stdin-fifo.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CA4CjF"}

package/dist/source/compose.d.ts

@@ -0,0 +1,10 @@
+import type { ClefManifest } from "../types";
+import type { Bulk, Lintable, Rotatable, SecretSource } from "./types";
+import type { StorageBackend } from "./storage-backend";
+import type { EncryptionBackend } from "./encryption-backend";
+/**
+ * Build a `SecretSource & Lintable & Rotatable & Bulk` from the two
+ * orthogonal backends and the manifest.
+ */
+export declare function composeSecretSource(storage: StorageBackend, encryption: EncryptionBackend, manifest: ClefManifest): SecretSource & Lintable & Rotatable & Bulk;
+//# sourceMappingURL=compose.d.ts.map

package/dist/source/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/source/compose.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,UAAU,CAAC;AAC3D,OAAO,KAAK,EACV,IAAI,EAIJ,QAAQ,EAER,SAAS,EAET,YAAY,EACb,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAqB,MAAM,sBAAsB,CAAC;AAGjF;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,iBAAiB,EAC7B,QAAQ,EAAE,YAAY,GACrB,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,IAAI,CAE5C"}

package/dist/source/default-bulk.d.ts

@@ -0,0 +1,12 @@
+import type { Bulk, SecretSource } from "./types";
+/**
+ * Wrap a `SecretSource` in a `Bulk` implementation that loops over
+ * `readCell` / `writeCell` / `deleteCell`. Sources whose substrate
+ * cannot batch — or that simply haven't bothered — get correct
+ * behavior for free at the cost of one round-trip per cell.
+ *
+ * Returned object satisfies `Bulk` only; combine via spread when a
+ * caller needs both the source surface and bulk methods.
+ */
+export declare function defaultBulk(source: SecretSource): Bulk;
+//# sourceMappingURL=default-bulk.d.ts.map

package/dist/source/default-bulk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-bulk.d.ts","sourceRoot":"","sources":["../../src/source/default-bulk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAW,YAAY,EAAE,MAAM,SAAS,CAAC;AAG3D;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CA6CtD"}

package/dist/source/encryption-backend.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `EncryptionBackend` is the substrate-agnostic encryption contract — a
+ * peer abstraction to `StorageBackend`. It takes plaintext values and
+ * produces opaque ciphertext bytes (and the reverse), without ever
+ * touching files, paths, or storage substrate.
+ *
+ * Implementations:
+ *   - `createSopsEncryptionBackend(sopsClient)` — SOPS via the bundled
+ *     `sops` binary. The default and only first-party implementation.
+ *   - Future: any byte-shaped encryption scheme (age-direct, libsodium,
+ *     BYO). Plugin authors can ship one as `@clef-sh/encryption-<id>`.
+ *
+ * The pairing with `StorageBackend` is intentionally orthogonal:
+ *
+ *   composeSecretSource(storage: StorageBackend,
+ *                       encryption: EncryptionBackend,
+ *                       manifest: ClefManifest): SecretSource
+ *
+ * Any combination of (storage, encryption) yields a working source.
+ *
+ * Plaintext discipline:
+ *   - `encrypt` and `decrypt` may hold plaintext briefly in process memory
+ *     while they shell out to the encryption tool. Implementations MUST
+ *     NOT write plaintext to disk, log it, or transmit it over an
+ *     untrusted channel.
+ *   - `rotate` is plaintext-free: it transforms ciphertext to ciphertext
+ *     (re-wrapping the data encryption key against an updated recipient
+ *     set) without exposing values to the calling process.
+ */
+import type { ClefManifest, DecryptedFile, SopsMetadata } from "../types";
+/**
+ * Per-call context. Carries the manifest (for recipients/backend
+ * resolution), the target environment (for per-env overrides), and the
+ * format hint forwarded from the `StorageBackend`.
+ */
+export interface EncryptionContext {
+    manifest: ClefManifest;
+    environment?: string;
+    /** Format of the ciphertext bytes — typically passed through verbatim. */
+    format: "yaml" | "json";
+}
+/**
+ * Recipient changes applied during a rotation. All fields are optional;
+ * a backend may interpret only the keys it understands (e.g. a custom
+ * non-SOPS backend that ignores `addAge` if it has no concept of age).
+ */
+export interface RotateOptions {
+    addAge?: string;
+    rmAge?: string;
+    addKms?: string;
+    rmKms?: string;
+    addGcpKms?: string;
+    rmGcpKms?: string;
+    addAzureKv?: string;
+    rmAzureKv?: string;
+    addPgp?: string;
+    rmPgp?: string;
+}
+export interface EncryptionBackend {
+    /** Stable identifier (e.g. `"sops"`). */
+    readonly id: string;
+    /** Short human-readable description, used in `clef doctor`. */
+    readonly description: string;
+    /**
+     * Encrypt a plaintext value-map into ciphertext bytes. The recipient
+     * set is derived from the manifest (and optional per-env override).
+     */
+    encrypt(values: Record<string, string>, ctx: EncryptionContext): Promise<string>;
+    /**
+     * Decrypt ciphertext bytes back into a plaintext value-map plus
+     * encryption metadata (backend, recipients, last-modified, ...).
+     */
+    decrypt(blob: string, ctx: EncryptionContext): Promise<DecryptedFile>;
+    /**
+     * Rotate the data encryption key and/or update the recipient set on
+     * an already-encrypted blob. Returns the new ciphertext. Plaintext is
+     * not exposed to the calling process.
+     */
+    rotate(blob: string, opts: RotateOptions, ctx: EncryptionContext): Promise<string>;
+    /** Inspect ciphertext metadata without decrypting. Pure parser. */
+    getMetadata(blob: string): SopsMetadata;
+    /** Whether `blob` is well-formed encrypted output. Never throws. */
+    validateEncryption(blob: string): boolean;
+}
+//# sourceMappingURL=encryption-backend.d.ts.map

package/dist/source/encryption-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption-backend.d.ts","sourceRoot":"","sources":["../../src/source/encryption-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE1E;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,YAAY,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEjF;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAEtE;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnF,mEAAmE;IACnE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC;IAExC,oEAAoE;IACpE,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3C"}

package/dist/source/errors.d.ts

@@ -0,0 +1,19 @@
+import { ClefError } from "../types";
+/**
+ * Thrown when a CLI command or UI route requires a capability the
+ * configured `SecretSource` does not implement (e.g. running
+ * `clef rotate` against a `postgres` source that does not implement
+ * `Rotatable`).
+ *
+ * Surfaces at the command-entry boundary so users see a clean message
+ * rather than a deep stack trace from a missing method call. The
+ * `capability` field is the trait name in lower-case kebab form
+ * (`"rotate"`, `"recipients"`, `"merge"`, etc.) — matching the keys of
+ * `SourceCapabilities`.
+ */
+export declare class SourceCapabilityUnsupportedError extends ClefError {
+    readonly capability: string;
+    readonly sourceId: string;
+    constructor(capability: string, sourceId: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/source/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/source/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC;;;;;;;;;;;GAWG;AACH,qBAAa,gCAAiC,SAAQ,SAAS;aAE3C,UAAU,EAAE,MAAM;aAClB,QAAQ,EAAE,MAAM;gBADhB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM;CAQnC"}

package/dist/source/filesystem-storage-backend.d.ts

@@ -0,0 +1,26 @@
+import type { ClefManifest } from "../types";
+import type { StorageBackend } from "./storage-backend";
+import type { CellRef, CellPendingMetadata } from "./types";
+export declare class FilesystemStorageBackend implements StorageBackend {
+    private readonly manifest;
+    private readonly repoRoot;
+    readonly id = "filesystem";
+    readonly description = "Filesystem-backed cell storage (default substrate)";
+    constructor(manifest: ClefManifest, repoRoot: string);
+    /**
+     * Resolve a cell reference to its absolute filesystem path. Public —
+     * used by substrate-specific trait implementations.
+     */
+    cellPath(cell: CellRef): string;
+    /** The repo root, exposed for filesystem-shaped trait implementations. */
+    getRepoRoot(): string;
+    blobFormat(cell: CellRef): "yaml" | "json";
+    readBlob(cell: CellRef): Promise<string>;
+    writeBlob(cell: CellRef, blob: string): Promise<void>;
+    deleteBlob(cell: CellRef): Promise<void>;
+    blobExists(cell: CellRef): Promise<boolean>;
+    readPendingMetadata(cell: CellRef): Promise<CellPendingMetadata>;
+    writePendingMetadata(cell: CellRef, meta: CellPendingMetadata): Promise<void>;
+    private sidecarPath;
+}
+//# sourceMappingURL=filesystem-storage-backend.d.ts.map

package/dist/source/filesystem-storage-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-storage-backend.d.ts","sourceRoot":"","sources":["../../src/source/filesystem-storage-backend.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAG5D,qBAAa,wBAAyB,YAAW,cAAc;IAK3D,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,QAAQ,CAAC,EAAE,gBAAgB;IAC3B,QAAQ,CAAC,WAAW,wDAAwD;gBAGzD,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,MAAM;IAGnC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM;IAO/B,0EAA0E;IAC1E,WAAW,IAAI,MAAM;IAIrB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM;IAIpC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAKxC,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBrD,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAI3C,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAIhE,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAInF,OAAO,CAAC,WAAW;CAKpB"}

package/dist/source/guards.d.ts

@@ -0,0 +1,14 @@
+import type { Bulk, Lintable, MergeAware, Migratable, RecipientManaged, Rotatable, SecretSource, SourceCapabilities, Structural } from "./types";
+export declare function isLintable(s: SecretSource): s is SecretSource & Lintable;
+export declare function isRotatable(s: SecretSource): s is SecretSource & Rotatable;
+export declare function isRecipientManaged(s: SecretSource): s is SecretSource & RecipientManaged;
+export declare function isMergeAware(s: SecretSource): s is SecretSource & MergeAware;
+export declare function isMigratable(s: SecretSource): s is SecretSource & Migratable;
+export declare function isBulk(s: SecretSource): s is SecretSource & Bulk;
+export declare function isStructural(s: SecretSource): s is SecretSource & Structural;
+/**
+ * Build a boolean capability descriptor for the source. Used by the UI
+ * server's `GET /api/capabilities` endpoint and by `clef doctor` output.
+ */
+export declare function describeCapabilities(s: SecretSource): SourceCapabilities;
+//# sourceMappingURL=guards.d.ts.map

package/dist/source/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/source/guards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACX,MAAM,SAAS,CAAC;AAqBjB,wBAAgB,UAAU,CAAC,CAAC,EAAE,YAAY,GAAG,CAAC,IAAI,YAAY,GAAG,QAAQ,CAExE;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,YAAY,GAAG,CAAC,IAAI,YAAY,GAAG,SAAS,CAE1E;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,YAAY,GAAG,CAAC,IAAI,YAAY,GAAG,gBAAgB,CAExF;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,YAAY,GAAG,CAAC,IAAI,YAAY,GAAG,UAAU,CAE5E;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,YAAY,GAAG,CAAC,IAAI,YAAY,GAAG,UAAU,CAE5E;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,YAAY,GAAG,CAAC,IAAI,YAAY,GAAG,IAAI,CAEhE;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,YAAY,GAAG,CAAC,IAAI,YAAY,GAAG,UAAU,CAO5E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,YAAY,GAAG,kBAAkB,CAUxE"}

package/dist/source/index.d.ts

@@ -0,0 +1,10 @@
+export type { AddRecipientRequest, Bulk, CellData, CellPendingMetadata, CellRef, Lintable, MergeAware, Migratable, RecipientDriftResult, RecipientManaged, RemoveRecipientRequest, Rotatable, SecretSource, SourceCapabilities, Structural, } from "./types";
+export { describeCapabilities, isBulk, isLintable, isMergeAware, isMigratable, isRecipientManaged, isRotatable, isStructural, } from "./guards";
+export { defaultBulk } from "./default-bulk";
+export { SourceCapabilityUnsupportedError } from "./errors";
+export { MockSecretSource } from "./mock-source";
+export type { StorageBackend } from "./storage-backend";
+export { FilesystemStorageBackend } from "./filesystem-storage-backend";
+export type { EncryptionBackend, EncryptionContext, RotateOptions } from "./encryption-backend";
+export { composeSecretSource } from "./compose";
+//# sourceMappingURL=index.d.ts.map

package/dist/source/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/source/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mBAAmB,EACnB,IAAI,EACJ,QAAQ,EACR,mBAAmB,EACnB,OAAO,EACP,QAAQ,EACR,UAAU,EACV,UAAU,EACV,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,UAAU,GACX,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,oBAAoB,EACpB,MAAM,EACN,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,YAAY,GACb,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,gCAAgC,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGjD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAChG,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC"}

package/dist/source/mock-source.d.ts

@@ -0,0 +1,89 @@
+/**
+ * In-memory test fixture used by CLI command tests and any future
+ * consumer that needs to exercise source-shaped code paths without a
+ * real git+SOPS substrate. Production code must NOT depend on this
+ * file — it is exported under `@clef-sh/core` solely so workspace
+ * tests can import it.
+ *
+ * Capability dialing: pass `capabilities: { lint: false, ... }` to
+ * construct a source missing specific traits, so tests can assert
+ * `SourceCapabilityUnsupportedError` paths (Phase 5+).
+ */
+import type { AddNamespaceOptions, AddEnvironmentOptions, AddRecipientRequest, CellPendingMetadata, CellRef, CellData, RecipientDriftResult, RemoveRecipientRequest, RotateOptions, SecretSource } from "./types";
+import type { ClefManifest, SopsMetadata } from "../types";
+import type { Recipient, RecipientsResult } from "../recipients";
+import type { MigrationOptions, MigrationResult, MigrationTarget } from "../migration/backend";
+import type { MergeResult } from "../merge/driver";
+interface MockCapabilityToggles {
+    lint?: boolean;
+    rotate?: boolean;
+    recipients?: boolean;
+    merge?: boolean;
+    migrate?: boolean;
+    bulk?: boolean;
+    structural?: boolean;
+}
+interface MockSecretSourceOptions {
+    id?: string;
+    description?: string;
+    /** Pre-populated cell values keyed by `${namespace}/${environment}`. */
+    cells?: Record<string, Record<string, string>>;
+    /** Default recipients populated into every read cell's metadata. */
+    recipients?: string[];
+    /** Capability toggles (default: all true). */
+    capabilities?: MockCapabilityToggles;
+}
+/**
+ * In-memory `SecretSource` implementing every trait by default. Toggle
+ * capabilities off via the `capabilities` constructor option to
+ * simulate a source that does not support a given feature.
+ *
+ * The `_disabled*` private fields exist because TypeScript type guards
+ * detect trait support by method presence. To "disable" a capability
+ * the corresponding methods are simply not defined on the instance —
+ * the public class definition declares them, but the constructor
+ * deletes them when toggled off.
+ */
+export declare class MockSecretSource implements SecretSource {
+    readonly id: string;
+    readonly description: string;
+    private readonly cells;
+    private readonly pending;
+    private readonly recipients;
+    constructor(options?: MockSecretSourceOptions);
+    readCell(cell: CellRef): Promise<CellData>;
+    writeCell(cell: CellRef, values: Record<string, string>): Promise<void>;
+    deleteCell(cell: CellRef): Promise<void>;
+    cellExists(cell: CellRef): Promise<boolean>;
+    listKeys(cell: CellRef): Promise<string[]>;
+    getCellMetadata(_cell: CellRef): Promise<SopsMetadata>;
+    scaffoldCell(cell: CellRef, _manifest: ClefManifest): Promise<void>;
+    getPendingMetadata(cell: CellRef): Promise<CellPendingMetadata>;
+    markPending(cell: CellRef, keys: string[], setBy: string): Promise<void>;
+    markResolved(cell: CellRef, keys: string[]): Promise<void>;
+    recordRotation(cell: CellRef, keys: string[], rotatedBy: string): Promise<void>;
+    removeRotation(cell: CellRef, keys: string[]): Promise<void>;
+    validateEncryption(cell: CellRef): Promise<boolean>;
+    checkRecipientDrift(_cell: CellRef, expected: string[]): Promise<RecipientDriftResult>;
+    rotate(_cell: CellRef, _opts: RotateOptions): Promise<void>;
+    listRecipients(_manifest: ClefManifest, _environment?: string): Promise<Recipient[]>;
+    addRecipient(req: AddRecipientRequest): Promise<RecipientsResult>;
+    removeRecipient(req: RemoveRecipientRequest): Promise<RecipientsResult>;
+    mergeCells(_base: CellRef, _ours: CellRef, _theirs: CellRef): Promise<MergeResult>;
+    installMergeDriver(_repoRoot: string): Promise<void>;
+    uninstallMergeDriver(_repoRoot: string): Promise<void>;
+    installHooks(_repoRoot: string): Promise<void>;
+    uninstallHooks(_repoRoot: string): Promise<void>;
+    migrateBackend(_target: MigrationTarget, _opts: MigrationOptions): Promise<MigrationResult>;
+    bulkSet(namespace: string, key: string, valuesByEnv: Record<string, string>, manifest: ClefManifest): Promise<void>;
+    bulkDelete(namespace: string, key: string, manifest: ClefManifest): Promise<void>;
+    copyValue(key: string, from: CellRef, to: CellRef, manifest: ClefManifest): Promise<void>;
+    addNamespace(_name: string, _opts: AddNamespaceOptions, _manifest: ClefManifest): Promise<void>;
+    removeNamespace(name: string, _manifest: ClefManifest): Promise<void>;
+    renameNamespace(from: string, to: string, _manifest: ClefManifest): Promise<void>;
+    addEnvironment(_name: string, _opts: AddEnvironmentOptions, _manifest: ClefManifest): Promise<void>;
+    removeEnvironment(name: string, _manifest: ClefManifest): Promise<void>;
+    renameEnvironment(from: string, to: string, _manifest: ClefManifest): Promise<void>;
+}
+export {};
+//# sourceMappingURL=mock-source.d.ts.map

package/dist/source/mock-source.d.ts.map

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

package/dist/source/storage-backend.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `StorageBackend` is the substrate-level plugin-author surface for *where*
+ * ciphertext bytes live. It is one of two orthogonal abstractions composed
+ * into a `SecretSource`:
+ *
+ *   - `StorageBackend`    — substrate (filesystem, postgres, S3, ...)
+ *   - `EncryptionBackend` — encryption (SOPS, age-direct, custom, ...)
+ *
+ * Both vary independently. Any combination — `(filesystem, sops)`,
+ * `(postgres, sops)`, `(filesystem, custom)`, `(postgres, custom)` —
+ * produces a working `SecretSource` via `composeSecretSource(storage,
+ * encryption, manifest)`.
+ *
+ * Implementations have **zero** knowledge of encryption, recipients, KMS,
+ * or age. They store and retrieve opaque bytes by `CellRef` and a small
+ * metadata sidecar; plugin authors never re-implement encryption.
+ *
+ * Format of the bytes:
+ *   - Whatever the paired `EncryptionBackend` produces and consumes
+ *     (SOPS YAML/JSON for `sops`; could be anything for a custom backend).
+ *   - The `StorageBackend` does not parse the bytes; it stores and
+ *     retrieves them verbatim.
+ *
+ * Atomicity:
+ *   - `writeBlob` MUST be atomic from the caller's perspective. A torn
+ *     write would leave the cell in an undecryptable state. Filesystem
+ *     impls use temp-file + rename; database impls use a transaction.
+ */
+import type { CellRef, CellPendingMetadata } from "./types";
+export interface StorageBackend {
+    /** Stable identifier for diagnostic output (e.g. `"filesystem"`, `"postgres"`). */
+    readonly id: string;
+    /** Short human-readable description, used in `clef doctor`. */
+    readonly description: string;
+    /**
+     * Read the cell's ciphertext bytes. Throws if the cell does not exist —
+     * callers should use `blobExists` first when absence is a valid state.
+     */
+    readBlob(cell: CellRef): Promise<string>;
+    /** Atomically replace the cell's ciphertext bytes. Idempotent. */
+    writeBlob(cell: CellRef, blob: string): Promise<void>;
+    /** Remove the cell's blob. No-op if it does not exist. */
+    deleteBlob(cell: CellRef): Promise<void>;
+    /** Whether the cell currently has stored ciphertext. */
+    blobExists(cell: CellRef): Promise<boolean>;
+    /**
+     * Format hint for the cell's bytes. Forwarded to the paired
+     * `EncryptionBackend` so it can pick the right input/output type. The
+     * filesystem substrate derives this from the file extension; other
+     * substrates pick a fixed format.
+     */
+    blobFormat(cell: CellRef): "yaml" | "json";
+    /**
+     * Read pending + rotation metadata for the cell. Returns an empty
+     * record when no metadata exists. Never throws on missing.
+     */
+    readPendingMetadata(cell: CellRef): Promise<CellPendingMetadata>;
+    /** Atomically replace the cell's pending + rotation metadata. */
+    writePendingMetadata(cell: CellRef, meta: CellPendingMetadata): Promise<void>;
+}
+//# sourceMappingURL=storage-backend.d.ts.map

package/dist/source/storage-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-backend.d.ts","sourceRoot":"","sources":["../../src/source/storage-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzC,kEAAkE;IAClE,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtD,0DAA0D;IAC1D,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC,wDAAwD;IACxD,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE5C;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAE3C;;;OAGG;IACH,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEjE,iEAAiE;IACjE,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E"}