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

25
backend/src/db/migrate.js
View File

@@ -654,6 +654,31 @@ const migrate = async () => {
ON CONFLICT (key) DO NOTHING ON CONFLICT (key) DO NOTHING
` `
// 5. Phase 4 USP one-time gate. Customers see S5b USP at most once; this flag
// is the cross-device source of truth, OR-merged with a local
// SharedPreferences flag on the client. Existing customers come out as
// false and will see USP one more time on next "aku mau curhat" — business
// accepted this backfill cost.
await sql`
ALTER TABLE customers
ADD COLUMN IF NOT EXISTS usp_seen BOOLEAN NOT NULL DEFAULT FALSE
`
// --- Phase 4 §2.1: Anonymous → existing-user merge breadcrumb ---
//
// When an anonymous customer verifies a phone that already belongs to a
// different (existing) customer row, we don't 409 the OTP and we don't
// delete the anon row (which would orphan its chat_sessions /
// customer_transactions). Instead we stamp account_belongs_to on the anon
// row pointing at the existing customer's id, then log the app in as the
// existing user. Actual data reconciliation (moving FKs onto the existing
// row) is deferred to a later phase — this column is the breadcrumb that
// makes the merge replayable.
await sql`
ALTER TABLE customers
ADD COLUMN IF NOT EXISTS account_belongs_to UUID REFERENCES customers(id) ON DELETE SET NULL
`
console.log('Migration complete.') console.log('Migration complete.')
await sql.end() await sql.end()
} }

78
backend/src/routes/public/client.auth.routes.js
View File

@@ -1,11 +1,16 @@
import { authenticate } from '../../plugins/auth.js' import { authenticate } from '../../plugins/auth.js'
import { getCustomerById, updateCustomerDisplayName } from '../../services/customer.service.js' import {
getCustomerById,
markCustomerUspSeen,
updateCustomerDisplayName,
} from '../../services/customer.service.js'
import { import {
completeCustomerPhoneSignIn, completeCustomerPhoneSignIn,
signInWithGoogle, signInWithGoogle,
signInWithApple, signInWithApple,
} from '../../services/auth.service.js' } from '../../services/auth.service.js'
import { requestOtp, verifyOtp } from '../../services/otp.service.js' import { requestOtp, verifyOtp } from '../../services/otp.service.js'
import { verifyAccessToken } from '../../services/token.service.js'
import { UserType } from '../../constants.js' import { UserType } from '../../constants.js'
const extractDeviceInfo = (request) => ({ const extractDeviceInfo = (request) => ({
@@ -13,6 +18,29 @@ const extractDeviceInfo = (request) => ({
ip: request.ip || null, 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) => { const sendAuthError = (reply, err) => {
if (!err.statusCode) reply.request.log.error({ err }, 'Unhandled auth error') if (!err.statusCode) reply.request.log.error({ err }, 'Unhandled auth error')
return reply.code(err.statusCode || 500).send({ return reply.code(err.statusCode || 500).send({
@@ -44,7 +72,7 @@ export const clientAuthRoutes = async (app) => {
}) })
app.post('/otp/verify', async (request, reply) => { 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 { try {
const { phone, user_type } = await verifyOtp({ otpRequestId: otp_request_id, code }) const { phone, user_type } = await verifyOtp({ otpRequestId: otp_request_id, code })
if (user_type !== UserType.CUSTOMER) { 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' }, 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({ const { tokens, profile } = await completeCustomerPhoneSignIn({
phone, phone,
anonymousCustomerId: anonymous_customer_id || null, anonymousCustomerId,
deviceInfo: extractDeviceInfo(request), deviceInfo: extractDeviceInfo(request),
}) })
return reply.send({ success: true, data: { ...tokens, profile } }) return reply.send({ success: true, data: { ...tokens, profile } })
@@ -67,7 +103,7 @@ export const clientAuthRoutes = async (app) => {
// --- Google --- // --- Google ---
app.post('/google', async (request, reply) => { app.post('/google', async (request, reply) => {
const { id_token, anonymous_customer_id } = request.body || {} const { id_token } = request.body || {}
if (!id_token) { if (!id_token) {
return reply.code(422).send({ return reply.code(422).send({
success: false, success: false,
@@ -75,9 +111,14 @@ export const clientAuthRoutes = async (app) => {
}) })
} }
try { 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({ const { tokens, profile } = await signInWithGoogle({
idToken: id_token, idToken: id_token,
anonymousCustomerId: anonymous_customer_id || null, anonymousCustomerId,
deviceInfo: extractDeviceInfo(request), deviceInfo: extractDeviceInfo(request),
}) })
return reply.send({ success: true, data: { ...tokens, profile } }) return reply.send({ success: true, data: { ...tokens, profile } })
@@ -89,7 +130,7 @@ export const clientAuthRoutes = async (app) => {
// --- Apple --- // --- Apple ---
app.post('/apple', async (request, reply) => { app.post('/apple', async (request, reply) => {
const { id_token, anonymous_customer_id } = request.body || {} const { id_token } = request.body || {}
if (!id_token) { if (!id_token) {
return reply.code(422).send({ return reply.code(422).send({
success: false, success: false,
@@ -97,9 +138,13 @@ export const clientAuthRoutes = async (app) => {
}) })
} }
try { 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({ const { tokens, profile } = await signInWithApple({
idToken: id_token, idToken: id_token,
anonymousCustomerId: anonymous_customer_id || null, anonymousCustomerId,
deviceInfo: extractDeviceInfo(request), deviceInfo: extractDeviceInfo(request),
}) })
return reply.send({ success: true, data: { ...tokens, profile } }) return reply.send({ success: true, data: { ...tokens, profile } })
@@ -127,6 +172,25 @@ export const clientAuthRoutes = async (app) => {
return reply.send({ success: true, data: customer }) 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 --- // --- Update display name ---
app.patch('/profile', { preHandler: authenticate }, async (request, reply) => { app.patch('/profile', { preHandler: authenticate }, async (request, reply) => {

111
backend/src/services/auth.service.js
View File

@@ -7,6 +7,7 @@ import {
createAnonymousCustomerV2, createAnonymousCustomerV2,
createCustomerWithIdentity, createCustomerWithIdentity,
upgradeCustomerIdentity, upgradeCustomerIdentity,
stampAccountBelongsTo,
} from './customer.service.js' } from './customer.service.js'
import { import {
getMitraByPhone, getMitraByPhone,
@@ -38,15 +39,37 @@ export class AuthError extends Error {
} }
} }
const normalizeIdentityConflict = async ({ existing, anonymousCustomerId }) => { // Phase 4 §2.1 — shared identity-resolution path used by phone/Google/Apple
// If an authenticated identity is already linked to a DIFFERENT customer, // sign-ins. Three branches:
// reject. Merge is deferred per PRD. //
if (existing && anonymousCustomerId && existing.id !== anonymousCustomerId) { // 1. existing identity row + anon prefix points at a different row
throw new AuthError( // → stamp `account_belongs_to` on the anon row and return the existing
'This account is already linked to another session. Please log out first.', // row. The anon row stays intact so its prior chat_sessions /
'IDENTITY_ALREADY_LINKED', 409, // customer_transactions FKs remain valid; reconciliation onto the
) // existing customer is replayable later via the breadcrumb.
// 2. existing identity row (no anon, or anon id == existing.id)
// → return existing as-is.
// 3. no existing row + anon prefix
// → upgrade the anon row in place (set identity fields, preserve
// display_name etc. via COALESCE).
// 4. no existing row + no anon
// → create a fresh identified customer with display_name=null (client
// routes to the set-display-name screen).
//
// `identityFields` is the set of columns added by either upgrade or create
// (phone, google_sub+email, apple_sub+email). display_name=null is appended
// automatically for the create case.
const resolveCustomerForIdentity = async ({ existing, anonymousCustomerId, identityFields }) => {
if (existing) {
if (anonymousCustomerId && existing.id !== anonymousCustomerId) {
await stampAccountBelongsTo(anonymousCustomerId, existing.id)
} }
return existing
}
if (anonymousCustomerId) {
return await upgradeCustomerIdentity(anonymousCustomerId, identityFields)
}
return await createCustomerWithIdentity({ ...identityFields, display_name: null })
} }
// --- Anonymous --- // --- Anonymous ---
@@ -63,21 +86,14 @@ export const signInAnonymous = async ({ deviceInfo } = {}) => {
return { tokens, profile: customer } return { tokens, profile: customer }
} }
// --- Phone OTP — Customer --- // --- Phone OTP — Customer (Phase 4 §2.1 merge breadcrumb) ---
export const completeCustomerPhoneSignIn = async ({ phone, anonymousCustomerId, deviceInfo }) => { export const completeCustomerPhoneSignIn = async ({ phone, anonymousCustomerId, deviceInfo }) => {
const existing = await getCustomerByPhone(phone) const existing = await getCustomerByPhone(phone)
await normalizeIdentityConflict({ existing, anonymousCustomerId }) const customer = await resolveCustomerForIdentity({
existing,
let customer anonymousCustomerId,
if (existing) { identityFields: { phone },
customer = existing })
} else if (anonymousCustomerId) {
customer = await upgradeCustomerIdentity(anonymousCustomerId, { phone })
} else {
customer = await createCustomerWithIdentity({ phone, display_name: null })
}
const tokens = await issueTokens({ const tokens = await issueTokens({
userType: UserType.CUSTOMER, userType: UserType.CUSTOMER,
userId: customer.id, userId: customer.id,
@@ -101,32 +117,18 @@ export const completeMitraPhoneSignIn = async ({ phone, deviceInfo }) => {
return { tokens, profile: mitra } return { tokens, profile: mitra }
} }
// --- Google (customer only) --- // --- Google (customer only) — Phase 4 §2.1 merge breadcrumb ---
//
// We don't pull display_name from Google; the anon's display_name is
// preserved via upgradeCustomerIdentity's COALESCE.
export const signInWithGoogle = async ({ idToken, anonymousCustomerId, deviceInfo }) => { export const signInWithGoogle = async ({ idToken, anonymousCustomerId, deviceInfo }) => {
const google = await verifyGoogleIdToken(idToken) const google = await verifyGoogleIdToken(idToken)
const existing = await getCustomerByGoogleSub(google.sub) const existing = await getCustomerByGoogleSub(google.sub)
await normalizeIdentityConflict({ existing, anonymousCustomerId }) const customer = await resolveCustomerForIdentity({
existing,
let customer anonymousCustomerId,
if (existing) { identityFields: { google_sub: google.sub, email: google.email },
customer = existing
} else if (anonymousCustomerId) {
// Preserve the anonymous display_name; we don't pull name from Google.
customer = await upgradeCustomerIdentity(anonymousCustomerId, {
google_sub: google.sub,
email: google.email,
}) })
} else {
// No anonymous bootstrap → display_name is null; frontend routes to
// the set-display-name screen.
customer = await createCustomerWithIdentity({
google_sub: google.sub,
email: google.email,
display_name: null,
})
}
const tokens = await issueTokens({ const tokens = await issueTokens({
userType: UserType.CUSTOMER, userType: UserType.CUSTOMER,
userId: customer.id, userId: customer.id,
@@ -135,29 +137,16 @@ export const signInWithGoogle = async ({ idToken, anonymousCustomerId, deviceInf
return { tokens, profile: customer } return { tokens, profile: customer }
} }
// --- Apple (customer only) --- // --- Apple (customer only) — Phase 4 §2.1 merge breadcrumb ---
export const signInWithApple = async ({ idToken, anonymousCustomerId, deviceInfo }) => { export const signInWithApple = async ({ idToken, anonymousCustomerId, deviceInfo }) => {
const apple = await verifyAppleIdToken(idToken) const apple = await verifyAppleIdToken(idToken)
const existing = await getCustomerByAppleSub(apple.sub) const existing = await getCustomerByAppleSub(apple.sub)
await normalizeIdentityConflict({ existing, anonymousCustomerId }) const customer = await resolveCustomerForIdentity({
existing,
let customer anonymousCustomerId,
if (existing) { identityFields: { apple_sub: apple.sub, email: apple.email },
customer = existing
} else if (anonymousCustomerId) {
customer = await upgradeCustomerIdentity(anonymousCustomerId, {
apple_sub: apple.sub,
email: apple.email,
}) })
} else {
customer = await createCustomerWithIdentity({
apple_sub: apple.sub,
email: apple.email,
display_name: null,
})
}
const tokens = await issueTokens({ const tokens = await issueTokens({
userType: UserType.CUSTOMER, userType: UserType.CUSTOMER,
userId: customer.id, userId: customer.id,

29
backend/src/services/customer.service.js
View File

@@ -13,7 +13,7 @@ export const updateCustomerDisplayName = async (customerId, displayName) => {
// --- Phase 3.4: Self-Managed Auth --- // --- Phase 3.4: Self-Managed Auth ---
const CUSTOMER_SELECT = sql`id, display_name, is_anonymous, phone, email, google_sub, apple_sub, created_at` const CUSTOMER_SELECT = sql`id, display_name, is_anonymous, phone, email, google_sub, apple_sub, usp_seen, account_belongs_to, created_at`
export const getCustomerById = async (id) => { export const getCustomerById = async (id) => {
const [row] = await sql`SELECT ${CUSTOMER_SELECT} FROM customers WHERE id = ${id}` const [row] = await sql`SELECT ${CUSTOMER_SELECT} FROM customers WHERE id = ${id}`
@@ -79,3 +79,30 @@ export const upgradeCustomerIdentity = async (customerId, {
` `
return row return row
} }
// --- Phase 4 §2.1: Anonymous → existing merge breadcrumb ---
// Stamps the anon-row with the existing customer's id. The anon row stays
// intact (preserving its chat_sessions/customer_transactions FKs); the
// breadcrumb makes the data reconciliation replayable in a later phase.
// Returns the updated anon row (mostly for tests/audit).
export const stampAccountBelongsTo = async (anonCustomerId, existingCustomerId) => {
const [row] = await sql`
UPDATE customers
SET account_belongs_to = ${existingCustomerId}
WHERE id = ${anonCustomerId}
RETURNING ${CUSTOMER_SELECT}
`
return row
}
// --- Phase 4: USP one-time gate ---
export const markCustomerUspSeen = async (customerId) => {
const [row] = await sql`
UPDATE customers SET usp_seen = TRUE
WHERE id = ${customerId}
RETURNING ${CUSTOMER_SELECT}
`
return row
}

223
backend/test/services/auth.service.test.js Normal file
View File

@@ -0,0 +1,223 @@
import { describe, it, expect, beforeEach, vi } from 'vitest'
import { randomUUID } from 'node:crypto'
// Stub the social-identity verifiers so Google/Apple tests don't need real
// id_tokens. Each test passes the synthetic payload directly via the
// id_token string and the mock returns it parsed.
vi.mock('../../src/services/social-identity.service.js', () => ({
verifyGoogleIdToken: vi.fn(async (idToken) => JSON.parse(idToken)),
verifyAppleIdToken: vi.fn(async (idToken) => JSON.parse(idToken)),
}))
const {
completeCustomerPhoneSignIn,
signInWithGoogle,
signInWithApple,
} = await import('../../src/services/auth.service.js')
const { db, resetDb } = await import('../helpers/db.js')
const { createCustomer } = await import('../helpers/fixtures.js')
// Phase 4 §2.1 — Anonymous → existing-user merge breadcrumb.
//
// `resetDb` does NOT truncate the customers table (see helpers/db.js); each
// test must use a phone that's unique across runs to avoid colliding with rows
// left behind by prior runs.
const uniquePhone = () => {
const digits = randomUUID().replace(/[^0-9]/g, '').slice(0, 11).padEnd(11, '0')
return `+628${digits}`
}
describe('completeCustomerPhoneSignIn — Phase 4 §2.1 merge breadcrumb', () => {
beforeEach(async () => {
await resetDb()
})
// --- Case 4: no anon prefix, new phone ---
it('creates a fresh identified customer with null display_name (no anon, new phone)', async () => {
const phone = uniquePhone()
const { profile } = await completeCustomerPhoneSignIn({
phone,
anonymousCustomerId: null,
deviceInfo: {},
})
expect(profile.phone).toBe(phone)
expect(profile.display_name).toBeNull()
expect(profile.is_anonymous).toBe(false)
expect(profile.account_belongs_to).toBeNull()
})
// --- Case 3: anon prefix, new phone → upgrade in place ---
it('upgrades the anon row in place, preserving display_name (anon, new phone)', async () => {
const phone = uniquePhone()
const anon = await createCustomer({ callName: 'Bujak', isAnonymous: true })
const { profile } = await completeCustomerPhoneSignIn({
phone,
anonymousCustomerId: anon.id,
deviceInfo: {},
})
expect(profile.id).toBe(anon.id) // same row, upgraded
expect(profile.phone).toBe(phone)
expect(profile.display_name).toBe('Bujak') // preserved via COALESCE
expect(profile.is_anonymous).toBe(false)
expect(profile.account_belongs_to).toBeNull() // no merge
// No new customer row was created.
const sql = db()
const [{ count }] = await sql`SELECT COUNT(*)::int AS count FROM customers WHERE phone = ${phone}`
expect(count).toBe(1)
})
// --- Case 1: anon prefix, existing phone → stamp breadcrumb, return existing ---
it('stamps account_belongs_to on the anon row and returns the existing customer (anon, existing phone)', async () => {
const phone = uniquePhone()
const existing = await createCustomer({ callName: 'Wati', phone, isAnonymous: false })
const anon = await createCustomer({ callName: 'Bujak', isAnonymous: true })
const { profile, tokens } = await completeCustomerPhoneSignIn({
phone,
anonymousCustomerId: anon.id,
deviceInfo: {},
})
// The session logs in AS the existing user.
expect(profile.id).toBe(existing.id)
expect(profile.display_name).toBe('Wati') // existing's name, overwrites local
expect(profile.phone).toBe(phone)
expect(profile.account_belongs_to).toBeNull() // existing row is the target, not stamped
// Token claims point at the existing user (so subsequent requests act as them).
expect(tokens.access_token).toBeDefined()
// Anon row stays intact, now carries the merge breadcrumb.
const sql = db()
const [anonRow] = await sql`SELECT id, display_name, account_belongs_to, is_anonymous FROM customers WHERE id = ${anon.id}`
expect(anonRow).toBeDefined() // not deleted
expect(anonRow.display_name).toBe('Bujak') // preserved
expect(anonRow.account_belongs_to).toBe(existing.id) // breadcrumb stamped
expect(anonRow.is_anonymous).toBe(true) // still anon (for later reconciliation)
})
// --- Case 2a: no anon prefix, existing phone → return existing, no stamping ---
it('returns the existing customer as-is when no anon prefix (existing phone, fresh app)', async () => {
const phone = uniquePhone()
const existing = await createCustomer({ callName: 'Wati', phone, isAnonymous: false })
const { profile } = await completeCustomerPhoneSignIn({
phone,
anonymousCustomerId: null,
deviceInfo: {},
})
expect(profile.id).toBe(existing.id)
expect(profile.display_name).toBe('Wati')
expect(profile.account_belongs_to).toBeNull()
})
// --- Case 2b: anon id === existing's id (user re-verifying own phone) ---
// No-op merge. account_belongs_to stays null; no self-reference is created.
it('does not self-stamp when the anon id equals the existing customer id (re-verify)', async () => {
const phone = uniquePhone()
const existing = await createCustomer({ callName: 'Wati', phone, isAnonymous: false })
const { profile } = await completeCustomerPhoneSignIn({
phone,
anonymousCustomerId: existing.id, // same id as the existing row
deviceInfo: {},
})
expect(profile.id).toBe(existing.id)
expect(profile.account_belongs_to).toBeNull()
// Verify nothing self-referenced.
const sql = db()
const [row] = await sql`SELECT account_belongs_to FROM customers WHERE id = ${existing.id}`
expect(row.account_belongs_to).toBeNull()
})
// --- Google: stamp breadcrumb on existing-different-id (parity with phone) ---
it('Google: stamps account_belongs_to when existing google_sub differs from anon (Case 1)', async () => {
const googleSub = `g-${randomUUID()}`
const [existing] = await db()`
INSERT INTO customers (display_name, is_anonymous, google_sub, email)
VALUES ('Wati', false, ${googleSub}, 'wati@example.com')
RETURNING ${db()`id, display_name, is_anonymous, phone, email, google_sub, apple_sub, usp_seen, account_belongs_to, created_at`}
`
const anon = await createCustomer({ callName: 'Bujak', isAnonymous: true })
const { profile } = await signInWithGoogle({
idToken: JSON.stringify({ sub: googleSub, email: 'wati@example.com' }),
anonymousCustomerId: anon.id,
deviceInfo: {},
})
expect(profile.id).toBe(existing.id)
expect(profile.display_name).toBe('Wati')
const [anonRow] = await db()`SELECT account_belongs_to FROM customers WHERE id = ${anon.id}`
expect(anonRow.account_belongs_to).toBe(existing.id)
})
// --- Google: upgrade-in-place when google_sub is new ---
it('Google: upgrades anon in place when google_sub is new, preserving display_name (Case 3)', async () => {
const googleSub = `g-${randomUUID()}`
const anon = await createCustomer({ callName: 'Bujak', isAnonymous: true })
const { profile } = await signInWithGoogle({
idToken: JSON.stringify({ sub: googleSub, email: 'bujak@example.com' }),
anonymousCustomerId: anon.id,
deviceInfo: {},
})
expect(profile.id).toBe(anon.id)
expect(profile.google_sub).toBe(googleSub)
expect(profile.email).toBe('bujak@example.com')
expect(profile.display_name).toBe('Bujak')
expect(profile.is_anonymous).toBe(false)
expect(profile.account_belongs_to).toBeNull()
})
// --- Apple: stamp breadcrumb on existing-different-id (parity with phone) ---
it('Apple: stamps account_belongs_to when existing apple_sub differs from anon (Case 1)', async () => {
const appleSub = `a-${randomUUID()}`
const [existing] = await db()`
INSERT INTO customers (display_name, is_anonymous, apple_sub, email)
VALUES ('Wati', false, ${appleSub}, 'wati@apple.example')
RETURNING ${db()`id, display_name, is_anonymous, phone, email, google_sub, apple_sub, usp_seen, account_belongs_to, created_at`}
`
const anon = await createCustomer({ callName: 'Bujak', isAnonymous: true })
const { profile } = await signInWithApple({
idToken: JSON.stringify({ sub: appleSub, email: 'wati@apple.example' }),
anonymousCustomerId: anon.id,
deviceInfo: {},
})
expect(profile.id).toBe(existing.id)
expect(profile.display_name).toBe('Wati')
const [anonRow] = await db()`SELECT account_belongs_to FROM customers WHERE id = ${anon.id}`
expect(anonRow.account_belongs_to).toBe(existing.id)
})
// --- Multi-merge: same anon path used twice for the same existing user accumulates without conflict ---
it('handles multiple anon rows pointing at the same existing user (multi-merge accumulation)', async () => {
const phone = uniquePhone()
const existing = await createCustomer({ callName: 'Wati', phone, isAnonymous: false })
const anon1 = await createCustomer({ callName: 'Bujak', isAnonymous: true })
const anon2 = await createCustomer({ callName: 'Bendoyo', isAnonymous: true })
await completeCustomerPhoneSignIn({ phone, anonymousCustomerId: anon1.id, deviceInfo: {} })
await completeCustomerPhoneSignIn({ phone, anonymousCustomerId: anon2.id, deviceInfo: {} })
const sql = db()
const rows = await sql`SELECT id, account_belongs_to FROM customers WHERE id IN (${anon1.id}, ${anon2.id}) ORDER BY display_name`
expect(rows).toHaveLength(2)
for (const row of rows) {
expect(row.account_belongs_to).toBe(existing.id)
}
})
})

9
client_app/lib/core/auth/auth_notifier.dart
View File

@@ -243,15 +243,18 @@ class Auth extends _$Auth {
Future<void> verifyOtp(String otpRequestId, String code) async { Future<void> verifyOtp(String otpRequestId, String code) async {
state = const AsyncLoading(); state = const AsyncLoading();
try { try {
// Bearer is attached automatically by ApiClient from AuthBridge — when
// the user is currently anonymous, that's the anon session's access
// token, which the backend uses to derive the anon id for the Phase 4
// §2.1 merge breadcrumb. The legacy body field `anonymous_customer_id`
// is no longer sent (server ignores it; tamper-able UUIDs in the body
// were the security hole closed in §2.1 hardening).
final response = await _apiClient.postRaw( final response = await _apiClient.postRaw(
'/api/client/auth/otp/verify', '/api/client/auth/otp/verify',
data: { data: {
'otp_request_id': otpRequestId, 'otp_request_id': otpRequestId,
'code': code, 'code': code,
if (_currentAnonymousCustomerId() != null)
'anonymous_customer_id': _currentAnonymousCustomerId(),
}, },
skipAuth: true,
); );
final profile = await _applyTokens(response); final profile = await _applyTokens(response);
state = AsyncData(await _stateForProfile(profile)); state = AsyncData(await _stateForProfile(profile));

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 + > exists (see Phase 1 auto-link via phone); the app-side reconciliation +
> `has_transacted` plumbing is the new work. > `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) ## 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]** 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]** 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]** 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** - [ ] **[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 ### 1.6 Backend: Auth Middleware + Cross-User-Type Guards
- [ ] **[BE]** Protected route with no `Authorization` header → 401 `AUTH_MISSING` - [ ] **[BE]** Protected route with no `Authorization` header → 401 `AUTH_MISSING`