feat(security): authenticate BLAKE3-owned updates

[joshuajbouw]

Linked Issues

Closes #1247
Closes #1249
Closes #1250

Summary

Complete the pre-release security boundary for Astrid-owned identifiers and self-managed updates in one reviewed change: domain-separated BLAKE3 identifiers, a BLAKE3-first release-integrity contract with SHA-256 compatibility artifacts, and fail-closed Sigstore publisher authentication before integrity verification or extraction.

This PR supersedes #1248 and #1251 by containing their exact reviewed source changes plus the publisher-authentication work originally scoped here.

Changes

• add generic IdentifierHash and PublicKeyFingerprint newtypes backed by domain-separated BLAKE3
• prefix invite and pair-device bearer tokens, version their stores, invalidate non-migratable legacy SHA-256 indexes, and preserve unknown future schemas
• self-heal recoverable CLI key metadata and use canonical blake3:<64 lowercase hex> fingerprints across kernel, gateway, audit, and MCP-owned surfaces
• stop logging dictionary-testable hashes of low-entropy environment values
• publish BLAKE3SUMS.txt as the primary Astrid release-integrity manifest while retaining signed and attested SHA256SUMS.txt for released clients, Homebrew, and downstream compatibility
• strictly reject malformed, duplicate, uppercase, missing, mismatched, SHA-only, and overlong manifest entries
• authenticate release archives with fresh production Sigstore TUF metadata, the exact Astrid release workflow/tag identity, and the GitHub Actions issuer before integrity verification or extraction
• keep publisher-authentication, integrity, and preparation failures as typed stages, preserving exact asset-selection failure causes
• preserve empty credential-store reads on read-only deployments while keeping non-empty legacy SHA invalidation mandatory
• run Cosign and the native production verifier over every archive/bundle pair before release publication
• document the identifier, release-integrity, publisher-authentication, and compatibility boundaries

External SHA contracts such as SRI, Git object formats, Cargo registry checksums, Sigstore/SLSA internals, and Homebrew formula fields remain unchanged.

Verification

• exact signed head: c44a3908aa3e34611540e5d82331171e218940ae
• exact base: merged main at 122725708f6b58d3c77c1dc4df4763f345d94c3e
• all 20 commits from the base verify as Good GPG signatures
• full Astrid CLI unit suite: 493 passed, 1 intentional release-gate test ignored
• publisher-authentication suite: 10 passed, 1 intentional live release-gate test ignored
• self-update suite: 15 passed
• full kernel suite: 281 passed
• complete affected-package matrix previously passed for CLI, core, crypto, gateway, kernel, and MCP
• strict all-target/all-feature Clippy passed for the CLI and all affected identifier packages
• cargo fmt --all -- --check
• cargo metadata --locked --no-deps --format-version 1
• git diff --check
• actionlint .github/workflows/release.yml
• BLAKE3 derive-key vectors independently reproduced with b3sum --derive-key
• independent security reviews found no unresolved correctness or security issue; the final exact consolidated head is being re-reviewed

Checklist

• Linked to issues
• CHANGELOG.md updated under [Unreleased]

No release is created or published by this change.

[Copilot]

Pull request overview

This PR strengthens Astrid’s self-managed updater by adding publisher authentication (keyless Sigstore verification pinned to Astrid’s release workflow identity + GitHub Actions issuer) before integrity checks and extraction, and wires the release workflow to prove the native verifier accepts every published archive/bundle pair. It also continues the broader BLAKE3 transition by standardizing several Astrid-owned fingerprints/identifiers and updating docs/fixtures accordingly.

Changes:

• Add a typed self-update staging pipeline that authenticates archives via Sigstore (fresh public-good TUF roots, pinned identity/issuer) before BLAKE3 integrity verification and extraction.
• Update release automation to generate/publish BLAKE3 manifests, verify signatures with Cosign, and run the native verifier gate over all archives before creating a release.
• Replace legacy SHA-256-labeled identifiers with domain-separated BLAKE3 identifiers/fingerprints across tokens, key fingerprints, MCP binary pinning docs/config, and related fixtures/docs.

Reviewed changes

Copilot reviewed 39 out of 40 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Updates astrid update description and links to the self-update security model.
e2e/fixtures/compat/legacy-sha-pair-token.toml	Adds compatibility fixture for legacy SHA-256 pair-token store invalidation.
e2e/fixtures/compat/legacy-pair-token-without-scope.toml	Updates legacy fixture to schema v1 + blake3: token identifiers.
docs/self-update-security.md	Adds detailed self-update trust/authentication model documentation.
docs/gateway-client.md	Switches client-generation hash guidance from sha256 to b3sum.
docs/distro-signing.md	Updates distro pinning guidance from sha256 to BLAKE3 and b3sum examples.
docs/config.md	Updates binary_hash examples/docs to blake3:.
crates/astrid-mcp/src/config.rs	Enforces binary_hash as blake3:<64 lowercase hex> with parsing/formatting + tests.
crates/astrid-kernel/src/pair_token.rs	Moves pair-token identifiers to domain-separated BLAKE3 + schema envelope + legacy invalidation.
crates/astrid-kernel/src/kernel_router/admin/pair_device_handlers.rs	Updates docs to reflect BLAKE3 pair-token hashing.
crates/astrid-kernel/src/kernel_router/admin/mod.rs	Updates audit-token fingerprinting to canonical blake3: form handling.
crates/astrid-kernel/src/kernel_router/admin/invite_handlers.rs	Switches public-key fingerprinting to typed BLAKE3 fingerprints; updates revoke logic + tests.
crates/astrid-kernel/src/invite.rs	Migrates invite tokens to typed bearer + BLAKE3 identifiers + schema envelope + legacy invalidation.
crates/astrid-kernel/Cargo.toml	Removes sha2 dependency from kernel crate.
crates/astrid-integration-tests/tests/compatibility_fixtures.rs	Adds integration coverage for legacy SHA pair-token fixture invalidation.
crates/astrid-gateway/src/routes/invites.rs	Updates OpenAPI docs to typed tokens + blake3: fingerprints.
crates/astrid-gateway/src/routes/env.rs	Removes SHA-256 value fingerprint logging from env writes (reduces low-entropy leakage).
crates/astrid-gateway/src/routes/auth.rs	Updates docs/examples to typed invite/pair tokens and BLAKE3 key fingerprints.
crates/astrid-gateway/Cargo.toml	Removes sha2 dependency from gateway crate.
crates/astrid-crypto/src/prelude.rs	Exposes new identifier/fingerprint types in prelude.
crates/astrid-crypto/src/lib.rs	Adds identifier module exports.
crates/astrid-crypto/src/identifier.rs	Introduces domain-separated BLAKE3 identifier and Ed25519 public-key fingerprint types + tests.
crates/astrid-core/src/kernel_api/mod.rs	Updates API docs to typed tokens and blake3: fingerprints.
crates/astrid-config/src/defaults.toml	Updates example binary_hash to blake3:.
crates/astrid-cli/tests/fixtures/self_update/v0.9.4/SHA256SUMS.txt.sigstore.json	Adds legacy Sigstore bundle fixture for historical verification tests.
crates/astrid-cli/tests/fixtures/self_update/v0.9.4/SHA256SUMS.txt	Adds legacy SHA-256 manifest fixture used by bundle verification tests.
crates/astrid-cli/src/commands/update_auth.rs	Implements publisher-authentication + integrity stages and verified-only extraction boundary.
crates/astrid-cli/src/commands/update_auth_tests.rs	Adds unit + release-gate tests for Sigstore verification and strict manifest parsing.
crates/astrid-cli/src/commands/self_update.rs	Integrates publisher auth + bounded downloads + canonical tag parsing into self-update flow.
crates/astrid-cli/src/commands/self_update_tests.rs	Updates/extends tests for canonical tags, exact asset lookup, and mandatory bundle/manifest.
crates/astrid-cli/src/commands/mod.rs	Adds update_auth module.
crates/astrid-cli/src/commands/keypair.rs	Migrates key metadata schema and fingerprints to BLAKE3 with self-healing from stored public key.
crates/astrid-cli/src/commands/invite.rs	Updates CLI docs/output widths for blake3: fingerprints and typed tokens.
crates/astrid-cli/src/cli.rs	Updates --source help text to mirror/mocked discovery with pinned publisher identity.
crates/astrid-cli/Cargo.toml	Drops sha2; adds sigstore-verify dependency.
crates/astrid-capsule-install/src/github_source.rs	Updates tests to expect BLAKE3SUMS asset naming.
CHANGELOG.md	Documents self-update publisher authentication and BLAKE3 identifier transition under Unreleased.
Cargo.toml	Adds exact-pinned sigstore-verify workspace dependency with TUF support.
Cargo.lock	Updates lockfile for sigstore-verify and related dependency graph changes.
.github/workflows/release.yml	Adds recursive submodules, checksum generation, Cosign verification, and native verifier gating before release creation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 39 out of 40 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

crates/astrid-mcp/src/config.rs:244

• ServerConfig::verify_binary() parses binary_hash before checking whether command is set. This means a config that sets binary_hash but omits command will now error (e.g., due to the new blake3: format checks) even though the function intends to treat “no command to verify” as a no-op (return Ok(())). Move hash parsing below the command presence check so the early-return remains side-effect free.

[Copilot]

Pull request overview

Copilot reviewed 39 out of 40 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 51 out of 52 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 51 out of 52 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 51 out of 52 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 40 out of 41 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 40 out of 41 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 40 out of 41 changed files in this pull request and generated 2 comments.