feat: API token authentication for programmatic access

Add Bearer token support for machine-to-machine API access (Home Assistant,
scripts, other DOCSight instances). Tokens are managed via Settings > General
when admin_password is set. API routes now return 401 JSON instead of 302
redirects. Token creation/revocation requires session auth to prevent
privilege escalation from compromised tokens.

Author: Dennis Braun

app/i18n/de.json

@@ -613,5 +613,19 @@
   "timezone": "Zeitzone",
   "timezone_hint": "Verwende eine IANA-Zeitzone (z.B. Europe/Berlin), damit die Sommerzeit korrekt berücksichtigt wird.",
   "timezone_auto": "Automatisch",
-  "timezone_posix_warning": "Dein Container verwendet eine POSIX-Zeitzone ohne Sommerzeitunterstützung. Wähle eine IANA-Zeitzone (z.B. Europe/Berlin), um das zu beheben."
+  "timezone_posix_warning": "Dein Container verwendet eine POSIX-Zeitzone ohne Sommerzeitunterstützung. Wähle eine IANA-Zeitzone (z.B. Europe/Berlin), um das zu beheben.",
+  "api_tokens_title": "API-Tokens",
+  "api_tokens_desc": "Tokens für programmatischen API-Zugriff erstellen (z.B. Home Assistant, Skripte)",
+  "api_token_name": "Token-Name",
+  "api_token_name_placeholder": "z.B. Home Assistant",
+  "api_token_create": "Token erstellen",
+  "api_token_created": "Token erstellt. Jetzt kopieren — er wird nicht erneut angezeigt.",
+  "api_token_copy_warning": "Dieser Token wird nur einmal angezeigt. Sicher aufbewahren.",
+  "api_token_copied": "Token kopiert!",
+  "api_token_prefix": "Token",
+  "api_token_last_used": "Zuletzt verwendet",
+  "api_token_revoke": "Widerrufen",
+  "api_token_revoke_confirm": "Token \"{name}\" widerrufen? Systeme die ihn verwenden verlieren den Zugriff.",
+  "api_token_revoked": "Token widerrufen",
+  "api_tokens_none": "Noch keine API-Tokens erstellt."
 }

app/i18n/en.json

@@ -613,5 +613,19 @@
   "timezone": "Timezone",
   "timezone_hint": "Use an IANA timezone (e.g. Europe/Berlin) to ensure correct daylight saving time handling.",
   "timezone_auto": "Auto",
-  "timezone_posix_warning": "Your container uses a POSIX timezone that does not support daylight saving time. Select an IANA timezone (e.g. Europe/Berlin) to fix this."
+  "timezone_posix_warning": "Your container uses a POSIX timezone that does not support daylight saving time. Select an IANA timezone (e.g. Europe/Berlin) to fix this.",
+  "api_tokens_title": "API Tokens",
+  "api_tokens_desc": "Create tokens for programmatic API access (e.g. Home Assistant, scripts)",
+  "api_token_name": "Token Name",
+  "api_token_name_placeholder": "e.g. Home Assistant",
+  "api_token_create": "Create Token",
+  "api_token_created": "Token created. Copy it now — it won't be shown again.",
+  "api_token_copy_warning": "This token will only be shown once. Store it securely.",
+  "api_token_copied": "Token copied!",
+  "api_token_prefix": "Token",
+  "api_token_last_used": "Last Used",
+  "api_token_revoke": "Revoke",
+  "api_token_revoke_confirm": "Revoke token \"{name}\"? Any system using it will lose access.",
+  "api_token_revoked": "Token revoked",
+  "api_tokens_none": "No API tokens created yet."
 }

app/i18n/es.json

@@ -608,5 +608,19 @@
   "timezone": "Zona horaria",
   "timezone_hint": "Usa una zona horaria IANA (ej. Europe/Madrid) para el cambio de horario de verano automatico.",
   "timezone_auto": "Automatico",
-  "timezone_posix_warning": "Tu contenedor usa una zona horaria POSIX sin horario de verano. Selecciona una zona IANA (ej. Europe/Madrid) para corregirlo."
+  "timezone_posix_warning": "Tu contenedor usa una zona horaria POSIX sin horario de verano. Selecciona una zona IANA (ej. Europe/Madrid) para corregirlo.",
+  "api_tokens_title": "Tokens API",
+  "api_tokens_desc": "Crear tokens para acceso API programatico (ej. Home Assistant, scripts)",
+  "api_token_name": "Nombre del token",
+  "api_token_name_placeholder": "ej. Home Assistant",
+  "api_token_create": "Crear token",
+  "api_token_created": "Token creado. Copialo ahora — no se mostrara de nuevo.",
+  "api_token_copy_warning": "Este token solo se muestra una vez. Guardalo de forma segura.",
+  "api_token_copied": "Token copiado!",
+  "api_token_prefix": "Token",
+  "api_token_last_used": "Ultimo uso",
+  "api_token_revoke": "Revocar",
+  "api_token_revoke_confirm": "Revocar token \"{name}\"? Los sistemas que lo usen perderan el acceso.",
+  "api_token_revoked": "Token revocado",
+  "api_tokens_none": "No se han creado tokens API."
 }

app/i18n/fr.json

@@ -605,5 +605,19 @@
   "timezone": "Fuseau horaire",
   "timezone_hint": "Utilisez un fuseau horaire IANA (ex. Europe/Paris) pour le changement d'heure automatique.",
   "timezone_auto": "Automatique",
-  "timezone_posix_warning": "Votre conteneur utilise un fuseau horaire POSIX sans changement d'heure automatique. Selectionnez un fuseau IANA (ex. Europe/Paris) pour corriger."
+  "timezone_posix_warning": "Votre conteneur utilise un fuseau horaire POSIX sans changement d'heure automatique. Selectionnez un fuseau IANA (ex. Europe/Paris) pour corriger.",
+  "api_tokens_title": "Tokens API",
+  "api_tokens_desc": "Creer des tokens pour l'acces API programmatique (ex. Home Assistant, scripts)",
+  "api_token_name": "Nom du token",
+  "api_token_name_placeholder": "ex. Home Assistant",
+  "api_token_create": "Creer un token",
+  "api_token_created": "Token cree. Copiez-le maintenant — il ne sera plus affiche.",
+  "api_token_copy_warning": "Ce token ne sera affiche qu'une seule fois. Conservez-le en securite.",
+  "api_token_copied": "Token copie !",
+  "api_token_prefix": "Token",
+  "api_token_last_used": "Derniere utilisation",
+  "api_token_revoke": "Revoquer",
+  "api_token_revoke_confirm": "Revoquer le token \"{name}\" ? Les systemes qui l'utilisent perdront l'acces.",
+  "api_token_revoked": "Token revoque",
+  "api_tokens_none": "Aucun token API cree."
 }

app/storage.py

@@ -3,9 +3,12 @@
 import json
 import logging
 import os
+import secrets
 import sqlite3
 from datetime import datetime, timedelta
 
+from werkzeug.security import generate_password_hash, check_password_hash
+
 ALLOWED_MIME_TYPES = {
     "image/png", "image/jpeg", "image/gif", "image/webp",
     "application/pdf", "text/plain",
@@ -275,6 +278,72 @@ def _init_db(self):
                 except Exception as e:
                     log.warning("Failed to add is_demo to %s: %s", tbl, e)
 
+            # ── API tokens table ──
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS api_tokens (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    name TEXT NOT NULL,
+                    token_hash TEXT NOT NULL,
+                    token_prefix TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    last_used_at TEXT,
+                    revoked INTEGER NOT NULL DEFAULT 0
+                )
+            """)
+
+    # ── API Token Management ──
+
+    def create_api_token(self, name):
+        """Create a new API token. Returns (token_id, plaintext_token)."""
+        raw = secrets.token_urlsafe(48)
+        plaintext = "dsk_" + raw
+        prefix = plaintext[:8]
+        token_hash = generate_password_hash(plaintext)
+        created_at = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
+        with sqlite3.connect(self.db_path) as conn:
+            cur = conn.execute(
+                "INSERT INTO api_tokens (name, token_hash, token_prefix, created_at) VALUES (?, ?, ?, ?)",
+                (name, token_hash, prefix, created_at),
+            )
+            return cur.lastrowid, plaintext
+
+    def validate_api_token(self, token):
+        """Validate a Bearer token. Returns token info dict or None."""
+        with sqlite3.connect(self.db_path) as conn:
+            conn.row_factory = sqlite3.Row
+            rows = conn.execute(
+                "SELECT id, name, token_hash, token_prefix, created_at, last_used_at FROM api_tokens WHERE revoked = 0"
+            ).fetchall()
+            for row in rows:
+                if check_password_hash(row["token_hash"], token):
+                    now = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
+                    conn.execute("UPDATE api_tokens SET last_used_at = ? WHERE id = ?", (now, row["id"]))
+                    return {
+                        "id": row["id"],
+                        "name": row["name"],
+                        "token_prefix": row["token_prefix"],
+                        "created_at": row["created_at"],
+                    }
+        return None
+
+    def get_api_tokens(self):
+        """Return list of all tokens (without hashes) for UI display."""
+        with sqlite3.connect(self.db_path) as conn:
+            conn.row_factory = sqlite3.Row
+            rows = conn.execute(
+                "SELECT id, name, token_prefix, created_at, last_used_at, revoked FROM api_tokens ORDER BY created_at DESC"
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    def revoke_api_token(self, token_id):
+        """Soft-revoke a token. Returns True if a token was revoked."""
+        with sqlite3.connect(self.db_path) as conn:
+            cur = conn.execute(
+                "UPDATE api_tokens SET revoked = 1 WHERE id = ? AND revoked = 0",
+                (token_id,),
+            )
+            return cur.rowcount > 0
+
     def save_snapshot(self, analysis):
         """Save current analysis as a snapshot. Runs cleanup afterwards."""
         ts = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")

app/templates/settings.html

@@ -726,6 +726,50 @@
                             </div>
                         </div>
                     </div>
+
+                    <!-- API Tokens (only when password is set) -->
+                    {% if config.admin_password %}
+                    <div class="settings-card" id="api-tokens-card">
+                        <div class="settings-card-header">
+                            <div class="settings-card-icon"><i data-lucide="key-round"></i></div>
+                            <div>
+                                <div class="settings-card-title">{{ t.api_tokens_title|default('API Tokens') }}</div>
+                                <div class="settings-card-desc">{{ t.api_tokens_desc|default('Create tokens for programmatic API access') }}</div>
+                            </div>
+                        </div>
+                        <div style="padding: 0 16px 16px;">
+                            <div style="display: flex; gap: 8px; margin-bottom: 12px;">
+                                <input type="text" id="api-token-name" placeholder="{{ t.api_token_name_placeholder|default('e.g. Home Assistant') }}" style="flex: 1;">
+                                <button type="button" class="btn btn-primary" onclick="createApiToken()">
+                                    <i data-lucide="plus" style="width:16px;height:16px;"></i>
+                                    {{ t.api_token_create|default('Create Token') }}
+                                </button>
+                            </div>
+                            <div id="api-token-created-banner" style="display: none; background: var(--card-bg, #1a1d23); border: 1px solid var(--accent, #4f8cff); border-radius: 8px; padding: 12px; margin-bottom: 12px;">
+                                <div style="font-weight: 600; margin-bottom: 4px;">{{ t.api_token_created|default('Token created. Copy it now.') }}</div>
+                                <div style="display: flex; gap: 8px; align-items: center;">
+                                    <code id="api-token-plaintext" style="flex: 1; word-break: break-all; font-size: 0.85em; padding: 6px 8px; background: var(--bg, #12141a); border-radius: 4px;"></code>
+                                    <button type="button" class="btn" onclick="copyToken()" style="white-space: nowrap;">
+                                        <i data-lucide="copy" style="width:14px;height:14px;"></i>
+                                    </button>
+                                </div>
+                                <div style="font-size: 0.8em; opacity: 0.7; margin-top: 6px;">{{ t.api_token_copy_warning|default('This token will only be shown once.') }}</div>
+                            </div>
+                            <table id="api-tokens-table" style="width: 100%; font-size: 0.9em; display: none;">
+                                <thead>
+                                    <tr style="text-align: left; opacity: 0.7;">
+                                        <th style="padding: 4px 8px;">{{ t.api_token_name|default('Name') }}</th>
+                                        <th style="padding: 4px 8px;">{{ t.api_token_prefix|default('Token') }}</th>
+                                        <th style="padding: 4px 8px;">{{ t.api_token_last_used|default('Last Used') }}</th>
+                                        <th style="padding: 4px 8px;"></th>
+                                    </tr>
+                                </thead>
+                                <tbody id="api-tokens-body"></tbody>
+                            </table>
+                            <div id="api-tokens-empty" style="opacity: 0.6; font-size: 0.9em;">{{ t.api_tokens_none|default('No API tokens created yet.') }}</div>
+                        </div>
+                    </div>
+                    {% endif %}
                 </div>
 
                 <!-- ═══ Panel: Backup ═══ -->
@@ -1173,10 +1217,106 @@
         saveFooter.style.display = (id === 'support') ? 'none' : '';
     }
 
+    if (id === 'general') loadApiTokens();
     history.replaceState(null, '', '#' + id);
     closeMobileSidebar();
 }
 
+/* ── API Token Management ── */
+function _tokenCell(text, style) {
+    var td = document.createElement('td');
+    td.style.cssText = style || 'padding:4px 8px;';
+    td.textContent = text;
+    return td;
+}
+
+function loadApiTokens() {
+    var table = document.getElementById('api-tokens-table');
+    var body = document.getElementById('api-tokens-body');
+    var empty = document.getElementById('api-tokens-empty');
+    if (!table || !body) return;
+    fetch('/api/tokens').then(function(r) { return r.json(); }).then(function(data) {
+        var tokens = (data.tokens || []).filter(function(t) { return !t.revoked; });
+        while (body.firstChild) body.removeChild(body.firstChild);
+        if (tokens.length === 0) {
+            table.style.display = 'none';
+            if (empty) empty.style.display = 'block';
+            return;
+        }
+        table.style.display = 'table';
+        if (empty) empty.style.display = 'none';
+        tokens.forEach(function(tk) {
+            var tr = document.createElement('tr');
+            tr.appendChild(_tokenCell(tk.name, 'padding:4px 8px;'));
+            var prefixTd = document.createElement('td');
+            prefixTd.style.cssText = 'padding:4px 8px;';
+            var code = document.createElement('code');
+            code.textContent = tk.token_prefix + '...';
+            prefixTd.appendChild(code);
+            tr.appendChild(prefixTd);
+            tr.appendChild(_tokenCell(tk.last_used_at || '\u2014', 'padding:4px 8px;'));
+            var actionTd = document.createElement('td');
+            actionTd.style.cssText = 'padding:4px 8px;';
+            var btn = document.createElement('button');
+            btn.type = 'button';
+            btn.className = 'btn btn-sm';
+            btn.style.cssText = 'font-size:0.8em;padding:2px 8px;';
+            btn.textContent = T.api_token_revoke || 'Revoke';
+            btn.setAttribute('data-token-id', tk.id);
+            btn.setAttribute('data-token-name', tk.name);
+            btn.addEventListener('click', function() {
+                revokeToken(parseInt(this.getAttribute('data-token-id')), this.getAttribute('data-token-name'));
+            });
+            actionTd.appendChild(btn);
+            tr.appendChild(actionTd);
+            body.appendChild(tr);
+        });
+    }).catch(function() {});
+}
+
+function createApiToken() {
+    var inp = document.getElementById('api-token-name');
+    var name = (inp.value || '').trim();
+    if (!name) { inp.focus(); return; }
+    fetch('/api/tokens', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({name: name})
+    }).then(function(r) { return r.json().then(function(d) { return {ok: r.ok, data: d}; }); })
+    .then(function(res) {
+        if (!res.ok) { showToast(res.data.error || 'Error', false); return; }
+        inp.value = '';
+        var banner = document.getElementById('api-token-created-banner');
+        document.getElementById('api-token-plaintext').textContent = res.data.token;
+        banner.style.display = 'block';
+        loadApiTokens();
+        if (typeof lucide !== 'undefined') lucide.createIcons();
+    }).catch(function() { showToast('Error', false); });
+}
+
+function copyToken() {
+    var text = document.getElementById('api-token-plaintext').textContent;
+    navigator.clipboard.writeText(text).then(function() {
+        showToast(T.api_token_copied || 'Token copied!', true);
+    });
+}
+
+function revokeToken(id, name) {
+    var msg = (T.api_token_revoke_confirm || 'Revoke token "{name}"?').replace('{name}', name);
+    if (!confirm(msg)) return;
+    fetch('/api/tokens/' + id, {method: 'DELETE'})
+    .then(function(r) { return r.json(); })
+    .then(function(data) {
+        if (data.success) {
+            showToast(T.api_token_revoked || 'Token revoked', true);
+            document.getElementById('api-token-created-banner').style.display = 'none';
+            loadApiTokens();
+        } else {
+            showToast(data.error || 'Error', false);
+        }
+    }).catch(function() { showToast('Error', false); });
+}
+
 /* Restore section from URL hash */
 (function() {
     var hash = location.hash.replace('#', '');