feat: create managed profiles atomically

- Require a fresh cookie MFA proof before creation\n- Create the credential-less profile and initial Guardian grant together

src/app/api/managed-profiles/route.ts

@@ -0,0 +1,73 @@
+import { NextRequest } from "next/server";
+import { z } from "zod/v4";
+
+import {
+  apiHandler,
+  MFA_STEP_UP_MAX_AGE_SECONDS,
+  requireFreshMfa,
+} from "@/lib/api-handler";
+import { apiSuccess, returnAllZodIssues, safeJson } from "@/lib/api-response";
+import { auditLog } from "@/lib/auth/audit";
+import { createManagedProfile } from "@/lib/managed-profiles/create";
+import { annotate } from "@/lib/logging/context";
+import { isValidTimezone } from "@/lib/tz/format";
+
+const managedProfileSchema = z
+  .object({
+    displayName: z.string().trim().min(1).max(80),
+    dateOfBirth: z.iso.date().nullable().optional(),
+    locale: z.enum(["de", "en", "es", "fr", "it", "pl"]),
+    timezone: z
+      .string()
+      .min(1)
+      .max(64)
+      .refine(isValidTimezone, "Invalid IANA timezone"),
+  })
+  .strict();
+
+/**
+ * Create a record a Guardian administers. This deliberately uses the
+ * cookie-only fresh-MFA gate: a Bearer token cannot mint a credential-less
+ * person and persistent management relationship.
+ */
+export const POST = apiHandler(async (request: NextRequest) => {
+  const { user } = await requireFreshMfa(MFA_STEP_UP_MAX_AGE_SECONDS);
+  const { data: body, error: jsonError } = await safeJson(request, {
+    maxBytes: 64 * 1024,
+  });
+  if (jsonError) return jsonError;
+
+  const parsed = managedProfileSchema.safeParse(body);
+  if (!parsed.success) return returnAllZodIssues(parsed.error, 422);
+
+  const { profile, creatorGrant } = await createManagedProfile({
+    creatorId: user.id,
+    displayName: parsed.data.displayName,
+    dateOfBirth: parsed.data.dateOfBirth
+      ? new Date(`${parsed.data.dateOfBirth}T00:00:00.000Z`)
+      : null,
+    locale: parsed.data.locale,
+    timezone: parsed.data.timezone,
+  });
+
+  await auditLog("managed_profile.created", {
+    userId: user.id,
+    details: { profileId: profile.id, grantId: creatorGrant.id },
+  }).catch(() => {});
+  annotate({
+    action: { name: "managed_profile.create" },
+    meta: { profile_id: profile.id },
+  });
+
+  return apiSuccess(
+    {
+      id: profile.id,
+      displayName: profile.displayName,
+      dateOfBirth: profile.dateOfBirth,
+      locale: profile.locale,
+      timezone: profile.timezone,
+      recordKind: "managed" as const,
+    },
+    201,
+  );
+});

src/lib/managed-profiles/create.ts

@@ -0,0 +1,88 @@
+import { randomBytes } from "node:crypto";
+
+import { Prisma } from "@/generated/prisma/client";
+import type { AccountGrant, User } from "@/generated/prisma/client";
+import { prisma } from "@/lib/db";
+
+const USERNAME_ATTEMPTS = 4;
+
+export interface CreateManagedProfileInput {
+  creatorId: string;
+  displayName: string;
+  dateOfBirth: Date | null;
+  locale: string;
+  timezone: string;
+}
+
+export interface CreatedManagedProfile {
+  profile: User;
+  creatorGrant: AccountGrant;
+}
+
+export class ManagedProfileCreationError extends Error {
+  constructor() {
+    super("Unable to allocate a managed profile identity");
+    this.name = "ManagedProfileCreationError";
+  }
+}
+
+function managedUsername(): string {
+  return `managed-${randomBytes(18).toString("hex")}`;
+}
+
+function isUniqueViolation(error: unknown): boolean {
+  return (
+    error instanceof Prisma.PrismaClientKnownRequestError &&
+    error.code === "P2002"
+  );
+}
+
+/**
+ * Create the credential-less record and its first Guardian grant together.
+ *
+ * A profile is never useful before the creator can manage it, and a creator
+ * grant without its record is invalid by definition. Keeping both writes in
+ * one transaction makes a failed grant insert leave no login-less user behind.
+ */
+export async function createManagedProfile(
+  input: CreateManagedProfileInput,
+): Promise<CreatedManagedProfile> {
+  for (let attempt = 0; attempt < USERNAME_ATTEMPTS; attempt += 1) {
+    try {
+      return await prisma.$transaction(async (tx) => {
+        const now = new Date();
+        const profile = await tx.user.create({
+          data: {
+            username: managedUsername(),
+            email: null,
+            passwordHash: null,
+            displayName: input.displayName,
+            dateOfBirth: input.dateOfBirth,
+            locale: input.locale,
+            timezone: input.timezone,
+            managedProfileAt: now,
+          },
+        });
+        const creatorGrant = await tx.accountGrant.create({
+          data: {
+            grantorId: profile.id,
+            granteeId: input.creatorId,
+            access: "MANAGE",
+            scopeJson: Prisma.DbNull,
+            invitedAt: now,
+            acceptedAt: now,
+            expiresAt: null,
+          },
+        });
+        return { profile, creatorGrant };
+      });
+    } catch (error) {
+      if (isUniqueViolation(error) && attempt + 1 < USERNAME_ATTEMPTS) {
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  throw new ManagedProfileCreationError();
+}