@intentius/chant-lexicon-k8s 0.46.0 → 0.49.0

package/dist/rules/wk8503.ts

@@ -0,0 +1,220 @@
+/**
+ * WK8503: Workload consumes a Secret nothing in the output produces
+ *
+ * A pod that references a Secret which no manifest in the same build creates
+ * passes `chant build`, passes `chant lint`, applies cleanly — and then fails
+ * at pod start with `CreateContainerConfigError` (chant #1382). This check
+ * closes that gap with the same cross-resource bundle-join ARGO003 uses: every
+ * secret reference in a pod spec (envFrom.secretRef, env valueFrom
+ * secretKeyRef, secret volumes, projected secret sources, imagePullSecrets)
+ * must resolve to a Secret the output produces.
+ *
+ * Producers are the Secret manifests themselves plus the secret-materializing
+ * CRs the lexicon knows: `ExternalSecret` (spec.target.name, defaulting to the
+ * CR's own name), `InfisicalSecret` / `InfisicalDynamicSecret`
+ * (spec.managedSecretReference.secretName — its secretNamespace is honored
+ * separately from the CR's metadata.namespace), and cert-manager
+ * `Certificate` (spec.secretName). Namespaces must be compatible; a side with
+ * no namespace matches any.
+ *
+ * The typed waiver is a `SecretProvenance` declaration (chant #1828, epic
+ * #1365): a `declareSecret({ name, provenance: "referenced" | "from-provider"
+ * | "generated-once" })` covering the secret's name says the estate knows
+ * where the value comes from, and silences the check. That is what lets this
+ * ship at error severity with no suppression comment — a secret minted out of
+ * band is declared, not ignored. References marked `optional: true` are
+ * skipped (the author already said it may not exist).
+ *
+ * `committed-encrypted` is deliberately NOT in that waiver set. The other
+ * three kinds are promises about something outside the build; a
+ * committed-encrypted declaration is a claim about an artifact inside it, and
+ * the build emits that artifact. So it joins the PRODUCER set instead, with
+ * its namespace read from the emitted ciphertext (SOPS leaves metadata
+ * cleartext) — which means namespace matching applies to it exactly as it
+ * does to a literal Secret, and a declaration whose file is broken fails
+ * WK8504 rather than silently waiving this check.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { collectSecretDeclarations } from "@intentius/chant/secret-provenance";
+import { extractPodSpec, type K8sManifest } from "./k8s-helpers";
+import { allManifests } from "./argo-helpers";
+import { resolveEncryptedSecretClaims } from "./sops-helpers";
+
+/** A Secret some manifest in the output materializes. */
+interface ProducedSecret {
+  name: string;
+  namespace?: string;
+}
+
+/** One secret reference found in a pod spec. */
+interface SecretRef {
+  name: string;
+  /** Which field referenced it, for the message (e.g. "envFrom.secretRef"). */
+  via: string;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined;
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+/** Collect every Secret the output produces, from literal Secrets and the
+ * secret-materializing CR kinds the lexicon ships. */
+function collectProducedSecrets(manifests: K8sManifest[]): ProducedSecret[] {
+  const produced: ProducedSecret[] = [];
+  for (const m of manifests) {
+    const metaName = m.metadata?.name;
+    const metaNs = m.metadata?.namespace;
+    switch (m.kind) {
+      case "Secret": {
+        if (typeof metaName === "string") produced.push({ name: metaName, namespace: metaNs });
+        break;
+      }
+      case "ExternalSecret": {
+        // external-secrets.io — writes spec.target.name, defaulting to the CR's own name.
+        const target = asRecord(m.spec?.target);
+        const targetName = typeof target?.name === "string" ? target.name : metaName;
+        if (typeof targetName === "string") produced.push({ name: targetName, namespace: metaNs });
+        break;
+      }
+      case "InfisicalSecret":
+      case "InfisicalDynamicSecret": {
+        // secrets.infisical.com — writes spec.managedSecretReference.secretName;
+        // secretNamespace is carried separately from the CR's own namespace.
+        const ref = asRecord(m.spec?.managedSecretReference);
+        if (typeof ref?.secretName === "string") {
+          const ns = typeof ref.secretNamespace === "string" ? ref.secretNamespace : metaNs;
+          produced.push({ name: ref.secretName, namespace: ns });
+        }
+        break;
+      }
+      case "Certificate": {
+        // cert-manager — materializes the keypair into spec.secretName.
+        const secretName = m.spec?.secretName;
+        if (typeof secretName === "string") produced.push({ name: secretName, namespace: metaNs });
+        break;
+      }
+    }
+  }
+  return produced;
+}
+
+/** Collect every non-optional secret reference in a pod spec. */
+function collectSecretRefs(podSpec: Record<string, unknown>): SecretRef[] {
+  const refs: SecretRef[] = [];
+
+  const containers = [
+    ...asArray(podSpec.containers),
+    ...asArray(podSpec.initContainers),
+    ...asArray(podSpec.ephemeralContainers),
+  ];
+  for (const c of containers) {
+    const container = asRecord(c);
+    if (!container) continue;
+    for (const e of asArray(container.envFrom)) {
+      const secretRef = asRecord(asRecord(e)?.secretRef);
+      if (typeof secretRef?.name === "string" && secretRef.optional !== true) {
+        refs.push({ name: secretRef.name, via: "envFrom.secretRef" });
+      }
+    }
+    for (const e of asArray(container.env)) {
+      const keyRef = asRecord(asRecord(asRecord(e)?.valueFrom)?.secretKeyRef);
+      if (typeof keyRef?.name === "string" && keyRef.optional !== true) {
+        refs.push({ name: keyRef.name, via: "env[].valueFrom.secretKeyRef" });
+      }
+    }
+  }
+
+  for (const v of asArray(podSpec.volumes)) {
+    const volume = asRecord(v);
+    if (!volume) continue;
+    const secret = asRecord(volume.secret);
+    if (typeof secret?.secretName === "string" && secret.optional !== true) {
+      refs.push({ name: secret.secretName, via: "volumes[].secret.secretName" });
+    }
+    const projected = asRecord(volume.projected);
+    for (const s of asArray(projected?.sources)) {
+      const source = asRecord(asRecord(s)?.secret);
+      if (typeof source?.name === "string" && source.optional !== true) {
+        refs.push({ name: source.name, via: "volumes[].projected.sources[].secret" });
+      }
+    }
+  }
+
+  for (const p of asArray(podSpec.imagePullSecrets)) {
+    const pull = asRecord(p);
+    if (typeof pull?.name === "string") {
+      refs.push({ name: pull.name, via: "imagePullSecrets" });
+    }
+  }
+
+  return refs;
+}
+
+/** True when a produced Secret satisfies a reference. A side with no
+ * namespace matches any — only two explicit, different namespaces miss. */
+function producerCovers(producer: ProducedSecret, name: string, namespace: string | undefined): boolean {
+  if (producer.name !== name) return false;
+  return producer.namespace === undefined || namespace === undefined || producer.namespace === namespace;
+}
+
+export const wk8503: PostSynthCheck = {
+  id: "WK8503",
+  description:
+    "Workload consumes a Secret nothing in the output produces — produce it (Secret, ExternalSecret, InfisicalSecret, Certificate) or declare its provenance with declareSecret()",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const manifests = allManifests(ctx);
+    const produced = collectProducedSecrets(manifests);
+
+    // Committed ciphertext produces a Secret as surely as a Secret manifest
+    // does — Flux decrypts the emitted sidecar straight into the cluster — so
+    // it joins the producer set, namespace and all. A claim whose file did
+    // not resolve produces nothing: WK8504 reports why, and this check still
+    // fires, which is the point of not treating it as a waiver.
+    for (const claim of resolveEncryptedSecretClaims(ctx)) {
+      if (claim.problems.length > 0) continue;
+      produced.push({ name: claim.declaration.name, namespace: claim.document?.namespace });
+    }
+
+    // The typed waiver: a SecretProvenance declaration covering the name, for
+    // the three kinds whose value genuinely comes from outside this build.
+    const declaredNames = new Set<string>();
+    for (const decl of collectSecretDeclarations(ctx.entities).values()) {
+      if (decl.provenance === "committed-encrypted") continue;
+      declaredNames.add(decl.name);
+    }
+
+    for (const manifest of manifests) {
+      const podSpec = extractPodSpec(manifest);
+      if (!podSpec) continue;
+      const workload = manifest.metadata?.name ?? manifest.kind ?? "workload";
+      const namespace = manifest.metadata?.namespace;
+
+      const reported = new Set<string>();
+      for (const ref of collectSecretRefs(podSpec)) {
+        if (reported.has(ref.name)) continue;
+        if (declaredNames.has(ref.name)) continue;
+        if (produced.some((p) => producerCovers(p, ref.name, namespace))) continue;
+        reported.add(ref.name);
+        diagnostics.push({
+          checkId: "WK8503",
+          severity: "error",
+          message:
+            `${manifest.kind} "${workload}" consumes Secret "${ref.name}" (via ${ref.via}), ` +
+            `but nothing in the build output produces it — the pod will fail at start. ` +
+            `Produce it in this build, or declare its provenance: ` +
+            `declareSecret({ name: "${ref.name}", provenance: "referenced" }).`,
+          entity: workload,
+          lexicon: "k8s",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/wk8504.ts

@@ -0,0 +1,51 @@
+/**
+ * WK8504: committed-encrypted secret declaration does not resolve
+ *
+ * `declareSecret({ provenance: "committed-encrypted", file })` is a claim
+ * about an artifact INSIDE the build, which is what separates it from the
+ * three kinds that promise something outside one. A claim inside the build
+ * should be verified rather than taken on trust, and this is the check that
+ * makes it falsifiable: it fires when the declared file produced no sidecar,
+ * when the emitted document is not a `v1` Secret of the declared name, when
+ * it carries no `sops` block, or when a `data`/`stringData` value is not
+ * `ENC[...]`-shaped.
+ *
+ * That last case is the failure this rule exists for: someone edits
+ * `db-credentials.sops.yaml` by hand, forgets `sops -e`, and commits
+ * plaintext. Before this, nothing in chant would notice.
+ *
+ * It reads `output.files`, not `getPrimaryOutput`. The ciphertext is
+ * deliberately kept out of the primary output — that is what makes applying
+ * an undecrypted Secret structurally impossible — so every other post-synth
+ * check in the lexicon is blind to it by construction, and this one has to
+ * ask for the sidecars explicitly.
+ *
+ * A value is only ever tested for the `ENC[` prefix; the message names the
+ * offending KEY, never what was found there.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { resolveEncryptedSecretClaims } from "./sops-helpers";
+
+export const wk8504: PostSynthCheck = {
+  id: "WK8504",
+  description:
+    "committed-encrypted secret declaration does not resolve — the declared file is missing, is not the named Secret, or is not encrypted",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const claim of resolveEncryptedSecretClaims(ctx)) {
+      for (const problem of claim.problems) {
+        diagnostics.push({
+          checkId: "WK8504",
+          severity: "error",
+          message: `declareSecret("${claim.declaration.name}"): ${problem}`,
+          entity: claim.declaration.name,
+          lexicon: "k8s",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/wk8505.ts

@@ -0,0 +1,63 @@
+/**
+ * WK8505: committed-encrypted secret with no Flux decryption wiring
+ *
+ * Flux is the thing that actually decrypts a committed-encrypted secret's
+ * sidecar, via `spec.decryption` on the reconciling `Kustomization`
+ * (`FluxAppFor`'s `decryption` option). Nothing forces the two calls to be
+ * wired together: `declareSecret({ provenance: "committed-encrypted" })` and
+ * `FluxAppFor(...)` are independent, so it is easy to add the ciphertext
+ * without adding the wiring — the build succeeds, WK8504 passes because the
+ * file resolves cleanly, and Flux still applies the sidecar as raw
+ * `ENC[...]` bytes because nothing told it to decrypt first.
+ *
+ * Warning, not error. The reference project shape (`examples/flux-apps`)
+ * runs the workload build and the Flux build as separate `chant build`
+ * invocations, so "no Kustomization in THIS build sets spec.decryption" can
+ * mean "wired up in the other build" as easily as "forgotten" — the design
+ * doc's §4 explains why no path-to-build-target join exists to tell those
+ * apart. Promote to error if that join ever becomes available.
+ *
+ * Fires only on claims that actually resolved (`problems.length === 0`, via
+ * `resolveEncryptedSecretClaims`), not on every raw declaration. An
+ * unresolved declaration is already WK8504's job at error severity; firing
+ * this warning on top of it would report a Flux wiring gap for a Secret the
+ * build has not confirmed exists.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { allManifests, manifestsOfKind } from "./argo-helpers";
+import type { K8sManifest } from "./k8s-helpers";
+import { resolveEncryptedSecretClaims } from "./sops-helpers";
+
+/** Flux Kustomizations only — the kustomize.config.k8s.io kind shares the name. */
+function fluxKustomizations(manifests: K8sManifest[]): K8sManifest[] {
+  return manifestsOfKind(manifests, "Kustomization").filter((m) => {
+    const apiVersion = m.apiVersion;
+    return typeof apiVersion !== "string" || apiVersion.startsWith("kustomize.toolkit.fluxcd.io/");
+  });
+}
+
+export const wk8505: PostSynthCheck = {
+  id: "WK8505",
+  description:
+    "committed-encrypted secret with no Flux decryption wiring — add decryption: 'sops' to the FluxAppFor reconciling the path that carries it",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const kustomizations = fluxKustomizations(allManifests(ctx));
+    if (kustomizations.length === 0) return [];
+    if (kustomizations.some((k) => k.spec?.decryption !== undefined)) return [];
+
+    const resolved = resolveEncryptedSecretClaims(ctx).filter((claim) => claim.problems.length === 0);
+
+    return resolved.map((claim) => ({
+      checkId: "WK8505",
+      severity: "warning",
+      message:
+        `declareSecret("${claim.declaration.name}") is committed-encrypted, but no Flux Kustomization ` +
+        `in this build sets spec.decryption — Flux will apply "${claim.filename}" without decrypting it. ` +
+        `Add decryption: "sops" to the FluxAppFor reconciling the path that carries it, or ignore if that ` +
+        `Kustomization is declared in a different build.`,
+      entity: claim.declaration.name,
+      lexicon: "k8s",
+    }));
+  },
+};

package/dist/secret-labels.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The `generated-once` marker label (chant #1830, epic #1365 decision 5).
+ *
+ * `k8sSecretStore` (./secret-store.ts) stamps this label onto every Secret it
+ * mints, next to the ownership marker. Both k8s prune paths key on it:
+ *
+ * - the apply-path prune (`applyManifest`'s owned-only sweep,
+ *   op/activities/kubectl.ts) excludes a labeled Secret from the prunable set
+ *   and reports it `retained` instead of deleting it;
+ * - env teardown (./teardown.ts `executeTeardown`) reports the same `retained`
+ *   outcome for it, loudly, and never deletes it.
+ *
+ * The rationale is the materialization contract: the stored bytes are the ONLY
+ * copy of material chant never held, so no sweep may destroy them. Deletion is
+ * an explicit human act — `kubectl delete secret <name>`, or a future gated
+ * op — never a side effect of "no longer declared".
+ *
+ * Dependency-light on purpose: no client import, so the constants are usable
+ * from the build path, the prune paths, and the docs/tests alike.
+ */
+/** The label key a generated-once Secret carries. */
+export declare const GENERATED_ONCE_LABEL_KEY = "chant.intentius.io/generated-once";
+/** The label value `k8sSecretStore` stamps. */
+export declare const GENERATED_ONCE_LABEL_VALUE = "true";
+/**
+ * True when a live object's labels mark it generated-once. Any non-empty
+ * value counts: the label's presence is the claim, and a sweep must err on
+ * the side of keeping.
+ */
+export declare function isGeneratedOnce(labels: Record<string, unknown> | undefined): boolean;
+//# sourceMappingURL=secret-labels.d.ts.map

package/dist/secret-labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-labels.d.ts","sourceRoot":"","sources":["../src/secret-labels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qDAAqD;AACrD,eAAO,MAAM,wBAAwB,sCAAsC,CAAC;AAE5E,+CAA+C;AAC/C,eAAO,MAAM,0BAA0B,SAAS,CAAC;AAEjD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,OAAO,CAGpF"}

package/dist/secret-store.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 { SecretStoreAdapter } from "@intentius/chant/secret-materialization";
+import { type EnsureSecretInput, type EnsureSecretOutput } from "@intentius/chant/components/verbs/ensure-secret";
+import type { Capability } from "@intentius/chant/components/capability";
+import { type OwnershipMarker } from "@intentius/chant/ownership";
+import type { K8sClient } from "@intentius/chant-k8s-client";
+import { type K8sConnector } from "./api/connect.js";
+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 declare function k8sSecretStore(namespace: string, client?: K8sClient, options?: K8sSecretStoreOptions): SecretStoreAdapter;
+/**
+ * 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 declare function k8sEnsureSecretCapability(namespace: string, client?: K8sClient, options?: K8sSecretStoreOptions): Capability<EnsureSecretInput, EnsureSecretOutput>;
+//# sourceMappingURL=secret-store.d.ts.map

package/dist/secret-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-store.d.ts","sourceRoot":"","sources":["../src/secret-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAEV,kBAAkB,EAEnB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,iDAAiD,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACzE,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAKvE,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,SAAS,EAClB,OAAO,GAAE,qBAA0B,GAClC,kBAAkB,CA8DpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,SAAS,EAClB,OAAO,GAAE,qBAA0B,GAClC,UAAU,CAAC,iBAAiB,EAAE,kBAAkB,CAAC,CAEnD"}

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AA8MlG;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UA2K3B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AA+MlG;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAyM3B,CAAC"}

package/dist/sops/encrypted-secret-file.d.ts

@@ -0,0 +1,52 @@
+import { type Declarable } from "@intentius/chant/declarable";
+import type { BuildRootContext, BuildRootContribution } from "@intentius/chant/lexicon";
+import { 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.js";
+/** 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 declare function validateEncryptedSecretDocument(text: string, declared: {
+    name: string;
+    file: string;
+}): {
+    problems: string[];
+    document?: EncryptedSecretDocument;
+};
+/** 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 declare function resolveEncryptedSecrets(options: ResolveEncryptedSecretsOptions): Map<string, Declarable>;
+/** Every committed-encrypted declaration in an entity map, keyed by entity name. */
+export declare function committedEncryptedDeclarations(entities: ReadonlyMap<string, Declarable>): Map<string, CommittedEncryptedSecretDeclaration>;
+/**
+ * The `buildRoots` contribution: one entity per committed-encrypted
+ * declaration, holding the file's bytes verbatim.
+ */
+export declare function encryptedSecretBuildRoot(ctx: BuildRootContext): Promise<BuildRootContribution>;
+//# sourceMappingURL=encrypted-secret-file.d.ts.map

package/dist/sops/encrypted-secret-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encrypted-secret-file.d.ts","sourceRoot":"","sources":["../../src/sops/encrypted-secret-file.ts"],"names":[],"mappings":"AAuCA,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAQjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACxF,OAAO,EAGL,KAAK,mCAAmC,EACzC,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACL,4BAA4B,EAC5B,0BAA0B,EAC1B,8BAA8B,EAC9B,2BAA2B,EAC3B,eAAe,EACf,KAAK,yBAAyB,GAC/B,MAAM,UAAU,CAAC;AAElB,kEAAkE;AAClE,MAAM,WAAW,uBAAuB;IACtC,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,uBAAuB,CAAA;CAAE,CAiF5D;AAQD,wFAAwF;AACxF,MAAM,WAAW,8BAA8B;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,mCAAmC,CAAC,CAAC;IACvE,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,8BAA8B,GACtC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAmDzB;AAED,oFAAoF;AACpF,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,GACxC,GAAG,CAAC,MAAM,EAAE,mCAAmC,CAAC,CAMlD;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAIpG"}

package/dist/sops/entity.d.ts

@@ -0,0 +1,31 @@
+import type { Declarable } from "@intentius/chant/declarable";
+/** Marks an entity whose bytes are committed ciphertext, emitted verbatim. */
+export declare const ENCRYPTED_SECRET_FILE_MARKER: unique symbol;
+/**
+ * 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 declare const ENCRYPTED_SECRET_FILE_TYPE = "K8s::Sops::EncryptedSecretFile";
+/** Entity-map key prefix, colon-separated so it cannot collide with a TS export name. */
+export declare 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 declare function isEncryptedSecretFileEntity(entity: Declarable): entity is EncryptedSecretFileEntity;
+/** The sidecar filename a declaration's file is emitted under. */
+export declare function sidecarFilename(file: string): string;
+//# sourceMappingURL=entity.d.ts.map

package/dist/sops/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../src/sops/entity.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,8EAA8E;AAC9E,eAAO,MAAM,4BAA4B,eAA8C,CAAC;AAExF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,mCAAmC,CAAC;AAE3E,yFAAyF;AACzF,eAAO,MAAM,8BAA8B,UAAU,CAAC;AAEtD,MAAM,WAAW,yBAA0B,SAAQ,UAAU;IAC3D,QAAQ,CAAC,UAAU,EAAE,OAAO,0BAA0B,CAAC;IACvD,QAAQ,CAAC,CAAC,4BAA4B,CAAC,EAAE,IAAI,CAAC;IAC9C,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,IAAI,yBAAyB,CAEnG;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/teardown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"teardown.d.ts","sourceRoot":"","sources":["../src/teardown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EAGlB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAIpC,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAIvE,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,eAAe,CAAC;CACzB;AAoBD;;;GAGG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,YAAkC,GAC1C,OAAO,CAAC,mBAAmB,CAAC,CA4D9B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,kBAAkB,GAAG;IAAE,UAAU,EAAE,iBAAiB,EAAE,CAAA;CAAE,EACjE,OAAO,GAAE,YAAkC,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CAe5B"}
+{"version":3,"file":"teardown.d.ts","sourceRoot":"","sources":["../src/teardown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EAGlB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAIpC,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAKvE,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,eAAe,CAAC;CACzB;AAoBD;;;GAGG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,YAAkC,GAC1C,OAAO,CAAC,mBAAmB,CAAC,CA4D9B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,kBAAkB,GAAG;IAAE,UAAU,EAAE,iBAAiB,EAAE,CAAA;CAAE,EACjE,OAAO,GAAE,YAAkC,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CAe5B"}