@intentius/chant-lexicon-k8s 0.46.0 → 0.50.0

package/src/sops/encrypted-secret-file.test.ts

@@ -0,0 +1,333 @@
+/**
+ * Committed SOPS ciphertext, end to end. What must hold: a
+ * committed-encrypted `declareSecret()` resolves its file at `buildRoots()`,
+ * the bytes leave the build BYTE-FOR-BYTE as a sidecar, the primary output
+ * never carries them, and every way the claim can be false — missing file,
+ * wrong name, no `sops` block, a value that is not `ENC[...]` — refuses with
+ * the path in the message and nothing emitted.
+ *
+ * The fixture (`../testdata/sops/db-credentials.sops.yaml`) is a real
+ * sops-shaped document: cleartext structure, `ENC[...]` values, an age
+ * recipient block and a `mac`. Nothing in this suite decrypts anything —
+ * there is no key, and no code path that could use one.
+ */
+import { describe, test, expect } from "vitest";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { build } from "@intentius/chant";
+import { declareSecret, type CommittedEncryptedSecretDeclaration } from "@intentius/chant/secret-provenance";
+import type { Declarable } from "@intentius/chant/declarable";
+import {
+  encryptedSecretBuildRoot,
+  resolveEncryptedSecrets,
+  validateEncryptedSecretDocument,
+  committedEncryptedDeclarations,
+} from "./encrypted-secret-file";
+import { isEncryptedSecretFileEntity, ENCRYPTED_SECRET_FILE_TYPE } from "./entity";
+import { k8sSerializer } from "../serializer";
+import { k8sPlugin } from "../plugin";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const fixtureRoot = join(here, "..", "testdata", "sops");
+const FIXTURE = "db-credentials.sops.yaml";
+const FIXTURE_TEXT = readFileSync(join(fixtureRoot, FIXTURE), "utf-8");
+/** Absolute path to core's factory — a temp project cannot resolve "@intentius/chant". */
+const DECLARE_SECRET_MODULE = join(here, "..", "..", "..", "..", "packages", "core", "src", "secret-provenance");
+
+function declaration(
+  overrides: Partial<{ name: string; file: string }> = {},
+): CommittedEncryptedSecretDeclaration {
+  return declareSecret({
+    name: overrides.name ?? "db-credentials",
+    provenance: "committed-encrypted",
+    file: overrides.file ?? FIXTURE,
+    keys: ["POSTGRES_USER", "POSTGRES_PASSWORD"],
+  });
+}
+
+function declarations(...decls: CommittedEncryptedSecretDeclaration[]) {
+  return new Map(decls.map((d, i) => [`decl${i}`, d]));
+}
+
+describe("resolveEncryptedSecrets — the buildRoots read path", () => {
+  test("reads the committed bytes and wraps them in one entity", () => {
+    const entities = resolveEncryptedSecrets({
+      projectRoot: fixtureRoot,
+      declarations: declarations(declaration()),
+    });
+
+    expect([...entities.keys()]).toEqual(["sops:db-credentials"]);
+    const entity = entities.get("sops:db-credentials")!;
+    expect(isEncryptedSecretFileEntity(entity)).toBe(true);
+    if (!isEncryptedSecretFileEntity(entity)) return;
+    expect(entity.lexicon).toBe("k8s");
+    expect(entity.entityType).toBe(ENCRYPTED_SECRET_FILE_TYPE);
+    expect(entity.filename).toBe(FIXTURE);
+    expect(entity.secretName).toBe("db-credentials");
+    // The namespace is read from the file, not restated by the author — SOPS
+    // encrypts values, not structure, so metadata is cleartext.
+    expect(entity.namespace).toBe("apps");
+    expect(entity.text).toBe(FIXTURE_TEXT);
+  });
+
+  test("a declaration in a subdirectory keeps the basename as the sidecar name", () => {
+    const entities = resolveEncryptedSecrets({
+      projectRoot: join(fixtureRoot, ".."),
+      declarations: declarations(declaration({ file: `sops/${FIXTURE}` })),
+    });
+    const entity = [...entities.values()][0];
+    expect(isEncryptedSecretFileEntity(entity) && entity.filename).toBe(FIXTURE);
+  });
+
+  test("no committed-encrypted declarations contributes nothing", async () => {
+    const contribution = await encryptedSecretBuildRoot({ projectRoot: fixtureRoot, config: {} });
+    expect(contribution.entities.size).toBe(0);
+  });
+
+  test("the plugin hook resolves declarations from ctx.entities", async () => {
+    const contribution = await k8sPlugin.buildRoots!({
+      projectRoot: fixtureRoot,
+      config: {},
+      entities: new Map<string, Declarable>([["dbCredentials", declaration()]]),
+    });
+    expect([...contribution.entities.keys()]).toEqual(["sops:db-credentials"]);
+  });
+
+  test("committedEncryptedDeclarations ignores the other three kinds", () => {
+    const entities = new Map<string, Declarable>([
+      ["a", declareSecret({ name: "a", provenance: "referenced" })],
+      ["b", declareSecret({ name: "b", provenance: "generated-once", keys: ["k"] })],
+      ["c", declaration()],
+    ]);
+    expect([...committedEncryptedDeclarations(entities).keys()]).toEqual(["c"]);
+  });
+
+  test("a missing file refuses, naming the resolved path", () => {
+    expect(() =>
+      resolveEncryptedSecrets({
+        projectRoot: fixtureRoot,
+        declarations: declarations(declaration({ name: "gone", file: "nowhere.sops.yaml" })),
+      }),
+    ).toThrow(/not readable at .*nowhere\.sops\.yaml/);
+  });
+
+  test("two declarations whose paths share a basename refuse rather than overwrite", async () => {
+    const dir = join(tmpdir(), `chant-sops-collide-${Date.now()}-${Math.random()}`);
+    await mkdir(join(dir, "a"), { recursive: true });
+    await mkdir(join(dir, "b"), { recursive: true });
+    try {
+      await writeFile(join(dir, "a", "creds.sops.yaml"), FIXTURE_TEXT);
+      await writeFile(
+        join(dir, "b", "creds.sops.yaml"),
+        FIXTURE_TEXT.replace("name: db-credentials", "name: other-credentials"),
+      );
+      expect(() =>
+        resolveEncryptedSecrets({
+          projectRoot: dir,
+          declarations: declarations(
+            declaration({ file: "a/creds.sops.yaml" }),
+            declaration({ name: "other-credentials", file: "b/creds.sops.yaml" }),
+          ),
+        }),
+      ).toThrow(/collides/);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("validateEncryptedSecretDocument", () => {
+  const declared = { name: "db-credentials", file: FIXTURE };
+
+  test("the fixture is clean, and its key names (never values) are read back", () => {
+    const { problems, document } = validateEncryptedSecretDocument(FIXTURE_TEXT, declared);
+    expect(problems).toEqual([]);
+    expect(document!.name).toBe("db-credentials");
+    expect(document!.namespace).toBe("apps");
+    expect(document!.keys.sort()).toEqual(["POSTGRES_PASSWORD", "POSTGRES_USER"]);
+  });
+
+  test("a metadata.name other than the declared one is a problem", () => {
+    const text = FIXTURE_TEXT.replace("name: db-credentials", "name: other-credentials");
+    const { problems } = validateEncryptedSecretDocument(text, declared);
+    expect(problems.join("\n")).toMatch(/metadata\.name "other-credentials"/);
+  });
+
+  test("a document that is not a v1 Secret is a problem", () => {
+    const text = FIXTURE_TEXT.replace("kind: Secret", "kind: ConfigMap");
+    const { problems } = validateEncryptedSecretDocument(text, declared);
+    expect(problems.join("\n")).toMatch(/not a v1 Secret/);
+  });
+
+  test("a missing sops block is a problem — the file was never encrypted", () => {
+    const text = FIXTURE_TEXT.slice(0, FIXTURE_TEXT.indexOf("sops:"));
+    const { problems } = validateEncryptedSecretDocument(text, declared);
+    expect(problems.join("\n")).toMatch(/no top-level `sops` block/);
+  });
+
+  test("a plaintext data value is a problem, reported by KEY name only", () => {
+    const text = FIXTURE_TEXT.replace(
+      /POSTGRES_PASSWORD: ENC\[[^\]]*\]/,
+      "POSTGRES_PASSWORD: hunter2",
+    );
+    const { problems } = validateEncryptedSecretDocument(text, declared);
+    const message = problems.join("\n");
+    expect(message).toMatch(/stringData\."POSTGRES_PASSWORD" is not encrypted/);
+    // The constitutional line: a value is tested, never echoed.
+    expect(message).not.toContain("hunter2");
+  });
+
+  test("multi-document files are refused in v1", () => {
+    const { problems } = validateEncryptedSecretDocument(`${FIXTURE_TEXT}\n---\n${FIXTURE_TEXT}`, declared);
+    expect(problems.join("\n")).toMatch(/contains 2 YAML documents/);
+  });
+
+  test("unparseable YAML is refused, not thrown through", () => {
+    const { problems } = validateEncryptedSecretDocument("a:\n  - b\n c: [", declared);
+    expect(problems.length).toBe(1);
+    expect(problems[0]).toMatch(/not valid YAML/);
+  });
+
+  test("every problem is reported at once, not one per build", () => {
+    const text = FIXTURE_TEXT.replace("name: db-credentials", "name: wrong").replace(
+      /POSTGRES_USER: ENC\[[^\]]*\]/,
+      "POSTGRES_USER: postgres",
+    );
+    const { problems } = validateEncryptedSecretDocument(text, declared);
+    expect(problems.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("resolution refuses on any problem, emitting nothing", () => {
+    const dir = join(tmpdir(), `chant-sops-bad-${Date.now()}-${Math.random()}`);
+    return (async () => {
+      await mkdir(dir, { recursive: true });
+      try {
+        await writeFile(
+          join(dir, FIXTURE),
+          FIXTURE_TEXT.replace(/POSTGRES_USER: ENC\[[^\]]*\]/, "POSTGRES_USER: postgres"),
+        );
+        expect(() =>
+          resolveEncryptedSecrets({ projectRoot: dir, declarations: declarations(declaration()) }),
+        ).toThrow(/does not resolve[\s\S]*is not encrypted/);
+      } finally {
+        await rm(dir, { recursive: true, force: true });
+      }
+    })();
+  });
+});
+
+describe("sidecar emission", () => {
+  const workload: Declarable = {
+    lexicon: "k8s",
+    entityType: "K8s::Apps::Deployment",
+    kind: "resource",
+    props: {
+      metadata: { name: "api", namespace: "apps" },
+      spec: {
+        template: {
+          spec: {
+            containers: [
+              { name: "api", image: "api:1.0", envFrom: [{ secretRef: { name: "db-credentials" } }] },
+            ],
+          },
+        },
+      },
+    },
+    [Symbol.for("chant.declarable")]: true,
+  } as unknown as Declarable;
+
+  function serializeWithCiphertext() {
+    const entities = new Map<string, Declarable>([["api", workload]]);
+    for (const [name, entity] of resolveEncryptedSecrets({
+      projectRoot: fixtureRoot,
+      declarations: declarations(declaration()),
+    })) {
+      entities.set(name, entity);
+    }
+    return k8sSerializer.serialize(entities);
+  }
+
+  test("the ciphertext leaves as a sidecar file, byte for byte", () => {
+    const result = serializeWithCiphertext();
+    expect(typeof result).toBe("object");
+    if (typeof result === "string") return;
+    expect(Object.keys(result.files ?? {})).toEqual([FIXTURE]);
+    expect(result.files![FIXTURE]).toBe(FIXTURE_TEXT);
+  });
+
+  test("the primary output carries no ciphertext and no Secret document", () => {
+    const result = serializeWithCiphertext();
+    const primary = typeof result === "string" ? result : result.primary;
+    expect(primary).toContain("kind: Deployment");
+    expect(primary).not.toContain("ENC[");
+    expect(primary).not.toContain("kind: Secret");
+    expect(primary).not.toContain("sops");
+  });
+
+  test("a build with no ciphertext still returns a bare string — the common case is unchanged", () => {
+    const result = k8sSerializer.serialize(new Map<string, Declarable>([["api", workload]]));
+    expect(typeof result).toBe("string");
+  });
+
+  test("the whole path through build(): declaration in, sidecar out", async () => {
+    const dir = join(tmpdir(), `chant-sops-build-${Date.now()}-${Math.random()}`);
+    await mkdir(dir, { recursive: true });
+    try {
+      await writeFile(join(dir, FIXTURE), FIXTURE_TEXT);
+      await writeFile(
+        join(dir, "secrets.infra.ts"),
+        `import { declareSecret } from ${JSON.stringify(DECLARE_SECRET_MODULE)};
+export const dbCredentials = declareSecret({
+  name: "db-credentials",
+  provenance: "committed-encrypted",
+  file: ${JSON.stringify(FIXTURE)},
+  keys: ["POSTGRES_USER", "POSTGRES_PASSWORD"],
+});
+`,
+      );
+
+      const result = await build(dir, [k8sSerializer], undefined, {
+        buildRoots: [(ctx) => k8sPlugin.buildRoots!({ projectRoot: dir, config: {}, entities: ctx.entities })],
+      });
+
+      expect(result.errors).toEqual([]);
+      const output = result.outputs.get("k8s")!;
+      expect(typeof output).toBe("object");
+      if (typeof output === "string") return;
+      expect(output.files![FIXTURE]).toBe(FIXTURE_TEXT);
+      expect(output.primary).not.toContain("ENC[");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("a broken declaration fails the build with a message, not a stack trace", async () => {
+    const dir = join(tmpdir(), `chant-sops-build-bad-${Date.now()}-${Math.random()}`);
+    await mkdir(dir, { recursive: true });
+    try {
+      await writeFile(
+        join(dir, "secrets.infra.ts"),
+        `import { declareSecret } from ${JSON.stringify(DECLARE_SECRET_MODULE)};
+export const dbCredentials = declareSecret({
+  name: "db-credentials",
+  provenance: "committed-encrypted",
+  file: "secrets/never-committed.sops.yaml",
+});
+`,
+      );
+
+      const result = await build(dir, [k8sSerializer], undefined, {
+        buildRoots: [(ctx) => k8sPlugin.buildRoots!({ projectRoot: dir, config: {}, entities: ctx.entities })],
+      });
+
+      expect(result.errors.length).toBe(1);
+      expect(result.errors[0].message).toContain("never-committed.sops.yaml");
+      expect(result.errors[0].message).toContain("not readable");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/sops/encrypted-secret-file.ts

@@ -0,0 +1,264 @@
+/**
+ * Committed SOPS ciphertext as a build artifact (epic lex00/iac-cd-bench#6).
+ *
+ * A `declareSecret({ provenance: "committed-encrypted", file })` names a
+ * repo-relative path to ciphertext that lives in git. This module is the
+ * resolution stage: at `buildRoots()` — chant's one sanctioned impure seam,
+ * the same one the kustomize roots and cedar's `Schema` use — it reads those
+ * bytes, validates the document is what the declaration claims, and wraps
+ * them in an entity the serializer copies out VERBATIM as a sidecar file.
+ *
+ * Three properties this is built to keep:
+ *
+ * - **Never inlined.** The bytes go to `SerializerResult.files`, never into
+ *   the primary multi-document YAML. chant's own appliers read the primary
+ *   output, so "chant pushes an undecrypted Secret into a cluster" is
+ *   structurally impossible rather than merely unlikely. Flux is the only
+ *   thing that applies the sidecar, and Flux decrypts first.
+ * - **Deterministic and offline.** The bytes are copied, not re-serialized:
+ *   no parse-and-re-emit round trip, no key sorting, no digest. No `sops`
+ *   binary is invoked in either direction, so a missing binary and a missing
+ *   age key are not failure modes — the plaintext has no representation here
+ *   at any stage.
+ * - **Fails loudly, not weirdly.** A missing file, a non-Secret document, a
+ *   name mismatch, a missing `sops` block, or a `data`/`stringData` value
+ *   that is not `ENC[...]`-shaped refuses with the declared path in the
+ *   message. That last check is the one that earns the feature: it catches
+ *   "edited the file and forgot to re-encrypt", the exact failure mode that
+ *   puts plaintext into git.
+ *
+ * The entity is deliberately internal — not exported from the package entry
+ * point, not constructible by an author. The authored surface is
+ * `declareSecret`; a public entity taking inline bytes is the one thing this
+ * whole design exists to prevent.
+ *
+ * Design: docs/design/committed-encrypted-sops-provenance.md §3.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadAll } from "js-yaml";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import {
+  ENCRYPTED_SECRET_ENTITY_PREFIX,
+  ENCRYPTED_SECRET_FILE_MARKER,
+  ENCRYPTED_SECRET_FILE_TYPE,
+  sidecarFilename,
+  type EncryptedSecretFileEntity,
+} from "./entity";
+import type { BuildRootContext, BuildRootContribution } from "@intentius/chant/lexicon";
+import {
+  collectSecretDeclarations,
+  isCommittedEncryptedSecret,
+  type CommittedEncryptedSecretDeclaration,
+} from "@intentius/chant/secret-provenance";
+
+export {
+  ENCRYPTED_SECRET_FILE_MARKER,
+  ENCRYPTED_SECRET_FILE_TYPE,
+  ENCRYPTED_SECRET_ENTITY_PREFIX,
+  isEncryptedSecretFileEntity,
+  sidecarFilename,
+  type EncryptedSecretFileEntity,
+} from "./entity";
+
+/** A parsed ciphertext document, or the reasons it is not one. */
+export interface EncryptedSecretDocument {
+  /** `metadata.name`, when the document had one. */
+  name?: string;
+  /** `metadata.namespace`, when the document had one. */
+  namespace?: string;
+  /** Key names found under `data`/`stringData` — names only, never values. */
+  keys: string[];
+}
+
+/**
+ * Validate one committed ciphertext document against its declaration.
+ *
+ * Returns every problem found, so an author sees all of them at once rather
+ * than one per build. Both consumers share this: the `buildRoots()` stage
+ * turns the list into a refusal, and WK8504 turns it into diagnostics.
+ *
+ * A value is only ever tested for the `ENC[` prefix, inside this one frame,
+ * and only the offending KEY name is reported — the discipline
+ * `declareSecret`'s own runtime guard uses.
+ */
+export function validateEncryptedSecretDocument(
+  text: string,
+  declared: { name: string; file: string },
+): { problems: string[]; document?: EncryptedSecretDocument } {
+  const problems: string[] = [];
+
+  let docs: unknown[];
+  try {
+    docs = loadAll(text);
+  } catch (err) {
+    return {
+      problems: [`${declared.file} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`],
+    };
+  }
+
+  const present = docs.filter((d) => d !== null && d !== undefined);
+  if (present.length === 0) {
+    return { problems: [`${declared.file} contains no YAML document`] };
+  }
+  if (present.length > 1) {
+    // v1 keys a declaration by one `name`; a declaration-per-document sharing
+    // a file, or a `names: string[]` field, is a design change to make
+    // deliberately rather than by accident.
+    return {
+      problems: [
+        `${declared.file} contains ${present.length} YAML documents — ` +
+          `a committed-encrypted declaration covers exactly one Secret`,
+      ],
+    };
+  }
+
+  const doc = present[0];
+  if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
+    return { problems: [`${declared.file} is not a Kubernetes object`] };
+  }
+  const record = doc as Record<string, unknown>;
+
+  if (record.apiVersion !== "v1" || record.kind !== "Secret") {
+    problems.push(
+      `${declared.file} is not a v1 Secret ` +
+        `(apiVersion "${String(record.apiVersion)}", kind "${String(record.kind)}")`,
+    );
+  }
+
+  const metadata = asRecord(record.metadata);
+  const name = typeof metadata?.name === "string" ? metadata.name : undefined;
+  const namespace = typeof metadata?.namespace === "string" ? metadata.namespace : undefined;
+  if (name !== declared.name) {
+    problems.push(
+      `${declared.file} has metadata.name "${name ?? "(none)"}", ` +
+        `but the declaration names "${declared.name}"`,
+    );
+  }
+
+  // SOPS's own metadata block. Its absence means the file was never encrypted
+  // (or was decrypted in place and committed), which is the whole point of
+  // checking. `sops.mac` is a MAC over the PLAINTEXT — it is carried by the
+  // verbatim copy and must never be read as a semantic value, so nothing here
+  // looks past the block's presence.
+  if (asRecord(record.sops) === undefined) {
+    problems.push(
+      `${declared.file} has no top-level \`sops\` block — it does not look encrypted. ` +
+        `Run \`sops -e -i\` before committing.`,
+    );
+  }
+
+  // Scoped to data/stringData alone: SOPS's `encrypted_regex` leaves
+  // apiVersion, kind and metadata cleartext by design.
+  const keys: string[] = [];
+  for (const field of ["data", "stringData"] as const) {
+    const block = asRecord(record[field]);
+    if (block === undefined) continue;
+    for (const [key, value] of Object.entries(block)) {
+      keys.push(key);
+      if (typeof value !== "string" || !value.startsWith("ENC[")) {
+        problems.push(
+          `${declared.file}: ${field}."${key}" is not encrypted (expected an ENC[...] value) — ` +
+            `re-run \`sops -e -i\` before committing`,
+        );
+      }
+    }
+  }
+
+  return { problems, document: { name, namespace, keys } };
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/** Options for {@link resolveEncryptedSecrets} — `readFile` is injectable for tests. */
+export interface ResolveEncryptedSecretsOptions {
+  projectRoot: string;
+  declarations: ReadonlyMap<string, CommittedEncryptedSecretDeclaration>;
+  readFile?: (path: string) => string;
+}
+
+/**
+ * Read and validate every committed-encrypted declaration, returning one
+ * entity per resolved file. Throws on the first declaration that does not
+ * resolve, with every problem for that declaration in the message — a build
+ * that would emit a broken or unencrypted Secret must not proceed.
+ */
+export function resolveEncryptedSecrets(
+  options: ResolveEncryptedSecretsOptions,
+): Map<string, Declarable> {
+  const read = options.readFile ?? ((path: string) => readFileSync(path, "utf-8"));
+  const entities = new Map<string, Declarable>();
+  const byFilename = new Map<string, string>();
+
+  for (const decl of options.declarations.values()) {
+    const absolute = resolve(options.projectRoot, decl.file);
+    let text: string;
+    try {
+      text = read(absolute);
+    } catch (err) {
+      throw new Error(
+        `declareSecret("${decl.name}"): committed ciphertext not readable at ${absolute} ` +
+          `(declared as "${decl.file}") — ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+
+    const { problems, document } = validateEncryptedSecretDocument(text, decl);
+    if (problems.length > 0) {
+      throw new Error(
+        `declareSecret("${decl.name}"): committed ciphertext does not resolve —\n  ` +
+          problems.join("\n  "),
+      );
+    }
+
+    const filename = sidecarFilename(decl.file);
+    const collides = byFilename.get(filename);
+    if (collides !== undefined) {
+      throw new Error(
+        `declareSecret("${decl.name}"): sidecar filename "${filename}" collides with the one ` +
+          `"${collides}" already emits — additional files share one flat namespace, so two ` +
+          `declarations whose paths share a basename would silently overwrite each other`,
+      );
+    }
+    byFilename.set(filename, decl.file);
+
+    const entity: EncryptedSecretFileEntity = {
+      lexicon: "k8s",
+      entityType: ENCRYPTED_SECRET_FILE_TYPE,
+      filename,
+      text,
+      secretName: decl.name,
+      ...(document?.namespace !== undefined ? { namespace: document.namespace } : {}),
+      sourcePath: decl.file,
+      [DECLARABLE_MARKER]: true,
+      [ENCRYPTED_SECRET_FILE_MARKER]: true,
+    };
+    entities.set(`${ENCRYPTED_SECRET_ENTITY_PREFIX}${decl.name}`, entity);
+  }
+
+  return entities;
+}
+
+/** Every committed-encrypted declaration in an entity map, keyed by entity name. */
+export function committedEncryptedDeclarations(
+  entities: ReadonlyMap<string, Declarable>,
+): Map<string, CommittedEncryptedSecretDeclaration> {
+  const out = new Map<string, CommittedEncryptedSecretDeclaration>();
+  for (const [name, decl] of collectSecretDeclarations(entities)) {
+    if (isCommittedEncryptedSecret(decl)) out.set(name, decl);
+  }
+  return out;
+}
+
+/**
+ * The `buildRoots` contribution: one entity per committed-encrypted
+ * declaration, holding the file's bytes verbatim.
+ */
+export async function encryptedSecretBuildRoot(ctx: BuildRootContext): Promise<BuildRootContribution> {
+  const declarations = committedEncryptedDeclarations(ctx.entities ?? new Map());
+  if (declarations.size === 0) return { entities: new Map() };
+  return { entities: resolveEncryptedSecrets({ projectRoot: ctx.projectRoot, declarations }) };
+}

package/src/sops/entity.ts

@@ -0,0 +1,53 @@
+/**
+ * The committed-ciphertext entity: marker, shape and type guard only.
+ *
+ * Split from `./encrypted-secret-file.ts` so the serializer can recognise the
+ * entity without pulling `node:fs` and a YAML parser into its module graph —
+ * the resolution stage needs both, the emission stage needs neither.
+ *
+ * Not exported from the package entry point and not constructible by an
+ * author: the authored surface is `declareSecret({ provenance:
+ * "committed-encrypted", file })`. A public entity taking inline bytes is
+ * exactly what this design exists to prevent.
+ */
+import { basename } from "node:path";
+import type { Declarable } from "@intentius/chant/declarable";
+
+/** Marks an entity whose bytes are committed ciphertext, emitted verbatim. */
+export const ENCRYPTED_SECRET_FILE_MARKER = Symbol.for("chant.k8s.encryptedSecretFile");
+
+/**
+ * The entity's type name. Deliberately outside the `K8s::{Group}::{Kind}`
+ * surface a real Secret speaks: an observer must NOT read this against a live
+ * cluster — the ciphertext is not the thing in the cluster, the decrypted
+ * Secret is — so a type with no generated operation surface, reporting the
+ * honest NOT-OBSERVED, is the right answer.
+ */
+export const ENCRYPTED_SECRET_FILE_TYPE = "K8s::Sops::EncryptedSecretFile";
+
+/** Entity-map key prefix, colon-separated so it cannot collide with a TS export name. */
+export const ENCRYPTED_SECRET_ENTITY_PREFIX = "sops:";
+
+export interface EncryptedSecretFileEntity extends Declarable {
+  readonly entityType: typeof ENCRYPTED_SECRET_FILE_TYPE;
+  readonly [ENCRYPTED_SECRET_FILE_MARKER]: true;
+  /** Sidecar filename written beside the primary output. */
+  readonly filename: string;
+  /** The committed bytes, exactly as read. */
+  readonly text: string;
+  /** `metadata.name` of the encrypted Secret — equal to the declaration's name. */
+  readonly secretName: string;
+  /** `metadata.namespace`, cleartext in the file (SOPS encrypts values, not structure). */
+  readonly namespace?: string;
+  /** The declared repo-relative path, for diagnostics. */
+  readonly sourcePath: string;
+}
+
+export function isEncryptedSecretFileEntity(entity: Declarable): entity is EncryptedSecretFileEntity {
+  return (entity as unknown as Record<symbol, unknown>)[ENCRYPTED_SECRET_FILE_MARKER] === true;
+}
+
+/** The sidecar filename a declaration's file is emitted under. */
+export function sidecarFilename(file: string): string {
+  return basename(file);
+}