API Reference

The current contract for the DNS-Manager control plane (Cloudflare Worker dns-manager-api + D1 + KV HEALTH_KV + R2). Two surfaces, one database:

open = unauthenticated (WAF-gated), HMAC = signed device request, JWT = operator bearer token, ingest = scoped capture token (bookmarklet / webhook — neither JWT nor HMAC). Endpoints marked (PR #NNN) are in an open pull request, not yet on main.

Retired: the legacy PHP panel (dns_list.php, dns_active.php) is gone — the Worker + D1 below is canonical.

Architecture

One Cloudflare Worker (dns-manager-api) backs both surfaces; a Cloudflare Pages site (public/) serves the admin GUI. Everything runs on the free tier (~10 ms CPU/request, no native bcrypt, WAF Block/Skip/Challenge only).

Components

Security model

• Public app surface — unauthenticated by design (pre-shipped apps can't log in); protected by WAF allow-listing + a User-Agent rule for Smarters.
• Device provisioning + messages — HMAC-SHA256 over a locked canonical string (method·path·query·sha256(body)·ts·nonce·deviceId·keyId); ±300 s timestamp window; single-use nonce (replay cache on the Cache API, per-PoP, fail-open); per-IP + per-device rate limits.
• Admin API — Cloudflare Access + a signed HS256 JWT (1 h TTL, token_version bumped on password change); RBAC admin/operator.
• Secrets — passwords are PBKDF2-HMAC-SHA256 (WebCrypto, not bcrypt); Xtream creds are AES-GCM at rest (per-record IV, AAD bound to device_id:key_id); JWT_SECRET/PROVISION_KEK/DNX_HMAC_KEYS are Cloudflare secrets.

Request flow — a box coming online

1 · Public app surface (IPTV-Smarters rebrand + Helix)

Pre-shipped apps re-pointed to https://dnsm.cbkr.xyz/api/. Do not rename these — the APKs append the path verbatim (shapes recovered in CONTRACTS.md). All open; no-store so GUI changes take effect on the next poll.

The Smarters resolver. The app posts a form body (m=gu, u=playlist, d, k, sc, pw, r, av, dt, do); the su field is load-bearing. Per-device routing is via the ?d= / ?device= query param (the worker routes by query, not the body field).

Helix bootstrap (home.php?action=appinfo is Helix's real config URL; action=update|getvpn are re-pointed apkloc/vpn resources that return {}). Each portal becomes domain1…domainN with all 12 Helix keys (one missing key makes Helix discard the whole response). ?d=/?device=<deviceId> serves that device's playlists.

Splash video — returns video/mp4 bytes (or a 302 to INTRO_VIDEO_URL); never JSON, never 404 (the app loads it in a VideoView).

Public R2 passthrough for message banner/poster art (minted by the admin asset upload). Key is pinned to the minted shape (no traversal).

2 · Device provisioning (3DNX player — operator-assigned)

Every request is HMAC-signed. Headers: X-DNX-Sign (HMAC-SHA256 of the canonical string), X-DNX-Ts (unix s, ±300 s), X-DNX-Nonce (single-use), X-DNX-KeyId, X-DNX-DeviceId. The signed deviceId is authoritative. Per-IP + per-device rate limits.

3 · Device messages (operator → box push)

HMAC-signed like provisioning. The box polls for messages (banner/poster/notification/ad) targeted at it (or broadcast) and acknowledges them. ad renders in the dashboard sidebar slot (1:9 art); it requires image_url, forces requires_ack off, and uses priority to pick the winning ad.

A box reporting configHash on poll drives the config-drift badge in the panel.

4 · 3DNX Connect (phone self-service onboarding)

A keyboard-less box shows a PIN+QR; the user types creds on a phone at /connect; the box pulls them. The claimSecret (box-only) is required to claim — a leaked on-screen code alone can't retrieve creds. Codes live in D1 (connect_codes; single-use, in-band expiry). All open (no creds yet) but per-IP rate-limited via the Cache+D1 limiter.

4b · Device backup / restore (encrypted, device-scoped)

HMAC-signed like provisioning. The app builds a password-encrypted JSON envelope (AES-256-GCM) locally and uploads the opaque base64 ciphertext for cross-device restore — the Worker never decrypts or inspects it. One latest backup per device (re-upload overwrites). Body deviceId must equal the signed device; payload capped at ~900 KB. Stored in D1 device_backups.

5 · Admin API (operator panel)

All JWT (Bearer) + Cloudflare Access. Token from /api/auth/login (HS256, 1 h TTL). RBAC: provisioning/messages require admin or operator.

Auth

DNS entries / portals (all admin-authed)

Devices (provisioning)

Multi-playlist (per device)

Rollouts (canary / staged rollout · #160)

Ring a config change (helix render-flags or an m3u source) to a pilot tag cohort, watch adoption via the existing config-drift (configHash) signal, then promote to the full cohort or roll back to a per-device snapshot. The ring only controls which devices get a change and when — never the device-facing response shape.

State transitions are compare-and-swap guarded (a double-submit returns 409). Cohorts are capped at 500 and applied in chunked D1 batches. Encrypted creds travel verbatim in the snapshot, so rollback never needs the KEK.

Health-aware auto-failover (#161)

Resellers (XUI.one auto-provision)

Register a reseller panel, then auto-provision a device: the Worker calls the panel's admin API to create a line and assigns the resulting Xtream creds to the device. The panel API key is AES-GCM encrypted at rest (never returned/logged). XUI.one plain-api_key mode.

No-API ingest (capture lines from panels with no API — Inbox)

For reseller panels with no API. A scoped ingest token lets an operator bookmarklet (or a reseller webhook) post a captured line into a staging Inbox; the Worker auto-detects m3u/Xtream, encrypts creds, and dedups. The operator then assigns each inbox item to a device. Generate the token + bookmarklet/webhook URL on the Inbox page.

Messages

Providers (wholesale lines)

Ledger (per-device cost)

Fleet ops · triage · audit

Admin operations (operator workflows)

The panel pages map to these flows. Sign in via Cloudflare Access at m7k2.cbkr.xyz (first login forces a password change; the panel calls /api/auth/login for the JWT).

Provision a new device

• Operator-assigned: the box shows a pairing code → Devices → Assign a device → enter the code (or pick a Pending row) → set display name, source (Xtream server+creds, or M3U URL — pick a saved portal preset to avoid retyping), optionally a content filter, and Helix display flags → Assign. The box pulls it on its next poll.
• Self-service (Connect): the box shows a PIN+QR; the customer opens /connect on a phone and types the playlist details; the box pulls them. The operator watches Live Connect codes.

Restore a device after a reinstall / build switch

Why it's needed: a box's device_id is generated and stored by the app, so a reinstall — or switching between a debug and a signed build — makes it reappear as a brand-new device with no config. Restore copies the old device's playlists onto the new one so you don't re-enter anything.

• Steps (operator): in Devices, find the new (empty) box → click Restore → enter the old device id (the one it had before the reinstall) → confirm. The old device's active playlists are appended to the new one; it pulls them on its next poll.
• Under the hood: POST /api/admin/devices/:id/clone-from {source_device_id} reads the source's active playlists and decrypts each Xtream credential under the source's key, re-encrypting it under the new device's key (creds never leave the Worker in the clear), then appends them — non-destructive, existing config preserved. The new device is marked assigned.
• Notes: admin/operator only; the source must still exist and have active playlists; m3u sources copy verbatim. It is a config copy, not an identity move. (Roadmapped next: a self-service device-side restore code, and a per-device auth secret — see issue #174.)

Capture lines from a panel with no API (Inbox)

On the Inbox page, generate an ingest token (shown once) and copy the bookmarklet into your browser. On a reseller panel's "line created" page, select the m3u URL / Xtream creds and click the bookmarklet — the line lands in the Inbox (creds encrypted, m3u/Xtream auto-detected, deduped). Or generate a Webhook URL and paste it into a panel that can POST callbacks. Then Assign each inbox item to a device (creds re-encrypted for it), or Discard it.

Curate content (the filter)

In the assign form, choose Default — English regions and Preview categories: the panel fetches the provider's live categories and classifies each keep/hide (US/CA/Caribbean/UK/AU/NZ + 24/7-English + Canada-French kept). Flip any row; tick Lock to make hides PIN-protected. The result is pushed as the device's CurationProfile — no app change.

Message the fleet

Messages → compose a banner/poster/notification/ad (Sidebar), broadcast or target one device, optionally require acknowledgement, set an expiry, and upload art to R2. The live TV preview shows how it renders. Sent messages show ack counts; deactivate to stop delivery (ack history kept).

Manage portals & health

Dashboard → CRUD the DNS entries (portals), set active/priority. Check Health probes each portal from the edge (best-effort badge; a Cron re-probes active portals every 30 min). Portals double as the assign-form presets.

Roll out a change safely (canary)

For a risky config change (a new provider URL, a render-flag flip) across a segment: tag a small pilot cohort, create a rollout targeting the segment tag with that pilot tag, apply-pilot, then watch the rollout's adoption metrics (synced / drifted / awaiting) as the pilot boxes re-poll. If it's healthy, promote to the rest; if not, roll back — every applied device is restored from its pre-change snapshot. Lowers the blast radius of a bad edit from the whole segment to the pilot. Drive it from the Rollouts page.

Self-healing failover

A box reports per-portal outcome after it tries each source. When it reports its primary source failed and has a healthy lower-priority source, a */30 Cron (or POST /api/admin/failover/run) automatically promotes the healthy source — recorded as an auto-failover rollout you can see and roll back — and auto-reverts when the original recovers. The trigger is the box's own report, not the edge health probe (which has datacenter-IP false-negatives and stays an operator badge signal only). An anti-flap cooldown stops a flapping portal from bouncing a device.

Monitor & triage

• Online / drift: the Devices list shows an online dot (from last_seen) and a config-drift badge (✓ synced / ⚠ stale) once a box reports its configHash.
• Per-device timeline: Events shows every provisioning event with IP/country/ISP/edge-PoP.
• Audit & ops: the provisioning audit log, the migration-status health snapshot, the audit dead-letter queue, and the public-surface API access Logs page.

Roles

admin and operator both reach the provisioning/messages admin API; the distinction is reserved for future least-privilege splits. All admin mutations write a provision_audit row (actor + IP/geo).

Data model (D1 tables)

CurationProfile

Pushed in a device's provision/playlist config (stored as profile_json); the box applies it client-side. The panel's "Default — English regions" preset (PR #120) computes hide_categories from the provider's real category list so US/CA/Caribbean/UK/AU/NZ + 24/7-English + Canada-French survive.