Security: define dependency provenance and reproducible audit policy

[Joaco2603]

Problem

The contracts depend on OpenZeppelin Stellar Contracts from Git tag v0.7.1. Cargo.lock pins the resolved commit, but the repository has no enforceable policy for reviewing dependency updates, proving the source of the resolved revision, or managing audit exceptions.

Smart-contract dependencies are part of the trusted computing base: an unreviewed Git revision or an undocumented advisory exception can change contract behavior before the WASM is built.

Required outcome

Establish a reproducible, enforceable dependency-supply-chain policy for the Rust/Soroban workspace.

Dependency provenance controls

• Determine and document whether compatible crates.io releases exist and whether they are preferable to the current OpenZeppelin Git dependencies.
• If Git dependencies remain, pin every OpenZeppelin package to the same reviewed immutable revision; keep the human-readable tag only as documentation, not as the sole trust boundary.
• Create a machine-readable allowlist/manifest of approved Git source URL, repository owner, tag, resolved commit, packages, and review date.
• Add a verification command that compares Cargo.toml, Cargo.lock, and the allowlist, failing when a Git dependency is added, removed, retargeted, or resolved to an unapproved commit.
• Require dependency-update PRs to include the upstream release/commit diff, compatibility assessment, security impact, and an intentional lockfile update.

Audit and CI controls

• Keep cargo audit in CI and provide a reproducible local make audit path.
• Add a checked-in, documented advisory-exception policy: every ignored/yanked advisory needs a rationale, owner, review/expiry date, and CI must fail when the exception expires.
• Run the provenance verification and audit as distinct, named CI steps before build/test output is trusted.
• Ensure CI triggers when dependency-policy files, Cargo manifests/lockfile, Makefile, or workflow configuration change.
• Produce CI logs/artifacts that identify the exact Rust toolchain, host target, lockfile hash, and approved Git revision used for the verification run.

Operational documentation

• Document the trusted dependency sources, immutable revisions, review workflow, local verification commands, and emergency rollback procedure in the README or security documentation.
• Define a maintainer procedure for rotating a compromised dependency revision and regenerating/reviewing the lockfile.

Acceptance criteria

• cargo build --workspace passes with the approved lockfile.
• cargo test --workspace passes using the documented host target.
• cargo audit passes in CI and locally through the documented command.
• The provenance verifier fails in tests/CI for an unapproved Git URL, package, tag, or resolved commit, and passes for the approved dependency graph.
• All OpenZeppelin Git packages resolve to one documented immutable commit, or their crates.io replacement and version constraints are documented and tested.
• The policy manifest and Cargo.lock are synchronized; a stale manifest or lockfile mismatch fails deterministically.
• Advisory exceptions are checked in, justified, time-bounded, and cause CI failure after expiry.
• CI has separate, visible provenance, audit, build, test, clippy, and format evidence.
• README/security documentation explains dependency updates, audits, provenance verification, incident rollback, and the exact local commands.
• The implementation does not silently change the deployed contracts' public API or token/marketplace behavior.

Non-goals

• Replacing every third-party dependency or building a custom package registry.
• Claiming a Git tag alone is immutable provenance.
• Suppressing audit findings without a time-bounded, reviewed exception.

[Tobi-8]

oh, i have done this exact same thing before.
kindly assign

[Flourishbar]

Hi maintainer. I want to apply for this issue because supply-chain security and dependency integrity are critical for the reliability of smart contract projects. With my experience working with Rust ecosystems, dependency management, and CI/CD workflows, I can evaluate whether the OpenZeppelin Stellar dependencies can be safely migrated to crates.io, implement integrity verification where Git dependencies remain necessary, integrate cargo audit into the CI pipeline, and document the dependency strategy and associated risks to improve the project's long-term security and maintainability.

[AbuJulaybeeb]

Hi Maintainer, I have reviewed the description of the issue and would like to hop on this issue and deliver ETA

[Mac-5]

Hi — I'd like to take this one.

Understanding of the task

Right now the workspace depends on OpenZeppelin Stellar Contracts via a Git dependency pinned to tag v0.7.1, resolved in Cargo.lock to commit 3f81125bed3114cc93f5fca6d13240082050269a. Cargo.lock already correctly records that resolved revision — the gap isn't that the lockfile is missing or wrong, it's that there's no written policy for how that pin gets reviewed, updated, or verified, and no CI step catching known-vulnerable dependencies.

Proposed approach

Check for a crates.io release. Confirm whether OpenZeppelin's Stellar Contracts are published on crates.io at or near v0.7.1. If a crates.io release exists and is equivalent to the tag, document that as the preferred source (crates.io releases are immutable and easier to verify than a moving Git ref). If not available yet, document that explicitly and keep the Git dependency as the interim source of truth.
If the Git dependency stays:
Add a CONTRIBUTING.md (or a section in README.md) stating that any change to the rev/tag for this dependency requires a PR that (a) shows the diff of the upstream release notes, (b) is reviewed by a second contributor, and (c) includes a fresh cargo build --workspace / cargo test --workspace run.
Confirm Cargo.lock is committed and that CI fails the build if Cargo.lock would change (cargo build --locked), so the resolved commit can't drift silently.
CI: cargo audit. Add a GitHub Actions job that runs cargo audit against the workspace on every PR and on a schedule (e.g. weekly), using cargo-audit with the RustSec advisory DB. Provide the equivalent local command so it's reproducible outside CI:
cargo install cargo-audit --locked
cargo audit
Documentation. Add a short "Dependency Policy" section to README.md recording:
Expected source (crates.io vs. Git) for OpenZeppelin Stellar Contracts
Current pinned tag (v0.7.1) and commit (3f81125bed3114cc93f5fca6d13240082050269a)
The review process for bumping it
The cargo audit command and where it runs in CI

Acceptance criteria I'll target

cargo build --workspace passes
cargo test --workspace passes
cargo audit passes in CI
README documents the dependency source/commit, update policy, and audit workflow

Relevant background

I've worked in this repository before — issue #7 (cross-contract auth testing for buy_prompt → sell_forwarded and remint → mint_forwarded), so I'm already familiar with the workspace layout and CI setup. I do smart contract security auditing across EVM/Rust/Move ecosystems, including Soroban, and this kind of supply-chain/provenance hardening is squarely in that wheelhouse.