RS-Key

The upgrade path is the product: flashing the newest release replaces the firmware in place, and an already-provisioned device keeps its credentials across the upgrade — a persistent-format change must load older record layouts forward and say how. The one case where that does not hold is documented at the top of the CHANGELOG with the export step to take first. There are no maintained release branches, stated in SECURITY.md; supported means the tip of main.

GitHub Issues, with issue templates:
https://github.com/TheMaxMur/RS-Key/issues

No externally reported vulnerability has been resolved in the last 12 months, so
there is nobody yet to credit. SECURITY.md invites private reports and treats the
reporter's name as theirs to give or withhold.
https://github.com/TheMaxMur/RS-Key/blob/main/SECURITY.md

SECURITY.md documents the whole path: report privately through GitHub's private
vulnerability reporting, what counts as a vulnerability here and what the threat
model already concedes, what a good report contains, what to expect (an
acknowledgment within a few days from one maintainer, a fix on main as fast as
severity warrants), and which versions are supported.
https://github.com/TheMaxMur/RS-Key/blob/main/SECURITY.md

CONTRIBUTING.md and AGENTS.md state the standards contributions must meet:
rustfmt formatting, clippy with -D warnings, no_std and no allocator in firmware
crates, unsafe only with an entry in docs/unsafe.md, an SPDX header on every
file, comments that explain constraints rather than mechanics with a three-line
ceiling, no magic values, typed state instead of string matching, and the Python
conventions for the host CLI.
https://github.com/TheMaxMur/RS-Key/blob/main/CONTRIBUTING.md

Mechanically, in the gate and in the pre-commit hook: cargo fmt --check across
every workspace including the detached ones, clippy with -D warnings on the
embedded, host, TUI, emulator and fuzz targets, and rustdoc with
RUSTDOCFLAGS=-D warnings. CI runs the same script, so a style violation cannot be
merged.

The relevant conventions here are cargo's, and they are honored: RUSTFLAGS, the
target triple, CARGO_TARGET_*_LINKER and the standard profile settings all work
as expected for both the firmware and the native host tools. The one C/assembly
unit is a bare-metal cross-compile for thumbv8m and deliberately pins
arm-none-eabi-gcc, because the dev shell's host CC cannot produce a loadable
object for a Cortex-M33 — honoring an injected CC there would yield a firmware
image that does not boot.

The release profile keeps full debug info (debug = 2) on purpose; the UF2 that
gets flashed is unaffected because debug info is not part of the flashed image,
and the gate itself reads symbol names out of the ELF. Nothing strips.

Cargo workspaces, not recursive make. The dependency graph is explicit in the
manifests, checked by scripts/crate_graph.py to be strictly tiered with no
sideways edges, and enforced by cargo-deny. Nothing recurses into subdirectories
to guess at ordering.

nix build .#firmware is hermetic: the toolchain, the target and every tool are
pinned by flake.lock, and dependencies by Cargo.lock. A scheduled repro job in
the deep-checks workflow rebuilds and compares, so drift is caught rather than
assumed absent.

The firmware installs the way every RP2350 board does: hold BOOTSEL, drag one
.uf2 onto the drive that appears — or use the web flasher. Uninstall is flashing
something else. The host CLI installs through the standard Python conventions
(uv tool install ./tools, pipx install ./tools, or pip), all of which
uninstall the same way.

The host tools honor the conventions of their ecosystems: uv/pipx/pip place the CLI in the standard user location and respect the active virtualenv or prefix, and cargo writes into the usual target directory. The firmware has no install prefix to honor — its destination is a fixed flash offset on the device.

nix develop is the entire setup: Rust stable with the thumbv8m target,
picotool, gitleaks, cargo-audit/deny and the Python stack, pinned by flake.lock.
Entering the shell also installs the pre-commit hook. Without Nix,
rust-toolchain.toml pins the toolchain and components for rustup.
https://themaxmur.github.io/RS-Key/build.html

Machine-readable and pinned: Cargo.toml/Cargo.lock for the Rust side (plus
separate lockfiles for the detached TUI, emulator and fuzz workspaces),
flake.nix/flake.lock for the toolchain and tools, and pyproject for the host CLI.
Git dependencies are restricted to the embassy organization.
https://github.com/TheMaxMur/RS-Key/blob/main/Cargo.lock

Three layers, all in the gate: cargo-audit against the RustSec advisory database, cargo-deny for advisories plus a license allow-list and a source policy, and cargo-vet for supply-chain review status. Dependabot opens update pull requests. No advisory is silently ignored — each entry in deny.toml carries its reason and its dependency chain.

Every reused component is a versioned package in a lockfile, updated with
cargo update or a flake input bump — there are no convenience copies of
third-party source in the build. The vendored third-party test suites under
third_party/ are test harnesses, not shipped code, and are identified as such.

Deprecations are compile errors here, not warnings: clippy runs with -D warnings and rustdoc with RUSTDOCFLAGS=-D warnings, so a deprecated API in the technology stack fails the gate the day the dependency marks it. Where the project stays on an older upstream it is a pinned, stated decision rather than drift.

Every pull request and every push to main runs the same merge gate CI runs
verbatim — nix develop -c ./scripts/check.sh, over a hundred rows — plus the
emulator suites, which drive the real applet stack over a socket with no
hardware. Results are reported per job on the pull request, and scheduled
deep-check workflows run the slower tiers (fuzzing, Miri, Kani, coverage,
reproducibility) daily and weekly.
https://github.com/TheMaxMur/RS-Key/blob/main/.github/workflows/ci.yml

The written policy is that a bug fix starts by reproducing the bug — a failing
host test where the logic is host-testable, a tests/*.py repro otherwise — and
then fixes it. In practice the fixes of the last six months ship with their
tests in the same commit, which is also what makes the gate able to tell a
repaired defect from a rewritten one.

Measured and floored rather than estimated: the deep-checks workflow runs
cargo llvm-cov --fail-under-lines 80 over the host crates, so coverage cannot
silently fall below the bar. The most recent scheduled run reports 86.06% lines
and 84.88% regions. (The floor excludes the firmware glue crate and the flash
wiper, which are embedded-only and not host-executable by construction.)

CONTRIBUTING.md states it as a requirement, not a preference: a protocol-visible
change comes with a test at the level where it is visible — a host test if the
logic is host-testable, a tests/*.py script if only the real USB stack exercises
it — and a new parser comes with a new fuzz target. The pull request template
asks how the change was tested.

The policy is written in CONTRIBUTING.md ("Tests") and the pull request
template asks how the change was tested.
https://github.com/TheMaxMur/RS-Key/blob/main/CONTRIBUTING.md

-D warnings everywhere, no exceptions per crate; plus unsafe sites are
enumerated and justified in docs/unsafe.md, and dependencies are gated by
cargo-deny and cargo-vet. https://themaxmur.github.io/RS-Key/unsafe.html

The assurance case argues this explicitly rather than asserting it: each of
Saltzer and Schroeder's principles against what the tree actually does —
economy of mechanism (no_std, no allocator, no mutexes, ownership as
synchronization), fail-safe defaults (alwaysUv on; a failed flash read is never
laundered into an absence), complete mediation (authorization re-checked at use,
a PIN retry spent before the comparison), open design, separation of privilege,
least privilege (the partition table denies the bootloader the KV store; applets
own disjoint file-id ranges; zero applet-to-applet edges, enforced by cargo-deny)
and least common mechanism. https://themaxmur.github.io/RS-Key/assurance-case.html