@cosmicdrift/kumiko-framework 0.1.0

package/src/search/in-memory-adapter.ts

@@ -0,0 +1,123 @@
+import type { EntityId, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { SearchAdapter, SearchAdapterConfig, SearchResult } from "./types";
+
+type StoredDoc = {
+  entityType: string;
+  entityId: EntityId;
+  weight: number;
+  text: Record<string, string>;
+};
+
+type TenantIndex = {
+  config: SearchAdapterConfig;
+  docs: Map<string, StoredDoc>;
+};
+
+function docKey(entityType: string, entityId: EntityId): string {
+  return `${entityType}:${entityId}`;
+}
+
+export function createInMemorySearchAdapter(): SearchAdapter {
+  const tenants = new Map<string, TenantIndex>();
+
+  function getTenant(tenantId: TenantId): TenantIndex {
+    let tenant = tenants.get(tenantId);
+    if (!tenant) {
+      tenant = { config: { searchableFields: [] }, docs: new Map() };
+      tenants.set(tenantId, tenant);
+    }
+    return tenant;
+  }
+
+  return {
+    async configure(tenantId, config) {
+      const tenant = getTenant(tenantId);
+      tenant.config = config;
+    },
+
+    async index(tenantId, doc) {
+      const tenant = getTenant(tenantId);
+      const text: Record<string, string> = {};
+
+      for (const [key, value] of Object.entries(doc.fields)) {
+        if (value !== null && value !== undefined) {
+          text[key] = String(value).toLowerCase();
+        }
+      }
+
+      tenant.docs.set(docKey(doc.entityType, doc.entityId), {
+        entityType: doc.entityType,
+        entityId: doc.entityId,
+        weight: doc.weight,
+        text,
+      });
+    },
+
+    async search(tenantId, query, options) {
+      const tenant = tenants.get(tenantId);
+      if (!tenant) return [];
+
+      const q = query.toLowerCase();
+      const limit = options?.limit ?? 50;
+      const filterType = options?.filterType;
+      const rankingFields = tenant.config.rankingFields ?? tenant.config.searchableFields;
+
+      const scored: Array<{ result: SearchResult; score: number }> = [];
+
+      for (const doc of tenant.docs.values()) {
+        if (filterType && doc.entityType !== filterType) continue;
+
+        let matchScore = 0;
+        const fieldsToSearch =
+          tenant.config.searchableFields.length > 0
+            ? [...tenant.config.searchableFields]
+            : Object.keys(doc.text);
+
+        for (const fieldName of fieldsToSearch) {
+          const value = doc.text[fieldName];
+          if (!value?.includes(q)) continue;
+
+          // Field ranking: earlier in ranking = higher weight
+          const rankIndex = rankingFields.indexOf(fieldName);
+          const fieldWeight = rankIndex >= 0 ? (rankingFields.length - rankIndex) * 100 : 1;
+
+          const exactBonus = value === q ? 50 : 0;
+          const prefixBonus = value.startsWith(q) ? 25 : 0;
+
+          matchScore += fieldWeight + exactBonus + prefixBonus;
+        }
+
+        if (matchScore > 0) {
+          // Entity weight multiplier from searchWeight
+          const totalScore = matchScore * doc.weight;
+          scored.push({
+            result: { entityType: doc.entityType, entityId: doc.entityId },
+            score: totalScore,
+          });
+        }
+      }
+
+      scored.sort((a, b) => b.score - a.score);
+      return scored.slice(0, limit).map((s) => s.result);
+    },
+
+    async remove(tenantId, entityType, entityId) {
+      tenants.get(tenantId)?.docs.delete(docKey(entityType, entityId));
+    },
+
+    async indexBatch(tenantId, docs) {
+      for (const doc of docs) {
+        await this.index(tenantId, doc);
+      }
+    },
+
+    async removeBatch(tenantId, items) {
+      const tenant = tenants.get(tenantId);
+      // skip: tenant has no in-memory index (never configured) — nothing to remove
+      if (!tenant) return;
+      for (const item of items) {
+        tenant.docs.delete(docKey(item.entityType, item.entityId));
+      }
+    },
+  };
+}

package/src/search/index.ts

@@ -0,0 +1,12 @@
+// Meilisearch-Adapter lebt im Sub-Path-Export `@cosmicdrift/kumiko-framework/search/meilisearch`.
+// Damit lädt der Main-Barrel keinen Meilisearch-Client beim bloßen Anfassen
+// von SearchAdapter-Types. Apps die Meilisearch nicht nutzen, ziehen den
+// Client-Code nicht mit rein.
+export { createInMemorySearchAdapter } from "./in-memory-adapter";
+export type {
+  SearchAdapter,
+  SearchAdapterConfig,
+  SearchDocument,
+  SearchOptions,
+  SearchResult,
+} from "./types";

package/src/search/meilisearch-adapter.ts

@@ -0,0 +1,106 @@
+import type { EntityId, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { Meilisearch } from "meilisearch";
+import type { SearchAdapter, SearchResult } from "./types";
+
+export type MeilisearchAdapterOptions = {
+  url: string;
+  apiKey: string;
+  indexPrefix?: string;
+};
+
+function tenantIndex(prefix: string, tenantId: TenantId): string {
+  return `${prefix}t${tenantId}`;
+}
+
+// Meilisearch primary-key-ids: alphanumerics, `-`, `_`. UUIDs contain `-` —
+// legal. Replace anything else just in case callers pass unexpected shapes.
+function docId(entityType: string, entityId: EntityId): string {
+  return `${entityType}_${String(entityId).replace(/[^0-9A-Za-z_-]/g, "_")}`;
+}
+
+export function createMeilisearchAdapter(options: MeilisearchAdapterOptions): SearchAdapter {
+  const client = new Meilisearch({ host: options.url, apiKey: options.apiKey });
+  const prefix = options.indexPrefix ?? "kumiko_";
+
+  return {
+    async configure(tenantId, config) {
+      const index = client.index(tenantIndex(prefix, tenantId));
+      const fields = config.rankingFields ?? config.searchableFields;
+      await index.updateSearchableAttributes([...fields]).waitTask();
+      await index.updateFilterableAttributes(["_type", "_weight"]).waitTask();
+      await index.updateSortableAttributes(["_weight"]).waitTask();
+    },
+
+    async index(tenantId, doc) {
+      const index = client.index(tenantIndex(prefix, tenantId));
+      await index
+        .addDocuments(
+          [
+            {
+              _id: docId(doc.entityType, doc.entityId),
+              _type: doc.entityType,
+              _weight: doc.weight,
+              _entityId: doc.entityId,
+              ...doc.fields,
+            },
+          ],
+          { primaryKey: "_id" },
+        )
+        .waitTask();
+    },
+
+    async indexBatch(tenantId, docs) {
+      // skip: empty batch — avoid an unnecessary Meilisearch round-trip
+      if (docs.length === 0) return;
+      const index = client.index(tenantIndex(prefix, tenantId));
+      const payload = docs.map((doc) => ({
+        _id: docId(doc.entityType, doc.entityId),
+        _type: doc.entityType,
+        _weight: doc.weight,
+        _entityId: doc.entityId,
+        ...doc.fields,
+      }));
+      // Single Meilisearch task covering all N docs. Meilisearch processes
+      // the payload server-side as one indexing job — waitTask blocks until
+      // that job is done, but it's one round-trip instead of N.
+      await index.addDocuments(payload, { primaryKey: "_id" }).waitTask();
+    },
+
+    async removeBatch(tenantId, items) {
+      // skip: empty batch — avoid an unnecessary Meilisearch round-trip
+      if (items.length === 0) return;
+      const index = client.index(tenantIndex(prefix, tenantId));
+      const ids = items.map((i) => docId(i.entityType, i.entityId));
+      await index.deleteDocuments(ids).waitTask();
+    },
+
+    async search(tenantId, query, options) {
+      const index = client.index(tenantIndex(prefix, tenantId));
+
+      const filter: string[] = [];
+      if (options?.filterType) {
+        filter.push(`_type = "${options.filterType}"`);
+      }
+
+      const searchParams: Record<string, unknown> = {
+        limit: options?.limit ?? 50,
+        sort: ["_weight:desc"],
+      };
+      if (filter.length > 0) searchParams["filter"] = filter;
+
+      const results = await index.search(query, searchParams);
+
+      return results.hits.map(
+        (hit: Record<string, unknown>): SearchResult => ({
+          entityType: hit["_type"] as string,
+          entityId: hit["_entityId"] as EntityId,
+        }),
+      );
+    },
+
+    async remove(tenantId, entityType, entityId) {
+      const index = client.index(tenantIndex(prefix, tenantId));
+      await index.deleteDocument(docId(entityType, entityId)).waitTask();
+    },
+  };
+}

package/src/search/types.ts

@@ -0,0 +1,39 @@
+import type { EntityId, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+export type SearchAdapterConfig = {
+  searchableFields: readonly string[];
+  rankingFields?: readonly string[];
+};
+
+export type SearchDocument = {
+  entityType: string;
+  entityId: EntityId;
+  weight: number;
+  fields: Record<string, unknown>;
+};
+
+export type SearchResult = {
+  entityType: string;
+  entityId: EntityId;
+};
+
+export type SearchOptions = {
+  limit?: number;
+  filterType?: string;
+};
+
+export type SearchAdapter = {
+  configure(tenantId: TenantId, config: SearchAdapterConfig): Promise<void>;
+  index(tenantId: TenantId, doc: SearchDocument): Promise<void>;
+  search(tenantId: TenantId, query: string, options?: SearchOptions): Promise<SearchResult[]>;
+  remove(tenantId: TenantId, entityType: string, entityId: EntityId): Promise<void>;
+  // Bulk variants. Default implementations loop over the single-doc methods —
+  // adapters should override when the backend supports a real batch call
+  // (Meilisearch, Elasticsearch, Typesense all do). Cuts a batch-write from
+  // N sequential HTTP + waitTask round-trips to one.
+  indexBatch?(tenantId: TenantId, docs: readonly SearchDocument[]): Promise<void>;
+  removeBatch?(
+    tenantId: TenantId,
+    items: readonly { entityType: string; entityId: EntityId }[],
+  ): Promise<void>;
+};

package/src/secrets/__tests__/dek-cache.test.ts

@@ -0,0 +1,213 @@
+import { randomBytes } from "node:crypto";
+import { describe, expect, test, vi } from "vitest";
+import { createDekCache } from "../dek-cache";
+import type { MasterKeyProvider } from "../types";
+
+// Minimal stub provider — counts unwrap calls so we can observe caching.
+function makeCountingProvider(): MasterKeyProvider & { unwrapCallCount: () => number } {
+  let calls = 0;
+  return {
+    unwrapDek: async (_encryptedDek, _version) => {
+      calls++;
+      return randomBytes(32);
+    },
+    wrapDek: async () => ({ encryptedDek: randomBytes(60), kekVersion: 1 }),
+    currentVersion: () => 1,
+    isAvailable: async () => true,
+    unwrapCallCount: () => calls,
+  };
+}
+
+describe("DekCache", () => {
+  test("second read within TTL is served from cache (no provider call)", async () => {
+    const provider = makeCountingProvider();
+    const cache = createDekCache({ ttlMs: 1000 });
+    const encryptedDek = Buffer.from("some-wrapped-dek-bytes");
+
+    await cache.unwrapDek(encryptedDek, 1, provider);
+    expect(provider.unwrapCallCount()).toBe(1);
+
+    await cache.unwrapDek(encryptedDek, 1, provider);
+    await cache.unwrapDek(encryptedDek, 1, provider);
+    expect(provider.unwrapCallCount()).toBe(1);
+  });
+
+  test("after TTL expiry, provider is called again", async () => {
+    let t = 1_000_000;
+    const provider = makeCountingProvider();
+    const cache = createDekCache({ ttlMs: 1000, now: () => t });
+    const encryptedDek = Buffer.from("wrapped");
+
+    await cache.unwrapDek(encryptedDek, 1, provider);
+    expect(provider.unwrapCallCount()).toBe(1);
+
+    t += 1500; // past TTL
+    await cache.unwrapDek(encryptedDek, 1, provider);
+    expect(provider.unwrapCallCount()).toBe(2);
+  });
+
+  test("different kekVersion entries do not collide", async () => {
+    const provider = makeCountingProvider();
+    const cache = createDekCache({ ttlMs: 60_000 });
+    const encryptedDek = Buffer.from("same-wrapped-payload");
+
+    // Same encryptedDek bytes at two different versions — must be two
+    // distinct cache entries, never confuse one for the other.
+    await cache.unwrapDek(encryptedDek, 1, provider);
+    await cache.unwrapDek(encryptedDek, 2, provider);
+    expect(provider.unwrapCallCount()).toBe(2);
+    expect(cache.size()).toBe(2);
+  });
+
+  test("returned DEK is a defensive copy (caller can zero without affecting cache)", async () => {
+    const provider = makeCountingProvider();
+    const cache = createDekCache({ ttlMs: 60_000 });
+    const encryptedDek = Buffer.from("payload");
+
+    const first = await cache.unwrapDek(encryptedDek, 1, provider);
+    first.fill(0);
+
+    // Second call should still produce a non-zero DEK, served from cache.
+    const second = await cache.unwrapDek(encryptedDek, 1, provider);
+    expect(second.some((b) => b !== 0)).toBe(true);
+    // Only one underlying provider unwrap despite the zeroing.
+    expect(provider.unwrapCallCount()).toBe(1);
+  });
+
+  test("clear() drops all entries and forces next read back through the provider", async () => {
+    const provider = makeCountingProvider();
+    const cache = createDekCache({ ttlMs: 60_000 });
+    const encryptedDek = Buffer.from("payload");
+
+    await cache.unwrapDek(encryptedDek, 1, provider);
+    expect(cache.size()).toBe(1);
+
+    cache.clear();
+    expect(cache.size()).toBe(0);
+
+    await cache.unwrapDek(encryptedDek, 1, provider);
+    expect(provider.unwrapCallCount()).toBe(2);
+  });
+
+  test("clear() zeros the cached DEK bytes before dropping", async () => {
+    const dek = randomBytes(32);
+    const captured = Buffer.from(dek); // original reference for comparison
+    const provider: MasterKeyProvider = {
+      unwrapDek: async () => dek,
+      wrapDek: async () => ({ encryptedDek: randomBytes(60), kekVersion: 1 }),
+      currentVersion: () => 1,
+      isAvailable: async () => true,
+    };
+    const cache = createDekCache({ ttlMs: 60_000 });
+    // Populate via the actual unwrap path so the cache takes its own copy.
+    const dummyReturn = await cache.unwrapDek(Buffer.from("x"), 1, provider);
+    // The defensive copy means dek the provider returned is distinct from
+    // what the cache stored; we spy on the cache side via vi.
+    void dummyReturn;
+    void captured;
+    cache.clear();
+    // Post-clear we can't easily inspect the zeroed internal buffer from
+    // outside — but size() going to 0 plus the no-throw behaviour confirms
+    // the code path runs. The real security property (no stale bytes in
+    // heap snapshots) can only be observed with a debugger.
+    expect(cache.size()).toBe(0);
+  });
+
+  test("expired entry is pruned on next miss to bound memory", async () => {
+    let t = 1_000_000;
+    const provider = makeCountingProvider();
+    const cache = createDekCache({ ttlMs: 100, now: () => t });
+
+    await cache.unwrapDek(Buffer.from("a"), 1, provider);
+    expect(cache.size()).toBe(1);
+
+    t += 200; // past TTL
+    await cache.unwrapDek(Buffer.from("a"), 1, provider);
+    // Still size 1, but it's the fresh entry — not a leak of the expired one.
+    expect(cache.size()).toBe(1);
+  });
+
+  test("concurrent same-key calls both go through to provider in v1 (no request coalescing)", async () => {
+    // Documenting current behaviour: we don't dedupe in-flight unwraps.
+    // Two simultaneous reads of the same encryptedDek will each hit the
+    // provider. Fine for v1 — real-world collision risk is low and the
+    // cost is "one extra provider call" per burst. v2 could add a
+    // promise-cache to coalesce.
+    const provider = makeCountingProvider();
+    const cache = createDekCache({ ttlMs: 60_000 });
+    const ed = Buffer.from("concurrent");
+    await Promise.all([cache.unwrapDek(ed, 1, provider), cache.unwrapDek(ed, 1, provider)]);
+    expect(provider.unwrapCallCount()).toBe(2);
+  });
+
+  test("defaults TTL is 5 minutes when not overridden", async () => {
+    // Sanity on the documented default — a regression where someone tweaks
+    // DEFAULT_TTL_MS would silently change the security posture.
+    const provider = makeCountingProvider();
+    let t = 0;
+    const cache = createDekCache({ now: () => t });
+    await cache.unwrapDek(Buffer.from("x"), 1, provider);
+    t = 4 * 60 * 1000; // 4 min in
+    await cache.unwrapDek(Buffer.from("x"), 1, provider);
+    expect(provider.unwrapCallCount()).toBe(1);
+    t = 5 * 60 * 1000 + 1; // just past 5 min
+    await cache.unwrapDek(Buffer.from("x"), 1, provider);
+    expect(provider.unwrapCallCount()).toBe(2);
+    // avoid vitest unused-import warning
+    void vi;
+  });
+
+  test("LRU: evicts oldest when maxEntries is reached", async () => {
+    const provider = makeCountingProvider();
+    const cache = createDekCache({ maxEntries: 3, ttlMs: 60_000 });
+    // Fill the cache.
+    await cache.unwrapDek(Buffer.from("A"), 1, provider);
+    await cache.unwrapDek(Buffer.from("B"), 1, provider);
+    await cache.unwrapDek(Buffer.from("C"), 1, provider);
+    expect(cache.size()).toBe(3);
+    expect(provider.unwrapCallCount()).toBe(3);
+
+    // Insert a fourth — A (oldest) must be evicted. Size stays at cap.
+    await cache.unwrapDek(Buffer.from("D"), 1, provider);
+    expect(cache.size()).toBe(3);
+    expect(provider.unwrapCallCount()).toBe(4);
+
+    // Re-request A — cache miss because it was evicted, provider is called.
+    await cache.unwrapDek(Buffer.from("A"), 1, provider);
+    expect(provider.unwrapCallCount()).toBe(5);
+
+    // Re-request D — cache hit, no new provider call.
+    await cache.unwrapDek(Buffer.from("D"), 1, provider);
+    expect(provider.unwrapCallCount()).toBe(5);
+  });
+
+  test("LRU: touching an entry moves it to the 'most recent' end", async () => {
+    const provider = makeCountingProvider();
+    const cache = createDekCache({ maxEntries: 3, ttlMs: 60_000 });
+    await cache.unwrapDek(Buffer.from("A"), 1, provider);
+    await cache.unwrapDek(Buffer.from("B"), 1, provider);
+    await cache.unwrapDek(Buffer.from("C"), 1, provider);
+    // Touch A — now B is the oldest.
+    await cache.unwrapDek(Buffer.from("A"), 1, provider);
+    expect(provider.unwrapCallCount()).toBe(3); // A was a cache hit
+
+    // Insert D — evicts B (oldest after the touch), not A.
+    await cache.unwrapDek(Buffer.from("D"), 1, provider);
+    // A still cached
+    await cache.unwrapDek(Buffer.from("A"), 1, provider);
+    expect(provider.unwrapCallCount()).toBe(4);
+    // B was evicted
+    await cache.unwrapDek(Buffer.from("B"), 1, provider);
+    expect(provider.unwrapCallCount()).toBe(5);
+  });
+
+  test("default maxEntries is 1000 so burst-cost is bounded", async () => {
+    const provider = makeCountingProvider();
+    const cache = createDekCache();
+    // Insert 1001 unique entries — size must cap at 1000.
+    for (let i = 0; i < 1001; i++) {
+      await cache.unwrapDek(Buffer.from(`key-${i}`), 1, provider);
+    }
+    expect(cache.size()).toBe(1000);
+  });
+});

package/src/secrets/__tests__/env-master-key-provider.test.ts

@@ -0,0 +1,119 @@
+import { randomBytes } from "node:crypto";
+import { describe, expect, test } from "vitest";
+import { createEnvMasterKeyProvider } from "../env-master-key-provider";
+
+function env(vars: Record<string, string>): Record<string, string> {
+  return vars;
+}
+
+describe("EnvMasterKeyProvider — keyring loading", () => {
+  test("accepts a single-version keyring", () => {
+    const key = randomBytes(32).toString("base64");
+    const provider = createEnvMasterKeyProvider({
+      env: env({
+        KUMIKO_SECRETS_MASTER_KEY_V1: key,
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+      }),
+    });
+    expect(provider.currentVersion()).toBe(1);
+  });
+
+  test("accepts multi-version keyring and respects CURRENT_VERSION override", () => {
+    const provider = createEnvMasterKeyProvider({
+      env: env({
+        KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+        KUMIKO_SECRETS_MASTER_KEY_V2: randomBytes(32).toString("base64"),
+        KUMIKO_SECRETS_MASTER_KEY_V3: randomBytes(32).toString("base64"),
+        // Explicit: even though V3 exists, V2 stays active until ops flips this.
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "2",
+      }),
+    });
+    expect(provider.currentVersion()).toBe(2);
+  });
+
+  test("rejects boot when no KEK is set", () => {
+    expect(() =>
+      createEnvMasterKeyProvider({
+        env: env({ KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1" }),
+      }),
+    ).toThrow(/no KEK found/);
+  });
+
+  test("rejects boot when CURRENT_VERSION is missing", () => {
+    expect(() =>
+      createEnvMasterKeyProvider({
+        env: env({ KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64") }),
+      }),
+    ).toThrow(/CURRENT_VERSION not set/);
+  });
+
+  test("rejects boot when CURRENT_VERSION points to an absent KEK", () => {
+    expect(() =>
+      createEnvMasterKeyProvider({
+        env: env({
+          KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+          KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "7",
+        }),
+      }),
+    ).toThrow(/currentVersion=7 not present/);
+  });
+
+  test("rejects KEK with wrong byte length (not AES-256)", () => {
+    expect(() =>
+      createEnvMasterKeyProvider({
+        env: env({
+          // 16 bytes = AES-128 key, not what we want
+          KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(16).toString("base64"),
+          KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+        }),
+      }),
+    ).toThrow(/exactly 32 bytes/);
+  });
+
+  test("rejects non-numeric CURRENT_VERSION", () => {
+    expect(() =>
+      createEnvMasterKeyProvider({
+        env: env({
+          KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+          KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "latest",
+        }),
+      }),
+    ).toThrow(/must be a positive integer/);
+  });
+});
+
+describe("EnvMasterKeyProvider — wrap/unwrap", () => {
+  test("wrap then unwrap round-trips the DEK bytes", async () => {
+    const provider = createEnvMasterKeyProvider({
+      env: env({
+        KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+      }),
+    });
+    const dek = randomBytes(32);
+    const wrapped = await provider.wrapDek(dek);
+    expect(wrapped.kekVersion).toBe(1);
+    const unwrapped = await provider.unwrapDek(wrapped.encryptedDek, wrapped.kekVersion);
+    expect(unwrapped.equals(dek)).toBe(true);
+  });
+
+  test("unwrap throws for an unknown kekVersion with a clear error", async () => {
+    const provider = createEnvMasterKeyProvider({
+      env: env({
+        KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+      }),
+    });
+    await expect(provider.unwrapDek(Buffer.alloc(60), 99)).rejects.toThrow(/no KEK for version 99/);
+  });
+
+  test("isAvailable returns true after successful boot", async () => {
+    const provider = createEnvMasterKeyProvider({
+      env: env({
+        KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+      }),
+    });
+    expect(await provider.isAvailable()).toBe(true);
+  });
+});

package/src/secrets/__tests__/envelope.test.ts

@@ -0,0 +1,74 @@
+import { randomBytes } from "node:crypto";
+import { describe, expect, test } from "vitest";
+import { createEnvMasterKeyProvider } from "../env-master-key-provider";
+import { decryptValue, encryptValue } from "../envelope";
+
+function makeEnv(versions: Record<number, Buffer>, currentVersion: number): Record<string, string> {
+  const env: Record<string, string> = {
+    KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: String(currentVersion),
+  };
+  for (const [v, key] of Object.entries(versions)) {
+    env[`KUMIKO_SECRETS_MASTER_KEY_V${v}`] = key.toString("base64");
+  }
+  return env;
+}
+
+describe("envelope — encryptValue/decryptValue", () => {
+  test("round-trips plaintext correctly", async () => {
+    const provider = createEnvMasterKeyProvider({
+      env: makeEnv({ 1: randomBytes(32) }, 1),
+    });
+    const envelope = await encryptValue("hello world", provider);
+    const back = await decryptValue(envelope, provider);
+    expect(back).toBe("hello world");
+  });
+
+  test("every encryption produces a distinct IV and ciphertext for the same plaintext", async () => {
+    const provider = createEnvMasterKeyProvider({
+      env: makeEnv({ 1: randomBytes(32) }, 1),
+    });
+    const a = await encryptValue("same", provider);
+    const b = await encryptValue("same", provider);
+    // Different IVs → different ciphertexts, even for the same plaintext.
+    // This is a GCM security requirement: reusing (key, IV) breaks the cipher.
+    expect(a.iv.equals(b.iv)).toBe(false);
+    expect(a.ciphertext.equals(b.ciphertext)).toBe(false);
+  });
+
+  test("round-trips UTF-8 content including emoji", async () => {
+    const provider = createEnvMasterKeyProvider({
+      env: makeEnv({ 1: randomBytes(32) }, 1),
+    });
+    const envelope = await encryptValue("🔐 Geheim — mit Umlauten ä ö ü ß", provider);
+    expect(await decryptValue(envelope, provider)).toBe("🔐 Geheim — mit Umlauten ä ö ü ß");
+  });
+
+  test("tampered ciphertext fails auth-tag check", async () => {
+    const provider = createEnvMasterKeyProvider({
+      env: makeEnv({ 1: randomBytes(32) }, 1),
+    });
+    const envelope = await encryptValue("integrity matters", provider);
+    // Flip one byte of the ciphertext. GCM auth tag must reject.
+    const tampered = {
+      ...envelope,
+      ciphertext: Buffer.concat([
+        envelope.ciphertext.subarray(0, 1),
+        Buffer.from([envelope.ciphertext[0]! ^ 0xff]),
+        envelope.ciphertext.subarray(2),
+      ]),
+    };
+    await expect(decryptValue(tampered, provider)).rejects.toThrow();
+  });
+
+  test("tampered authTag is rejected", async () => {
+    const provider = createEnvMasterKeyProvider({
+      env: makeEnv({ 1: randomBytes(32) }, 1),
+    });
+    const envelope = await encryptValue("auth me", provider);
+    const tampered = {
+      ...envelope,
+      authTag: Buffer.alloc(envelope.authTag.length, 0),
+    };
+    await expect(decryptValue(tampered, provider)).rejects.toThrow();
+  });
+});