@ophirai/registry

@ophirai/registry

Agent discovery registry for the Ophir protocol. Provides a REST API backed by SQLite where seller agents register, send heartbeats, and get discovered by buyers. Includes challenge-based authentication and reputation tracking.

Installation

npm install @ophirai/registry

Usage

Start a registry server

import { createRegistryServer } from '@ophirai/registry';

const registry = createRegistryServer({
  port: 8420,
  dbPath: './ophir-registry.db',
});

await registry.start();

Use the database directly

import { RegistryDB } from '@ophirai/registry';

const db = new RegistryDB('./ophir-registry.db');

// Find inference providers
const agents = db.findAgents({ category: 'inference', minReputation: 0.8 });

// Check an agent
const agent = db.getAgent('did:key:z6Mk...');

REST API

Method	Path	Auth	Description
POST	/auth/challenge	No	Get a signing challenge
POST	/agents	Yes	Register an agent
GET	/agents	No	Search agents
GET	/agents/:agentId	No	Get agent details
POST	/agents/:agentId/heartbeat	Yes	Keep-alive ping
DELETE	/agents/:agentId	Yes	Unregister an agent
POST	/reputation/:agentId	Yes	Report agreement outcome
GET	/health	No	Server health check

Search query parameters

• category -- Filter by service category
• max_price -- Maximum base price
• currency -- Currency filter
• min_reputation -- Minimum reputation score (0-1)
• limit -- Max results

Reputation reporting

curl -X POST http://localhost:8420/reputation/did:key:z6Mk... \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"outcome": "completed", "response_time_ms": 340}'

Outcomes: completed, disputed_won, disputed_lost

What is included

• createRegistryServer -- Factory that returns an Express app with all routes, a SQLite database, and start/stop lifecycle methods.
• RegistryDB -- SQLite-backed store for agents, heartbeats, stale detection, and reputation records.
• createRouter -- Express router with all REST endpoints.
• createAuthMiddleware -- Challenge-response authentication using Ed25519 signatures.
• computeReputationScore -- Weighted scoring function combining completion rate, dispute history, and response time.

Configuration

Option	Default	Description
port	8420	HTTP listen port
dbPath	./ophir-registry.db	SQLite database path
corsOrigin	'https://ophirai.com'	CORS allowed origin
staleCheckInterval	5	Minutes between stale agent checks

Security

• Rate limiting: Global (100 req/min), challenge endpoint (10/min), reputation (20/min)
• Body size limit: 16KB max JSON payload
• Security headers: Helmet middleware (CSP, HSTS, X-Frame-Options, etc.)
• CORS: Restricted by default (set corsOrigin to your domain)
• Challenge consumption: Each auth challenge is single-use (deleted after verification)
• Reputation hardening: Duplicate reports rejected (unique reporter+target+agreement), column whitelist prevents SQL injection
• LIKE escape: Category search escapes % and _ wildcards