feat | Add layerlens.attestation: cryptographic hash chains for tamper-evide…

[garrettallen14]

PR is in conjuction with these SDK changes here.

FULL PR description here.

SDK changes

Adds cryptographic attestation and HMAC signing to the instrumentation SDK. Every @trace() call automatically produces attestation data (hash chain + root hash). If the org has a signing key, traces are HMAC-signed for authenticity. If not, the SDK auto-creates one on the first @trace() call.

New Module: layerlens.attestation

AttestationEnvelope

Field	Type	Description
hash	string	SHA-256 hash of the event data
scope	string	event or trial
previous_hash	string	Hash of the previous envelope (chain link)
timestamp	datetime	UTC timestamp
signature	string (optional)	Base64-encoded HMAC-SHA256 signature
signing_key_id	string (optional)	Key that produced the signature

HashChain

Method	Description
add_event(data)	Hash an event and append it to the chain
finalize()	Compute a trial-level root hash over all event hashes and seal the chain

TrialVerification

Field	Type	Description
valid	bool	Overall result
chain_valid	bool	Chain link continuity
trial_hash_valid	bool	Root hash matches event hashes
signatures_valid	bool	All HMAC signatures verified
errors	list	Detailed error messages

Signing

Two pure functions: hmac_sign(secret, data) and hmac_verify(secret, data, signature).

Modified Module: layerlens.instrument

TraceRecorder

Method	Description
_build_attestation()	Builds a hash chain from the span tree and returns attestation data
flush() / async_flush()	Uploads trace + attestation data

upload_trace()

Writes trace + attestation payload to a temp file, calls client.traces.upload().

Client + Resource Changes

Signing key management is abstracted away from the SDK user.

• New client.signing_keys resource (sync + async)
• SDK auto-fetches (or auto-creates) the org's signing key on the first @trace() call
• Cached per client instance with weakref-based liveness checks
• clear_signing_key_cache() exposed for key rotation