This document covers the security posture of the Kintsugi USB project: what we attest to, what we don't, and how to report concerns.

This is a community rescue-USB toolkit, not a commercial product. Response is best-effort by a solo maintainer. There is no paid support, no formal SLA, and no bounty program. Reports are welcome and will be taken seriously.

Only the most recent tagged release receives security fixes. Older releases are historical. The wizard-first build model means most users run their own custom builds — those are not "versions" we maintain.

For v1.0, any maintainer-produced images (published to the warehouse NFS mount per ADR-006 §D4) ship with a SHA-256 checksum alongside the image file. Recipients verify integrity with:

# Linux / macOS
shasum -a 256 -c kintsugi-v2026.5.0.img.zst.sha256

# Windows PowerShell
Get-FileHash kintsugi-v2026.5.0.img.zst -Algorithm SHA256

SHA-256 protects against accidental corruption in transit. It does not, on its own, protect against malicious substitution if an attacker can modify both the image and the checksum on the host serving them.

A full cryptographic signing flow (minisign, Ed25519) is scheduled for v1.1. At that point:

• Every release artifact will carry a .minisig signature
• The maintainer's public key kintsugi.pub will be committed to this repo and pinned in README.md
• scripts/verify-image.sh wraps the sha256 + minisign verification in a single command (the sha256 stage is live today; the minisign stage activates automatically once a .minisig and kintsugi.pub are present)
• docs/flash-image.md will gain per-OS one-liners for the full verify flow

This deferral is an explicit trade-off to let iteration-1 focus on the build toolkit (the wizard is the product). See ADR-003 (amended) and ADR-006 §D5.

The signing key is a long-lived Ed25519 minisign keypair. This section is the authoritative record of its custody model and rotation procedure. The procedure is documented now (issue #19); the keypair itself is generated as a separate offline ceremony before the first signed (v1.1) release.

• The secret key is never committed to this repository and never stored on a networked build host. It lives on the maintainer's trusted offline machine (or a hardware token). Its location is recorded privately, outside this repo.
• Only kintsugi.pub is public — committed to repo root and pinned in README.md. Recipients trust it on first use (TOFU); there is no web-of-trust.
• The build/publish host (scripts/publish-release.sh) never holds the secret key. Signing is a deliberate maintainer step performed on the offline machine against the artifact's sha256, not an automated CI action — at least until a hardware-token-backed signer is wired up.

Rotate when: the secret key is suspected compromised, the storage medium is retired, or on a routine cadence (recommended: every 2 years, or per organizational policy).

1. Generate the replacement keypair offline — on the trusted/offline machine: minisign -G -p kintsugi-new.pub -s kintsugi-new.key. Store the new secret key with the same custody discipline as the old one.
2. Publish a transition notice — before retiring the old key, commit the new kintsugi.pub alongside the old one in a clearly-labeled ## Key rotation block in this file, signed-over by the old key where possible, so recipients can chain trust from the key they already pinned.
3. Dual-sign one release — sign the next release with both the old and new keys (.minisig and .minisig.new) so recipients on either key can verify during the overlap window.
4. Retire the old key — after the overlap release, replace kintsugi.pub with the new key, update the pinned block in README.md, and record the rotation (date, reason, fingerprints — never key material) in the rotation log below.
5. If compromised — skip the overlap; revoke immediately, publish a private disclosure, re-sign the current release with the new key, and treat all releases signed by the compromised key as suspect pending re-verification.

• The base image produced by scripts/publish-release.sh at tag time
• The scripts and docs as committed in the tagged git release
• manifest/models-recommended.yaml and manifest/agentic-frameworks-recommended.yaml as committed

• Model weights — user-fetched via kintsugi-models pull. Carry the source's own integrity story (Ollama registry digest, HuggingFace sha256, or user-supplied checksum). See manifest/models-recommended.yaml for the recommended list; anything outside it is entirely user-owned.
• Agentic framework binaries — user-fetched via kintsugi-frameworks install. Carry their vendors' own signing / install-verification.
• User-pulled anything else — the wizard's "Other" options and any --custom-slug invocations bypass the recommended list; you're the trust anchor for those choices.
• Your downstream fork — if you fork this toolkit to build your own distribution, sign with your own key. Don't claim the maintainer's signature.

This boundary is described in more detail in manifest/THIRD-PARTY-LICENSES.md and docs/toolkit-guide.md.

For bugs, misconfigurations, doc errors, or observations that would benefit from public visibility: https://git.integrolabs.net/roctinam/kintsugi-usb/issues — label with security if appropriate.

If the issue is sensitive — a suspected tampered image, a compromised credential, evidence of maliciously-modified scripts, a key compromise — contact the maintainer directly:

• Email: via GitHub profile for roctinam (pgp key on keyserver if available)
• Gitea DM: via https://git.integrolabs.net/roctinam

Include as much as you can:

• Which release or build (git commit hash, wizard profile if available)
• What you observed (error, suspicious behavior, checksum mismatch, install failure)
• How you observed it (commands run, network conditions, host type)
• Any captured evidence (log snippets, stderr, harness output)

• Acknowledgement within a reasonable best-effort window (this is a solo-maintained project — days, not hours)
• If the report is valid and sensitive, coordinated disclosure: fix first, public advisory later
• If the report is valid and non-sensitive: a Gitea issue and a fix in the next tagged release
• Credit at your discretion — we're happy to thank reporters publicly or keep reports anonymous

• ADR-003 — Release Verification Rigor (amended — v1.0 sha256 only; v1.1+ full signing)
• ADR-005 — Toolkit scope + user-driven models
• ADR-006 — Wizard-first UX + user-driven agentic frameworks + signing deferred
• Risk register — R-02 (supply-chain provenance), R-07 (secrets in repo), R-17 (malicious user-pulled slug), R-19 (VS Code telemetry), R-20 (Copilot subscription dependency)

This policy evolves. Last updated: 2026-05-24 (added release-signing-key custody + rotation procedure, issue #19). Next review: when the v1.1 signing keypair is generated.