feat(examples): physical-attestation-governed — cold chain sensor receipts

[tomjwxf]

Summary

Extends the receipt format from #667 and #1159 to physical-world hardware attestation. Demonstrates Ed25519-signed receipts from a cold chain sensor device — every temperature, shock, GPS, and light reading is policy-evaluated and signed using the same receipt envelope format as software agent tool calls.

This work comes from an active hardware R&D program (Australian ETCF grant application, TRL 4→6) for a dedicated cold chain attestation sensor. The device specification predates this contribution — we're sharing it here because the physical AI governance gap identified in #787 is exactly the problem we're solving at the hardware level.

Connection to #787

@pshkv's SINT Protocol enforces `maxVelocityMps` and `maxForceNewtons` inline for robotic actuators. Our sensor enforces `temperature_c < 18.0` and `shock_g < 5.0` inline for supply chain shipments. Both produce signed receipts verifiable with the same offline CLI. Same governance pattern, different physical domain.

@imran-siddique noted on #787: "contributions welcome — especially from teams working at the intersection of robotics and agentic AI." Cold chain attestation is a simpler, lower-risk entry point to the same class of physical AI governance primitives.

What's included

```
examples/physical-attestation-governed/
├── README.md
├── getting_started.py # 8 scenarios, 722 lines
└── policies/
└── cold-chain-policy.yaml # Cedar-equivalent rules
```

8 scenarios

#	Scenario	What it demonstrates
1	Cold Chain Journey	Barossa Valley → Adelaide → Singapore → Tokyo, 12 readings
2	Temperature Excursion Blocks Release	22.4°C triggers deny — shipment release blocked
3	Shock Event Creates Alert	8.7g shock produces signed alert receipt
4	Receipt Tamper Detection	Editing any field invalidates the signature
5	Chain Integrity Verification	Hash-linked chain detects insertions/deletions
6	Multi-Sensor Correlation	Compound event (temp + shock + lux) in single receipt
7	Offline Verification	All receipts verify without network
8	Device Identity Attestation	Boot receipt proves which hardware produced readings

Hardware spec (simulated)

Component	Part	Role
Temperature + humidity	Sensirion SHT40	±0.2°C accuracy
Accelerometer	ST LIS2DH12	±16g range, shock detection
GPS	Quectel L76K	Position + timestamp
Ambient light	Vishay VEML7700	Sun exposure detection
Secure element	Microchip ATECC608B	Ed25519 key storage + signing

BOM target: $14.50 at volume (10K units).

Key property: receipt format is identical

The same receipt envelope works for both software agents and physical sensors:

```
Software: protect-mcp signs tool call → { payload, signature } → @veritasacta/verify
Hardware: ATECC608B signs sensor reading → { payload, signature } → @veritasacta/verify
```

Same JCS canonicalization (RFC 8785). Same chain structure (`previousReceiptHash`). Same verifier. Same exit codes. One proof layer for both domains.

Testing

```bash
python examples/physical-attestation-governed/getting_started.py

8 scenarios completed

12 journey receipts signed and chain-linked

All verified, all tamper attempts detected

```

Zero dependencies beyond Python 3.10+.

Relationship to existing work

PR	What	Relationship
#667	protect-mcp integration	Software receipt signing — the software counterpart
#1159	protect-mcp governed example	8 software scenarios — mirrored here with 8 physical scenarios
#787	Physical AI OWASP gap (SINT)	The governance gap this example addresses from the sensor side

Design decisions

• SHA-256 HMAC for demo signing — same pattern as feat(examples): protect-mcp governed example — Cedar policies + signed receipts #1159. Production uses Ed25519 from ATECC608B. Envelope format is identical; only `signature.alg` changes.
• Inline fallback — runs standalone with zero dependencies, same as feat(examples): protect-mcp governed example — Cedar policies + signed receipts #1159.
• Real supply chain journey — Barossa Valley → Tokyo is a real wine export route with realistic temperature profiles, not synthetic data.

Happy to iterate. This is meant to show that the receipt format from #667/#1159 scales to physical devices without any protocol changes.

[github-actions]

Welcome to the Agent Governance Toolkit! Thanks for your first pull request.
Please ensure tests pass, code follows style (ruff check), and you have signed the CLA.
See our Contributing Guide.

[github-actions]

🤖 AI Agent: security-scanner — Security Review of PR: feat(examples): physical-attestation-governed — cold chain sensor receipts

Security Review of PR: feat(examples): physical-attestation-governed — cold chain sensor receipts

This PR introduces physical-world hardware attestation for cold chain sensors, extending the governance framework to physical sensor readings. Below is a detailed security analysis based on the critical areas outlined:

---

1. Prompt Injection Defense Bypass

Rating: 🔵 LOW
Analysis:
This PR does not involve direct user input or prompt-based interactions. The sensor readings are generated programmatically or sourced from hardware, and the policy evaluation is deterministic based on predefined rules. There is no evidence of vulnerabilities related to prompt injection.

Recommendation:
No action required.

---

2. Policy Engine Circumvention

Rating: 🟠 HIGH
Analysis:
The policy evaluation logic is implemented inline in Python (evaluate_policy) and mirrors Cedar-style rules. However, the inline implementation lacks robust safeguards against tampering or circumvention. For example:

• The policy evaluation does not enforce immutability of the SensorReading or PolicyResult objects, allowing potential manipulation before signing.
• The fallback signing mechanism (HS256-DEMO) is insecure and could allow attackers to forge signatures if the key is exposed.

Attack Vector:
An attacker could modify the SensorReading or PolicyResult before signing, bypassing policy enforcement. Additionally, the use of HMAC-SHA256 for signing in the demo environment is insecure and could be exploited if the key is leaked.

Recommendation:

• Replace the inline policy evaluation with a production-grade Cedar policy engine.
• Use Ed25519 signatures from the ATECC608B secure element for all environments, including demos, to prevent forgery.
• Ensure immutability of SensorReading and PolicyResult objects before signing.

---

3. Trust Chain Weaknesses

Rating: 🔴 CRITICAL
Analysis:
The receipt chain relies on hash linking (previousReceiptHash) for integrity. However:

• The chain does not enforce cryptographic proof of the previous receipt's validity. An attacker could insert or delete receipts without detection if they recompute the hashes.
• The SensorReceiptChain implementation does not validate the integrity of the chain during receipt addition or verification.

Attack Vector:
An attacker could tamper with the receipt chain by inserting or deleting receipts and recalculating hashes, breaking the trust chain.

Recommendation:

• Implement cryptographic validation of the entire chain during receipt addition and verification.
• Use Merkle trees or similar cryptographic structures to ensure chain integrity.
• Add chain validation logic to detect tampering during verification.

---

4. Credential Exposure

Rating: 🟠 HIGH
Analysis:
The demo signing key (DEMO_KEY) is hardcoded in the source code ("a" * 64). While this is acceptable for demonstration purposes, it sets a poor precedent and risks accidental exposure in production environments.

Attack Vector:
If the hardcoded key is mistakenly used in production, it could be exploited to forge signatures.

Recommendation:

• Remove hardcoded keys from the source code.
• Use secure key management practices, such as hardware security modules (HSMs) or environment variables, for key storage.

---

5. Sandbox Escape

Rating: 🔵 LOW
Analysis:
This PR does not involve sandboxing or containerization. The code runs standalone in Python and does not execute untrusted code or interact with external processes.

Recommendation:
No action required.

---

6. Deserialization Attacks

Rating: 🟡 MEDIUM
Analysis:
The receipt payloads are serialized and deserialized using JSON. While JSON is generally safe, the lack of validation during deserialization could allow malformed or malicious payloads to bypass verification.

Attack Vector:
An attacker could craft a malicious JSON payload that exploits weaknesses in the deserialization logic.

Recommendation:

• Validate all deserialized JSON payloads against a strict schema before processing.
• Use libraries that enforce schema validation, such as jsonschema.

---

7. Race Conditions

Rating: 🔵 LOW
Analysis:
The receipt chain is append-only and does not involve concurrent operations. There is no evidence of race conditions in the current implementation.

Recommendation:
No action required.

---

8. Supply Chain

Rating: 🟡 MEDIUM
Analysis:
The PR introduces no external dependencies, relying solely on Python's standard library. However, the use of inline cryptographic primitives (hmac, hashlib) could lead to supply chain risks if replaced with third-party libraries in the future.

Attack Vector:
Dependency confusion or typosquatting attacks could occur if external libraries are introduced for cryptographic operations.

Recommendation:

• Continue using Python's standard library for cryptographic operations.
• If external dependencies are introduced, pin versions and verify their integrity.

---

Summary of Findings

Category	Rating	Action Required
Prompt Injection Defense Bypass	🔵 LOW	No action required.
Policy Engine Circumvention	🟠 HIGH	Replace inline policy evaluation with Cedar engine; enforce immutability.
Trust Chain Weaknesses	🔴 CRITICAL	Implement cryptographic chain validation; use Merkle trees for integrity.
Credential Exposure	🟠 HIGH	Remove hardcoded keys; use secure key management practices.
Sandbox Escape	🔵 LOW	No action required.
Deserialization Attacks	🟡 MEDIUM	Validate JSON payloads against a strict schema.
Race Conditions	🔵 LOW	No action required.
Supply Chain	🟡 MEDIUM	Pin versions and verify integrity if external dependencies are introduced.

---

Recommendations for Fixes

1. Policy Engine: Replace the inline policy evaluation with a production-grade Cedar engine. Ensure immutability of objects before signing.
2. Trust Chain: Implement cryptographic validation of the receipt chain using Merkle trees or similar structures.
3. Signing Key: Remove hardcoded keys and use secure key management practices.
4. Deserialization: Validate all JSON payloads against a strict schema during deserialization.
5. Cryptographic Signing: Use Ed25519 signatures from the ATECC608B secure element in all environments, including demos.

---

Final Notes

This PR introduces valuable functionality for physical-world AI governance but contains critical security weaknesses that must be addressed before deployment.

[github-actions]

🤖 AI Agent: code-reviewer

Pull Request Review for feat(examples): physical-attestation-governed — cold chain sensor receipts

---

🔴 CRITICAL: Security Issues

1. Insecure Signature Algorithm for Demonstration

   • The use of SHA-256 HMAC for signing receipts in the demonstration is insecure and could lead to a false sense of security. While the PR mentions that production devices will use Ed25519 from the ATECC608B secure element, the demonstration code should also use a secure algorithm (e.g., Ed25519) to prevent misuse or misinterpretation of the example code.
   • Recommendation: Replace the HMAC-based signing with a secure Ed25519 implementation, even for demonstration purposes. If this is not feasible, include prominent warnings in the documentation and code comments to clarify that this is for demonstration only and should not be used in production.

2. Tamper Detection Vulnerability

   • The SensorReceipt.verify() method relies on hmac.compare_digest to validate the signature. However, the payload field is mutable, and there is no mechanism to ensure the integrity of the payload field itself. An attacker could modify the payload and re-sign it with the same key, effectively bypassing the tamper detection.
   • Recommendation: Use a cryptographic signature scheme like Ed25519 that binds the signature to the payload. This ensures that any modification to the payload invalidates the signature, even if the attacker has access to the signing key.

3. Lack of Secure Key Management

   • The DEMO_KEY is hardcoded in the example ("a" * 64), which is insecure and could lead to accidental misuse in production.
   • Recommendation: Use a secure key management solution or environment variables to handle keys, even in demonstration code. At a minimum, include a warning in the code and documentation about the risks of hardcoding keys.

4. No Replay Protection

   • The receipt format does not include a mechanism to prevent replay attacks. An attacker could reuse a valid receipt to falsely claim compliance.
   • Recommendation: Include a nonce or timestamp in the receipt payload and ensure that the verifier checks for uniqueness or freshness of the receipt.

5. Policy Evaluation Logic

   • The policy evaluation logic is implemented in Python, but the production system is expected to use Cedar policies. This discrepancy could lead to inconsistencies between the demonstration and production environments.
   • Recommendation: Use a Cedar policy engine (e.g., py-cedar) in the demonstration code to ensure consistency with the production environment.

---

🟡 WARNING: Potential Breaking Changes

1. Backward Compatibility of Receipt Format
   • The receipt format introduced here (draft-farley-acta-signed-receipts-01) must be backward-compatible with the existing software agent receipt format from PRs #667 and #1159. Any changes to the format could break existing verifiers.
   • Recommendation: Add explicit tests to ensure that the receipt format remains compatible with the software agent receipts. Include tests for both software and hardware receipts in the same test suite.

---

💡 Suggestions for Improvement

1. Thread Safety

   • The SensorReceiptChain class uses a mutable list (self.receipts) and a mutable counter (self._sequence) without any thread-safety mechanisms. If this class is used in a multi-threaded environment, it could lead to race conditions.
   • Recommendation: Use thread-safe constructs like threading.Lock or concurrent.futures to ensure thread safety when accessing or modifying shared state.

2. Type Safety

   • While the code uses type hints, there are no runtime checks to validate the structure of SensorReading or SensorReceipt objects.
   • Recommendation: Use Pydantic models to enforce type safety and validate the structure of these objects at runtime.

3. Policy Evaluation Logging

   • The evaluate_policy function does not log the evaluation process, which could make debugging difficult in production.
   • Recommendation: Add structured logging to capture policy evaluation decisions, including the input parameters and the resulting decision.

4. Error Handling

   • The code lacks robust error handling. For example, if the evaluate_policy function encounters an unexpected input, it may raise an unhandled exception.
   • Recommendation: Add error handling and validation for inputs to ensure the system fails gracefully.

5. Documentation

   • While the PR includes a detailed README, it would benefit from a more explicit warning about the use of insecure signing in the demonstration code.
   • Recommendation: Add a bold, highlighted warning at the top of the README and in the code comments to emphasize that the HMAC-based signing is for demonstration purposes only and should not be used in production.

6. Test Coverage

   • The PR includes 8 scenarios, but there is no mention of automated tests for these scenarios.
   • Recommendation: Integrate these scenarios into the pytest test suite to ensure they are automatically tested in the CI/CD pipeline.

7. Use of Constants

   • The COLD_CHAIN_POLICY is hardcoded in the script, which makes it difficult to modify or extend.
   • Recommendation: Load the policy from an external YAML or JSON file (e.g., cold-chain-policy.yaml) to make it easier to update and manage.

8. Code Organization

   • The getting_started.py script is quite long (576 lines) and combines multiple concerns (e.g., signing, simulation, policy evaluation, and scenarios).
   • Recommendation: Refactor the script into smaller, reusable modules. For example:
     • signing.py for signing and verification logic.
     • policy.py for policy evaluation logic.
     • simulator.py for the sensor simulation.
     • scenarios.py for the scenario definitions.

9. Future Considerations: SPIFFE/SVID

   • The PR does not mention the use of SPIFFE/SVID for device identity attestation, which could be a valuable addition for secure device authentication.
   • Recommendation: Consider integrating SPIFFE/SVID for device identity attestation in future iterations.

10. Testing Edge Cases

    • The scenarios do not appear to test edge cases, such as boundary values for temperature, shock, and light.
    • Recommendation: Add tests for edge cases (e.g., temperature exactly at 18.0°C, shock exactly at 5.0g) to ensure the policy engine behaves as expected.

---

Summary

• Strengths: The PR provides a well-documented and comprehensive example of extending the receipt format to physical-world hardware attestation. The scenarios are realistic and align with the project's goals of addressing physical AI governance gaps.
• Critical Issues: Insecure signing algorithm, lack of replay protection, and mutable payloads that could allow tampering.
• Warnings: Potential backward compatibility issues with the receipt format.
• Suggestions: Improve thread safety, type safety, error handling, and code organization. Add automated tests for scenarios and edge cases. Consider future integration with SPIFFE/SVID for device identity attestation.

Action Items

1. 🔴 Replace HMAC with Ed25519 for signing, or add prominent warnings about the demonstration-only nature of the current implementation.
2. 🔴 Implement a mechanism to ensure the integrity of the payload field in SensorReceipt.
3. 🔴 Add replay protection to the receipt format.
4. 🟡 Ensure backward compatibility with existing receipt formats.
5. 💡 Refactor the code for better modularity and maintainability.
6. 💡 Add automated tests for all scenarios and edge cases.
7. 💡 Use Pydantic models for type safety and validation.
8. 💡 Add structured logging to the policy evaluation process.

Let me know if you need further clarification or assistance!