docs: define registration token state

2026-07-10 16:17:56 +08:00
parent 6129a9221a
commit 5d195cda45
1 changed files with 29 additions and 0 deletions
@@ -0,0 +1,29 @@
+# Registration Token State Design
+
+## Status
+
+Pending written-spec review.
+
+## Goal
+
+Registration creates an account but never creates or retains a browser login state. Only a successful password login or SMS login may persist an authentication token.
+
+## Contract Owner
+
+`utils/ApiClient.js` owns browser token persistence. Pages invoke API methods and redirect according to their existing form configuration; they do not read, write, or clear the token directly.
+
+## Required Behavior
+
+1. `login()` and `loginBySms()` persist the token returned by their successful responses under `genealogy_auth_token`.
+2. `register()` posts the existing registration request unchanged and returns its response unchanged.
+3. After a successful `register()` response, `register()` clears `genealogy_auth_token`. This applies even when the response includes `token`, `accessToken`, or `tokenValue`.
+4. If `register()` fails, token storage is not changed.
+5. `register.html` continues redirecting to `login.html` after `register()` resolves.
+
+## Scope
+
+This change does not add a profile-page login guard, 401 redirect handling, or logout UI. Those are separate authentication-lifecycle steps that must consume the same `ApiClient` token contract.
+
+## Verification
+
+The API-client tests must prove that successful registration removes a previously stored token and does not store a token returned by registration. They must also retain coverage showing password and SMS login still store their returned tokens.