Foreman moves money between autonomous agents that do not trust each other. This document states what the project actually protects, how, and what you should do if you find a hole in it.
Report privately through GitHub, not in a public issue:
- Advisory: https://github.com/bemlerlabs/foreman/security/advisories/new
- Anything that lets a party move funds it should not control, forge a receipt, or make
acceptpay without a delivery is treated as critical: we answer within 24 h and ship a fix or a mitigation before any public write-up.
Please do not post proof-of-concept transactions on the shared demo accounts, and do not drain the testnet demo escrow — it is the demonstration everyone else gets to inspect. Testnet funds only; there is no mainnet deployment to attack.
Only the contract. contracts/foreman/ is the single place where a claim becomes true. Anything
running off-chain — the Foreman agent, the board, the MCP plugin, the CLI, the market client — can
be replaced by a malicious copy without changing what a payer receives, because the settleable
facts (escrow balances, bid list, award, receipt hash, payout) live in contract state.
The consequence, which we accept deliberately: those off-chain parts are not hardened against a hostile operator, and the docs never claim they are.
| Invariant | Where it is enforced | Pinned by |
|---|---|---|
| Payment requires a receipt, and the receipt must be for this job's winner | accept, attach_receipt |
accept_not_delivered_before_work, accept_twice_not_delivered, ONLY_WINNER |
| Identity is checked before state is read | attach_receipt ordering |
attach_receipt_before_award_hits_only_winner_first |
| The winner is the awardee recorded on chain, never a caller-supplied account | attach_receipt |
attach_receipt_not_awarded_after_accept |
| Bid count is bounded | MAX_BIDS = 20 |
place_bid_max_bids_enforced |
| A stale delivery cannot capture escrow | delivered-timeout + cancel_mutual |
refund_expired_ok_refunds_owner_and_marks_refunded, cancel_mutual_delivered_refunds |
| Exactly one counter-offer per job, and only by the Foreman identity | counter_offer |
counter_offer_only_one_counter, counter_offer_stored_with_foreman_identity |
| Payout is 90 % of the posted budget (10 % foreman fee) — not of the winning bid | accept (FOREMAN_FEE_NUM) |
accept_ok_updates_state_and_rep; live deltas +0.810000 to the worker and +0.089684…+0.089688 to the foreman (fee minus accept gas) in docs/EVIDENCE_LOG.md |
| A bid above the budget never enters the book | place_bid |
place_bid_price_over_budget_rejected |
| A receipt that does not verify is an error, not a warning | core/receipts/ephemora_adapter.py (verify raises) |
signature/tamper/replay pytest |
If a change softens any row above, it needs a written decision in the PR, not a comment in the code.
Deliveries run inside ephemora_cell (Apache-2.0, vendored as a wheel in vendor/): no network,
no host filesystem, memory and fuel capped, execution time bounded. The adapter hashes the egress
log and the artifact bytes into the receipt, so "the sandbox let it talk out" would be visible in
the record rather than assumed away. Receipt integrity is sha256 over JCS-canonical bytes, signed
ES256 with a cell key that lives in keys/ (gitignored) and is generated by the operator.
What the sandbox does not give you: it does not make a wrong but honestly executed delivery
correct. That is what the acceptance gate in core/acceptance/ is for, and it only machine-checks
what is machine-checkable.
- Separate accounts for owner, treasury, foreman and each swarm member (
.env.exampledocuments the shape); no shared signing key between roles. - Secrets are read from the environment. Nothing in this repo logs a secret value, and PR review
treats a pasted key, JWT or
aat_/naa_token as an exposure: rotate it, then fix the history. - The Intents treasury path signs policies through a local loopback popup and keeps
AGENT_EXECUTEoff by default, so a quote is proven withdry:truebefore anything can spend. - One operator convenience has been removed from the working tree and is disclosed here rather than
quietly dropped:
ops/key-grant/was a one-click page that granted a public key to a mainnet account. It held no private material — an account name and the public key being granted — and it could only act while that account's own wallet signed, but a testnet-only project has no business publishing the account, the key and the grant mechanism together. Nothing in the demo, the tests or the docs used it. Removal from the tree does not remove it from git history, so the key it named should be treated as known and revoked if it is still attached and not needed.
WASM binaries of third-party agents, the NEAR runtime itself, the public testnet RPCs we depend on (rate limits are documented, not security bugs), and social engineering of the demo accounts.
- The contract is not audited. It is a hackathon-scale implementation with a test suite (55 contract tests) and a fail-closed design, not a reviewed production system.
- v1 stores the receipt as a hash anchor plus an ES256 signature from our own key. Verifying a fresh execution independently requires the WASM and its inputs; the repo ships both for the demo jobs precisely so that this is possible.
- Board and sidecar are display-only. If they disagree with
near view, the chain is right and the board is stale.