Integration Guide

Browser  ──►  Your API route  ──►  Truest Human  POST /api/dkba
   ▲               │
   │               ▼
   │        Your database  (questions + answer key stay here)
   │               │
   └───────────────┘
     one question at a time, no answer key ever leaves your server

// lib/dkba-schemas.ts
import { z } from "zod";

// What you SEND. Validate it before every call so a malformed payload
// fails in your code instead of as a wasted (billed) API round-trip.
export const dkbaRequestSchema = z.object({
  firstName: z.string(),
  middleName: z.string().optional(),
  lastName: z.string(),
  generation: z.string().optional(),
  street: z.string(),
  city: z.string(),
  state: z.string(),
  zipCode: z.string(),
  dateOfBirth: z.string(),                 // "YYYY-MM-DD"
  ssn: z.string(),                         // last 4 digits only
  phoneNumber: z.string().nullable().optional(),
  emailAddress: z.string().optional(),
  ipAddress: z.string().optional(),
});
export type DkbaRequest = z.infer<typeof dkbaRequestSchema>;

// What you RECEIVE. Note the isCorrect flag on every answer — that is the
// answer key. It must stay on your server (see "Present questions safely").
const evsAnswer = z.object({ text: z.string(), isCorrect: z.boolean() });
const evsQuestion = z.object({
  text: z.string(),
  questionType: z.number(),
  answers: z.array(evsAnswer),
});
const evsResult = z.object({ code: z.string(), description: z.string().optional() });

const dkbaSuccess = z.object({
  ok: z.literal(true),
  data: z.object({
    kbaQuestions: z.object({ questions: z.array(evsQuestion) }),
    workflowOutcome: evsResult,            // code: "P" | "R" | "F"
    dkba: z.object({
      consumerIdDetail: z.object({ /* name + address on file */ }).optional(),
      dateOfBirthResult: evsResult,
      phoneVerificationResult: evsResult,
      socialSecurityNumberResult: evsResult,
    }),
  }),
});
const dkbaFailure = z.object({ ok: z.literal(false), errorMessage: z.string() });

export const dkbaResponseSchema = z.union([dkbaSuccess, dkbaFailure]);
export type DkbaResponse = z.infer<typeof dkbaResponseSchema>;

// lib/request-dkba.ts
import {
  DkbaRequest,
  dkbaRequestSchema,
  dkbaResponseSchema,
} from "./dkba-schemas";

export async function requestDkba(request: DkbaRequest) {
  const payload = dkbaRequestSchema.parse(request); // validate what you SEND

  const endpoint = process.env.TRUEST_HUMAN_API_ENDPOINT;
  const apiKey = process.env.TRUEST_HUMAN_API_KEY;
  if (!endpoint) throw new Error("TRUEST_HUMAN_API_ENDPOINT is not defined");
  if (!apiKey) throw new Error("TRUEST_HUMAN_API_KEY is not defined");

  const response = await fetch(`${endpoint}/dkba`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: apiKey, // no "Bearer" prefix
    },
    body: JSON.stringify(payload),
  });

  const json: unknown = await response.json();
  const parsed = dkbaResponseSchema.parse(json); // validate what you RECEIVE

  if (!parsed.ok) throw new Error(parsed.errorMessage);
  return parsed;
}

TRUEST_HUMAN_API_KEY=th_test_your_key_here
TRUEST_HUMAN_API_ENDPOINT=https://truesthuman.com/api

// app/api/verify/route.ts — look up identity, then store the questions
import { NextResponse } from "next/server";
import { requestDkba } from "@/lib/request-dkba";
// ...your own db, auth, id + shuffle helpers

export async function POST(request: Request) {
  const currentUser = await getCurrentUser(); // authenticate YOUR user first
  const body = await request.json();

  // Already have questions for this user? Serve the next stored one instead
  // of paying for a second lookup that would return the same answer.
  const existing = await db.query.question.findMany({
    where: eq(question.userId, currentUser.id),
  });
  if (existing.length > 0) {
    return NextResponse.json({
      ok: true,
      question: await getNextCleanQuestion(currentUser),
    });
  }

  const result = await requestDkba({
    firstName: currentUser.firstName,
    lastName: currentUser.lastName,
    middleName: currentUser.middleName ?? undefined,
    street: [body.addressLine1, body.addressLine2].filter(Boolean).join(" "),
    city: body.city,
    state: body.state,
    zipCode: body.zipCode,
    dateOfBirth: currentUser.dateOfBirth, // "YYYY-MM-DD"
    ssn: currentUser.ssn,                 // last 4 digits
    phoneNumber: currentUser.phoneNumber,
    ipAddress: getIpAddress(request),
  });

  // 1) Did we positively identify the person? Require BOTH a passing
  //    workflow code AND an identity record on file.
  const codePassed = ["P", "R"].includes(result.data.workflowOutcome.code);
  const idPassed = result.data.dkba.consumerIdDetail != null;
  if (!codePassed || !idPassed) {
    // First identity failure: allow one more attempt. Second: block.
    if (currentUser.dkbaCodeFailed) {
      await db.update(user).set({ blocked: true }).where(eq(user.id, currentUser.id));
      return NextResponse.json({ ok: true, blocked: true });
    }
    await db.update(user).set({ dkbaCodeFailed: true }).where(eq(user.id, currentUser.id));
    return NextResponse.json({ ok: true, retry: true });
  }

  // 2) Thin file: the identity is real but there are no questions to ask.
  //    Persist it so you never re-charge for the same dead-end lookup.
  const questions = result.data.kbaQuestions.questions;
  if (questions.length === 0) {
    await db.update(user).set({ dkbaNoQuestions: true }).where(eq(user.id, currentUser.id));
    return NextResponse.json({ ok: true, noQuestions: true });
  }

  // 3) Store every question and its options. Keep the correct flag in your
  //    DB — it is the answer key and must never reach the browser.
  for (const [index, q] of shuffle(questions).entries()) {
    const questionId = createId();
    await db.insert(question).values({
      id: questionId,
      prompt: q.text,
      priority1: q.questionType,
      priority2: index,
      userId: currentUser.id,
    });
    await db.insert(questionOption).values(
      q.answers.map((a) => ({
        id: createId(),
        questionId,
        text: a.text,
        correct: a.isCorrect, // stored server-side ONLY
      })),
    );
  }

  return NextResponse.json({
    ok: true,
    question: await getNextCleanQuestion(currentUser),
  });
}

// lib/clean-question.ts — turn a stored question into something safe to send
import shuffle from "./shuffle";

export function cleanQuestion(props: { number: number; question: StoredQuestion }) {
  const correct = props.question.options.find((o) => o.correct);
  if (!correct) throw new Error("Question has no correct option");

  const incorrect = props.question.options.filter((o) => !o.correct);
  if (incorrect.length < 2) throw new Error("Need at least two distractors");

  // One correct option + up to four distractors, then shuffle so the
  // position of the answer does not leak it.
  const display = shuffle([correct, ...incorrect.slice(0, 4)]);

  // Build an EXPLICIT object. Never spread the DB row — that would ship
  // every option's correct flag (the answer key) to the browser.
  return {
    id: props.question.id,
    number: props.number,
    prompt: props.question.prompt,
    options: display.map((o) => o.text), // text only, never the correct flag
  };
}

// app/api/timer/route.ts — start the round clock
export async function POST() {
  const currentUser = await getCurrentUser();
  if (currentUser.dkbaVerified) throw new ApiError(400, "Already verified");

  // Idempotent: if a deadline already exists (refresh, second tab), return
  // it instead of resetting the clock and giving the user free time.
  if (currentUser.roundDeadline) {
    return NextResponse.json({
      ok: true,
      roundDeadline: new Date(currentUser.roundDeadline).getTime(),
      question: await getNextCleanQuestion(currentUser),
    });
  }

  // Two minutes to complete the round.
  const roundDeadline = new Date();
  roundDeadline.setMinutes(roundDeadline.getMinutes() + 2);

  const question = await getNextCleanQuestion(currentUser);
  await db
    .update(user)
    .set({ dkbaStarted: true, roundDeadline })
    .where(eq(user.id, currentUser.id));

  return NextResponse.json({
    ok: true,
    roundDeadline: roundDeadline.getTime(),
    question,
  });
}

// components/round-timer.tsx — DISPLAY ONLY; the server owns the real deadline
"use client";
import { useEffect, useRef, useState } from "react";

export function RoundTimer(props: { seconds: number; onExpire: () => void }) {
  const [seconds, setSeconds] = useState(props.seconds);
  const firedRef = useRef(false); // fire onExpire at most once

  useEffect(() => {
    const interval = setInterval(() => {
      setSeconds((prev) => {
        if (prev < 1) {
          clearInterval(interval);
          if (!firedRef.current) {
            firedRef.current = true;
            props.onExpire(); // POST to your time-out route — server decides
          }
          return 0;
        }
        return prev - 1;
      });
    }, 1000);
    return () => clearInterval(interval);
  }, [props]);

  const m = Math.floor(seconds / 60);
  const s = Math.floor(seconds % 60).toString().padStart(2, "0");
  // seconds is derived from the server deadline minus now; render only.
  return <div suppressHydrationWarning>{m}:{s}</div>;
}

// app/api/time-out/route.ts — the SERVER decides whether time is up
export async function POST() {
  const currentUser = await getCurrentUser();
  if (currentUser.dkbaVerified) {
    return NextResponse.json({ ok: true, round2: currentUser.round2 });
  }
  if (!currentUser.roundDeadline) throw new ApiError(400, "No round deadline");

  // Never trust the client clock. Re-check the deadline here, or a user
  // could POST early to skip questions and jump to a fresh round.
  if (new Date(currentUser.roundDeadline) > new Date()) {
    throw new ApiError(400, "Round has not expired yet");
  }

  const questions = await db.query.question.findMany({
    where: eq(question.userId, currentUser.id),
    with: { questionOptions: true },
  });
  return handleRoundTimeout({
    questions,
    round2: currentUser.round2,
    userId: currentUser.id,
  });
}

// app/api/cron/expire-kba-rounds/route.ts — catch abandoned tabs
export const maxDuration = 60;

export async function GET(request: Request) {
  // The interactive timeout only fires while the verify page stays open.
  // A user who closes the tab leaves an expired deadline that never
  // resolves — so sweep them on a schedule (e.g. a Vercel Cron every minute).
  const secret = process.env.CRON_SECRET;
  if (request.headers.get("authorization") !== `Bearer ${secret}`) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const expired = await db.query.user.findMany({
    where: and(
      isNotNull(user.roundDeadline),
      lt(user.roundDeadline, new Date()),
      eq(user.dkbaVerified, false),
      eq(user.blocked, false),
    ),
    columns: { id: true, round2: true },
  });

  for (const u of expired) {
    const questions = await db.query.question.findMany({
      where: eq(question.userId, u.id),
      with: { questionOptions: true },
    });
    // Same handler the interactive route uses. Idempotent: it clears
    // roundDeadline, so a processed user drops out of the next sweep.
    await handleRoundTimeout({ questions, round2: u.round2, userId: u.id });
  }

  return NextResponse.json({ processed: expired.length });
}

// app/api/answer/route.ts — score one answer, then advance or finish the round
export async function POST(request: Request) {
  const currentUser = await getCurrentUser();
  if (currentUser.blocked) throw new ApiError(403, "User is blocked");
  if (currentUser.dkbaVerified) {
    return NextResponse.json({ ok: true, dkbaVerified: true, round2: currentUser.round2 });
  }
  if (!currentUser.roundDeadline) throw new ApiError(500, "No round deadline");

  // Check the deadline BEFORE recording the answer, so a late submission
  // cannot sneak in past the timer.
  if (new Date(currentUser.roundDeadline) < new Date()) {
    const questions = await loadQuestions(currentUser.id);
    return handleRoundTimeout({ questions, round2: currentUser.round2, userId: currentUser.id });
  }

  const { questionId, answer } = answerRequestSchema.parse(await request.json());
  const current = await getNextQuestion({ userId: currentUser.id, round2: currentUser.round2 });

  // Reject a client that is out of sync (stale tab, replay, race with timer).
  if (questionId !== current.id) {
    throw new ApiError(409, "Question mismatch: client and server are out of sync");
  }

  // Score against the DB — the browser never sent us the answer key.
  const correctOption = current.questionOptions.find((o) => o.correct);
  const correct = answer === correctOption?.text;
  await db
    .update(question)
    .set({ answered: true, everAnswered: true, correct })
    .where(eq(question.id, current.id));

  // Finished the 5 questions in this round?
  const answered = await answeredQuestionsThisRound(currentUser);
  if (answered.length === 5) {
    const passed = answered.filter((q) => q.correct).length >= 4; // 4 of 5

    if (!currentUser.round2) {
      // End of Round 1.
      if (passed) return markVerified(currentUser);
      return failRound({ userId: currentUser.id, questions: answered }); // -> Round 2
    }

    // End of Round 2.
    if (passed) return markVerified(currentUser);
    return resetToRoundOne(currentUser); // don't hard-block; let them retry
  }

  // Otherwise serve the next question in this round.
  return buildQuestionResponse({
    round2: currentUser.round2,
    number: answered.length + 1,
    question: await getNextQuestion(currentUser),
  });
}

provide details
  └─ identity lookup  (POST /api/dkba)
       ├─ Fail                → retry once, then BLOCK
       ├─ Thin file (0 Qs)    → contact support (no retry, no re-charge)
       └─ Pass                → store questions, start Round 1 (2:00)

           Round 1 · 5 questions · need 4 of 5
             ├─ Pass          → VERIFIED
             └─ Fail / timeout → Round 2 (2:00, fresh + recycled questions)

                 Round 2 · 5 questions · need 4 of 5
                   ├─ Pass          → VERIFIED
                   └─ Fail / timeout → reset to Round 1 (try again later)