@terreno/api 0.19.0 → 0.20.1

package/src/configurationPlugin.test.ts

@@ -2,7 +2,8 @@
 import {afterAll, beforeAll, beforeEach, describe, expect, it} from "bun:test";
 import mongoose, {model, Schema} from "mongoose";
 import type {SecretProvider} from "./configurationPlugin";
-import {configurationPlugin} from "./configurationPlugin";
+import {configurationPlugin, flattenToDotPaths} from "./configurationPlugin";
+import {isDeletedPlugin} from "./plugins";
 
 // --- Test schema with secret fields ---
 
@@ -65,13 +66,52 @@ const simpleSchema = new Schema({
 simpleSchema.plugin(configurationPlugin);
 const SimpleConfigModel = model("SimpleConfiguration", simpleSchema) as any;
 
+// --- Schema opting into the _singleton unique index ---
+
+const indexedSchema = new Schema({
+  value: {default: "default", description: "A value", type: String},
+});
+indexedSchema.plugin(configurationPlugin, {enforceSingletonIndex: true});
+const IndexedConfigModel = model("IndexedConfiguration", indexedSchema) as any;
+
+// --- Soft-delete-aware schema ---
+
+const softDeleteSchema = new Schema({
+  value: {default: "default", description: "A value", type: String},
+});
+softDeleteSchema.plugin(configurationPlugin);
+softDeleteSchema.plugin(isDeletedPlugin);
+const SoftDeleteConfigModel = model("SoftDeleteConfiguration", softDeleteSchema) as any;
+
+// --- Schema with a validated field (enum) for runValidators coverage ---
+
+const validatedSchema = new Schema({
+  level: {
+    default: "low",
+    description: "Severity level",
+    enum: ["low", "medium", "high"],
+    type: String,
+  },
+});
+validatedSchema.plugin(configurationPlugin);
+const ValidatedConfigModel = model("ValidatedConfiguration", validatedSchema) as any;
+
 describe("configurationPlugin", () => {
   describe("schema setup", () => {
-    it("adds a _singleton field with unique index", () => {
+    it("does not add a _singleton index by default", () => {
       const indexes = SimpleConfigModel.schema.indexes();
       const singletonIndex = indexes.find(
         ([fields]: [Record<string, any>]) => fields._singleton !== undefined
       );
+      expect(singletonIndex).toBeUndefined();
+      expect(SimpleConfigModel.schema.path("_singleton")).toBeUndefined();
+    });
+
+    it("adds a _singleton field with unique index when enforceSingletonIndex is true", () => {
+      const indexes = IndexedConfigModel.schema.indexes();
+      const singletonIndex = indexes.find(
+        ([fields]: [Record<string, any>]) => fields._singleton !== undefined
+      );
       expect(singletonIndex).toBeDefined();
       expect(singletonIndex[1].unique).toBe(true);
     });
@@ -168,6 +208,50 @@ describe("configurationPlugin", () => {
       expect(resolved.size).toBe(1);
       expect(resolved.get("apiKey")).toBe("resolved-key");
     });
+
+    it("passes the discovered secret version to the provider", async () => {
+      const versionedSchema = new Schema({
+        token: {
+          default: "",
+          description: "Pinned secret",
+          secret: true,
+          secretName: "pinned-token",
+          secretVersion: "5",
+          type: String,
+        },
+      });
+      versionedSchema.plugin(configurationPlugin);
+      const VersionedModel = model("VersionedConfiguration", versionedSchema) as any;
+
+      const received: Array<{name: string; version?: string}> = [];
+      const provider: SecretProvider = {
+        getSecret: async (name: string, version?: string) => {
+          received.push({name, version});
+          return "value";
+        },
+        name: "versioned-provider",
+      };
+
+      await VersionedModel.resolveSecrets(provider);
+      expect(received).toEqual([{name: "pinned-token", version: "5"}]);
+    });
+  });
+
+  describe("flattenToDotPaths", () => {
+    it("flattens nested plain objects into dotted paths", () => {
+      expect(flattenToDotPaths({a: {b: 1}})).toEqual([["a.b", 1]]);
+    });
+
+    it("treats arrays as leaves", () => {
+      expect(flattenToDotPaths({a: [1, 2]})).toEqual([["a", [1, 2]]]);
+    });
+
+    it("treats null as a leaf and keeps top-level keys", () => {
+      expect(flattenToDotPaths({a: null, b: "x"})).toEqual([
+        ["a", null],
+        ["b", "x"],
+      ]);
+    });
   });
 
   describe("singleton behavior (requires MongoDB)", () => {
@@ -258,6 +342,22 @@ describe("configurationPlugin", () => {
       expect(config.value).toBe("custom");
     });
 
+    it("runs schema validators on updateConfig (rejects invalid enum)", async () => {
+      if (!dbConnected) {
+        return;
+      }
+      try {
+        await ValidatedConfigModel.collection.drop();
+      } catch {
+        // Collection may not exist yet
+      }
+      await ValidatedConfigModel.getConfig();
+      await expect(ValidatedConfigModel.updateConfig({level: "bogus"})).rejects.toThrow();
+      // A valid value still applies.
+      const ok = await ValidatedConfigModel.updateConfig({level: "high"});
+      expect(ok.level).toBe("high");
+    });
+
     it("prevents deleteOne", async () => {
       if (!dbConnected) {
         return;
@@ -297,4 +397,76 @@ describe("configurationPlugin", () => {
       }
     });
   });
+
+  describe("soft-delete-aware singleton (requires MongoDB)", () => {
+    let dbConnected = false;
+
+    beforeAll(async () => {
+      try {
+        if (mongoose.connection.readyState === 1) {
+          dbConnected = true;
+        } else {
+          await mongoose.connect("mongodb://127.0.0.1/terreno-config-test", {
+            connectTimeoutMS: 3000,
+            serverSelectionTimeoutMS: 3000,
+          });
+          dbConnected = true;
+        }
+      } catch {
+        dbConnected = false;
+      }
+    });
+
+    beforeEach(async () => {
+      if (!dbConnected) {
+        return;
+      }
+      try {
+        await SoftDeleteConfigModel.collection.drop();
+      } catch {
+        // Collection may not exist yet
+      }
+    });
+
+    it("operates on the non-deleted singleton", async () => {
+      if (!dbConnected) {
+        return;
+      }
+      const config = await SoftDeleteConfigModel.getConfig();
+      expect(config.value).toBe("default");
+      const updated = await SoftDeleteConfigModel.updateConfig({value: "live"});
+      expect(updated.value).toBe("live");
+      expect(updated.deleted).toBe(false);
+    });
+
+    it("allows a new singleton after the existing one is soft-deleted", async () => {
+      if (!dbConnected) {
+        return;
+      }
+      const first = await SoftDeleteConfigModel.getConfig();
+      // Soft delete by setting deleted: true (allowed)
+      first.deleted = true;
+      await first.save();
+
+      // A new non-deleted singleton can now be created
+      const second = await SoftDeleteConfigModel.getConfig();
+      expect(second.deleted).toBe(false);
+      expect(second._id.toString()).not.toBe(first._id.toString());
+    });
+
+    it("does not let updateConfig touch a soft-deleted document", async () => {
+      if (!dbConnected) {
+        return;
+      }
+      const first = await SoftDeleteConfigModel.getConfig();
+      first.deleted = true;
+      await first.save();
+
+      // updateConfig creates and targets a fresh non-deleted singleton
+      const updated = await SoftDeleteConfigModel.updateConfig({value: "fresh"});
+      expect(updated.deleted).toBe(false);
+      expect(updated.value).toBe("fresh");
+      expect(updated._id.toString()).not.toBe(first._id.toString());
+    });
+  });
 });

package/src/configurationPlugin.ts

@@ -11,6 +11,12 @@ export interface SecretFieldMeta {
   path: string;
   secretProvider?: string;
   secretName: string;
+  /**
+   * Optional secret version to pin resolution to. When omitted the provider
+   * resolves the latest version. Discovered from the `secretVersion` schema
+   * path option.
+   */
+  version?: string;
 }
 
 /**
@@ -18,7 +24,15 @@ export interface SecretFieldMeta {
  */
 export interface SecretProvider {
   name: string;
-  getSecret(secretName: string): Promise<string | null>;
+  /**
+   * Resolve a secret value by name. Returns `null` when the secret is not found.
+   *
+   * @param secretName - The secret identifier (short name or provider-specific path).
+   * @param version - Optional version to pin resolution to. Providers that do not
+   *   support versioning (e.g. environment variables) ignore this parameter. When
+   *   omitted, the latest version is resolved.
+   */
+  getSecret(secretName: string, version?: string): Promise<string | null>;
 }
 
 /**
@@ -30,6 +44,18 @@ export interface ConfigurationPluginOptions {
    * Typically set during app startup so the model can resolve secrets on demand.
    */
   secretProvider?: SecretProvider;
+  /**
+   * When `true`, adds a `_singleton` sentinel field with a unique index to
+   * enforce the singleton constraint at the database level.
+   *
+   * Defaults to `false`. Leave this off when the consuming app already enforces
+   * a single non-deleted document via the pre-save guard (the default behavior)
+   * or via its own indexes/soft-delete plugin, to avoid double-enforcement and
+   * conflicting indexes.
+   *
+   * @defaultValue false
+   */
+  enforceSingletonIndex?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -75,14 +101,26 @@ export interface ConfigurationStatics<T extends object> {
   getConfig(): Promise<T & Document>;
   /** Get a specific value by dot-notation key. */
   getConfig<P extends Paths<T>>(key: P): Promise<PathValue<T, P>>;
-  /** Update the singleton configuration document (deep merge). */
+  /**
+   * Update the singleton configuration document.
+   *
+   * The patch is flattened into MongoDB dotted paths and applied with
+   * `findOneAndUpdate({$set})`. This preserves sibling fields inside nested
+   * subdocuments when a partial nested patch is supplied, and tolerates legacy /
+   * out-of-schema fields already persisted on the document (unlike a full
+   * `doc.save()`, which throws under `strict: "throw"`).
+   */
   updateConfig(updates: DeepPartial<T>): Promise<T & Document>;
   /** Get secret field metadata discovered from the schema. */
   getSecretFields(): SecretFieldMeta[];
   /**
    * Resolve all secret field values from a provider.
    * Uses the provider passed here, or falls back to the one configured in the plugin options.
-   * Returns a map of path -> value.
+   * Returns an **in-memory** map of path -> value for programmatic use (startup
+   * self-checks, request-time resolution).
+   *
+   * This method never persists resolved values. Secret material must never be
+   * written to the configuration document.
    */
   resolveSecrets(provider?: SecretProvider): Promise<Map<string, string>>;
 }
@@ -103,6 +141,47 @@ export interface ConfigurationStatics<T extends object> {
  */
 export interface ConfigurationModel<T extends object> extends Model<T>, ConfigurationStatics<T> {}
 
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Flattens a nested patch into MongoDB-style dotted paths, recursing into plain
+ * objects only; arrays and other values are treated as leaves.
+ *
+ * @example
+ * flattenToDotPaths({a: {b: 1}}) // => [["a.b", 1]]
+ */
+export const flattenToDotPaths = (
+  obj: Record<string, unknown>,
+  prefix = ""
+): Array<[string, unknown]> => {
+  const out: Array<[string, unknown]> = [];
+  for (const [key, value] of Object.entries(obj)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    const isPlainObject =
+      value !== null &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      Object.getPrototypeOf(value) === Object.prototype;
+    if (isPlainObject) {
+      out.push(...flattenToDotPaths(value as Record<string, unknown>, path));
+    } else {
+      out.push([path, value]);
+    }
+  }
+  return out;
+};
+
+/**
+ * Builds the filter used to locate the singleton document. When the schema is
+ * soft-delete aware (has a `deleted` path, e.g. via `isDeletedPlugin`), the
+ * singleton is "the one non-deleted document"; otherwise any document matches.
+ */
+const buildSingletonFilter = (schema: Schema): Record<string, unknown> => {
+  return schema.path("deleted") ? {deleted: false} : {};
+};
+
 // ---------------------------------------------------------------------------
 // Plugin
 // ---------------------------------------------------------------------------
@@ -111,13 +190,23 @@ export interface ConfigurationModel<T extends object> extends Model<T>, Configur
  * Mongoose schema plugin that adds singleton configuration behavior.
  *
  * Adds:
- * - Pre-save hook enforcing exactly one document
+ * - Pre-save hook enforcing exactly one non-deleted document (soft-delete aware
+ *   when the schema has a `deleted` path, e.g. via `isDeletedPlugin`)
  * - `getConfig()` static: fetches or creates the singleton (full doc or keyed value)
- * - `updateConfig(updates)` static: patches the singleton
+ * - `updateConfig(updates)` static: patches the singleton via `findOneAndUpdate({$set})`
+ *   with dotted paths (preserves sibling subdoc fields; tolerates legacy fields)
  * - `getSecretFields()` static: returns metadata for fields with `secret: true`
- * - `resolveSecrets(provider?)` static: fetches secret values, using the plugin provider by default
+ * - `resolveSecrets(provider?)` static: resolves secret values into an in-memory map,
+ *   using the plugin provider by default (never persists values)
+ * - Hard-delete blockers (`deleteOne`/`deleteMany`/`findOneAndDelete`); soft deletes
+ *   (setting `deleted: true`) are allowed
+ *
+ * Soft deletes are allowed and a soft-deleted document does not block creating a
+ * new singleton. The `_singleton` unique index is opt-in via
+ * `enforceSingletonIndex` (default off).
  *
- * Mark fields as secrets using schema path options:
+ * Mark fields as secrets using schema path options. Pin a version with the
+ * optional `secretVersion` option:
  * ```typescript
  * const configSchema = new Schema({
  *   apiKey: {
@@ -125,6 +214,7 @@ export interface ConfigurationModel<T extends object> extends Model<T>, Configur
  *     description: "Third-party API key",
  *     secret: true,
  *     secretName: "my-api-key",
+ *     secretVersion: "3", // optional — resolves "latest" when omitted
  *   },
  * });
  * configSchema.plugin(configurationPlugin, {secretProvider: new EnvSecretProvider()});
@@ -136,24 +226,31 @@ export const configurationPlugin = (schema: Schema, options?: ConfigurationPlugi
   // Apply findOneOrNone so the singleton lookup avoids bare Model.findOne (idempotent).
   findOneOrNone(schema);
 
-  // Add a sentinel field with a unique index to enforce singleton at the DB level.
-  // All config documents get _singleton: "config", and the unique index prevents duplicates.
-  schema.add({
-    _singleton: {
-      default: "config",
-      description: "Sentinel field enforcing singleton constraint",
-      immutable: true,
-      select: false,
-      type: String,
-    },
-  });
-  schema.index({_singleton: 1}, {unique: true});
+  // Optionally add a sentinel field with a unique index to enforce the singleton
+  // at the database level. This is opt-in (default off) so it does not conflict
+  // with consumers that already enforce a single non-deleted document via the
+  // pre-save guard below or via their own soft-delete plugin/indexes.
+  if (pluginOptions.enforceSingletonIndex) {
+    schema.add({
+      _singleton: {
+        default: "config",
+        description: "Sentinel field enforcing singleton constraint",
+        immutable: true,
+        select: false,
+        type: String,
+      },
+    });
+    schema.index({_singleton: 1}, {unique: true});
+  }
 
-  // Enforce singleton: only one document allowed (application-level guard)
+  // Enforce singleton: only one non-deleted document allowed (application-level
+  // guard). Soft-delete-aware: a soft-deleted document does not block creating a
+  // new singleton.
   schema.pre("save", async function () {
     if (this.isNew) {
+      const filter = buildSingletonFilter(schema);
       // Cheap existence check — no document needs to be returned.
-      const existing = await (this.constructor as Model<unknown>).exists({});
+      const existing = await (this.constructor as Model<unknown>).exists(filter);
       if (existing) {
         throw new APIError({
           status: 409,
@@ -183,9 +280,10 @@ export const configurationPlugin = (schema: Schema, options?: ConfigurationPlugi
 
   // Static: get the singleton configuration document or a value at a path (race-safe via upsert)
   schema.statics.getConfig = async function (key?: string): Promise<unknown> {
+    const singletonFilter = buildSingletonFilter(this.schema);
     const findSingleton = (): Promise<Document | null> =>
       (this as unknown as FindOneOrNonePlugin<unknown>).findOneOrNone(
-        {}
+        singletonFilter
       ) as Promise<Document | null>;
     let config: Document | null = await findSingleton();
     if (!config) {
@@ -222,14 +320,44 @@ export const configurationPlugin = (schema: Schema, options?: ConfigurationPlugi
     return value;
   };
 
-  // Static: update the singleton configuration document (race-safe)
+  // Static: update the singleton configuration document via $set dotted paths.
+  // Flattening to dotted paths preserves sibling subdoc fields and tolerates
+  // legacy/out-of-schema fields already persisted on the document.
   schema.statics.updateConfig = async function (
     updates: Record<string, unknown>
   ): Promise<unknown> {
-    const config = await (this as ConfigurationModel<Record<string, unknown>>).getConfig();
-    Object.assign(config, updates);
-    await (config as Document).save();
-    return config;
+    const singletonFilter = buildSingletonFilter(this.schema);
+    const setFields: Record<string, unknown> = {};
+    for (const [path, value] of flattenToDotPaths(updates)) {
+      setFields[path] = value;
+    }
+
+    // Nothing to set — return the current singleton (creating it if missing).
+    if (Object.keys(setFields).length === 0) {
+      return (this as unknown as ConfigurationModel<Record<string, unknown>>).getConfig();
+    }
+
+    // runValidators keeps schema validation (enum/min/custom validators) on the
+    // patched paths, matching the prior doc.save() behavior. Legacy/out-of-schema
+    // fields already on the document are untouched (not in $set), so they are not
+    // re-validated.
+    const updated = await this.findOneAndUpdate(
+      singletonFilter,
+      {$set: setFields},
+      {new: true, runValidators: true}
+    );
+    if (updated) {
+      return updated;
+    }
+
+    // No singleton yet — create one (with subdocument defaults applied), then
+    // apply the patch.
+    await (this as unknown as ConfigurationModel<Record<string, unknown>>).getConfig();
+    return this.findOneAndUpdate(
+      singletonFilter,
+      {$set: setFields},
+      {new: true, runValidators: true}
+    ).orFail();
   };
 
   // Static: discover secret fields from schema options
@@ -243,6 +371,7 @@ export const configurationPlugin = (schema: Schema, options?: ConfigurationPlugi
             path: prefix ? `${prefix}.${pathName}` : pathName,
             secretName: (opts.secretName as string) ?? pathName,
             secretProvider: opts.secretProvider as string | undefined,
+            version: opts.secretVersion as string | undefined,
           });
         }
         // Recurse into subschemas
@@ -275,7 +404,7 @@ export const configurationPlugin = (schema: Schema, options?: ConfigurationPlugi
 
     const results = await Promise.allSettled(
       secrets.map(async (meta: SecretFieldMeta) => {
-        const value = await resolvedProvider.getSecret(meta.secretName);
+        const value = await resolvedProvider.getSecret(meta.secretName, meta.version);
         if (value !== null) {
           resolved.set(meta.path, value);
         }

package/src/secretProviders.test.ts

@@ -0,0 +1,186 @@
+import {beforeEach, describe, expect, it} from "bun:test";
+
+import type {SecretProvider} from "./configurationPlugin";
+import {CachingSecretProvider, CompositeSecretProvider, EnvSecretProvider} from "./secretProviders";
+
+describe("EnvSecretProvider", () => {
+  beforeEach(() => {
+    delete process.env.MY_SECRET_KEY;
+  });
+
+  it("resolves from a SCREAMING_SNAKE_CASE env var", async () => {
+    process.env.MY_SECRET_KEY = "from-env";
+    const provider = new EnvSecretProvider();
+    expect(await provider.getSecret("my-secret-key")).toBe("from-env");
+  });
+
+  it("returns null when the env var is missing", async () => {
+    const provider = new EnvSecretProvider();
+    expect(await provider.getSecret("my-secret-key")).toBeNull();
+  });
+
+  it("ignores the version parameter", async () => {
+    process.env.MY_SECRET_KEY = "value";
+    const provider = new EnvSecretProvider();
+    expect(await provider.getSecret("my-secret-key", "5")).toBe("value");
+  });
+});
+
+describe("CompositeSecretProvider", () => {
+  it("throws when constructed with no providers", () => {
+    expect(() => new CompositeSecretProvider([])).toThrow();
+  });
+
+  it("returns the first non-null result", async () => {
+    const a: SecretProvider = {getSecret: async () => null, name: "a"};
+    const b: SecretProvider = {getSecret: async () => "from-b", name: "b"};
+    const c: SecretProvider = {getSecret: async () => "from-c", name: "c"};
+    const provider = new CompositeSecretProvider([a, b, c]);
+    expect(await provider.getSecret("x")).toBe("from-b");
+  });
+
+  it("falls through to the next provider when one throws", async () => {
+    const failing: SecretProvider = {
+      getSecret: async () => {
+        throw new Error("provider down");
+      },
+      name: "failing",
+    };
+    const fallback: SecretProvider = {getSecret: async () => "from-fallback", name: "fallback"};
+    const provider = new CompositeSecretProvider([failing, fallback]);
+    expect(await provider.getSecret("x")).toBe("from-fallback");
+  });
+
+  it("returns null when every provider yields null", async () => {
+    const a: SecretProvider = {getSecret: async () => null, name: "a"};
+    const b: SecretProvider = {getSecret: async () => null, name: "b"};
+    const provider = new CompositeSecretProvider([a, b]);
+    expect(await provider.getSecret("x")).toBeNull();
+  });
+
+  it("forwards the version parameter to each provider", async () => {
+    const seen: Array<string | undefined> = [];
+    const a: SecretProvider = {
+      getSecret: async (_name, version) => {
+        seen.push(version);
+        return null;
+      },
+      name: "a",
+    };
+    const b: SecretProvider = {
+      getSecret: async (_name, version) => {
+        seen.push(version);
+        return "value";
+      },
+      name: "b",
+    };
+    const provider = new CompositeSecretProvider([a, b]);
+    await provider.getSecret("x", "7");
+    expect(seen).toEqual(["7", "7"]);
+  });
+
+  it("builds a composite name from the underlying providers", () => {
+    const provider = new CompositeSecretProvider([
+      {getSecret: async () => null, name: "gcp"},
+      {getSecret: async () => null, name: "env"},
+    ]);
+    expect(provider.name).toBe("composite(gcp,env)");
+  });
+});
+
+describe("CachingSecretProvider", () => {
+  it("memoizes a value within the TTL (single underlying call)", async () => {
+    let calls = 0;
+    const underlying: SecretProvider = {
+      getSecret: async () => {
+        calls++;
+        return "value";
+      },
+      name: "underlying",
+    };
+    const provider = new CachingSecretProvider(underlying, {ttlMs: 10_000});
+    expect(await provider.getSecret("x")).toBe("value");
+    expect(await provider.getSecret("x")).toBe("value");
+    expect(calls).toBe(1);
+  });
+
+  it("re-fetches after clear()", async () => {
+    let calls = 0;
+    const underlying: SecretProvider = {
+      getSecret: async () => {
+        calls++;
+        return `value-${calls}`;
+      },
+      name: "underlying",
+    };
+    const provider = new CachingSecretProvider(underlying, {ttlMs: 10_000});
+    expect(await provider.getSecret("x")).toBe("value-1");
+    provider.clear();
+    expect(await provider.getSecret("x")).toBe("value-2");
+    expect(calls).toBe(2);
+  });
+
+  it("re-fetches after the TTL expires", async () => {
+    let calls = 0;
+    const underlying: SecretProvider = {
+      getSecret: async () => {
+        calls++;
+        return `value-${calls}`;
+      },
+      name: "underlying",
+    };
+    const provider = new CachingSecretProvider(underlying, {ttlMs: 1});
+    expect(await provider.getSecret("x")).toBe("value-1");
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(await provider.getSecret("x")).toBe("value-2");
+    expect(calls).toBe(2);
+  });
+
+  it("caches different versions independently", async () => {
+    const seen: Array<string | undefined> = [];
+    const underlying: SecretProvider = {
+      getSecret: async (_name, version) => {
+        seen.push(version);
+        return `v-${version ?? "latest"}`;
+      },
+      name: "underlying",
+    };
+    const provider = new CachingSecretProvider(underlying, {ttlMs: 10_000});
+    expect(await provider.getSecret("x", "1")).toBe("v-1");
+    expect(await provider.getSecret("x", "2")).toBe("v-2");
+    // Cached hits, no additional underlying calls.
+    expect(await provider.getSecret("x", "1")).toBe("v-1");
+    expect(seen).toEqual(["1", "2"]);
+  });
+
+  it("clearKey invalidates a single secret", async () => {
+    let calls = 0;
+    const underlying: SecretProvider = {
+      getSecret: async () => {
+        calls++;
+        return `value-${calls}`;
+      },
+      name: "underlying",
+    };
+    const provider = new CachingSecretProvider(underlying, {ttlMs: 10_000});
+    await provider.getSecret("x");
+    provider.clearKey("x");
+    await provider.getSecret("x");
+    expect(calls).toBe(2);
+  });
+
+  it("caches null results", async () => {
+    let calls = 0;
+    const underlying: SecretProvider = {
+      getSecret: async () => {
+        calls++;
+        return null;
+      },
+      name: "underlying",
+    };
+    const provider = new CachingSecretProvider(underlying, {ttlMs: 10_000});
+    expect(await provider.getSecret("missing")).toBeNull();
+    expect(await provider.getSecret("missing")).toBeNull();
+    expect(calls).toBe(1);
+  });
+});