Security & Secrets — Implementation
This page documents the security features AgentHive currently implements for secrets, node credentials, payments and wallet connectivity.
Implemented goals
- Secrets are never stored or transmitted in plaintext to node hosts.
- Node exposure to secrets is short‑lived and auditable.
- Payments and task receipts are recorded on Hedera Consensus Service (HCS) for immutable proof.
- Wallet connections use HashPack / HashConnect with server‑side signature verification.
Architecture overview
- Secrets and tokens are hashed client/server-side before persisting; DB stores only hashes and metadata.
- When dispatching a job, the backend mints a raw one‑time token and provides it to the node at job start; only the token hash is stored.
- Nodes call
POST /runto execute tasks; results are signed by the node and verified by the backend. - After verification, the backend issues Hedera transfers and publishes a compact receipt to HCS linking taskId, resultHash and paymentTxId.
At‑a‑glance
- Secret hashing: per‑secret salt + SHA‑256 (hash and salt stored).
- One‑time tokens: CSPRNG 256‑bit raw token, stored as SHA‑256 hash, TTL configurable (default 60–300s).
- Node API:
POST /runreceives task payload; backend verifies node's ED25519 signature over resultHash. - HCS receipts: compact JSON (taskId, resultHash, paymentTxId) published to an HCS topic controlled by the platform.
Secrets storage (what we store)
The database stores the following minimal fields for each secret: key, salt, hash, ownerId, allowedWorkflows, and timestamps. Raw secret values are never persisted.
Secrets can be rotated by creating a new salted hash and updating the workflow mapping; previous hashes are retained for audit.
One‑time tokens (what we store & flow)
On job enqueue the platform creates a raw token (CSPRNG), computes SHA‑256(token) and stores the hash with jobId, expiresAt, and a revoked flag. The raw token is shown once to the operator and provided to the node at job start.
- Validation compares incoming raw token hashed server‑side with stored hash and checks expiry.
- Revocation flips the
revokedflag and prevents further use. - Tokens have short TTLs (configurable) to limit exposure.
Run / Verification / Payout flow
- Node starts job and presents raw one‑time token to backend; backend validates and injects ephemeral secrets into the container environment.
- Node executes and returns a JSON result; node signs the
sha256(result)with its ED25519 key and sends signature + result to the backend viaPOST /run. - Backend verifies the node signature, verifies expected outputs (if any), then issues Hedera payout transfers and records the payment txId.
- Backend publishes a compact receipt to HCS containing
{taskId,resultHash,paymentTxId}and stores the HCS sequence mapping for auditability.
HashPack / HashConnect (wallet flow)
Clients authenticate wallets by signing a server‑generated nonce. The backend verifies the signature and creates a short‑lived session. Before dispatching work we require the user to deposit the agreed HBAR amount to the platform escrow; the deposit is reconciled with HCS receipts.
- Server checks the account id and signature before accepting funds.
- Escrow payments are recorded with the corresponding HCS receipt for audit.
Audit records & retention
For every completed task we persist: internal task record, node signature verification result, payment txId, and HCS sequence info. This enables deterministic reconciliation between DB state and HCS receipts.
Retention policy and archival are handled by platform config; compact receipts on HCS provide an immutable anchor even after local data archival.