Metadata-Version: 2.4
Name: meok-bft-verifier
Version: 1.0.0
Summary: BFT council verifier MCP - turns SOV3 council votes into Ed25519-signed attestations the A2A economy can verify offline.
Author: meok.ai
License: MIT
Project-URL: Homepage, https://meok.ai
Project-URL: Documentation, https://meok.ai/docs/bft-verifier
Project-URL: Repository, https://github.com/csoai-org/meok-bft-verifier
Keywords: mcp,model-context-protocol,bft,byzantine-fault-tolerance,ed25519,agent-identity,a2a,trust-chain,sov3,meok,council
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25
Requires-Dist: pydantic>=2.0
Requires-Dist: mcp>=0.9.0
Requires-Dist: cryptography>=42.0
Dynamic: license-file

# meok-bft-verifier

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
[![BFT](https://img.shields.io/badge/consensus-3%2F4-critical)](https://en.wikipedia.org/wiki/Byzantine_fault)
[![Ed25519](https://img.shields.io/badge/signed-Ed25519-orange.svg)](https://ed25519.cr.yp.to)

> **BFT council verifier MCP** — turns SOV3 council votes into Ed25519-signed
> attestations the A2A economy can verify offline.

The BFT verifier is the **trust-chain primitive** of the MEOK sovereign
hive. When 3 of 4 hive agents vote "yes" on a council proposal, the
verifier seals the decision into a tamper-evident attestation any agent in
the agent-to-agent (A2A) economy can verify in microseconds — no network
call required.

---

## Install

```bash
pip install meok-bft-verifier
```

From source:

```bash
git clone https://github.com/csoai-org/meok-bft-verifier
cd meok-bft-verifier
pip install -e .
```

---

## 30-second demo

```bash
# Terminal 1 — start SOV3 on localhost:3101 (see SOV3 docs).
# Terminal 2 — install and run:
pip install meok-bft-verifier
meok-bft-verifier
```

The server speaks MCP over stdio. Wire it into Claude Desktop, Cursor, or
any MCP-aware client:

```json
{
  "mcpServers": {
    "meok-bft-verifier": {
      "command": "meok-bft-verifier"
    }
  }
}
```

From an MCP client, ask:

> *"Tally votes on proposal `proposal_2f20a86f8351` and verify the
> attestation."*

The client calls `collect_votes`, then if BFT passes, `verify_attestation`
on the returned attestation — all in one round-trip.

---

## The 2 tools

### `collect_votes(proposal_id, sov3_url="http://localhost:3101")`

Calls SOV3 `/mcp tools/call get_proposal_votes(proposal_id)`, normalises
the response, and BFT-tallies the votes against the known 4 hive agents:

| voter               | role                                  |
|---------------------|---------------------------------------|
| `m2_cowork_claude`     | Apple silicon M2 MacBook, cowork lane     |
| `m3_jeeves_strategic`  | Apple silicon M3 MacBook, strategic lane  |
| `m4_keystone_engineer` | Apple silicon M4 MacBook, engineer lane   |
| `orion_substrate`      | Remote GPU runpod, sovereign-substrate lane |

A proposal is BFT-passed when **3 of 4** hive agents vote `"yes"` (f=1
Byzantine fault tolerance — the classical `n ≥ 3f+1` bound for n=4).

If the threshold is met, the verifier signs an **Ed25519 attestation**
and returns it. Otherwise it returns `bft_passed=False` and
`attestation=None`.

```json
{
  "proposal_id": "proposal_2f20a86f8351",
  "votes": [
    {"voter": "m2_cowork_claude",      "vote": "yes", "ts": "2026-06-13T..."},
    {"voter": "m3_jeeves_strategic",   "vote": "yes", "ts": "2026-06-13T..."},
    {"voter": "m4_keystone_engineer",  "vote": "yes", "ts": "2026-06-13T..."}
  ],
  "bft_passed": true,
  "attestation": {
    "proposal_id": "proposal_2f20a86f8351",
    "title": "...",
    "bft_passed": true,
    "votes": [...],
    "voter_count": 3,
    "decided_at": "2026-06-13T...",
    "attestation_id": "uuid",
    "issuer": "meok-bft-verifier",
    "signature": "<128 hex chars Ed25519>",
    "public_key": "<128 hex chars>",
    "kid": "meok-bft-..."
  }
}
```

### `verify_attestation(attestation)`

**100% offline** Ed25519 verification. No network call, no SOV3 dependency.
Just Ed25519 + a 24h freshness check.

```json
{
  "valid": true,
  "proposal_id": "proposal_2f20a86f8351",
  "bft_passed": true,
  "voter_count": 3,
  "expired": false,
  "signed_by": "meok-bft-a3f9..."
}
```

---

## Why BFT matters

A single agent can lie. A signed vote from one voter is just one opinion.
A BFT council of 4 agents, of which 3 must agree, is a **fault-tolerant
trust primitive**: even if one agent is compromised, hallucinating, or
malicious, the majority verdict still reflects reality.

This is the same machinery that powers Tendermint, HotStuff, and every
production blockchain — wrapped into a single Ed25519 attestation that
fits in a JSON envelope.

In the MEOK hive, every consequential decision (policy changes, OWEM
adoptions, charter amendments, MCP fleet promotions) goes through this
verifier. The signed attestation is the receipt the rest of the A2A
economy uses to decide whether to honour the decision.

---

## EU AI Act alignment

The verifier directly supports **Article 9 (risk management)** and
**Article 12 (record-keeping)**:

- **Article 9.2(b)** — risk management "implemented as a planned
  sequence of measures" → the attestation is a tamper-evident audit
  record of who voted what.
- **Article 12.1** — "automatic recording of events" → every BFT
  decision is captured as a signed JSON envelope.
- **Article 14 (human oversight)** — a 3/4 council majority is
  human-reviewable: any operator can read the `votes` array and audit the
  decision trail.

Pair `meok-bft-verifier` with `meok-compliance-passport-mcp` (the
companion MCP at the same org) to get **signed council decisions** plus
**signed compliance credentials** — the two primitives any Article 9/12
audit will ask for.

---

## The A2A verification chain

```
┌─────────────┐   jsonrpc      ┌──────────────┐
│ BFT verifier│ ─────────────▶ │ SOV3 /mcp    │
│ collect_    │  get_proposal_ │ council +    │
│ votes       │  votes         │ vote ledger  │
└──────┬──────┘                └──────────────┘
       │ 3/4 yes?
       ▼
┌─────────────────┐
│ Ed25519 sign    │ ── attestation ──▶ stored as a sigil on the
│ (canonical JSON)│                    ed25519 chain (offline-verifiable)
└─────────────────┘
       │
       ▼
┌─────────────────┐
│ verify_         │ ── 100% offline Ed25519 verify, voter_count >= 3,
│ attestation     │    decided_at < 24h ago, signed by known kid
└─────────────────┘
       │
       ▼
   verdict: {valid, proposal_id, bft_passed, voter_count, expired, signed_by}
```

The chain is **append-only**, **cryptographically tamper-evident**, and
**offline-verifiable**. That is the trust primitive the A2A economy
needs: any agent, anywhere, can audit any decision without trusting any
intermediary.

---

## Development

```bash
git clone https://github.com/csoai-org/meok-bft-verifier
cd meok-bft-verifier
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v
```

### Key management

The verifier derives its Ed25519 keypair from the `MEOK_BFT_KEY_FILE`
env var (32 raw bytes). If unset, it uses a deterministic version-seeded
ephemeral key — fine for tests, **not for production**. In production
point it at your KMS or the sovereign secrets keystone.

---

## Related MCPs

- [`meok-compliance-passport-mcp`](https://github.com/csoai-ORG/meok-compliance-passport-mcp)
  — signed compliance credentials (EU AI Act, GDPR, HIPAA, …).
- `sov3-bridge` MCP — federated tool access across the MEOK empire.

---

## License

MIT — see [LICENSE](LICENSE).

---

*Built by meok.ai for the sovereign AI substrate.*
