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

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>

backend/src/routes/public/client.auth.routes.js

@@ -1,11 +1,16 @@
 import { authenticate } from '../../plugins/auth.js'
-import { getCustomerById, updateCustomerDisplayName } from '../../services/customer.service.js'
+import {
+  getCustomerById,
+  markCustomerUspSeen,
+  updateCustomerDisplayName,
+} from '../../services/customer.service.js'
 import {
   completeCustomerPhoneSignIn,
   signInWithGoogle,
   signInWithApple,
 } from '../../services/auth.service.js'
 import { requestOtp, verifyOtp } from '../../services/otp.service.js'
+import { verifyAccessToken } from '../../services/token.service.js'
 import { UserType } from '../../constants.js'
 
 const extractDeviceInfo = (request) => ({
@@ -13,6 +18,29 @@ const extractDeviceInfo = (request) => ({
   ip: request.ip || null,
 })
 
+// Phase 4 §2.1 — Resolve the trusted anonymous customer id for the merge path.
+// Source of truth is a verified Bearer JWT. The body field was deliberately
+// dropped: a tamper-able UUID in the body lets anyone who learns a victim's
+// anon id stamp `account_belongs_to` on it, which would mis-route their
+// transactions during reconciliation. The JWT is HS256-signed with
+// AUTH_JWT_SECRET — un-forgeable.
+//
+// Rules:
+//   - Bearer valid + customer + customer.is_anonymous → return that customer id.
+//   - Bearer valid + customer but NOT anonymous (already verified)         → null
+//   - Bearer absent or invalid                                             → null
+const resolveAnonymousCustomerId = async ({ bearer }) => {
+  if (!bearer || !bearer.startsWith('Bearer ')) return null
+  try {
+    const claims = verifyAccessToken(bearer.slice('Bearer '.length))
+    if (claims.userType !== UserType.CUSTOMER) return null
+    const customer = await getCustomerById(claims.userId)
+    return customer?.is_anonymous ? customer.id : null
+  } catch {
+    return null
+  }
+}
+
 const sendAuthError = (reply, err) => {
   if (!err.statusCode) reply.request.log.error({ err }, 'Unhandled auth error')
   return reply.code(err.statusCode || 500).send({
@@ -44,7 +72,7 @@ export const clientAuthRoutes = async (app) => {
   })
 
   app.post('/otp/verify', async (request, reply) => {
-    const { otp_request_id, code, anonymous_customer_id } = request.body || {}
+    const { otp_request_id, code } = request.body || {}
     try {
       const { phone, user_type } = await verifyOtp({ otpRequestId: otp_request_id, code })
       if (user_type !== UserType.CUSTOMER) {
@@ -53,9 +81,17 @@ export const clientAuthRoutes = async (app) => {
           error: { code: 'WRONG_FLOW', message: 'This OTP was issued for a different user type' },
         })
       }
+      // Phase 4 §2.1 — the anon prefix used to drive the
+      // account_belongs_to merge is derived ONLY from the verified Bearer
+      // JWT. Clients that need the merge must send their anonymous session's
+      // access_token as `Authorization: Bearer …`. The body field is no
+      // longer accepted.
+      const anonymousCustomerId = await resolveAnonymousCustomerId({
+        bearer: request.headers.authorization,
+      })
       const { tokens, profile } = await completeCustomerPhoneSignIn({
         phone,
-        anonymousCustomerId: anonymous_customer_id || null,
+        anonymousCustomerId,
         deviceInfo: extractDeviceInfo(request),
       })
       return reply.send({ success: true, data: { ...tokens, profile } })
@@ -67,7 +103,7 @@ export const clientAuthRoutes = async (app) => {
   // --- Google ---
 
   app.post('/google', async (request, reply) => {
-    const { id_token, anonymous_customer_id } = request.body || {}
+    const { id_token } = request.body || {}
     if (!id_token) {
       return reply.code(422).send({
         success: false,
@@ -75,9 +111,14 @@ export const clientAuthRoutes = async (app) => {
       })
     }
     try {
+      // Phase 4 §2.1 — anon prefix is derived ONLY from the Bearer JWT;
+      // body field `anonymous_customer_id` is not accepted.
+      const anonymousCustomerId = await resolveAnonymousCustomerId({
+        bearer: request.headers.authorization,
+      })
       const { tokens, profile } = await signInWithGoogle({
         idToken: id_token,
-        anonymousCustomerId: anonymous_customer_id || null,
+        anonymousCustomerId,
         deviceInfo: extractDeviceInfo(request),
       })
       return reply.send({ success: true, data: { ...tokens, profile } })
@@ -89,7 +130,7 @@ export const clientAuthRoutes = async (app) => {
   // --- Apple ---
 
   app.post('/apple', async (request, reply) => {
-    const { id_token, anonymous_customer_id } = request.body || {}
+    const { id_token } = request.body || {}
     if (!id_token) {
       return reply.code(422).send({
         success: false,
@@ -97,9 +138,13 @@ export const clientAuthRoutes = async (app) => {
       })
     }
     try {
+      // Phase 4 §2.1 — same Bearer-only contract as /otp/verify and /google.
+      const anonymousCustomerId = await resolveAnonymousCustomerId({
+        bearer: request.headers.authorization,
+      })
       const { tokens, profile } = await signInWithApple({
         idToken: id_token,
-        anonymousCustomerId: anonymous_customer_id || null,
+        anonymousCustomerId,
         deviceInfo: extractDeviceInfo(request),
       })
       return reply.send({ success: true, data: { ...tokens, profile } })
@@ -127,6 +172,25 @@ export const clientAuthRoutes = async (app) => {
     return reply.send({ success: true, data: customer })
   })
 
+  // --- Phase 4: mark USP screen as seen (one-time gate, idempotent) ---
+
+  app.post('/usp-seen', { preHandler: authenticate }, async (request, reply) => {
+    if (request.auth.userType !== UserType.CUSTOMER) {
+      return reply.code(403).send({
+        success: false,
+        error: { code: 'FORBIDDEN', message: 'Customer account required' },
+      })
+    }
+    const updated = await markCustomerUspSeen(request.auth.userId)
+    if (!updated) {
+      return reply.code(404).send({
+        success: false,
+        error: { code: 'NOT_FOUND', message: 'Customer account not found' },
+      })
+    }
+    return reply.send({ success: true, data: updated })
+  })
+
   // --- Update display name ---
 
   app.patch('/profile', { preHandler: authenticate }, async (request, reply) => {