kryten-webqueue 0.41.0__tar.gz → 0.42.0__tar.gz

{kryten_webqueue-0.41.0 → kryten_webqueue-0.42.0}/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 ## [Unreleased]
 
+## [0.42.0] - 2026-08-24
+
+### Added
+
+- **Public API for third-party client apps (Smart TV / tablet device linking).**
+  A new key-authenticated API under `/api/public/v1` exposes the live channel
+  state so an external application can render the equivalent of the `/queue`
+  page. See [docs/PUBLIC_API.md](docs/PUBLIC_API.md) for the full contract and a
+  developer's guide.
+  - **Device linking flow.** A logged-in user visits **`/link`** ("Link a
+    Device", also reachable from the account/Z-coin dashboard), names the
+    device, and receives a **5-character, single-use, uppercase-alphanumeric
+    one-time pad** (10-minute TTL, unambiguous alphabet). The device redeems it
+    at **`POST /api/public/v1/link`** and receives a long-lived API key
+    (`Authorization: Bearer <key>`). The pad is destroyed on redemption (one key
+    per pad); a user may link multiple devices, each with its own named key.
+  - **Data endpoints (Bearer key required):** `GET /api/public/v1/current`
+    (now playing — title, synopsis, total/elapsed/remaining time),
+    `GET /api/public/v1/queue` (ordered queue with predicted start times), and
+    `GET /api/public/v1/events` (upcoming enabled scheduled playlists).
+  - **Device management.** `GET/POST/DELETE /user/devices*` (session-cookie) back
+    a dashboard list where users name, view, and **revoke** linked devices. Keys
+    are stored only as a SHA-256 hash plus a non-secret display prefix; the
+    plaintext key is returned exactly once at redemption and never again.
+  - **Revoke-on-ban.** Issuing a `ban` through the webqueue admin moderation UI
+    now also revokes that user's device keys. A scheduled
+    **`device_key_ban_reconcile`** job additionally reconciles key holders
+    against kryten-moderator's authoritative ban list (via api-gate,
+    case-insensitive) to cover bans issued directly in CyTube or by the
+    moderator service. It is seeded to run every 15 minutes by default
+    (adjustable/disable-able via the admin job scheduler; deactivate rather than
+    delete, as a deleted schedule is re-seeded on startup).
+  - **Abuse protection.** Per-user throttling on pad generation and per-IP
+    throttling on the redemption endpoint; strict code-format validation.
+  - New DB migration **v27** (`device_link_codes`, `device_api_keys`).
+
 ## [0.41.0] - 2026-08-24
 
 ### Fixed

{kryten_webqueue-0.41.0 → kryten_webqueue-0.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kryten-webqueue
-Version: 0.41.0
+Version: 0.42.0
 Summary: Netflix/Tubi-style catalog browser and pay-to-play queue management for CyTube
 Author: grobertson
 License-Expression: MIT

kryten_webqueue-0.42.0/docs/PUBLIC_API.md

@@ -0,0 +1,289 @@
+# Public API — Developer's Guide
+
+The kryten-webqueue **Public API** lets approved third-party applications (Smart
+TV and tablet clients) read the live channel state — what's playing now, the
+upcoming pay-to-play queue, and scheduled events — using a long-lived API key.
+
+- **Base URL:** `https://queue.dropsugar.co`
+- **API root:** `/api/public/v1`
+- **Auth:** `Authorization: Bearer <api_key>` on every data request.
+- **Format:** JSON, UTF-8. All timestamps are ISO-8601 (UTC, `+00:00`).
+
+Every externally callable endpoint lives under `/api/public/v1`. The only
+endpoint that does **not** require the `Authorization` header is the bootstrap
+exchange (`POST /api/public/v1/link`), which trades a one-time code for a key.
+
+---
+
+## 1. Linking flow (how a device gets a key)
+
+Keys are minted through a short, user-driven pairing flow so a device never
+handles the user's credentials.
+
+```
+┌────────────┐   1. names device, gets code    ┌──────────────────┐
+│  Browser   │ ───────────────────────────────▶│  queue.dropsugar │
+│ (logged in)│   GET /link  →  "AB2CD"          │      .co         │
+└────────────┘                                  └──────────────────┘
+      │  2. user reads the 5-char code aloud / types it
+      ▼
+┌────────────┐   3. POST /api/public/v1/link    ┌──────────────────┐
+│  TV / app  │ ───────────────────────────────▶│  queue.dropsugar │
+│            │      { "code": "AB2CD" }         │      .co         │
+│            │ ◀───────────────────────────────│                  │
+└────────────┘   4. { "api_key": "kqd_…" }      └──────────────────┘
+      │  5. store the key; send it as a Bearer token thereafter
+      ▼
+   GET /api/public/v1/current, /queue, /events …
+```
+
+**Rules the client must respect**
+
+1. The user first names the device in the browser (`/link`) and receives a
+   **5-character, uppercase alphanumeric** code.
+2. The code is a **one-time pad**: valid for **10 minutes** and usable **once**.
+   On a successful exchange it is destroyed and cannot be reused.
+3. Codes use an unambiguous alphabet (no `O`, `0`, `I`, `1`). Uppercase the
+   user's input before sending; the server also normalizes.
+4. The API key is returned **exactly once**, in the exchange response. Store it
+   securely on the device — it is never retrievable again. If lost, the user
+   revokes the device and links again.
+5. A user may link multiple devices; each has its own key and name.
+6. A key is valid indefinitely until the user revokes it (or the user is
+   banned, which revokes all of their keys).
+
+---
+
+## 2. Endpoints
+
+### 2.1 `POST /api/public/v1/link` — exchange a code for a key
+
+Bootstrap only. **No** `Authorization` header.
+
+**Request body**
+
+```json
+{
+  "code": "AB2CD"
+}
+```
+
+| Field | Type   | Notes                                            |
+|-------|--------|--------------------------------------------------|
+| code  | string | The 5-char pad from `/link`. Case-insensitive.   |
+
+**200 response**
+
+```json
+{
+  "api_key": "kqd_9f3a1c7b2e5d4a6f8091b2c3d4e5f60718293a4b5c6d7e8f",
+  "token_type": "Bearer",
+  "device_id": 12,
+  "device_name": "Living Room TV",
+  "username": "alice"
+}
+```
+
+| Field       | Type    | Notes                                          |
+|-------------|---------|------------------------------------------------|
+| api_key     | string  | Full secret. Send as `Authorization: Bearer …`. Shown once. |
+| token_type  | string  | Always `"Bearer"`.                             |
+| device_id   | integer | Server-side id for this linked device.         |
+| device_name | string  | The name the user chose.                       |
+| username    | string  | The account the key acts on behalf of.         |
+
+**Errors**
+
+| Status | Meaning                                             |
+|--------|-----------------------------------------------------|
+| 400    | Code is malformed (wrong length / illegal chars).   |
+| 404    | Code is unknown, already used, or expired.          |
+| 429    | Too many attempts from this client; back off.       |
+
+---
+
+### 2.2 `GET /api/public/v1/current` — now playing
+
+Requires `Authorization: Bearer <key>`.
+
+**200 response (something playing)**
+
+```json
+{
+  "playing": true,
+  "item": {
+    "title": "The Blob",
+    "friendly_token": "aB3xY",
+    "synopsis": "A gelatinous alien terrorises a small town.",
+    "duration_sec": 5400,
+    "current_time_sec": 1234.5,
+    "remaining_sec": 4165.5,
+    "cover_art_url": "https://queue.dropsugar.co/images/aB3xY/500.webp",
+    "categories": ["Horror", "Sci-Fi"],
+    "tags": ["1958", "cult"]
+  },
+  "updated_at": "2026-08-24T21:40:00+00:00"
+}
+```
+
+**200 response (nothing playing)**
+
+```json
+{ "playing": false, "item": null, "updated_at": "2026-08-24T21:40:00+00:00" }
+```
+
+| Field                  | Type            | Notes                                    |
+|------------------------|-----------------|------------------------------------------|
+| playing                | boolean         | `false` when the channel is idle.        |
+| item.title             | string          | Display title.                           |
+| item.friendly_token    | string \| null  | Catalog id (stable per item).            |
+| item.synopsis          | string \| null  | Plot / description.                      |
+| item.duration_sec      | integer \| null | Total runtime in seconds.                |
+| item.current_time_sec  | number          | Elapsed playback position, seconds.      |
+| item.remaining_sec     | number \| null  | Time left, seconds.                      |
+| item.cover_art_url     | string \| null  | Absolute poster URL.                     |
+| item.categories        | string[]        | Category names.                          |
+| item.tags              | string[]        | Tag names.                               |
+| updated_at             | string          | When the snapshot was produced.          |
+
+---
+
+### 2.3 `GET /api/public/v1/queue` — the upcoming queue
+
+Requires `Authorization: Bearer <key>`.
+
+**200 response**
+
+```json
+{
+  "items": [
+    {
+      "position": 0,
+      "uid": 88213,
+      "title": "The Blob",
+      "friendly_token": "aB3xY",
+      "duration_sec": 5400,
+      "estimated_start_at": "2026-08-24T21:40:00+00:00",
+      "estimated_start_in_sec": 0,
+      "cover_art_url": "https://queue.dropsugar.co/images/aB3xY/500.webp",
+      "queued_by": "alice",
+      "tier": "queue",
+      "is_now_playing": true
+    },
+    {
+      "position": 1,
+      "uid": 88214,
+      "title": "Plan 9 from Outer Space",
+      "friendly_token": "cD4wZ",
+      "duration_sec": 4740,
+      "estimated_start_at": "2026-08-24T23:10:00+00:00",
+      "estimated_start_in_sec": 4165,
+      "cover_art_url": "https://queue.dropsugar.co/images/cD4wZ/500.webp",
+      "queued_by": "bob",
+      "tier": "playnext",
+      "is_now_playing": false
+    }
+  ],
+  "count": 2,
+  "updated_at": "2026-08-24T21:40:00+00:00"
+}
+```
+
+| Field                        | Type            | Notes                                        |
+|------------------------------|-----------------|----------------------------------------------|
+| items[].position             | integer         | 0-based order in the queue.                  |
+| items[].uid                  | integer \| null | Playlist uid (for correlating updates).      |
+| items[].title                | string          | Display title.                               |
+| items[].friendly_token       | string \| null  | Catalog id.                                  |
+| items[].duration_sec         | integer \| null | Runtime in seconds.                          |
+| items[].estimated_start_at   | string \| null  | Predicted start (ISO-8601).                  |
+| items[].estimated_start_in_sec | integer \| null | Predicted seconds until start.             |
+| items[].cover_art_url        | string \| null  | Absolute poster URL.                         |
+| items[].queued_by            | string \| null  | Username who queued it (may be absent).      |
+| items[].tier                 | string \| null  | `queue` or `playnext`.                       |
+| items[].is_now_playing       | boolean         | `true` for the item currently on screen.     |
+| count                        | integer         | `items.length`.                              |
+| updated_at                   | string          | Snapshot time.                               |
+
+> The now-playing item is included here **and** in `/current`. Filter on
+> `is_now_playing` if you want strictly upcoming items.
+
+---
+
+### 2.4 `GET /api/public/v1/events` — scheduled events
+
+Requires `Authorization: Bearer <key>`. Returns upcoming **enabled** scheduled
+playlists (what operators call "events"), soonest first.
+
+**200 response**
+
+```json
+{
+  "events": [
+    { "label": "Friday Night Grindhouse", "fire_at": "2026-08-28T02:00:00+00:00", "is_recurring": true },
+    { "label": "Halloween Marathon",      "fire_at": "2026-10-31T20:00:00+00:00", "is_recurring": false }
+  ],
+  "count": 2,
+  "updated_at": "2026-08-24T21:40:00+00:00"
+}
+```
+
+| Field                 | Type    | Notes                                         |
+|-----------------------|---------|-----------------------------------------------|
+| events[].label        | string  | Event name.                                   |
+| events[].fire_at      | string  | Scheduled start (ISO-8601, future only).      |
+| events[].is_recurring | boolean | Whether the event repeats.                    |
+| count                 | integer | `events.length`.                              |
+| updated_at            | string  | Snapshot time.                                |
+
+---
+
+## 3. Authentication details
+
+Send the key on every data request:
+
+```
+Authorization: Bearer kqd_9f3a1c7b2e5d4a6f8091b2c3d4e5f60718293a4b5c6d7e8f
+```
+
+- Missing header → **401** `{"detail": "Missing API key"}`.
+- Unknown/revoked key → **401** `{"detail": "Invalid API key"}`.
+- Both 401s include `WWW-Authenticate: Bearer`.
+
+Keys are stored server-side only as an irreversible SHA-256 hash; the plaintext
+lives solely on the device.
+
+---
+
+## 4. Errors (all endpoints)
+
+Errors use FastAPI's standard shape:
+
+```json
+{ "detail": "Invalid or expired code." }
+```
+
+| Status | When                                                        |
+|--------|-------------------------------------------------------------|
+| 400    | Malformed request (bad code format, bad JSON).              |
+| 401    | Missing or invalid API key.                                 |
+| 404    | Unknown/expired link code.                                  |
+| 429    | Rate limited (link generation or code exchange).            |
+
+---
+
+## 5. Client implementation notes
+
+- **Polling:** these endpoints return point-in-time snapshots. Poll `/current`
+  and `/queue` every ~10–15s; `/events` changes rarely (every few minutes is
+  plenty).
+- **Countdowns:** compute live countdowns on-device from `remaining_sec` /
+  `estimated_start_in_sec` rather than re-polling every second.
+- **Cover art:** `cover_art_url` is absolute and ready to load. It may be
+  `null`; show a placeholder.
+- **Key loss / revocation:** if requests start returning 401, the key was
+  revoked (by the user, or automatically when the account is banned — bans are
+  reconciled against the moderator service on a schedule). Prompt the user to
+  re-link.
+- **Time zones:** all times are UTC with an explicit offset; convert for
+  display.

{kryten_webqueue-0.41.0 → kryten_webqueue-0.42.0}/kryten_webqueue/app.py

@@ -38,6 +38,8 @@ from .routes.admin_promos import router as admin_promos_router
 from .routes.admin_moderation import router as admin_moderation_router
 from .routes.feedback import router as feedback_router
 from .routes.admin_feedback import router as admin_feedback_router
+from .routes.devices import router as devices_router
+from .routes.public_api import router as public_api_router
 from .routes.pages import router as pages_router
 from .ws.handler import router as ws_router
 
@@ -100,6 +102,7 @@ async def lifespan(app: FastAPI):
     from .jobs.tasks import (
         catalog_enrich_job,
         catalog_blackout_job,
+        device_key_ban_reconcile_job,
         fetch_job,
         fetch_queue_add_job,
         fetch_queue_drain_job,
@@ -109,6 +112,7 @@ async def lifespan(app: FastAPI):
         tmdb_coverage_report_job,
         CATALOG_ENRICH_SCHEMA,
         CATALOG_BLACKOUT_SCHEMA,
+        DEVICE_KEY_BAN_RECONCILE_SCHEMA,
         FETCH_SCHEMA,
         FETCH_QUEUE_ADD_SCHEMA,
         FETCH_QUEUE_DRAIN_SCHEMA,
@@ -151,6 +155,12 @@ async def lifespan(app: FastAPI):
         label="Catalog Blackout (hide upcoming-weekend items)",
         schema=CATALOG_BLACKOUT_SCHEMA,
     )
+    job_manager.register(
+        "device_key_ban_reconcile",
+        device_key_ban_reconcile_job,
+        label="Device Key Ban Reconcile (revoke banned users' API keys)",
+        schema=DEVICE_KEY_BAN_RECONCILE_SCHEMA,
+    )
     job_manager.register(
         "motd_posters",
         motd_posters_job,
@@ -181,6 +191,17 @@ async def lifespan(app: FastAPI):
 
     # Cron-based job scheduler (persists schedules to job_schedules table)
     job_scheduler = JobScheduler(db, job_manager)
+    # Seed a default schedule for the security-sensitive ban-reconcile job so it
+    # runs periodically out-of-the-box. Only seeded when absent, so an admin's
+    # cron/active changes are preserved (disable it by deactivating, not
+    # deleting — a deleted row is re-seeded on next startup).
+    if await db.get_job_schedule("device_key_ban_reconcile") is None:
+        await db.upsert_job_schedule(
+            "device_key_ban_reconcile",
+            "*/15 * * * *",
+            label="Device Key Ban Reconcile (revoke banned users' API keys)",
+            created_by="system",
+        )
     await job_scheduler.start()
     app.state.job_scheduler = job_scheduler
 
@@ -233,6 +254,13 @@ async def lifespan(app: FastAPI):
     # feedback/suggestion endpoints (per-user, namespaced keys).
     app.state.rate_limiter = RateLimiter()
     app.state.feedback_rate_limiter = RateLimiter(max_requests=12, window_seconds=300)
+    # Device linking: throttle pad generation (per user) and redemption (per IP).
+    app.state.device_link_rate_limiter = RateLimiter(
+        max_requests=10, window_seconds=600
+    )
+    app.state.device_exchange_rate_limiter = RateLimiter(
+        max_requests=10, window_seconds=600
+    )
     # Hard per-user submission quota for feedback and suggestions: 2/day, 6/week
     # (namespaced keys, checked in addition to the short-burst limiter above).
     app.state.feedback_quota_limiter = QuotaLimiter(
@@ -376,6 +404,8 @@ def create_app(config: Config) -> FastAPI:
     app.include_router(admin_moderation_router)
     app.include_router(feedback_router)
     app.include_router(admin_feedback_router)
+    app.include_router(devices_router)
+    app.include_router(public_api_router)
     app.include_router(ws_router)
 
     # Health check

kryten_webqueue-0.42.0/kryten_webqueue/auth/device_keys.py

@@ -0,0 +1,99 @@
+"""Device-linking primitives and the public-API auth dependency.
+
+The smart-TV / tablet apps authenticate with a long-lived API key rather than a
+session cookie. Keys are minted by exchanging a short-lived one-time pad (link
+code) at ``POST /api/public/v1/link`` and are stored only as an irreversible
+SHA-256 hash. This module owns the code/key formats, hashing, and the FastAPI
+dependency that resolves ``Authorization: Bearer <key>`` to a user.
+"""
+
+import hashlib
+import secrets
+
+from fastapi import Request, HTTPException
+
+# Unambiguous uppercase alphanumeric alphabet (no 0/O/1/I) — friendly for
+# on-screen TV entry while remaining strictly alphanumeric.
+LINK_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+LINK_CODE_LENGTH = 5
+LINK_CODE_TTL_MINUTES = 10
+
+API_KEY_PREFIX = "kqd_"  # kryten queue device
+# Display prefix length: scheme prefix + 8 leading hex chars (non-secret).
+_KEY_DISPLAY_LEN = len(API_KEY_PREFIX) + 8
+
+
+def generate_link_code() -> str:
+    """Return a fresh 5-char uppercase one-time pad."""
+    return "".join(secrets.choice(LINK_CODE_ALPHABET) for _ in range(LINK_CODE_LENGTH))
+
+
+def normalize_link_code(raw: str) -> str:
+    """Normalize user/device-supplied input: strip and uppercase."""
+    return (raw or "").strip().upper()
+
+
+def is_valid_link_code_format(code: str) -> bool:
+    """True when ``code`` is the right length and uses only the code alphabet."""
+    return len(code) == LINK_CODE_LENGTH and all(
+        ch in LINK_CODE_ALPHABET for ch in code
+    )
+
+
+def generate_api_key() -> str:
+    """Return a fresh opaque API key: ``kqd_`` + 48 hex chars."""
+    return f"{API_KEY_PREFIX}{secrets.token_hex(24)}"
+
+
+def api_key_display_prefix(full_key: str) -> str:
+    """Non-secret prefix stored for display (e.g. ``kqd_a1b2c3d4``)."""
+    return full_key[:_KEY_DISPLAY_LEN]
+
+
+def hash_api_key(full_key: str) -> str:
+    """Irreversible SHA-256 hex digest of a full API key (what we persist)."""
+    return hashlib.sha256(full_key.encode("utf-8")).hexdigest()
+
+
+def _extract_bearer_key(request: Request) -> str | None:
+    """Pull the key from ``Authorization: Bearer <key>`` (or a bare key)."""
+    header = request.headers.get("authorization")
+    if not header:
+        return None
+    header = header.strip()
+    if header.lower().startswith("bearer "):
+        return header[7:].strip() or None
+    return header or None
+
+
+async def get_api_key_user(request: Request) -> dict:
+    """FastAPI dependency: authenticate a public-API request by API key.
+
+    Resolves ``Authorization: Bearer <key>`` to the owning user, updates the
+    key's last-used timestamp, and returns ``{username, device_id, device_name}``.
+    Raises 401 when the header is missing or the key is unknown.
+    """
+    key = _extract_bearer_key(request)
+    if not key:
+        raise HTTPException(
+            status_code=401,
+            detail="Missing API key",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    db = request.app.state.db
+    row = await db.get_device_key_by_hash(hash_api_key(key))
+    if not row:
+        raise HTTPException(
+            status_code=401,
+            detail="Invalid API key",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    try:
+        await db.touch_device_key(row["id"])
+    except Exception:  # noqa: BLE001 — last-used tracking must never block a request
+        pass
+    return {
+        "username": row["username"],
+        "device_id": row["id"],
+        "device_name": row["device_name"],
+    }

{kryten_webqueue-0.41.0 → kryten_webqueue-0.42.0}/kryten_webqueue/catalog/db/__init__.py

@@ -13,6 +13,7 @@ from ._people import _PeopleMixin
 from ._enrichment import _EnrichmentMixin
 from ._fetch_queue import _FetchQueueMixin
 from ._blackouts import _BlackoutMixin
+from ._devices import _DevicesMixin
 
 
 class Database(
@@ -25,6 +26,7 @@ class Database(
     _EnrichmentMixin,
     _FetchQueueMixin,
     _BlackoutMixin,
+    _DevicesMixin,
     _DBBase,
 ):
     """Async SQLite database wrapper."""

{kryten_webqueue-0.41.0 → kryten_webqueue-0.42.0}/kryten_webqueue/catalog/db/_connection.py

@@ -474,6 +474,41 @@ MIGRATIONS = [
     );
     CREATE INDEX IF NOT EXISTS idx_catalog_blackouts_expires ON catalog_blackouts(expires_at);
     """,
+    # v27: Device linking for the public API (Smart-TV / tablet apps).
+    #
+    # device_link_codes are short-lived, single-use one-time pads: a logged-in
+    # user names a device and receives a 5-char code (10-min TTL). The device
+    # POSTs the code to /api/public/v1/link to exchange it for an API key. The
+    # code is deleted the moment it is successfully redeemed (one key per pad).
+    #
+    # device_api_keys stores issued keys as an irreversible SHA-256 hash plus a
+    # non-secret display prefix and the user-chosen device name. The full key is
+    # returned exactly once (at exchange) and never persisted in plaintext. A
+    # user may hold many keys (one per linked device); revoking a row (via the
+    # dashboard, or automatically on ban) permanently disables that device.
+    """
+    CREATE TABLE IF NOT EXISTS device_link_codes (
+        code        TEXT PRIMARY KEY,
+        username    TEXT NOT NULL,
+        device_name TEXT NOT NULL,
+        created_at  TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        expires_at  TIMESTAMP NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_device_link_codes_user ON device_link_codes(username);
+    CREATE INDEX IF NOT EXISTS idx_device_link_codes_expires ON device_link_codes(expires_at);
+
+    CREATE TABLE IF NOT EXISTS device_api_keys (
+        id           INTEGER PRIMARY KEY AUTOINCREMENT,
+        username     TEXT NOT NULL,
+        device_name  TEXT NOT NULL,
+        key_prefix   TEXT NOT NULL,
+        key_hash     TEXT NOT NULL UNIQUE,
+        created_at   TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        last_used_at TIMESTAMP
+    );
+    CREATE INDEX IF NOT EXISTS idx_device_api_keys_user ON device_api_keys(username);
+    CREATE INDEX IF NOT EXISTS idx_device_api_keys_hash ON device_api_keys(key_hash);
+    """,
 ]