@clef-sh/core 0.1.17 → 0.1.19

package/dist/lint/runner.d.ts

@@ -24,6 +24,13 @@ export declare class LintRunner {
      * @param repoRoot - Absolute path to the repository root.
      */
     run(manifest: ClefManifest, repoRoot: string): Promise<LintResult>;
+    /**
+     * Cross-reference `.clef-meta.yaml` against the cipher's plaintext key
+     * names for each existing cell.  Reports orphan rotation records and
+     * dual-state (pending + rotation) inconsistencies.  Uses
+     * {@link readSopsKeyNames} (plaintext YAML parse) — no decryption.
+     */
+    private lintMetadataConsistency;
     /**
      * Lint service identity configurations for drift issues.
      */

package/dist/lint/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/lint/runner.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EAEZ,UAAU,EAIX,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7C;;;;;;;;GAQG;AACH,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAFV,aAAa,EAAE,aAAa,EAC5B,eAAe,EAAE,eAAe,EAChC,UAAU,EAAE,iBAAiB;IAGhD;;;;;;OAMG;IACG,GAAG,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA6NxE;;OAEG;YACW,qBAAqB;IAoGnC;;;;;OAKG;IACG,GAAG,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CAWzE"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/lint/runner.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EAEZ,UAAU,EAIX,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAI7C;;;;;;;;GAQG;AACH,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAFV,aAAa,EAAE,aAAa,EAC5B,eAAe,EAAE,eAAe,EAChC,UAAU,EAAE,iBAAiB;IAGhD;;;;;;OAMG;IACG,GAAG,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAmOxE;;;;;OAKG;YACW,uBAAuB;IAgDrC;;OAEG;YACW,qBAAqB;IAoGnC;;;;;OAKG;IACG,GAAG,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CAWzE"}

package/dist/manifest/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/manifest/parser.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,YAAY,EAKb,MAAM,UAAU,CAAC;AAGlB;;;GAGG;AACH,eAAO,MAAM,sBAAsB,cAAc,CAAC;AAelD;;;;;;;;GAQG;AACH,qBAAa,cAAc;IACzB;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY;IAsBrC;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY;IAujBtC;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI;CAchF"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/manifest/parser.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,YAAY,EAKb,MAAM,UAAU,CAAC;AAGlB;;;GAGG;AACH,eAAO,MAAM,sBAAsB,cAAc,CAAC;AAuBlD;;;;;;;;GAQG;AACH,qBAAa,cAAc;IACzB;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY;IAsBrC;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY;IA+lBtC;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI;CAchF"}

package/dist/merge/metadata-driver.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Merge two `.clef-meta.yaml` contents (as strings).  Does not read the
+ * base revision — the timestamp-ordered merge is associative without one,
+ * which is the whole reason we can auto-resolve.  The caller is
+ * responsible for reading / writing from disk.
+ *
+ * Returns the merged YAML content with the standard Clef header comment.
+ */
+export declare function mergeMetadataContents(oursContent: string, theirsContent: string): string;
+/**
+ * Filesystem wrapper around {@link mergeMetadataContents}.  Reads ours and
+ * theirs, writes the merged result back to `oursPath` (the conventional
+ * destination git passes as `%A`).  Does not read `basePath` — see the
+ * merge algorithm's docstring for why a base revision is not needed.
+ */
+export declare function mergeMetadataFiles(_basePath: string, oursPath: string, theirsPath: string): void;
+//# sourceMappingURL=metadata-driver.d.ts.map

package/dist/merge/metadata-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-driver.d.ts","sourceRoot":"","sources":["../../src/merge/metadata-driver.ts"],"names":[],"mappings":"AAgNA;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAQxF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAKhG"}

package/dist/migration/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/migration/backend.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,uBAAuB,EAGxB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGlD,OAAO,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAE3C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,WAAW,CAAC;IACrB,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,uBAAuB,GAAG,SAAS,CAM7F,CAAC;AAMF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,uBAAuB,CAOzB;AAUD,qBAAa,eAAe;IAcxB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,EAAE;IAdrB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoB;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoB;IAEnD;;;;;;;OAOG;gBAED,UAAU,EAAE,iBAAiB,EACZ,aAAa,EAAE,aAAa,EAC5B,EAAE,EAAE,kBAAkB,EACvC,gBAAgB,CAAC,EAAE,iBAAiB;IAMhC,OAAO,CACX,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,EACzB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,GACnD,OAAO,CAAC,eAAe,CAAC;IAoL3B,OAAO,CAAC,iBAAiB;IA8BzB,OAAO,CAAC,yBAAyB;CAmBlC"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/migration/backend.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,uBAAuB,EAGxB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGlD,OAAO,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAE3C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,WAAW,CAAC;IACrB,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,uBAAuB,GAAG,SAAS,CAO7F,CAAC;AAMF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,uBAAuB,CAOzB;AAUD,qBAAa,eAAe;IAcxB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,EAAE;IAdrB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoB;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoB;IAEnD;;;;;;;OAOG;gBAED,UAAU,EAAE,iBAAiB,EACZ,aAAa,EAAE,aAAa,EAC5B,EAAE,EAAE,kBAAkB,EACvC,gBAAgB,CAAC,EAAE,iBAAiB;IAMhC,OAAO,CACX,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,EACzB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,GACnD,OAAO,CAAC,eAAe,CAAC;IAoL3B,OAAO,CAAC,iBAAiB;IA8BzB,OAAO,CAAC,yBAAyB;CAmBlC"}

package/dist/pack/backends/json-envelope.d.ts

@@ -0,0 +1,33 @@
+import type { PackOutput } from "../../artifact/types";
+import type { BackendPackResult, PackBackend, PackRequest } from "../types";
+/**
+ * Options specific to the {@link JsonEnvelopeBackend}. At least one of
+ * `outputPath` or `output` must be provided; `signingKey` and
+ * `signingKmsKeyId` are mutually exclusive.
+ */
+export interface JsonEnvelopeOptions {
+    /** Local file path for the artifact JSON. Used when `output` is not provided. */
+    outputPath?: string;
+    /**
+     * Pre-constructed output backend. Takes precedence over `outputPath`.
+     * Used by `clef serve` with {@link MemoryPackOutput} to avoid disk I/O.
+     */
+    output?: PackOutput;
+    /** Ed25519 private key for artifact signing (base64 DER PKCS8). */
+    signingKey?: string;
+    /** KMS asymmetric signing key ARN/ID (ECDSA_SHA_256). Mutually exclusive with signingKey. */
+    signingKmsKeyId?: string;
+}
+/**
+ * Default pack backend. Produces the canonical Clef JSON artifact
+ * envelope (age-encrypted for age identities, AES-256-GCM with
+ * KMS-wrapped DEK for KMS-envelope identities) and writes it to
+ * a file or a provided output adapter.
+ */
+export declare class JsonEnvelopeBackend implements PackBackend {
+    readonly id = "json-envelope";
+    readonly description = "Write the Clef JSON artifact envelope to a local file (default).";
+    validateOptions(raw: Record<string, unknown>): void;
+    pack(req: PackRequest): Promise<BackendPackResult>;
+}
+//# sourceMappingURL=json-envelope.d.ts.map

package/dist/pack/backends/json-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-envelope.d.ts","sourceRoot":"","sources":["../../../src/pack/backends/json-envelope.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5E;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6FAA6F;IAC7F,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACrD,QAAQ,CAAC,EAAE,mBAAmB;IAC9B,QAAQ,CAAC,WAAW,sEAAsE;IAE1F,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAY7C,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA8BzD"}

package/dist/pack/registry.d.ts

@@ -0,0 +1,27 @@
+import type { PackBackend, PackBackendFactory } from "./types";
+/**
+ * Registry of pack backends. The CLI registers `clef-native` eagerly and
+ * may register additional backends discovered via optional plugin packages
+ * (e.g. `@clef-sh/pack-vault`). Embedders (tests, IaC synth hooks) may
+ * construct a registry directly and register only the backends they need.
+ */
+export declare class PackBackendRegistry {
+    private readonly factories;
+    /**
+     * Register a backend factory under the given id. Throws if a backend
+     * with the same id is already registered — collisions surface as a clear
+     * error rather than a silent overwrite.
+     */
+    register(id: string, factory: PackBackendFactory): void;
+    /** Whether a backend with the given id has been registered. */
+    has(id: string): boolean;
+    /** Registered backend ids, in registration order. */
+    list(): string[];
+    /**
+     * Resolve a backend by id. Throws if unknown. Factories may be async so
+     * a plugin package can defer construction (e.g. loading a heavy SDK only
+     * when the backend is actually used).
+     */
+    resolve(id: string): Promise<PackBackend>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/pack/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/pack/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyC;IAEnE;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAOvD,+DAA+D;IAC/D,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,qDAAqD;IACrD,IAAI,IAAI,MAAM,EAAE;IAIhB;;;;OAIG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAQhD"}

package/dist/pack/types.d.ts

@@ -0,0 +1,78 @@
+import type { ClefManifest, EncryptionBackend, SubprocessRunner } from "../types";
+import type { KmsProvider } from "../kms";
+import type { PackResult } from "../artifact/types";
+/**
+ * Shared services a PackBackend may use. A backend is free to ignore any
+ * field it does not need.
+ */
+export interface PackServices {
+    /** Decryption/encryption of SOPS source files in the matrix. */
+    encryption: EncryptionBackend;
+    /** KMS provider, already constructed. Undefined when the manifest does not require one. */
+    kms?: KmsProvider;
+    /** For subprocess access (git, external CLIs). Prefer this over child_process. */
+    runner: SubprocessRunner;
+}
+/**
+ * Input to `PackBackend.pack`. Fields are the intersection of what all
+ * conceivable backends need; anything backend-specific lives in
+ * `backendOptions` and is typed and validated by the backend itself.
+ *
+ * Implementations must not read `process.env`, log decrypted values, or
+ * call `process.exit` — a `PackRequest` may be constructed by any caller
+ * (CLI, IaC synth-time hook, test), not just the `clef pack` command.
+ */
+export interface PackRequest {
+    /** Service identity name from the manifest. */
+    identity: string;
+    /** Target environment name. */
+    environment: string;
+    /** Parsed manifest. */
+    manifest: ClefManifest;
+    /** Absolute path to the clef repo root. */
+    repoRoot: string;
+    /** Shared services the backend may use. */
+    services: PackServices;
+    /** Optional TTL in seconds. Backends that do not support it should ignore. */
+    ttl?: number;
+    /** Backend-specific options; shape is the backend's private concern. */
+    backendOptions: Record<string, unknown>;
+}
+/**
+ * Result of a `PackBackend.pack` call. Extends the existing `PackResult`
+ * with the backend identifier and a freeform details map for per-backend
+ * diagnostics.
+ */
+export interface BackendPackResult extends PackResult {
+    /** Identifier of the backend that produced this result (e.g. `"clef-native"`). */
+    backend: string;
+    /**
+     * Freeform per-backend diagnostic detail (e.g. secret ARN, bucket key,
+     * commit SHA). Values must be JSON-serializable.
+     */
+    details?: Record<string, string | number | boolean | null>;
+}
+/**
+ * Contract for a pack destination. A backend turns a (identity, environment)
+ * pair into whatever its target system requires — a local JSON file for
+ * `clef-native`, a Vault KV write for a future vault backend, and so on.
+ */
+export interface PackBackend {
+    /** Stable backend identifier (e.g. `"clef-native"`, `"aws-secrets"`, `"vault"`). */
+    readonly id: string;
+    /** Short human description, used by `clef pack --help` and diagnostics. */
+    readonly description: string;
+    /**
+     * Validate and normalize backend-specific options. Throw with a precise
+     * error message on invalid input. Called before `pack`.
+     */
+    validateOptions?(raw: Record<string, unknown>): void;
+    /**
+     * Perform the pack. Must not log plaintext secrets, must not write
+     * plaintext to disk, and must not depend on process-global state.
+     */
+    pack(req: PackRequest): Promise<BackendPackResult>;
+}
+/** Factory signature used by `PackBackendRegistry.register`. */
+export type PackBackendFactory = () => PackBackend | Promise<PackBackend>;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pack/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAClF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,UAAU,EAAE,iBAAiB,CAAC;IAC9B,2FAA2F;IAC3F,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,kFAAkF;IAClF,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,QAAQ,EAAE,YAAY,CAAC;IACvB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;CAC5D;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,eAAe,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACrD;;;OAGG;IACH,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACpD;AAED,gEAAgE;AAChE,MAAM,MAAM,kBAAkB,GAAG,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC"}

package/dist/pending/metadata.d.ts

@@ -3,26 +3,38 @@ interface PendingKey {
     since: Date;
     setBy: string;
 }
-interface PendingMetadata {
+interface RotationRecord {
+    key: string;
+    lastRotatedAt: Date;
+    rotatedBy: string;
+    rotationCount: number;
+}
+/**
+ * Parsed contents of a `.clef-meta.yaml` sidecar.
+ *
+ * Both `pending` and `rotations` may be empty arrays — they represent two
+ * independent per-key state sections.  A fresh cell with no sidecar file
+ * on disk is represented as `{ version: 1, pending: [], rotations: [] }`.
+ */
+interface CellMetadata {
     version: 1;
     pending: PendingKey[];
+    rotations: RotationRecord[];
 }
+/** @deprecated Use {@link CellMetadata}.  Retained for external import compatibility. */
+type PendingMetadata = CellMetadata;
 /**
  * Derive the `.clef-meta.yaml` path from an `.enc.yaml` path.
  * Example: `database/dev.enc.yaml` → `database/dev.clef-meta.yaml`
  */
 declare function metadataPath(encryptedFilePath: string): string;
-/** Load pending-key metadata for an encrypted file. Returns empty metadata if the file is missing. */
-declare function loadMetadata(filePath: string): Promise<PendingMetadata>;
-/** Write pending-key metadata to disk. Creates parent directories if needed. */
-declare function saveMetadata(filePath: string, metadata: PendingMetadata): Promise<void>;
+/** Load metadata for an encrypted file.  Returns empty metadata if the file is missing or unreadable. */
+declare function loadMetadata(filePath: string): Promise<CellMetadata>;
+/** Write metadata to disk.  Creates parent directories if needed. */
+declare function saveMetadata(filePath: string, metadata: CellMetadata): Promise<void>;
 /**
  * Mark one or more keys as pending (placeholder value) for an encrypted file.
  * If a key is already pending, its timestamp and `setBy` are updated.
- *
- * @param filePath - Path to the encrypted file.
- * @param keys - Key names to mark as pending.
- * @param setBy - Identifier of the actor setting these keys (e.g. a username or CI job).
  */
 declare function markPending(filePath: string, keys: string[], setBy: string): Promise<void>;
 /** Remove keys from the pending list after they have received real values. */
@@ -31,16 +43,29 @@ declare function markResolved(filePath: string, keys: string[]): Promise<void>;
 declare function getPendingKeys(filePath: string): Promise<string[]>;
 /** Check whether a single key is currently pending for the given encrypted file. */
 declare function isPending(filePath: string, key: string): Promise<boolean>;
+/**
+ * Record a rotation for one or more keys.  Creates a new record when the key
+ * has never rotated before (rotation_count: 1), or upserts an existing record
+ * by bumping rotation_count and updating last_rotated_at + rotated_by.
+ *
+ * Also removes the corresponding `pending` entry if present — a rotation is
+ * the resolution of a pending placeholder, so the two states are mutually
+ * exclusive.
+ */
+declare function recordRotation(filePath: string, keys: string[], rotatedBy: string, now?: Date): Promise<void>;
+/**
+ * Remove rotation records for the given keys.  Called when a key is deleted
+ * from the cell via `clef delete` — leaving a stale record would mislead
+ * policy evaluation.
+ */
+declare function removeRotation(filePath: string, keys: string[]): Promise<void>;
+/** Return the rotation records currently recorded for the given encrypted file. */
+declare function getRotations(filePath: string): Promise<RotationRecord[]>;
 /** Generate a cryptographically random 64-character hex string for use as a placeholder value. */
 declare function generateRandomValue(): string;
 /**
  * Same as {@link markPending} but retries once after `retryDelayMs` on transient failure.
- *
- * @param filePath - Path to the encrypted file.
- * @param keys - Key names to mark as pending.
- * @param setBy - Identifier of the actor setting these keys.
- * @param retryDelayMs - Delay in milliseconds before the single retry (default: 200).
  */
 declare function markPendingWithRetry(filePath: string, keys: string[], setBy: string, retryDelayMs?: number): Promise<void>;
-export { PendingKey, PendingMetadata, metadataPath, loadMetadata, saveMetadata, markPending, markPendingWithRetry, markResolved, getPendingKeys, isPending, generateRandomValue, };
+export { PendingKey, RotationRecord, CellMetadata, PendingMetadata, metadataPath, loadMetadata, saveMetadata, markPending, markPendingWithRetry, markResolved, getPendingKeys, isPending, recordRotation, removeRotation, getRotations, generateRandomValue, };
 //# sourceMappingURL=metadata.d.ts.map

package/dist/pending/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/pending/metadata.ts"],"names":[],"mappings":"AAiBA,UAAU,UAAU;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,eAAe;IACvB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;;GAGG;AACH,iBAAS,YAAY,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAIvD;AAID,sGAAsG;AACtG,iBAAe,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAsBtE;AAED,gFAAgF;AAChF,iBAAe,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAetF;AAED;;;;;;;GAOG;AACH,iBAAe,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAazF;AAED,8EAA8E;AAC9E,iBAAe,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAI3E;AAED,wFAAwF;AACxF,iBAAe,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAGjE;AAED,oFAAoF;AACpF,iBAAe,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGxE;AAED,kGAAkG;AAClG,iBAAS,mBAAmB,IAAI,MAAM,CAErC;AAED;;;;;;;GAOG;AACH,iBAAe,oBAAoB,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,MAAM,EACb,YAAY,SAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,OAAO,EACL,UAAU,EACV,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,SAAS,EACT,mBAAmB,GACpB,CAAC"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/pending/metadata.ts"],"names":[],"mappings":"AAoCA,UAAU,UAAU;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,cAAc;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,UAAU,YAAY;IACpB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,SAAS,EAAE,cAAc,EAAE,CAAC;CAC7B;AAED,yFAAyF;AACzF,KAAK,eAAe,GAAG,YAAY,CAAC;AAEpC;;;GAGG;AACH,iBAAS,YAAY,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAIvD;AAQD,yGAAyG;AACzG,iBAAe,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAiDnE;AAED,qEAAqE;AACrE,iBAAe,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBnF;AAED;;;GAGG;AACH,iBAAe,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYzF;AAED,8EAA8E;AAC9E,iBAAe,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAI3E;AAED,wFAAwF;AACxF,iBAAe,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAGjE;AAED,oFAAoF;AACpF,iBAAe,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGxE;AAED;;;;;;;;GAQG;AACH,iBAAe,cAAc,CAC3B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,IAAiB,GACrB,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED;;;;GAIG;AACH,iBAAe,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7E;AAED,mFAAmF;AACnF,iBAAe,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAGvE;AAED,kGAAkG;AAClG,iBAAS,mBAAmB,IAAI,MAAM,CAErC;AAED;;GAEG;AACH,iBAAe,oBAAoB,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,MAAM,EACb,YAAY,SAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,OAAO,EACL,UAAU,EACV,cAAc,EACd,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,SAAS,EACT,cAAc,EACd,cAAc,EACd,YAAY,EACZ,mBAAmB,GACpB,CAAC"}

package/dist/policy/evaluator.d.ts

@@ -13,27 +13,37 @@
  * See docs/contributing/testing.md for the rationale.
  */
 import { SopsMetadata } from "../types";
+import { RotationRecord } from "../pending/metadata";
 import { FileRotationStatus, PolicyDocument } from "./types";
 /**
- * Evaluates SOPS file metadata against a {@link PolicyDocument}.
+ * Evaluates per-key rotation state against a {@link PolicyDocument}.
  *
  * The evaluator is intentionally pure — it never reads the filesystem and
- * never decrypts.  All inputs come from the caller.
+ * never decrypts.  All inputs (file metadata, key names, rotation records)
+ * come from the caller.
  */
 export declare class PolicyEvaluator {
     private readonly policy;
     constructor(policy: PolicyDocument);
     /**
-     * Evaluate a single encrypted file's rotation state.
+     * Evaluate a single encrypted file's per-key rotation state.
      *
      * @param filePath    Repo-relative or absolute path to the encrypted file.
-     * @param environment Environment name from the matrix; selects per-env
-     *                    overrides if present in the policy.
-     * @param metadata    Result of `SopsClient.getMetadata()` for the file.
-     * @param now         Reference time (defaults to `new Date()`).  Inject for
-     *                    deterministic tests and reproducible audits.
+     * @param environment Environment name; selects per-env overrides.
+     * @param metadata    SOPS metadata for the file (carries last_modified,
+     *                    backend, recipients).  The evaluator does not read
+     *                    `last_modified` for the policy gate — it is echoed
+     *                    into the output for audit consumers only.
+     * @param keys        Plaintext key names present in the cipher, enumerated
+     *                    from the unencrypted YAML top-level keys (no decrypt
+     *                    required since SOPS stores key names in plaintext).
+     * @param rotations   Rotation records from `.clef-meta.yaml`.  Records for
+     *                    keys not in `keys` are ignored (those are orphans;
+     *                    lint surfaces them as a warning).
+     * @param now         Reference time.  Inject for deterministic tests.
      */
-    evaluateFile(filePath: string, environment: string, metadata: SopsMetadata, now?: Date): FileRotationStatus;
+    evaluateFile(filePath: string, environment: string, metadata: SopsMetadata, keys: string[], rotations: RotationRecord[], now?: Date): FileRotationStatus;
+    private evaluateKey;
     private resolveMaxAgeDays;
 }
 //# sourceMappingURL=evaluator.d.ts.map

package/dist/policy/evaluator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/policy/evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAM7D;;;;;GAKG;AACH,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,cAAc;IAEnD;;;;;;;;;OASG;IACH,YAAY,CACV,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,YAAY,EACtB,GAAG,GAAE,IAAiB,GACrB,kBAAkB;IA2BrB,OAAO,CAAC,iBAAiB;CAK1B"}
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/policy/evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAqB,cAAc,EAAE,MAAM,SAAS,CAAC;AAMhF;;;;;;GAMG;AACH,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,cAAc;IAEnD;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CACV,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,EAAE,cAAc,EAAE,EAC3B,GAAG,GAAE,IAAiB,GACrB,kBAAkB;IAsBrB,OAAO,CAAC,WAAW;IA0CnB,OAAO,CAAC,iBAAiB;CAK1B"}

package/dist/policy/types.d.ts

@@ -29,11 +29,46 @@ export interface PolicyDocument {
     version: 1;
     rotation?: PolicyRotationConfig;
 }
+/**
+ * Per-key rotation verdict inside a {@link FileRotationStatus}.  Each entry
+ * corresponds to one plaintext key present in the encrypted file.
+ *
+ * The authoritative signal is `last_rotated_at` from `.clef-meta.yaml`
+ * (recorded by `clef set` / `clef import` when a value actually changes).
+ * When no record exists, `last_rotated_known: false` and `compliant: false` —
+ * unknown rotation state is treated as a policy violation by design.
+ */
+export interface KeyRotationStatus {
+    /** Key name as it appears in the cipher (plaintext). */
+    key: string;
+    /** ISO 8601 of the last recorded rotation, or `null` when unknown. */
+    last_rotated_at: string | null;
+    /** Whether `.clef-meta.yaml` had a rotation record for this key. */
+    last_rotated_known: boolean;
+    /** Git identity that performed the last rotation, or `null` when unknown. */
+    rotated_by: string | null;
+    /** Monotonically increasing counter across rotations, or `0` when unknown. */
+    rotation_count: number;
+    /** `last_rotated_at + max_age_days`.  `null` when `last_rotated_known: false`. */
+    rotation_due: string | null;
+    /** `true` iff the rotation is known and past due. */
+    rotation_overdue: boolean;
+    /** `0` when not overdue or unknown. */
+    days_overdue: number;
+    /** `true` iff `last_rotated_known && !rotation_overdue`. */
+    compliant: boolean;
+}
 /**
  * Result of evaluating a single encrypted file against a {@link PolicyDocument}.
  *
  * Field names are part of the public compliance artifact contract — see the
  * notice at the top of this file.
+ *
+ * The policy gate is driven by per-key rotation state (`keys[*].compliant`).
+ * `compliant` on this struct is the AND of the per-key verdicts.  File-level
+ * rotation fields are intentionally absent — `sops.lastmodified` is a file
+ * freshness signal, not a value-rotation signal, and the two answer different
+ * questions (see the rotation policy docs for rationale).
  */
 export interface FileRotationStatus {
     /** Repo-relative or absolute path the evaluator was given. */
@@ -46,17 +81,13 @@ export interface FileRotationStatus {
     last_modified: string;
     /**
      * Whether the underlying SOPS file actually carried a `lastmodified` field.
-     * `false` means `last_modified` is a synthetic fallback and the rotation
-     * verdict should be treated with suspicion (tooling should surface this
-     * distinctly from a normal "compliant" verdict).
+     * `false` means `last_modified` is a synthetic fallback.  Kept as a raw
+     * signal for audit consumers; does not gate policy.
      */
     last_modified_known: boolean;
-    /** ISO 8601. Computed as `last_modified + max_age_days`. */
-    rotation_due: string;
-    rotation_overdue: boolean;
-    /** `0` when not overdue. */
-    days_overdue: number;
-    /** `false` if `rotation_overdue`; `true` otherwise. */
+    /** Per-key rotation verdicts.  Empty array only for cells that have no keys. */
+    keys: KeyRotationStatus[];
+    /** AND of `keys[*].compliant`.  `true` only when every key is compliant. */
     compliant: boolean;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/policy/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,6EAA6E;AAC7E,MAAM,WAAW,yBAAyB;IACxC,mFAAmF;IACnF,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;CAC1D;AAED,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,+EAA+E;IAC/E,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,mBAAmB,EAAE,OAAO,CAAC;IAC7B,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,4BAA4B;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,cAGT,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/policy/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,6EAA6E;AAC7E,MAAM,WAAW,yBAAyB;IACxC,mFAAmF;IACnF,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;CAC1D;AAED,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,oEAAoE;IACpE,kBAAkB,EAAE,OAAO,CAAC;IAC5B,6EAA6E;IAC7E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,8EAA8E;IAC9E,cAAc,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qDAAqD;IACrD,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,+EAA+E;IAC/E,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,mBAAmB,EAAE,OAAO,CAAC;IAC7B,gFAAgF;IAChF,IAAI,EAAE,iBAAiB,EAAE,CAAC;IAC1B,4EAA4E;IAC5E,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,cAGT,CAAC"}

package/dist/scanner/index.d.ts

@@ -2,7 +2,7 @@ import type { ClefManifest, SubprocessRunner } from "../types";
 import { ScanMatch } from "./patterns";
 export type { ScanMatch } from "./patterns";
 export type { ClefIgnoreRules } from "./ignore";
-export { shannonEntropy, isHighEntropy, matchPatterns, redactValue } from "./patterns";
+export { shannonEntropy, isHighEntropy, matchPatterns, matchPublicPrefix, redactValue, } from "./patterns";
 export { loadIgnoreRules, shouldIgnoreFile, shouldIgnoreMatch, parseIgnoreContent } from "./ignore";
 export interface ScanResult {
     matches: ScanMatch[];
@@ -15,6 +15,14 @@ export interface ScanOptions {
     stagedOnly?: boolean;
     paths?: string[];
     severity?: "all" | "high";
+    /**
+     * When `true` (default) the entropy detector skips values that match known
+     * public-by-design credential shapes — reCAPTCHA site keys, Stripe
+     * publishable keys, etc.  Set to `false` (via `--no-public-allowlist`) to
+     * report every high-entropy value regardless of shape.  Pattern matches
+     * are unaffected — a leaked AWS/Stripe secret key is still flagged.
+     */
+    publicAllowlist?: boolean;
 }
 /**
  * Scans repository files for plaintext secrets using pattern matching and entropy detection.

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scanner/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,EAA6D,SAAS,EAAE,MAAM,YAAY,CAAC;AAGlG,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEpG,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CAC3B;AAUD;;;;;;;;GAQG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,gBAAgB;IAErD;;;;;;;;OAQG;IACG,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC;IA8GtB,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,QAAQ;IAehB,OAAO,CAAC,aAAa;YA4BP,cAAc;YAUd,eAAe;YAef,kBAAkB;IAShC,OAAO,CAAC,OAAO;CAqBhB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scanner/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,EAML,SAAS,EACV,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EACL,cAAc,EACd,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEpG,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAUD;;;;;;;;GAQG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,gBAAgB;IAErD;;;;;;;;OAQG;IACG,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC;IA+GtB,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,QAAQ;IAehB,OAAO,CAAC,aAAa;YAkCP,cAAc;YAUd,eAAe;YAef,kBAAkB;IAShC,OAAO,CAAC,OAAO;CAqBhB"}

package/dist/scanner/patterns.d.ts

@@ -19,6 +19,18 @@ export interface ScanMatch {
     entropy?: number;
     preview: string;
 }
+/**
+ * Returns a matching public-prefix definition if the value is a known
+ * client-facing credential shape (reCAPTCHA site key, Stripe publishable
+ * key, etc.).  `null` when the value is not recognized as public.
+ *
+ * Used by the entropy detector to avoid false positives on strings that are
+ * public by design.  The check is intentionally conservative — patterns are
+ * anchored (`^...$`) so partial matches do not qualify.
+ */
+export declare function matchPublicPrefix(value: string): {
+    name: string;
+} | null;
 /**
  * Calculate Shannon entropy (bits per character) of a string.
  */

package/dist/scanner/patterns.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../src/scanner/patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AA0BD;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYlD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,SAAM,EAAE,SAAS,SAAK,GAAG,OAAO,CAErF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,CAgB7F"}
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../src/scanner/patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AA4CD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKxE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYlD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,SAAM,EAAE,SAAS,SAAK,GAAG,OAAO,CAErF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,CAgB7F"}

package/dist/sops/client.d.ts

@@ -14,6 +14,7 @@ export declare class SopsClient implements EncryptionBackend {
     private readonly ageKeyFile?;
     private readonly ageKey?;
     private readonly sopsCommand;
+    private readonly keyserviceArgs;
     /**
      * @param runner - Subprocess runner used to invoke the `sops` binary.
      * @param ageKeyFile - Optional path to an age private key file. Passed as
@@ -22,8 +23,17 @@ export declare class SopsClient implements EncryptionBackend {
      *   to the subprocess environment.
      * @param sopsPath - Optional explicit path to the sops binary. When omitted,
      *   resolved automatically via {@link resolveSopsPath}.
+     * @param keyserviceAddr - Optional address of an external SOPS KeyService
+     *   sidecar (e.g. `tcp://127.0.0.1:12345`). When set, every SOPS invocation
+     *   includes `--enable-local-keyservice=false --keyservice <addr>` so KMS
+     *   wrap/unwrap is routed to the sidecar (used for the HSM backend, where
+     *   the sidecar is `clef-keyservice` talking PKCS#11 to the HSM).
+     *
+     *   The flags are inserted **after** the SOPS subcommand — placing them
+     *   before is silently ignored by SOPS (a footgun discovered the first
+     *   time we shipped this).
      */
-    constructor(runner: SubprocessRunner, ageKeyFile?: string | undefined, ageKey?: string | undefined, sopsPath?: string);
+    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.

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;AAyClB;;;;;;;;;GASG;AACH,qBAAa,UAAW,YAAW,iBAAiB;IAahD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAd1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC;;;;;;;;OAQG;gBAEgB,MAAM,EAAE,gBAAgB,EACxB,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,MAAM,CAAC,EAAE,MAAM,YAAA,EAChC,QAAQ,CAAC,EAAE,MAAM;IAKnB,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;IAsEhB;;;;;;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;IAWrB,OAAO,CAAC,iBAAiB;IAgCzB,OAAO,CAAC,gBAAgB;CAqDzB"}
+{"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"}

package/dist/sops/hsm-arn.d.ts

@@ -0,0 +1,51 @@
+/**
+ * TIER 1 MODULE — Security and correctness critical.
+ *
+ * Wraps and unwraps PKCS#11 URIs as synthetic AWS KMS ARNs so they pass
+ * through SOPS's `--kms` validation regex. Every encrypted file with
+ * backend `hsm` stores its key identifier as a Clef-shaped ARN; the
+ * clef-keyservice side decodes it back to a pkcs11 URI before handing
+ * the DEK wrap/unwrap to the HSM.
+ *
+ * Contract v1 — frozen with the clef-keyservice team:
+ *
+ *   arn:aws:kms:us-east-1:000000000000:alias/clef-hsm/v1/<BASE64URL(pkcs11-uri)>
+ *
+ * - Region / account are placeholders. SOPS never dials AWS because
+ *   `--enable-local-keyservice=false` routes every KMS op to the
+ *   keyservice sidecar.
+ * - Payload is RFC 4648 §5 base64url, no padding. Alphabet is
+ *   `[A-Za-z0-9_-]`, which is why the regex below ends with `+$`
+ *   over that exact class.
+ * - Version marker lets us evolve the encoding if RFC 7512 extensions
+ *   push us to a different format — bump to `v2` on both sides.
+ *
+ * Coverage threshold: 95% lines/functions, 90% branches.
+ */
+/**
+ * Wrap a pkcs11 URI in a Clef HSM synthetic ARN.
+ *
+ * @param uri - A pkcs11 URI (e.g. `pkcs11:slot=0;label=clef-dek-wrapper`).
+ * @returns An ARN that passes SOPS's `--kms` regex and carries the URI as payload.
+ * @throws If `uri` does not start with `pkcs11:`.
+ */
+export declare function pkcs11UriToSyntheticArn(uri: string): string;
+/**
+ * Decode a Clef HSM synthetic ARN back to its pkcs11 URI.
+ *
+ * @param arn - A string that may or may not be a Clef HSM ARN.
+ * @returns The pkcs11 URI if `arn` matches the contract; `null` otherwise.
+ *   Returning `null` (rather than throwing) lets callers branch cleanly
+ *   between "this is a Clef HSM ARN" and "this is some other KMS ARN".
+ *   Callers that require a valid decode should throw themselves.
+ */
+export declare function syntheticArnToPkcs11Uri(arn: string): string | null;
+/**
+ * Check whether a string is a Clef HSM synthetic ARN (regardless of
+ * whether its payload decodes cleanly).
+ *
+ * Used by {@link SopsClient.detectBackend} to classify entries in
+ * `sops.kms[]` as `hsm` rather than `awskms`.
+ */
+export declare function isClefHsmArn(arn: string): boolean;
+//# sourceMappingURL=hsm-arn.d.ts.map

package/dist/sops/hsm-arn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hsm-arn.d.ts","sourceRoot":"","sources":["../../src/sops/hsm-arn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAWH;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAY3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAalE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjD"}