camera-trng/skill.md

Camera TRNG API Skill Documentation

This document describes how to use the Camera TRNG (True Random Number Generator) API as an MCP-compatible service.

Overview

The Camera TRNG server provides quantum-based random number generation using thermal noise from a covered camera sensor. The API is accessible via HTTP and self-documents its capabilities through the .well-known/mcp.json endpoint.

Discovery

The API can be discovered by fetching the MCP endpoint:

curl http://localhost:8787/.well-known/mcp.json

The response includes self-referencing URLs that use the request's hostname (from SNI/HTTP Host header), making it work correctly whether accessed via localhost, a domain name, or behind a reverse proxy.

API Endpoints

1. Get Random Bytes (/random)

Generate cryptographically secure random bytes from camera sensor entropy.

Parameters:

• bytes (integer, default: 32, max: 1048576): Number of random bytes to generate
• hex (boolean, default: false): Return bytes as hexadecimal string instead of binary

Examples:

# Get 32 bytes as hex string
curl -s "http://localhost:8787/random?bytes=32&hex=true"

# Get 64 raw bytes saved to a file
curl -s "http://localhost:8787/random?bytes=64" -o random.bin

# Get 1 KB and pipe to xxd for hex viewing
curl -s "http://localhost:8787/random?bytes=1024" | xxd

# Get 1 MB of random data
curl -s "http://localhost:8787/random?bytes=1048576" -o random-1mb.bin

2. Stream Random Bytes (/stream)

Stream continuous random bytes. Useful for high-throughput applications or feeding entropy to other processes.

Parameters:

• bytes (integer, optional): Total bytes to stream (omit for unlimited)
• hex (boolean, default: false): Stream as hexadecimal strings instead of binary

Examples:

# Stream unlimited random bytes (binary, Ctrl-C to stop)
curl -N "http://localhost:8787/stream"

# Stream exactly 1 MB as hex
curl -N "http://localhost:8787/stream?bytes=1048576&hex=true"

# Stream hex to a file
curl -N "http://localhost:8787/stream?hex=true" > entropy.hex

# Pipe stream to another process
curl -N "http://localhost:8787/stream?bytes=4096" | openssl enc -aes-256-cbc -pass pass:test -in /dev/stdin

# Stream 10 KB of binary entropy, view as hex dump
curl -sN "http://localhost:8787/stream?bytes=10240" | xxd | head -40

3. List Cameras (/cameras)

List available camera devices on the system.

Example:

curl -s "http://localhost:8787/cameras" | jq

Response:

{
  "cameras": [
    {
      "index": 0,
      "human_name": "FaceTime HD Camera",
      "description": "Built-in camera",
      "misc": ""
    }
  ]
}

4. Health Check (/health)

Check server status, pool level, and harvester state.

Example:

curl -s "http://localhost:8787/health" | jq

Response:

{
  "status": "ok",
  "pool_bytes_available": 262144,
  "total_camera_bytes_harvested": 1048576,
  "csprng_seeded_from_camera": true
}

5. Quantum Dice (/dice)

Roll quantum-random dice.

Parameters:

• d (integer, default: 6, range: 2–256): Number of sides
• count (integer, default: 1, max: 100): Number of dice to roll

Examples:

# Roll one d6
curl -s "http://localhost:8787/dice" | jq

# Roll 5d20
curl -s "http://localhost:8787/dice?d=20&count=5" | jq

6. Quantum Password Generator (/password)

Generate a cryptographically random password.

Parameters:

• length (integer, default: 20, max: 128): Password length
• charset (string, default: "alphanumeric"): One of alphanumeric, full, hex, or flag combos (lower, upper, digit, symbol)
• exclude_ambiguous (boolean, default: false): Remove 0 O o I l 1 |

Examples:

# Default 20-char alphanumeric password
curl -s "http://localhost:8787/password" | jq -r .password

# 32-char with full charset, no ambiguous chars
curl -s "http://localhost:8787/password?length=32&charset=full&exclude_ambiguous=true" | jq -r .password

# Hex-only 64-char token
curl -s "http://localhost:8787/password?length=64&charset=hex" | jq -r .password

7. Quantum Coin Flip (/coin)

Flip a quantum coin.

Example:

curl -s "http://localhost:8787/coin" | jq -r .result

8. Quantum 8 Ball (/8ball)

Get a quantum-random Magic 8 Ball answer.

Parameters:

• question (string, optional): The question to ask

Example:

curl -s "http://localhost:8787/8ball?question=Will+it+work" | jq

MCP Integration

The API implements the Model Context Protocol (MCP) specification, allowing AI assistants and other MCP clients to discover and use the TRNG service automatically.

MCP Tools

The following tools are exposed via MCP:

1. get-random: Generate random bytes (cryptographically secure)
2. get-stream: Stream random bytes continuously
3. list-cameras: Discover available cameras
4. health-check: Verify server status

Self-Referencing URLs

The MCP endpoint (/.well-known/mcp.json) automatically detects the request's hostname from:

• HTTP Host header
• X-Forwarded-Proto header (for reverse proxy scenarios)

This ensures URLs in the MCP response always reference the correct origin, whether accessed via:

• localhost:8787
• trng.example.com
• Behind a reverse proxy with forwarded headers

Usage Examples

Python

import requests

# Get 32 random bytes
resp = requests.get("http://localhost:8787/random?bytes=32")
random_bytes = resp.content
print(random_bytes.hex())

# Stream random data
with requests.get("http://localhost:8787/stream?hex=true", stream=True) as r:
    for chunk in r.iter_content(chunk_size=64):
        print(chunk.decode(), end="")

# Tools
print(requests.get("http://localhost:8787/dice?d=20&count=3").json())
print(requests.get("http://localhost:8787/password?length=24&charset=full").json()["password"])
print(requests.get("http://localhost:8787/coin").json()["result"])
print(requests.get("http://localhost:8787/8ball").json()["answer"])

JavaScript/Node.js

// Get random bytes
const resp = await fetch("http://localhost:8787/random?bytes=32");
const buffer = await resp.arrayBuffer();
const bytes = new Uint8Array(buffer);

// Stream random data
const stream = await fetch("http://localhost:8787/stream?hex=true");
const reader = stream.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

// Tools
const dice = await (await fetch("http://localhost:8787/dice?d=6&count=5")).json();
const pw   = await (await fetch("http://localhost:8787/password?length=20")).json();
const coin = await (await fetch("http://localhost:8787/coin")).json();
const ball = await (await fetch("http://localhost:8787/8ball")).json();

curl (comprehensive)

# ── Random ────────────────────────────────────────────
curl -s "http://localhost:8787/random?bytes=32&hex=true"
curl -s "http://localhost:8787/random?bytes=1024" -o random.bin
curl -s "http://localhost:8787/random?bytes=256" | xxd

# ── Stream ────────────────────────────────────────────
curl -N  "http://localhost:8787/stream"
curl -N  "http://localhost:8787/stream?bytes=1024&hex=true"
curl -N  "http://localhost:8787/stream?hex=true" > entropy.hex

# ── Tools ─────────────────────────────────────────────
curl -s "http://localhost:8787/dice?d=20&count=3"         | jq
curl -s "http://localhost:8787/password?length=24"        | jq -r .password
curl -s "http://localhost:8787/coin"                      | jq -r .result
curl -s "http://localhost:8787/8ball?question=Ship+it"    | jq

# ── Health & Discovery ────────────────────────────────
curl -s "http://localhost:8787/health"                    | jq
curl -s "http://localhost:8787/cameras"                   | jq
curl -s "http://localhost:8787/.well-known/mcp.json"      | jq

Limitations

• Maximum 1 MB per request (/random)
• Maximum 4 concurrent requests
• Requires a camera device with covered lens
• Performance depends on camera frame rate

Security Notes

• No authentication required (intended for local/trusted networks)
• Random data is only from camera input; otherwise requests fail
• Consider rate limiting in production deployments

See Also

• TECHNICAL.md - Technical implementation details
• README.md - Project overview and setup instructions