# hive-mcp-spire. SPIRE Attestation (AFiR) MCP Server

SPIRE creates a tamper-evident, content-bound signature over the exact agent record submitted by the caller. It proves the integrity and provenance of that submitted record. It does not independently observe the agent or establish that the described event occurred.

SPIRE is the attestation surface of the **AFiR Protection Program** from [Hive Civilization](https://www.thehiveryiq.com). Every attestation is signed with **ML-DSA-65 (NIST FIPS 204)**, a post-quantum signature, by the Hive typed signer. No secret is needed to check an attestation: anyone with the published public key and an independent ML-DSA-65 implementation can verify the signature without contacting Hive. The `verify_attestation` tool shipped in this server is a convenience relay that calls the same signer over the network; it is not itself an offline verifier. See "Verifying without this server" below for how to check an envelope with no call to Hive at all.

Patent Pending. MIT licensed. Build tier (first 1M attestations) free; **verify is always free.**

> **v1.1.0 fix:** prior versions signed `sha256('')` for every attestation. The submitted mint, trajectory, or coherence content was never actually hashed into the envelope. This is fixed as of schema v2 (fragment types `spire.mint.v2` / `spire.trajectory.v2` / `spire.coherence.v2`); see [`RELEASE_NOTES_v1.1.0.md`](./RELEASE_NOTES_v1.1.0.md) for details. Attestations signed before this fix are still ML-DSA-65-signature-valid but are not content-bound. `verify_attestation` now flags them explicitly, and now fails overall validity (not just a side field) when the content you supply does not match what the signer actually hashed.

> **Demo key notice:** the public key currently published by the upstream signer (`get_pubkey`) is documented by that signer as a dedicated demo key, isolated from production keys. Treat attestations minted today as a working proof of the signing and verification mechanism, not as backed by a production key-custody process.

---

## Tools

| Tool | What it seals | Pass |
|---|---|---|
| `sign_mint` | Constitutional agent-instance mint (Atom 1). Instance binding, granted authority, custody terms. No-self-attest custody, decaying authority, non-transferable binding. | `mint`: `{instance_id, agent_ref, authority, granted_at, decay, custodian_ref}`, all six fields required |
| `sign_trajectory` | Agent trajectory record (Atom 2). Binds the submitted ordered causal edges. | `trajectory`: `{run_id, agent_ref, edges:[{from, to, seq, cause}]}`, edges must be non-empty |
| `sign_coherence` | Coherence record (Atom 3, lead claim). Binds the submitted aggregate trajectory-drift measure. It does not establish correctness. | `coherence`: `{run_id, agent_ref, drift_score, window, mandate_ref}`, `drift_score` in `[0,1]` |
| `verify_attestation` | Verify any signed SPIRE attestation by calling the upstream signer plus an independent content check. Returns `{valid, signature_valid, reasons[], content_check, ...}`. Fails `valid` if content does not match what was signed, even if the raw signature checks out. **Always free.** | `attestation`: the full object returned by any sign tool; optional `atom` to re-check content |
| `get_pubkey` | The ML-DSA-65 (FIPS 204) public key, issuer DID, and spec, for independent verification. **Free.** | none |

Each sign tool returns a signed `afir.attestation` object: the ML-DSA-65 `envelope`, its canonical `fragments_canon`, the original `atom` you submitted, and a locally-computed `canonical_fragment_hash`. The server returns success only if the signer-reported hash matches the locally computed hash, so every successful schema v2 response has `content_bound: true`. Every submission is validated against a required-field schema before signing.

Hand the returned object to `verify_attestation`, or to your own independent ML-DSA-65 verifier with the published key, to confirm it. Pass `atom` again to `verify_attestation` to re-check content binding, not just the signature. If the content you supply does not match what was signed, `verify_attestation` reports overall `valid: false` and adds `content_mismatch` to `reasons`, because a valid signature over the wrong content is not proof of the content you are relying on.

---

## Verifying without this server

The signature itself is real ML-DSA-65 (FIPS 204). A third party with the published public key (`get_pubkey`) and their own independent ML-DSA-65 implementation can check `envelope.envelope_signature` without running this server or contacting `HIVE_SIGNER_URL`. That is the sense in which the underlying cryptography is checkable offline. This repository does not currently ship that independent verifier code; `verify_attestation` as implemented here always calls the same upstream signer that issued the envelope. If you need a verification path with no network call to Hive at any point, you will need to bring your own ML-DSA-65 verification library and check the envelope fields directly; that capability is not in this repository today.

---

## Endpoints

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/health` | Liveness |
| `GET` | `/` | Service descriptor and atom map |
| `POST` | `/mcp` | MCP JSON-RPC 2.0 (initialize, tools/list, tools/call, ping) |
| `GET` | `/.well-known/mcp.json` | MCP discovery manifest |
| `GET` | `/.well-known/agent.json` | A2A agent card |

Any other path returns an honest JSON `404` naming the path that was not found and listing the routes above, not a framework default page.

**Transport:** Streamable-HTTP. **Protocol:** MCP `2024-11-05`. **Inbound only**: the server never holds custody; it relays typed fragments to the Hive signer and returns the signed envelope.

Upstream signer: `https://hive-typed-signer.onrender.com` (override with `HIVE_SIGNER_URL`). The server validates `HIVE_SIGNER_URL` and `PORT` at startup and refuses to start with a malformed value, instead of failing confusingly on the first tool call.

---

## Connect

**Hosted:** the README previously pointed at `https://hive-mcp-spire.onrender.com/mcp` as the recommended connection method. As of this writing that hosted URL returns `404` on `/health`, `/`, and every other path; it is not currently live. Use the local instructions below until a hosted deploy is confirmed reachable.

**Smithery:** [smithery.ai/new?repo=srotzin/hive-mcp-spire](https://smithery.ai/new?repo=srotzin/hive-mcp-spire)

**Local:**

```bash
git clone https://github.com/srotzin/hive-mcp-spire.git
cd hive-mcp-spire
npm install
node server.js     # listens on :3000
```

Quick check:

```bash
curl -s http://localhost:3000/health
curl -s -X POST http://localhost:3000/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

---

## Environment

| Var | Default | Purpose |
|---|---|---|
| `PORT` | `3000` | Listen port. Must be a positive number or the server refuses to start. |
| `ENABLE` | `true` | Set `false` for a dormant health-only instance |
| `HIVE_SIGNER_URL` | `https://hive-typed-signer.onrender.com` | Upstream typed signer. Must be a valid `http` or `https` URL or the server refuses to start. |

---

## Testing

```bash
npm install
npm test                  # unit + schema + legacy-detection + integration
npm run test:unit         # canonicalization, atom-schema, and legacy-detection tests, no network required
npm run test:integration  # live MCP server plus upstream-signer round trip; self-skips cleanly if the signer is unreachable
```

CI (`.github/workflows/ci.yml`) runs the full suite on Node 18, 20, and 22 on every push and pull request, then starts the server and confirms `/health` and `/.well-known/mcp.json` respond.

---

## Why this exists

SPIRE binds the exact submitted state into a post-quantum signature that can be checked independently of Hive's servers, given an independent ML-DSA-65 implementation and the published key. The result proves that the signed bytes have not changed and identifies the signing key. Additional evidence is required to establish whether the submitted state accurately describes a real event.

Part of the Hive Civilization agent economy. Copyright 2026 Steve Rotzin / Hive Civilization. MIT.