Role in the system
The agent is the Distribrute software that runs on operator-controlled hardware. It requests bounded search work, verifies that work locally, invokes the approved password-search tool, and reports the outcome. It never receives the full wallet or customer identity.
The operator machine is an untrusted zone. The protocol does not assume that installing the agent makes the host trustworthy. Instead, it limits the host to a safe test piece whose recovered password is not spendable without wallet material the operator never receives.
Work loop
- The device enrolls with a one-time token and creates its own signing key.
- The agent signs its work request and receives a lease, signed case manifest, signed search chunk, and approved tool information.
- The supervisor validates the assignment before any search tool runs.
- The runner executes the approved hashcat binary against only the leased candidate range.
- A miss, failure, or possible match is returned to the supervisor as a structured result.
- Possible passwords are sealed for Verify and reported with the exact lease context.
The agent can run once or continue polling as a daemon. An idle gate can avoid taking work while the operator’s NVIDIA GPUs are already busy.
What the supervisor verifies
The coordinator is not a trust root. For every lease, the supervisor independently checks:
| Check | Purpose |
|---|---|
| Manifest and chunk signatures | Prevent the coordinator from inventing or changing authorized work |
| Lease-to-chunk binding | Ensure the device runs only its assigned search range |
| Safe-test-piece hash | Prevent target substitution |
| Expiry and workload tier | Reject stale or incompatible work |
| Verify sealing key | Prevent a result from being redirected to an unapproved recipient |
| Signed tool catalog and binary hash | Ensure the runner executes the authorized hashcat build |
| Wordlist-range hash or mask definition | Ensure the candidate space matches the signed assignment |
Production builds bake the Authorizer and Release public-key pins into the binary. Development builds can enable alternate pins explicitly, but a production build fails closed rather than accepting an environment-provided replacement trust root.
Supervisor and runner
The agent separates work into two processes:
- The supervisor owns the device key, pinned trust, signed catalog, lease validation, and candidate sealing.
- The runner receives a narrow per-lease job and executes the already-approved tool without invoking a shell.
The runner does not need the device key, trust pins, or tool catalog. This boundary is enforced by the code and process interface today. Both processes still run under the same confined service account, so this is not a strong OS security boundary. A separate runner identity with tighter filesystem, system-call, and network isolation remains planned.
Search execution
The implemented agent supports wordlist ranges and hashcat-keyspace mask chunks. It fetches only the assigned portion of a large wordlist and checks that range against its signed hash before execution. Mask work is checked against the shared mask grammar and signed unit definition.
The bundled hashcat supports the current Blockchain.com and Bitcoin Core safe-test-piece formats. Blockchain.com’s one-block test can return false positives over a large search, so the runner keeps searching after a match and can report multiple candidates. Verify, not hashcat’s exit code, decides whether any candidate is correct.
Failures after accepting a lease are reported explicitly where possible. This lets the coordinator reopen work without waiting for an abandoned lease to expire.
Candidate reporting
A possible password is encrypted on the device using ephemeral X25519 key agreement, HKDF-SHA-256, and ChaCha20-Poly1305. The lease context is authenticated as associated data. The semi-trusted coordinator relays the ciphertext but cannot read it.
The report itself is signed by the enrolled device key. Verify then checks the signed assignment, candidate membership, and wallet-specific ground truth before accepting a recovery.
Sealing does not hide a found password from the operator who controls the machine. The runner must handle the candidate locally, and a hostile host can inspect its own process. The safe-test-piece design makes that acceptable only because the operator lacks the wallet material needed to spend.
Signed installation and updates
The release pipeline produces a package containing the agent, hashcat bundle, signed tool catalog, service definition, configuration template, and build provenance. An Ed25519-signed release manifest lists every packaged file and its SHA-256 digest.
Before installation, the package verifier checks the release signature, every listed file hash, package paths, and unexpected files. The systemd installation runs under a dedicated service account with restricted capabilities, protected system paths, and narrowly granted NVIDIA device access. A digest-pinned container deployment path also exists for compatible operator environments.
Reproducible builds
The reproducible-build tooling covers the two security-relevant binaries shipped to an operator:
- the Rust
distribrute-agentbinary; - the bundled hashcat binary and required modules.
The build uses a digest-pinned container image, a pinned Rust toolchain, a locked dependency graph, canonical build paths, normalized source paths, and declared build-time public keys. Hashcat uses a declared source timestamp, generic x86-64 target, fixed version input, and deterministic build options.
Each release’s provenance records the relevant source commits, declared timestamp, baked public-key pins, toolchain information, and expected agent and hashcat digests. The reproduction command rebuilds both artifacts from those inputs, compares their SHA-256 digests, and fails on a mismatch. The signed release package and deterministic archive are built inside the same pinned environment.
Reproducibility boundary
The agent and hashcat binaries are designed to reproduce bit-for-bit. The complete runtime container image is not yet fully reproducible because its final operating-system package layer is not version-pinned to a snapshot. This does not change the reproduced binary digests, but the distinction should be explicit.
Independent reproduction also requires access to the exact source revisions and release provenance. The build capability being live does not, by itself, claim that every source revision or release is publicly distributed.
Implemented and planned scope
Live in code: Linux x86-64 with NVIDIA GPUs, signed enrollment and reports, wordlist and mask work, the supervisor/runner split, real hashcat execution, idle gating, signed packages, package verification, systemd and container installation paths, and reproducible agent/hashcat binaries.
Planned: Windows, macOS, and AMD operator releases; a stronger OS boundary around the runner; fully reproducible runtime images; and broader self-service fleet operation.
For the surrounding trust boundaries, see System architecture and Trust model.