@crayvera/sidecar

Local sidecar daemon for signing and anchoring agent actions. Provides HTTP API for integration with any language or framework.

Features

• HTTP API: REST endpoints for signing, verification, and anchoring
• Background Queue: Batch anchor requests for efficient on-chain submission
• Process Management: Start/stop/status with PID file tracking
• Unix Socket Support: Optional Unix socket binding for local-only access
• Replay Protection: Built-in nonce and timestamp validation

Installation

pnpm add @crayvera/sidecar

Quick Start

Via CLI

# Start sidecar daemon
crayvera launch sidecar

# Start with specific options
crayvera launch sidecar --port 4000 --agent YOUR_PUBKEY --network devnet

# Check status
crayvera launch sidecar-status

# Stop sidecar
crayvera launch sidecar-stop

Via Standalone CLI

# Start
crayvera-sidecar start

# Start with options
crayvera-sidecar start --port 4000 --agent YOUR_PUBKEY

# Check status
crayvera-sidecar status

# Stop
crayvera-sidecar stop

Programmatic Usage

import { SidecarServer } from '@crayvera/sidecar';

const server = new SidecarServer({
  port: 3847,
  agentPubkey: 'YOUR_AGENT_PUBKEY',
  network: 'devnet',
  enableQueue: true,
});

await server.start();

// Handle shutdown
process.on('SIGINT', async () => {
  await server.stop();
  process.exit(0);
});

API Endpoints

GET /health

Health check endpoint.

curl http://localhost:3847/health

Response:

{ "status": "ok" }

GET /status

Get agent and queue status.

curl http://localhost:3847/status

Response:

{
  "version": "0.1.0",
  "status": "running",
  "agent": {
    "pubkey": "ABC123...",
    "shortId": "ABC123",
    "status": "active",
    "network": "devnet"
  },
  "queue": {
    "size": 5,
    "pending": 0,
    "flushedTotal": 42
  },
  "uptime": 3600
}

POST /sign

Sign arbitrary data.

curl -X POST http://localhost:3847/sign \
  -H "Content-Type: application/json" \
  -d '{"data": "Hello, World!"}'

Response:

{
  "signature": "base64-encoded-signature",
  "agentPubkey": "ABC123...",
  "timestamp": 1707123456789
}

POST /sign-http

Sign an HTTP request (for making authenticated API calls).

curl -X POST http://localhost:3847/sign-http \
  -H "Content-Type: application/json" \
  -d '{
    "method": "POST",
    "path": "/api/data",
    "body": "{\"key\": \"value\"}"
  }'

Response:

{
  "headers": {
    "X-Crayvera-Agent": "ABC123...",
    "X-Crayvera-Sig": "CRAYVERA-SIG-V1:sig:nonce:timestamp"
  }
}

POST /anchor

Anchor an action to Solana. Actions are queued by default for batch submission.

curl -X POST http://localhost:3847/anchor \
  -H "Content-Type: application/json" \
  -d '{
    "type": "COMMIT",
    "hash": "abc123def456...",
    "metadata": {"repo": "my-project"},
    "queue": true
  }'

Response (queued):

{
  "queued": true,
  "queuePosition": 5
}

Response (immediate, with "queue": false):

{
  "queued": false,
  "result": {
    "txSignature": "...",
    "proofAddress": "...",
    "timestamp": 1707123456789
  }
}

POST /anchor/flush

Manually flush the anchor queue.

curl -X POST http://localhost:3847/anchor/flush

Response:

{
  "flushed": 5,
  "failed": 0,
  "results": [...]
}

POST /verify

Verify an HTTP request signature.

curl -X POST http://localhost:3847/verify \
  -H "Content-Type: application/json" \
  -d '{
    "method": "POST",
    "path": "/api/data",
    "headers": {
      "X-Crayvera-Agent": "ABC123...",
      "X-Crayvera-Sig": "CRAYVERA-SIG-V1:sig:nonce:timestamp"
    },
    "body": "{\"key\": \"value\"}"
  }'

Response:

{
  "verified": true,
  "agentPubkey": "ABC123...",
  "agentStatus": "active"
}

POST /verify-hash

Verify an action hash on-chain.

curl -X POST http://localhost:3847/verify-hash \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "abc123def456...",
    "agentPubkey": "ABC123..."
  }'

Configuration

| Option | CLI Flag | Default | Description | | -------------------- | ------------------ | ----------- | -------------------------------------- | | port | --port | 3847 | HTTP port to listen on | | host | --host | 127.0.0.1 | Host to bind to | | socketPath | --socket | - | Unix socket path (alternative to port) | | agentPubkey | --agent | - | Agent public key to load | | network | --network | devnet | Solana network | | enableQueue | --no-queue | true | Enable anchoring queue | | queueFlushInterval | --queue-interval | 30000 | Queue flush interval (ms) | | maxQueueSize | --queue-size | 100 | Max queue size before auto-flush |

Security

The sidecar binds to 127.0.0.1 by default, making it accessible only from the local machine. For production deployments:

1. Never expose to the internet - The sidecar has no authentication
2. Use Unix sockets for tighter security: --socket /tmp/crayvera.sock
3. Run as a dedicated user with minimal permissions
4. Use a firewall to block external access to the port

Integration Examples

Python

import requests

SIDECAR_URL = "http://localhost:3847"

# Sign an HTTP request
def sign_request(method, path, body=None):
    response = requests.post(f"{SIDECAR_URL}/sign-http", json={
        "method": method,
        "path": path,
        "body": body,
    })
    return response.json()["headers"]

# Make authenticated request
headers = sign_request("POST", "/api/data", '{"key": "value"}')
response = requests.post("https://api.example.com/api/data", 
                        headers=headers,
                        json={"key": "value"})

Go

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

const sidecarURL = "http://localhost:3847"

func signRequest(method, path, body string) (map[string]string, error) {
    payload := map[string]string{
        "method": method,
        "path":   path,
        "body":   body,
    }
    
    data, _ := json.Marshal(payload)
    resp, err := http.Post(sidecarURL+"/sign-http", "application/json", bytes.NewReader(data))
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var result struct {
        Headers map[string]string `json:"headers"`
    }
    json.NewDecoder(resp.Body).Decode(&result)
    
    return result.Headers, nil
}

Shell/Curl

#!/bin/bash

# Sign and make request
HEADERS=$(curl -s -X POST http://localhost:3847/sign-http \
  -H "Content-Type: application/json" \
  -d '{"method": "GET", "path": "/api/status"}')

AGENT=$(echo $HEADERS | jq -r '.headers["X-Crayvera-Agent"]')
SIG=$(echo $HEADERS | jq -r '.headers["X-Crayvera-Sig"]')

curl https://api.example.com/api/status \
  -H "X-Crayvera-Agent: $AGENT" \
  -H "X-Crayvera-Sig: $SIG"

License

MIT