@clef-sh/core 0.1.28 → 0.2.0

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"}

package/dist/source/types.d.ts

@@ -0,0 +1,212 @@
+/**
+ * `SecretSource` is the high-level cell-storage seam consumed by every
+ * non-source-specific consumer (CLI commands, UI server, pack backends).
+ * Methods take and return plaintext at this boundary; encryption is a
+ * lower-layer concern that does not appear in this contract.
+ *
+ * Architecture (introduced in Phase 2):
+ *
+ *   ┌─────────────────────────────────────────────────────┐
+ *   │  SecretSource    plaintext cells, what consumers see │
+ *   ├─────────────────────────────────────────────────────┤
+ *   │  SopsClient      uniform encryption (KMS/age via     │
+ *   │                  the SOPS subprocess)                │
+ *   ├─────────────────────────────────────────────────────┤
+ *   │  BlobStore       opaque ciphertext bytes by CellRef  │
+ *   └─────────────────────────────────────────────────────┘
+ *
+ * The bundled `GitSopsSource` is composed from `FilesystemBlobStore +
+ * SopsClient + manifest`. A future third-party source plugs in by
+ * implementing `BlobStore` (a small, encryption-free interface) — the
+ * encryption layer is provided uniformly by clef. Plugin authors do
+ * not implement encryption primitives.
+ *
+ * The optional capability traits (`Lintable`, `Rotatable`, etc.)
+ * declare functionality some sources can offer and others cannot.
+ * SOPS-backed traits (lint/rotate/recipients/migrate) are uniform
+ * across every source because they live at the SopsClient layer.
+ * Substrate-shaped traits (`MergeAware`, `Structural`) are decided by
+ * the BlobStore. Consumers use the type guards in `./guards` for
+ * runtime detection; CLI commands and UI routes that require an
+ * unsupported capability fail fast with
+ * `SourceCapabilityUnsupportedError` (see `./errors`).
+ */
+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";
+import type { CellMetadata as PendingCellMetadata } from "../pending/metadata";
+import type { AddNamespaceOptions, AddEnvironmentOptions } from "../structure/manager";
+import type { RotateOptions } from "./encryption-backend";
+export type { RotateOptions };
+/** Identifies a cell in the namespace × environment matrix. */
+export interface CellRef {
+    namespace: string;
+    environment: string;
+}
+/** Result of decrypting / loading a cell's contents. */
+export interface CellData {
+    values: Record<string, string>;
+    /**
+     * Source-reported metadata. For `git-sops` this carries the SOPS
+     * envelope fields (recipients, lastModified, backend, version).
+     * Sources with no native equivalent populate sensible defaults.
+     */
+    metadata: SopsMetadata;
+}
+/**
+ * Pending and rotation metadata for a cell. Mirrors the existing
+ * `.clef-meta.yaml` data model so the only thing that changes is *where*
+ * the metadata lives — file sidecar (git-sops) vs. database row
+ * (postgres) etc.
+ */
+export type CellPendingMetadata = PendingCellMetadata;
+/**
+ * Boolean capability descriptor returned by `describeCapabilities` and
+ * surfaced to UI clients via `GET /api/capabilities`. Field names match
+ * the trait identifier so adding a new trait means adding one boolean.
+ */
+export interface SourceCapabilities {
+    lint: boolean;
+    rotate: boolean;
+    recipients: boolean;
+    merge: boolean;
+    migrate: boolean;
+    bulk: boolean;
+    structural: boolean;
+}
+/**
+ * Core contract every source must implement. Operations are cell-level
+ * — callers never need to know about file paths, table names, or any
+ * other substrate detail.
+ *
+ * Methods throw `ClefError` (or one of its subclasses such as
+ * `SopsDecryptionError` / `SopsKeyNotFoundError`) on failure. Sources
+ * are expected to translate substrate-specific errors into the Clef
+ * hierarchy so CLI/UI consumers can render uniform error messages.
+ */
+export interface SecretSource {
+    /** Stable source identifier (e.g. `"git-sops"`, `"postgres"`). */
+    readonly id: string;
+    /** Short human-readable description, used in `clef doctor` output. */
+    readonly description: string;
+    /** Decrypt / load the cell's values and metadata. */
+    readCell(cell: CellRef): Promise<CellData>;
+    /**
+     * Replace the cell's values atomically. Implementations must ensure
+     * a failure mid-write does not leave partial values visible.
+     */
+    writeCell(cell: CellRef, values: Record<string, string>): Promise<void>;
+    /** Remove the cell entirely (or its scaffolded equivalent). */
+    deleteCell(cell: CellRef): Promise<void>;
+    /** Whether the cell currently has stored data. */
+    cellExists(cell: CellRef): Promise<boolean>;
+    /**
+     * List the keys present in the cell. Sources that can answer this
+     * without decrypting (git-sops reads `data.*` keys from the SOPS
+     * file) should do so for performance; otherwise a default
+     * implementation can decrypt and return `Object.keys`.
+     */
+    listKeys(cell: CellRef): Promise<string[]>;
+    /** Read source-reported metadata without loading values. */
+    getCellMetadata(cell: CellRef): Promise<SopsMetadata>;
+    /**
+     * Create a new (or empty) cell consistent with the manifest's
+     * declared recipients/backend for this environment. Idempotent.
+     */
+    scaffoldCell(cell: CellRef, manifest: ClefManifest): Promise<void>;
+    /** Pending + rotation metadata. */
+    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>;
+}
+/**
+ * Source-specific lint checks. Portable matrix-completeness lint runs
+ * over every source via the core interface and is *not* part of this
+ * trait — only checks that depend on the substrate (e.g. SOPS envelope
+ * integrity, recipient drift) live here.
+ */
+export interface Lintable {
+    /** Whether the cell has valid encryption envelope metadata. */
+    validateEncryption(cell: CellRef): Promise<boolean>;
+    /** Compare the cell's actual recipients against the expected set. */
+    checkRecipientDrift(cell: CellRef, expected: string[]): Promise<RecipientDriftResult>;
+}
+/** Result of `Lintable.checkRecipientDrift`. */
+export interface RecipientDriftResult {
+    /** Recipients expected by the manifest but absent from the cell. */
+    missing: string[];
+    /** Recipients present on the cell but not in the manifest. */
+    unexpected: string[];
+}
+/**
+ * Re-key a cell: rotate the data encryption key and/or update the
+ * recipient set without exposing plaintext to the calling process. The
+ * `RotateOptions` shape mirrors the substrate-level `EncryptionBackend`
+ * — at the SOPS layer that means add/remove for any of age, AWS KMS,
+ * GCP KMS, Azure KV, PGP. Backends interpret only the keys they
+ * understand.
+ */
+export interface Rotatable {
+    rotate(cell: CellRef, opts: RotateOptions): Promise<void>;
+}
+/**
+ * Manifest-level recipient management. `add` and `remove` mutate both
+ * the manifest declaration and re-encrypt every affected cell — the
+ * trait bundles these because list/add/remove are useless apart.
+ */
+export interface RecipientManaged {
+    listRecipients(manifest: ClefManifest, environment?: string): Promise<Recipient[]>;
+    addRecipient(req: AddRecipientRequest): Promise<RecipientsResult>;
+    removeRecipient(req: RemoveRecipientRequest): Promise<RecipientsResult>;
+}
+export interface AddRecipientRequest {
+    key: string;
+    label?: string;
+    environment?: string;
+    manifest: ClefManifest;
+}
+export interface RemoveRecipientRequest {
+    key: string;
+    environment?: string;
+    manifest: ClefManifest;
+}
+/** Three-way merge + git driver/hook installation. */
+export interface MergeAware {
+    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>;
+}
+/** Re-encrypt every cell to a new SOPS backend (e.g. age → awskms). */
+export interface Migratable {
+    migrateBackend(target: MigrationTarget, opts: MigrationOptions): Promise<MigrationResult>;
+}
+/**
+ * Batch operations across the matrix. Sources that can do these in a
+ * single round-trip (e.g. one SQL transaction) should implement the
+ * trait directly; otherwise consumers wrap a `SecretSource` in
+ * `defaultBulk` for a correct-but-slow looped fallback.
+ */
+export interface Bulk {
+    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>;
+}
+/**
+ * Namespace + environment CRUD. On a file-based source this cascades
+ * to file/folder renames; on a DB source it's a metadata table update.
+ */
+export interface Structural {
+    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 type { AddNamespaceOptions, AddEnvironmentOptions };
+//# sourceMappingURL=types.d.ts.map

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

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