17 added, 12 removed. Audit A to A.
---
name: air-gapped-signing-workflow-for-cold-storage
- description: Simulates and enforces a strict air-gapped signing workflow (Coordinator
- -> QR/SD -> Offline Vault -> Sign -> Broadcast) for institutional crypto custody.
+ description: Models a strict air-gapped Ethereum-style signing workflow (Coordinator -> QR/SD -> Offline Vault -> Sign -> Broadcast) for institutional crypto custody.
domain: crypto-custody-security
subdomain: Key Management
tags:
- crypto
- custody
- security
- air-gap
- - psbt
+ - clear-signing
brokers_frameworks:
- Generic
version: "1.1.0"
author: System
license: MIT
---
## When to Use
- Use this skill when designing the architecture for institutional crypto treasury management or securing API withdrawal whitelists. To prevent catastrophic private key theft, high-value signing must never occur on internet-connected machines. This workflow enforces the physical separation of the "Coordinator" (online) and the "Signer" (offline vault), ensuring clear signing without network exposure.
+ Use this skill when designing institutional crypto treasury workflows or securing API withdrawal processes. High-value signing must never occur on internet-connected machines. This reference separates the online `OnlineCoordinator` from the offline vault and requires clear signing before approval.
## Prerequisites
- Python 3.9+
- - Understanding of Partially Signed Bitcoin Transactions (PSBT) or equivalent unsigned payload structures.
+ - Understanding of Ethereum-style addresses, nonces, and chain/network identifiers.
+ - Production deployments must use audited chain-native transaction parsers, hardware wallets or HSMs, and real public-key signatures. The included signature primitive is an educational test seam only.
## Workflow
- 1. **Coordinator (Online)**: Algorithm generates an unsigned transaction intent (destination, amount).
- 2. **Export to Air-Gap**: The unsigned payload is encoded (conceptually via QR code or SD card) to cross the physical air gap.
- 3. **Signer (Offline)**: The offline vault decodes the payload, performs **Clear Signing** verification (displaying exact intent to hardware screen), and signs with the isolated private key.
- 4. **Import & Broadcast**: The signed payload is returned across the air gap to the Coordinator for blockchain broadcast.
+ 1. **Coordinator (Online)**: Generate and retain a validated, versioned unsigned intent with destination, decimal amount, network, and nonce.
+ 2. **Canonical Export**: Serialize the exact intent deterministically and transfer it only through controlled QR or clean SD media. Do not use USB, Bluetooth, Wi-Fi, or cellular bridges.
+ 3. **Signer (Offline)**: Decode and validate the payload, display the exact destination and amount, apply local policy, and obtain human approval before signing.
+ 4. **Signed Return**: Return the signed envelope containing the canonical payload, payload hash, signature, and signer key identifier through the controlled medium.
+ 5. **Independent Verification**: The coordinator recomputes the payload hash, checks that the intent was issued by this coordinator, validates signer identity, and verifies the signature before any broadcast adapter is called.
+ 6. **Idempotent Broadcast**: Reject replayed or duplicate payloads. Treat ambiguous RPC outcomes as unresolved until reconciled; never blindly retry an unknown order state.
## Common Pitfalls
- - **Blind Signing**: The offline device simply signs the payload hash without decoding and verifying the destination address and amount, making it vulnerable to malware on the online coordinator.
- - **Network Bridging**: Using USB cables, Bluetooth, or WiFi to transfer the payload to the "offline" device, completely defeating the air gap.
+ - **Blind Signing**: Signing a hash without decoding and displaying the destination and amount allows a compromised coordinator to redirect funds.
+ - **Network Bridging**: USB cables, Bluetooth, Wi-Fi, or cellular connectivity defeat the air gap.
+ - **Unbound Envelopes**: Accepting a signature without binding it to the exact coordinator-issued payload permits substitution.
+ - **Replay**: Broadcasting a valid signed payload more than once can create duplicate operational actions.
+ - **Demo Cryptography in Production**: The standard-library HMAC-style primitive in this reference is not asymmetric custody cryptography and must not protect production funds.
## Verification
- Run `python scripts/test_air_gapped_signing_workflow_for_cold_storage.py` to ensure the strict segregation of online and offline environments and the failure of blind/tampered signatures.
+ Run `python scripts/test_air_gapped_signing_workflow_for_cold_storage.py` or `python -m unittest discover -s skills/air-gapped-signing-workflow-for-cold-storage/scripts` to verify successful transfers, canonicalization, tamper rejection, and replay controls.
## Related Skills
- `hot-cold-wallet-split-for-trading-bots`
- `multi-signature-approval-for-large-transfers`