HealthLog/src/app/api/auth/claim/route.ts

/**
 * `POST /api/auth/claim` — claim a managed profile through its handover link
 * (v1.42, #959). The person the profile describes sets a username, an email
 * and a password, and the profile becomes their own account. No data moves.
 *
 * Anonymous by design: the claimant has no credentials yet, and the one-time
 * `hlp_` token in the BODY is what authorises the request. The order of the
 * work is the registration route's, for the same reasons:
 *
 *   1. refusals that read no token (`claimGate`: SSO-only, live session, rate
 *      limit);
 *   2. the body, strictly parsed, and the link checked;
 *   3. the username and email collision probe, before any expensive work;
 *   4. password strength, the breach corpus, the Argon2id hash — outside the
 *      lock, because none of it depends on the profile;
 *   5. the claim itself, one transaction under the managed-profile lock
 *      (`claimManagedProfile`), where the token is consumed;
 *   6. after the commit: the session, the device record, and a notification
 *      to each former Guardian on their own channels.
 *
 * A closed registration does not block a claim: no account is created, the
 * link is the door.
 */
import { NextRequest } from "next/server";

import { apiHandler } from "@/lib/api-handler";
import {
  apiError,
  apiSuccess,
  returnAllZodIssues,
  safeJson,
} from "@/lib/api-response";
import { auditLog } from "@/lib/auth/audit";
import { recordSignInDevice } from "@/lib/auth/login-alert";
import { checkPasswordStrength, hashPassword } from "@/lib/auth/password";
import { createSession, getSession } from "@/lib/auth/session";
import { prisma } from "@/lib/db";
import { getServerTranslator } from "@/lib/i18n/server-translator";
import { resolveServerLocale } from "@/lib/i18n/server-locale";
import { annotate } from "@/lib/logging/context";
import { claimGate, claimInvalid } from "@/lib/managed-profiles/claim-gate";
import {
  claimManagedProfile,
  HandoverError,
  previewHandover,
} from "@/lib/managed-profiles/handover";
import { notifyGuardiansOfHandover } from "@/lib/managed-profiles/handover-notify";
import { checkPasswordBreachIfEnabled } from "@/lib/password-breach-check";
import { claimSchema } from "@/lib/validations/managed-profile-handover";

const taken = () =>
  apiError("Username or email already taken", 409, {
    errorCode: "profile_claim.taken",
  });

export const POST = apiHandler(async (request: NextRequest) => {
  // Refuses to claim over a live session — see `claimGate`.
  const gate = await claimGate(request, "claim", (await getSession()) !== null);
  if (gate.refusal) return gate.refusal;
  const ip = gate.ip ?? "unknown";

  const { data: body, error: jsonError } = await safeJson(request, {
    maxBytes: 16 * 1024,
  });
  if (jsonError) return jsonError;
  const parsed = claimSchema.safeParse(body);
  if (!parsed.success) return returnAllZodIssues(parsed.error, 422);
  const { token, username, email, password } = parsed.data;

  // The link first. Without this the collision probe below would answer 409
  // to anybody, token or not, and the claim route would be a username and
  // email oracle that registration being closed does not close. With it, only
  // the holder of a live link learns that a name is taken. The claim re-checks
  // everything under the lock; this read decides nothing on its own.
  if (!(await previewHandover(token))) return claimInvalid();

  // Before the strength check, the breach lookup and the hash, exactly as the
  // registration route orders it (its comment carries the timing argument).
  // The profile's own row never collides here: its username is the generated
  // `managed-…` one, which no chosen name may start with, and it has no email.
  const [existingEmail, existingUsername] = await Promise.all([
    prisma.user.findUnique({ where: { email }, select: { id: true } }),
    prisma.user.findUnique({ where: { username }, select: { id: true } }),
  ]);
  if (existingEmail || existingUsername) return taken();

  const locale = await resolveServerLocale({ request });
  const strength = checkPasswordStrength(password, [username, email], locale);
  if (!strength.isAcceptable) {
    return apiError(
      strength.feedback[0] || "Password too weak (score < 3)",
      422,
    );
  }
  const breach = await checkPasswordBreachIfEnabled(password);
  if (breach?.breached) {
    return apiError(
      getServerTranslator(locale).t("auth.passwordBreached"),
      422,
    );
  }
  const passwordHash = await hashPassword(password);

  let claimed;
  try {
    claimed = await claimManagedProfile({
      link: { rawToken: token },
      username,
      email,
      passwordHash,
      ipAddress: ip,
    });
  } catch (error) {
    if (error instanceof HandoverError) {
      annotate({
        action: { name: "profile_claim.refused" },
        meta: { reason: error.code },
      });
      return error.code === "taken" ? taken() : claimInvalid();
    }
    throw error;
  }

  // The new owner starts with onboarding owed: the claim reset it, because
  // the disclaimer and the setup were a Guardian's answers, not theirs.
  const ua = request.headers.get("user-agent");
  await createSession(claimed.profileId, true, ip, ua);
  void recordSignInDevice({
    userId: claimed.profileId,
    ip,
    userAgent: ua,
    alertOnNew: false,
  });
  await auditLog("auth.claim", {
    userId: claimed.profileId,
    actorUserId: null,
    ipAddress: ip,
    details: { method: "password" },
  });

  notifyGuardiansOfHandover("claimed", claimed.displayName, claimed.guardians);

  annotate({
    action: { name: "profile_claim.complete" },
    meta: { guardians: claimed.guardians.length },
  });
  return apiSuccess(
    { userId: claimed.profileId, username: claimed.username },
    201,
  );
});