UHRP Server (Basic)

A simple, file-system based UHRP (Universal Host Reference Protocol) host server. Stores files locally on disk and provides HTTP endpoints for UHRP data retrieval and storage.

What it does

A lightweight Node.js server with Express that implements UHRP storage and metadata endpoints. Files are served publicly from the local object directory. The raw PUT /put commit is HMAC-authorized; the upload, list, find, and renew workflows require BRC-103 identity, and payment policy runs after authentication.

Clients PUT files with authentication, retrieve files via public GET, and query metadata via POST /lookup.

When to deploy this

• Local development and testing of UHRP clients
• Proof-of-concept deployments with small file volumes
• Single-server setups without cloud infrastructure
• Educational or internal network use

Dependencies

HTTP endpoints

WebSocket endpoints

None.

Configuration (env vars)

PUT /put validates authorization, expiry, declared size, and any Content-Length before consuming the body. It streams into a private same-filesystem temporary file, hashes incrementally, and uses exclusive atomic linking so partial data and overwrites are never published.

See Public Service Edge Security for the complete endpoint threat model.

Run locally

# Install dependencies
npm install

# Development with nodemon hot-reload
npm run dev

# Build TypeScript
npm run build

# Run production build
npm start

Files stored in ./public or configured data directory.

Deploy to production

# Build and start
npm run build && npm start

# Or build the repository's digest-pinned, multi-stage Node 24 image
docker build -t uhrp-lite:local .
docker run -d \
  -e SERVER_PRIVATE_KEY=<256-bit-hex> \
  -e HOSTING_DOMAIN=https://uhrp.example.com \
  -e HTTP_PORT=8080 \
  -v uhrp_data:/app/public \
  -p 8080:8080 \
  uhrp-lite:local

The container runs as the unprivileged node user and probes /ready before it is considered healthy. The service remains filesystem-based with no external database; mount durable storage at /app/public.

Migrations

None; stateless server with files stored directly on disk with JSON metadata.

Health checks

• GET /health and GET /healthz report process liveness.
• GET /ready returns 200 only after wallet-backed authentication and payment middleware initialization completes.
• Monitor disk space and the mounted object directory separately.

Spec conformance

• UHRP – Implements basic UHRP host protocol for file storage and retrieval
• BRC-103 – Mutual authentication on uploader metadata and renewal endpoints
• BRC-100 – Optional payment verification (via payment middleware if enabled)

Integration with ts-stack

• UHRP clients upload/retrieve files using SERVER_PRIVATE_KEY and HOSTING_DOMAIN
• Wallet Storage derives keys from SERVER_PRIVATE_KEY, validates optional payments
• Overlay nodes can advertise UHRP hosting capability via overlay
• No npm package published; standalone reference implementation

Common pitfalls

• No cleanup mechanism: files persist until manually deleted; monitor disk usage in production
• Raw object commit is HMAC-authorized; authenticated upload/renew workflows apply payment middleware
• Single instance only: no built-in replication or load balancing
• MIME types auto-detected from file extension; unusual extensions may lack proper type
• Direct disk access: ensure filesystem permissions allow Node.js process read/write access
• No backup strategy: files lost if filesystem corrupted; implement external backup policy

Source

• GitHub
• npm package