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

[l2ysho]

Note

TL;DR — TBD

Stacked on #1431 (Stage-1, subtask 2). Base branch is claude/token-resolution-1418, not master.

What changed

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

{
  "version": 2,
  "activeProfile": "<userId>",
  "profiles": {
    "<userId>": {
      "username": "moria",
      "name": null,                    // reserved for `--profile <name>`
      "organizationOwnerUserId": "…",  // set => organization profile
      "authMethod": "token",           // reserved, device flow
      "expiresAt": null,               // reserved
      "hasRefreshToken": false         // reserved
    }
  },
  "secretsBackend": "keyring"
}

• Keyed by userId, not a display name. The key names the keyring entry in Secret storage v2 #1420, so a rename must never orphan a secret.
• Secrets keep their v1 location — the keyring, or top-level token/proxy.password on the file backend. Per-profile secret keys are Secret storage v2 #1420; putting them in the profile now would force a second migration.
• The reserved fields are written and never read. Leaving any of them out forces a v3 migration when the device flow lands.
• Fields nothing reads are dropped: email, plan, effectivePlatformFeatures, isPaying, createdAt, and proxy.groups. email is also gone from the AuthJSON type, where it was declared and never used.
• getLocalUserInfo() keeps its return shape, so its call sites are untouched.
• Writes are atomic — temp file plus rename, 0600. Two CLI processes can run at once. A read-modify-write pair still races and last write wins; that is accepted, not locked around.

Migration

Runs after ensureMigrated() as a separate step, so a keyring failure and a shape failure cannot mask each other. Idempotent, single-flight, and it never throws — a migration failure must not block a command.

State in the wild	auth.json	keyring	Result
A	plaintext secrets, no marker	empty	v2, secrets wherever ensureMigrated() put them
B	no secrets, marker keyring	token, proxy-password	v2, keyring untouched
C	plaintext secrets, marker file	empty	v2, secrets stay in the file

• The old file is backed up as auth.json.v1.bak, and an existing backup is never overwritten.
• A corrupt file is left alone rather than rewritten — readers already treat it as logged out, and 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 and the .bak are kept and the next command asks for a re-login; no key is invented.
• A file whose version is higher than 2 is refused with a clear error on read, and by both profile writers. No reverse migration.

Behavior worth calling out

• apify logout routes through the store instead of rimraf-ing the file. It drops the active profile and its plaintext secrets, and removes the file once no profile is left — same observable result today, and it does not need rewriting when auth switch arrives. It also removes auth.json.v1.bak, which would otherwise leave a plaintext token on disk after a logout.
• An older CLI keeps working on a v2 file — no downgrade break. Verified by hand against apify-cli@1.10.0 on the file backend: apify info printed the right username and user ID. It finds the top-level token, and its per-command auth.json refresh — the write feat: one token resolution order across every command #1431 removes — merges the user('me') response back in, restoring the flat id/username it needs. The file then carries both shapes and both CLIs read it. On the keyring backend the secretsBackend marker survives the migration, so the same path should hold; not verified, no keyring entry on the test machine. No downgrade release note needed.

Deviation from the issue

The issue specified that a dangling activeProfile should be "treated as logged out". It now throws a clear error naming the missing profile when a token is present, and reports logged out only when there is nothing to authenticate with. Returning {} while resolveAuth() still resolves the top-level token left ~9 commands building `${undefined}/${name}` and failing with a misleading Actor with name "x" was not found — and the adjacent "no activeProfile at all" state, which a user cannot tell apart, already threw. Only reachable from a hand-edited file; no writer produces it.

Verification

• pnpm run test:local — 634 passed, 4 skipped (63 files), up 3 from the base.
• pnpm run lint, pnpm run format, pnpm run build — clean.
• pnpm run update-docs — no change; no flag, arg, description, or registration moved.
• pnpm run test:api not run — no token in this environment. log_in_out.test.ts and info.test.ts asserted the v1 flat shape and could not have passed against a v2 file; both were updated, but only by reading, not by running.
• 16 new tests in test/local/lib/auth-file.test.ts: A/B/C on both backends, idempotency on an already-v2 file, the backup guard, the dropped fields, a corrupt file, a v1 file with no id, a dangling activeProfile, and a version: 3 file surviving both a login and a logout byte-for-byte.
• New test/__setup__/auth-file.ts helper. The test/local/ files that parsed auth.json by hand now read a profile through it or through getLocalUserInfo(), as do the two API tests that asserted the v1 shape.
• Install size unchanged — no dependency added or removed (package.json and pnpm-lock.yaml are identical to the base branch).

Requires Node ≥22 to run pnpm 11 locally.

Left out, deliberately

• No additive login, no --profile, no auth switch, no auth list. The file can hold N profiles; Stage-2 (Stage-2: Login - token multi account support #1386) puts a second one there. Figure out a better auth file structure for future extensibility #567's listing part is auth list, Stage-3 (Stage-3: Multi-account UX #1384).
• No per-profile keyring keys — that is Secret storage v2 #1420, and it needs the user IDs this change introduces.
• No proxy object in the profile. The password is a secret, and nothing reads proxy.groups.
• No lock around read-modify-write. Each write is atomic; a concurrent pair still ends in last-write-wins, as the issue accepted.
• Figure out a better auth file structure for future extensibility #567 is already closed, so this does not re-close it.

Closes #1419

🤖 Generated with Claude Code