@intentius/chant 0.124.28 → 0.124.30

package/dist/lifecycle/mixed-environment.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Whether an environment runs a mix of releases, and the lines that settle
+ * it (#4035). Derived when read, from the environment's release ledger and
+ * its deploy outcomes (./deploy-outcome.ts); nothing here is written.
+ *
+ * Two things make an environment mixed:
+ *
+ * - a component is unsettled: the newest promote, rollback or redeploy that
+ *   named it left it `failed` or `gated`, and the release ledger has no
+ *   record of it newer than that run, so what it runs is not known;
+ * - the latest records of its components name more than one release, a
+ *   record of no release counting as one value, and at least one names a
+ *   release.
+ *
+ * The ledger already says per component what deployed, and with which
+ * release, so the second needs no record of its own. Only the first needs
+ * the outcome: a failed deploy writes no release record, by design, so the
+ * ledger alone can't tell a component that failed partway from one that was
+ * never touched.
+ */
+import type { ReleaseRecord } from "./release-ledger.js";
+import type { DeployOutcome } from "./deploy-outcome.js";
+/** One component of a mixed environment. */
+export interface MixedComponent {
+    component: string;
+    /** The digest the release ledger records the component running, or null when it has no record in the environment. */
+    digest: string | null;
+    /** The release that record names, or null. */
+    releaseDigest: string | null;
+    releaseLabel: string | null;
+    /** `settled` when the ledger's record is what it runs; `failed` or `gated` when the newest run that named it left it so. */
+    state: "settled" | "failed" | "gated";
+    /** For an unsettled component, the run that left it so and what that run was deploying. Null when settled. */
+    attempt: {
+        verb: DeployOutcome["verb"];
+        runId: string;
+        timestamp: string;
+        digest: string;
+        releaseDigest: string | null;
+        releaseLabel: string | null;
+    } | null;
+}
+export interface MixedEnvironment {
+    /** Every component the ledger records or a run left unsettled, sorted by name. */
+    components: MixedComponent[];
+    /** `chant components redeploy <env> --component <c>` for each unsettled component the ledger records, which puts its recorded release back. */
+    redeploy: string[];
+    /** `chant components rollback <env> --release <label|digest>`, naming the release to go back to, or null when there is none to name. */
+    rollback: string | null;
+}
+/** What a reader knows about a release a rollback could go back to. */
+export interface ReleaseCheck {
+    /** Its release file can still be read, so its templates can be deployed. */
+    kept: boolean;
+    /** Its commit is revoked (#4033), so it is refused. */
+    revoked: boolean;
+}
+/**
+ * The components a run left unsettled: for each, the newest outcome naming it
+ * `failed` or `gated` that no release record of it is newer than.
+ */
+export declare function unsettledComponents(records: readonly ReleaseRecord[], outcomes: readonly DeployOutcome[]): Map<string, {
+    outcome: DeployOutcome;
+    state: "failed" | "gated";
+    digest: string;
+    releaseDigest: string | null;
+}>;
+/**
+ * The newest release the environment's ledger names that a rollback can go
+ * back to: not in `exclude`, still kept, and not revoked. With `before`, only
+ * records older than that time count. Null when there is none.
+ */
+export declare function rollbackTarget(input: {
+    records: readonly ReleaseRecord[];
+    exclude: ReadonlySet<string>;
+    before?: string;
+    check: (releaseDigest: string) => Promise<ReleaseCheck>;
+}): Promise<string | null>;
+/** The line that rolls `env` back to a release, by its label when it has one. */
+export declare function releaseRollbackLine(env: string, releaseDigest: string, label: string | null | undefined): string;
+/** The line that redeploys one component's recorded release in `env`. */
+export declare function redeployLine(env: string, component: string): string;
+/**
+ * The environment's mixed state, or null when it runs one release (or no
+ * release at all) and no component is unsettled.
+ */
+export declare function mixedEnvironment(input: {
+    env: string;
+    records: readonly ReleaseRecord[];
+    outcomes: readonly DeployOutcome[];
+    /** A release's label, or undefined. */
+    label: (releaseDigest: string) => Promise<string | undefined>;
+    check: (releaseDigest: string) => Promise<ReleaseCheck>;
+}): Promise<MixedEnvironment | null>;
+//# sourceMappingURL=mixed-environment.d.ts.map

package/dist/lifecycle/mixed-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mixed-environment.d.ts","sourceRoot":"","sources":["../../src/lifecycle/mixed-environment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,qHAAqH;IACrH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4HAA4H;IAC5H,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IACtC,8GAA8G;IAC9G,OAAO,EAAE;QACP,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAC5B,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,GAAG,IAAI,CAAC;CACV;AAED,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,+IAA+I;IAC/I,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wIAAwI;IACxI,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,EAAE,OAAO,CAAC;IACd,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;CAClB;AAWD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,QAAQ,EAAE,SAAS,aAAa,EAAE,GACjC,GAAG,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAiBlH;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE;IAC1C,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACzD,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAczB;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAEhH;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,uCAAuC;IACvC,KAAK,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC9D,KAAK,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACzD,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CA2DnC"}

package/dist/lifecycle/mixed-environment.js

@@ -0,0 +1,154 @@
+/**
+ * Whether an environment runs a mix of releases, and the lines that settle
+ * it (#4035). Derived when read, from the environment's release ledger and
+ * its deploy outcomes (./deploy-outcome.ts); nothing here is written.
+ *
+ * Two things make an environment mixed:
+ *
+ * - a component is unsettled: the newest promote, rollback or redeploy that
+ *   named it left it `failed` or `gated`, and the release ledger has no
+ *   record of it newer than that run, so what it runs is not known;
+ * - the latest records of its components name more than one release, a
+ *   record of no release counting as one value, and at least one names a
+ *   release.
+ *
+ * The ledger already says per component what deployed, and with which
+ * release, so the second needs no record of its own. Only the first needs
+ * the outcome: a failed deploy writes no release record, by design, so the
+ * ledger alone can't tell a component that failed partway from one that was
+ * never touched.
+ */
+function latest(records) {
+    const out = new Map();
+    for (const r of records) {
+        const current = out.get(r.component);
+        if (!current || r.timestamp >= current.timestamp)
+            out.set(r.component, r);
+    }
+    return out;
+}
+/**
+ * The components a run left unsettled: for each, the newest outcome naming it
+ * `failed` or `gated` that no release record of it is newer than.
+ */
+export function unsettledComponents(records, outcomes) {
+    const newest = new Map();
+    for (const outcome of outcomes) {
+        for (const c of outcome.components) {
+            if (c.outcome !== "failed" && c.outcome !== "gated")
+                continue;
+            const seen = newest.get(c.component);
+            if (!seen || outcome.timestamp >= seen.outcome.timestamp) {
+                newest.set(c.component, { outcome, state: c.outcome, digest: c.digest, releaseDigest: c.releaseDigest });
+            }
+        }
+    }
+    const recorded = latest(records);
+    for (const [component, u] of newest) {
+        const r = recorded.get(component);
+        if (r && r.timestamp > u.outcome.timestamp)
+            newest.delete(component);
+    }
+    return newest;
+}
+/**
+ * The newest release the environment's ledger names that a rollback can go
+ * back to: not in `exclude`, still kept, and not revoked. With `before`, only
+ * records older than that time count. Null when there is none.
+ */
+export async function rollbackTarget(input) {
+    const ordered = input.records
+        .map((r, i) => ({ r, i }))
+        .filter(({ r }) => r.releaseDigest !== undefined && (input.before === undefined || r.timestamp < input.before))
+        .sort((a, b) => (a.r.timestamp === b.r.timestamp ? b.i - a.i : a.r.timestamp < b.r.timestamp ? 1 : -1));
+    const seen = new Set();
+    for (const { r } of ordered) {
+        const digest = r.releaseDigest;
+        if (seen.has(digest) || input.exclude.has(digest))
+            continue;
+        seen.add(digest);
+        const check = await input.check(digest);
+        if (check.kept && !check.revoked)
+            return digest;
+    }
+    return null;
+}
+/** The line that rolls `env` back to a release, by its label when it has one. */
+export function releaseRollbackLine(env, releaseDigest, label) {
+    return `chant components rollback ${env} --release ${label ?? releaseDigest}`;
+}
+/** The line that redeploys one component's recorded release in `env`. */
+export function redeployLine(env, component) {
+    return `chant components redeploy ${env} --component ${component}`;
+}
+/**
+ * The environment's mixed state, or null when it runs one release (or no
+ * release at all) and no component is unsettled.
+ */
+export async function mixedEnvironment(input) {
+    const { env, records } = input;
+    const recorded = latest(records);
+    const unsettled = unsettledComponents(records, input.outcomes);
+    const releases = new Set([...recorded.values()].map((r) => r.releaseDigest ?? null));
+    const divergent = releases.size > 1 && [...releases].some((d) => d !== null);
+    if (unsettled.size === 0 && !divergent)
+        return null;
+    const labelOf = async (digest) => (digest ? ((await input.label(digest)) ?? null) : null);
+    const names = [...new Set([...recorded.keys(), ...unsettled.keys()])].sort();
+    const components = [];
+    for (const component of names) {
+        const r = recorded.get(component);
+        const u = unsettled.get(component);
+        components.push({
+            component,
+            digest: r?.digest ?? null,
+            releaseDigest: r?.releaseDigest ?? null,
+            releaseLabel: await labelOf(r?.releaseDigest),
+            state: u ? u.state : "settled",
+            attempt: u
+                ? {
+                    verb: u.outcome.verb,
+                    runId: u.outcome.runId,
+                    timestamp: u.outcome.timestamp,
+                    digest: u.digest,
+                    releaseDigest: u.releaseDigest,
+                    releaseLabel: await labelOf(u.releaseDigest),
+                }
+                : null,
+        });
+    }
+    // The release the environment was moving to is not one to go back to: the
+    // one a run left components unsettled on, else, of the releases its
+    // components run, the one that reached the environment last.
+    const exclude = new Set();
+    if (unsettled.size > 0) {
+        for (const u of unsettled.values())
+            if (u.releaseDigest)
+                exclude.add(u.releaseDigest);
+    }
+    else {
+        const firstSeen = new Map();
+        for (const r of records) {
+            if (r.releaseDigest === undefined)
+                continue;
+            const seen = firstSeen.get(r.releaseDigest);
+            if (seen === undefined || r.timestamp < seen)
+                firstSeen.set(r.releaseDigest, r.timestamp);
+        }
+        let arrived;
+        for (const d of releases) {
+            if (d === null)
+                continue;
+            if (arrived === undefined || firstSeen.get(d) > firstSeen.get(arrived))
+                arrived = d;
+        }
+        if (arrived !== undefined)
+            exclude.add(arrived);
+    }
+    const target = await rollbackTarget({ records, exclude, check: input.check });
+    return {
+        components,
+        redeploy: components.filter((c) => c.state !== "settled" && c.digest !== null).map((c) => redeployLine(env, c.component)),
+        rollback: target ? releaseRollbackLine(env, target, await labelOf(target)) : null,
+    };
+}

package/dist/lifecycle/publish-attachments.d.ts

@@ -0,0 +1,79 @@
+/**
+ * What a publish attaches to what it publishes (#4049): an SBOM and the
+ * release's provenance statement.
+ *
+ * The provenance statement is an in-toto Statement v1 whose predicate
+ * (`https://intentius.io/chant/release/v1`) names the release, its commit,
+ * and the cut that signed it, with the cut's ssh signature in the
+ * `chant-release` namespace. Anyone holding the repository checks that
+ * signature offline with `chant release verify`, against
+ * `.chant/allowed_signers` at the release's commit. The predicate also says
+ * whether the run had an OIDC token: in CI, the provenance a registry records
+ * (npm's `--provenance`) is signed with it, and from a workstation the
+ * release's signature is the only provenance there is.
+ *
+ * The SBOM is an SPDX or CycloneDX JSON document. A target attaches the file
+ * its declaration's `sbom` names; with none named, the OCI and forge targets
+ * write one from the member's `package-lock.json` or `pom.xml` with the
+ * hermetic writer `generate-sbom` uses (../components/verbs/bom-writer.ts),
+ * dated with the cut's time, so a publish run again writes the same bytes.
+ * `sbom: false` publishes without one. The npm target carries its SBOM in
+ * each package instead, since a registry keeps no file beside a package
+ * (./publish-npm.ts).
+ *
+ * Both are written as sorted JSON, so the same release attaches the same
+ * bytes on every run, and a resumed stage finds what an earlier run sent.
+ */
+import { type PublishContext } from "./release-publish.js";
+/** The in-toto statement type the provenance statement is. */
+export declare const IN_TOTO_STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
+/** The predicate type of chant's release provenance. */
+export declare const RELEASE_PREDICATE_TYPE = "https://intentius.io/chant/release/v1";
+/** The media type an in-toto statement is attached under. */
+export declare const IN_TOTO_MEDIA_TYPE = "application/vnd.in-toto+json";
+/** The file name the provenance statement is attached under. */
+export declare const PROVENANCE_FILE = "release.intoto.json";
+/** The file name of an SBOM chant writes from a lockfile. */
+export declare const GENERATED_SBOM_FILE = "sbom.spdx.json";
+/** The names an npm package's own SBOM is looked for under, at its root, when the declaration names none. */
+export declare const PACKAGE_SBOM_FILES: readonly ["sbom.spdx.json", "sbom.cdx.json", "sbom.cyclonedx.json"];
+/** One file attached to what a target publishes. */
+export interface Attachment {
+    kind: "sbom" | "provenance";
+    /** The file name it is attached under. */
+    name: string;
+    mediaType: string;
+    bytes: Uint8Array;
+    digest: string;
+}
+/**
+ * The provenance statement for `subjects`, the digests of what the target
+ * publishes. Every value in it comes from the release, its cut and the run's
+ * OIDC check, never from the clock, so it is the same bytes on every run.
+ */
+export declare function releaseProvenance(ctx: PublishContext, subjects: ReadonlyArray<{
+    name: string;
+    digest: string;
+}>): Attachment;
+/** The media type of an SBOM document, or null when `bytes` is neither SPDX nor CycloneDX JSON. */
+export declare function sbomMediaType(bytes: Uint8Array): string | null;
+/**
+ * The SBOM a target attaches, for an OCI image or a forge release: the file
+ * `declared` names (relative to the member, checked against the release's
+ * digest when the release records it), else one written from the member's
+ * lockfile for `subject`. Null when `declared` is `false`. Throws
+ * `publish-sbom-missing` when there is neither.
+ */
+export declare function memberSbom(ctx: PublishContext, declared: string | false | undefined, subject: string, target: string): Attachment | null;
+/**
+ * The SBOM an npm package carries at its root: the file `declared` names, else
+ * the first of {@link PACKAGE_SBOM_FILES} it holds, in a package directory or
+ * under `package/` in a packed `.tgz`. Null when `declared` is `false`.
+ * Throws `publish-sbom-missing` when the package has none, and
+ * `publish-sbom-invalid` when it is not SPDX or CycloneDX JSON.
+ */
+export declare function packageSbom(abs: string, isDirectory: boolean, path: string, name: string, declared: string | false | undefined): {
+    file: string;
+    digest: string;
+} | null;
+//# sourceMappingURL=publish-attachments.d.ts.map

package/dist/lifecycle/publish-attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-attachments.d.ts","sourceRoot":"","sources":["../../src/lifecycle/publish-attachments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAUH,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAG5E,8DAA8D;AAC9D,eAAO,MAAM,sBAAsB,oCAAoC,CAAC;AACxE,wDAAwD;AACxD,eAAO,MAAM,sBAAsB,0CAA0C,CAAC;AAC9E,6DAA6D;AAC7D,eAAO,MAAM,kBAAkB,iCAAiC,CAAC;AACjE,gEAAgE;AAChE,eAAO,MAAM,eAAe,wBAAwB,CAAC;AACrD,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AACpD,6GAA6G;AAC7G,eAAO,MAAM,kBAAkB,YAAI,gBAAgB,EAAE,eAAe,EAAE,qBAAqB,CAAU,CAAC;AAEtG,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC;IAC5B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,UAAU,CAgB5H;AAED,mGAAmG;AACnG,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAW9D;AAyBD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA2BxI;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA2BxK"}

package/dist/lifecycle/publish-attachments.js

@@ -0,0 +1,179 @@
+/**
+ * What a publish attaches to what it publishes (#4049): an SBOM and the
+ * release's provenance statement.
+ *
+ * The provenance statement is an in-toto Statement v1 whose predicate
+ * (`https://intentius.io/chant/release/v1`) names the release, its commit,
+ * and the cut that signed it, with the cut's ssh signature in the
+ * `chant-release` namespace. Anyone holding the repository checks that
+ * signature offline with `chant release verify`, against
+ * `.chant/allowed_signers` at the release's commit. The predicate also says
+ * whether the run had an OIDC token: in CI, the provenance a registry records
+ * (npm's `--provenance`) is signed with it, and from a workstation the
+ * release's signature is the only provenance there is.
+ *
+ * The SBOM is an SPDX or CycloneDX JSON document. A target attaches the file
+ * its declaration's `sbom` names; with none named, the OCI and forge targets
+ * write one from the member's `package-lock.json` or `pom.xml` with the
+ * hermetic writer `generate-sbom` uses (../components/verbs/bom-writer.ts),
+ * dated with the cut's time, so a publish run again writes the same bytes.
+ * `sbom: false` publishes without one. The npm target carries its SBOM in
+ * each package instead, since a registry keeps no file beside a package
+ * (./publish-npm.ts).
+ *
+ * Both are written as sorted JSON, so the same release attaches the same
+ * bytes on every run, and a resumed stage finds what an earlier run sent.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { sortedJsonReplacer } from "../utils.js";
+import { writeBom } from "../components/verbs/bom-writer.js";
+import { parseNpmPackageLock, parsePomXml } from "../components/verbs/lockfile-sbom-generator.js";
+import { SBOM_MEDIA_TYPES } from "../components/verbs/sbom-generator.js";
+import { bytesDigest, checkReleaseDigest, memberFile } from "./publish-targets.js";
+import { PublishTargetError } from "./release-publish.js";
+import { RELEASE_SEAL_NAMESPACE } from "../workspace/identity-gate-rule.js";
+/** The in-toto statement type the provenance statement is. */
+export const IN_TOTO_STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
+/** The predicate type of chant's release provenance. */
+export const RELEASE_PREDICATE_TYPE = "https://intentius.io/chant/release/v1";
+/** The media type an in-toto statement is attached under. */
+export const IN_TOTO_MEDIA_TYPE = "application/vnd.in-toto+json";
+/** The file name the provenance statement is attached under. */
+export const PROVENANCE_FILE = "release.intoto.json";
+/** The file name of an SBOM chant writes from a lockfile. */
+export const GENERATED_SBOM_FILE = "sbom.spdx.json";
+/** The names an npm package's own SBOM is looked for under, at its root, when the declaration names none. */
+export const PACKAGE_SBOM_FILES = ["sbom.spdx.json", "sbom.cdx.json", "sbom.cyclonedx.json"];
+const json = (value) => new Uint8Array(Buffer.from(`${JSON.stringify(value, sortedJsonReplacer, 2)}\n`, "utf-8"));
+const attachment = (kind, name, mediaType, bytes) => ({ kind, name, mediaType, bytes, digest: bytesDigest(bytes) });
+/**
+ * The provenance statement for `subjects`, the digests of what the target
+ * publishes. Every value in it comes from the release, its cut and the run's
+ * OIDC check, never from the clock, so it is the same bytes on every run.
+ */
+export function releaseProvenance(ctx, subjects) {
+    const cut = ctx.cut ?? null;
+    const statement = {
+        _type: IN_TOTO_STATEMENT_TYPE,
+        subject: subjects.map((s) => ({ name: s.name, digest: { [s.digest.split(":")[0] ?? "sha256"]: s.digest.split(":")[1] ?? s.digest } })),
+        predicateType: RELEASE_PREDICATE_TYPE,
+        predicate: {
+            releaseDigest: ctx.release.releaseDigest,
+            label: ctx.label,
+            member: ctx.release.member,
+            commit: ctx.release.commit,
+            cut: cut ? { actor: cut.actor, label: cut.label, timestamp: cut.timestamp, runId: cut.runId, signature: cut.signature, namespace: RELEASE_SEAL_NAMESPACE } : null,
+            provenance: ctx.provenance.oidc ? { kind: "oidc", ci: ctx.provenance.ci } : { kind: "signature", ci: ctx.provenance.ci },
+        },
+    };
+    return attachment("provenance", PROVENANCE_FILE, IN_TOTO_MEDIA_TYPE, json(statement));
+}
+/** The media type of an SBOM document, or null when `bytes` is neither SPDX nor CycloneDX JSON. */
+export function sbomMediaType(bytes) {
+    let doc;
+    try {
+        doc = JSON.parse(Buffer.from(bytes).toString("utf-8"));
+    }
+    catch {
+        return null;
+    }
+    if (!doc || typeof doc !== "object")
+        return null;
+    if (typeof doc.spdxVersion === "string")
+        return SBOM_MEDIA_TYPES.spdx;
+    if (doc.bomFormat === "CycloneDX")
+        return SBOM_MEDIA_TYPES.cyclonedx;
+    return null;
+}
+function invalid(where) {
+    return new PublishTargetError("publish-sbom-invalid", `${where} is not an SPDX or CycloneDX JSON document`, "Point sbom at the SPDX or CycloneDX JSON the build writes.");
+}
+/** The lockfile nearest the member: `package-lock.json` or `pom.xml` in `cwd` or a directory above it inside its repository (only `cwd` outside one). */
+function nearestLockfile(cwd) {
+    let top = null;
+    try {
+        top = realpathSync(execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim());
+    }
+    catch {
+        top = null;
+    }
+    let dir = realpathSync(cwd);
+    for (;;) {
+        for (const [kind, file] of [["npm", "package-lock.json"], ["maven", "pom.xml"]]) {
+            if (existsSync(join(dir, file)))
+                return { kind, path: join(dir, file) };
+        }
+        const up = dirname(dir);
+        if (top === null || dir === top || up === dir || !up.startsWith(top))
+            return null;
+        dir = up;
+    }
+}
+/**
+ * The SBOM a target attaches, for an OCI image or a forge release: the file
+ * `declared` names (relative to the member, checked against the release's
+ * digest when the release records it), else one written from the member's
+ * lockfile for `subject`. Null when `declared` is `false`. Throws
+ * `publish-sbom-missing` when there is neither.
+ */
+export function memberSbom(ctx, declared, subject, target) {
+    if (declared === false)
+        return null;
+    if (declared !== undefined) {
+        const abs = memberFile(ctx.cwd, declared);
+        const bytes = new Uint8Array(readFileSync(abs));
+        checkReleaseDigest(ctx.release, "asset", ctx.cwd, declared, [bytesDigest(bytes)]);
+        const mediaType = sbomMediaType(bytes);
+        if (!mediaType)
+            throw invalid(declared);
+        return attachment("sbom", declared.split("/").pop() ?? declared, mediaType, bytes);
+    }
+    const lock = nearestLockfile(ctx.cwd);
+    if (!lock) {
+        throw new PublishTargetError("publish-sbom-missing", `${target} attaches an SBOM to what it publishes, and its declaration names none and there is no package-lock.json or pom.xml in ${ctx.cwd} or above it to write one from`, "Set sbom in the declaration to the SPDX or CycloneDX file the build writes, or sbom: false to publish without one.");
+    }
+    const content = readFileSync(lock.path, "utf-8");
+    const packages = lock.kind === "npm" ? parseNpmPackageLock(content) : parsePomXml(content);
+    const at = new Date(ctx.cut?.timestamp ?? 0);
+    const doc = writeBom("spdx", { subjectName: subject, subjectId: ctx.release.releaseDigest, packages, generator: `chant-lockfile-sbom/${lock.kind === "npm" ? "package-lock.json" : "pom.xml"}` }, () => (Number.isNaN(at.getTime()) ? new Date(0) : at));
+    return attachment("sbom", GENERATED_SBOM_FILE, doc.mediaType, new Uint8Array(Buffer.from(doc.bytes, "utf-8")));
+}
+/**
+ * The SBOM an npm package carries at its root: the file `declared` names, else
+ * the first of {@link PACKAGE_SBOM_FILES} it holds, in a package directory or
+ * under `package/` in a packed `.tgz`. Null when `declared` is `false`.
+ * Throws `publish-sbom-missing` when the package has none, and
+ * `publish-sbom-invalid` when it is not SPDX or CycloneDX JSON.
+ */
+export function packageSbom(abs, isDirectory, path, name, declared) {
+    if (declared === false)
+        return null;
+    const candidates = declared !== undefined ? [declared] : [...PACKAGE_SBOM_FILES];
+    let listed = null;
+    if (!isDirectory) {
+        try {
+            listed = new Set(execFileSync("tar", ["-tzf", abs], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).split("\n").map((l) => l.trim()));
+        }
+        catch {
+            listed = new Set();
+        }
+    }
+    for (const file of candidates) {
+        let bytes = null;
+        if (isDirectory) {
+            if (existsSync(join(abs, file)))
+                bytes = new Uint8Array(readFileSync(join(abs, file)));
+        }
+        else if (listed.has(`package/${file}`)) {
+            bytes = new Uint8Array(execFileSync("tar", ["-xzOf", abs, `package/${file}`], { stdio: ["ignore", "pipe", "ignore"] }));
+        }
+        if (bytes === null)
+            continue;
+        if (!sbomMediaType(bytes))
+            throw invalid(`${file} in ${path}`);
+        return { file, digest: bytesDigest(bytes) };
+    }
+    throw new PublishTargetError("publish-sbom-missing", `${name} (${path}) carries no SBOM: npm keeps no file beside a package, so its SBOM goes in it, and ${declared !== undefined ? declared : `none of ${PACKAGE_SBOM_FILES.join(", ")}`} is at its root`, `Write one into the package before it is packed, such as npm sbom --sbom-format spdx > ${path}/sbom.spdx.json, and keep it in the package's files; or set sbom: false to publish without one.`);
+}

package/dist/lifecycle/publish-credentials.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Credentials for publish targets (#4047), and the redactor every line a
+ * publish prints goes through.
+ *
+ * A target reads its credential from the environment of the run, by a name
+ * the declaration gives or the target's default, so a workstation sets it in
+ * its shell and CI in the job's secrets. chant never writes a credential to
+ * `chant/lifecycle`, to a file it keeps, or to its output: the value is held
+ * in memory for the requests that need it, and every line a target prints,
+ * and every error it throws, passes through {@link Redactor.redact} first.
+ *
+ * The redactor masks the value of each credential a target read, the values
+ * of the environment variables CI and registries use for tokens
+ * ({@link TOKEN_ENV_VARS}), and the token forms npm and HTTP headers write
+ * (`_authToken=...`, `Authorization: Bearer ...`).
+ */
+/** Environment variables that hold a token in CI or for a registry. Their values are masked in all publish output. */
+export declare const TOKEN_ENV_VARS: readonly ["NODE_AUTH_TOKEN", "NPM_TOKEN", "NPM_ID_TOKEN", "SIGSTORE_ID_TOKEN", "ACTIONS_ID_TOKEN_REQUEST_TOKEN", "ACTIONS_RUNTIME_TOKEN", "GITHUB_TOKEN", "GH_TOKEN", "GITLAB_TOKEN", "CI_JOB_TOKEN", "FORGEJO_TOKEN", "GITEA_TOKEN", "OCI_PASSWORD", "DOCKER_PASSWORD"];
+/** What a masked value is replaced with. */
+export declare const REDACTED = "[redacted]";
+/** Masks credentials in text a publish prints. */
+export interface Redactor {
+    /** Add a value to mask. Values shorter than 4 characters are not masked, since they would mask ordinary text. */
+    add(value: string | undefined | null): void;
+    redact(text: string): string;
+}
+/** A redactor that masks the token variables of `env` and every value added to it later. */
+export declare function createRedactor(env?: NodeJS.ProcessEnv, names?: readonly string[]): Redactor;
+/** A credential a target read, and the variable it came from. The value is never printed. */
+export interface Credential {
+    value: string;
+    /** The environment variable, or `docker config` for one read from the docker config file. */
+    from: string;
+}
+/** The first of `names` set in `env`, added to `redactor`, or null. */
+export declare function readCredential(env: NodeJS.ProcessEnv, names: readonly string[], redactor: Redactor): Credential | null;
+//# sourceMappingURL=publish-credentials.d.ts.map

package/dist/lifecycle/publish-credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-credentials.d.ts","sourceRoot":"","sources":["../../src/lifecycle/publish-credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,sHAAsH;AACtH,eAAO,MAAM,cAAc,YACzB,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,gCAAgC,EAChC,uBAAuB,EACvB,cAAc,EACd,UAAU,EACV,cAAc,EACd,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,iBAAiB,CACT,CAAC;AAEX,4CAA4C;AAC5C,eAAO,MAAM,QAAQ,eAAe,CAAC;AAErC,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,iHAAiH;IACjH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC;IAC5C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9B;AAED,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAe,EAAE,KAAK,GAAE,SAAS,MAAM,EAAO,GAAG,QAAQ,CAkBnG;AAED,6FAA6F;AAC7F,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;CACd;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,GAAG,UAAU,GAAG,IAAI,CAStH"}

package/dist/lifecycle/publish-credentials.js

@@ -0,0 +1,69 @@
+/**
+ * Credentials for publish targets (#4047), and the redactor every line a
+ * publish prints goes through.
+ *
+ * A target reads its credential from the environment of the run, by a name
+ * the declaration gives or the target's default, so a workstation sets it in
+ * its shell and CI in the job's secrets. chant never writes a credential to
+ * `chant/lifecycle`, to a file it keeps, or to its output: the value is held
+ * in memory for the requests that need it, and every line a target prints,
+ * and every error it throws, passes through {@link Redactor.redact} first.
+ *
+ * The redactor masks the value of each credential a target read, the values
+ * of the environment variables CI and registries use for tokens
+ * ({@link TOKEN_ENV_VARS}), and the token forms npm and HTTP headers write
+ * (`_authToken=...`, `Authorization: Bearer ...`).
+ */
+/** Environment variables that hold a token in CI or for a registry. Their values are masked in all publish output. */
+export const TOKEN_ENV_VARS = [
+    "NODE_AUTH_TOKEN",
+    "NPM_TOKEN",
+    "NPM_ID_TOKEN",
+    "SIGSTORE_ID_TOKEN",
+    "ACTIONS_ID_TOKEN_REQUEST_TOKEN",
+    "ACTIONS_RUNTIME_TOKEN",
+    "GITHUB_TOKEN",
+    "GH_TOKEN",
+    "GITLAB_TOKEN",
+    "CI_JOB_TOKEN",
+    "FORGEJO_TOKEN",
+    "GITEA_TOKEN",
+    "OCI_PASSWORD",
+    "DOCKER_PASSWORD",
+];
+/** What a masked value is replaced with. */
+export const REDACTED = "[redacted]";
+/** A redactor that masks the token variables of `env` and every value added to it later. */
+export function createRedactor(env = {}, names = []) {
+    const values = new Set();
+    const add = (v) => {
+        if (typeof v === "string" && v.trim().length >= 4)
+            values.add(v.trim());
+    };
+    for (const name of [...TOKEN_ENV_VARS, ...names])
+        add(env[name]);
+    return {
+        add,
+        redact(text) {
+            let out = text;
+            // Longest first, so a value that contains another is masked whole.
+            for (const v of [...values].sort((a, b) => b.length - a.length))
+                out = out.split(v).join(REDACTED);
+            return out
+                .replace(/(_authToken\s*=\s*)("?)[^\s"]+\2/g, `$1${REDACTED}`)
+                .replace(/(authorization:\s*(?:bearer|basic|token)\s+)[^\s"',]+/gi, `$1${REDACTED}`)
+                .replace(/(private-token:\s*|job-token:\s*)[^\s"',]+/gi, `$1${REDACTED}`);
+        },
+    };
+}
+/** The first of `names` set in `env`, added to `redactor`, or null. */
+export function readCredential(env, names, redactor) {
+    for (const name of names) {
+        const value = env[name];
+        if (typeof value === "string" && value !== "") {
+            redactor.add(value);
+            return { value, from: name };
+        }
+    }
+    return null;
+}