Supelock Registry

The identity backbone of the Supelock system.

Maps actor_id → Ed25519 public key so the Supelock middleware can verify signed agent requests.

What is Supelock? · Quickstart · API Reference · Contributing

---

What is Supelock?

Today, when an AI agent hits your API, you have no way to tell if it's a legitimate bot or a malicious scraper. Both look identical at the HTTP level.

Supelock fixes this. Agents cryptographically sign every request with a declared intent. Your server verifies the signature and grants trust based on verified identity — not guesswork.

Agent (SDK)          Registry              Middleware            Your API
    |                    |                     |                    |
    |-- POST /register ->|                     |                    |
    |<- 201 Created -----|                     |                    |
    |                    |                     |                    |
    |---------- signed request (X-Supelock-*) -------->|           |
    |                    |<-- GET /actors/id --|                    |
    |                    |--- public key ----->|                    |
    |                    |                     |-- verified ------->|
    |                    |                     |<- 200 OK ----------|

This repo is the Registry — the service that stores and serves public keys.

---

Quickstart

Requirements: Python 3.10+

git clone https://github.com/Sagnikkroy/Supelock-Registry
cd Supelock-Registry
pip install fastapi "uvicorn[standard]" aiosqlite httpx pydantic cryptography
uvicorn supelock_registry.main:app --port 8001 --reload

Open http://localhost:8001/docs to see the interactive API.

---

API Reference

Register an agent

POST /actors/register

{
  "actor_id": "my-ci-bot",
  "public_key": "<base64-encoded Ed25519 public key>",
  "label": "CI pipeline bot",
  "owner": "team-infra"
}

Returns 201 Created on success, 409 Conflict if the actor already exists.

---

Look up a public key

GET /actors/{actor_id}

Returns 200 OK with the actor's public key and metadata. Returns 404 Not Found if unknown, 410 Gone if revoked.

This is the endpoint the middleware calls on every incoming Supelock request.

---

Revoke an agent

DELETE /actors/{actor_id}

Soft-deletes the actor — sets revoked_at timestamp. The record is preserved for auditing. Any future middleware lookup returns 410 Gone immediately.

---

List all actors

GET /actors?owner=team-infra&include_revoked=false

Useful for dashboards and auditing. Filter by owner to scope to a team or project.

---

Health check

GET /health

{
  "status": "ok",
  "database": "connected",
  "service": "supelock-registry",
  "version": "0.1.0"
}

---

Connecting to the Middleware

Copy registry_client.py into your Supelock-Middleware repo and replace the hardcoded dict in registry.py:

from registry_client import RegistryClient

registry = RegistryClient("http://localhost:8001")

# fetch public key for verification
public_key = await registry.get_public_key(actor_id)

RegistryClient handles 404, 410, network timeouts, and optional in-memory caching automatically.

---

Project Structure

Supelock-Registry/
├── supelock_registry/
│   ├── main.py          # FastAPI app + lifespan
│   ├── database.py      # SQLite setup via aiosqlite
│   ├── schemas.py       # Pydantic request/response models
│   ├── crud.py          # All database operations
│   └── routes/
│       ├── actors.py    # Register, lookup, revoke, list
│       └── health.py    # Health check
├── registry_client.py   # HTTP client for middleware to use
├── tests/
│   └── test_registry.py # 12 tests, all passing
└── pyproject.toml

---

Running Tests

pip install pytest pytest-asyncio cryptography httpx
pytest tests/ -v

Expected: 12 passed.

---

Part of the Supelock Ecosystem

Repo	Role	Status
Supelock-SDK	Agent identity + request signing	✅ Built
Supelock-Registry	Public key storage	✅ Built (this repo)
Supelock-Middleware	Verification + trust assignment	✅ Built
Supelock-Policy	Rate limits + intent enforcement	🚧 In progress
Supelock-Dashboard	Live request monitoring UI	📋 Planned

---

Contributing

Issues, PRs, and feedback are welcome. This is an early-stage open source project — your input shapes the direction.

Good first issues to pick up:

• Key rotation — allow an actor to update its public key with proof of old key ownership
• PostgreSQL backend — add an alternative to SQLite for production deployments
• API key auth — require a bearer token to register/revoke actors (prevent spam)
• Prometheus metrics — expose request counts, latency, actor count at /metrics
• Docker image — publish a minimal image to GitHub Container Registry
• Rate limiting on the registry itself — prevent registration floods

To contribute:

git clone https://github.com/Sagnikkroy/Supelock-Registry
cd Supelock-Registry
pip install fastapi "uvicorn[standard]" aiosqlite httpx pydantic cryptography pytest pytest-asyncio
pytest tests/ -v   # make sure everything passes before you start

Open an issue before starting large changes so we can discuss the approach first.

---

License

MIT — see LICENSE.