How mizcausevic-dev/hash-attestation-rs works
Purpose and principal workflow: hash-attestation is a Rust library for signing JSON documents with Ed25519 and checking attestations against public keys already trusted by the caller; it does not fetch keys or establish vendor identity. The external application caller initiates both signing and verification, providing the document and, for verification, an attestation and trusted key. New signatures use RFC 8785 canonicalization and bind the hash profile, key URL, and signer-asserted timestamp; legacy v0.1 verification remains supported.
Components
Public API
• Crate API — src/lib.rs: Exposes the attestation, signer, verifier, error, and hash APIs; raw-JSON parsing is also exported here.
Signing and verification
• Attestor — src/attestor.rs: Signs documents, offers strict raw-JSON signing and legacy signing, and exposes the corresponding verifying key.
• Verifier and trust set — src/attestor.rs: Keeps an in-memory key_url -> VerifyingKey map and verifies against a registered key or an independently expected key URL.
• Attestation envelope — src/attestation.rs: Defines the serialized signature record and verifies its hash and Ed25519 signature, selecting legacy or v0.2 behavior by hash profile.
Canonicalization and input safety
• Canonical hashes and strict JSON parsing — src/hash.rs: Computes legacy and RFC 8785 SHA-256 hashes; its raw-input parser rejects duplicate keys and unsafe integer literals.
• Finite-number validation — src/validate.rs: Recursively rejects NaN and infinity before JCS serialization.
Optional audit emission
• Audit event emitter — src/audit_stream.rs: With the audit-stream feature, posts best-effort signing or verification events to the configured /events endpoint.
External participants
• Application caller — null repository path: Invokes the library with document data and handles signing keys, trust establishment, and verification results.
• Independent trust source — null repository path: Supplies or authenticates the public key and its expected URL outside this crate.
• Audit-stream endpoint — null repository path: Optionally receives emitted operational events; it is not part of the cryptographic trust decision.
Relationships
• Application caller -> Crate API: Calls the exported Rust library APIs; evidence: src/lib.rs.
• Crate API -> Attestor: Re-exports the signing API; evidence: src/lib.rs.
• Crate API -> Verifier and trust set: Re-exports the verification API; evidence: src/lib.rs.
• Attestor -> Canonical hashes and strict JSON parsing: Hashes structured input with JCS or parses raw JSON before signing; evidence: src/attestor.rs.
• Canonical hashes and strict JSON parsing -> Finite-number validation: Checks serializable values for non-finite numbers before JCS hashing; evidence: src/hash.rs.
• Attestor -> Attestation envelope: Constructs the v0.2 envelope, signs its signing input, and stores the signature; evidence: src/attestor.rs.
• Verifier and trust set -> Attestation envelope: Looks up a registered key and delegates cryptographic verification; evidence: src/attestor.rs.
• Attestation envelope -> Canonical hashes and strict JSON parsing: Recomputes the body hash for the declared profile; evidence: src/attestation.rs.
• Independent trust source -> Application caller: The caller must independently establish key ownership and bind it to the expected vendor; evidence: README.md.
• Application caller -> Verifier and trust set: Registers its trusted key before verification; evidence: README.md.
• Attestor -> Audit event emitter: Under the optional feature, emits attestation_signed after signing; evidence: src/attestor.rs.
• Verifier and trust set -> Audit event emitter: Under the optional feature, emits verification success or failure after checking; evidence: src/attestor.rs.
• Audit event emitter -> Audit-stream endpoint: Sends events by HTTP POST to /events; evidence: src/audit_stream.rs.
Coverage limits: The source excerpts show the library’s core signing, verification, canonicalization, and optional audit paths. No consuming application or audit service implementation is included, so their runtime behavior and trust-establishment mechanisms cannot be established here.
Main entry points: attestor.rs Attestor · lib.rs Crate API · attestation.rs Attestation envelope · hash.rs Canonical hashes and strict JSON parsing
Components 10
Signing and Verification
Attestation creation, trusted-key management, and signature verification.
- Attestor
src/attestor.rs - Verifier and trust set · Keeps an in-memory key_url-to-VerifyingKey map.
src/attestor.rs - Attestation envelope
src/attestation.rs
Canonicalization and Input Safety
Strict JSON parsing, hash profiles, and finite-number validation.
- Canonical hashes and strict JSON parsing
src/hash.rs - Finite-number validation
src/validate.rs
Optional Audit Emission
Best-effort operational event emission when the audit-stream feature is enabled.
- Audit event emitter · Optional best-effort event emission.
src/audit_stream.rs
Other components
- Application caller · Provides documents and handles keys, trust establishment, and results.
- Independent trust source · Supplies or authenticates a public key and its expected URL outside the crate.
- Audit-stream endpoint · Receives optional operational events; not part of the cryptographic trust decision.
Connections 13
- Application caller → Crate API: calls APIs
src/lib.rs - Crate API → Attestor: re-exports
src/lib.rs - Crate API → Verifier and trust set: re-exports
src/lib.rs - Attestor → Canonical hashes and strict JSON parsing: hashes or parses
src/attestor.rs - Canonical hashes and strict JSON parsing → Finite-number validation: validates numbers
src/hash.rs - Attestor → Attestation envelope: constructs and signs
src/attestor.rs - Verifier and trust set → Attestation envelope: delegates verification
src/attestor.rs - Attestation envelope → Canonical hashes and strict JSON parsing: recomputes hash
src/attestation.rs - Independent trust source → Application caller: establishes key trust · Key ownership and vendor binding are established outside this crate.
README.md - Application caller → Verifier and trust set: registers trusted key
README.md - Attestor → Audit event emitter: emits signed event · Optional audit-stream feature.
src/attestor.rs - Verifier and trust set → Audit event emitter: emits verification result · Optional audit-stream feature.
src/attestor.rs - Audit event emitter → Audit-stream endpoint: posts events · HTTP POST to /events.
src/audit_stream.rs