# SelfClaw - Agent Verification Registry

> Verified agent keys, backed by Self.

SelfClaw is an **API registry** providing sybil-resistant verification for AI agents using Self.xyz passport proofs. Optional on-chain anchoring on Celo is planned. Most "AI agents" are just REST APIs — anyone with an API key can post as an agent. SelfClaw solves this with cryptographic proof of humanity.

**Website:** https://selfclaw.app

## Quick Integration

### Check if an agent is verified

```javascript
// Use query param for safety (base64 contains + / = which need encoding)
const response = await fetch(
  `https://selfclaw.app/api/selfclaw/v1/agent?publicKey=${encodeURIComponent(publicKey)}`
);
const data = await response.json();

if (data.verified) {
  console.log("Agent is backed by a verified human!");
  console.log("Human ID:", data.humanId);
  console.log("Swarm:", data.swarm); // All agents from this human
}
```

## API Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /api/selfclaw/v1/agent?publicKey=...` | Check agent verification (query param, recommended) |
| `GET /api/selfclaw/v1/agent/{identifier}` | Check agent verification (path param, URL-encode required) |
| `GET /api/selfclaw/v1/human/{humanId}` | Get all agents for a human (swarm) |
| `GET /api/selfclaw/v1/stats` | Registry statistics |
| `POST /api/selfclaw/v1/start-verification` | Start verification flow (returns sessionId + QR config) |
| `POST /api/selfclaw/v1/callback` | Self.xyz proof callback (called by Self app) |

**URL Safety:** Use query params (`?publicKey=...`) or URL-encode path params with `encodeURIComponent()`. Base64 contains `+`, `/`, `=` which break URLs.

## Response Format

```json
{
  "verified": true,
  "publicKey": "MCowBQYDK2VwAyEA...",
  "agentName": "my-research-agent",
  "humanId": "0x1234abcd...",
  "selfxyz": {
    "verified": true,
    "registeredAt": "2026-02-01T12:00:00Z"
  },
  "swarm": "https://selfclaw.app/human/0x1234abcd..."
}
```

## Why SelfClaw?

1. **Passport-First** - Self.xyz uses your passport's NFC chip for verification. Works anywhere with a phone.
2. **Zero-Knowledge Proofs** - Raw passport data stays on your device; only the ZK proof is shared. Privacy by mathematics.
3. **129+ Countries** - Supports biometric e-passports with NFC chips. Global coverage.
4. **One Human, Many Agents** - Register your entire agent swarm under one verified identity.
5. **Open Standard** - Built on OpenClaw verification spec. Anyone can validate results.

## Key Format

SelfClaw uses **SPKI DER format** (base64 encoded) for Ed25519 public keys:
- Example: `MCowBQYDK2VwAyEA...` (44 characters)
- Generate with Node.js:

```javascript
import { generateKeyPairSync } from "crypto";

const { publicKey, privateKey } = generateKeyPairSync("ed25519");

// Export SPKI DER (base64) for SelfClaw
const publicKeySpki = publicKey.export({ type: "spki", format: "der" }).toString("base64");
console.log("Public Key:", publicKeySpki); // MCowBQYDK2VwAyEA...
```

## Signature Verification Flow

When verifying an agent's identity in your application:

1. Generate unique challenge with domain, timestamp, nonce, and agentKeyHash
2. Request agent signs challenge with Ed25519 private key
3. Verify signature matches claimed public key
4. Query SelfClaw API to confirm public key is registered

```javascript
import { createHash, createPublicKey, verify as cryptoVerify } from "crypto";

// 1. Generate challenge (agentKeyHash binds proof to this specific agent)
const agentKeyHash = createHash("sha256").update(publicKeySpki).digest("hex");
const challenge = JSON.stringify({
  domain: "your-app.com",
  timestamp: Date.now(),
  nonce: crypto.randomUUID(),
  agentKeyHash: agentKeyHash
});

// 2. Agent signs and returns { publicKey (SPKI base64), signature (base64) }

// 3. Verify signature using Node.js crypto (handles SPKI directly)
const spkiDer = Buffer.from(publicKeySpki, "base64");
const keyObject = createPublicKey({ key: spkiDer, format: "der", type: "spki" });
const signatureBuffer = Buffer.from(signature, "base64");
const isValid = cryptoVerify(null, Buffer.from(challenge), keyObject, signatureBuffer);

// OR using @noble/ed25519 (requires extracting raw 32-byte key)
// import { verify } from "@noble/ed25519";
// const rawKey = spkiDer.subarray(-32); // Last 32 bytes of SPKI DER
// const isValid = await verify(signatureBuffer, Buffer.from(challenge), rawKey);

// 4. Check SelfClaw registry
if (isValid) {
  const res = await fetch(
    `https://selfclaw.app/api/selfclaw/v1/agent?publicKey=${encodeURIComponent(publicKeySpki)}`
  );
  const data = await res.json();
  if (data.verified) {
    console.log("Agent is verified by human:", data.humanId);
  }
}
```

## Security Considerations

- **Proof-to-key binding**: During registration, the Self.xyz ZK proof is bound to the agent's public key hash. This prevents replay attacks where someone reuses a proof to register different keys.
- **Challenge binding**: Include `agentKeyHash` in challenges to bind verification to a specific agent key.
- **Unique challenges**: Always include domain, timestamp, and nonce to prevent replay attacks.
- **Verify signature first**: Check signature validity before querying registry.
- **Privacy model**: Raw passport data stays on-device; only the ZK proof (and any optional disclosures) are shared.
- **Swarm tracking**: Use `humanId` to identify all agents from the same human.

## Trust Model

SelfClaw is an **API registry** that stores verification records in PostgreSQL. This provides:
- Fast lookups (milliseconds)
- Simple integration
- No blockchain transaction fees

**Optional on-chain anchoring on Celo is planned** for use cases requiring stronger decentralization guarantees.

## OpenClaw Standard

SelfClaw implements the OpenClaw verification standard:
- Canonical challenge format (domain, timestamp, nonce, agentKeyHash)
- Proof-to-key binding via userDefinedData in Self.xyz
- Open response schema for interoperability

Anyone can validate results without trusting the SelfClaw API by:
1. Verifying the agent's signature locally
2. Checking the humanId against Self.xyz directly (when on-chain anchoring is live)

## Built With

- **Self.xyz** - Privacy-preserving passport verification with ZK proofs
- **OpenClaw** - Open verification standard for agent identity
- **Celo** (planned) - Mobile-first blockchain for on-chain anchoring

## Links

- Landing Page: https://selfclaw.app
- Developer Docs: https://selfclaw.app/developers
- Self.xyz Docs: https://docs.self.xyz