Login and Session
Where the unified login entry, OAuth callback, sessions, me, and logout sit in the downcity flow of @downcity/services.
The accounts service owns the shared account tables, better-auth runtime, OAuth callback, sessions, profiles, and City user_token issuance. Concrete login methods are provider-driven.
How to think about login entry points
Product login is a unified state machine:
providerslogin/startlogin/continuelogin/resultlogin/exchange
In a typical downcity flow, providers tells the frontend which login methods are actually enabled on the current City and whether each method uses the oauth or input flow. login/start creates a login attempt and returns the next step. login/continue submits input with the claim proof. POST login/result accepts login_id and login_secret and returns status only. POST login/exchange accepts that proof and a stable random exchange_id to deliver user_token. Keep the secret exclusively in the initiating client; send it in JSON bodies, never URLs, pages, or logs.
GET /v1/accounts/providers is a client-facing enabled list. Providers that are mounted in code but missing required env or runtime configuration are not returned. Use the Federation env catalog or admin workspace to discover what still needs to be configured.
The oauth flow returns an authorization URL from login/start. The input flow returns the current step inputs from login/start; email uses email/password. Local Account is also an input flow, but with an empty inputs array, and login/start immediately returns status: "done". In every case, obtain the token through login/exchange. Reuse the original exchange_id on transport retries; a different ID cannot claim the same result again.
OAuth supplies client_type, an exact redirect_uri, random state, and S256 PKCE. Website callbacks must match AccountsService trusted_web_callbacks; an empty list rejects web OAuth. CLI/Desktop use an exclusive local 127.0.0.1 ephemeral port. After validating callback state, exchange the authorization code, private verifier, login_secret, and stable exchange_id for a token. Status never delivers credentials.
The official accounts service can expose email, GitHub, Google, and WeChat Website App login depending on mounted providers and server-side configuration. The frontend should always trust providers instead of hardcoding login buttons.
If you want to actually wire up Google login next, continue with Google Login Setup.
If you want to actually wire up WeChat website login next, continue with WeChat Login Setup.
Device sessions, renewal, and logout
For client_type: "desktop" or "cli", login/exchange returns user_token, refresh_token, session_id, expires_at, and refresh_expires_at. Both timestamps use ISO 8601. Access credentials last 15 minutes; the refresh session expires after 90 days without renewal. Website login is held separately by the website BFF cookie.
Before sending a protected request, renew an access credential with less than one minute remaining:
const renewed = await guest.service("accounts").action("refresh").invoke({
refresh_token: saved_session.refresh_token,
refresh_id: saved_refresh_id,
});Generate a random refresh_id and persist it with the old credential before sending. Persist the complete successful response atomically. On a lost response, retry the same credential and ID: only the last rotation can be recovered, until that session expires or is revoked. A different ID cannot recover a consumed credential. Serialize renewal across processes to avoid overwriting each other's result. The service stores only refresh credential hashes.
A refresh 401 requires sign-in. Network failures and 5xx retain the saved credential and pending ID for retry. Never automatically replay model requests, payments, or other writes. A Federation client can use resolve_user_token(fetcher) to read the current credential before each authenticated request; the host owns renewal, storage, and coordination. City source views share this resolver.
GET /v1/accounts/me requires valid access credentials. Logout can use refresh credentials even if access has expired:
await user.account.logout(saved_session.refresh_token);Logout revokes the entire device session. Valid Bearer credentials can also revoke their own session through POST /v1/accounts/logout with an empty body. Protected requests check session revocation online; streams already running are not forcibly interrupted. SDK logout preserves credentials on transport failure. Desktop and CLI invalidate local shared credentials before remote revocation: offline sign-out ends local use, but an unavailable service cannot confirm remote revocation.
Why session still matters here
Even if the downcity mainly uses user_token to call City later, the account system still needs:
- better-auth auth tables
- a session table
- login-state facts
- downcity-facing profile data
That is why the service is not just "a few routes," but a minimal account infrastructure layer.
Mounting AccountsService does not make every login method available. Email login requires an email provider with a verification-email sender and completed email verification. OAuth login requires the matching provider and client credentials. OAuth identities are identified by provider and provider user ID; matching email addresses never silently merge accounts. Email conflicts require a verified linking or recovery flow.
What me returns now
GET /v1/accounts/me no longer returns only the runtime user. It also returns:
profile: downcity-facing display data such as display name and avatar
That keeps product clients and admin tools from reconstructing user state directly from auth rows.