# dgb-digiid-mcp

**Give an AI agent a verifiable identity.** An [MCP](https://modelcontextprotocol.io)
server that lets an agent prove *who it is* using [Digi-ID](https://www.digibyte.org/digi-id/) —
DigiByte's passwordless authentication — by signing a challenge with a key it
never reveals.

The natural companion to [dgb-digidollar-mcp](https://github.com/dgb-tools/dgb-digidollar-mcp):
an agent that can **prove who it is** *and* **pay for what it uses** — the two
genuinely chain-shaped problems of the agent era, both on a decentralized rail.

> Works on testnet or mainnet. Signing and verifying are pure cryptography, so the
> node does **not** need to be synced or funded — any DigiByte node with the
> identity wallet loaded will do. And because no money is involved, it's safe on
> mainnet from day one.

## The flow

```
Service ──"prove who you are": digiid://mysite/cb?x=<nonce>──▶ Agent
Agent   ──signs the URI with its identity key──────────────▶ (no key revealed)
Agent   ──POST { address, uri, signature } ─────────────────▶ Service /callback
Service ──verifies signature + domain + nonce──────────────▶ authenticated as <address>
```

The agent's **address is its identity**. A service recognises the same agent
across sessions without ever handling a password or a shared secret.

**Proven end to end** (see `example/service.js`): an agent authenticated to a
service through the MCP server, and a forged response — the correct challenge
signed with the *wrong* key but claiming the identity address — was rejected with
"signature does not verify."

## Why it can't be faked

- **The signature is bound to the address.** Only the holder of the identity's
  private key can produce a signature that `verifymessage(address, sig, uri)`
  accepts. Claiming someone else's address doesn't help — the math won't verify.
- **Domain-bound.** The signed message is the full `digiid://` URI including your
  domain, so a signature the agent made for another site can't be replayed at yours.
- **Nonce / one-time use.** Each challenge carries a random nonce the service
  issued and burns on use, so a captured response can't be replayed.
- **Legacy-address requirement, handled.** DigiByte message signing only works
  with legacy (P2PKH) addresses, not bech32 — the server checks this at startup
  and fails loudly rather than mysteriously.

## Tools (agent side)

| Tool | What it does |
|------|--------------|
| `get_identity` | Return the agent's Digi-ID address — its stable public identity. Reveals no secret. |
| `authenticate` | Given a `digiid://` challenge, sign it and POST the response to the service's callback. Returns the service's reply. The agent's "log in." |

## Library (service side)

`src/digiid.js` is a dependency-free module a service uses to challenge and verify:

```js
import { buildChallenge, verifyResponse } from "dgb-digiid-mcp";

const { uri, nonce } = buildChallenge({ domain: "mysite.com" });
// ...show uri to the agent (or as a QR to a human's Digi-ID wallet)...

const result = await verifyResponse(
  { address, uri, signature },
  { verifyMessage, expectedDomain: "mysite.com", isNonceValid }
);
if (result.ok) authenticateSession(result.identity);
```

Because Digi-ID is a published standard, the same server works for **human**
Digi-ID wallets too — not just agents.

## Setup

Point it at any DigiByte node and give it a legacy identity address:

```bash
digibyte-cli -rpcwallet=identity getnewaddress "agent" "legacy"   # note the "legacy"
npm install
cp .env.example .env    # RPC creds + DIGIID_ADDRESS
```

Run the demo (a passwordless login service + the agent authenticating to it):

```bash
node --env-file=.env example/service.js     # terminal 1
# then drive the MCP server's `authenticate` tool against the challenge from GET /login
```

Add to your MCP client (`npx dgb-digiid-mcp`), env: `DGB_RPC_URL`, `DGB_RPC_USER`,
`DGB_RPC_PASSWORD`, `DGB_WALLET`, `DIGIID_ADDRESS`.

## Related

- [dgb-digidollar-mcp](https://github.com/dgb-tools/dgb-digidollar-mcp) — the agent *pays* in DigiDollar.
- [dgb-x402](https://github.com/dgb-tools/dgb-x402) — services accept those payments.
- [dgb-chain-mcp](https://github.com/dgb-tools/dgb-chain-mcp) — the agent queries DigiByte.

Independent community project. Not affiliated with the DigiByte Foundation. MIT licensed.