fix: provenance-file takes precedence over OIDC auto-generated provenance

[yunseo-kim]

Why Needed

When publishing with an externally generated provenance bundle under OIDC trusted publishing
(npm publish <tarball> --provenance-file=<bundle>), npm silently discarded the supplied bundle and published
its own auto-generated provenance instead. Three layers interacted:

1. lib/utils/oidc.js auto-enabled provenance (opts.provenance = true) whenever the provenance config was at
   its default, without checking whether a provenance-file was supplied.
2. In libnpmpublish's buildMetadata(), the inner provenance === true branch then ran generateProvenance(),
   so the verifyProvenance(subject, provenanceFile) branch, the only code path that reads the supplied file,
   never executed.
3. Every documented way to disable automatic provenance was unusable in combination with --provenance-file
   (config-layer mutual exclusivity error, env carve-out, or publishConfig flatten timing).

What Changes

• lib/utils/oidc.js: skip auto-enabling provenance when a provenance file is configured (opts.provenanceFile).
  opts already carries provenanceFile from every config source (CLI/env/npmrc/publishConfig) by the time the
  OIDC flow runs, so this covers all entry paths. The supplied bundle is now verified via verifyProvenance() and
  published, as documented.
• libnpmpublish: buildMetadata() now throws EPROVENANCECONFLICT when both provenance: true and
  provenanceFile are provided.
• Docs: config descriptions for provenance / provenance-file and the libnpmpublish README now state the
  precedence rule.

⚠️ New error code (feedback requested)

This PR introduces EPROVENANCECONFLICT in libnpmpublish, thrown when both provenance: true and
provenanceFile are provided programmatically.
Rationale: the README already documents the two as mutually exclusive, and silently preferring either direction
discards a cryptographically meaningful artifact. Note the CLI's config layer reports the same conflict as a
TypeError without an error code (pre-existing). Happy to align on EUSAGE or another convention per
review.

Testing

• New CLI regression test: OIDC trusted publishing + provenance-file config asserts the published packument's
  sigstore attachment deep-equals the supplied bundle (and that sigstore generation is never invoked).
• New libnpmpublish test: both options set → rejects with EPROVENANCECONFLICT, no registry PUT,
  generation not invoked.
• Full root suite green with 100% coverage; libnpmpublish workspace suite green; lint clean.

References

Fixes #9879

Out of scope (noted for follow-up)

• publishConfig.provenance: false does not block the OIDC auto-enable (publishConfig flattens into opts only,
  so config.isDefault('provenance') stays true). A separate behavioral question about isDefault semantics.
• config.set('provenance', true, 'user') bypassing load-time exclusivity is unreachable in this flow after this fix;
  hardening config.set itself is an @npmcli/config semver-major conversation.

[martinrrm]

Thanks for the contribution! This looks great, lets just add a new test and keep the error as EUSAGE

[martinrrm]

Lets use the existing EUSAGE error.

 throw Object.assign(
    new Error('provenance and provenanceFile cannot be used together'),
    { code: 'EUSAGE' }
  )

[martinrrm]

update this to EUSAGE

[martinrrm]

Let's add another test to prove that publishConfig is flattened into opts.provenanceFile beofre oidc() decides whether to enable automatic provenance.

The important distinction is:

// Existing regression path
config: {
  'provenance-file': provenanceBundlePath,
}

versus:

// Additional regression path
packageJson: {
  publishConfig: {
    'provenance-file': provenanceBundlePath,
  },
}

The second case exercises Publish.#getManifest() and its special flatten(filteredPublishConfig, opts) path in  lib/commands/publish.js. Automatic provenance would still be enabled if that flattening did not reach  opts.provenanceFile.

Rather than duplicating the existing 119-line test, I would parameterize it:

const provenanceFileSources = [
  {
    name: 'CLI config',
    options: provenanceBundlePath => ({
      config: {
        'provenance-file': provenanceBundlePath,
      },
    }),
  },
  {
    name: 'publishConfig',
    options: provenanceBundlePath => ({
      packageJson: {
        publishConfig: {
          'provenance-file': provenanceBundlePath,
        },
      },
    }),
  },
]

for (const { name, options } of provenanceFileSources) {
  t.test(`${name} provenance-file takes precedence over OIDC auto-provenance`, async t => {
    const bundleDir = t.testdir()
    const provenanceBundlePath = path.join(
      bundleDir,
      'provenance-bundle.json'
    )
    const packMock = { tarballData: null }

    const sourceOptions = options(provenanceBundlePath)

    const { npm, registry, prefix, joinedOutput } = await mockOidc(t, {
      oidcOptions: { github: true },
      config: {
        '//registry.npmjs.org/:_authToken': 'existing-fallback-token',
        ...sourceOptions.config,
      },
      packageJson: sourceOptions.packageJson,
      mockGithubOidcOptions: {
        audience: 'npm:registry.npmjs.org',
        idToken: githubPublicIdToken,
      },
      mockOidcTokenExchangeOptions: {
        idToken: githubPublicIdToken,
        body: {
          token: 'exchange-token',
        },
      },
      publishOptions: {
        token: 'exchange-token',
        noPut: true,
      },
      load: {
        mocks: {
          libnpmaccess: {
            getVisibility: async () => ({ public: true }),
          },
          libnpmpack: async () => packMock.tarballData,
          libnpmpublish: t.mock('libnpmpublish', {
            'libnpmpublish/lib/provenance': t.mock(
              'libnpmpublish/lib/provenance',
              {
                sigstore: {
                  verify: async () => {},
                  attest: async () => {
                    throw new Error(
                      'sigstore.attest must not be called when provenance-file is configured'
                    )
                  },
                },
              }
            ),
          }),
        },
      },
    })

    // Current existing setup:
    // 1. Build the deterministic tarball.
    // 2. Calculate its SHA-512 digest.
    // 3. Create and write a matching provenance bundle.
    // 4. Capture the registry PUT body.
    // 5. Run npm publish.

    await npm.exec('publish', [])

    t.match(joinedOutput(), '+ @npmcli/test-package@1.0.0')

    const attachment =
      publishedBody?._attachments[`${pkg}-1.0.0.sigstore`]

    t.ok(attachment, 'published packument includes supplied provenance')
    t.strictSame(
      JSON.parse(attachment.data),
      provenanceBundle,
      'published sigstore bundle is the user-supplied provenance file'
    )
  })
}

The omitted bundle and registry setup remains unchanged from the existing test. Only the source of provenance-file becomes parameterized.

This verifies four things for publishConfig:

1. publishConfig["provenance-file"] is flattened into opts.provenanceFile.
2. OIDC token exchange still occurs normally.
3. OIDC does not auto-enable generated provenance.
4. The supplied bundle is verified and uploaded byte-for-byte;  sigstore.attest() is never called.