# Supply chain

Documentation version: 0.3.1.

SourceOrrery runs inside every application that reads a secret with it, so
a tampered package would be as dangerous as a tampered vault. This page
describes how the source becomes the packages you install, what stops
someone altering them on the way, how to check what you installed, and
what is not done yet. The [threat model](https://sourceorrery.ai/security/threat-model/) covers the vault
itself.




> [!NOTE]
> This page describes the release workflow of **0.3.1**. Verify the actual
> package's version, workflow run and available attestations when installing;
> a configured publishing method is not itself proof about a downloaded file.

## From commit to package

* **Checks matched to the change.** Code changes trigger formatting,
  Clippy with warnings as errors, tests on Ubuntu, Windows and macOS,
  SDK tests and the cross-language conformance harness against a real
  vault, and an audit of every dependency graph
  ([below](https://sourceorrery.ai/security/supply-chain/#dependency-audit)). The `CI` gate aggregates those jobs. Documentation-only changes may skip the
  native builds; the documentation workflow builds and link-checks the site.
* **One workflow, one commit, every package.** A release is cut by
  dispatching `.github/workflows/release.yml` by hand, never by pushing a
  tag. One run builds the CLI and the C ABI for six targets and every SDK
  package from a single commit, creates the GitHub Release with
  `SHA256SUMS`, and publishes to each registry. No package is uploaded
  from a developer's machine. The procedure is in [Releasing](https://sourceorrery.ai/reference/release/).
* **Locked dependencies.** CI and the release build with `cargo --locked`
  against the committed `Cargo.lock` (the Python and Node extensions have
  lock files of their own) and with `npm ci` against `package-lock.json`.
  A dependency changes only in a commit that changes a lock file.
* <a id="dependency-audit"></a>**Every dependency graph audited.** The
  `dependency audit` CI job runs `scripts/ci/dependency-audit.py` over
  each graph resolved on its own, and fails on a known vulnerability, on
  a scanner or advisory service that fails (an unavailable scan is never
  a pass), and on a lock file or package manifest under version control
  that its inventory does not cover:

  | Graph | Checked with |
  |---|---|
  | `Cargo.lock`, `bindings/python/Cargo.lock`, `bindings/node/Cargo.lock` | `cargo audit` (RustSec) |
  | `package-lock.json` of `site/`, `bindings/node/`, `scripts/coverage/`, `scripts/ci/lstk/` | `npm audit --package-lock-only` (no install; the site's private icon registry is not needed) |
  | `bindings/python/ci-requirements.txt`, `scripts/coverage/requirements.txt` (hash-pinned) | the OSV.dev API, every pin |
  | `bindings/python/pyproject.toml` | no runtime dependencies; its build requirement is pinned above |
  | `bindings/java/pom.xml` | the OSV.dev API, direct dependencies and plugins (the transitive graph needs Maven; Dependabot follows it) |
  | the `.csproj` files | the OSV.dev API, direct package references (the transitive graph needs the .NET SDK; Dependabot follows it) |
  | `bindings/go/go.mod`, `composer.json`, `bindings/cpp/CMakeLists.txt`, the npm platform packages | no third-party dependency; the audit fails if one appears |

  A **maintenance notice** (RustSec's "unmaintained") is not a
  vulnerability and is not fixed by calling it one. Each one is reviewed in
  the script's `REVIEWED` table with an owner by role, the upstream issue,
  the upgrade that removes it and what makes it due again; an unreviewed
  notice is a warning in CI and fails a release (`--strict`). Reviewed now:

  | Advisories | Through | Owner | Upstream | Removed by | Revisit |
  |---|---|---|---|---|---|
  | RUSTSEC-2026-0370 (`zvariant`), -0371 (`zbus_names`), -0372 (`zvariant_derive`) | `sourceorrery-storage` → `zbus-secret-service-keyring-store` 1.0.1 → `secret-service` 5.2.0 → `zbus` 5.19 (the Linux credential store) | maintainer of the storage keystore | [z-galaxy/zbus#2043](https://github.com/z-galaxy/zbus/issues/2043): merged into `zbus` 6 | `secret-service` and the keyring store on `zbus` 6 | their release on `zbus` 6 (a Dependabot cargo update); the upgrade gets the Linux keyring smoke test and the MSRV build |
* **Pinned actions, automated updates.** Every third-party GitHub Action
  the workflows use is referenced by the full commit SHA of a release,
  with the version as a comment, so a moved or compromised tag cannot
  change what runs in CI or in a release build. Dependabot
  (`.github/dependabot.yml`) opens a weekly grouped pull request per
  ecosystem for the actions and for the Rust, npm, Python, NuGet and
  Maven dependencies (Rust lock files only; a range change is a deliberate
  commit), and the `workflows` CI job runs zizmor over `.github/` so an
  unpinned action or a shell step that expands an input fails the gate.
* **Bills of materials and auditable binaries.** Every release carries a
  CycloneDX document per shipped binary and target, and the CLI and the C
  ABI library are built with `cargo auditable`, which embeds their
  dependency list in the binary ([below](https://sourceorrery.ai/security/supply-chain/#software-bill-of-materials)).
* **Immutable versions.** The workflow refuses a tag that already exists.
  A version is never rebuilt or replaced; a mistake is fixed by the next
  patch version.
* **No cryptography of our own.** Every primitive comes from the RustCrypto
  crates ([architecture](https://sourceorrery.ai/architecture/#storage-cryptography-and-audit)).

## Trusted publishing

With trusted publishing, a registry is told once which repository and
which workflow file may publish a package. At release time the publishing
job presents an identity token that GitHub signs for that one workflow run
(OpenID Connect), and the registry exchanges it for a short-lived publishing
credential under the configured trust policy. The workflow does not need a
stored long-lived token for those registries. npm and PyPI also record a **provenance**
statement, signed through Sigstore, that ties each published file to the
commit and the workflow run that built it.

The npm, PyPI, crates.io and NuGet packages have trusted publishers
configured for `release.yml` and `ReleasePackages.yaml` in
`Netizine/sourceorrery`. Normal 0.3.1 releases use those policies, including
the Azure provider and OS helper crate; no first-publication bootstrap is
required. Other distribution channels use their mechanisms listed below.

| Registry | Package | Published with | What you can check |
|----------|---------|----------------|--------------------|
| npm | `@sourceorreryai/sdk` and its six platform packages | Trusted publishing | Provenance and registry signatures |
| PyPI | `sourceorrery` | Trusted publishing | An attestation for every file, and its SHA-256 against the release |
| crates.io | the eleven publishable `sourceorrery*` crates | Trusted publishing (a token that lives 30 minutes) | The checksums in `Cargo.lock` |
| NuGet | `SourceOrrery` | Trusted publishing (a key that lives one hour) | nuget.org's repository signature |
| Maven Central | `ai.sourceorrery:sourceorrery` | The workflow uses a Central publishing token and signs each file with the release key | The `.asc` signature next to each file |
| Go module proxy | `github.com/netizine/sourceorrery/bindings/go` | Nothing uploaded: the tag `bindings/go/vX.Y.Z` | The Go checksum database |
| Packagist | `sourceorrery/sourceorrery` | Nothing uploaded: the tag `vX.Y.Z` | The commit recorded in `composer.lock` |
| GitHub Release | CLI and C ABI archives, wheels, jar, `.nupkg`, npm tarballs, `SHA256SUMS` | The release workflow | A build provenance attestation per file (`gh attestation verify`), `SHA256SUMS`, and the workflow run linked from the release |
| Homebrew tap | `sourceorrery` in `Netizine/homebrew-sourceorrery` | Nothing uploaded: the release workflow commits a formula naming the release archive for each platform and its SHA-256 | Homebrew checks the hash before installing; the formula is a readable file in the tap |
| Scoop bucket | `sourceorrery` in `Netizine/scoop-sourceorrery` | Nothing uploaded: the release workflow commits a manifest naming the release archives and their SHA-256 | Scoop checks the hash before installing |
| WinGet | `Netizine.SourceOrrery` | A pull request on `microsoft/winget-pkgs` with manifests naming the release archives and their SHA-256, validated there | WinGet checks `InstallerSha256` before installing |

The wheels and sdist on PyPI, the npm tarballs and the jar on Maven
Central are byte for byte the files attached to the GitHub Release, so
their SHA-256 hashes appear in its `SHA256SUMS`. Comparing the copies can
detect a mismatch between the registry and release, but both originate in
the same build workflow: a compromised workflow could publish matching
malicious files to both. Check provenance as well as hashes. The
`.nupkg` on nuget.org differs from the release's only by the repository
signature nuget.org adds.

## Checking what you installed

### npm

In a project that depends on `@sourceorreryai/sdk`:

```bash
npm audit signatures
```

It checks the registry signature of every installed package and the
provenance of those that carry one; the SourceOrrery packages count among
the *verified attestations*. The package page on npmjs.com shows the same
provenance, with links to the commit and the workflow run.

### NuGet

```bash
dotnet nuget verify --all ~/.nuget/packages/sourceorrery/0.3.1/sourceorrery.0.3.1.nupkg
```

Expect `Signature type: Repository` with the subject
`NuGet.org Repository by Microsoft`.

### Maven Central

Every file is signed with the SourceOrrery release key:

```text
F14C 928F CC55 C651 7F1A  E1E7 DAFA E59A 4372 DBC2
```

```bash
gpg --keyserver keyserver.ubuntu.com --recv-keys F14C928FCC55C6517F1AE1E7DAFAE59A4372DBC2
curl -LO https://repo1.maven.org/maven2/ai/sourceorrery/sourceorrery/0.3.1/sourceorrery-0.3.1.jar
curl -LO https://repo1.maven.org/maven2/ai/sourceorrery/sourceorrery/0.3.1/sourceorrery-0.3.1.jar.asc
gpg --verify sourceorrery-0.3.1.jar.asc sourceorrery-0.3.1.jar    # Good signature from "SourceOrrery Releases ..."
```

### PyPI

Each file published by trusted publishing carries an attestation, shown
under *Provenance* on the file's page on pypi.org with the repository,
workflow and commit that built it. To check one yourself:

```bash
pip install pypi-attestations
pypi-attestations verify pypi --repository https://github.com/Netizine/sourceorrery \
    pypi:sourceorrery-<version>-cp311-abi3-manylinux_2_28_x86_64.whl
```

To make sure every install gets exactly those files, pin the hashes. Each
file's SHA-256 is on its PyPI page and in the release's `SHA256SUMS`;
check that the two agree, then require them:

```text
# requirements.txt
sourceorrery==0.3.1 \
    --hash=sha256:<hash of the wheel for each platform you deploy to>
```

```bash
pip install --require-hashes -r requirements.txt
```

`pip-compile --generate-hashes` (pip-tools) and
`uv pip compile --generate-hashes` write those lines for you from PyPI.

### Cargo

`Cargo.lock` records the checksum of every crate, and Cargo verifies it on
every build. Install the CLI with `--locked`:

```bash
cargo install --locked sourceorrery-cli --version 0.3.1
```

The crate ships the lock file the release was built and tested with;
without `--locked`, Cargo resolves the newest compatible version of every
dependency at install time instead.

### Go

Nothing to do. The `go` command checks every module version against the
checksum database at `sum.golang.org` and records it in `go.sum`; a
published version can never change.

### Composer

Packagist serves the repository at the release tag, and `composer.lock`
records the commit it installed. Compare it with the tag:

```bash
git ls-remote https://github.com/Netizine/sourceorrery refs/tags/v0.3.1
```

### Release archives

Every file on a GitHub Release, `SHA256SUMS` included, carries a **build
provenance attestation**: a statement signed through Sigstore in the
release workflow run, stored with the repository, naming the file's
SHA-256, the commit and the workflow that built it. Check a download
against it with the GitHub CLI (signed in, or `--owner` for a public
repository without signing in):

```bash
gh attestation verify sourceorrery-0.3.1-x86_64-unknown-linux-gnu.tar.gz --repo Netizine/sourceorrery
```

The command fails for a file that was altered after the build or that did
not come out of `release.yml` in `Netizine/sourceorrery`. It proves origin
on a GitHub-hosted runner; it does not make the code safe, and no
reproducible-build claim is made. The attestations are listed under
*Attestations* on the repository's *Actions* tab as well.

`SHA256SUMS` next to the archives proves a download is intact without the
GitHub CLI, as [Getting started](https://sourceorrery.ai/getting-started/)
shows; for the files that are also on a registry, compare with the
registry's hash as above.

### Software bill of materials

Every GitHub Release carries one [CycloneDX](https://cyclonedx.org) 1.5
document (`*.cdx.json`) per shipped binary and target, listed in
`SHA256SUMS` and covered by the provenance attestation like every other
file:

| File | Describes |
|------|-----------|
| `sourceorrery-X.Y.Z-<target>.cdx.json` | the `sourceorrery` CLI binary in the archive of the same name |
| `sourceorrery-ffi-X.Y.Z-<target>.cdx.json` | the C ABI library (`libsourceorrery_ffi.*`, `sourceorrery_ffi.dll`) in the `sourceorrery-ffi` archive, and the same library as embedded in the Java jar, the .NET package and the Go, C, C++ and PHP SDKs |
| `sourceorrery-python-X.Y.Z-<target>.cdx.json` | the extension module inside the Python wheel for that platform |
| `sourceorrery-node-X.Y.Z-<target>.cdx.json` | the addon inside the `@sourceorreryai/sdk-<platform>` package |

Each lists every Rust crate compiled into that binary for that target,
with name, version, licence and
[package URL](https://github.com/package-url/purl-spec) (`pkg:cargo/…`),
and the dependency graph between them; build-time-only dependencies are
left out. The documents are rendered from the lock files by
`cargo cyclonedx` in the release workflow, so they describe exactly what
`cargo --locked` built. The language-level wrappers around the C ABI (the
jar, the NuGet package, the npm main package, the Go module, the PHP
package) have no third-party runtime dependencies of their own, so no
separate document is published for them.

```bash
jq -r '.components[] | "\(.name) \(.version) \(.licenses[0].license.id // "")"' sourceorrery-0.3.1-x86_64-unknown-linux-gnu.cdx.json
```

The CLI and the C ABI library are also built with
[`cargo auditable`](https://github.com/rust-secure-code/cargo-auditable),
which embeds the same dependency list in the binary itself, so a binary
on disk can be checked against the RustSec advisory database without its
SBOM:

```bash
cargo install cargo-audit --locked
cargo audit bin ./sourceorrery
```

## What SourceOrrery changes in your own supply chain

A malicious dependency, a poisoned install script or a misled coding agent
may look for credentials in plain files: `.env`, configuration files or
shell history. Replacing plaintext configuration with vault references
reduces that exposure after the original files and copies are removed.
It does not change these limits:

* **Code running as you can open the vault as you.** An install script or
  an agent runs with your user's rights, so it can run the CLI and open
  any vault you can open without typing anything: this machine's key opens
  it silently, and `run` never asks the view check. Elsewhere a vault opens
  only where its recovery key is available. Keep production secrets in
  vaults that development machines cannot open, and keep
  `SOURCEORRERY_RECOVERY_KEY` out of shells that install packages. The
  authenticated broker (milestone 3) is what will change this
  ([threat model](https://sourceorrery.ai/security/threat-model/#the-three-guarantees)).
* **Code inside your application reads what your application reads.** A
  compromised dependency can read every secret the application can. What
  it cannot do through an SDK is write: no SDK can set, disable, delete or
  purge a secret, change the vault's keys, checks or connections, or
  manage the audit log
  ([ADR 0005](https://sourceorrery.ai/decisions/0005-read-only-sdks/)), so it cannot plant a value for
  the next deployment through the library. Every read is recorded in the
  vault's audit log, which `sourceorrery audit` shows.
* **`sourceorrery run` hands values to every dependency in the child.** It
  puts them in the environment of the process it starts. An SDK keeps each
  value in the process that asked for it, in a guarded buffer, until it is
  closed.

## Not done yet

> [!WARNING]
> Checksums and provenance do not establish that code is safe. The
> binaries are not notarised or Authenticode-signed, and no
> reproducible-build claim is made.

* Maven Central's checked-in upload uses a stored publishing token and
  GPG signatures. Registry trust does not replace that workflow mechanism.
* macOS binaries are not signed or notarised; Windows binaries are not
  Authenticode-signed.
* No claim of reproducible builds is made: an SBOM and an attestation say
  what was built from which commit, not that a second build would be
  byte-for-byte the same.

These are on the [roadmap](https://sourceorrery.ai/roadmap/). To report a package you suspect
was tampered with, follow the
[security policy](https://github.com/Netizine/sourceorrery/blob/main/SECURITY.md): email security@sourceorrery.ai, not a
public issue.
