rama/halobestie-clone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 4 §2.1: anonymous → existing-user merge breadcrumb

Browse Source 
Adds `customers.account_belongs_to UUID NULL` and refactors customer
sign-in (phone/Google/Apple) so an anon row that re-verifies into an
existing customer no longer 409s. Instead the anon row stays intact
with a breadcrumb pointing at the real customer; tokens are issued
for the existing user. Actual data reconciliation onto the existing
row (chat_sessions, customer_transactions, payment_sessions,
pairing_failures) is deferred.

Backend
- migrate.js: ADD COLUMN account_belongs_to UUID REFERENCES customers(id)
  ON DELETE SET NULL.
- customer.service.js: stampAccountBelongsTo helper; account_belongs_to
  exposed in CUSTOMER_SELECT.
- auth.service.js: new shared resolveCustomerForIdentity (4-case logic);
  normalizeIdentityConflict + IDENTITY_ALREADY_LINKED 409 deleted;
  completeCustomerPhoneSignIn / signInWithGoogle / signInWithApple all
  route through the shared helper.
- client.auth.routes.js: new resolveAnonymousCustomerId picks the anon
  prefix ONLY from a verified Bearer JWT — closes the UUID-leak attack
  where a tamper-able body field could mis-route someone else's
  transactions. /otp/verify, /google, /apple all use it; the body field
  `anonymous_customer_id` is no longer accepted on any of them.
- test/services/auth.service.test.js: 9 Vitest cases covering phone +
  Google + Apple, all 4 logic cases + multi-merge accumulation.

Customer app
- auth_notifier.dart::verifyOtp: drop `skipAuth: true` and the dead
  body field so ApiClient auto-attaches the anon's Bearer from
  AuthBridge. Survives the AuthOtpSentData state transition (the
  earlier `_currentAnonymousCustomerId()` state-drop bug is bypassed by
  sourcing the id from the bridge instead of state).
- Google + Apple client paths remain unchanged (gated on provider
  creds; mirror this fix when wiring lands).

Docs
- flow_customer.mermaid.md: new §2.1 sub-section with the merge
  diagram, schema note, replaces-current-behaviour paragraph, and
  Bearer-only security callout.
- phase3.4-testing.md: §1.5 line 76 simplified (no more per-path
  split); new §1.5.1 with the 5-step operator scenario + DB invariants
  + curl recipe + Vitest pointer; new §1.5.2 covering Google/Apple
  parity (deferred client work flagged).

Verification (against live dev backend, before this commit):
- Vitest: 9/9 in auth.service.test.js; 49/51 overall (2 unrelated
  pre-existing failures in session-timer.service.test.js).
- Operator Node smoke: 14/14 in the §1.5.1 scenario; 11/11 in the
  Bearer-precedence cases.
- Real-device UI walkthrough on SM-A530F still pending — see resume
  memory `project_phase4_2_1_resume_test`.

Sister WIP bundled in migrate.js + customer.service.js: `usp_seen`
column + `markCustomerUspSeen` helper (Phase 4 USP one-time gate, was
already uncommitted in the working tree).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
ramadhan sjamsani
2026-05-13 23:57:53 +08:00
parent 22b10c4bbf
commit a48f108fc0
8 changed files with 596 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
requirement/flow_customer.mermaid.md
View File

@@ -131,6 +131,91 @@ flowchart TD
> exists (see Phase 1 auto-link via phone); the app-side reconciliation +
> `has_transacted` plumbing is the new work.
### 2.1 Anonymous → existing-user merge (post-transaction OTP) 🔴
> **Concern:** a real user can accidentally transact as anonymous (skipped
> login, picked "tanpa verifikasi", or reopened the app after logout) and
> only later verify their phone. If that phone already belongs to another
> customer row in our DB, the anonymous customer's transactions live under
> a separate, unreachable identity — a data gap where the same human shows
> up as two distinct customers. The flow must capture this transition so
> the orphan can be reconciled with the real account later.
```mermaid
flowchart TD
Open["Open app · fresh install or post-logout"] --> Transact["Anonymous transact(s) under Anon-row · S2→S6→…→S10→close"]
Transact --> More{"more sessions?"}
More -->|"yes"| Transact
More -->|"no · verify phone"| OTP["S3a/S3b OTP"]
OTP -->|"OTP ok"| PhoneLookup{"phone exists in customers?"}
PhoneLookup -->|"5.1 · new phone"| AnonUpgrade["Upgrade Anon-row in place<br/>(set phone, preserve display_name<br/>+ has_transacted + history) 🔴"]
AnonUpgrade --> Continue["Resume verified flow as same id"]
PhoneLookup -->|"5.2 · existing user"| StampBelongsTo["5.2.1 · stamp Anon.account_belongs_to = Existing.id<br/>(keep Anon row + its chat_sessions/transactions intact) 🔴"]
StampBelongsTo --> ReloginAs["5.2.2 · issue tokens for Existing.id<br/>app re-logs in as Existing 🔴"]
ReloginAs --> Continue
classDef partial fill:#fff7e6,stroke:#d4a017
class StampBelongsTo,ReloginAs,AnonUpgrade partial
```
> **Schema (new):** add a nullable self-FK on the customers table:
> `account_belongs_to UUID NULL REFERENCES customers(id)`. This points from
> an orphaned anon row → the real account it should be merged into. The
> column is *just the breadcrumb* — actually moving `chat_sessions`,
> `customer_transactions`, `payment_sessions`, `pairing_failures` onto the
> real account is a separate reconciliation step deferred to a later
> phase. Keeping the anon row intact (rather than deleting it) preserves
> the historical record and lets reconciliation be replayed/audited.
> **Flow:**
> 1. User opens the app (fresh install or after logout).
> 2. User taps "aku mau curhat" and proceeds through S2 Nama → VerifChoice.
> 3. User picks "tanpa verifikasi" (anonymous path).
> 4. One or more anonymous transactions complete and close.
> 5. User later opts to verify phone (S3a/S3b OTP). Backend looks up phone:
> - **5.1 · phone not found** → upgrade the active anon row in place:
> set `phone`, keep `display_name`, `has_transacted`, `usp_seen`. The
> same customer id continues; all prior anonymous transactions are
> now attached to the verified identity automatically.
> - **5.2 · phone exists (Existing-row)** →
> - **5.2.1** stamp `account_belongs_to = Existing.id` on the active
> anon row. The anon row is **not** deleted; its
> `chat_sessions`/`customer_transactions` FKs stay valid.
> - **5.2.2** issue tokens for `Existing.id` and re-login the app as
> that user — the app should treat this like a normal returning
> verified session (overwrites local call_sign per mermaid §2
> line 62; honors `has_transacted` to skip S6 paywall).
> **Replaces current behaviour:**
> The legacy `normalizeIdentityConflict` helper threw `IDENTITY_ALREADY_LINKED`
> (409) for case 5.2 across all three identity paths (phone/Google/Apple).
> It has been deleted; the new shared `resolveCustomerForIdentity`
> ([auth.service.js](../backend/src/services/auth.service.js)) implements the
> 4-case merge logic uniformly. The customer app currently only exercises
> the phone-OTP path, but Google and Apple behave identically once their
> credentials land.
> **Auth source for the anon id (security):** the backend identifies the
> anon row to stamp **only** from a verified Bearer JWT presented as
> `Authorization: Bearer <token>` on `/otp/verify`. The earlier body field
> `anonymous_customer_id` is no longer read — accepting it would let anyone
> who learns a victim's anon UUID mis-route their transactions. Bearer
> tokens are HS256-signed with `AUTH_JWT_SECRET` and unforgeable. See
> `resolveAnonymousCustomerId` in
> [client.auth.routes.js](../backend/src/routes/public/client.auth.routes.js).
> Client implication: on the verified-OTP path the app must carry the
> anonymous session's access token through `requestOtp` → `verifyOtp` (today
> the client uses `skipAuth: true` and drops the bridge token — needs to be
> fixed alongside the `AuthOtpSentData` carry-through bug, which is the
> "real account verification implementation" tracked separately).
> **Note on multi-merge:** if a user does this dance repeatedly across
> installs/logouts, multiple anon rows can accumulate, each pointing at the
> same `account_belongs_to`. That's fine — reconciliation later walks the
> set; treat `account_belongs_to` as many-to-one.
---
## 3. Pre-pairing → Searching → Match (shared)

107
requirement/phase3.4-testing.md
View File

@@ -73,9 +73,114 @@ Related docs: [phase3.4.md](./phase3.4.md), [phase3.4-plan.md](./phase3.4-plan.m
- [ ] **[BE]** OTP verify with `anonymous_customer_id` → upgrades SAME customer row; customer UUID unchanged; display_name preserved
- [ ] **[BE]** Google verify with `anonymous_customer_id` → upgrades SAME customer row; google_sub added; display_name preserved if present, else backfilled from Google profile
- [ ] **[BE]** Apple verify with `anonymous_customer_id` → upgrades SAME row
- [ ] **[BE]** Upgrade with `anonymous_customer_id` when identity is ALREADY taken by a different customer → 409 `IDENTITY_CONFLICT` (anonymous row is NOT deleted)
- [ ] **[BE]** Upgrade with `anonymous_customer_id` when identity is ALREADY taken by a different customer → 200 with merge breadcrumb (see §1.5.1 below). Applies uniformly to phone, Google, and Apple paths (Phase 4 §2.1).
- [ ] **[BE]** Upgrade issues a NEW auth_sessions row. Old anonymous refresh still works (separate session) and reflects the upgraded profile on subsequent calls — **intentional for multi-device UX; do not "fix" without discussion**
### 1.5.1 Backend: Anonymous → existing-user merge breadcrumb (Phase 4 §2.1)
End-to-end scenario where a verified user accidentally transacts as anonymous on a fresh install, then re-verifies the same phone. The flow must NOT 409 and must stamp the breadcrumb on the anonymous row so reconciliation can move its transactions onto the real account later. Spec: [flow_customer.mermaid.md §2.1](./flow_customer.mermaid.md#21-anonymous--existing-user-merge-post-transaction-otp-).
**Setup**
- Verified customer row `User-A` exists with `phone=+62…X`, `display_name="Wati"`, `is_anonymous=false`. (Created earlier via OTP sign-up.)
**Scenario steps**
1. **[C]** Customer logs in successfully using phone `+62…X` → app holds `User-A` tokens (smoke-verifiable: `/api/client/auth/me` returns `User-A`'s `id` + `display_name="Wati"`).
2. **[C]** Customer taps logout → refresh token revoked; app state returns to `AuthInitialData`.
3. **[C]** Customer reopens the app and proceeds through onboarding → S2 Nama "Bujak" → VerifChoice → **"tanpa verifikasi" (anonymous)** → backend creates `Anon-B` with `is_anonymous=true`, `display_name="Bujak"`, `phone=NULL`.
4. **[C]** Customer completes ≥1 transaction as `Anon-B` (chat session, payment session, etc.) → rows in `chat_sessions` / `customer_transactions` carry `customer_id = Anon-B.id`.
5. **[C]** Customer goes back through VerifChoice → "verifikasi nomor HP" → enters the same `+62…X` → OTP verify request carries `Authorization: Bearer <Anon-B's access_token>` (issued by `/api/shared/auth/anonymous` in step 3). **The backend derives the anon id from the Bearer JWT only — there is no body field for `anonymous_customer_id`.** The same Bearer-only contract applies to `/api/client/auth/google` and `/api/client/auth/apple` (client_app does not exercise those paths yet — creds pending — but the backend behaves identically when they land).
**Expected**
- [ ] **[BE]** `POST /api/client/auth/otp/verify` returns **200** (NOT 409).
- [ ] **[BE]** Response `data.profile.id === User-A.id` (the existing account, not `Anon-B`).
- [ ] **[BE]** Response `data.profile.display_name === "Wati"` (overwrites the locally-typed "Bujak" per mermaid §2 line 62).
- [ ] **[BE]** Response `data.access_token` decodes to `{ sub: User-A.id, user_type: 'customer', … }` — subsequent authenticated calls act as `User-A`.
- [ ] **[BE]** DB invariant: `SELECT account_belongs_to FROM customers WHERE id = Anon-B.id` → `User-A.id`. Breadcrumb stamped.
- [ ] **[BE]** DB invariant: `Anon-B` row still exists — `is_anonymous=true`, `display_name="Bujak"` preserved, `phone=NULL`. NOT deleted.
- [ ] **[BE]** DB invariant: `Anon-B`'s `chat_sessions` / `customer_transactions` FKs are unchanged (still point at `Anon-B.id`). Actual data reconciliation onto `User-A` is the deferred phase; the breadcrumb is what enables it later.
- [ ] **[BE]** Re-running the same flow on a NEW fresh install (different `Anon-C`) with the same phone → second breadcrumb accumulates (`Anon-C.account_belongs_to = User-A.id`). Many anon rows may point at the same real user — fine.
**Negative checks**
- [ ] **[BE]** If the customer logs in directly with their phone (no anonymous prefix, fresh install) → 200, no merge breadcrumb on any row (Case 2a of the spec).
- [ ] **[BE]** If the customer re-verifies their own phone *while logged in as `User-A`* (anonymous_customer_id == existing.id) → 200, `account_belongs_to` stays NULL (no self-stamping, Case 2b).
- [ ] **[BE]** New phone (not in DB) + `anonymous_customer_id` set → anon row upgraded in place (`is_anonymous=false`, phone set, `display_name` preserved); no merge breadcrumb (Case 3 of spec).
**Auth source for `anonymous_customer_id` (security note)**
The backend derives the anon id **only** from a verified Bearer JWT presented as `Authorization: Bearer <token>`. The body field `anonymous_customer_id` is no longer read — accepting it would let anyone who learns a victim's anon UUID stamp the merge breadcrumb on it. Bearer tokens are HS256-signed with `AUTH_JWT_SECRET` and cannot be forged.
The resolver (`resolveAnonymousCustomerId` in [client.auth.routes.js](../backend/src/routes/public/client.auth.routes.js)) returns:
- The anon's `customer.id`, if the Bearer is valid AND `is_anonymous = true`.
- `null` if the Bearer is missing, invalid, expired, or belongs to a verified customer.
**Curl-runnable smoke** (against running dev backend; uses `fazpass_reference` to read the stub OTP code from DB):
```bash
# Pre: insert User-A and Anon-B via SQL; Anon-B's access_token is what the
# /api/shared/auth/anonymous endpoint returned.
curl -X POST $BASE/api/client/auth/otp/request \
-H 'content-type: application/json' \
-d '{"phone":"+62…X"}' # → otp_request_id
# Look up stub code:
psql -c "SELECT fazpass_reference FROM otp_requests WHERE id='<otp_request_id>'"
# fazpass_reference is "stub_<uuid>:<code>"
curl -X POST $BASE/api/client/auth/otp/verify \
-H 'content-type: application/json' \
-H "Authorization: Bearer <Anon-B's access_token>" \
-d '{"otp_request_id":"…","code":"<code>"}'
# Expect 200; profile.id === User-A.id; profile.display_name === "Wati"
psql -c "SELECT id, account_belongs_to FROM customers WHERE id='<Anon-B.id>'"
# Expect account_belongs_to === User-A.id
```
**Vitest coverage** for the boundary logic: [`backend/test/services/auth.service.test.js`](../backend/test/services/auth.service.test.js) covers all 4 service-level cases + multi-merge accumulation (6 tests). The route-layer Bearer enforcement was operator-verified with 11 additional checks against the live backend (5 cases: anon-Bearer, attacker-tries-body, no-Bearer-body-ignored, verified-Bearer, garbage-Bearer) — all green; the test script is intentionally not retained in-tree (one-off operator smoke).
### 1.5.2 Backend: Google / Apple parity for the merge breadcrumb (Phase 4 §2.1)
The same 4-case merge logic (`resolveCustomerForIdentity` in [auth.service.js](../backend/src/services/auth.service.js)) is applied to `signInWithGoogle` and `signInWithApple`. Both `/api/client/auth/google` and `/api/client/auth/apple` derive the anon prefix **only** from the Bearer JWT; the body field `anonymous_customer_id` is not read.
> **client_app does not exercise these routes today.** Google / Apple SDK
> integration on the customer app is gated on `authProvidersProvider` and
> won't trigger until provider credentials are provisioned. The backend
> tests below cover the behaviour so the merge is correct the moment the
> client wiring lands. When that happens, the client work mirrors the
> phone-OTP fix: drop `skipAuth: true` and any `anonymous_customer_id` body
> field on `loginGoogle` / `loginApple` so ApiClient attaches the anon's
> Bearer automatically.
**Expected behaviour — uniform with the phone path**
| Path | Existing identity? | Anon prefix (Bearer)? | Outcome |
|---|---|---|---|
| `/google` | yes, different id | yes | Anon row gets `account_belongs_to = Existing.id`; tokens for `Existing`. Anon row preserved. |
| `/google` | no | yes | Anon row upgraded in place (`google_sub` + `email` set; `display_name` preserved via COALESCE; `is_anonymous=false`). |
| `/google` | yes | no | Returns existing; no merge. |
| `/google` | no | no | Creates a fresh row with `display_name=null`; client routes to `AuthNeedsDisplayNameData`. |
| `/apple` | (same matrix) | | (same outcomes; `apple_sub` instead of `google_sub`) |
**Provider-specific notes**
- Display name is **not** taken from the provider. Google's `name` claim is intentionally ignored (anonymous-chose name wins); Apple's first-launch display_name behaviour (Apple withholds it on subsequent sign-ins) is irrelevant for the same reason.
- `email` is recorded on the customer row when present in the verified id_token; subsequent OTP/Apple sign-ins don't overwrite a non-null email via `COALESCE`.
**Checklist**
- [ ] **[BE]** Vitest `signInWithGoogle` — Case 1 (existing google_sub on a DIFFERENT customer + anon prefix) → 200; stamps `account_belongs_to`; returns existing.
- [ ] **[BE]** Vitest `signInWithGoogle` — Case 3 (new google_sub + anon prefix) → 200; anon row upgraded in place; `display_name` preserved; `google_sub`/`email` set.
- [ ] **[BE]** Vitest `signInWithApple` — Case 1 (existing apple_sub on a DIFFERENT customer + anon prefix) → 200; stamps `account_belongs_to`; returns existing.
- [ ] **[BE]** Route-level (curl): `POST /api/client/auth/google` with `Authorization: Bearer <Anon's access_token>` and a valid `id_token` for an existing Google account → 200 + merge breadcrumb on the anon row.
- [ ] **[BE]** Route-level (curl): same call WITHOUT Bearer (body has `anonymous_customer_id` instead) → 200 sign-in completes, but the body field is ignored; anon row's `account_belongs_to` stays NULL. Confirms the security hardening from §1.5.1 covers Google as well.
- [ ] **[BE]** Identical curl smokes for `/api/client/auth/apple`.
> The "valid id_token" requirement makes the curl checks non-trivial without
> provider credentials. Until creds land, the Vitest layer is the
> authoritative coverage; the curl checklist serves as an operator runbook
> for the day client wiring goes live.
**Vitest coverage** lives in [`backend/test/services/auth.service.test.js`](../backend/test/services/auth.service.test.js) alongside the phone tests (9 tests total: 6 phone + 1 Google upgrade + 1 Google stamp + 1 Apple stamp). The social-identity verifiers are mocked at module scope so tests don't require real id_tokens.
### 1.6 Backend: Auth Middleware + Cross-User-Type Guards
- [ ] **[BE]** Protected route with no `Authorization` header → 401 `AUTH_MISSING`