Feature guide

Identity and access

Accounts, sessions, password reset, email verification, Google sign-in, roles, trusted origins, and rate limits.

← Technical overview

What this domain owns

Who the caller is and what role/session is available. Feature access itself belongs to entitlements.

Feature flow diagram

Sign-in / sign-up form
        │
        v
/api/auth/* ──> schema + rate limit + trusted origin
        │
        v
Identity service ──> account store
        │
        v
Set-Cookie session ──> app shell refreshes session and roles

This diagram shows the normal direction of control and data. Follow it before changing a boundary or adding a dependency.

Class and relationship diagram

┌───────────────┐ calls ┌────────────────────┐ uses ┌───────────────────────┐
│ Auth route    │──────▶│ identityAccess     │─────▶│ LegacyIdentityService │
└───────────────┘       ├────────────────────┤      ├───────────────────────┤
                        │ + signIn.execute() │      │ + signUp()            │
                        │ + registerUser     │      │ + signIn()            │
                        │ + signOut          │      │ + verifyEmail()       │
                        └─────────┬──────────┘      └───────────┬───────────┘
                                  ▼                             ▼
                          ┌───────────────┐             ┌───────────────┐
                          │ Rate limit    │             │ Auth helpers  │
                          └───────────────┘             │ + session     │
                                                        └───────────────┘

Boxes show the important data types or services. Their fields and main methods are listed inside; arrows show the primary dependency or data relationship.

Sequence diagram

Learner
Auth route
Security
Identity use case
Identity service
Auth helpers
Browser
submit credentials
check origin + rate limit
request allowed
execute validated action
verify account/credential
create session
session token
auth result
return Set-Cookie + typed outcome

Read this from top to bottom: each arrow is the next interaction in the normal successful path.

Start here in the code

Choose any filename to open it directly in VS Code.

How it works

  1. A form calls an auth route.
  2. The route validates input and applies rate limits.
  3. Identity service creates or reads an account/session.
  4. The response sets/refreshes the session cookie.
  5. The app shell refreshes session-dependent UI.

Read this code

app/api/auth/signin/route.tsOpen in VS Code — Authenticate at the server boundary

const body = signInSchema.parse(await request.json());
await assertTrustedOrigin(request);
await rateLimit(request, 'signin');

const session = await identity.signIn(body);
return sessionResponse(session);

What each part is doing

  1. Parse untrusted request data before using it.
  2. Origin and rate-limit checks happen before a password is checked.
  3. Only the server creates the session response and its cookie.

This is a deliberately short excerpt of the real pattern, with unrelated details omitted. Read the named file for the complete implementation.

Related API and server boundaries

  • /api/auth/signup
  • /api/auth/signin
  • /api/auth/session
  • /api/auth/signout
  • /api/auth/reset-password
  • /api/auth/roles

Tests to read and run

Implementation notes

This is the home for detailed explanations, decision records, request examples, and diagrams for this feature. Add new feature-specific documentation here instead of expanding the platform overview.