feat: auth.json v2 with profiles keyed by user ID

[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)
• auth.js backup in auth.json.v1.bak, removed after logout
• old CLI can work with v2 auth shape if rollback needed

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

• The old file is snapshotted to auth.json.v1.bak, without the secrets — it is written once and never refreshed, so a rotated token copied there would outlive the account it belongs to. A login or a logout removes it, for the same reason.
• 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.
• An older CLI keeps working on a v2 file. Verified against apify-cli@1.10.0: it finds the token and its per-command refresh re-adds the flat id/username, so the file carries both shapes and both CLIs read it. No downgrade release note needed.

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