# Design

## Context

See `proposal.md` — Why. After wave 1 the mall selects adapters per domain through `liveDomains` (`apps/mall/plugins/api.ts`); `auth`, `cart`, `orders`, `shipments` and `invoices` are what remain on fixed data.

Session truth today lives entirely in `localStorage`: `vmall.token` is read by the plugin's `getToken`, `vmall.user` is read by `middleware/auth.ts`, and both are written by `stores/session.ts`. The fixed-data `me()` returns a constant `MOCK_USER`, so nothing ever proves a stored token is still valid.

The live contract this wave targets (`apps/api/src/routes/auth.rs`):

| Endpoint | Behaviour |
|---|---|
| `POST /auth/register` | 400 on invalid email, password under 8 characters, or blank display name; **409** on duplicate email |
| `POST /auth/login` | **401** on bad credentials; returns `{ token, user }` |
| `GET /auth/me` | requires a bearer token; returns the `User` |

`ApiError` already carries `status` and `code` (`packages/shared/src/api.ts:26-34`).

## Goals / Non-Goals

**Goals:**
- Credentials, roles and tokens become the real user's, with failures reported distinctly.
- The flip stays confined to the `auth` domain, so every other domain keeps working.

**Non-Goals:**
- No refresh-token or cookie/session-server move: the JWT stays in `localStorage`.
- No password-reset backend; `/forgot-password` stays presentational, which is a known gap rather than something this wave fixes.
- No change to what the buyer center displays — its data is still fixed.

## Decisions

**1. Validate a restored token once per load through `me()`, and only clear the session on 401/403.**
`middleware/auth.ts` currently trusts `localStorage`, so a stale or forged token reaches protected pages and fails later, further from the cause. A single `me()` call on hydrate puts the check where the session is established.
*Alternatives:* a 401 interceptor inside the shared `request()` helper (touches all three apps — a shared-package change outside this wave); validating in every guarded page (one call per navigation).
A network failure is deliberately **not** treated as a rejected token, so an unreachable API does not silently log the shopper out.

**2. The 8-character rule lives in the panel and mirrors the API.**
The API is the authority; the client check exists only to avoid a pointless round trip and a generic error. Relaxing the API to accept 6 would weaken the backend and needs a change outside this wave.

**3. Errors are mapped on `ApiError.status`/`code`, never on message text.**
Matching the API's prose would break whenever its wording changes. New strings go in `apps/mall/locales-extra.ts`, because AGENTS.md reserves the shared locale bundle for contract changes.

**4. The register panel drops the verification-code field.**
It is a mandatory no-op: the button only starts a countdown, the value is never sent, and no endpoint issues a code. Keeping it would demand input the API never checks.

**5. `liveDomains` gains `auth`; rollback stays a one-string edit.**
The fixed-data adapter keeps serving auth, so removing the entry restores the previous behaviour with no data migration.

## Risks / Trade-offs

- [A 401 from a still-mocked domain could be mistaken for a session failure] → only `me()` drives validation; cart, orders and invoices stay fixed-data and never answer 401.
- [Validation adds a round trip before the session is usable] → it runs only when a stored token exists, and it replaces blind trust rather than adding a second source of truth.
- [The demo loses "any password works"] → intended and marked **BREAKING**; the seeded `customer@vmall.local` account still demonstrates sign-in.
- [The register panel becomes shorter than the backend's own validation] → the panel mirrors the API rule, and the API still enforces it independently.

## Migration Plan

1. Add `auth` to `liveDomains` and land the panel, session and middleware changes in the same commit, so no user can submit the old 6-character rule against the new API.
2. Verify against the running backend with the seeded customer, then a wrong password, then a tampered token.
3. Rollback: drop `auth` from `liveDomains`. The fixed-data adapter still serves the domain, and no stored data needs reverting.