Account Login

Start, continue, inspect, and close a Federation user session.

Account operations live under federation.user.account.

const providers = await federation.user.account.providers();

const login = await federation.user.account.login({
  provider: "email",
  client_type: "cli",
  input: {
    email: "[email protected]",
    password: "password",
  },
});

Email login requires completed email verification. For multi-step providers, use login_start() and continue(); the same account accessor retains the initiating proof. status() only queries status. After completion, exchange() obtains and stores the User Token, retaining a stable exchange ID across transport retries. login() handles the exchange automatically.

GitHub, Google, and WeChat OAuth return automatically to the initiating product after provider authentication. Every OAuth start supplies redirect_uri, random state, code_challenge, and code_challenge_method: "S256". The product validates callback state, then exchanges authorization_code, code_verifier, and its private initiating proof. status() never delivers authorization codes or tokens. Never put the login secret or verifier in URLs or logs.

CLI and Desktop use a host-managed loopback receiver. Import create_loopback_login_callback from @downcity/federation/node; this Node-only entry point listens on 127.0.0.1 at a random unprivileged port and validates the random callback path, Host, and state. Pass its parameters to login_start() with client_type: "cli" or "desktop", open the returned URL in the local system browser, and call exchange({ authorization_code: callback.authorization_code, code_verifier: callback.code_verifier }) after receiving the callback. Release the listener on cancellation, timeout, or window close. Keep proofs in the host process. The CLI requires a local browser; remote or headless OAuth sign-in is unsupported.

The local browser callback page displays “Authorization received” and asks the user to return to Downcity. This confirms receipt of the authorization code; sign-in completes in the application after token exchange and account storage. The page follows the browser’s English or Chinese language preference and the system’s light or dark appearance. Invalid or expired callback responses ask the user to start signing in again from Downcity. The page can be closed manually and does not redirect or close itself.

For host-managed login() orchestration, on_authorize: async (url) => ({ authorization_code, code_verifier }) opens the browser, waits for a validated callback, and returns the exchange proof. Cross-page websites use login_start() and exchange() in their BFF instead.

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.

Use exchange({ exchange_id }) to specify a securely retained exchange ID and reuse it on transport retries.

Federation validates signature, issuer, audience, expiry, and session revocation for protected requests. Device logout revokes its entire session. SDK logout preserves credentials on transport failure; Desktop and CLI end local use before attempting remote revocation. Running streams are not forcibly interrupted.

After login, use the same federation.user object for current(), AI, payment, and Services.

Renewable device credentials

Desktop and CLI login results include refresh_token, session_id, expires_at, and refresh_expires_at alongside user_token. Persist the full response privately. Access credentials last 15 minutes; successful refresh extends the 90-day idle deadline. The SDK keeps the current access token in memory; your host owns durable renewal and cross-process coordination.

Bind federation.user.set_token_resolver(read_current_access_token) or constructor option resolve_user_token to an asynchronous function receiving the client's fetcher and returning the latest token for this fixed session. It runs before each authenticated request, including City source views. Renew before expiry, persist a stable refresh_id before sending, and save the complete rotated response atomically. Network failures preserve the pending request; a refresh 401 requires sign-in. Business requests are never automatically replayed after a 401.

The resolver can supply authentication on its own; an initial user_token is optional. current(), Services, AI, payment, and City source views all resolve credentials before sending requests. An empty token or resolver failure stops the request without falling back to a saved token.

const federation = new Federation({
  url: federation_url,
  resolve_user_token: read_current_access_token,
});
const current_user = await federation.user.current();

Call await federation.user.account.logout(saved_session.refresh_token) to revoke even when access has expired. See Login and Session for the HTTP protocol and recovery rules.