@xtr-dev/rondevu-server 0.4.0 → 0.5.0

package/README.md

@@ -2,9 +2,9 @@
 
 [![npm version](https://img.shields.io/npm/v/@xtr-dev/rondevu-server)](https://www.npmjs.com/package/@xtr-dev/rondevu-server)
 
-🌐 **DNS-like WebRTC signaling with username claiming and service discovery**
+🌐 **Simple WebRTC signaling with RPC interface**
 
-Scalable WebRTC signaling server with cryptographic username claiming, service publishing, and privacy-preserving discovery.
+Scalable WebRTC signaling server with cryptographic username claiming, service publishing with semantic versioning, and efficient offer/answer exchange via JSON-RPC interface.
 
 **Related repositories:**
 - [@xtr-dev/rondevu-client](https://github.com/xtr-dev/rondevu-client) - TypeScript client library ([npm](https://www.npmjs.com/package/@xtr-dev/rondevu-client))
@@ -15,12 +15,14 @@ Scalable WebRTC signaling server with cryptographic username claiming, service p
 
 ## Features
 
+- **RPC Interface**: Single endpoint for all operations with batching support
 - **Username Claiming**: Cryptographic username ownership with Ed25519 signatures (365-day validity, auto-renewed on use)
-- **Service Publishing**: Package-style naming with semantic versioning (com.example.chat@1.0.0)
-- **Privacy-Preserving Discovery**: UUID-based service index prevents enumeration
-- **Public/Private Services**: Control service visibility
-- **Stateless Authentication**: AES-256-GCM encrypted credentials, no server-side sessions
+- **Service Publishing**: Service:version@username naming (e.g., `chat:1.0.0@alice`)
+- **Service Discovery**: Random and paginated discovery for finding services without knowing usernames
+- **Semantic Versioning**: Compatible version matching (chat:1.0.0 matches any 1.x.x)
+- **Signature-Based Authentication**: All authenticated requests use Ed25519 signatures
 - **Complete WebRTC Signaling**: Offer/answer exchange and ICE candidate relay
+- **Batch Operations**: Execute multiple operations in a single HTTP request
 - **Dual Storage**: SQLite (Node.js/Docker) and Cloudflare D1 (Workers) backends
 
 ## Architecture
@@ -30,11 +32,13 @@ Username Claiming → Service Publishing → Service Discovery → WebRTC Connec
 
 alice claims "alice" with Ed25519 signature
   ↓
-alice publishes com.example.chat@1.0.0 with multiple offers → receives UUID abc123
+alice publishes chat:1.0.0@alice with offers
   ↓
-bob requests alice/com.example.chat@1.0.0 → gets compatible service with available offer
+bob queries chat:1.0.0@alice (direct) or chat:1.0.0 (discovery) → gets offer SDP
   ↓
-WebRTC connection established via offer/answer exchange
+bob posts answer SDP → WebRTC connection established
+  ↓
+ICE candidates exchanged via server relay
 ```
 
 ## Quick Start
@@ -46,7 +50,7 @@ npm install && npm start
 
 **Docker:**
 ```bash
-docker build -t rondevu . && docker run -p 3000:3000 -e STORAGE_PATH=:memory: -e AUTH_SECRET=$(openssl rand -hex 32) rondevu
+docker build -t rondevu . && docker run -p 3000:3000 -e STORAGE_PATH=:memory: rondevu
 ```
 
 **Cloudflare Workers:**
@@ -54,351 +58,201 @@ docker build -t rondevu . && docker run -p 3000:3000 -e STORAGE_PATH=:memory: -e
 npx wrangler deploy
 ```
 
-## API Endpoints
-
-### Public Endpoints
-
-#### `GET /`
-Returns server version and info
-
-#### `GET /health`
-Health check endpoint with version
+## RPC Interface
 
-#### `POST /register`
-Register a new peer and receive credentials (peerId + secret)
+All API calls are made to `POST /rpc` with JSON-RPC format.
 
-Generates a cryptographically random 128-bit peer ID.
+### Request Format
 
-**Response:**
+**Single method call:**
 ```json
 {
-  "peerId": "f17c195f067255e357232e34cf0735d9",
-  "secret": "DdorTR8QgSn9yngn+4qqR8cs1aMijvX..."
+  "method": "getUser",
+  "message": "getUser:alice:1733404800000",
+  "signature": "base64-encoded-signature",
+  "params": {
+    "username": "alice"
+  }
 }
 ```
 
-### User Management (RESTful)
-
-#### `GET /users/:username`
-Check username availability and claim status
-
-**Response:**
+**Batch calls:**
 ```json
-{
-  "username": "alice",
-  "available": false,
-  "claimedAt": 1733404800000,
-  "expiresAt": 1765027200000,
-  "publicKey": "..."
-}
+[
+  {
+    "method": "getUser",
+    "message": "getUser:alice:1733404800000",
+    "signature": "base64-encoded-signature",
+    "params": { "username": "alice" }
+  },
+  {
+    "method": "claimUsername",
+    "message": "claim:bob:1733404800000",
+    "signature": "base64-encoded-signature",
+    "params": {
+      "username": "bob",
+      "publicKey": "base64-encoded-public-key"
+    }
+  }
+]
 ```
 
-#### `POST /users/:username`
-Claim a username with cryptographic proof
-
-**Request:**
-```json
-{
-  "publicKey": "base64-encoded-ed25519-public-key",
-  "signature": "base64-encoded-signature",
-  "message": "claim:alice:1733404800000"
-}
-```
+### Response Format
 
-**Response:**
+**Single response:**
 ```json
 {
-  "username": "alice",
-  "claimedAt": 1733404800000,
-  "expiresAt": 1765027200000
+  "success": true,
+  "result": { /* method-specific data */ }
 }
 ```
 
-**Validation:**
-- Username format: `^[a-z0-9][a-z0-9-]*[a-z0-9]$` (3-32 characters)
-- Signature must be valid Ed25519 signature
-- Timestamp must be within 5 minutes (replay protection)
-- Expires after 365 days, auto-renewed on use
-
-#### `GET /users/:username/services/:fqn`
-Get service by username and FQN with semver-compatible matching
-
-**Semver Matching:**
-- Requesting `chat@1.0.0` matches any `1.x.x` version
-- Major version must match exactly (`chat@1.0.0` will NOT match `chat@2.0.0`)
-- For major version 0, minor must also match (`0.1.0` will NOT match `0.2.0`)
-- Returns the most recently published compatible version
-
-**Response:**
+**Error response:**
 ```json
 {
-  "uuid": "abc123",
-  "serviceId": "service-id",
-  "username": "alice",
-  "serviceFqn": "chat.app@1.0.0",
-  "offerId": "offer-hash",
-  "sdp": "v=0...",
-  "isPublic": true,
-  "metadata": {},
-  "createdAt": 1733404800000,
-  "expiresAt": 1733405100000
+  "success": false,
+  "error": "Error message"
 }
 ```
 
-**Note:** Returns a single available offer from the service. If all offers are in use, returns 503.
+**Batch responses:** Array of responses matching request array order.
 
-### Service Management (RESTful)
+## Core Methods
 
-#### `POST /users/:username/services`
-Publish a service with multiple offers (requires authentication and username signature)
+### Username Management
 
-**Headers:**
-- `Authorization: Bearer {peerId}:{secret}`
-
-**Request:**
-```json
+```typescript
+// Check username availability
+POST /rpc
 {
-  "serviceFqn": "com.example.chat@1.0.0",
-  "offers": [
-    { "sdp": "v=0..." },
-    { "sdp": "v=0..." }
-  ],
-  "ttl": 300000,
-  "isPublic": false,
-  "metadata": { "description": "Chat service" },
-  "signature": "base64-encoded-signature",
-  "message": "publish:alice:com.example.chat@1.0.0:1733404800000"
+  "method": "getUser",
+  "params": { "username": "alice" }
 }
-```
 
-**Response (Full service details):**
-```json
+// Claim username (requires signature)
+POST /rpc
 {
-  "uuid": "uuid-v4-for-index",
-  "serviceId": "uuid-v4",
-  "username": "alice",
-  "serviceFqn": "com.example.chat@1.0.0",
-  "offers": [
-    {
-      "offerId": "offer-hash-1",
-      "sdp": "v=0...",
-      "createdAt": 1733404800000,
-      "expiresAt": 1733405100000
-    },
-    {
-      "offerId": "offer-hash-2",
-      "sdp": "v=0...",
-      "createdAt": 1733404800000,
-      "expiresAt": 1733405100000
-    }
-  ],
-  "isPublic": false,
-  "metadata": { "description": "Chat service" },
-  "createdAt": 1733404800000,
-  "expiresAt": 1733405100000
+  "method": "claimUsername",
+  "message": "claim:alice:1733404800000",
+  "signature": "base64-signature",
+  "params": {
+    "username": "alice",
+    "publicKey": "base64-public-key"
+  }
 }
 ```
 
-**Service FQN Format:**
-- Service name: Reverse domain notation (e.g., `com.example.chat`)
-- Version: Semantic versioning (e.g., `1.0.0`, `2.1.3-beta`)
-- Complete FQN: `service-name@version` (e.g., `com.example.chat@1.0.0`)
-
-**Validation:**
-- Service name pattern: `^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$`
-- Length: 3-128 characters
-- Version pattern: `^[0-9]+\.[0-9]+\.[0-9]+(-[a-z0-9.-]+)?$`
-
-#### `GET /services/:uuid`
-Get service details by UUID
-
-**Response:**
-```json
-{
-  "serviceId": "...",
-  "username": "alice",
-  "serviceFqn": "com.example.chat@1.0.0",
-  "offerId": "...",
-  "sdp": "v=0...",
-  "isPublic": false,
-  "metadata": { ... },
-  "createdAt": 1733404800000,
-  "expiresAt": 1733405100000
-}
-```
-
-#### `DELETE /users/:username/services/:fqn`
-Unpublish a service (requires authentication and ownership)
-
-**Headers:**
-- `Authorization: Bearer {peerId}:{secret}`
+### Service Publishing
 
-**Request:**
-```json
+```typescript
+// Publish service (requires signature)
+POST /rpc
 {
-  "username": "alice"
+  "method": "publishService",
+  "message": "publishService:alice:chat:1.0.0@alice:1733404800000",
+  "signature": "base64-signature",
+  "params": {
+    "serviceFqn": "chat:1.0.0@alice",
+    "offers": [{ "sdp": "webrtc-offer-sdp" }],
+    "ttl": 300000
+  }
 }
 ```
 
-### WebRTC Signaling (Service-Based)
-
-#### `POST /services/:uuid/answer`
-Answer a service offer (requires authentication)
+### Service Discovery
 
-**Headers:**
-- `Authorization: Bearer {peerId}:{secret}`
-
-**Request:**
-```json
+```typescript
+// Get specific service
+POST /rpc
 {
-  "sdp": "v=0..."
+  "method": "getService",
+  "params": { "serviceFqn": "chat:1.0.0@alice" }
 }
-```
 
-**Response:**
-```json
+// Random discovery
+POST /rpc
 {
-  "success": true,
-  "offerId": "offer-hash"
+  "method": "getService",
+  "params": { "serviceFqn": "chat:1.0.0" }
 }
-```
 
-#### `GET /services/:uuid/answer`
-Get answer for a service (offerer polls this)
-
-**Headers:**
-- `Authorization: Bearer {peerId}:{secret}`
-
-**Response:**
-```json
+// Paginated discovery
+POST /rpc
 {
-  "offerId": "offer-hash",
-  "answererId": "answerer-peer-id",
-  "sdp": "v=0...",
-  "answeredAt": 1733404800000
+  "method": "getService",
+  "params": {
+    "serviceFqn": "chat:1.0.0",
+    "limit": 10,
+    "offset": 0
+  }
 }
 ```
 
-**Note:** Returns 404 if not yet answered
-
-#### `POST /services/:uuid/ice-candidates`
-Post ICE candidates for a service (requires authentication)
+### WebRTC Signaling
 
-**Headers:**
-- `Authorization: Bearer {peerId}:{secret}`
-
-**Request:**
-```json
+```typescript
+// Answer offer (requires signature)
+POST /rpc
 {
-  "candidates": ["candidate:1 1 UDP..."],
-  "offerId": "optional-offer-id"
+  "method": "answerOffer",
+  "message": "answer:bob:offer-id:1733404800000",
+  "signature": "base64-signature",
+  "params": {
+    "serviceFqn": "chat:1.0.0@alice",
+    "offerId": "offer-id",
+    "sdp": "webrtc-answer-sdp"
+  }
 }
-```
 
-**Response:**
-```json
+// Add ICE candidates (requires signature)
+POST /rpc
 {
-  "count": 1,
-  "offerId": "offer-hash"
+  "method": "addIceCandidates",
+  "params": {
+    "serviceFqn": "chat:1.0.0@alice",
+    "offerId": "offer-id",
+    "candidates": [{ /* RTCIceCandidateInit */ }]
+  }
 }
-```
-
-**Note:** If `offerId` is omitted, the server will auto-detect the peer's offer
-
-#### `GET /services/:uuid/ice-candidates?since=1234567890&offerId=optional-offer-id`
-Get ICE candidates from the other peer (requires authentication)
-
-**Headers:**
-- `Authorization: Bearer {peerId}:{secret}`
 
-**Response:**
-```json
+// Poll for answers and ICE candidates (requires signature)
+POST /rpc
 {
-  "candidates": [
-    {
-      "candidate": "candidate:1 1 UDP...",
-      "createdAt": 1733404800000
-    }
-  ],
-  "offerId": "offer-hash"
+  "method": "poll",
+  "params": { "since": 1733404800000 }
 }
 ```
 
-**Note:** Returns candidates from the opposite role (offerer gets answerer candidates and vice versa)
-
 ## Configuration
 
-Environment variables:
+Quick reference for common environment variables:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PORT` | `3000` | Server port (Node.js/Docker) |
 | `CORS_ORIGINS` | `*` | Comma-separated allowed origins |
 | `STORAGE_PATH` | `./rondevu.db` | SQLite database path (use `:memory:` for in-memory) |
-| `VERSION` | `2.0.0` | Server version (semver) |
-| `AUTH_SECRET` | Random 32-byte hex | Secret key for credential encryption (required for production) |
-| `OFFER_DEFAULT_TTL` | `300000` | Default offer TTL in ms (5 minutes) |
-| `OFFER_MIN_TTL` | `60000` | Minimum offer TTL in ms (1 minute) |
-| `OFFER_MAX_TTL` | `3600000` | Maximum offer TTL in ms (1 hour) |
-| `MAX_OFFERS_PER_REQUEST` | `10` | Maximum offers per create request |
-
-## Database Schema
-
-### usernames
-- `username` (PK): Claimed username
-- `public_key`: Ed25519 public key (base64)
-- `claimed_at`: Claim timestamp
-- `expires_at`: Expiry timestamp (365 days)
-- `last_used`: Last activity timestamp
-- `metadata`: Optional JSON metadata
-
-### services
-- `id` (PK): Service ID (UUID)
-- `username` (FK): Owner username
-- `service_fqn`: Fully qualified name (com.example.chat@1.0.0)
-- `is_public`: Public/private flag
-- `metadata`: JSON metadata
-- `created_at`, `expires_at`: Timestamps
-
-### offers
-- `id` (PK): Offer ID (hash of SDP)
-- `peer_id` (FK): Owner peer ID
-- `service_id` (FK): Optional link to service (null for standalone offers)
-- `sdp`: WebRTC offer SDP
-- `answerer_peer_id`: Peer ID of answerer (null until answered)
-- `answer_sdp`: WebRTC answer SDP (null until answered)
-- `created_at`, `expires_at`, `last_seen`: Timestamps
-
-### service_index (privacy layer)
-- `uuid` (PK): Random UUID for discovery
-- `service_id` (FK): Links to service
-- `username`, `service_fqn`: Denormalized for performance
 
-## Security
+📚 See [ADVANCED.md](./ADVANCED.md#configuration) for complete configuration reference.
 
-### Username Claiming
-- **Algorithm**: Ed25519 signatures
-- **Message Format**: `claim:{username}:{timestamp}`
-- **Replay Protection**: Timestamp must be within 5 minutes
-- **Key Management**: Private keys never leave the client
+## Documentation
 
-### Service Publishing
-- **Ownership Verification**: Every publish requires username signature
-- **Message Format**: `publish:{username}:{serviceFqn}:{timestamp}`
-- **Auto-Renewal**: Publishing a service extends username expiry
-
-### Privacy
-- **Private Services**: Only UUID exposed, FQN hidden
-- **Public Services**: FQN and metadata visible
-- **No Enumeration**: Cannot list all services without knowing FQN
+📚 **[ADVANCED.md](./ADVANCED.md)** - Comprehensive guide including:
+- Complete RPC method reference with examples
+- Full configuration options
+- Database schema documentation
+- Security implementation details
+- Migration guides
 
-## Migration from V1
+## Security
 
-V2 is a **breaking change** that removes topic-based discovery. See [MIGRATION.md](../MIGRATION.md) for detailed migration guide.
+All authenticated operations require Ed25519 signatures:
+- **Message Format**: `{method}:{username}:{context}:{timestamp}`
+- **Signature**: Base64-encoded Ed25519 signature of the message
+- **Replay Protection**: Timestamps must be within 5 minutes
+- **Username Ownership**: Verified via public key signature
 
-**Key Changes:**
-- ❌ Removed: Topic-based discovery, bloom filters, public peer listings
-- ✅ Added: Username claiming, service publishing, UUID-based privacy
+See [ADVANCED.md](./ADVANCED.md#security) for detailed security documentation.
 
 ## License