# Supply-Chain Integrity

*"If you cannot verify what you are running, you are not running what you think you are."*

## Overview

Aura's supply-chain posture is built around a single principle: every artifact you execute should be independently verifiable against a signed, reproducible source of truth. Binaries are signed. Builds are deterministic. SBOMs are published. Dependency audits run in CI. The running binary can verify itself via `aura self-verify`. None of this requires trust in Naridon, Inc.'s infrastructure; all of it can be cross-checked by a third party.

This matters because supply-chain attacks have become the dominant vector against developer tooling. A single compromised package, a single unsigned release, a single tampered CI pipeline can ship backdoored code to every user of a popular tool. Aura is a security tool. A compromised Aura binary would be worse than no Aura at all. The controls documented here exist so that you can, with modest effort, satisfy yourself that the binary on your disk is the one we shipped.

## Threat Scope

The supply-chain threat model addresses five adversary capabilities:

1. **Distribution-channel tampering** — an attacker modifies a release artifact after we sign it but before you download it. Defended by minisign signatures verified against a public key pinned by your install procedure.
2. **Build-infrastructure compromise** — an attacker tampers with our CI to produce a backdoored binary that is nevertheless signed by our release key. Defended by reproducible builds: anyone with the source and toolchain fingerprint can rebuild and compare hashes.
3. **Dependency compromise** — a malicious or compromised crate introduces hostile behavior upstream of our code. Defended by `cargo-audit`, dependency review, and (for security-critical crates) vendoring or pinning to specific commits.
4. **Toolchain compromise** — the Rust compiler or standard toolchain is backdoored. Defended partially by reproducible builds against the pinned toolchain; a toolchain-level Trusting Trust attack remains a non-trivial concern for any compiled-language project.
5. **Self-update channel abuse** — the `aura self-update` mechanism is subverted to deliver a malicious version. Defended by signature verification at the download stage; the self-update process will refuse any binary not signed by the release key.

See the [threat model](/threat-model) for how these defenses compose with the rest of the system.

## Mechanism

### Signed releases

Every Aura release artifact is signed with minisign, an Ed25519-based scheme chosen for its simplicity, small signature size, and lack of web-of-trust complexity. The public key is published in the Aura repository root (`RELEASE_SIGNING_KEY.pub`), on the Naridon website, and baked into binaries as a hardcoded constant used by `aura self-verify`.

Release artifacts — per platform — are published alongside:

- `aura-<version>-<platform>.tar.gz` — the binary and supporting files
- `aura-<version>-<platform>.tar.gz.minisig` — minisign signature
- `aura-<version>-<platform>.tar.gz.sha256` — SHA-256 hash for quick comparison
- `SBOM-<version>.spdx.json` — Software Bill of Materials in SPDX format
- `SBOM-<version>.cyclonedx.json` — SBOM in CycloneDX format

Verify manually:

```bash
minisign -Vm aura-0.14.1-linux-x86_64.tar.gz \
  -P $(cat RELEASE_SIGNING_KEY.pub)
```

A successful verification is required before Aura will install or self-update. An install script that skips this step is unsupported; we publish detection patterns so you can flag such scripts in code review.

### Reproducible builds

Given identical source and identical toolchain, the compiled Aura binary is byte-for-byte identical across build hosts. Specifically:

- The Rust toolchain version is pinned in `rust-toolchain.toml` and fingerprinted in the release manifest.
- Cargo's `--locked` mode is used for all release builds; `Cargo.lock` is authoritative.
- Build timestamps are zeroed (`SOURCE_DATE_EPOCH` is set to the commit time of the release tag).
- Paths baked into debug info are normalized via `--remap-path-prefix`.
- Link order is deterministic under the pinned linker.
- Any randomness in the build process (rare in Rust, but possible in proc-macro crates) is identified and patched or eliminated.

To reproduce:

```bash
git clone https://github.com/Naridon-Inc/aura
cd aura
git checkout v0.14.1
./scripts/reproduce-build.sh
sha256sum target/release/aura
# Compare against the published hash in aura-0.14.1-linux-x86_64.tar.gz.sha256
```

The `scripts/reproduce-build.sh` script sets the environment variables and flags required for reproducibility. On the three officially supported platforms (Linux x86_64, Linux arm64, macOS arm64), a matching hash is expected. On other platforms, reproducibility is best-effort.

Independent rebuilders are welcome. If your organization runs a mirror of the build and publishes its own signatures, you strengthen the overall ecosystem. Naridon will list known-good reproducers in the release notes.

### SBOMs

Two SBOM formats ship with every release:

- **SPDX 2.3** — the ISO/IEC 5962:2021 format, favored by regulators.
- **CycloneDX 1.5** — the OWASP format, with better tooling in the Rust ecosystem.

The SBOM enumerates every crate in the dependency graph with its exact version, source (crates.io / git), license, and file hashes. This is what your procurement review or your NIS2 compliance officer will ask for.

Generating your own SBOM from source:

```bash
cargo sbom --format spdx > aura.spdx.json
cargo sbom --format cyclonedx > aura.cdx.json
```

(`cargo-sbom` is a Rust tool that follows SPDX/CycloneDX semantics; the output matches the shipped SBOM byte-for-byte when run against the tagged commit.)

### Dependency audit

CI runs `cargo audit` on every commit against the RustSec advisory database. A known advisory on a transitive dependency fails the build. The policy is:

- **Critical / High** — release blocker. Must be fixed or upstream-patched before release.
- **Medium** — tracked issue; target fix within one minor release.
- **Low / Informational** — tracked; fix opportunistically.

Advisories discovered after release are reported via our [security disclosure](/security-disclosure) channel and, where appropriate, trigger a patch release rather than a feature release.

In addition to `cargo audit`, release candidate builds run:

- `cargo deny` against a strict license allowlist (rejecting GPL-family licenses that would be incompatible with Apache 2.0 downstream).
- `cargo tree --duplicates` to surface dependency-version fragmentation.
- Manual review of any newly added transitive dependency not previously present in the tree.

### `aura self-verify`

The running binary can verify itself:

```bash
aura self-verify
```

Sample output:

```text
aura 0.14.1
  binary sha256:       4f3a9b21c7d8...e4c1
  expected sha256:     4f3a9b21c7d8...e4c1   OK
  release signature:   ed25519:3a1f...b9c2   OK
  toolchain fingerprint: rustc 1.78.0 (9b00956)  OK
  build timestamp:     2026-04-02T10:24:00Z (zeroed epoch match)
  sbom checksum:       blake3:7c2d...f1a3   OK

self-verify: all checks passed
```

`self-verify` hashes its own on-disk file (reading it fresh from disk, not relying on in-memory state), compares against the hardcoded expected hash for the build, verifies the minisign signature against the hardcoded public key, and cross-checks the toolchain fingerprint. A failure at any step exits non-zero with a specific error code, suitable for use in host-integrity monitoring.

This check is particularly valuable on CI hosts and on shared developer images. If `aura self-verify` ever fails on a host that previously passed, treat it as a compromise indicator.

### Self-update

The `aura self-update` subcommand:

1. Queries the release server for the latest version.
2. Downloads the release artifact and `.minisig` signature.
3. Verifies the signature against the pinned public key.
4. Verifies the SHA-256 checksum against the separate `.sha256` file.
5. Atomically replaces the binary (using a same-filesystem rename).
6. Runs `self-verify` on the new binary.
7. Rolls back if any step fails.

The pinned public key in the running binary is the root of trust for this process. An attacker who can replace the release artifact but cannot forge a signature against that key cannot deliver a malicious update.

Self-update is opt-in. Deployments that prefer explicit upgrades (most production environments) should leave it disabled and roll out new versions through their standard packaging pipeline.

## Configuration

Supply-chain-relevant configuration:

```toml
[updates]
# Automatic check on start. Disable in production.
auto_check = false
# Channel: "stable" | "beta"
channel = "stable"

[verify]
# Run self-verify on every start. Adds ~200ms to startup.
on_start = false
# Refuse to run if self-verify fails
refuse_on_mismatch = true
```

For air-gapped deployments, disable updates entirely and verify builds manually from your internal mirror. See [air-gapped install](/air-gapped-install) for the full procedure.

Example CI pipeline step for artifact verification:

```bash
set -euo pipefail

VERSION=0.14.1
PLATFORM=linux-x86_64
BASE=https://releases.naridon.com/aura/${VERSION}

curl -fsSLO ${BASE}/aura-${VERSION}-${PLATFORM}.tar.gz
curl -fsSLO ${BASE}/aura-${VERSION}-${PLATFORM}.tar.gz.minisig
curl -fsSLO ${BASE}/aura-${VERSION}-${PLATFORM}.tar.gz.sha256

sha256sum -c aura-${VERSION}-${PLATFORM}.tar.gz.sha256
minisign -Vm aura-${VERSION}-${PLATFORM}.tar.gz -P "$(cat ~/.aura/release-key.pub)"

tar xzf aura-${VERSION}-${PLATFORM}.tar.gz
./aura self-verify
```

## Limitations

- **We cannot eliminate Trusting Trust concerns.** A compromised rustc could inject backdoors invisible to source review. Defending against this requires diverse double-compilation, which we do not currently perform. It is a known gap in virtually every compiled-language ecosystem.
- **Transitive trust extends to crates.io.** We do not mirror crates.io internally. A compromise of that registry affects us as it would affect any Rust project. We mitigate via lockfile pinning and the `cargo-audit` pipeline, but these are detective rather than preventive.
- **Reproducible builds cover the three officially supported platforms.** Builds on other platforms may differ due to toolchain variation.
- **`aura self-verify` verifies the binary, not the configuration.** A host with a tampered `aura.toml` but a pristine binary will pass self-verify. Monitor configuration separately.
- **Naridon is not SOC 2 Type II audited.** We publish the controls above for independent review; we do not hold a formal attestation. Regulated deployments integrating Aura should attest against their own deployment, which can use these controls as evidence.
- **Naridon's internal build infrastructure is a trust anchor.** A compromise of our CI, combined with a compromise of the signing key custody, would allow a malicious signed release. Reproducible builds mean independent rebuilders can detect this; we encourage the practice.

## See Also

- [Threat model](/threat-model) — supply-chain adversary class
- [Cryptographic design](/cryptographic-design) — minisign and signing key lifecycle
- [Air-gapped install](/air-gapped-install) — offline verification workflow
- [Security disclosure](/security-disclosure) — reporting supply-chain issues
- [Compliance and audit](/compliance-and-audit) — using SBOMs for regulatory evidence
- [Incident response](/incident-response) — responding to a compromised binary