@intentius/chant 0.124.100 → 0.124.102

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (270) hide show
  1. package/dist/action-pins.d.ts +2 -0
  2. package/dist/action-pins.js +3 -0
  3. package/dist/ci-detect.d.ts +13 -0
  4. package/dist/ci-detect.js +12 -0
  5. package/dist/ci-evidence-claims.d.ts +12 -0
  6. package/dist/ci-evidence-claims.js +12 -0
  7. package/dist/ci-system.d.ts +66 -0
  8. package/dist/ci-system.js +61 -0
  9. package/dist/cli/handlers/build.js +27 -0
  10. package/dist/cli/handlers/release-doctor.d.ts +12 -0
  11. package/dist/cli/handlers/release-doctor.js +118 -0
  12. package/dist/cli/handlers/release-init.d.ts +10 -0
  13. package/dist/cli/handlers/release-init.js +374 -0
  14. package/dist/cli/handlers/release.d.ts +43 -2
  15. package/dist/cli/handlers/release.js +667 -39
  16. package/dist/cli/handlers/run-generate.js +11 -0
  17. package/dist/cli/main.d.ts +2 -0
  18. package/dist/cli/main.js +44 -101
  19. package/dist/cli/parse-args.js +48 -0
  20. package/dist/cli/registry.d.ts +16 -0
  21. package/dist/cli/release-commands/artifacts.d.ts +3 -0
  22. package/dist/cli/release-commands/artifacts.js +14 -0
  23. package/dist/cli/release-commands/candidates.d.ts +3 -0
  24. package/dist/cli/release-commands/candidates.js +16 -0
  25. package/dist/cli/release-commands/changed.d.ts +3 -0
  26. package/dist/cli/release-commands/changed.js +14 -0
  27. package/dist/cli/release-commands/compose.d.ts +3 -0
  28. package/dist/cli/release-commands/compose.js +16 -0
  29. package/dist/cli/release-commands/cut.d.ts +3 -0
  30. package/dist/cli/release-commands/cut.js +50 -0
  31. package/dist/cli/release-commands/doctor.d.ts +3 -0
  32. package/dist/cli/release-commands/doctor.js +14 -0
  33. package/dist/cli/release-commands/export.d.ts +3 -0
  34. package/dist/cli/release-commands/export.js +12 -0
  35. package/dist/cli/release-commands/images.d.ts +3 -0
  36. package/dist/cli/release-commands/images.js +13 -0
  37. package/dist/cli/release-commands/index.d.ts +8 -0
  38. package/dist/cli/release-commands/index.js +52 -0
  39. package/dist/cli/release-commands/init.d.ts +3 -0
  40. package/dist/cli/release-commands/init.js +19 -0
  41. package/dist/cli/release-commands/list.d.ts +3 -0
  42. package/dist/cli/release-commands/list.js +10 -0
  43. package/dist/cli/release-commands/next.d.ts +3 -0
  44. package/dist/cli/release-commands/next.js +13 -0
  45. package/dist/cli/release-commands/publish.d.ts +3 -0
  46. package/dist/cli/release-commands/publish.js +22 -0
  47. package/dist/cli/release-commands/stamp.d.ts +3 -0
  48. package/dist/cli/release-commands/stamp.js +15 -0
  49. package/dist/cli/release-commands/status.d.ts +3 -0
  50. package/dist/cli/release-commands/status.js +17 -0
  51. package/dist/cli/release-commands/tag.d.ts +3 -0
  52. package/dist/cli/release-commands/tag.js +12 -0
  53. package/dist/cli/release-commands/types.d.ts +20 -0
  54. package/dist/cli/release-commands/types.js +1 -0
  55. package/dist/cli/release-commands/verify.d.ts +3 -0
  56. package/dist/cli/release-commands/verify.js +15 -0
  57. package/dist/cli/release-commands/workflow.d.ts +3 -0
  58. package/dist/cli/release-commands/workflow.js +15 -0
  59. package/dist/cloud-lister/index.d.ts +4 -1
  60. package/dist/cloud-lister/index.js +2 -1
  61. package/dist/cloud-lister/kubernetes-components.d.ts +56 -0
  62. package/dist/cloud-lister/kubernetes-components.js +642 -0
  63. package/dist/cloud-lister/kubernetes.d.ts +18 -0
  64. package/dist/cloud-lister/kubernetes.js +26 -1
  65. package/dist/cloud-lister/mask.d.ts +5 -1
  66. package/dist/cloud-lister/mask.js +14 -5
  67. package/dist/components/cli-support.d.ts +1 -1
  68. package/dist/components/cli-support.js +1 -1
  69. package/dist/config-environments.d.ts +8 -1
  70. package/dist/config-environments.js +2 -0
  71. package/dist/config-import.d.ts +1 -1
  72. package/dist/config-import.js +6 -2
  73. package/dist/config-sandbox.d.ts +1 -1
  74. package/dist/config-sandbox.js +3 -3
  75. package/dist/config.d.ts +369 -10
  76. package/dist/config.js +127 -7
  77. package/dist/deep-observation.js +9 -3
  78. package/dist/floor-table.data.js +21 -1
  79. package/dist/forge-remote.d.ts +13 -0
  80. package/dist/forge-remote.js +15 -0
  81. package/dist/lexicon.d.ts +45 -4
  82. package/dist/lifecycle/__fixtures__/package-files.d.ts +32 -0
  83. package/dist/lifecycle/__fixtures__/package-files.js +72 -0
  84. package/dist/lifecycle/__fixtures__/publish-fakes.d.ts +62 -0
  85. package/dist/lifecycle/__fixtures__/publish-fakes.js +275 -3
  86. package/dist/lifecycle/publish-attachments.d.ts +2 -1
  87. package/dist/lifecycle/publish-attachments.js +19 -2
  88. package/dist/lifecycle/publish-cargo.d.ts +99 -0
  89. package/dist/lifecycle/publish-cargo.js +412 -0
  90. package/dist/lifecycle/publish-credentials.d.ts +1 -1
  91. package/dist/lifecycle/publish-credentials.js +13 -0
  92. package/dist/lifecycle/publish-declaration.d.ts +322 -4
  93. package/dist/lifecycle/publish-declaration.js +340 -9
  94. package/dist/lifecycle/publish-forge.d.ts +45 -2
  95. package/dist/lifecycle/publish-forge.js +434 -34
  96. package/dist/lifecycle/publish-git-ssh.d.ts +15 -0
  97. package/dist/lifecycle/publish-git-ssh.js +30 -4
  98. package/dist/lifecycle/publish-github.d.ts +40 -2
  99. package/dist/lifecycle/publish-github.js +100 -3
  100. package/dist/lifecycle/publish-helm.d.ts +83 -0
  101. package/dist/lifecycle/publish-helm.js +452 -0
  102. package/dist/lifecycle/publish-homebrew.d.ts +7 -9
  103. package/dist/lifecycle/publish-homebrew.js +34 -197
  104. package/dist/lifecycle/publish-index.d.ts +141 -0
  105. package/dist/lifecycle/publish-index.js +719 -0
  106. package/dist/lifecycle/publish-marketplace.js +77 -0
  107. package/dist/lifecycle/publish-maven.d.ts +79 -0
  108. package/dist/lifecycle/publish-maven.js +364 -0
  109. package/dist/lifecycle/publish-mcp-registry.d.ts +66 -0
  110. package/dist/lifecycle/publish-mcp-registry.js +305 -0
  111. package/dist/lifecycle/publish-npm.d.ts +27 -1
  112. package/dist/lifecycle/publish-npm.js +216 -3
  113. package/dist/lifecycle/publish-nuget.d.ts +93 -0
  114. package/dist/lifecycle/publish-nuget.js +377 -0
  115. package/dist/lifecycle/publish-oci.d.ts +91 -2
  116. package/dist/lifecycle/publish-oci.js +247 -8
  117. package/dist/lifecycle/publish-package-files.d.ts +16 -0
  118. package/dist/lifecycle/publish-package-files.js +39 -0
  119. package/dist/lifecycle/publish-pypi.d.ts +138 -0
  120. package/dist/lifecycle/publish-pypi.js +657 -0
  121. package/dist/lifecycle/publish-record.d.ts +6 -3
  122. package/dist/lifecycle/publish-record.js +6 -3
  123. package/dist/lifecycle/publish-rubygems.d.ts +84 -0
  124. package/dist/lifecycle/publish-rubygems.js +366 -0
  125. package/dist/lifecycle/publish-signing.d.ts +147 -0
  126. package/dist/lifecycle/publish-signing.js +257 -0
  127. package/dist/lifecycle/publish-targets.d.ts +37 -1
  128. package/dist/lifecycle/publish-targets.js +102 -0
  129. package/dist/lifecycle/publish-tauri.js +43 -0
  130. package/dist/lifecycle/publish-train-names.d.ts +57 -0
  131. package/dist/lifecycle/publish-train-names.js +123 -0
  132. package/dist/lifecycle/publish-verify.d.ts +121 -0
  133. package/dist/lifecycle/publish-verify.js +130 -0
  134. package/dist/lifecycle/query.js +8 -0
  135. package/dist/lifecycle/release-artifacts.d.ts +290 -0
  136. package/dist/lifecycle/release-artifacts.js +808 -0
  137. package/dist/lifecycle/release-changelog.d.ts +13 -1
  138. package/dist/lifecycle/release-changelog.js +35 -2
  139. package/dist/lifecycle/release-cut.d.ts +64 -4
  140. package/dist/lifecycle/release-cut.js +147 -34
  141. package/dist/lifecycle/release-doctor.d.ts +113 -0
  142. package/dist/lifecycle/release-doctor.js +1198 -0
  143. package/dist/lifecycle/release-green.d.ts +86 -0
  144. package/dist/lifecycle/release-green.js +286 -0
  145. package/dist/lifecycle/release-init-registries.d.ts +48 -0
  146. package/dist/lifecycle/release-init-registries.js +97 -0
  147. package/dist/lifecycle/release-init.d.ts +275 -0
  148. package/dist/lifecycle/release-init.js +984 -0
  149. package/dist/lifecycle/release-intents.d.ts +73 -0
  150. package/dist/lifecycle/release-intents.js +128 -0
  151. package/dist/lifecycle/release-next.d.ts +111 -0
  152. package/dist/lifecycle/release-next.js +251 -0
  153. package/dist/lifecycle/release-prerelease.d.ts +19 -0
  154. package/dist/lifecycle/release-prerelease.js +30 -0
  155. package/dist/lifecycle/release-publish.d.ts +256 -10
  156. package/dist/lifecycle/release-publish.js +247 -35
  157. package/dist/lifecycle/release-status-change.d.ts +226 -0
  158. package/dist/lifecycle/release-status-change.js +478 -0
  159. package/dist/lifecycle/release-status.d.ts +11 -0
  160. package/dist/lifecycle/release-status.js +1 -1
  161. package/dist/lifecycle/release-store.d.ts +73 -2
  162. package/dist/lifecycle/release-store.js +32 -1
  163. package/dist/lifecycle/release-tag.d.ts +142 -0
  164. package/dist/lifecycle/release-tag.js +322 -0
  165. package/dist/lifecycle/release-verify.d.ts +73 -1
  166. package/dist/lifecycle/release-verify.js +117 -2
  167. package/dist/lifecycle/release-version-formats.d.ts +73 -0
  168. package/dist/lifecycle/release-version-formats.js +570 -0
  169. package/dist/lifecycle/release-version.d.ts +58 -10
  170. package/dist/lifecycle/release-version.js +164 -36
  171. package/dist/lifecycle/release-workstation.d.ts +3 -2
  172. package/dist/lifecycle/release-workstation.js +3 -2
  173. package/dist/op/generate-pipeline.js +1 -1
  174. package/dist/op/local-executor.d.ts +1 -1
  175. package/dist/op/local-executor.js +2 -2
  176. package/dist/op/op-waves-evidence.js +9 -2
  177. package/dist/pr-forge-base.js +4 -2
  178. package/dist/pr-forge.d.ts +20 -2
  179. package/dist/pr-forge.js +46 -10
  180. package/dist/release-floors.d.ts +8 -1
  181. package/dist/release-floors.js +9 -2
  182. package/dist/sensitive-key.d.ts +12 -0
  183. package/dist/sensitive-key.js +52 -0
  184. package/dist/tool-pins.d.ts +40 -0
  185. package/dist/tool-pins.js +66 -0
  186. package/dist/ts-loader.d.ts +8 -0
  187. package/dist/ts-loader.js +19 -0
  188. package/dist/wave-runtime.mjs +345 -342
  189. package/dist/workspace/ci-forge.d.ts +17 -0
  190. package/dist/workspace/ci-forge.js +17 -0
  191. package/dist/workspace/ci-init.js +1 -1
  192. package/dist/workspace/composites.schema.json +1 -0
  193. package/dist/workspace/declaration.d.ts +8 -0
  194. package/dist/workspace/declaration.js +12 -0
  195. package/dist/workspace/declaration.schema.json +8 -0
  196. package/dist/workspace/environments.d.ts +2 -0
  197. package/dist/workspace/environments.js +1 -1
  198. package/dist/workspace/identity-gate-rule.d.ts +61 -5
  199. package/dist/workspace/identity-gate-rule.js +81 -12
  200. package/dist/workspace/lexicon-outputs.d.ts +1 -1
  201. package/dist/workspace/lexicon-outputs.js +1 -1
  202. package/dist/workspace/member-pipeline.d.ts +2 -1
  203. package/dist/workspace/member-pipeline.js +5 -2
  204. package/dist/workspace/reason-codes.d.ts +2 -0
  205. package/dist/workspace/reason-codes.js +3 -1
  206. package/dist/workspace/release-changed.d.ts +75 -4
  207. package/dist/workspace/release-changed.js +205 -34
  208. package/dist/workspace/release-changed.schema.json +20 -2
  209. package/dist/workspace/release-steps/artifacts.d.ts +7 -0
  210. package/dist/workspace/release-steps/artifacts.js +45 -0
  211. package/dist/workspace/release-steps/builds.d.ts +12 -0
  212. package/dist/workspace/release-steps/builds.js +38 -0
  213. package/dist/workspace/release-steps/doctor.d.ts +8 -0
  214. package/dist/workspace/release-steps/doctor.js +14 -0
  215. package/dist/workspace/release-steps/goreleaser.d.ts +16 -0
  216. package/dist/workspace/release-steps/goreleaser.js +36 -0
  217. package/dist/workspace/release-steps/green.d.ts +3 -0
  218. package/dist/workspace/release-steps/green.js +6 -0
  219. package/dist/workspace/release-steps/images.d.ts +22 -0
  220. package/dist/workspace/release-steps/images.js +59 -0
  221. package/dist/workspace/release-steps/index.d.ts +9 -0
  222. package/dist/workspace/release-steps/index.js +50 -0
  223. package/dist/workspace/release-steps/nfpm.d.ts +13 -0
  224. package/dist/workspace/release-steps/nfpm.js +29 -0
  225. package/dist/workspace/release-steps/nuget.d.ts +14 -0
  226. package/dist/workspace/release-steps/nuget.js +16 -0
  227. package/dist/workspace/release-steps/pypi.d.ts +15 -0
  228. package/dist/workspace/release-steps/pypi.js +21 -0
  229. package/dist/workspace/release-steps/qemu.d.ts +21 -0
  230. package/dist/workspace/release-steps/qemu.js +35 -0
  231. package/dist/workspace/release-steps/signing.d.ts +18 -0
  232. package/dist/workspace/release-steps/signing.js +30 -0
  233. package/dist/workspace/release-steps/stamp.d.ts +3 -0
  234. package/dist/workspace/release-steps/stamp.js +4 -0
  235. package/dist/workspace/release-steps/targets.d.ts +31 -0
  236. package/dist/workspace/release-steps/targets.js +40 -0
  237. package/dist/workspace/release-steps/types.d.ts +104 -0
  238. package/dist/workspace/release-steps/types.js +2 -0
  239. package/dist/workspace/release-steps/verify.d.ts +3 -0
  240. package/dist/workspace/release-steps/verify.js +4 -0
  241. package/dist/workspace/release-toolchains.d.ts +59 -0
  242. package/dist/workspace/release-toolchains.js +133 -0
  243. package/dist/workspace/release-train-workflow.d.ts +36 -0
  244. package/dist/workspace/release-train-workflow.js +121 -0
  245. package/dist/workspace/release-train.d.ts +3 -1
  246. package/dist/workspace/release-train.js +20 -3
  247. package/dist/workspace/release-workflow.d.ts +183 -59
  248. package/dist/workspace/release-workflow.js +570 -201
  249. package/dist/workspace/releases.schema.json +70 -1
  250. package/dist/workspace/search-contract.d.ts +1 -1
  251. package/dist/workspace/security.js +9 -2
  252. package/dist/workspace/train-cut.d.ts +182 -0
  253. package/dist/workspace/train-cut.js +504 -0
  254. package/dist/workspace/train-prepare.d.ts +64 -0
  255. package/dist/workspace/train-prepare.js +313 -0
  256. package/dist/workspace/train-publish.d.ts +177 -0
  257. package/dist/workspace/train-publish.js +574 -0
  258. package/dist/workspace/train-range-labels.d.ts +33 -0
  259. package/dist/workspace/train-range-labels.js +109 -0
  260. package/dist/workspace/train-shell.d.ts +5 -0
  261. package/dist/workspace/train-shell.js +17 -0
  262. package/dist/workspace/trust/check-evidence-report.d.ts +3 -7
  263. package/dist/workspace/trust/check-evidence-report.js +3 -7
  264. package/dist/workspace/trust/seal.d.ts +13 -3
  265. package/dist/workspace/trust/seal.js +14 -4
  266. package/dist/workspace/work-cli.d.ts +3 -2
  267. package/dist/workspace/work-cli.js +3 -2
  268. package/dist/workspace/workspace-ledger.d.ts +14 -1
  269. package/dist/workspace/workspace-ledger.js +33 -7
  270. package/package.json +1 -1
@@ -7,7 +7,10 @@
7
7
  * `chant/lifecycle`, under the member's prefix like `cuts.jsonl` beside it,
8
8
  * append-only. A target that staged gets a `staged` line with its items and
9
9
  * the state its reveal needs (a draft release's id); one that revealed gets
10
- * a `revealed` line. Each line is pushed as soon as it is written, so a CI
10
+ * a `revealed` line. The `release.verify` commands (#5157) get a `verified`
11
+ * or `verify-failed` line, under the target `verify:<hex>` of kind `verify`,
12
+ * with the failing command's name and exit status in its state; the lines of
13
+ * targets are what a resume reads. Each line is pushed as soon as it is written, so a CI
11
14
  * job that resumes on a fresh checkout reads it after `fetchLifecycle`.
12
15
  *
13
16
  * Why a record and not only the registries: a registry says whether a version
@@ -33,10 +36,10 @@ export interface PublishRecord {
33
36
  label: string | null;
34
37
  /** The target's key ({@link PublishTarget.key}). */
35
38
  target: string;
36
- kind: PublishTarget["kind"];
39
+ kind: PublishTarget["kind"] | "verify";
37
40
  /** The target's name, for a reader. */
38
41
  name: string;
39
- step: "staged" | "revealed";
42
+ step: "staged" | "revealed" | "verified" | "verify-failed";
40
43
  items: PublishItem[];
41
44
  /** What the reveal needs, on a `staged` line; `{}` on a `revealed` one. */
42
45
  state: Record<string, string>;
@@ -7,7 +7,10 @@
7
7
  * `chant/lifecycle`, under the member's prefix like `cuts.jsonl` beside it,
8
8
  * append-only. A target that staged gets a `staged` line with its items and
9
9
  * the state its reveal needs (a draft release's id); one that revealed gets
10
- * a `revealed` line. Each line is pushed as soon as it is written, so a CI
10
+ * a `revealed` line. The `release.verify` commands (#5157) get a `verified`
11
+ * or `verify-failed` line, under the target `verify:<hex>` of kind `verify`,
12
+ * with the failing command's name and exit status in its state; the lines of
13
+ * targets are what a resume reads. Each line is pushed as soon as it is written, so a CI
11
14
  * job that resumes on a fresh checkout reads it after `fetchLifecycle`.
12
15
  *
13
16
  * Why a record and not only the registries: a registry says whether a version
@@ -37,7 +40,7 @@ export function parsePublishRecords(text) {
37
40
  r.version === 1 &&
38
41
  typeof r.releaseDigest === "string" &&
39
42
  typeof r.target === "string" &&
40
- (r.step === "staged" || r.step === "revealed") &&
43
+ (r.step === "staged" || r.step === "revealed" || r.step === "verified" || r.step === "verify-failed") &&
41
44
  Array.isArray(r.items) &&
42
45
  typeof r.timestamp === "string";
43
46
  if (!ok) {
@@ -64,7 +67,7 @@ export function publishProgress(records) {
64
67
  for (const r of records) {
65
68
  if (r.step === "staged")
66
69
  staged.set(r.target, { target: r.name, destination: "", items: r.items, state: r.state });
67
- else
70
+ else if (r.step === "revealed")
68
71
  revealed.set(r.target, { target: r.name, destination: "", items: r.items });
69
72
  }
70
73
  return { staged, revealed };
@@ -0,0 +1,84 @@
1
+ /**
2
+ * The RubyGems target (#5232): `.gem` files pushed to RubyGems.org, or to
3
+ * another host that takes its API (`POST /api/v1/gems`, the gem as the body,
4
+ * the key in `Authorization`).
5
+ *
6
+ * The gems are files, directories of them, or `artifact:<name>`. Each file
7
+ * the release records must match its digest. The name, version and platform
8
+ * are read from the gem's own `metadata.gz`.
9
+ *
10
+ * A host has no draft: a version is visible once it is pushed, and a name,
11
+ * version and platform can never be pushed again, even after a yank. So the
12
+ * stage pushes nothing. It checks the gems and the credential, and reads
13
+ * `/api/v1/versions/<name>.json`: a version the host lists for the platform
14
+ * with the same SHA-256 is `present`; one it lists with another is refused
15
+ * (`publish-rubygems-version-exists`). The reveal reads it again and pushes
16
+ * the rest, so a reveal run again after a push whose record was lost sends
17
+ * nothing twice.
18
+ *
19
+ * Credentials:
20
+ *
21
+ * - `auth: "token"`: an API key from `tokenEnv` (default `GEM_HOST_API_KEY`,
22
+ * the variable `gem push` reads), with the push scope.
23
+ * - `auth: "trusted-publishing"`, RubyGems.org only: the run's OIDC ID token
24
+ * (audience `rubygems.org`, from GitHub Actions or `RUBYGEMS_ID_TOKEN`) is
25
+ * exchanged at `POST /api/v1/oidc/trusted_publisher/exchange_token` for a
26
+ * key that lasts minutes. The stage exchanges to check that RubyGems.org
27
+ * takes this workflow as a trusted publisher, and drops the key; the
28
+ * reveal exchanges again.
29
+ *
30
+ * Unset, `auth` is a token when the key's variable is set, else trusted
31
+ * publishing when the run has an OIDC ID token.
32
+ *
33
+ * A status change (#5163): `chant release yank` yanks each version the
34
+ * release pushed (`DELETE /api/v1/gems/yank`), with a key in `tokenEnv` that
35
+ * may yank. RubyGems.org takes no yank back, so `restore` is refused, and it
36
+ * has no deprecation, so `deprecate` changes nothing.
37
+ *
38
+ * A host keeps no file beside a gem, so nothing is attached. Under the
39
+ * `supply-chain` group the target is refused (`publish-sbom-missing`) unless
40
+ * `sbom` is `false`.
41
+ */
42
+ import type { RubygemsPublishDeclaration } from "./publish-declaration.js";
43
+ import { type PublishDeps, type PublishTarget } from "./release-publish.js";
44
+ /** The first chant that publishes a `rubygems` target (#5232). */
45
+ export declare const PUBLISH_RUBYGEMS_FLOOR = "0.124.102";
46
+ export declare const RUBYGEMS_ORG = "https://rubygems.org";
47
+ /** The audience RubyGems.org takes an OIDC ID token for. */
48
+ export declare const RUBYGEMS_AUDIENCE = "rubygems.org";
49
+ /** The variable an OIDC ID token for RubyGems.org is read from outside GitHub Actions. */
50
+ export declare const RUBYGEMS_ID_TOKEN_ENV = "RUBYGEMS_ID_TOKEN";
51
+ export declare const rubygemsHost: (decl: Pick<RubygemsPublishDeclaration, "host">) => string;
52
+ export declare const rubygemsTokenEnv: (decl: Pick<RubygemsPublishDeclaration, "tokenEnv">) => string;
53
+ /** How the target authenticates in `env`. */
54
+ export declare function rubygemsAuth(decl: RubygemsPublishDeclaration, env: NodeJS.ProcessEnv): "token" | "trusted-publishing";
55
+ /** One `.gem`, read. */
56
+ export interface RubyGem {
57
+ path: string;
58
+ file: string;
59
+ bytes: Buffer;
60
+ digest: string;
61
+ name: string;
62
+ version: string;
63
+ platform: string;
64
+ /** The gems it needs at run time. */
65
+ dependencies: string[];
66
+ }
67
+ /** A gemspec's name, version, platform and runtime dependencies, from the YAML `gem build` writes into `metadata.gz`. */
68
+ export declare function parseGemMetadata(yaml: string): {
69
+ name: string | null;
70
+ version: string | null;
71
+ platform: string;
72
+ dependencies: string[];
73
+ };
74
+ /** Read one `.gem`: a tar holding `metadata.gz`. */
75
+ export declare function readGem(path: string, abs: string): RubyGem;
76
+ /** An item's name: `<name>@<version>`, with `-<platform>` for a platform gem. A gem version holds no `-`. */
77
+ export declare const gemItemName: (g: Pick<RubyGem, "name" | "version" | "platform">) => string;
78
+ /** The gem an item names. */
79
+ export declare function parseGemItemName(name: string): {
80
+ name: string;
81
+ version: string;
82
+ platform: string;
83
+ } | null;
84
+ export declare function rubygemsTarget(decl: RubygemsPublishDeclaration, deps: PublishDeps): PublishTarget;
@@ -0,0 +1,366 @@
1
+ /**
2
+ * The RubyGems target (#5232): `.gem` files pushed to RubyGems.org, or to
3
+ * another host that takes its API (`POST /api/v1/gems`, the gem as the body,
4
+ * the key in `Authorization`).
5
+ *
6
+ * The gems are files, directories of them, or `artifact:<name>`. Each file
7
+ * the release records must match its digest. The name, version and platform
8
+ * are read from the gem's own `metadata.gz`.
9
+ *
10
+ * A host has no draft: a version is visible once it is pushed, and a name,
11
+ * version and platform can never be pushed again, even after a yank. So the
12
+ * stage pushes nothing. It checks the gems and the credential, and reads
13
+ * `/api/v1/versions/<name>.json`: a version the host lists for the platform
14
+ * with the same SHA-256 is `present`; one it lists with another is refused
15
+ * (`publish-rubygems-version-exists`). The reveal reads it again and pushes
16
+ * the rest, so a reveal run again after a push whose record was lost sends
17
+ * nothing twice.
18
+ *
19
+ * Credentials:
20
+ *
21
+ * - `auth: "token"`: an API key from `tokenEnv` (default `GEM_HOST_API_KEY`,
22
+ * the variable `gem push` reads), with the push scope.
23
+ * - `auth: "trusted-publishing"`, RubyGems.org only: the run's OIDC ID token
24
+ * (audience `rubygems.org`, from GitHub Actions or `RUBYGEMS_ID_TOKEN`) is
25
+ * exchanged at `POST /api/v1/oidc/trusted_publisher/exchange_token` for a
26
+ * key that lasts minutes. The stage exchanges to check that RubyGems.org
27
+ * takes this workflow as a trusted publisher, and drops the key; the
28
+ * reveal exchanges again.
29
+ *
30
+ * Unset, `auth` is a token when the key's variable is set, else trusted
31
+ * publishing when the run has an OIDC ID token.
32
+ *
33
+ * A status change (#5163): `chant release yank` yanks each version the
34
+ * release pushed (`DELETE /api/v1/gems/yank`), with a key in `tokenEnv` that
35
+ * may yank. RubyGems.org takes no yank back, so `restore` is refused, and it
36
+ * has no deprecation, so `deprecate` changes nothing.
37
+ *
38
+ * A host keeps no file beside a gem, so nothing is attached. Under the
39
+ * `supply-chain` group the target is refused (`publish-sbom-missing`) unless
40
+ * `sbom` is `false`.
41
+ */
42
+ import { readFileSync } from "node:fs";
43
+ import { gunzipSync } from "node:zlib";
44
+ import { readCredential } from "./publish-credentials.js";
45
+ import { releaseVersion } from "./publish-index.js";
46
+ import { packageFiles } from "./publish-package-files.js";
47
+ import { tarEntries } from "./publish-pypi.js";
48
+ import { bytesDigest, checkReleaseDigest, hasIdToken, publishTargetKey, runIdToken } from "./publish-targets.js";
49
+ import { trainName, waitUntilServed } from "./publish-train-names.js";
50
+ import { NEXT_RELEASE } from "../release-floors.js";
51
+ import { PublishTargetError } from "./release-publish.js";
52
+ /** The first chant that publishes a `rubygems` target (#5232). */
53
+ export const PUBLISH_RUBYGEMS_FLOOR = NEXT_RELEASE;
54
+ export const RUBYGEMS_ORG = "https://rubygems.org";
55
+ /** The audience RubyGems.org takes an OIDC ID token for. */
56
+ export const RUBYGEMS_AUDIENCE = "rubygems.org";
57
+ /** The variable an OIDC ID token for RubyGems.org is read from outside GitHub Actions. */
58
+ export const RUBYGEMS_ID_TOKEN_ENV = "RUBYGEMS_ID_TOKEN";
59
+ export const rubygemsHost = (decl) => (decl.host ?? RUBYGEMS_ORG).replace(/\/+$/, "");
60
+ export const rubygemsTokenEnv = (decl) => decl.tokenEnv ?? "GEM_HOST_API_KEY";
61
+ /** How the target authenticates in `env`. */
62
+ export function rubygemsAuth(decl, env) {
63
+ if (decl.auth)
64
+ return decl.auth;
65
+ if (env[rubygemsTokenEnv(decl)])
66
+ return "token";
67
+ return decl.host === undefined && hasIdToken(env, RUBYGEMS_ID_TOKEN_ENV) ? "trusted-publishing" : "token";
68
+ }
69
+ const unquote = (s) => s.trim().replace(/^(['"])(.*)\1$/, "$2");
70
+ /** A gemspec's name, version, platform and runtime dependencies, from the YAML `gem build` writes into `metadata.gz`. */
71
+ export function parseGemMetadata(yaml) {
72
+ const name = /^name: *(.+)$/m.exec(yaml)?.[1];
73
+ const version = /^version: *!ruby\/object:Gem::Version\s*\n\s+version: *(.+)$/m.exec(yaml)?.[1] ?? /^version: *([^!\s].*)$/m.exec(yaml)?.[1];
74
+ const platform = /^platform: *(.+)$/m.exec(yaml)?.[1];
75
+ const deps = /^dependencies: *\n([\s\S]*?)(?=^[^\s-])/m.exec(`${yaml}\n.`)?.[1] ?? "";
76
+ const dependencies = deps
77
+ .split(/^- !ruby\/object:Gem::Dependency\s*$/m)
78
+ .map((block) => ({ name: /^ {2}name: *(.+)$/m.exec(block)?.[1], type: /^ {2}type: *:?(\w+)/m.exec(block)?.[1] }))
79
+ .filter((d) => d.name !== undefined && d.type !== "development")
80
+ .map((d) => unquote(d.name));
81
+ return { name: name ? unquote(name) : null, version: version ? unquote(version) : null, platform: platform ? unquote(platform) : "ruby", dependencies: [...new Set(dependencies)] };
82
+ }
83
+ /** Read one `.gem`: a tar holding `metadata.gz`. */
84
+ export function readGem(path, abs) {
85
+ const bytes = readFileSync(abs);
86
+ const file = abs.split(/[\\/]/).pop();
87
+ const bad = (why) => new PublishTargetError("publish-rubygems-not-a-gem", `${path} is not a gem chant can read: ${why}`, "Name the .gem files gem build writes.");
88
+ let meta;
89
+ try {
90
+ const gz = tarEntries(bytes).get("metadata.gz");
91
+ if (!gz)
92
+ throw new Error("it holds no metadata.gz");
93
+ meta = parseGemMetadata(gunzipSync(gz).toString("utf-8"));
94
+ }
95
+ catch (err) {
96
+ throw bad(err instanceof Error ? err.message : String(err));
97
+ }
98
+ if (!meta.name || !meta.version)
99
+ throw bad("its metadata has no name or version");
100
+ return { path, file, bytes, digest: bytesDigest(new Uint8Array(bytes)), name: meta.name, version: meta.version, platform: meta.platform, dependencies: meta.dependencies };
101
+ }
102
+ const full = (g) => `${g.name}-${g.version}${g.platform === "ruby" ? "" : `-${g.platform}`}`;
103
+ /** An item's name: `<name>@<version>`, with `-<platform>` for a platform gem. A gem version holds no `-`. */
104
+ export const gemItemName = (g) => `${g.name}@${g.version}${g.platform === "ruby" ? "" : `-${g.platform}`}`;
105
+ /** The gem an item names. */
106
+ export function parseGemItemName(name) {
107
+ const at = name.lastIndexOf("@");
108
+ if (at <= 0)
109
+ return null;
110
+ const rest = name.slice(at + 1);
111
+ const dash = rest.indexOf("-");
112
+ return { name: name.slice(0, at), version: dash < 0 ? rest : rest.slice(0, dash), platform: dash < 0 ? "ruby" : rest.slice(dash + 1) };
113
+ }
114
+ export function rubygemsTarget(decl, deps) {
115
+ const fetchImpl = deps.fetch ?? ((url, init) => fetch(url, init));
116
+ const host = rubygemsHost(decl);
117
+ const label = decl.host ? new URL(host).host : "RubyGems.org";
118
+ const tokenName = rubygemsTokenEnv(decl);
119
+ const gems = (ctx) => {
120
+ if (ctx.requireSbom && decl.sbom !== false) {
121
+ throw new PublishTargetError("publish-sbom-missing", `${label} keeps no file beside a gem, so the gems this target publishes carry no SBOM`, "Attach the SBOM to the release elsewhere, such as with a forge target, and set sbom: false on this target.");
122
+ }
123
+ return packageFiles(ctx, decl.gems, ".gem", "publish-rubygems", "Build the gems before publishing, such as with gem build.").map(({ path, abs }) => {
124
+ const g = readGem(path, abs);
125
+ checkReleaseDigest(ctx.release, "asset", ctx.cwd, path, [g.digest]);
126
+ return g;
127
+ });
128
+ };
129
+ const item = (g) => ({ name: gemItemName(g), destination: `${host}/gems/${g.name}/versions/${g.version}${g.platform === "ruby" ? "" : `-${g.platform}`}`, digest: g.digest });
130
+ const fail = (ctx, code, what, status, text, fix) => {
131
+ throw new PublishTargetError(code, ctx.redactor.redact(`${what} on ${label} answered ${status}${text ? `: ${text.replace(/\s+/g, " ").slice(0, 300)}` : ""}`), fix);
132
+ };
133
+ /** Each version the host lists for a gem, `<version>-<platform>` to its SHA-256 in hex (or null); empty when it has no such gem. */
134
+ const listed = async (ctx, name) => {
135
+ const url = `${host}/api/v1/versions/${encodeURIComponent(name)}.json`;
136
+ const res = await fetchImpl(url, { method: "GET", headers: { "user-agent": "chant", accept: "application/json" } });
137
+ const text = await res.text().catch(() => "");
138
+ if (res.status === 404)
139
+ return new Map();
140
+ if (res.status !== 200)
141
+ fail(ctx, "publish-rubygems-failed", `reading ${url}`, res.status, text);
142
+ const out = new Map();
143
+ try {
144
+ for (const v of JSON.parse(text)) {
145
+ if (typeof v.number === "string")
146
+ out.set(`${v.number}-${typeof v.platform === "string" ? v.platform : "ruby"}`, typeof v.sha === "string" ? v.sha.toLowerCase() : null);
147
+ }
148
+ }
149
+ catch {
150
+ fail(ctx, "publish-rubygems-failed", `reading ${url}`, res.status, "not a JSON list");
151
+ }
152
+ return out;
153
+ };
154
+ /** Each gem: `present` when the host lists it with the same bytes; refused when it lists it with others. */
155
+ const presence = async (ctx, list) => {
156
+ const byName = new Map();
157
+ const out = new Map();
158
+ for (const g of list) {
159
+ if (!byName.has(g.name))
160
+ byName.set(g.name, await listed(ctx, g.name));
161
+ const versions = byName.get(g.name);
162
+ const key = `${g.version}-${g.platform}`;
163
+ if (!versions.has(key)) {
164
+ out.set(g.file, false);
165
+ continue;
166
+ }
167
+ const sha = versions.get(key);
168
+ if (sha && `sha256:${sha}` !== g.digest) {
169
+ throw new PublishTargetError("publish-rubygems-version-exists", `${label} already has ${full(g)}, with sha256:${sha}, not ${g.digest}`, "A gem host never takes a version twice: cut a release with a new version.");
170
+ }
171
+ out.set(g.file, true);
172
+ }
173
+ return out;
174
+ };
175
+ const credential = (ctx) => {
176
+ const auth = rubygemsAuth(decl, ctx.env);
177
+ if (auth === "trusted-publishing") {
178
+ if (!hasIdToken(ctx.env, RUBYGEMS_ID_TOKEN_ENV)) {
179
+ throw new PublishTargetError("publish-credentials-missing", `the RubyGems.org target publishes with trusted publishing, and this run has no OIDC ID token: not a GitHub Actions job with id-token: write, and ${RUBYGEMS_ID_TOKEN_ENV} is not set`, "In GitHub Actions, give the job permissions: id-token: write.");
180
+ }
181
+ return { auth, key: null, from: null };
182
+ }
183
+ const cred = readCredential(ctx.env, [tokenName], ctx.redactor);
184
+ if (!cred) {
185
+ throw new PublishTargetError("publish-credentials-missing", `the ${label} target reads its API key from ${tokenName}, and it is not set${decl.host ? "" : ", and this run has no OIDC ID token for trusted publishing"}`, decl.host ? `Set ${tokenName} to a key the host takes.` : `Set ${tokenName} to a RubyGems.org API key with the push scope, or publish from a GitHub Actions job with id-token: write and a trusted publisher on RubyGems.org.`);
186
+ }
187
+ return { auth, key: cred.value, from: cred.from };
188
+ };
189
+ /** Trusted publishing: a key for this run, for its OIDC ID token. */
190
+ const exchange = async (ctx) => {
191
+ const jwt = await runIdToken(ctx, fetchImpl, RUBYGEMS_AUDIENCE, RUBYGEMS_ID_TOKEN_ENV, "publish-rubygems-trusted-publishing");
192
+ const res = await fetchImpl(`${host}/api/v1/oidc/trusted_publisher/exchange_token`, { method: "POST", headers: { "user-agent": "chant", "content-type": "application/json", accept: "application/json" }, body: JSON.stringify({ jwt }) });
193
+ const text = await res.text().catch(() => "");
194
+ let body = {};
195
+ try {
196
+ body = JSON.parse(text);
197
+ }
198
+ catch {
199
+ // Reported by its status.
200
+ }
201
+ if (res.status < 200 || res.status > 299 || typeof body.rubygems_api_key !== "string" || !body.rubygems_api_key) {
202
+ throw new PublishTargetError("publish-rubygems-trusted-publishing", ctx.redactor.redact(`RubyGems.org gave no API key for this run's OIDC ID token: it answered ${res.status}${typeof body.error === "string" ? `: ${body.error}` : text ? `: ${text.replace(/\s+/g, " ").slice(0, 300)}` : ""}`), "Add this repository and workflow as a trusted publisher of the gem on RubyGems.org (a pending trusted publisher for a gem that does not exist yet).");
203
+ }
204
+ ctx.redactor.add(body.rubygems_api_key);
205
+ return body.rubygems_api_key;
206
+ };
207
+ const push = async (ctx, g, key) => {
208
+ ctx.log(`pushing ${g.file} (${g.bytes.byteLength} bytes) to ${label}`);
209
+ const res = await fetchImpl(`${host}/api/v1/gems`, { method: "POST", headers: { "user-agent": "chant", "content-type": "application/octet-stream", authorization: key }, body: new Uint8Array(g.bytes) });
210
+ const text = await res.text().catch(() => "");
211
+ if (res.status === 200 || res.status === 201)
212
+ return "sent";
213
+ if (res.status === 409 || /repushing|already been pushed/i.test(text)) {
214
+ // Another push of this version won the race, or a record was lost: the host keeps the first bytes it took.
215
+ const now = await presence(ctx, [g]).catch((err) => {
216
+ if (err instanceof PublishTargetError)
217
+ throw err;
218
+ return new Map();
219
+ });
220
+ if (now.get(g.file))
221
+ return "present";
222
+ throw new PublishTargetError("publish-rubygems-version-exists", ctx.redactor.redact(`${label} refused ${g.file}: ${text.replace(/\s+/g, " ").slice(0, 300)}`), "A gem host never takes a version twice, even after a yank: cut a release with a new version.");
223
+ }
224
+ return fail(ctx, "publish-rubygems-failed", `pushing ${g.file}`, res.status, text, /otp|multi.?factor|mfa/i.test(text)
225
+ ? "The account asks for a one-time password on API pushes: publish with trusted publishing, or set its MFA level to UI and gem signin."
226
+ : res.status === 401 || res.status === 403
227
+ ? `Check that the key has the push scope and that its owner owns ${g.name}.`
228
+ : undefined);
229
+ };
230
+ const target = {
231
+ kind: "rubygems",
232
+ name: `${label} ${decl.gems.join(", ")}`,
233
+ destination: label,
234
+ credentialEnv: [tokenName, RUBYGEMS_ID_TOKEN_ENV],
235
+ key: publishTargetKey(decl),
236
+ uploadsAtReveal: true,
237
+ async names(ctx) {
238
+ const list = packageFiles(ctx, decl.gems, ".gem", "publish-rubygems", "Build the gems before publishing.").map(({ path, abs }) => readGem(path, abs));
239
+ const provides = [...new Set(list.map((g) => trainName("rubygems", g.name)))];
240
+ const needs = new Set(list.flatMap((g) => g.dependencies.map((d) => trainName("rubygems", d))));
241
+ return { provides, needs: [...needs].filter((n) => !provides.includes(n)) };
242
+ },
243
+ /** #5165: whether the host lists each gem at the release's version. */
244
+ async published(ctx) {
245
+ const version = releaseVersion(ctx.label);
246
+ if (!version)
247
+ return null;
248
+ let list;
249
+ try {
250
+ list = packageFiles(ctx, decl.gems, ".gem", "publish-rubygems", "").map(({ path, abs }) => readGem(path, abs));
251
+ }
252
+ catch {
253
+ return null;
254
+ }
255
+ for (const g of list) {
256
+ const versions = await listed(ctx, g.name);
257
+ if (!versions.has(`${version}-${g.platform}`))
258
+ return false;
259
+ }
260
+ return true;
261
+ },
262
+ /** #5165: wait until the host lists each gem the reveal pushed. */
263
+ async visible(ctx, published) {
264
+ const list = published.items.filter((i) => i.attachment === undefined && !i.refused).map((i) => parseGemItemName(i.name)).filter((g) => g !== null);
265
+ if (list.length === 0)
266
+ return;
267
+ await waitUntilServed(ctx, deps, {
268
+ what: label,
269
+ code: "publish-rubygems-not-served",
270
+ check: async () => {
271
+ const missing = [];
272
+ for (const g of list)
273
+ if (!(await listed(ctx, g.name)).has(`${g.version}-${g.platform}`))
274
+ missing.push(full(g));
275
+ return missing;
276
+ },
277
+ });
278
+ },
279
+ async plan(ctx) {
280
+ const list = gems(ctx);
281
+ credential(ctx);
282
+ return list.map(item);
283
+ },
284
+ async stage(ctx) {
285
+ const list = gems(ctx);
286
+ const cred = credential(ctx);
287
+ if (cred.key)
288
+ ctx.log(`using the API key from ${cred.from}; ${label} has no read-only check of a key, so whether it may push shows at the reveal`);
289
+ else {
290
+ await exchange(ctx);
291
+ ctx.log("RubyGems.org takes this run as a trusted publisher; the reveal asks for a new key, since one lasts minutes");
292
+ }
293
+ const present = await presence(ctx, list);
294
+ const items = list.map((g) => (present.get(g.file) ? { ...item(g), present: true } : item(g)));
295
+ const waiting = items.filter((i) => !i.present).map((i) => i.name);
296
+ ctx.log(waiting.length === 0 ? `${label} already has every gem with the same bytes` : `${waiting.join(", ")} ${waiting.length === 1 ? "is" : "are"} pushed at the reveal, since ${label} has no draft`);
297
+ const staged = { target: target.name, destination: target.destination, items, state: waiting.length === 0 ? { present: "true" } : {} };
298
+ return staged;
299
+ },
300
+ async reveal(ctx, staged) {
301
+ if (staged.state.present === "true")
302
+ return { target: target.name, destination: target.destination, items: staged.items.map((i) => ({ ...i, present: true })) };
303
+ const list = gems(ctx);
304
+ const cred = credential(ctx);
305
+ // Read again: a reveal run after a push whose record was lost finds the gem there.
306
+ const present = await presence(ctx, list);
307
+ let key = cred.key;
308
+ const done = [];
309
+ const items = [];
310
+ for (const g of list) {
311
+ if (present.get(g.file)) {
312
+ items.push({ ...item(g), present: true });
313
+ continue;
314
+ }
315
+ key ?? (key = await exchange(ctx));
316
+ let r;
317
+ try {
318
+ r = await push(ctx, g, key);
319
+ }
320
+ catch (err) {
321
+ if (err instanceof PublishTargetError && done.length > 0)
322
+ throw new PublishTargetError(err.code, `${err.message}. Pushed before it: ${done.join(", ")}; the same publish run again pushes only the rest`, err.fix);
323
+ throw err;
324
+ }
325
+ if (r === "sent")
326
+ done.push(g.file);
327
+ items.push(r === "present" ? { ...item(g), present: true } : item(g));
328
+ }
329
+ return { target: target.name, destination: target.destination, items };
330
+ },
331
+ /** #5163: yank each version the release pushed. A yank can't be undone, and there is no deprecation. */
332
+ async setStatus(ctx) {
333
+ if (ctx.status === "deprecated")
334
+ return [{ what: `${label} unchanged: a gem version has no deprecation; yank takes it out of resolution`, already: true }];
335
+ const pushed = ctx.revealed
336
+ .filter((i) => i.attachment === undefined && !i.refused)
337
+ .map((i) => parseGemItemName(i.name))
338
+ .filter((g) => g !== null);
339
+ if (ctx.status === "active") {
340
+ return pushed.map((g) => ({ what: `restore ${full(g)}`, refused: { code: "release-status-unsupported", message: `${label} takes no yank back`, fix: "Cut a release with a new version." } }));
341
+ }
342
+ const what = (g) => `DELETE ${host}/api/v1/gems/yank gem_name=${g.name} version=${g.version}${g.platform === "ruby" ? "" : ` platform=${g.platform}`}`;
343
+ if (!ctx.apply)
344
+ return pushed.map((g) => ({ what: what(g) }));
345
+ const cred = readCredential(ctx.env, [tokenName], ctx.redactor);
346
+ if (!cred)
347
+ throw new PublishTargetError("publish-credentials-missing", `the ${label} target reads its API key from ${tokenName}, and it is not set`, `Set ${tokenName} to a key of ${label} with the yank scope.`);
348
+ const actions = [];
349
+ for (const g of pushed) {
350
+ if (!(await listed(ctx, g.name)).has(`${g.version}-${g.platform}`)) {
351
+ actions.push({ what: `${full(g)} is not listed on ${label}; it is yanked already, or was never pushed`, already: true });
352
+ continue;
353
+ }
354
+ const form = new URLSearchParams({ gem_name: g.name, version: g.version, ...(g.platform === "ruby" ? {} : { platform: g.platform }) }).toString();
355
+ ctx.log(`yanking ${full(g)} on ${label}`);
356
+ const res = await fetchImpl(`${host}/api/v1/gems/yank`, { method: "DELETE", headers: { "user-agent": "chant", "content-type": "application/x-www-form-urlencoded", authorization: cred.value }, body: form });
357
+ const text = await res.text().catch(() => "");
358
+ if (res.status < 200 || res.status > 299)
359
+ fail(ctx, "release-status-rubygems-failed", what(g), res.status, text, `Yanking needs a key with the yank scope whose owner owns ${g.name}.`);
360
+ actions.push({ what: what(g) });
361
+ }
362
+ return actions;
363
+ },
364
+ };
365
+ return target;
366
+ }
@@ -0,0 +1,147 @@
1
+ /**
2
+ * Sigstore signing at publish (#5164): keyless signatures and OIDC-signed
3
+ * SLSA provenance for what the OCI and forge targets publish, beside the
4
+ * release's own provenance statement and the cut's ssh signature, which stay
5
+ * as they are (./publish-attachments.ts).
6
+ *
7
+ * In a CI job with an OIDC token, a target's stage signs before anything is
8
+ * revealed:
9
+ *
10
+ * - an image gets a cosign signature, a Sigstore bundle over an in-toto
11
+ * statement whose predicate type is `https://sigstore.dev/cosign/sign/v1`,
12
+ * and SLSA provenance (`https://slsa.dev/provenance/v1`), each pushed as
13
+ * an OCI referrer of the image with the artifact type
14
+ * `application/vnd.dev.sigstore.bundle.v0.3+json`, the layout `cosign sign`
15
+ * and `actions/attest-build-provenance` push. `cosign verify` and `cosign
16
+ * verify-attestation --type slsaprovenance1` check them.
17
+ * - a forge release gets `<file>.sigstore.json` beside each file it holds (a
18
+ * `cosign sign-blob` bundle, checked with `cosign verify-blob`) and
19
+ * {@link SLSA_BUNDLE_FILE}, SLSA provenance over the declared assets.
20
+ *
21
+ * chant writes the statements and runs `cosign` (version 3, the binary
22
+ * `CHANT_COSIGN` names, else `cosign` on `PATH`) to sign them with the job's
23
+ * token: `cosign sign-blob` for a file and `cosign attest-blob --statement`
24
+ * for a statement. It pushes and uploads the bundles itself, with the
25
+ * target's own credentials. The generated release workflow downloads cosign
26
+ * pinned by SHA-256 (../tool-pins.ts).
27
+ *
28
+ * Signing is off unless `release.signing` in `chant.config.ts` turns it on
29
+ * or the workspace opts into the `supply-chain` group, where `signing: false`
30
+ * turns it off with a warning. When it is on and the run can't sign (no OIDC
31
+ * token cosign takes, or no cosign), the publish is refused before anything
32
+ * is sent.
33
+ */
34
+ import type { Redactor } from "./publish-credentials.js";
35
+ import type { SecurityGroup } from "../workspace/security.js";
36
+ import { type PublishContext } from "./release-publish.js";
37
+ /** The media type of a Sigstore bundle, and the artifact type of a referrer that holds one. */
38
+ export declare const SIGSTORE_BUNDLE_MEDIA_TYPE = "application/vnd.dev.sigstore.bundle.v0.3+json";
39
+ /** The predicate type of cosign's image signature statement. */
40
+ export declare const COSIGN_SIGN_PREDICATE = "https://sigstore.dev/cosign/sign/v1";
41
+ /** The predicate type of SLSA provenance v1. */
42
+ export declare const SLSA_PROVENANCE_PREDICATE = "https://slsa.dev/provenance/v1";
43
+ /** What a file's signature bundle is named after: `<file>.sigstore.json`. */
44
+ export declare const SIGSTORE_BUNDLE_SUFFIX = ".sigstore.json";
45
+ /** The forge asset that holds SLSA provenance over the release's assets. */
46
+ export declare const SLSA_BUNDLE_FILE = "release.slsa.sigstore.json";
47
+ /** The OCI annotation a bundle referrer names its predicate type under. */
48
+ export declare const BUNDLE_PREDICATE_ANNOTATION = "dev.sigstore.bundle.predicateType";
49
+ /** The buildType of SLSA provenance written in GitHub Actions, the one `actions/attest-build-provenance` writes. */
50
+ export declare const GITHUB_BUILD_TYPE = "https://actions.github.io/buildtypes/workflow/v1";
51
+ /** The buildType of SLSA provenance written in GitLab CI. */
52
+ export declare const GITLAB_BUILD_TYPE = "https://intentius.io/chant/release/build/gitlab-ci/v1";
53
+ /** The cosign major version chant runs: 3 writes Sigstore bundles by default. */
54
+ export declare const COSIGN_MAJOR = 3;
55
+ /** `release.signing` in `chant.config.ts`. */
56
+ export type SigningConfig = boolean | {
57
+ identity?: string;
58
+ issuer?: string;
59
+ };
60
+ /** Whether a publish signs, and why. */
61
+ export interface SigningSetting {
62
+ on: boolean;
63
+ /** `config` (release.signing), `supply-chain` (the group), or `off`. */
64
+ from: "config" | "supply-chain" | "off";
65
+ /** Set when the group asks for signing and `signing: false` turns it off. */
66
+ warning: string | null;
67
+ /** The certificate identity (a regular expression) and issuer a verify expects, when the config names them. */
68
+ identity?: string;
69
+ issuer?: string;
70
+ }
71
+ /** Whether a publish signs: `release.signing` first, then the `supply-chain` group. */
72
+ export declare function resolveSigning(config: SigningConfig | undefined, groups: ReadonlySet<SecurityGroup>): SigningSetting;
73
+ /** Who a keyless signature names: the OIDC issuer and a regular expression the certificate's identity matches. */
74
+ export interface SigstoreIdentity {
75
+ issuer: string;
76
+ identity: string;
77
+ }
78
+ /**
79
+ * Whether this run can sign keylessly, and the identity its certificate will
80
+ * name: in GitHub Actions, a job with `id-token: write`, whose certificate
81
+ * names a workflow of the repository; in GitLab CI, an ID token named
82
+ * `SIGSTORE_ID_TOKEN` with the audience `sigstore`, whose certificate names
83
+ * the project's pipeline. Anywhere else there is none.
84
+ */
85
+ export declare function signingIdentity(env: NodeJS.ProcessEnv): {
86
+ identity: SigstoreIdentity;
87
+ } | {
88
+ reason: string;
89
+ };
90
+ /** An in-toto Statement v1. */
91
+ export interface InTotoStatement {
92
+ _type: string;
93
+ subject: Array<{
94
+ name: string;
95
+ digest: Record<string, string>;
96
+ }>;
97
+ predicateType: string;
98
+ predicate: Record<string, unknown>;
99
+ }
100
+ /** The statement cosign signs for an image: its digest under `https://sigstore.dev/cosign/sign/v1`, with an empty predicate. */
101
+ export declare function cosignSignStatement(subject: {
102
+ name: string;
103
+ digest: string;
104
+ }): InTotoStatement;
105
+ /**
106
+ * SLSA provenance v1 over `subjects`, from the CI job's environment. In
107
+ * GitHub Actions it is the predicate `actions/attest-build-provenance`
108
+ * writes: the workflow, the event, the repository's ids, the commit and the
109
+ * run. In GitLab CI it names the project, its CI config, the pipeline source
110
+ * and the job. Either adds `internalParameters.chant`, the release's digest,
111
+ * label and member, and the source it resolves is the release's commit.
112
+ */
113
+ export declare function slsaProvenanceStatement(ctx: Pick<PublishContext, "env" | "release" | "label">, subjects: ReadonlyArray<{
114
+ name: string;
115
+ digest: string;
116
+ }>): InTotoStatement;
117
+ /** Signs with Sigstore. Injected, so tests sign with a fake. */
118
+ export interface Signer {
119
+ /** What signs, for messages, such as `cosign v3.1.4`. */
120
+ readonly name: string;
121
+ /** Null when it can sign here, else why not, in a sentence. */
122
+ unavailable(): string | null;
123
+ /** A bundle with a signature over `bytes` (`cosign sign-blob`). */
124
+ signBlob(bytes: Uint8Array, name: string): Promise<Uint8Array>;
125
+ /** A bundle with `statement` signed as a DSSE envelope (`cosign attest-blob --statement`). */
126
+ signStatement(statement: InTotoStatement): Promise<Uint8Array>;
127
+ }
128
+ /** Checks Sigstore signatures. Injected, so tests check with a fake. Each check gives null when it verifies, else why not. */
129
+ export interface SigstoreVerifier {
130
+ readonly name: string;
131
+ unavailable(): string | null;
132
+ verifyBlob(bundle: Uint8Array, digest: string, id: SigstoreIdentity): Promise<string | null>;
133
+ verifyBlobAttestation(bundle: Uint8Array, digest: string, predicateType: string, id: SigstoreIdentity): Promise<string | null>;
134
+ verifyImage(ref: string, id: SigstoreIdentity): Promise<string | null>;
135
+ verifyImageAttestation(ref: string, predicateType: string, id: SigstoreIdentity): Promise<string | null>;
136
+ }
137
+ /** The cosign a run uses: `CHANT_COSIGN`, else `cosign` on `PATH`. */
138
+ export declare function cosignPath(env: NodeJS.ProcessEnv): string;
139
+ /** A {@link Signer} that runs cosign keylessly, with `env`, which carries the job's OIDC token. */
140
+ export declare function cosignSigner(env: NodeJS.ProcessEnv, redactor: Redactor, cosign?: string): Signer;
141
+ /** A {@link SigstoreVerifier} that runs cosign. Image checks read the registry with docker's credentials. */
142
+ export declare function cosignVerifier(env: NodeJS.ProcessEnv, cosign?: string): SigstoreVerifier;
143
+ /** What a target signs with, in the publish context: the signer and the identity its certificate names. */
144
+ export interface SigningContext {
145
+ signer: Signer;
146
+ identity: SigstoreIdentity;
147
+ }