ytstats 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -6,7 +6,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.1.0] - 2026-07-27
+## [0.2.0] - 2026-07-28
+
+### Added
+
+- Add `YTSTATS_CREDENTIALS_FILE` — supply the OAuth client as a path to the JSON Google
+  issued, rather than as two extracted environment variables. Resolved after the
+  `YTSTATS_CLIENT_ID`/`YTSTATS_CLIENT_SECRET` pair and before stored credentials, so
+  existing setups are unaffected. Intended for CI, where secrets already arrive as
+  mounted files, and for per-directory configuration with direnv.
+- Add `AUTH_CLIENT_MISMATCH`, raised when a channel's stored token was issued by a
+  different OAuth client than the one currently resolving. Previously this reached
+  Google as `invalid_grant` and surfaced as `AUTH_TOKEN_EXPIRED`, which blames the
+  consent screen and sends the caller to fix the wrong thing.
+- Add a `clientId` field to `ytstats status` and to each account it lists, recording
+  which OAuth client resolved and which one authorized each channel. A client ID is
+  public by OAuth design, so neither is redacted.
+- Add a `clientId` field to `tokens.json` account records, binding each refresh token
+  to the client that issued it. Accounts written before this field existed read as
+  `null` and are treated as unknown rather than mismatched, so upgrading logs nobody
+  out.
+- Add documentation for running several OAuth clients side by side, one
+  `YTSTATS_CONFIG_DIR` per client, which moves credentials and tokens together.
+
+## [0.1.0] - 2026-07-28
 
 Initial release.
 
@@ -36,5 +59,6 @@ Initial release.
 - Client ID pre-flight validation, so a malformed OAuth client fails immediately
   instead of hanging until the browser callback times out.
 
-[Unreleased]: https://github.com/nicolasdao/ytstats/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/nicolasdao/ytstats/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/nicolasdao/ytstats/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/nicolasdao/ytstats/releases/tag/v0.1.0

package/README.md

@@ -106,7 +106,13 @@ Both the OAuth client and your tokens are written to a per-user directory, `0600
 | Linux | `$XDG_CONFIG_HOME/ytstats/` (default `~/.config/ytstats/`) |
 | Windows | `%APPDATA%\ytstats\` |
 
-Override with `YTSTATS_CONFIG_DIR`. For CI, set `YTSTATS_CLIENT_ID` and `YTSTATS_CLIENT_SECRET` instead of a file. These are plaintext files, like `gcloud`, `gh`, and `aws` use. `ytstats logout` revokes the token with Google and deletes them.
+Override with `YTSTATS_CONFIG_DIR`. For CI, point `YTSTATS_CREDENTIALS_FILE` at the JSON Google issued, or set `YTSTATS_CLIENT_ID` and `YTSTATS_CLIENT_SECRET` where the secret arrives as two variables. These are plaintext files, like `gcloud`, `gh`, and `aws` use. `ytstats logout` revokes the token with Google and deletes them.
+
+One config directory holds one OAuth client and any number of channels. To manage channels that live under *different* Google Cloud projects, give each its own directory — `YTSTATS_CONFIG_DIR` moves credentials and tokens together:
+
+```bash
+alias yt-acme='YTSTATS_CONFIG_DIR=~/.ytstats/acme ytstats'
+```
 
 ## Commands
 
@@ -227,7 +233,7 @@ src/
   diagnostics.js     the failure catalog
   errors.js          YtStatsError, Google error classification, redaction
   dates.js           reporting window resolution and validation
-test/                316 tests, none requiring network access
+test/                332 tests, none requiring network access
 docs/                topic documentation, indexed below
 ```
 

package/docs/architecture.md

@@ -31,7 +31,7 @@ bin/ytstats.js          thin shim; last-resort guard against stdout pollution
 
 ## Design principles
 
-**Everything I/O is injected.** API clients, the OAuth2 constructor, the loopback server, the browser opener, the identity lookup, the output sinks, and even `now()` are parameters with real defaults. This is why 316 tests run without a network connection and without opening a browser.
+**Everything I/O is injected.** API clients, the OAuth2 constructor, the loopback server, the browser opener, the identity lookup, the output sinks, and even `now()` are parameters with real defaults. This is why 332 tests run without a network connection and without opening a browser.
 
 **Pure logic is separated from effects.** `api/transforms.js`, `dates.js`, `config/paths.js` and `diagnostics.js` are pure and directly tested. Everything awkward to test is pushed to the edges.
 
@@ -49,7 +49,7 @@ bin/ytstats.js          thin shim; last-resort guard against stdout pollution
 | `config/store.js` | Atomic `0600` JSON read/write, traversal-safe filenames. |
 | `auth/credentials.js` | BYO credential resolution and validation. Rejects service accounts and malformed client IDs before they cost a browser round trip. |
 | `auth/oauth.js` | PKCE pair, CSRF state, loopback callback server, auth URL builder, scope list. |
-| `auth/tokens.js` | Multi-account token store keyed by channel; legacy import. |
+| `auth/tokens.js` | Multi-account token store keyed by channel; records which OAuth client issued each account's token; legacy import. |
 | `auth/session.js` | Ties the above together: `login`, `logout`, `getAuthenticatedClient` with refresh persistence. |
 | `api/client.js` | Builds the three API surfaces plus an authenticated CSV downloader; wraps calls in error mapping. |
 | `api/transforms.js` | Pure shaping: duration parsing, content classification, CSV, date normalization, row zipping. |

package/docs/auth.md

@@ -35,18 +35,21 @@ There is no code path that writes to a channel.
 
 ## Credential resolution
 
-`resolveCredentials()` returns `{ clientId, clientSecret, source }`, checking four sources in order and taking the first that yields a complete pair:
+`resolveCredentials()` returns `{ clientId, clientSecret, source }`, checking five sources in order and taking the first that yields a complete pair:
 
 | Order | Source | `source` value |
 |---|---|---|
 | 1 | `--client-secret <file>` | the path given |
 | 2 | `YTSTATS_CLIENT_ID` **and** `YTSTATS_CLIENT_SECRET` (both required) | `environment` |
-| 3 | `credentials.json` saved by a previous `ytstats login` | `stored` |
-| 4 | `client_secret*.json` auto-discovered in the working directory | the discovered path |
+| 3 | `YTSTATS_CREDENTIALS_FILE` — a path to the JSON Google issued | the path given |
+| 4 | `credentials.json` saved by a previous `ytstats login` | `stored` |
+| 5 | `client_secret*.json` auto-discovered in the working directory | the discovered path |
+
+The env pair is checked before the env path deliberately: adding the path form must not change resolution for anyone already exporting the pair.
 
 If none match, it throws `AUTH_NO_CREDENTIALS` with a `detail` naming everything it searched.
 
-`source` is for display only and never contains the secret — it is what `ytstats status` reports as `credentialSource` and what `login` prints to stderr.
+`source` is for display only and never contains the secret — it is what `ytstats status` reports as `credentialSource` and what `login` prints to stderr. `status` also reports the resolved `clientId`, which `source` alone cannot tell you once five sources can supply one; a client ID is public by OAuth design, so printing it is safe.
 
 ### File shapes accepted
 
@@ -110,6 +113,7 @@ Tokens live in `tokens.json` inside the per-user config directory (see [configur
       "channelId": "UC...",
       "channelTitle": "…",
       "customUrl": "@…",
+      "clientId": "123456789012-abc.apps.googleusercontent.com",
       "tokens": { "access_token": "…", "refresh_token": "…", "expiry_date": 0 },
       "savedAt": "2026-07-27T10:00:00.000Z"
     }
@@ -119,7 +123,17 @@ Tokens live in `tokens.json` inside the per-user config directory (see [configur
 
 Keyed by channel, so one machine can hold several. The first account logged in wins `default`; `ytstats use` changes it.
 
-**Saving merges rather than replaces.** A refresh response from Google contains a new `access_token` but no `refresh_token`, so `saveAccount()` spreads the existing tokens under the new ones. Overwriting would destroy the long-lived credential.
+**Saving merges rather than replaces.** A refresh response from Google contains a new `access_token` but no `refresh_token`, so `saveAccount()` spreads the existing tokens under the new ones. Overwriting would destroy the long-lived credential. `clientId` falls back the same way, because the refresh write-back path calls `saveAccount()` without one.
+
+### The client binding
+
+`clientId` records which OAuth client issued this account's refresh token. Google binds a refresh token to the client that issued it, so the pairing matters — but `credentials.json` holds one client for the whole config directory while `tokens.json` holds many channels, and the two can drift apart when a second `login` with a different `client_secret` overwrites the stored client.
+
+`getAuthenticatedClient()` compares the two after loading the account and throws `AUTH_CLIENT_MISMATCH` when they disagree. Without that check the run proceeds to a refresh Google rejects as `invalid_grant`, which maps to `AUTH_TOKEN_EXPIRED` and blames the consent screen — an accurate-sounding diagnosis of the wrong problem.
+
+The check is skipped when `account.clientId` is absent, so accounts stored before the field existed keep working: an unknown binding is not a mismatch. The field is not a secret and is never used to authenticate; `listAccounts()` includes it, and `ytstats status` prints it per account.
+
+To hold several clients on one machine, give each its own `YTSTATS_CONFIG_DIR` — see [configuration.md](configuration.md#running-several-oauth-clients-side-by-side).
 
 ### Refresh persistence
 
@@ -156,6 +170,7 @@ An unrecognised selector returns `null` — never a silent fallback to the defau
 | No OAuth client anywhere | `AUTH_NO_CREDENTIALS` |
 | Client exists, never logged in | `AUTH_NO_TOKENS` |
 | `--account` names an unknown channel | `AUTH_ACCOUNT_UNKNOWN` |
+| Stored token was issued by a different OAuth client | `AUTH_CLIENT_MISMATCH` |
 | Refresh token rejected (`invalid_grant`) | `AUTH_TOKEN_EXPIRED` |
 | Access explicitly revoked | `AUTH_TOKEN_REVOKED` |
 | Consent screen dismissed | `AUTH_CONSENT_DECLINED` |

package/docs/cli.md

@@ -76,7 +76,7 @@ Runs the loopback OAuth flow: opens the browser, captures the callback on `127.0
 | `--no-browser` | off | Print the URL and read the pasted redirect back — for SSH and headless machines |
 | `--timeout <seconds>` | `300` | How long to wait for the browser callback, so an automated caller is never blocked indefinitely |
 
-Credentials are resolved in this order: `--client-secret` → `YTSTATS_CLIENT_ID`/`YTSTATS_CLIENT_SECRET` → stored `credentials.json` → `client_secret*.json` in the working directory. See [configuration.md](configuration.md).
+Credentials are resolved in this order: `--client-secret` → `YTSTATS_CLIENT_ID`/`YTSTATS_CLIENT_SECRET` → `YTSTATS_CREDENTIALS_FILE` → stored `credentials.json` → `client_secret*.json` in the working directory. See [configuration.md](configuration.md).
 
 Returns `{ channelId, channelTitle, customUrl, configDir }`.
 
@@ -106,9 +106,18 @@ Local removal happens even when revocation fails — being offline should not le
 ytstats status
 ```
 
-Reports who is signed in and where configuration lives. Takes no flags and needs no authentication.
+Reports who is signed in and where configuration lives. Takes no flags and needs no authentication. This is the "who am I" command.
 
-Returns `{ authenticated, configDir, credentialSource, accounts[], setupGuide? }`. Each account carries `channelId`, `channelTitle`, `customUrl`, `savedAt`, and `isDefault` — never token material. `setupGuide` appears only when no account is signed in.
+Returns `{ authenticated, configDir, credentialSource, clientId, accounts[], setupGuide? }`. Each account carries `channelId`, `channelTitle`, `customUrl`, `clientId`, `savedAt`, and `isDefault` — never token material. `setupGuide` appears only when no account is signed in.
+
+`credentialSource` says *where* the OAuth client came from (a path, `environment`, or `stored`); `clientId` says *which* client that turned out to be. Both are `null` when no credentials resolve. Client IDs are public by OAuth design — only the secret is sensitive — so neither field is redacted.
+
+Comparing the top-level `clientId` against an account's `clientId` tells you whether that channel's stored token was issued by the client currently resolving. A disagreement is what [`AUTH_CLIENT_MISMATCH`](output-contract.md#diagnostic-catalog) reports on the next authenticated command.
+
+```bash
+ytstats status 2>/dev/null | jq '{clientId, credentialSource}'
+ytstats status 2>/dev/null | jq -r '.data.accounts[] | select(.isDefault) | .channelTitle'
+```
 
 ### doctor
 

package/docs/configuration.md

@@ -17,6 +17,7 @@ source:
 | `YTSTATS_CONFIG_DIR` | `resolveConfigDir()` | Overrides the config directory entirely. Relative values are resolved to absolute against the working directory |
 | `YTSTATS_CLIENT_ID` | `resolveCredentials()` | OAuth client id. **Both** this and the secret must be set for the pair to be used |
 | `YTSTATS_CLIENT_SECRET` | `resolveCredentials()` | OAuth client secret |
+| `YTSTATS_CREDENTIALS_FILE` | `resolveCredentials()` | Path to the `client_secret` JSON Google issued. Same effect as `--client-secret`, without repeating the flag |
 | `XDG_CONFIG_HOME` | `resolveConfigDir()` | Linux/BSD config base. **Ignored when relative**, per the XDG spec |
 | `APPDATA` | `resolveConfigDir()` | Windows config base; falls back to `%USERPROFILE%\AppData\Roaming` |
 | `HTTPS_PROXY` | `googleapis` / Node | Standard proxy variable, named in the `NETWORK_UNREACHABLE` remediation |
@@ -70,6 +71,7 @@ The multi-account token store, keyed by channel id:
       "channelId": "UC…",
       "channelTitle": "…",
       "customUrl": "@…",
+      "clientId": "123456789012-abc.apps.googleusercontent.com",
       "tokens": { "access_token": "…", "refresh_token": "…", "expiry_date": 0 },
       "savedAt": "2026-07-27T10:00:00.000Z"
     }
@@ -77,6 +79,8 @@ The multi-account token store, keyed by channel id:
 }
 ```
 
+`clientId` records which OAuth client issued this account's refresh token. It is not a secret and is never used to authenticate — it exists so a later run can tell whether the credentials it resolved are the ones the token belongs to. Accounts written before the field existed have `null` and are treated as unknown, not as a mismatch.
+
 Deleted entirely when the last account is removed. See [auth.md](auth.md#token-storage) for how it is read and merged.
 
 ## Permissions and write discipline
@@ -94,16 +98,24 @@ These are plaintext files, the same approach `gcloud`, `gh`, and `aws` take. `yt
 
 ## CI and headless machines
 
-Supply the OAuth client through the environment instead of a file:
+Point at a mounted secret file:
 
 ```bash
-export YTSTATS_CLIENT_ID=123456789012-abc.apps.googleusercontent.com
-export YTSTATS_CLIENT_SECRET=GOCSPX-…
+export YTSTATS_CREDENTIALS_FILE=/run/secrets/ytstats-client.json
 export YTSTATS_CONFIG_DIR=$PWD/.ytstats     # if $HOME is not writable
 ytstats login --no-browser
 ```
 
-Both `YTSTATS_CLIENT_ID` and `YTSTATS_CLIENT_SECRET` must be set — one alone is ignored and resolution falls through to the next source.
+This is usually the cleanest option in CI, where the runner already mounts secrets as files: it takes the JSON Google issued as-is, with no step that extracts two fields out of it, and a path in the environment leaks less than a secret in the environment.
+
+The pair still works where the secret arrives as two variables:
+
+```bash
+export YTSTATS_CLIENT_ID=123456789012-abc.apps.googleusercontent.com
+export YTSTATS_CLIENT_SECRET=GOCSPX-…
+```
+
+Both must be set — one alone is ignored and resolution falls through to the next source.
 
 `--no-browser` prints the authorization URL and reads the pasted redirect back, so a machine with no browser can still complete the flow. The refresh token it produces is then reusable, provided the consent screen is published to Production — in Testing mode Google expires it after 7 days.
 
@@ -115,11 +127,35 @@ Ordered in `resolveCredentials()`; the first complete pair wins:
 
 1. `--client-secret <file>`
 2. `YTSTATS_CLIENT_ID` + `YTSTATS_CLIENT_SECRET` (both required)
-3. Stored `credentials.json`
-4. `client_secret*.json` auto-discovered in the working directory
+3. `YTSTATS_CREDENTIALS_FILE`
+4. Stored `credentials.json`
+5. `client_secret*.json` auto-discovered in the working directory
+
+The env pair is checked before the env path so that the path form changes nothing for anyone already exporting the pair. If both are set, the pair wins and `ytstats status` reports `credentialSource: environment` — which is how you catch a stale `YTSTATS_CLIENT_ID` shadowing the file you meant to use.
 
 Auto-discovery prefers an exact `client_secret.json`, otherwise takes the alphabetically first match so the same directory always resolves the same way. Full detail in [auth.md](auth.md#credential-resolution).
 
+## Running several OAuth clients side by side
+
+One config directory holds **one** OAuth client — `credentials.json` is a single record, not one per channel. `tokens.json` holds many channels, so the two only stay consistent if every channel in a directory was authorized with the same client.
+
+That is fine for the common case (one Google Cloud project, several of your own channels). It breaks when channels live under *different* projects — managing a client's channel with a client-issued OAuth client, for instance. Give each client its own directory:
+
+```bash
+alias yt-acme='YTSTATS_CONFIG_DIR=~/.ytstats/acme YTSTATS_CREDENTIALS_FILE=~/secrets/acme.json ytstats'
+alias yt-mine='YTSTATS_CONFIG_DIR=~/.ytstats/mine ytstats'
+```
+
+`YTSTATS_CONFIG_DIR` is what does the real work: it moves the credentials *and* the tokens together, so the two halves cannot drift apart. Setting only `YTSTATS_CREDENTIALS_FILE` while leaving the config directory shared pairs one client's id with another's tokens, which is exactly the state [`AUTH_CLIENT_MISMATCH`](output-contract.md#diagnostic-catalog) exists to catch.
+
+Per-directory rather than per-shell, with [direnv](https://direnv.net/):
+
+```bash
+# .envrc
+export YTSTATS_CONFIG_DIR="$PWD/.ytstats"
+export YTSTATS_CREDENTIALS_FILE="$HOME/secrets/acme.json"
+```
+
 ## Not committing credentials
 
 The repository's `.gitignore` excludes `client_secret*.json`, `credentials.json`, `tokens.json`, and `.env` — because a downloaded client secret can easily land in the working directory during testing, and auto-discovery means it will be picked up from there.

package/docs/gotchas/auth.md

@@ -82,6 +82,30 @@ The caller turns that `null` into `AUTH_ACCOUNT_UNKNOWN`, listing the channels t
 
 **Where handled:** `loadAccount()` in `src/auth/tokens.js`; the `AUTH_ACCOUNT_UNKNOWN` branch in `getAuthenticatedClient()`.
 
+## One config directory holds one OAuth client, but many channels
+
+`tokens.json` is keyed by channel and holds as many as you log into. `credentials.json` is a **single** record for the whole directory. The two structures disagree, and a second `ytstats login` with a different `client_secret` file silently overwrites the stored client while the first channel's tokens stay put.
+
+Google binds a refresh token to the client that issued it, so the next command for that first channel refreshes with the wrong client and Google answers `invalid_grant`. That maps to `AUTH_TOKEN_EXPIRED`, whose cause names a Testing-mode consent screen — so the user publishes their consent screen, which changes nothing, and is now further from the answer than when they started. A misdiagnosis is more expensive than an error.
+
+Only reachable with two Google Cloud projects; the ordinary case of several channels under one project is consistent. The fix for the multi-project case is a config directory per client, since `YTSTATS_CONFIG_DIR` moves credentials and tokens together.
+
+**Where handled:** `saveAccount()` in `src/auth/tokens.js` records `clientId` at login; the comparison in `getAuthenticatedClient()` (`src/auth/session.js`) throws `AUTH_CLIENT_MISMATCH` before the refresh can happen.
+
+## An absent client binding is unknown, not a mismatch
+
+The mismatch check runs only when `account.clientId` is set. Accounts written before that field existed have none, and treating absent as "does not match" would reject every pre-existing account on upgrade — logging out every user to protect against a problem most of them do not have.
+
+The same reasoning applies to the refresh write-back path: `client.on('tokens', …)` calls `saveAccount()` with a partial payload and no `clientId`, so `saveAccount()` falls back to the existing value rather than nulling it. Dropping it there would disarm the check after the first refresh, which is precisely when it is still needed.
+
+**Where handled:** the `account.clientId &&` guard in `getAuthenticatedClient()`; the `clientId ?? existing?.clientId ?? null` fallback in `saveAccount()`.
+
+## The account selector is checked before the client binding
+
+`getAuthenticatedClient()` resolves credentials, then the account, then the binding. An unknown `--account` is the more specific complaint, and reporting a client mismatch for a channel that is not signed in at all would misdirect exactly the way the ordering elsewhere in this file exists to prevent.
+
+**Where handled:** the order of the `loadAccount()` / `AUTH_ACCOUNT_UNKNOWN` block and the `AUTH_CLIENT_MISMATCH` block in `src/auth/session.js`.
+
 ## The loopback server binds 127.0.0.1, never 0.0.0.0
 
 Binding `0.0.0.0` would expose the callback listener — and therefore the authorization code — to anything on the local network. The server binds `127.0.0.1` on an ephemeral port (`server.listen(0, '127.0.0.1')`).

package/docs/output-contract.md

@@ -115,11 +115,12 @@ ytstats fetch 2>/dev/null | jq -r 'if .ok then "fine" else .nextSteps[0] end'
 
 | Code | Recoverable | Retryable | Meaning |
 |---|---|---|---|
-| `AUTH_NO_CREDENTIALS` | yes | no | No OAuth client found in any of the four sources |
+| `AUTH_NO_CREDENTIALS` | yes | no | No OAuth client found in any of the five sources |
 | `AUTH_NO_TOKENS` | yes | no | Client exists, but no channel has been authorized here |
 | `AUTH_TOKEN_EXPIRED` | yes | no | Refresh token rejected (`invalid_grant`) — usually the 7-day Testing trap |
 | `AUTH_TOKEN_REVOKED` | yes | no | Access explicitly revoked, by logout elsewhere or in Google account settings |
 | `AUTH_ACCOUNT_UNKNOWN` | yes | no | `--account` matched no signed-in channel |
+| `AUTH_CLIENT_MISMATCH` | yes | no | The channel's stored token was issued by a different OAuth client than the one resolved |
 | `AUTH_CONSENT_DECLINED` | yes | **yes** | Google returned `access_denied` — consent dismissed or a scope refused |
 | `AUTH_TIMEOUT` | yes | no | Callback never arrived; usually "Access blocked" in the browser |
 | `AUTH_CLIENT_ID_INVALID` | yes | no | Client ID does not end in `.apps.googleusercontent.com` |

package/docs/testing.md

@@ -8,7 +8,7 @@ source:
 
 # Testing
 
-316 tests across 13 files. **None of them requires network access**, and none opens a browser.
+332 tests across 13 files. **None of them requires network access**, and none opens a browser.
 
 ## Running
 
@@ -32,14 +32,14 @@ Nothing is mocked at the module level. Tests hand in plain objects, which means
 
 | File | Tests | Covers |
 |---|---|---|
-| `test/envelope.test.js` | 96 | Envelope shape, the diagnostic catalog, severity routing, `nextSteps`, redaction |
+| `test/envelope.test.js` | 98 | Envelope shape, the diagnostic catalog, severity routing, `nextSteps`, redaction |
 | `test/api/transforms.test.js` | 33 | Duration parsing, content classification, CSV, date normalization, row zipping |
 | `test/cli.e2e.test.js` | 30 | The real binary, spawned as a subprocess |
 | `test/api/fetchers.test.js` | 27 | Exact query parameters sent by every Data, Analytics, and Reporting fetcher |
-| `test/auth/credentials.test.js` | 20 | Resolution precedence, file shapes, service-account rejection, discovery |
+| `test/auth/credentials.test.js` | 25 | Resolution precedence across all five sources, file shapes, service-account rejection, discovery |
+| `test/auth/tokens.test.js` | 23 | Multi-account store, merging, the client binding, default promotion, legacy import |
+| `test/auth/session.test.js` | 22 | `login`, `logout`, `getAuthenticatedClient`, refresh persistence, client-mismatch detection |
 | `test/auth/oauth.test.js` | 18 | PKCE, auth URL construction, and the loopback server over real HTTP |
-| `test/auth/session.test.js` | 18 | `login`, `logout`, `getAuthenticatedClient`, refresh persistence |
-| `test/auth/tokens.test.js` | 18 | Multi-account store, merging, default promotion, legacy import |
 | `test/config/store.test.js` | 14 | Atomic writes, permissions, traversal rejection |
 | `test/fetch-all.test.js` | 13 | Orchestration, per-step degradation, fatal codes, retention capping |
 | `test/dates.test.js` | 11 | Window resolution, calendar validation, bounds |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ytstats",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pull your YouTube channel stats and analytics as JSON. Bring your own Google Cloud credentials, no server, no data leaves your machine.",
   "type": "module",
   "bin": {

package/src/auth/credentials.js

@@ -32,12 +32,12 @@ export function parseClientSecret(raw) {
   return { clientId, clientSecret };
 }
 
-function readClientSecretFile(file) {
+function readClientSecretFile(file, flag = '--client-secret') {
   let raw;
   try {
     raw = fs.readFileSync(file, 'utf-8');
   } catch {
-    throw fail(DIAGNOSTICS.AUTH_CREDENTIALS_NOT_FOUND, { value: file, flag: '--client-secret' });
+    throw fail(DIAGNOSTICS.AUTH_CREDENTIALS_NOT_FOUND, { value: file, flag });
   }
 
   let parsed;
@@ -137,8 +137,12 @@ export function clearCredentials() {
  * Precedence:
  *   1. --client-secret <file>
  *   2. YTSTATS_CLIENT_ID + YTSTATS_CLIENT_SECRET (both required)
- *   3. credentials.json saved by a previous `ytstats login`
- *   4. client_secret*.json auto-discovered in the working directory
+ *   3. YTSTATS_CREDENTIALS_FILE — a path to the JSON Google issued
+ *   4. credentials.json saved by a previous `ytstats login`
+ *   5. client_secret*.json auto-discovered in the working directory
+ *
+ * The env-var pair is checked before the env-var path so that adding the path
+ * form changes nothing for anyone already exporting the pair.
  *
  * Returns { clientId, clientSecret, source }. `source` is for display only and
  * never contains the secret.
@@ -156,6 +160,15 @@ export function resolveCredentials({ clientSecretPath, env = process.env, cwd =
     };
   }
 
+  // A path in the environment leaks less than a secret in the environment, and
+  // it points straight at the file Google hands out — no extracting two fields.
+  if (env.YTSTATS_CREDENTIALS_FILE) {
+    return {
+      ...readClientSecretFile(env.YTSTATS_CREDENTIALS_FILE, 'YTSTATS_CREDENTIALS_FILE'),
+      source: env.YTSTATS_CREDENTIALS_FILE,
+    };
+  }
+
   const stored = loadStoredCredentials();
   if (stored) {
     return { clientId: stored.clientId, clientSecret: stored.clientSecret, source: 'stored' };
@@ -167,6 +180,8 @@ export function resolveCredentials({ clientSecretPath, env = process.env, cwd =
   }
 
   throw fail(DIAGNOSTICS.AUTH_NO_CREDENTIALS, {
-    detail: `Searched: --client-secret, YTSTATS_CLIENT_ID/SECRET env vars, stored credentials, and client_secret*.json in ${cwd}`,
+    detail:
+      'Searched: --client-secret, YTSTATS_CLIENT_ID/SECRET env vars, YTSTATS_CREDENTIALS_FILE, ' +
+      `stored credentials, and client_secret*.json in ${cwd}`,
   });
 }

package/src/auth/session.js

@@ -76,6 +76,21 @@ export function getAuthenticatedClient({ account: selector, clientSecretPath, en
       detail: `OAuth client resolved from: ${credentials.source}`,
     });
   }
+
+  // Google binds a refresh token to the client that issued it, so a mismatch
+  // here fails at refresh time as invalid_grant — which maps to
+  // AUTH_TOKEN_EXPIRED and blames the consent screen. Diagnose it precisely
+  // instead. Accounts stored before clientId was recorded have none, and must
+  // keep working: only an actual disagreement is an error.
+  if (account.clientId && account.clientId !== credentials.clientId) {
+    throw fail(DIAGNOSTICS.AUTH_CLIENT_MISMATCH, {
+      account: account.channelTitle ?? account.channelId,
+      expected: account.clientId,
+      value: credentials.clientId,
+      detail: `Resolved from: ${credentials.source}`,
+    });
+  }
+
   const client = newClient(deps, credentials, 'http://127.0.0.1');
   client.setCredentials(account.tokens);
 
@@ -87,6 +102,7 @@ export function getAuthenticatedClient({ account: selector, clientSecretPath, en
         channelId: account.channelId,
         channelTitle: account.channelTitle,
         customUrl: account.customUrl,
+        clientId: account.clientId,
         tokens,
       });
     } catch {
@@ -153,6 +169,9 @@ export async function login({
     channelId: identity.channelId,
     channelTitle: identity.channelTitle,
     customUrl: identity.customUrl,
+    // Record which client issued this token, so a later run with different
+    // credentials resolved can say so precisely rather than failing at refresh.
+    clientId: credentials.clientId,
     tokens,
   });
 

package/src/auth/tokens.js

@@ -8,11 +8,16 @@ import { YtStatsError, ERROR_CODES } from '../errors.js';
  * {
  *   version: 1,
  *   default: "UC...",
- *   accounts: { "UC...": { channelId, channelTitle, customUrl, tokens, savedAt } }
+ *   accounts: { "UC...": { channelId, channelTitle, customUrl, clientId, tokens, savedAt } }
  * }
  *
  * Keyed by channel so one machine can hold several channels; `default` is what
  * commands use when --account is not given.
+ *
+ * `clientId` records which OAuth client issued this account's refresh token. It
+ * is not a secret, and it is not used to authenticate — it exists so that a
+ * later run can tell whether the credentials it resolved are the ones the token
+ * actually belongs to. Absent on accounts saved before this field existed.
  */
 function emptyStore() {
   return { version: 1, default: null, accounts: {} };
@@ -30,7 +35,7 @@ function write(store) {
 }
 
 /** Persist (or update) one channel's tokens. First account logged in wins the default. */
-export function saveAccount({ channelId, channelTitle, customUrl, tokens }) {
+export function saveAccount({ channelId, channelTitle, customUrl, clientId, tokens }) {
   if (!channelId) {
     throw new YtStatsError('Cannot save credentials without a channel id.', {
       code: ERROR_CODES.AUTH_FAILED,
@@ -44,6 +49,9 @@ export function saveAccount({ channelId, channelTitle, customUrl, tokens }) {
     channelId,
     channelTitle: channelTitle ?? existing?.channelTitle ?? null,
     customUrl: customUrl ?? existing?.customUrl ?? null,
+    // Falls back like the fields above: the refresh-token write-back path calls
+    // this without a clientId, and must not erase the binding recorded at login.
+    clientId: clientId ?? existing?.clientId ?? null,
     // A refresh happens without a new refresh_token; keep the one we already hold.
     tokens: { ...(existing?.tokens ?? {}), ...tokens },
     savedAt: new Date().toISOString(),
@@ -75,13 +83,14 @@ export function loadAccount(selector) {
   return match ?? null;
 }
 
-/** Accounts without token material — safe to print. */
+/** Accounts without token material — safe to print. A client ID is not a secret. */
 export function listAccounts() {
   const store = read();
   return Object.values(store.accounts).map(a => ({
     channelId: a.channelId,
     channelTitle: a.channelTitle,
     customUrl: a.customUrl,
+    clientId: a.clientId ?? null,
     savedAt: a.savedAt,
     isDefault: a.channelId === store.default,
   }));

package/src/cli.js

@@ -196,8 +196,14 @@ export function buildProgram(deps = {}) {
     .action(run('status', async () => {
       const accounts = listAccounts();
       let credentialSource = null;
+      let clientId = null;
       try {
-        credentialSource = resolveCredentials().source;
+        // A client ID is public by OAuth design — only the secret is sensitive —
+        // and with five resolution sources, "which one did it pick" is not
+        // answerable from the source label alone.
+        const credentials = resolveCredentials();
+        credentialSource = credentials.source;
+        clientId = credentials.clientId;
       } catch {
         // Not configured yet; reported as null below.
       }
@@ -205,6 +211,7 @@ export function buildProgram(deps = {}) {
         authenticated: accounts.length > 0,
         configDir: configDir(),
         credentialSource,
+        clientId,
         accounts,
         setupGuide: accounts.length === 0 ? SETUP_GUIDE : undefined,
       };

package/src/diagnostics.js

@@ -172,6 +172,41 @@ export const DIAGNOSTICS = {
     },
   }),
 
+  AUTH_CLIENT_MISMATCH: def({
+    code: 'AUTH_CLIENT_MISMATCH',
+    exitCode: EXIT.AUTH,
+    recoverable: true,
+    retryable: false,
+    title: 'Stored token belongs to a different OAuth client',
+    detail:
+      'This channel was authorized with one Google Cloud OAuth client, but a different client ID was ' +
+      'resolved for this run. Google binds a refresh token to the client that issued it, so refreshing ' +
+      'with the wrong client would fail as invalid_grant — which reads like an expired token and sends ' +
+      'you to fix the wrong thing.',
+    cause:
+      'Usually a second ytstats login with a different client_secret file overwrote the stored ' +
+      'credentials while another channel was still signed in, since credentials.json holds one client ' +
+      'for the whole config directory. Also reached by setting YTSTATS_CLIENT_ID/SECRET or ' +
+      'YTSTATS_CREDENTIALS_FILE to a different client than the one this channel was authorized with.',
+    remediation: {
+      summary:
+        'Give each OAuth client its own config directory, or re-authorize this channel with the client ' +
+        'that is now resolving.',
+      steps: [
+        'Run: ytstats status  — clientId shows what resolved, and each account shows the client it was authorized with.',
+        'To keep several clients side by side, isolate them: export YTSTATS_CONFIG_DIR=~/.ytstats/<name>',
+        'Point at that client\'s file in the same shell: export YTSTATS_CREDENTIALS_FILE=/path/to/client_secret.json',
+        'Or, to consolidate on the client that is resolving now, re-run: ytstats login',
+      ],
+      commands: [
+        STATUS_CMD,
+        { run: 'ytstats login', description: 'Re-authorize this channel with the client that is resolving now' },
+        DOCTOR_CMD,
+      ],
+      docs: [SETUP_DOC],
+    },
+  }),
+
   AUTH_CONSENT_DECLINED: def({
     code: 'AUTH_CONSENT_DECLINED',
     exitCode: EXIT.AUTH,