@intentius/chant-lexicon-k8s 0.46.0 → 0.50.0

package/src/secret-store.test.ts

@@ -0,0 +1,184 @@
+/**
+ * The k8s SecretStoreAdapter (chant #1830) over the fake cluster — a real
+ * `@intentius/chant-k8s-client` with only the HTTP send replaced, the same
+ * harness the teardown and prune suites use.
+ *
+ * What is asserted is the constitutional line as much as the behavior: no
+ * return value and no log line of the read half ever carries a `data` value,
+ * and the write half consumes each key's material exactly once, at the write,
+ * with the ownership marker and the generated-once label stamped on.
+ */
+
+import { describe, test, expect, vi, afterEach } from "vitest";
+import {
+  SecretMaterial,
+  consumeSecretMaterial,
+  ensureSecretMaterialization,
+  SecretContractMismatchError,
+} from "@intentius/chant/secret-materialization";
+import { LABEL_OWNERSHIP_KEYS, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+import type { K8sClient, K8sObject } from "@intentius/chant-k8s-client";
+import type { RecordedRequest } from "@intentius/chant-k8s-client/testing";
+import { fakeCluster, objectKey } from "./api/fake-cluster";
+import { k8sSecretStore } from "./secret-store";
+import { GENERATED_ONCE_LABEL_KEY, GENERATED_ONCE_LABEL_VALUE } from "./secret-labels";
+
+const PLAINTEXT_A = "plain-material-alpha";
+const PLAINTEXT_B = "plain-material-bravo";
+const LIVE_VALUE_1 = Buffer.from("live-master-bytes", "utf-8").toString("base64");
+const LIVE_VALUE_2 = Buffer.from("live-conf-bytes", "utf-8").toString("base64");
+
+/** Every string no read-path return or log may ever contain. */
+const FORBIDDEN = [PLAINTEXT_A, PLAINTEXT_B, LIVE_VALUE_1, LIVE_VALUE_2, "live-master-bytes", "live-conf-bytes"];
+
+function liveSecret(): K8sObject {
+  return {
+    apiVersion: "v1",
+    kind: "Secret",
+    metadata: {
+      name: "master-key",
+      namespace: "prod",
+      uid: "uid-master-key",
+      labels: {
+        [LABEL_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE,
+        [GENERATED_ONCE_LABEL_KEY]: GENERATED_ONCE_LABEL_VALUE,
+      },
+      annotations: { "example.com/note": "hand-written" },
+    },
+    type: "Opaque",
+    data: { MASTER_KEY: LIVE_VALUE_1, "app.conf": LIVE_VALUE_2 },
+  };
+}
+
+function clusterWithSecret() {
+  return fakeCluster({
+    objects: { [objectKey("v1", "Secret", "master-key", "prod")]: liveSecret() },
+    respond: (req: RecordedRequest) => (req.method === "PATCH" ? { body: JSON.parse(String(req.body)) } : undefined),
+  });
+}
+
+async function clientOf(cluster: ReturnType<typeof fakeCluster>): Promise<K8sClient> {
+  return (await cluster.connector({})).client;
+}
+
+/** Spies on every console channel; returns everything logged as one string. */
+function spyConsole(): { flush: () => string } {
+  const calls: unknown[][] = [];
+  for (const level of ["log", "info", "warn", "error", "debug"] as const) {
+    vi.spyOn(console, level).mockImplementation((...args: unknown[]) => {
+      calls.push(args);
+    });
+  }
+  return { flush: () => calls.flat().map(String).join("\n") };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("k8sSecretStore — the read half never returns or logs a value", () => {
+  test("exists answers presence and nothing else", async () => {
+    const cluster = clusterWithSecret();
+    const store = k8sSecretStore("prod", await clientOf(cluster));
+    await expect(store.exists("master-key")).resolves.toBe(true);
+    await expect(store.exists("absent")).resolves.toBe(false);
+  });
+
+  test("describe projects key NAMES and labels/annotations, never data values", async () => {
+    const cluster = clusterWithSecret();
+    const spy = spyConsole();
+    const store = k8sSecretStore("prod", await clientOf(cluster));
+
+    const description = await store.describe("master-key");
+
+    expect(description.keys).toEqual(["MASTER_KEY", "app.conf"]);
+    expect(description.metadata?.[GENERATED_ONCE_LABEL_KEY]).toBe(GENERATED_ONCE_LABEL_VALUE);
+    expect(description.metadata?.["example.com/note"]).toBe("hand-written");
+    // The claim that matters: nothing value-shaped in the return, under any
+    // key — the description carries exactly `keys` and `metadata`, and no
+    // byte of the stored values appears anywhere in its serialization.
+    expect(Object.keys(description).sort()).toEqual(["keys", "metadata"]);
+    const serialized = JSON.stringify(description);
+    for (const forbidden of FORBIDDEN) expect(serialized).not.toContain(forbidden);
+    for (const forbidden of FORBIDDEN) expect(spy.flush()).not.toContain(forbidden);
+  });
+
+  test("ensureSecretMaterialization over the adapter: present-and-matching writes nothing", async () => {
+    const cluster = clusterWithSecret();
+    const store = k8sSecretStore("prod", await clientOf(cluster));
+    const outcome = await ensureSecretMaterialization(store, {
+      name: "master-key",
+      keys: ["MASTER_KEY", "app.conf"],
+    });
+    expect(outcome).toEqual({ outcome: "present", name: "master-key", keys: ["MASTER_KEY", "app.conf"] });
+    expect(cluster.layer.requests.filter((r) => r.method === "PATCH")).toEqual([]);
+  });
+
+  test("a key-set mismatch fails loudly naming key names, never values", async () => {
+    const cluster = clusterWithSecret();
+    const store = k8sSecretStore("prod", await clientOf(cluster));
+    const err = await ensureSecretMaterialization(store, {
+      name: "master-key",
+      keys: ["MASTER_KEY", "MISSING_KEY"],
+    }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(SecretContractMismatchError);
+    const message = String((err as Error).message);
+    expect(message).toContain("MISSING_KEY");
+    expect(message).toContain("app.conf");
+    for (const forbidden of FORBIDDEN) expect(message).not.toContain(forbidden);
+  });
+});
+
+describe("k8sSecretStore — create consumes material at the write and stamps the markers", () => {
+  test("mints one value per key, consumes each handle exactly once, stamps ownership + generated-once", async () => {
+    const cluster = fakeCluster({
+      respond: (req: RecordedRequest) => (req.method === "PATCH" ? { body: JSON.parse(String(req.body)) } : undefined),
+    });
+    const minted: SecretMaterial[] = [];
+    const generate = vi.fn((key: string) => {
+      const handle = SecretMaterial.mint(key === "MASTER_KEY" ? PLAINTEXT_A : PLAINTEXT_B);
+      minted.push(handle);
+      return handle;
+    });
+
+    const store = k8sSecretStore("prod", await clientOf(cluster), {
+      marker: { stack: "shop", env: "dev" },
+    });
+    const outcome = await ensureSecretMaterialization(
+      store,
+      { name: "master-key", keys: ["MASTER_KEY", "SECOND_KEY"] },
+      generate,
+    );
+    expect(outcome).toEqual({ outcome: "created", name: "master-key", keys: ["MASTER_KEY", "SECOND_KEY"] });
+
+    // One mint per declared key, and every handle burned at the write: a
+    // second consume of any of them throws.
+    expect(generate).toHaveBeenCalledTimes(2);
+    for (const handle of minted) {
+      expect(() => consumeSecretMaterial(handle)).toThrow(/already consumed/);
+    }
+
+    const patch = cluster.layer.requests.find((r) => r.method === "PATCH");
+    expect(patch).toBeDefined();
+    expect(patch!.path).toBe("/api/v1/namespaces/prod/secrets/master-key");
+    expect(patch!.query.fieldManager).toBe("chant:shop");
+    const body = JSON.parse(String(patch!.body)) as K8sObject;
+    expect(body.metadata?.labels).toEqual({
+      [LABEL_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE,
+      [LABEL_OWNERSHIP_KEYS.stack]: "shop",
+      [LABEL_OWNERSHIP_KEYS.env]: "dev",
+      [GENERATED_ONCE_LABEL_KEY]: GENERATED_ONCE_LABEL_VALUE,
+    });
+    expect(body.data).toEqual({
+      MASTER_KEY: Buffer.from(PLAINTEXT_A, "utf-8").toString("base64"),
+      SECOND_KEY: Buffer.from(PLAINTEXT_B, "utf-8").toString("base64"),
+    });
+  });
+
+  test("the handle itself never leaks material: stringify/inspect show only the redaction marker", () => {
+    const handle = SecretMaterial.mint(PLAINTEXT_A);
+    expect(String(handle)).not.toContain(PLAINTEXT_A);
+    expect(JSON.stringify({ handle })).not.toContain(PLAINTEXT_A);
+    consumeSecretMaterial(handle); // leave no live handle behind
+  });
+});

package/src/secret-store.ts

@@ -0,0 +1,165 @@
+/**
+ * The Kubernetes row of the secret-store seam (chant #1830, epic #1365) — a
+ * `SecretStoreAdapter` over the typed client, for the `ensure-secret`
+ * capability verb and the `ensureSecret(...)` op step (both #1829, both
+ * surfaces over core's one materialization engine).
+ *
+ * The constitutional line, held structurally:
+ *
+ * - `exists` and `describe` read the live Secret and report key NAMES and
+ *   labels/annotations only. The `data` values are projected to their key
+ *   names inside one function frame and the object is dropped — nothing
+ *   value-shaped is returned, logged, or retained. The mismatch check in core
+ *   therefore has nothing to compare but names, by construction.
+ * - `create` is the only writer. It redeems each key's material through
+ *   `consumeSecretMaterial` AT the write — the engine hands the generator
+ *   through this seam and never calls it — and returns nothing.
+ *
+ * Every minted Secret carries chant's ownership marker plus the
+ * `chant.intentius.io/generated-once` label (./secret-labels.ts), which is
+ * what both prune paths key their `retained` outcome on: a generated-once
+ * Secret is never in any prunable set, because the stored bytes are the only
+ * copy of material chant never held.
+ *
+ * Not exported from the package entry point — like ./teardown.ts, this module
+ * names the API client, which must stay off the build path (chant #1074,
+ * examples/k8s-client-boundary.test.ts). Consumers reach it by subpath:
+ * `@intentius/chant-lexicon-k8s/secret-store`.
+ */
+
+import type {
+  SecretMaterialGenerator,
+  SecretStoreAdapter,
+  SecretStoreDescription,
+} from "@intentius/chant/secret-materialization";
+import { consumeSecretMaterial } from "@intentius/chant/secret-materialization";
+import {
+  createEnsureSecretCapability,
+  type EnsureSecretInput,
+  type EnsureSecretOutput,
+} from "@intentius/chant/components/verbs/ensure-secret";
+import type { Capability } from "@intentius/chant/components/capability";
+import {
+  LABEL_OWNERSHIP_KEYS,
+  OWNERSHIP_MANAGED_BY_VALUE,
+  ownershipEntries,
+  type OwnershipMarker,
+} from "@intentius/chant/ownership";
+import type { K8sClient, K8sObject } from "@intentius/chant-k8s-client";
+import { defaultK8sConnector, type K8sConnector } from "./api/connect";
+import { GENERATED_ONCE_LABEL_KEY, GENERATED_ONCE_LABEL_VALUE } from "./secret-labels";
+
+const SECRET_REF = { apiVersion: "v1", kind: "Secret" } as const;
+
+export interface K8sSecretStoreOptions {
+  /**
+   * Ownership identity to stamp on a minted Secret, next to the
+   * generated-once label. Omitted stamps `managed-by=chant` alone — the
+   * Secret is still chant-owned and still never prunable.
+   */
+  marker?: OwnershipMarker;
+  /** chant environment, resolved through `k8s.profiles.<env>.context` when no client is handed in. */
+  environment?: string;
+  /** Explicit kubectl context, for the op write path. */
+  context?: string;
+  /** Project directory whose `chant.config.ts` carries the k8s profiles. Defaults to cwd. */
+  cwd?: string;
+  /** The connector to build a client with when none is handed in. Test seam. */
+  connect?: K8sConnector;
+}
+
+/**
+ * Build the k8s `SecretStoreAdapter` for one namespace.
+ *
+ * Pass a `client` where the caller already holds one (an activity that
+ * connected for the rest of its work); omit it and the adapter connects
+ * lazily through the same environment→cluster binding every other k8s path
+ * uses (./api/connect.ts).
+ */
+export function k8sSecretStore(
+  namespace: string,
+  client?: K8sClient,
+  options: K8sSecretStoreOptions = {},
+): SecretStoreAdapter {
+  let pending: Promise<K8sClient> | undefined = client ? Promise.resolve(client) : undefined;
+  const clientOf = (): Promise<K8sClient> =>
+    (pending ??= (options.connect ?? defaultK8sConnector)({
+      ...(options.environment !== undefined ? { environment: options.environment } : {}),
+      ...(options.context !== undefined ? { context: options.context } : {}),
+      ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+    }).then((connected) => connected.client));
+
+  return {
+    async exists(name: string): Promise<boolean> {
+      const c = await clientOf();
+      return (await c.readIfPresent({ ...SECRET_REF, name, namespace })) !== undefined;
+    },
+
+    async describe(name: string): Promise<SecretStoreDescription> {
+      const c = await clientOf();
+      const live = await c.read({ ...SECRET_REF, name, namespace });
+      // Project key names and drop the object in the same frame. The values
+      // exist only in `live`, which nothing below touches again — the return
+      // carries names and metadata, never a byte of `data`.
+      const keys = Object.keys((live.data as Record<string, unknown> | undefined) ?? {}).sort();
+      const metadata: Record<string, string> = {
+        ...(live.metadata?.annotations ?? {}),
+        ...(live.metadata?.labels ?? {}),
+      };
+      return { keys, metadata };
+    },
+
+    async create(name: string, keys: readonly string[], generate: SecretMaterialGenerator): Promise<void> {
+      const c = await clientOf();
+      // Mint and consume per key, at the write. `consumeSecretMaterial` burns
+      // each handle, so the material cannot be redeemed a second time by
+      // anything, this adapter included.
+      const data: Record<string, string> = {};
+      for (const key of keys) {
+        data[key] = Buffer.from(consumeSecretMaterial(await generate(key)), "utf-8").toString("base64");
+      }
+      const secret: K8sObject = {
+        apiVersion: SECRET_REF.apiVersion,
+        kind: SECRET_REF.kind,
+        metadata: {
+          name,
+          namespace,
+          labels: {
+            ...(options.marker
+              ? ownershipEntries(LABEL_OWNERSHIP_KEYS, options.marker)
+              : { [LABEL_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE }),
+            [GENERATED_ONCE_LABEL_KEY]: GENERATED_ONCE_LABEL_VALUE,
+          },
+        },
+        type: "Opaque",
+        data,
+      };
+      // Server-side apply as chant's field manager — the same write path every
+      // other chant mutation takes. The result (which echoes `data`) is
+      // deliberately discarded.
+      await c.apply(secret, {
+        ...(options.marker ? { fieldManager: `chant:${options.marker.stack}` } : {}),
+      });
+    },
+  };
+}
+
+/**
+ * The real `ensure-secret` capability for a Kubernetes namespace — core's
+ * factory (#1829) over this module's adapter. Replaces the starter set's
+ * typed stub for a project whose secret store is the cluster:
+ *
+ * ```ts
+ * registry.register(k8sEnsureSecretCapability("prod", undefined, {
+ *   marker: { stack: "shop", env: "prod" },
+ *   environment: "prod",
+ * }));
+ * ```
+ */
+export function k8sEnsureSecretCapability(
+  namespace: string,
+  client?: K8sClient,
+  options: K8sSecretStoreOptions = {},
+): Capability<EnsureSecretInput, EnsureSecretOutput> {
+  return createEnsureSecretCapability({ store: k8sSecretStore(namespace, client, options) });
+}

package/src/serializer.ts

@@ -15,6 +15,7 @@ import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-w
 import { emitYAML } from "@intentius/chant/yaml";
 import { isDefaultLabels, isDefaultAnnotations, type DefaultLabels, type DefaultAnnotations } from "./default-labels";
 import { isRenderedManifestEntity } from "./kustomize/rendered-entity";
+import { isEncryptedSecretFileEntity } from "./sops/entity";
 
 const require = createRequire(import.meta.url);
 
@@ -225,7 +226,11 @@ export const k8sSerializer: Serializer = {
   // `chant-disable ARGO001` already written (#1349).
   extraRulePrefixes: ["ARGO", "FLUX"],
 
-  serialize(entities: Map<string, Declarable>, _outputs?: LexiconOutput[], context?: SerializeContext): string {
+  serialize(
+    entities: Map<string, Declarable>,
+    _outputs?: LexiconOutput[],
+    context?: SerializeContext,
+  ): string | SerializerResult {
     // Build reverse map: entity → name
     const entityNames = new Map<Declarable, string>();
     for (const [name, entity] of entities) {
@@ -251,11 +256,36 @@ export const k8sSerializer: Serializer = {
 
     const namespaceDocs: string[] = [];
     const otherDocs: string[] = [];
+    /** Sidecar files — committed ciphertext, copied byte-for-byte. */
+    const files: Record<string, string> = {};
+    /** Basenames within `files` that must never be JSON.parse round-tripped (chant#1937). */
+    const verbatimFiles: string[] = [];
+    const warnings: string[] = [];
 
     for (const [name, entity] of entities) {
       if (isPropertyDeclarable(entity)) continue;
       if (isDefaultLabels(entity) || isDefaultAnnotations(entity)) continue;
 
+      // Committed SOPS ciphertext (epic lex00/iac-cd-bench#6) leaves as a
+      // SIDECAR and never as a document in the primary output. That is the
+      // load-bearing line: chant's appliers read the primary output, so an
+      // undecrypted Secret cannot reach a cluster through them. The bytes are
+      // copied exactly as committed — no re-emit, no label merge, no
+      // ownership stamp — because re-serializing would break the MAC the
+      // `sops` block carries over the plaintext.
+      if (isEncryptedSecretFileEntity(entity)) {
+        const existing = files[entity.filename];
+        if (existing !== undefined && existing !== entity.text) {
+          warnings.push(
+            `k8s: two committed-encrypted secrets emit the same sidecar filename ` +
+              `"${entity.filename}" — the second (${entity.sourcePath}) wins`,
+          );
+        }
+        files[entity.filename] = entity.text;
+        if (!verbatimFiles.includes(entity.filename)) verbatimFiles.push(entity.filename);
+        continue;
+      }
+
       // A kustomize build root's document (#1548 piece 3) is render-final:
       // the overlay decided every field, so the props ARE the manifest and
       // the spec-inference heuristics below (built for typed declarables)
@@ -386,7 +416,16 @@ export const k8sSerializer: Serializer = {
       }
     }
 
-    return [...namespaceDocs, ...otherDocs].join("\n---\n");
+    const primary = [...namespaceDocs, ...otherDocs].join("\n---\n");
+    // A bare string when there is nothing extra to write, so the common case
+    // stays byte-identical to what every existing consumer already reads.
+    if (Object.keys(files).length === 0 && warnings.length === 0) return primary;
+    return {
+      primary,
+      files,
+      ...(verbatimFiles.length > 0 ? { verbatimFiles } : {}),
+      ...(warnings.length > 0 ? { warnings } : {}),
+    };
   },
 };