From 80e2437fceaeff4955e965ff6ab76d77674d62c6 Mon Sep 17 00:00:00 2001 From: Mr-Neutr0n Date: Wed, 12 Aug 2026 17:31:35 +0530 Subject: [PATCH 1/2] docs(release): explain package provenance Signed-off-by: Mr-Neutr0n --- sdk/typescript/README.md | 41 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md index fbc0245f..b186e88d 100644 --- a/sdk/typescript/README.md +++ b/sdk/typescript/README.md @@ -25,6 +25,47 @@ When a newer version is available, the CLI shows the update command for your installation method. Set `CODEX_SECURITY_NO_UPDATE_NOTICE=1` to hide the notice. Notices are also disabled in CI and when stderr is not a terminal. +## Release and bundle provenance + +A published package contains several independently versioned layers. The npm +package version is the release anchor, while the bundled plugin and the Codex +runtime dependencies have their own version fields: + +| Layer | Source of truth | What it identifies | +| -------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------- | +| npm package | `sdk/typescript/package.json` and the `npm-vX.Y.Z` tag | The published SDK and CLI release | +| bundled plugin | `_bundled_plugin/.codex-plugin/plugin.json` and `BUNDLED_PLUGIN_VERSION` | The plugin manifest and compatibility version, not a content hash | +| Codex runtime | `@openai/codex` and `@openai/codex-sdk` in `package.json` | The runtime and SDK dependency versions used by the package | + +For an exact, byte-for-byte reference to the bundled plugin, use its Git tree +object at the release tag. For example, replace `0.1.5` with the release you +are checking: + +```bash +VERSION=0.1.5 +TAG="npm-v${VERSION}" + +git rev-parse "${TAG}^{commit}" +git rev-parse "${TAG}:sdk/typescript/_bundled_plugin" +git show "${TAG}:sdk/typescript/package.json" | jq -r .version +git show "${TAG}:sdk/typescript/_bundled_plugin/.codex-plugin/plugin.json" | jq -r .version +``` + +The first two values form the immutable release-to-bundle mapping. The npm +registry also records the published package's release commit and integrity +metadata: + +```bash +npm view "@openai/codex-security@${VERSION}" version gitHead dist.integrity +``` + +`bundledPluginVersion` in `codex-security info --json` is useful diagnostic +metadata, but it does not replace the bundled tree hash. A runtime or catalog +version supplied by the Codex distribution is external to this repository and +cannot be inferred from the npm tag or the plugin manifest. Record that value +from the runtime's own release metadata alongside the package tag and bundled +tree hash when producing a provenance report. + ## Run a scan from TypeScript Sign in with `npx @openai/codex-security login` or set `OPENAI_API_KEY` or From 29e0bed158e80f7e99659772d6816b8dd4bcbae1 Mon Sep 17 00:00:00 2001 From: Mr-Neutr0n Date: Thu, 13 Aug 2026 19:19:36 +0530 Subject: [PATCH 2/2] docs(release): clarify provenance verification Signed-off-by: Mr-Neutr0n --- sdk/typescript/README.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md index b186e88d..2d427d29 100644 --- a/sdk/typescript/README.md +++ b/sdk/typescript/README.md @@ -52,13 +52,35 @@ git show "${TAG}:sdk/typescript/_bundled_plugin/.codex-plugin/plugin.json" | jq ``` The first two values form the immutable release-to-bundle mapping. The npm -registry also records the published package's release commit and integrity -metadata: +registry exposes release metadata that is useful for inspection: ```bash npm view "@openai/codex-security@${VERSION}" version gitHead dist.integrity ``` +This metadata is not signed provenance verification. To verify the published +package cryptographically, use npm's signature and attestation audit and the +release workflow's SLSA checks: + +```bash +npm audit signatures \ + --prefix "$CONSUMER_DIR" \ + --registry=https://registry.npmjs.org/ \ + --json \ + --include-attestations +``` + +The audit must identify the public npm registry, an SLSA v1 attestation, the +exact package tarball, the protected release workflow, and the release commit. +The `npm view` fields and `dist.integrity` value are useful cross-checks, but a +matching registry record alone does not prove who built or signed the package. + +The first two historical npm releases, `0.1.0` and `0.1.1`, may omit `gitHead` +from their registry metadata. For those versions only, the release workflow +recovers the commit from verified SLSA provenance and then performs the normal +integrity and provenance checks. Every later release must publish a matching +40-character `gitHead`; a missing or mismatched value fails verification. + `bundledPluginVersion` in `codex-security info --json` is useful diagnostic metadata, but it does not replace the bundled tree hash. A runtime or catalog version supplied by the Codex distribution is external to this repository and