API compliance

Author: ckdake

PRODUCTION.md

@@ -156,6 +156,17 @@ No CLI step needed. Enter your email, password, and API key directly in the Sett
 
 > Re-authenticate any time tokens expire by clicking the button again.
 
+#### Strava write-only enforcement (API TOS)
+
+Strava's API terms require that Strava data is never used as a source of truth for other providers, and that all Strava data is deleted immediately when a user disconnects. TraceKit enforces this by setting `"write_only": True` on the Strava provider entry in `tracekit/appconfig.py`. The sync engine reads this flag and:
+
+- never selects Strava as the authoritative provider when resolving name/equipment conflicts
+- never propagates Strava-only activities outward to other providers
+- excludes Strava activity records older than 7 days from correlation (per API TOS data freshness requirements)
+- deletes all Strava activity data immediately on user disconnect (both via the Settings UI "Disconnect Strava" button and via the Strava deauthorization webhook)
+
+If `"write_only"` is removed or set to `False` for the Strava provider in `tracekit/appconfig.py`, Strava will start behaving like any other provider (source-of-truth capable). Do not do this — it would violate the Strava API TOS.
+
 ### Garmin
 
 Garmin uses garth for OAuth. Tokens are stored in the database and valid for roughly a year.

app/routes/auth_strava.py

@@ -3,7 +3,8 @@
 import os
 
 from db_init import _init_db
-from flask import Blueprint, redirect, request
+from flask import Blueprint, jsonify, redirect, request
+from flask_login import current_user
 
 strava_bp = Blueprint("auth_strava", __name__)
 
@@ -144,3 +145,56 @@ def api_auth_strava_callback():
         return _strava_callback_page(True, "Strava authentication successful!")
     except Exception as e:
         return _strava_callback_page(False, f"Token exchange failed: {e}")
+
+
+@strava_bp.route("/api/auth/strava/disconnect", methods=["POST"])
+def api_auth_strava_disconnect():
+    """Disconnect Strava: delete all local Strava activity data then clear credentials.
+
+    Required by Strava API TOS: when a user unlinks Strava, all data retrieved
+    via the Strava API must be immediately deleted.
+    """
+    _init_db()
+
+    from tracekit.user_context import set_user_id
+
+    if current_user.is_authenticated:
+        set_user_id(current_user.id)
+
+    errors = []
+
+    # 1. Delete all Strava activity data for this user.
+    try:
+        from tracekit.appconfig import load_config
+        from tracekit.core import Tracekit
+
+        config = load_config()
+        tk = Tracekit(config)
+        if tk.strava:
+            tk.strava.reset_activities(None)
+    except Exception as e:
+        errors.append(f"activity deletion failed: {e}")
+
+    # 2. Clear OAuth tokens and disable the provider.
+    try:
+        import json
+
+        from tracekit.appconfig import AppConfig, clear_strava_tokens
+
+        clear_strava_tokens()
+        user_id = current_user.id if current_user.is_authenticated else 0
+        row = AppConfig.get_or_none((AppConfig.key == "providers") & (AppConfig.user_id == user_id))
+        if row:
+            providers = json.loads(row.value)
+            strava_cfg = providers.get("strava", {}).copy()
+            strava_cfg["enabled"] = False
+            providers["strava"] = strava_cfg
+            AppConfig.update({AppConfig.value: json.dumps(providers)}).where(
+                (AppConfig.key == "providers") & (AppConfig.user_id == user_id)
+            ).execute()
+    except Exception as e:
+        errors.append(f"credential clearing failed: {e}")
+
+    if errors:
+        return jsonify({"error": "; ".join(errors)}), 500
+    return jsonify({"status": "disconnected"})

app/routes/strava_webhook.py

@@ -215,7 +215,11 @@ def _sync_local_activity(activity_id, user_id: int):
 
 
 def _handle_deauthorize(owner_id):
-    """Disable Strava and clear tokens for the user who revoked access."""
+    """Disable Strava and clear tokens for the user who revoked access.
+
+    Per Strava API TOS, all data retrieved via the Strava API must be deleted
+    immediately when a user deauthorizes the application.
+    """
     import json
 
     from tracekit.appconfig import AppConfig
@@ -228,6 +232,19 @@ def _handle_deauthorize(owner_id):
 
     set_user_id(user_id)
 
+    # Delete all Strava activity data for this user (required by Strava API TOS).
+    try:
+        from tracekit.appconfig import load_config
+        from tracekit.core import Tracekit
+
+        config = load_config()
+        tk = Tracekit(config)
+        if tk.strava:
+            deleted = tk.strava.reset_activities(None)
+            log.info("Strava deauth: deleted %d activity records for user_id=%d", deleted, user_id)
+    except Exception as e:
+        log.error("Strava deauth: error deleting activity data for user_id=%d: %s", user_id, e)
+
     try:
         row = AppConfig.get_or_none((AppConfig.key == "providers") & (AppConfig.user_id == user_id))
         if row is None:
@@ -247,7 +264,10 @@ def _handle_deauthorize(owner_id):
             .execute()
         )
         log.info("Strava deauth: disabled provider for user_id=%d", user_id)
-        _notify_admin(f"Strava webhook: user {user_id} (athlete {owner_id}) deauthorized — provider disabled", "error")
+        _notify_admin(
+            f"Strava webhook: user {user_id} (athlete {owner_id}) deauthorized — provider disabled and all data deleted",
+            "error",
+        )
     except Exception as e:
         log.error("Strava deauth: error disabling provider for user_id=%d: %s", user_id, e)
         _notify_admin(f"Strava webhook: deauth error for user {user_id}: {e}", "error")

app/static/settings.js

@@ -15,6 +15,11 @@ function showStatus(text, type = 'ok') {
 const PROVIDER_META = {
     strava: {
         label: 'Strava', sync_equipment: true, sync_name: true,
+        // Strava API TOS: Strava is a write-only target — it can never be the
+        // authoritative source for other providers.
+        write_only: true,
+        sync_equipment_label: 'Write equipment',
+        sync_name_label: 'Write name',
         // No text_fields by default — client_id/secret come from system credentials.
         // They are revealed in personal_credential_fields when the toggle is on.
         text_fields: [],
@@ -161,7 +166,8 @@ function makeProviderCard(name, data) {
 
     const header = document.createElement('div');
     header.className = 'provider-header';
-    header.innerHTML = `<span class="drag-handle">⠿</span><span class="provider-name">${escHtml(meta.label)}</span><span class="provider-activity-count"></span><span class="provider-inline-status"></span>`;
+    const writeOnlyBadge = meta.write_only ? '<span class="write-only-badge">write only</span>' : '';
+    header.innerHTML = `<span class="drag-handle">⠿</span><span class="provider-name">${escHtml(meta.label)}</span>${writeOnlyBadge}<span class="provider-activity-count"></span><span class="provider-inline-status"></span>`;
 
     const enabledToggle = makeToggle(`en-${name}`, data.enabled, 'Enabled');
     enabledToggle.querySelector('input').addEventListener('change', e => {
@@ -181,15 +187,17 @@ function makeProviderCard(name, data) {
     controls.className = 'provider-controls';
 
     if (meta.sync_equipment) {
-        const t = makeToggle(`se-${name}`, data.sync_equipment ?? false, 'Sync equipment');
+        const equipLabel = meta.sync_equipment_label || 'Sync equipment';
+        const t = makeToggle(`se-${name}`, data.sync_equipment ?? false, equipLabel);
         const seInput = t.querySelector('input');
         seInput.disabled = !data.enabled || !!meta.sync_equipment_disabled;
         if (!meta.sync_equipment_disabled) seInput.addEventListener('change', autoSave);
         if (meta.sync_equipment_disabled) t.title = 'Not supported by this provider';
         controls.appendChild(t);
     }
     if (meta.sync_name) {
-        const t = makeToggle(`sn-${name}`, data.sync_name ?? false, 'Sync name');
+        const nameLabel = meta.sync_name_label || 'Sync name';
+        const t = makeToggle(`sn-${name}`, data.sync_name ?? false, nameLabel);
         t.querySelector('input').disabled = !data.enabled;
         t.querySelector('input').addEventListener('change', autoSave);
         controls.appendChild(t);
@@ -223,6 +231,36 @@ function makeProviderCard(name, data) {
         authBtn.appendChild(stravaImg);
         authBtn.addEventListener('click', () => { window.location.href = '/api/auth/strava/authorize'; });
         card.appendChild(authBtn);
+
+        if (data.access_token) {
+            const disconnectBtn = document.createElement('button');
+            disconnectBtn.type = 'button';
+            disconnectBtn.className = 'btn btn-danger strava-disconnect-btn';
+            disconnectBtn.textContent = 'Disconnect Strava';
+            disconnectBtn.title = 'Disconnecting will immediately and permanently delete all Strava activity data from TraceKit (required by Strava API terms).';
+            disconnectBtn.addEventListener('click', async () => {
+                if (!confirm('Disconnecting Strava will immediately and permanently delete ALL Strava activity data from TraceKit. This is required by Strava\'s API terms and cannot be undone.\n\nContinue?')) return;
+                disconnectBtn.disabled = true;
+                disconnectBtn.textContent = 'Disconnecting…';
+                try {
+                    const resp = await fetch('/api/auth/strava/disconnect', { method: 'POST' });
+                    if (resp.ok) {
+                        showStatus('Strava disconnected. All Strava data deleted.');
+                        window.location.reload();
+                    } else {
+                        const d = await resp.json().catch(() => ({}));
+                        showStatus('Error: ' + (d.error || 'disconnect failed'), 'error');
+                        disconnectBtn.disabled = false;
+                        disconnectBtn.textContent = 'Disconnect Strava';
+                    }
+                } catch (e) {
+                    showStatus('Network error: ' + e.message, 'error');
+                    disconnectBtn.disabled = false;
+                    disconnectBtn.textContent = 'Disconnect Strava';
+                }
+            });
+            card.appendChild(disconnectBtn);
+        }
     }
 
     // RideWithGPS: OAuth button, same pattern as Strava.
@@ -404,11 +442,31 @@ function renderProviders(config) {
             return pa !== pb ? pa - pb : a[0].localeCompare(b[0]);
         });
 
+    const normalEntries   = entries.filter(([name]) => !(PROVIDER_META[name] || {}).write_only);
+    const writeOnlyEntries = entries.filter(([name]) =>  (PROVIDER_META[name] || {}).write_only);
+
     const list = document.getElementById('provider-list');
     list.innerHTML = '';
-    for (const [name, data] of entries) {
+
+    for (const [name, data] of normalEntries) {
         list.appendChild(makeProviderCard(name, data));
     }
+
+    if (writeOnlyEntries.length > 0) {
+        const divider = document.createElement('div');
+        divider.className = 'write-only-divider';
+        divider.innerHTML = '<hr><span class="write-only-divider-label">Write-only providers — receive updates, never a source of truth</span>';
+        list.appendChild(divider);
+
+        for (const [name, data] of writeOnlyEntries) {
+            const card = makeProviderCard(name, data);
+            // Write-only providers should not be dragged into the authoritative
+            // provider ordering — remove drag capability.
+            card.draggable = false;
+            card.querySelector('.drag-handle')?.remove();
+            list.appendChild(card);
+        }
+    }
 }
 
 // ── Collect settings from DOM and save ───────────────────────────────────────

app/static/style.css

@@ -1065,6 +1065,43 @@ select#timezone:focus {
 .auth-status-chip.connected { background: #eaf6ef; color: #1e8449; border: 1px solid #a9dfbf; }
 .auth-status-chip.not-connected { background: #f5f5f5; color: #888; border: 1px solid #ddd; }
 
+/* Write-only provider badge — shown in provider card header */
+.write-only-badge {
+    display: inline-block;
+    font-size: 0.7rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    background: #fff3cd;
+    color: #856404;
+    border: 1px solid #ffc107;
+    border-radius: 4px;
+    padding: 1px 6px;
+    margin-left: 4px;
+    vertical-align: middle;
+}
+
+/* Divider between regular and write-only providers */
+.write-only-divider {
+    margin: 12px 0 4px;
+}
+.write-only-divider hr {
+    border: none;
+    border-top: 1px solid #e0e0e0;
+    margin: 0 0 6px;
+}
+.write-only-divider-label {
+    font-size: 0.78rem;
+    color: #888;
+    font-style: italic;
+}
+
+/* Disconnect button for write-only providers */
+.strava-disconnect-btn {
+    margin-top: 10px;
+    font-size: 0.85rem;
+}
+
 /* Strava-branded auth button — uses official connect_with_strava.svg */
 .strava-auth-btn {
     display: inline-block;

tracekit/appconfig.py

@@ -39,6 +39,7 @@
         "strava": {
             "enabled": False,
             "priority": 3,
+            "write_only": True,  # Strava API TOS: Strava is a write target only, never a source of truth
             "sync_equipment": True,
             "sync_name": True,
             "use_personal_credentials": False,

tracekit/calendar.py

@@ -191,26 +191,27 @@ def get_single_month_data(year_month: str, home_timezone: str = "UTC") -> dict[s
         except Exception as e:
             print(f"Error getting activity days for {provider}/{year_month}: {e}")
 
-    garmin_devices: list[str] = []
-    try:
-        rows = (
-            GarminActivity.select(GarminActivity.device_name)
-            .where(
-                GarminActivity.start_time.is_null(False)
-                & (GarminActivity.start_time >= start_ts)
-                & (GarminActivity.start_time <= end_ts)
-                & GarminActivity.device_name.is_null(False)
-                & (GarminActivity.user_id == uid)
-            )
-            .distinct()
-        )
-        garmin_devices = sorted({r.device_name for r in rows if r.device_name})
-    except Exception:
-        pass
-
     provider_metadata: dict[str, dict] = {}
-    if garmin_devices:
-        provider_metadata["garmin"] = {"devices": garmin_devices}
+    for provider, model in provider_models.items():
+        if provider not in activity_counts:
+            continue
+        try:
+            rows = (
+                model.select(model.device_name)
+                .where(
+                    model.start_time.is_null(False)
+                    & (model.start_time >= start_ts)
+                    & (model.start_time <= end_ts)
+                    & model.device_name.is_null(False)
+                    & (model.user_id == uid)
+                )
+                .distinct()
+            )
+            devices = sorted({r.device_name for r in rows if r.device_name})
+            if devices:
+                provider_metadata[provider] = {"devices": devices}
+        except Exception:
+            pass
 
     return {
         "year_month": year_month,

tracekit/database.py

@@ -202,6 +202,11 @@ def _run_schema_upgrades() -> None:
         is_sqlite,
         [
             ("garmin_activities", "device_name", "VARCHAR(255)"),
+            ("strava_activities", "device_name", "VARCHAR(255)"),
+            ("ridewithgps_activities", "device_name", "VARCHAR(255)"),
+            ("intervalsicu_activities", "device_name", "VARCHAR(255)"),
+            ("file_activities", "device_name", "VARCHAR(255)"),
+            ("spreadsheet_activities", "device_name", "VARCHAR(255)"),
             ("notification", "expires", "INTEGER"),
             ("provider_status", "rate_limit_type", "VARCHAR(64)"),
             ("provider_status", "rate_limit_reset_at", "INTEGER"),

tracekit/providers/base_provider_activity.py

@@ -39,6 +39,7 @@ class BaseProviderActivity(Model):
     activity_type = CharField(max_length=50, null=True)
     duration_hms = CharField(max_length=20, null=True)
     equipment = CharField(max_length=255, null=True)
+    device_name = CharField(max_length=255, null=True)
 
     # Location information
     location_name = CharField(max_length=255, null=True)

tracekit/providers/garmin/garmin_activity.py

@@ -15,9 +15,6 @@ class GarminActivity(BaseProviderActivity):
     # Garmin-specific ID field
     garmin_id = CharField(max_length=50, unique=True, index=True)
 
-    # Device that recorded this activity (e.g. "Forerunner 965")
-    device_name = CharField(max_length=255, null=True)
-
     class Meta:  # type: ignore
         database = db
         table_name = "garmin_activities"