DaemonX Bridge Service - Developer API Documentation

Version: 1.0.2
Service Name: DaemonX Local POS Hardware Bridge
Base URL: http://127.0.0.1:9123 (or http://localhost:9123)
Transport: HTTP / 1.1 with JSON payloads
Target Platform: Windows 10 / Windows 11 (x64)

1. Architectural Overview

DaemonX is an ultra-low latency, zero-configuration local desktop daemon that connects modern web-based Point of Sale (POS) applications directly to physical retail hardware (ESC/POS thermal printers, A4 invoice spoolers, and cash drawers) without browser print prompts, Java runtimes, or OS dialogs.

┌─────────────────────────────────┐
│     Cloud Web POS Application   │  (e.g., https://pos.yourdomain.com)
│   (Next.js / React / Angular)   │
└────────────────┬────────────────┘
                 │
                 │ 1. Local HTTP Dispatch (Sub-15ms)
                 │    Headers: X-Bridge-Counter-Id, X-Bridge-Profile-Secret
                 ▼
┌────────────────────────────────────────────────────────┐
│     DaemonX Local Bridge Daemon (127.0.0.1:9123)       │
│                                                        │
│  ├── Loopback WAF & Origin Filter                      │
│  ├── Secure Encrypted Profile Storage                  │
│  ├── Offline Resilience Engine                         │
│  └── Raw ESC/POS & Headless Edge PDF Spooler Engine    │
└────────────────┬───────────────────┬───────────────────┘
                 │                   │
                 │ 2. Spooler Bytes  │ 3. Background Sync & Leases (5m)
                 ▼                   ▼
┌────────────────────────┐  ┌─────────────────────────────────┐
│ Windows Hardware Layer │  │     Nyxzie Cloud Core API       │
│  - USB/LAN Thermal     │  │  - Billing Quota & Heartbeat    │
│  - RJ11 Cash Drawers   │  │  - 24h Cryptographic JWT Lease  │
│  - Laser / Inkjet A4   │  └─────────────────────────────────┘
└────────────────────────┘

2. Security Model & Global Headers

All communication between the browser and DaemonX takes place over the host's loopback interface.

2.1. Network Isolation (Loopback Only)

DaemonX enforces strict loopback binding. Incoming connections from any remote IP address (non-127.0.0.1, ::1) are immediately rejected with 403 Forbidden ("Loopback only"). External network access to the port is blocked by design.

2.2. CORS Policy & Private Network Access

DaemonX fully supports W3C Private Network Access (PNA) preflight requests:

• Responds with Access-Control-Allow-Private-Network: true
• Validates the Origin header against the counter's allowed_origins whitelist configured in the secure profile.
• Unlisted browser origins receive 403 Forbidden ("CORS origin not allowed").

2.3. Counter Scoping & Authentication Headers

Protected operational endpoints require two authentication headers representing the paired counter:

*Note: Public diagnostics (/api/health) has relaxed loopback discovery scope as noted in its documentation.

X-Bridge-Profile-Secret is a developer/operator credential. It may be revealed in a trusted business/developer dashboard or copied into a local .env, but it must not be bundled into public client code, NEXT_PUBLIC_* environment variables, or generic long-lived browser storage.

3. Standard Response & Error Envelope

All responses return standard HTTP status codes.

Success Envelope

Successful requests return JSON with "success": true or the relevant resource representation:

{
  "success": true,
  "counter_id": "d402ddec-ecf7-4b39-b57a-86ce6008df05"
}

Error Envelope

When an error occurs, DaemonX returns a structured JSON envelope under the detail property:

{
  "detail": {
    "error": "DAEMONX_OFFLINE_ALLOWANCE_EXHAUSTED",
    "message": "Emergency offline allowance exhausted. Reconnect this counter to continue.",
    "counter_id": "d402ddec-ecf7-4b39-b57a-86ce6008df05",
    "offline_remaining": 0,
    "reconnect_required": true,
    "gate_reason": "OFFLINE_ALLOWANCE_EXHAUSTED",
    "operation": "print_thermal"
  }
}

Standard Error Code Registry

4. Endpoint Sitemap & Documentation Index

Local Bridge Endpoints (http://127.0.0.1:9123)

5. Offline Tolerance & High-Availability Resilience

DaemonX is engineered for uninterrupted checkout uptime during physical store network outages:

1. 24-Hour Offline Lease: Active workstations operate under a rolling 24-hour cryptographic lease, ensuring registers continue printing even if the store loses WAN internet connectivity.
2. Emergency Print Allowance: If connectivity is temporarily interrupted, counters seamlessly utilize a dynamic local allowance (30 to 200 emergency prints) to keep physical checkout lines moving.
3. Automatic Cloud Recovery: When network access is restored, the daemon automatically resyncs in the background, renews the lease, and resets allowances without requiring cashiers to restart the application or re-authenticate.