Description
Session Authentication and Company Selection connect a verified hosted identity to the correct company-scoped Dots principal. The browser supports sign-in, sign-up, password recovery, logout, and guarded application boot. Once authenticated, the session provider calls the server’s identity endpoint to hydrate memberships, the active company, effective permissions, Dotabase grants, and entitled capabilities rather than deriving authority in the client.
For people belonging to multiple companies, the active-company selector persists a chosen membership and sends it on company-scoped requests. The server accepts that selector only when it names one of the authenticated user’s memberships; otherwise resolution fails closed instead of redirecting to another tenant. If no explicit choice is present, credential binding and home-company rules provide the documented fallback.
Selling Points
- Gives users a complete authentication lifecycle instead of requiring static API keys or a localhost-only identity.
- Resolves permissions on the server at session hydration, preventing the browser from recreating security algebra.
- Supports one identity across multiple company memberships with an explicit active-company context.
- Rejects selectors for non-membership companies, protecting tenant boundaries during switching and deep links.
- Keeps returning sessions responsive through persisted safe snapshots followed by authoritative revalidation.
User Story
A consultant signs in once and sees memberships for two client companies. They select the second company, and the app refreshes with that workspace’s navigation, permissions, and Dotabase grants. When they later return, the selection is restored and revalidated. They walk away with convenient multi-company access without credentials or data crossing between the two tenants.
Extension Surface
This capability is fixed_core. Identity verification and actor resolution are security boundaries implemented in packages/api/src/auth/resolve-actor.ts and hydrated by apps/web/src/lib/session/SessionProvider.tsx. The active-company behavior in apps/web/src/lib/active-company/active-company-store.ts exposes application state, but there is no supported external identity-provider or tenant-resolution plugin contract.
Capabilities & Limits
- Supports hosted sign-in, sign-up, recovery, logout, and authenticated route gating.
- Hydrates memberships, effective permissions, grants, and capabilities from the server.
- Persists and validates active-company selection across memberships.
- A company selector cannot grant membership or override credential-bound tenancy.
- Email delivery and broader cloud-hosting concerns are operational dependencies outside this feature’s authority model.
Implementation Map
packages/api/src/routes/auth.tspackages/api/src/auth/resolve-actor.tsapps/web/src/lib/session/SessionProvider.tsxapps/web/src/lib/active-company/active-company-store.tsapps/web/src/modules/access/LoginPage.tsx