feat: add --provenance-file flag for publish command

[bdehamer]

Updates the publish command to accept a new --provenance-file option which points to an externally-generated provenance statement. If specified, the provenance statement will be read, verified and published as an attachment to the package.

Before the provenance is passed to the registry, there are some basic sanity checks like ensuring that the subject name/digest present in the provenance statement match the package being published. The signature in the provenance bundle is also verified to ensure it matches the package. More thorough verification checks are performed by the registry before it accepts the package for publishing.

This PR also introduces a mechanism to configure sets of flags whose use is mutually exclusive. This is currently applied to the --provenance and --provenance-file flags, but can be generally used for any flag sets with similar semantics.

Mutually-exclusive flags will appear like this in the help output:

Publish a package

Usage:
npm publish <package-spec>

Options:
[--tag <tag>] [--access <restricted|public>] [--dry-run] [--otp <otp>]
[-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
[-ws|--workspaces] [--include-workspace-root]
[--provenance|--provenance-file <file>]

An attempt to use exclusive flags at the same time will result in an error which looks like this:

$ node . publish --provenance --provenance-file ./foo
TypeError: --provenance-file can not be provided when using --provenance

[wraithgar]

This and the provenance flag definitely warrant a mention in the workspace readme.

[npm-cli-bot]

no statistically significant performance changes detected

timing results

app-large	clean	lock-only	cache-only	cache-only peer-deps	modules-only	no-lock	no-cache	no-modules	no-clean	no-clean audit	show-version	run-script
npm@9	34.785 ±3.55	15.040 ±0.07	14.658 ±0.14	17.061 ±0.80	2.601 ±0.19	2.438 ±0.03	2.050 ±0.02	10.152 ±0.12	2.044 ±0.02	3.139 ±0.18	0.362 ±0.01	0.374 ±0.01
#6490	42.260 ±7.51	15.221 ±0.20	14.673 ±0.11	16.969 ±0.57	2.549 ±0.10	2.433 ±0.04	2.051 ±0.03	10.115 ±0.10	2.028 ±0.01	3.081 ±0.06	0.348 ±0.00	0.385 ±0.00

app-medium	clean	lock-only	cache-only	cache-only peer-deps	modules-only	no-lock	no-cache	no-modules	no-clean	no-clean audit	show-version	run-script
npm@9	27.757 ±1.41	11.650 ±0.01	11.429 ±0.12	12.261 ±0.13	2.214 ±0.03	2.203 ±0.01	2.060 ±0.03	7.646 ±0.05	1.952 ±0.04	2.730 ±0.00	0.350 ±0.00	0.374 ±0.00
#6490	24.468 ±2.52	11.811 ±0.19	11.339 ±0.03	12.028 ±0.14	2.232 ±0.03	2.195 ±0.02	2.082 ±0.04	7.617 ±0.01	1.944 ±0.01	2.687 ±0.05	0.352 ±0.00	0.391 ±0.00

[ianlewis]

Should there be a note about the format of the provenance statement? Maybe also note that it should already be signed so that it's clear that npm isn't going to do signing for you?

[bdehamer]

Yeah, good call. I'll update

[bdehamer]

@ianlewis if you wanted to experiment with this before this change makes its way into an official npm release, you can do something like this to run from this branch.

[ianlewis]

@ianlewis if you wanted to experiment with this before this change makes its way into an official npm release, you can do something like this to run from this branch.

Sure. I think that's a private repo, but I'm doing something like this already with my own branch so I'll give it a try.

[bdehamer]

Sure. I think that's a private repo, but I'm doing something like this already with my own branch so I'll give it a try.

Whoops, didn't realize it was private. The line I was linking to is just this:

npm exec npm@npm/cli#bdehamer/provenance-path -- publish ${TARBALL} --access public --provenance-file provenance.json

[wraithgar]

This looks ready to me. We can button up the reflective checks of exclusive in another PR.

@lukekarrys will be landing this. @ianlewis do you see any show stoppers here?

[ianlewis]

@wraithgar @bdehamer LGTM. I tested your branch out and it worked the way I expected.

You may want to update the PR title to reflect that the flag is --provenance-file rather than --provenance-path.