bos-auth: 01 bos login — session + scoped FC key export, bos.config.json driven

[elliotBraem]

Sprout of #274 (v2 platform services spec). Ticket 01 of the gasless-auth sprint (frontier, parallel with #290).

What to build

bos login gives a human (or agent) a way to establish publish identity with zero keys on disk by default:

1. bos login (interactive): opens a wallet-approval popup (SIWN/NEP-413 browser flow at minimum), creates a session bound to the NEAR account, and persists a session handle under .bos/ (gitignored). Sessions are short-lived; the handle is re-verifiable server-side against nonce + recipient.
2. bos login --key: additionally mints/exports a function-access key scoped to the FastKV registry contract for headless use (CI and agents). This is the "AI agent signs with its own NEAR key" loop, preserved first-class.
3. bos.config.json is the single declarative surface: the config's account + extends chain picks the auth target; optional publish.auth = "session" | "key" selects the default credential kind. No auth state lives outside .bos/state.json-style local files mirrored by the config's declared account.

Acceptance criteria

• bos login gets a session binding the NEAR account without asking for a seed phrase or private key
• bos login --key produces a scoped function-call key that works when NEAR_PRIVATE_KEY is consumed by the existing publish path
• bos.config.json declares the auth contract (account, optional publish.auth), and a mismatched session is rejected with a clear error
• Sessions expire; re-login is non-destructive for an existing key
• Logout deletes both the handle and exported key

Blocked by

• none (frontier)

[elliotBraem]

Implemented on citynode fork branch feat/bos-login (uncommitted work-in-progress alongside earlier every-plugin build work on that branch).

What landed

bos login (session flow) — redesigned per sprint scoping: the auth target is the everything-dev auth plugin (Better Auth at the site origin), so login uses whatever the site offers — NEAR SIWN today, passkeys/social/email wherever the site enables them:

1. CLI binds a loopback callback server on 127.0.0.1 (ephemeral port), generates a one-time state nonce, and opens the browser at <site>/cli?state=…&port=…&account=…&device=…&expiresIn=….
2. The new /cli UI route (client-only, outside the auth-gated layout) shows the request ("the CLI on <device> is requesting a credential"), supports inline NEAR sign-in when no session exists, then mints a Better Auth API key (auth.apiKey.create, named after the device, default 90-day expiry) same-origin with the user's session cookie, and redirects to http://127.0.0.1:<port>/callback?key=…&keyId=…&state=…&account=….
3. The CLI validates the state nonce hand-to-hand, persists .bos/session.json (gitignored, 0600) with { credential: { apiKey, apiKeyId, accountId, siteUrl, createdAt, expiresAt }, publishKey }, and reports account mismatch as a warning when the site credential differs from bos.config.json account.

Why an API key rather than a raw session token: the session cookie is httpOnly so the browser can't hand it to the CLI; the api-key plugin is already installed (enableSessionForAPIKeys makes it usable across all surfaces via x-api-key), it is revocable in Settings → API keys, and it satisfies "re-verifiable server-side" through Better Auth's session middleware. This also makes the hosted-and-connected-from-local case work unchanged — the page lives in the same UI, auth is same-origin in dev and prod.

bos login --key — reuses the existing FC-key minting path (generateNearKeyPair + addFunctionCallAccessKey from near-cli-rs) through the new perspective scoped to the FastKV registry contract, then exports the minted pair to ~/.near-credentials/<network>/<account>.json (near-cli/near-kit compatible NEAR CLI credential format) so the existing publish path consumes it with zero changes. Recorded in .bos/session.json.

publish.auth config surface — added to BosConfigSchema/BosConfigInput (publish.auth = "session" | "key" | "custody", canonical order updated in merge.ts). The publish path enforces it: session requires a local .bos/session.json and rejects account mismatch with a clear error; custody rejects with a pointer to #291; explicit --private-key always preserves the CI/headless path.

bos logout — deletes the handle and the exported key file (removes the matching near-credentials credential only when the stored public key matches), and best-effort revokes the API key server-side (/api/auth/api-key/delete with x-api-key; on failure it warns the user to revoke manually).

Files

• packages/everything-dev/src/auth-session.ts — session handle persistence (0600 file)
• packages/everything-dev/src/auth-login.ts — loopback server, state nonce, browser open
• packages/everything-dev/src/contract.ts + contract.meta.ts + cli.ts — login/logout routes, flag metadata, output
• packages/everything-dev/src/plugin.ts — login/logout handlers, site-URL resolution, key export, revoke
• packages/everything-dev/src/types.ts / merge.ts — publish.auth surface
• packages/everything-dev/src/publish.ts — auth-kind guard
• packages/everything-dev/src/near-cli.ts — addFunctionCallAccessKey accepts an externally supplied keypair
• ui/src/routes/_layout/cli.tsx — login-handoff page
• Tests: tests/unit/auth-session.test.ts, tests/unit/publish-auth-guard.test.ts

Verification

• bun lint clean; bun typecheck all 8 workspaces pass; everything-dev suite 436 passed / 2 skipped (pre-existing skips).
• Acceptance criteria: session ✅ (no seed phrase/keys), --key produces a scoped FC key consumed by the existing publish path ✅, config declares the auth contract with clear mismatch errors ✅, re-login is non-destructive ✅, logout deletes handle + exported key ✅.

[elliotBraem]

Follow-up: the CLI login handshake now routes through the standard /login page instead of doing inline sign-in on /cli.

• New unauthenticated visitors to /cli (session or delegate mode) are redirected to /login?redirect=/cli?… via a typed <Navigate>; after sign-in the login page navigates back with the full query intact, so the mint/approve step resumes exactly where the CLI left off.
• Enabled by adopting TanStack Router's canonical redirect-back pattern in _anon/login.tsx: sanitizeRedirect in validateSearch (drops open-redirect vectors), throw redirect({ to: search.redirect }) in beforeLoad, and navigate({ to: search.redirect }) on success — no more search-param stripping on the way in, and no window.location (the only remaining location.href assignment is the cross-origin loopback handoff to 127.0.0.1, which is outside the router).
• _authenticated and _admin guards now store a relative location.pathname + location.search as the redirect (the old absolute location.href value was silently rejected by same-origin sanitization and fell back to /dashboard, losing return-targets with query strings — also fixed).