[l2ysho]

Note

TL;DR

• auth.json prepared for multiple accounts -> old shape migrated to new profiles shape (userID keys)
• seamless for user, no change in flow, still one account in auth.json (in a profiles structure)
• token attribute will be migrate in followup with token in keyring (same for proxy password)
• testing -> APIFY_DISABLE_KEYRING=1 + usual scenarios (all combinations of old / new shape of auth.js and logged in / logged out user, all seems to be fine)
• no backup file: nothing read it and it could not restore a login
• a downgrade needs apify login again — see the release note below

Part of #1383 (Stage-1). Closes #1419.

What changed

New src/lib/auth-file.ts owns the file — reading, an atomic write, the migration, and the profile accessors. credentials.ts, login, logout, getLocalUserInfo() and the rental-sunset notice all go through it. No caller parses auth.json by hand any more.

{
  "version": 2,
  "activeProfile": "<userId>",
  "profiles": { "<userId>": { "username": "moria", "name": null, ... } },
  "secretsBackend": "keyring"
}

• Keyed by user ID, not username. Secret storage v2 #1420 names the keyring entry after that key, and usernames are mutable — a rename would strand a live token in the OS keyring with no in-CLI way to find or delete it.
• Secrets keep their v1 location — the keyring, or top-level token/proxy.password on the file backend. Secret storage v2 #1420 moves both backends together, because downgradeBackendToFile() can flip mid-process and a half-moved scheme loses a token.
• Reserved fields (name, authMethod, expiresAt, hasRefreshToken, loggedInAt, per-profile secretsBackend) are written and never read, so the device flow and Secret storage v2 #1420 need no extra format change. loggedInAt is recorded from the start because auth list will order by it and a logout will fall back to the most recent profile left — neither can backfill a time nobody wrote down.
• Dropped: email, plan, effectivePlatformFeatures, isPaying, createdAt, proxy.groups. Checked all 19 call sites — no readers. email also leaves the AuthJSON type.
• getLocalUserInfo() keeps its return shape, so its call sites are untouched.
• Writes are atomic — temp file plus rename, 0600. That also repairs a legacy 0644 auth.json, which the old in-place write never did.

Migration

A version-step chain, so moving data between shapes later means adding a table entry rather than reworking the module. Runs after ensureMigrated(), is single-flight, and never throws — a failure leaves the old shape, which the readers still understand, and says so once.

State	auth.json	keyring
A	plaintext secrets, no marker	empty
B	no secrets, marker keyring	token, proxy password
C	plaintext secrets, marker file	empty

• A corrupt file is left byte-for-byte alone. Readers already treat it as logged out; rewriting would destroy what is still recoverable by hand.
• A v1 file with a token but no id has no key to store a profile under. The secrets stay and the next command asks for a re-login; no key is invented.
• A file from a newer CLI is refused with an error that names apify logout as the way out.

Behavior worth calling out

• apify logout routes through the store instead of rimraf. It drops the active profile and its secrets, removes the backup, and never refuses — it is the only escape from a file this CLI cannot read, so a shape it does not understand is discarded whole rather than edited.

• The version guard runs on the stored-login path only. A platform run or CI job has APIFY_TOKEN as its only credential and no interest in the stored file; checking it first would stop apify run over a file it never reads.

• A downgrade needs a release note. An older CLI is not fully compatible with a v2 file, verified against 1.10.0:

  • apify info and other commands that call the API first work — the per-command refresh re-adds the flat id/username the old code reads.
  • apify run throws Stale credentials found without user metadata on a freshly migrated file. It reads the local file without that refresh, and a v2 file has no flat id/username until some other command puts them back.
  • apify login mixes two accounts. 1.10.0 merges into the existing file rather than replacing it, so activeProfile and profiles keep the old account while the flat fields and the token become the new one. This CLI then shows one account and authenticates as the other.

  Release note: after upgrading, run apify login again before using an older CLI against the same machine.

Verification

• pnpm run test:local — 665 passed, 4 skipped, up 12 from master.
• pnpm run lint, pnpm run format, pnpm run build — clean.
• pnpm run update-docs — no diff; no flag, arg, description or registration moved.
• CI green on 36a7004d, including API Tests and Windows on Node 22 and 24.
• Manual, against a real account: v1 → v2 on a genuine pre-profile file, both backends, apify run injecting the right identity, actors ls against the API, the installed CLI reading the migrated file, and logout clearing both files.
• New test/local/lib/auth-file.test.ts covers states A/B/C on both backends, idempotency, the backup contents and mode, a corrupt file, a v1 file with no id, a dangling activeProfile, a version: 3 file surviving a login and discarded by a logout, and the migration's failure path.
• Install size unchanged — no dependency added or removed.

Left out, deliberately

• No additive login, no --profile, no auth switch/list. The file can hold N profiles; Stage-2 (Stage-2: Login - token multi account support #1386) puts a second one there, Stage-3 (Stage-3: Multi-account UX #1384) adds the commands.
• No per-profile secret keys — Secret storage v2 #1420, which needs the user IDs this change introduces.
• No lock around read-modify-write. Each write is atomic; a concurrent pair still ends last-write-wins, as auth.json v2 #1419 accepted.

🤖 Generated with Claude Code

[DaveHanns]

Good job 🚀

I have also let Claude go through the PR and it found few nits. Feel free to ignore.

Should be addressed

• PR body vs #1383: the body says an old CLI reads the v2 file and no release note is needed. Not quite. 1.10.0 login on a v2 file leaves activeProfile pointing at the old account while the token is the new one, and 1.10.0 run throws on a fresh v2 file until an API command rewrites the flat fields. Either mirror flat id/username on v2 writes, or add the release note.
• auth.json.v1.bak: nothing reads it, it can't restore a login without secrets, it keeps email, and a 1.10.0 logout orphans it. Drop it or document what it's for.
• logout.ts:31-33: removeActiveProfile never refuses, so the comment is wrong. The order also flipped to file-first, and #1420 needs keyring-first. Keep the original order.

Nits

• auth-file.ts:19-32: reserved fields are required but never read. Make them optional. Body says per-profile secretsBackend is written; it isn't.
• auth-file.ts:94-106: third copy of temp-plus-rename. Lift into files.ts, can be a follow-up.
• auth-file.ts:177, credentials.ts:253: typeof version === 'number' treats a string "2" as v1 and drops profiles.
• auth-file.ts:231: drop the useRentalSunsetNotice reference, the hook already explains it.
• auth-file.ts:256-261, auth.ts:195: "drops the previous secrets" is true on the file backend only. On keyring the old token lives until setToken overwrites it.
• auth-file.ts:267, 306-307: rmSync ignores maxRetries/retryDelay without recursive: true.
• types.ts:3: AuthJSON is now the resolved view, not the file. Doc comment for now. gitSource.ts:100 "as auth.json records it" is stale.
• auth-file.test.ts:291, 328: duplicate describe('replacing the stored account').
• auth-file.test.ts:183: fails as root. Add process.getuid?.() === 0 to the skip.
• auth-file.test.ts:180: comment describes review history, not the test.
• credentials.test.ts:40: authFileWrites() also counts .v1.bak.tmp-* writes.