@intentius/chant 0.124.28 → 0.124.29

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;
+}

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

@@ -0,0 +1,97 @@
+/**
+ * Where a member declares its publish targets (#4047): `release.publish` in
+ * its `chant.config.ts`, a list of targets that `chant release publish` runs
+ * in order.
+ *
+ * ```ts
+ * export default {
+ *   release: {
+ *     publish: [
+ *       { type: "npm", packages: ["packages/core", "packages/cli"] },
+ *       { type: "oci", image: "dist/api.oci.tar", repository: "ghcr.io/acme/api", tags: ["{label}"], usernameEnv: "GITHUB_ACTOR", passwordEnv: "GITHUB_TOKEN" },
+ *       { type: "forge", forge: "github", repo: "acme/api", assets: ["dist/api-linux-amd64.tar.gz"] },
+ *     ],
+ *   },
+ * };
+ * ```
+ *
+ * The config is the one at the release's commit: a publish with a target
+ * refuses a checkout whose `HEAD` is another commit. Paths are relative to
+ * the member's directory. A declaration names the environment variables its
+ * credentials are read from, never the credentials.
+ *
+ * This module imports nothing but zod, so ../config.ts can validate the block.
+ */
+import { z } from "zod";
+/** npm: `npm publish` for each package, in the order given. */
+export declare const NpmPublishSchema: z.ZodObject<{
+    type: z.ZodLiteral<"npm">;
+    packages: z.ZodArray<z.ZodString>;
+    registry: z.ZodOptional<z.ZodString>;
+    access: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        restricted: "restricted";
+    }>>;
+    sbom: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+}, z.core.$strict>;
+/** An OCI registry such as GHCR or Docker Hub: the image is pushed by digest, then tagged. */
+export declare const OciPublishSchema: z.ZodObject<{
+    type: z.ZodLiteral<"oci">;
+    image: z.ZodString;
+    repository: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    usernameEnv: z.ZodOptional<z.ZodString>;
+    passwordEnv: z.ZodOptional<z.ZodString>;
+    sbom: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+}, z.core.$strict>;
+/** Release assets on a GitHub, GitLab or Forgejo release named by the release's tag. */
+export declare const ForgePublishSchema: z.ZodObject<{
+    type: z.ZodLiteral<"forge">;
+    forge: z.ZodEnum<{
+        forgejo: "forgejo";
+        github: "github";
+        gitlab: "gitlab";
+    }>;
+    repo: z.ZodString;
+    api: z.ZodOptional<z.ZodString>;
+    assets: z.ZodArray<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+    tokenEnv: z.ZodOptional<z.ZodString>;
+    sbom: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+}, z.core.$strict>;
+export declare const PublishDeclarationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"npm">;
+    packages: z.ZodArray<z.ZodString>;
+    registry: z.ZodOptional<z.ZodString>;
+    access: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        restricted: "restricted";
+    }>>;
+    sbom: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"oci">;
+    image: z.ZodString;
+    repository: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    usernameEnv: z.ZodOptional<z.ZodString>;
+    passwordEnv: z.ZodOptional<z.ZodString>;
+    sbom: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"forge">;
+    forge: z.ZodEnum<{
+        forgejo: "forgejo";
+        github: "github";
+        gitlab: "gitlab";
+    }>;
+    repo: z.ZodString;
+    api: z.ZodOptional<z.ZodString>;
+    assets: z.ZodArray<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+    tokenEnv: z.ZodOptional<z.ZodString>;
+    sbom: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+}, z.core.$strict>], "type">;
+export type NpmPublishDeclaration = z.infer<typeof NpmPublishSchema>;
+export type OciPublishDeclaration = z.infer<typeof OciPublishSchema>;
+export type ForgePublishDeclaration = z.infer<typeof ForgePublishSchema>;
+export type PublishDeclaration = z.infer<typeof PublishDeclarationSchema>;
+//# sourceMappingURL=publish-declaration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"publish-declaration.d.ts","sourceRoot":"","sources":["../../src/lifecycle/publish-declaration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB;;;;;;;;;kBAelB,CAAC;AAEZ,8FAA8F;AAC9F,eAAO,MAAM,gBAAgB;;;;;;;;kBAgBlB,CAAC;AAEZ,wFAAwF;AACxF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;kBAiBpB,CAAC;AAEZ,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAAyF,CAAC;AAE/H,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AACrE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AACrE,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AACzE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/lifecycle/publish-declaration.js

@@ -0,0 +1,83 @@
+/**
+ * Where a member declares its publish targets (#4047): `release.publish` in
+ * its `chant.config.ts`, a list of targets that `chant release publish` runs
+ * in order.
+ *
+ * ```ts
+ * export default {
+ *   release: {
+ *     publish: [
+ *       { type: "npm", packages: ["packages/core", "packages/cli"] },
+ *       { type: "oci", image: "dist/api.oci.tar", repository: "ghcr.io/acme/api", tags: ["{label}"], usernameEnv: "GITHUB_ACTOR", passwordEnv: "GITHUB_TOKEN" },
+ *       { type: "forge", forge: "github", repo: "acme/api", assets: ["dist/api-linux-amd64.tar.gz"] },
+ *     ],
+ *   },
+ * };
+ * ```
+ *
+ * The config is the one at the release's commit: a publish with a target
+ * refuses a checkout whose `HEAD` is another commit. Paths are relative to
+ * the member's directory. A declaration names the environment variables its
+ * credentials are read from, never the credentials.
+ *
+ * This module imports nothing but zod, so ../config.ts can validate the block.
+ */
+import { z } from "zod";
+const envName = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "an environment variable name");
+/** An SBOM file, or `false` to publish without one (#4049). */
+const sbomField = z.union([z.string().min(1), z.literal(false)]);
+/** npm: `npm publish` for each package, in the order given. */
+export const NpmPublishSchema = z
+    .object({
+    type: z.literal("npm"),
+    /** Package directories or packed `.tgz` files, relative to the member, published in this order. */
+    packages: z.array(z.string().min(1)).min(1),
+    /** The registry, else the one npm's own config names. */
+    registry: z.string().url().optional(),
+    access: z.enum(["public", "restricted"]).optional(),
+    /**
+     * The SBOM each package carries at its root (#4049), a file name relative
+     * to the package. Default: the first of `sbom.spdx.json`, `sbom.cdx.json`,
+     * `sbom.cyclonedx.json` it holds. `false` publishes without one.
+     */
+    sbom: sbomField.optional(),
+})
+    .strict();
+/** An OCI registry such as GHCR or Docker Hub: the image is pushed by digest, then tagged. */
+export const OciPublishSchema = z
+    .object({
+    type: z.literal("oci"),
+    /** An OCI image layout, as a directory or a tar file such as `docker save` writes, relative to the member. */
+    image: z.string().min(1),
+    /** `<registry host>/<name>`, such as `ghcr.io/acme/api` or `docker.io/acme/api`. */
+    repository: z.string().min(1),
+    /** Tags to point at the pushed digest. `{label}` is the release's label. Default: `["{label}"]`, or none for a release with no label. */
+    tags: z.array(z.string().min(1)).optional(),
+    /** The variable holding the registry user name. Default `OCI_USERNAME`. */
+    usernameEnv: envName.optional(),
+    /** The variable holding the registry password or token. Default `OCI_PASSWORD`. */
+    passwordEnv: envName.optional(),
+    /** The SBOM pushed as a referrer of the image (#4049), relative to the member. Default: one written from the member's lockfile. `false` publishes without one. */
+    sbom: sbomField.optional(),
+})
+    .strict();
+/** Release assets on a GitHub, GitLab or Forgejo release named by the release's tag. */
+export const ForgePublishSchema = z
+    .object({
+    type: z.literal("forge"),
+    forge: z.enum(["github", "gitlab", "forgejo"]),
+    /** `owner/name` on GitHub and Forgejo; the project path or numeric id on GitLab. */
+    repo: z.string().min(1),
+    /** The API root: default `$GITHUB_API_URL` or `https://api.github.com` on GitHub, `$CI_API_V4_URL` or `https://gitlab.com/api/v4` on GitLab, `$GITHUB_API_URL` on Forgejo, which has no default. */
+    api: z.string().url().optional(),
+    /** Files to attach, relative to the member. */
+    assets: z.array(z.string().min(1)).min(1),
+    /** The forge release's tag. Default: the tag the cut made, `release/<label>` or `release/<member>/<label>`. */
+    tag: z.string().min(1).optional(),
+    /** The variable holding the token. Default `GITHUB_TOKEN`, `GITLAB_TOKEN` (then `CI_JOB_TOKEN`), or `FORGEJO_TOKEN`. */
+    tokenEnv: envName.optional(),
+    /** The SBOM attached to the release (#4049), relative to the member. Default: one written from the member's lockfile. `false` publishes without one. */
+    sbom: sbomField.optional(),
+})
+    .strict();
+export const PublishDeclarationSchema = z.discriminatedUnion("type", [NpmPublishSchema, OciPublishSchema, ForgePublishSchema]);

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

@@ -0,0 +1,53 @@
+/**
+ * The forge release-asset target (#4047): files attached to the release a
+ * GitHub, GitLab or Forgejo repository has for the release's tag, through
+ * each forge's REST API and an injectable `fetch`.
+ *
+ * The tag is the declaration's `tag`, else the one the cut made
+ * (`release/<label>`, or `release/<member>/<label>`), so a release with no
+ * label and no declared tag is refused.
+ *
+ * A publish is two steps (#4048), so a consumer never sees a release with
+ * some of its assets:
+ *
+ * - GitHub and Forgejo stage on a draft release: the draft for the tag that
+ *   `GET /repos/{repo}/releases` lists, else a new one,
+ *   `POST /repos/{repo}/releases` with `draft: true` at the release's commit.
+ *   GitHub uploads each asset to the draft's `upload_url`, Forgejo with a
+ *   multipart `POST /repos/{repo}/releases/{id}/assets`. The reveal publishes
+ *   the draft, `PATCH /repos/{repo}/releases/{id}` with `draft: false`, and
+ *   the forge creates the tag then if it was not pushed.
+ * - GitLab has no draft release, so its stage puts each asset in the
+ *   project's generic package registry (package `release`, version the
+ *   label) and makes no release. The reveal creates the release at the
+ *   commit with a link to each asset, in one `POST /projects/{id}/releases`.
+ *
+ * An asset already on the draft with the same name is left as it is when
+ * its `digest` matches (GitHub), so a stage run again uploads only the rest;
+ * one that differs, or one on a forge that reports no digest (Forgejo), is
+ * refused (`publish-forge-asset-exists`). A release already published for
+ * the tag is refused (`publish-forge-release-published`), since assets
+ * uploaded to it would show one at a time, unless it already holds every
+ * asset, which is what a publish revealed earlier leaves (on Forgejo and
+ * GitLab, which report no digest, by name).
+ *
+ * With the declared assets the stage attaches two more files (#4049): the
+ * SBOM (the file `sbom` names, else `sbom.spdx.json` written from the
+ * member's lockfile) and `release.intoto.json`, the release's provenance
+ * statement over the assets' digests, which carries the cut's signature
+ * (./publish-attachments.ts). They go on the draft with the assets, so
+ * nothing is visible before they are attached.
+ *
+ * The token is read from `tokenEnv`, else `GITHUB_TOKEN`, `GITLAB_TOKEN`
+ * then `CI_JOB_TOKEN`, or `FORGEJO_TOKEN`, and is masked in all output.
+ */
+import type { ForgePublishDeclaration } from "./publish-declaration.js";
+import { type PublishDeps, type PublishTarget } from "./release-publish.js";
+/** The variables a forge's token is read from, in order. */
+export declare function forgeTokenEnv(decl: Pick<ForgePublishDeclaration, "forge" | "tokenEnv">): string[];
+/** The API root a forge is reached at. */
+export declare function forgeApi(decl: Pick<ForgePublishDeclaration, "forge" | "api">, env: NodeJS.ProcessEnv): string | null;
+/** A GitLab generic package version: the label with what GitLab refuses replaced. */
+export declare function gitlabPackageVersion(label: string): string;
+export declare function forgeTarget(decl: ForgePublishDeclaration, deps: PublishDeps): PublishTarget;
+//# sourceMappingURL=publish-forge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"publish-forge.d.ts","sourceRoot":"","sources":["../../src/lifecycle/publish-forge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAMH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAErE,OAAO,EAA2C,KAAK,WAAW,EAAuC,KAAK,aAAa,EAAqB,MAAM,mBAAmB,CAAC;AAE1K,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,uBAAuB,EAAE,OAAO,GAAG,UAAU,CAAC,GAAG,MAAM,EAAE,CAKjG;AAED,0CAA0C;AAC1C,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,uBAAuB,EAAE,OAAO,GAAG,KAAK,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,GAAG,IAAI,CAGpH;AAqID,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,uBAAuB,EAAE,IAAI,EAAE,WAAW,GAAG,aAAa,CA0H3F"}