OTP test infrastructure for Maestro flows

Dev-only /internal/_test/peek-otp + /internal/_test/reset-phone endpoints
gated by NODE_ENV !== 'production'. peek-otp reads the latest stub OTP
out of an in-memory map populated by otp.service.js fazpassSendStub;
reset-phone wipes otp_requests rows (and optionally the customers row)
so flows can re-run without tripping cooldowns.

JS + shell helpers under .maestro/scripts/ wrap the endpoints for use
inside Maestro runScript steps. 01_smoke.yaml expanded from a launch-only
sanity check to a full cold-start onboarding -> force-register -> OTP ->
home walk.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/src/app.internal.js

@@ -10,6 +10,7 @@ import { internalConfigRoutes } from './routes/internal/config.routes.js'
 import { sessionManagementRoutes } from './routes/internal/session.routes.js'
 import { mitraActivityRoutes } from './routes/internal/mitra-activity.routes.js'
 import { failedPairingsRoutes } from './routes/internal/failed-pairings.routes.js'
+import { internalTestRoutes } from './routes/internal/_test.routes.js'
 import { errorHandler } from './plugins/error-handler.js'
 
 export const buildInternalApp = async () => {
@@ -38,5 +39,10 @@ export const buildInternalApp = async () => {
   app.register(mitraActivityRoutes, { prefix: '/internal/mitra-activity' })
   app.register(failedPairingsRoutes, { prefix: '/internal/failed-pairings' })
 
+  // Dev/test-only — never registered in production builds.
+  if (process.env.NODE_ENV !== 'production') {
+    app.register(internalTestRoutes, { prefix: '/internal/_test' })
+  }
+
   return app
 }

backend/src/routes/internal/_test.routes.js

@@ -0,0 +1,41 @@
+// Dev/test-only routes. Registration in app.internal.js is gated on
+// NODE_ENV !== 'production' so these endpoints never exist in prod builds.
+//
+// Used by Maestro flows + curl harnesses to read state that the OTP stub
+// keeps in memory (the stub-generated code per phone), without baking
+// test phone numbers or fixed codes into production code paths.
+
+import { peekStubOtp } from '../../services/otp.service.js'
+import { getDb } from '../../db/client.js'
+
+const sql = getDb()
+
+export const internalTestRoutes = async (fastify) => {
+  fastify.get('/peek-otp', async (request, reply) => {
+    const phone = request.query?.phone
+    if (!phone) {
+      return reply.code(400).send({ error: 'phone query param required' })
+    }
+    const entry = peekStubOtp(phone)
+    if (!entry) {
+      return reply.code(404).send({ error: 'no_otp_for_phone', phone })
+    }
+    return entry
+  })
+
+  // Wipe rate-limit + cooldown state for a phone so flows can re-run quickly.
+  // Deletes otp_requests rows for the phone and (optionally) the customer row
+  // so identity-upgrade flows start fresh.
+  fastify.post('/reset-phone', async (request, reply) => {
+    const phone = request.body?.phone
+    if (!phone) {
+      return reply.code(400).send({ error: 'phone required in body' })
+    }
+    const dropCustomer = request.body?.drop_customer === true
+    await sql`DELETE FROM otp_requests WHERE phone = ${phone}`
+    if (dropCustomer) {
+      await sql`DELETE FROM customers WHERE phone = ${phone}`
+    }
+    return { ok: true, phone, dropped_customer: dropCustomer }
+  })
+}

backend/src/services/otp.service.js

@@ -26,9 +26,17 @@ const generate6DigitCode = () => {
   return String(crypto.randomInt(0, 1_000_000)).padStart(6, '0')
 }
 
+// Dev-only in-memory cache of latest stub OTP per phone, read by the
+// /internal/_test/peek-otp endpoint to make Maestro flows deterministic
+// without baking test phone numbers into production code paths.
+const stubOtpByPhone = new Map()
+
+export const peekStubOtp = (phone) => stubOtpByPhone.get(phone) ?? null
+
 const fazpassSendStub = async ({ phone, channel }) => {
   const reference = `stub_${crypto.randomUUID()}`
   const code = generate6DigitCode()
+  stubOtpByPhone.set(phone, { code, reference, channel, generated_at: new Date().toISOString() })
   // Log the code so developers can read it during dev testing.
   // eslint-disable-next-line no-console
   console.log(`[OTP STUB] phone=${phone} channel=${channel} code=${code} ref=${reference}`)