fix: block on invalid OAuth credentials

Author: sumitake

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable project changes are recorded here. The README shows only the most recent entry.
 
+## 2026-07-14 - OAuth-Blocked Recovery
+
+- Classified refresh-token `invalid_grant` responses and unusable token files as explicit OAuth authorization blocks instead of ambiguous retry failures.
+- Added bounded local credential fingerprinting and signal-interruptible waiting that makes no API calls until token content changes, then resumes automatically.
+- Preserved already-public FFmpeg ingest under its local watchdog during an OAuth block and revalidated the exact cached lifecycle state after reauthorization.
+- Limited custom child-stopping signal handlers to visible test-pattern runs so device authorization terminates normally.
+- Added regression coverage and operator documentation for revoked, missing, malformed, unreadable, and oversized token states.
+
 ## 2026-07-11 - Description-Neutral Lifecycle Identity
 
 - Stopped setting `liveBroadcast` and `liveStream` descriptions; new insert payloads omit the description field entirely and privacy updates remain status-only.

README.md

@@ -132,6 +132,7 @@ See the [recovery state machine](docs/architecture-and-flows.md#recovery-state-m
 | Lifecycle state is missing or corrupt | Legacy markers may be read once for migration; otherwise conflicting same-stream or same-title resources block creation until an operator reconciles ownership. |
 | Ambiguous or unknown remote state | Reconciliation fails closed and creates nothing until the ambiguity is resolved. |
 | OAuth access token expires | API helper refreshes from the stored refresh token. |
+| OAuth refresh token is missing, invalid, expired, revoked, unreadable, or malformed | API mutation pauses without entering ambiguous backoff. The service waits for the token file to change and resumes automatically after `youtube-autoencoder-api authorize` saves a replacement. If a verified public stream is already running, FFmpeg remains under its local progress watchdog while the control plane is blocked. |
 | Previous broadcast is `complete`, `revoked`, or confirmed missing | One new unlisted generation may be staged after the source probe passes. |
 
 Recovery deadlines survive service and host restarts. Exponential backoff uses these class floors and caps:
@@ -143,6 +144,8 @@ Recovery deadlines survive service and host restarts. Exponential backoff uses t
 | Quota | 15 minutes | 6 hours | `userRequestsExceedRateLimit`, quota errors, HTTP 429. |
 | Ambiguous | 5 minutes | 1 hour | Multiple managed candidates, unknown lifecycle, conflicting state. |
 
+OAuth authorization failures are blocked conditions, not retry classes. They do not consume API quota while the token file is unchanged.
+
 The project never sets or updates YouTube `liveBroadcast` or `liveStream` descriptions. Normal recovery validates the exact broadcast ID in the private schema-v3 state file. Before a new insert, the helper persists the required title, scheduled start, privacy, creation window, and stream relationship; if the insert outcome is ambiguous, those fields may identify exactly one remote candidate, but they can never authorize another automatic insert. Legacy description markers are read only during one-way migration from schema v2.
 
 ### Test Pattern Flow
@@ -399,6 +402,7 @@ systemctl --user enable --now youtube-autoencoder.service
 | `invalid_client` | OAuth client type does not support the device-code flow. | Create a client for TVs and Limited Input devices, then replace `google-oauth-client.json`. |
 | `authorization_pending` | The browser approval has not completed yet. | Finish the device-code flow; the CLI will keep polling until the code expires. |
 | `slow_down` | Polling is too frequent. | The helper backs off automatically. |
+| `invalid_grant` | The refresh token expired, was revoked, or no longer belongs to the OAuth client. Testing-mode authorizations commonly expire after seven days. | Move the OAuth app to In production for unattended use, rerun `youtube-autoencoder-api authorize`, and select the account that owns or manages the intended channel. The running service detects the saved token and resumes automatically. |
 | Token works briefly then expires | App is still in Testing mode. | Add the correct test user for setup, then move the app to In production for unattended use and complete required verification. |
 | API calls fail despite valid OAuth | The account does not own/manage the YouTube channel, live streaming is not enabled, or quota/policy blocks the operation. | Reauthorize with the right channel account, enable live streaming, and check project quota and YouTube Studio restrictions. |
 
@@ -521,10 +525,11 @@ Each eligible collection performs one [`videos.list`](https://developers.google.
 
 Only the most recent changelog entry is shown here. See `CHANGELOG.md` for full history.
 
-### 2026-07-11 - Description-Neutral Lifecycle Identity
+### 2026-07-14 - OAuth-Blocked Recovery
 
-- New YouTube stream and broadcast inserts omit the description field, and normal lifecycle recovery never updates descriptions.
-- Schema-v3 exact-ID state and a durable create fingerprint retain duplicate-safe recovery; legacy markers are read only for one-way migration.
+- Refresh-token rejection and unusable token files now enter an explicit OAuth-blocked state instead of ambiguous retry backoff.
+- The supervisor waits without API calls until token content changes, preserves an already-public FFmpeg stream under its watchdog, and revalidates exact lifecycle state after reauthorization.
+- Device authorization keeps normal termination semantics; child-specific signal handling is limited to the visible test-pattern command.
 
 ## Repository Layout
 

bin/youtube-autoencoder

@@ -8,6 +8,7 @@ import contextlib
 import dataclasses
 import datetime as dt
 import fcntl
+import hashlib
 import json
 import os
 import pathlib
@@ -33,6 +34,11 @@ OBS_SERVICE_FILE = pathlib.Path(os.environ.get("YTA_OBS_SERVICE_FILE", OBS_PROFI
 OBS_SCENE_FILE = pathlib.Path(
     os.environ.get("YTA_OBS_SCENE_FILE", HOME / ".config/obs-studio/basic/scenes/Untitled.json")
 ).expanduser()
+CONFIG_DIR = pathlib.Path(os.environ.get("YTA_CONFIG_DIR", HOME / ".config/youtube-autoencoder")).expanduser()
+OAUTH_TOKEN_FILE = pathlib.Path(
+    os.environ.get("YTA_YOUTUBE_TOKEN_FILE", CONFIG_DIR / "youtube-token.json")
+).expanduser()
+OAUTH_TOKEN_MAX_BYTES = 1024 * 1024
 
 child: subprocess.Popen[Any] | None = None
 stopping = False
@@ -199,9 +205,61 @@ def lifecycle_action(lifecycle: str) -> str:
 
 
 def classify_api_error(error: ApiCommandError) -> str:
+    if error.retry_class == "oauth":
+        return "oauth"
     return error.retry_class if error.retry_class in RETRY_LIMITS else "ambiguous"
 
 
+def oauth_token_fingerprint() -> tuple[Any, ...]:
+    try:
+        token_stat = OAUTH_TOKEN_FILE.stat()
+    except FileNotFoundError:
+        return ("missing",)
+    except OSError as exc:
+        return ("unreadable", exc.errno)
+
+    metadata = (
+        token_stat.st_dev,
+        token_stat.st_ino,
+        token_stat.st_mode & 0o7777,
+        token_stat.st_uid,
+        token_stat.st_gid,
+        token_stat.st_size,
+        token_stat.st_mtime_ns,
+    )
+    if token_stat.st_size > OAUTH_TOKEN_MAX_BYTES:
+        return ("oversized", *metadata)
+    try:
+        with OAUTH_TOKEN_FILE.open("rb") as handle:
+            raw = handle.read(OAUTH_TOKEN_MAX_BYTES + 1)
+    except OSError as exc:
+        return ("unreadable", *metadata, exc.errno)
+    if len(raw) > OAUTH_TOKEN_MAX_BYTES:
+        return ("oversized", *metadata)
+    return ("readable", *metadata, hashlib.sha256(raw).hexdigest())
+
+
+def oauth_blocked_poll_interval() -> float:
+    return max(0.1, float(env("YTA_OAUTH_BLOCKED_POLL_SEC", "5")))
+
+
+def wait_for_oauth_token_change(
+    baseline: tuple[Any, ...],
+    *,
+    runtime: StreamRuntime | None = None,
+) -> bool:
+    while not stopping:
+        if oauth_token_fingerprint() != baseline:
+            log("OAuth credential change detected; resuming YouTube API recovery")
+            return True
+        duration = oauth_blocked_poll_interval()
+        if runtime is None:
+            sleep_interruptibly(duration)
+        else:
+            wait_with_runtime(runtime, duration)
+    return False
+
+
 def retry_delay(
     retry_class: str,
     *,
@@ -906,32 +964,43 @@ def revalidate_public_state(runtime: StreamRuntime, state: dict[str, Any]) -> di
 
 
 def manage_with_public_fallback(runtime: StreamRuntime, cached_state: dict[str, Any]) -> dict[str, Any]:
-    try:
-        return manage_youtube_lifecycle(runtime, prepared_state=cached_state)
-    except ApiCommandError as error:
-        if not verified_public_state(cached_state) or not error.public_fallback_allowed:
-            raise
-        ensure_encoder_running(runtime)
-        retry_class = classify_api_error(error)
-        attempt = retry_attempt(cached_state, retry_class)
-        delay = retry_delay(retry_class, attempt=attempt, retry_after=error.retry_after)
-        not_before = retry_not_before(delay)
+    while True:
+        token_fingerprint = oauth_token_fingerprint()
         try:
-            api_command_while_streaming(
-                ["set-retry", retry_class, str(attempt), not_before],
-                runtime,
-                timeout=30,
+            return manage_youtube_lifecycle(runtime, prepared_state=cached_state)
+        except ApiCommandError as error:
+            if not verified_public_state(cached_state) or not error.public_fallback_allowed:
+                raise
+            ensure_encoder_running(runtime)
+            retry_class = classify_api_error(error)
+            if retry_class == "oauth":
+                log(
+                    "YouTube OAuth authorization required; preserving verified public stream and waiting for "
+                    "credential change. Run: youtube-autoencoder-api authorize. "
+                    f"error={redact_text(str(error))}"
+                )
+                if not wait_for_oauth_token_change(token_fingerprint, runtime=runtime):
+                    return dict(cached_state)
+                continue
+            attempt = retry_attempt(cached_state, retry_class)
+            delay = retry_delay(retry_class, attempt=attempt, retry_after=error.retry_after)
+            not_before = retry_not_before(delay)
+            try:
+                api_command_while_streaming(
+                    ["set-retry", retry_class, str(attempt), not_before],
+                    runtime,
+                    timeout=30,
+                )
+            except EncoderStopped:
+                raise
+            except Exception as persist_error:  # noqa: BLE001
+                log(f"could not persist public-stream API cooldown: {redact_text(str(persist_error))}")
+            ensure_encoder_running(runtime)
+            log(
+                "YouTube API unavailable; preserving verified public stream without mutation "
+                f"class={retry_class} attempt={attempt} retry_not_before={not_before}"
             )
-        except EncoderStopped:
-            raise
-        except Exception as persist_error:  # noqa: BLE001
-            log(f"could not persist public-stream API cooldown: {redact_text(str(persist_error))}")
-        ensure_encoder_running(runtime)
-        log(
-            "YouTube API unavailable; preserving verified public stream without mutation "
-            f"class={retry_class} attempt={attempt} retry_not_before={not_before}"
-        )
-        return dict(cached_state)
+            return dict(cached_state)
 
 
 @contextlib.contextmanager
@@ -1082,13 +1151,22 @@ def supervisor_loop() -> int:
             sleep_interruptibly(cooldown)
             continue
         try:
+            token_fingerprint = oauth_token_fingerprint()
             rc = run_once(cached_state=state)
             if stopping:
                 break
             raise EncoderStopped(f"ffmpeg stream attempt exited rc={rc}")
         except Exception as exc:  # noqa: BLE001
             if stopping:
                 break
+            if isinstance(exc, ApiCommandError) and classify_api_error(exc) == "oauth":
+                log(
+                    "YouTube OAuth authorization required; pausing API recovery until the credential changes. "
+                    "Run: youtube-autoencoder-api authorize. "
+                    f"error={redact_text(str(exc))}"
+                )
+                wait_for_oauth_token_change(token_fingerprint)
+                continue
             retry_class = failure_retry_class(exc)
             try:
                 state = read_recovery_state()

bin/youtube-autoencoder-api

@@ -55,6 +55,8 @@ RATE_LIMIT_REASONS = {
     "userRateLimitExceeded",
     "userRequestsExceedRateLimit",
 }
+OAUTH_REQUIRED_REASONS = {"invalid_grant"}
+TOKEN_FILE_MAX_BYTES = 1024 * 1024
 STATE_SCHEMA_VERSION = 3
 LEGACY_STATE_SCHEMA_VERSION = 2
 RECOVERABLE_STATES = {"created", "ready", "testStarting", "testing", "liveStarting", "live"}
@@ -81,13 +83,19 @@ class YouTubeApiError(RuntimeError):
 
     @property
     def retry_class(self) -> str:
+        if any(reason in OAUTH_REQUIRED_REASONS for reason in self.reasons):
+            return "oauth"
         if self.status == 429 or any(reason in RATE_LIMIT_REASONS for reason in self.reasons):
             return "quota"
         if self.status is None or self.status >= 500:
             return "api"
         return "fatal"
 
 
+class OAuthAuthorizationRequired(RuntimeError):
+    retry_class = "oauth"
+
+
 class ReconciliationError(RuntimeError):
     retry_class = "ambiguous"
 
@@ -335,17 +343,36 @@ def authorize(_args: argparse.Namespace) -> int:
     raise TimeoutError("OAuth device code expired before authorization completed")
 
 
+def read_token_data() -> dict[str, Any]:
+    try:
+        with TOKEN_FILE.open("rb") as handle:
+            raw = handle.read(TOKEN_FILE_MAX_BYTES + 1)
+    except FileNotFoundError as exc:
+        raise OAuthAuthorizationRequired("missing token file; run: youtube-autoencoder-api authorize") from exc
+    except OSError as exc:
+        raise OAuthAuthorizationRequired(
+            f"could not read token file {TOKEN_FILE}; rerun authorization or fix its permissions"
+        ) from exc
+    if len(raw) > TOKEN_FILE_MAX_BYTES:
+        raise OAuthAuthorizationRequired("token file is too large; rerun authorization")
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise OAuthAuthorizationRequired("invalid token file; rerun authorization") from exc
+    if not isinstance(data, dict):
+        raise OAuthAuthorizationRequired("invalid token file; rerun authorization")
+    return data
+
+
 def token() -> str:
-    if not TOKEN_FILE.exists():
-        raise FileNotFoundError("missing token file; run: youtube-autoencoder-api authorize")
-    data = read_json(TOKEN_FILE)
+    data = read_token_data()
     expires_at = int(data.get("created_at") or 0) + int(data.get("expires_in") or 0) - 120
     if data.get("access_token") and time.time() < expires_at:
         return str(data["access_token"])
 
     refresh_token = str(data.get("refresh_token") or "")
     if not refresh_token:
-        raise ValueError("token file has no refresh_token; rerun authorization")
+        raise OAuthAuthorizationRequired("token file has no refresh_token; rerun authorization")
     cfg = client_config()
     refreshed = http_json(
         "POST",
@@ -1364,8 +1391,6 @@ def transition_command(args: argparse.Namespace) -> int:
 
 
 def main() -> int:
-    signal.signal(signal.SIGTERM, stop_child)
-    signal.signal(signal.SIGINT, stop_child)
     parser = argparse.ArgumentParser(description="Control YouTube Live for YouTube AutoEncoder")
     sub = parser.add_subparsers(dest="command", required=True)
 
@@ -1476,6 +1501,9 @@ def main() -> int:
     clear_retry_p.set_defaults(func=clear_retry_command)
 
     args = parser.parse_args()
+    if args.command == "run-visible-test":
+        signal.signal(signal.SIGTERM, stop_child)
+        signal.signal(signal.SIGINT, stop_child)
     return int(args.func(args))
 
 

config/youtube-autoencoder.env.example

@@ -36,6 +36,8 @@ YTA_YOUTUBE_STAGING_PRIVACY=unlisted
 YTA_YOUTUBE_LIVE_PRIVACY=public
 YTA_YOUTUBE_TITLE_PREFIX=AutoEncoder Live
 YTA_YOUTUBE_POLL_INTERVAL_SEC=5
+# Polls only the local token file while OAuth authorization is blocked; no API request is made.
+YTA_OAUTH_BLOCKED_POLL_SEC=5
 YTA_YOUTUBE_TRANSITION_TIMEOUT_SEC=180
 YTA_YOUTUBE_LOCK_TIMEOUT_SEC=10
 YTA_YOUTUBE_COMPLETE_ON_EXIT=false

docs/architecture-and-flows.md

@@ -81,6 +81,7 @@ stateDiagram-v2
         state "Testing, live, and publication gates" as RecoveryGates
         state "Verified public stream" as RecoveryStable
         state "Public stream with API cooldown" as RecoveryPublicFallback
+        state "Public stream waiting for OAuth replacement" as RecoveryPublicOAuthBlocked
 
         [*] --> RecoveryProbe
         RecoveryProbe --> RecoveryReconcile : source available
@@ -92,18 +93,23 @@ stateDiagram-v2
         RecoveryGates --> RecoveryStable : two healthy live observations and privacy readback
         RecoveryStable --> RecoveryPublicFallback : API unavailable, media healthy
         RecoveryPublicFallback --> RecoveryStable : API recovers
+        RecoveryStable --> RecoveryPublicOAuthBlocked : OAuth rejected, media healthy
+        RecoveryPublicOAuthBlocked --> RecoveryStable : token changes and exact IDs revalidate
     }
     state "Persist classified cooldown" as RecoveryBackoff
+    state "Wait for OAuth token replacement" as RecoveryOAuthBlocked
 
     [*] --> RecoveryStartup
     RecoveryStartup --> RecoveryBackoff : retry deadline active
     RecoveryBackoff --> RecoveryStartup : deadline expires or host restarts
     RecoveryStartup --> RecoveryGeneration : no active deadline
     RecoveryGeneration --> RecoveryBackoff : recoverable failure, preserve ownership
+    RecoveryGeneration --> RecoveryOAuthBlocked : OAuth rejected before verified public ingest
+    RecoveryOAuthBlocked --> RecoveryStartup : token content changes
     RecoveryCreate --> RecoveryBackoff : insert outcome uncertain, never reinsert
 ```
 
-The helper never sets or updates YouTube descriptions. Schema-v3 state stores the exact broadcast ID and a write-ahead create fingerprint. A lost insert response enters `verify_create`; recovery may adopt exactly one normalized remote match, but zero or multiple matches stay blocked under durable ambiguous backoff. Legacy description markers are read only for one-way schema-v2 migration.
+The helper never sets or updates YouTube descriptions. Schema-v3 state stores the exact broadcast ID and a write-ahead create fingerprint. A lost insert response enters `verify_create`; recovery may adopt exactly one normalized remote match, but zero or multiple matches stay blocked under durable ambiguous backoff. OAuth rejection does not enter that backoff: the service makes no further API calls until the private token file changes. Legacy description markers are read only for one-way schema-v2 migration.
 
 Return to [Recovery Behavior](../README.md#recovery-behavior).
 

docs/raspberry-pi.md

@@ -46,6 +46,7 @@ YTA_INSTANCE_ID=encoder-hostname
 YTA_YOUTUBE_STAGING_PRIVACY=unlisted
 YTA_YOUTUBE_LIVE_PRIVACY=public
 YTA_YOUTUBE_POLL_INTERVAL_SEC=5
+YTA_OAUTH_BLOCKED_POLL_SEC=5
 YTA_FFMPEG_PROGRESS_TIMEOUT_SEC=45
 YTA_YOUTUBE_COMPLETE_ON_EXIT=false
 ```
@@ -66,6 +67,8 @@ sudo -u encoder -H youtube-autoencoder-api authorize
 
 Approve the device code in a browser for the Google account that owns the YouTube channel.
 
+If a refresh token later expires or is revoked, the service enters an OAuth-blocked state without creating or mutating broadcasts. Run the same authorization command again. The service detects the atomically saved replacement token and resumes automatically; no service restart is required.
+
 For a fresh deployment without an existing reusable stream, provision and validate it before enabling the production service:
 
 ```bash