feat(security): replace owned identifiers with BLAKE3 by joshuajbouw · Pull Request #1248 · astrid-runtime/astrid

joshuajbouw · 2026-07-15T00:19:32Z

Linked Issue

Summary

Replace Astrid-owned SHA-256 identifiers with explicit BLAKE3 semantics before those formats acquire an external compatibility constituency. Content digests remain distinct from domain-separated identifiers, recoverable metadata self-heals, and non-recoverable legacy token indexes fail closed.

Changes

add generic IdentifierHash and PublicKeyFingerprint newtypes backed by BLAKE3 derive-key contexts
migrate invite and pair-device token indexes to distinct BLAKE3 domains with golden vectors and constant-time comparison coverage
prefix raw bearer tokens as astrid_inv_ / astrid_pair_ and serialize fingerprints as blake3:<hex> so secrets and identifiers are self-describing
version both token stores; invalidate schema-0 SHA-256 records, preserve unknown future schemas unchanged, and reject malformed state
migrate CLI key metadata from schema 1 to schema 2 by recomputing its fingerprint from the retained public key
use the shared public-key fingerprint in kernel responses and audit redaction
correct MCP binary pins from the inaccurate sha256:<BLAKE3> spelling to blake3:<BLAKE3>, while preserving the existing no-op behavior when an SSE server has no local command to verify
document the exact blake3:<64 lowercase hex> local-command pin shape with a syntactically valid example
stop logging dictionary-testable fingerprints of low-entropy env values
remove unused direct sha2 dependencies from the kernel and gateway while retaining SHA where external protocols require it
compose attenuated pair-device authority with the typed BLAKE3 token flow and cover issue, redeem, and revoke in one regression
acknowledge the intentional public OpenAPI credential-description change with the required contract marker

Verification

exact signed head: f948083f5b7a5461a0ff001f1f2f34cd1d26f387
exact base: merged main at 122725708f6b58d3c77c1dc4df4763f345d94c3e
the seven source commits are patch-identical to the independently reviewed composition at 1556c728; the restored metadata-only OpenAPI marker leaves the reviewed tree byte-identical, and all eight signatures verify
cargo fmt --all -- --check
cargo metadata --locked --no-deps --format-version 1
git diff --check origin/main..HEAD
complete affected-package matrix: 480 CLI, 274 core, 18 crypto, 159 gateway unit plus 35 gateway integration, 277 kernel, 122 MCP, and selected doctests
strict all-target/all-feature Clippy across CLI, core, crypto, gateway, kernel, and MCP
BLAKE3 derive-key vectors independently reproduced with b3sum --derive-key
regression coverage preserves no-command MCP hash behavior while keeping strict BLAKE3 parsing for local binaries
combined pair-device regression proves explicit attenuation survives typed-token issue and redeem, then the derived BLAKE3 device identity revokes cleanly
independent exact-tree security review found no actionable issues

Dependency Handling

This PR targets main and is restacked directly onto the squash-merged operator-distro boundary. It has no remaining open parent dependency.

Checklist

Linked to an issue
CHANGELOG.md updated under [Unreleased]

No release is created or published by this change.

Copilot

Pull request overview

This PR migrates Astrid-owned identifiers (invite tokens, pair-device tokens, public-key fingerprints, and MCP binary pins) from SHA-256-centric strings to explicit, domain-separated BLAKE3 semantics, aiming to make internal identifiers self-describing and avoid accidental external compatibility commitments.

Changes:

Introduces IdentifierHash and PublicKeyFingerprint newtypes (BLAKE3 derive-key domain separation) and updates kernel/CLI/gateway usage to emit blake3:<hex> fingerprints.
Versions and migrates invite/pair token stores: schema-0 (legacy SHA-256) fails closed via invalidation; schema-1 persists with typed raw-token prefixes (astrid_inv_ / astrid_pair_) and constant-time comparisons.
Updates MCP binary integrity pins to blake3:<hex>, removes SHA-256 env value fingerprint logging in the gateway, and removes direct sha2 deps where no longer needed.

Reviewed changes

Copilot reviewed 25 out of 26 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
e2e/fixtures/compat/legacy-sha-pair-token.toml	Adds a compatibility fixture representing a legacy SHA-256 pair-token store record.
e2e/fixtures/compat/legacy-pair-token-without-scope.toml	Updates the legacy pair-token fixture to schema 1 and a `blake3:<hex>` token hash.
docs/gateway-client.md	Updates guidance to use BLAKE3 tooling (`b3sum`) for spec hashing.
docs/distro-signing.md	Updates distro signing documentation from sha256 pin examples to BLAKE3 (`b3sum`).
docs/config.md	Updates `binary_hash` documentation/examples to `blake3:<hex>`.
crates/astrid-mcp/src/config.rs	Enforces `blake3:<64 lowercase hex>` for MCP `binary_hash`, rejecting the retired `sha256:` label; adds tests.
crates/astrid-kernel/src/pair_token.rs	Migrates pair-token identifiers to domain-separated BLAKE3, adds schema handling and invalidation for legacy SHA stores, and typed token prefixing.
crates/astrid-kernel/src/kernel_router/admin/pair_device_handlers.rs	Updates docs to reflect BLAKE3-based persistence and redaction posture.
crates/astrid-kernel/src/kernel_router/admin/mod.rs	Updates audit redaction docs and revoke token fingerprinting to use the new canonicalization helper.
crates/astrid-kernel/src/kernel_router/admin/invite_handlers.rs	Switches public-key fingerprinting to shared BLAKE3 helper; updates invite revoke matching logic; adds persistence/revocation tests.
crates/astrid-kernel/src/invite.rs	Migrates invite-token identifiers to domain-separated BLAKE3 with schema handling, typed token prefixing, canonicalization helper, and tests.
crates/astrid-kernel/Cargo.toml	Removes direct `sha2` dependency from the kernel crate.
crates/astrid-integration-tests/tests/compatibility_fixtures.rs	Adds an integration test ensuring legacy SHA pair-token stores are invalidated and rewritten.
crates/astrid-gateway/src/routes/invites.rs	Updates OpenAPI schema/docs to reflect typed tokens and `blake3:<hex>` fingerprints.
crates/astrid-gateway/src/routes/env.rs	Removes SHA-256 value fingerprint logging to avoid dictionary-testable leakage for low-entropy env values.
crates/astrid-gateway/src/routes/auth.rs	Updates request/response docs/examples for typed tokens and BLAKE3 public-key fingerprints.
crates/astrid-gateway/Cargo.toml	Removes direct `sha2` dependency from the gateway crate and updates comments.
crates/astrid-crypto/src/prelude.rs	Re-exports new identifier/fingerprint helpers in the crypto prelude.
crates/astrid-crypto/src/lib.rs	Adds the new `identifier` module and exports `IdentifierHash`/`PublicKeyFingerprint`.
crates/astrid-crypto/src/identifier.rs	New module implementing domain-separated BLAKE3 identifier types with tests.
crates/astrid-core/src/kernel_api/mod.rs	Updates API docs to reflect typed tokens and `blake3:<hex>` public-key/token fingerprints.
crates/astrid-config/src/defaults.toml	Updates default config comments to `binary_hash = "blake3:..."`.
crates/astrid-cli/src/commands/keypair.rs	Migrates key metadata to schema 2 with BLAKE3 fingerprints and self-healing migration/repair logic.
crates/astrid-cli/src/commands/invite.rs	Updates CLI help/output formatting for `blake3:<hex>` fingerprints.
CHANGELOG.md	Adds an [Unreleased] changelog entry documenting the BLAKE3 identifier migration and related changes.
Cargo.lock	Removes now-unused `sha2` dependency entries for affected crates.

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

Copilot

Pull request overview

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

Copilot

Pull request overview

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

Copilot

Pull request overview

Copilot reviewed 37 out of 38 changed files in this pull request and generated 4 comments.

Copilot

Pull request overview

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

Copilot

Pull request overview

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

API-CONTRACT-CHANGE: pair and invite bearer tokens now expose typed prefixes, and public key and token fingerprints now use the blake3:<hex> format.

Copilot

Pull request overview

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

## 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 - [x] Linked to issues - [x] CHANGELOG.md updated under `[Unreleased]` No release is created or published by this change.

joshuajbouw · 2026-07-15T18:41:51Z

Superseded by and landed through #1254. The merged squash commit a1d4e65 contains this complete signed BLAKE3 identifier and compatibility work together with the coordinated release-integrity and publisher-authentication stack.

Copilot AI review requested due to automatic review settings July 15, 2026 00:19

Copilot started reviewing on behalf of joshuajbouw July 15, 2026 00:20 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

Comment thread crates/astrid-kernel/src/invite.rs Outdated

Comment thread crates/astrid-kernel/src/invite.rs Outdated

Comment thread crates/astrid-kernel/src/pair_token.rs Outdated

joshuajbouw mentioned this pull request Jul 15, 2026

feat(release): make BLAKE3 the primary integrity manifest #1251

Closed

2 tasks

joshuajbouw force-pushed the agent/owned-blake3 branch from c8ecd13 to 3a34e97 Compare July 15, 2026 02:02

joshuajbouw requested a review from Copilot July 15, 2026 06:14

Copilot started reviewing on behalf of joshuajbouw July 15, 2026 06:15 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

joshuajbouw force-pushed the agent/owned-blake3 branch from 1b2e55a to e7affe8 Compare July 15, 2026 07:43

joshuajbouw requested a review from Copilot July 15, 2026 07:44

Copilot started reviewing on behalf of joshuajbouw July 15, 2026 07:46 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

joshuajbouw mentioned this pull request Jul 15, 2026

feat(security): authenticate BLAKE3-owned updates #1254

Merged

2 tasks

joshuajbouw requested a review from Copilot July 15, 2026 08:22

Copilot started reviewing on behalf of joshuajbouw July 15, 2026 08:40 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

Comment thread crates/astrid-config/src/defaults.toml Outdated

Comment thread crates/astrid-capsule/src/profile_cache.rs

Comment thread crates/astrid-capsule/src/profile_cache.rs

Comment thread crates/astrid-capsule/src/profile_cache.rs

joshuajbouw requested a review from Copilot July 15, 2026 08:47

Copilot started reviewing on behalf of joshuajbouw July 15, 2026 08:55 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

joshuajbouw added 7 commits July 15, 2026 21:15

feat(security): replace owned identifiers with blake3

3d788ca

fix(cli): own scanned key names before path moves

11fb2b8

docs(security): describe typed bearer identifiers

ed9b8a5

fix(mcp): preserve remote hash no-op

0802234

test(kernel): compose BLAKE3 device authority flow

a84d773

docs(mcp): specify exact BLAKE3 pin format

b011243

docs(config): use a valid BLAKE3 pin example

6fa606c

joshuajbouw force-pushed the agent/owned-blake3 branch from 04789ce to 6fa606c Compare July 15, 2026 17:17

joshuajbouw requested a review from Copilot July 15, 2026 17:18

Copilot started reviewing on behalf of joshuajbouw July 15, 2026 17:20 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

docs(api): acknowledge typed credential formats

f948083

API-CONTRACT-CHANGE: pair and invite bearer tokens now expose typed prefixes, and public key and token fingerprints now use the blake3:<hex> format.

joshuajbouw requested a review from Copilot July 15, 2026 17:27

Copilot started reviewing on behalf of joshuajbouw July 15, 2026 17:32 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

joshuajbouw closed this Jul 15, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(security): replace owned identifiers with BLAKE3#1248

feat(security): replace owned identifiers with BLAKE3#1248
joshuajbouw wants to merge 8 commits into
mainfrom
agent/owned-blake3

joshuajbouw commented Jul 15, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

joshuajbouw commented Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

joshuajbouw commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Linked Issue

Summary

Changes

Verification

Dependency Handling

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

joshuajbouw commented Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

joshuajbouw commented Jul 15, 2026 •

edited

Loading