@stardeck-customer-apps/testing 0.15.0 → 0.16.0

package/SKILL.md

@@ -341,6 +341,37 @@ externalId })` helper models a trusted platform/channel link, and
   `.merge(sourceId, canonicalId)` models governed merge redirects. They are
   setup helpers only; deployed app code cannot create verified links or merge
   identities through the integrations SDK.
+- **Profile connections** (`client.identities.claims`) are driven from the same
+  accessor: `.claims()` and `.claim(claimId)` inspect what the app opened;
+  `.enableStaffAssist()` turns on the org opt-in that `assist`/`transfer` claims
+  need (off by default, so an un-opted project gets the real 403);
+  `.completeClaim(claimId, { clerkUserId })` models the customer finishing the
+  platform-hosted flow; `.refuseClaim(claimId, reason)` models reception or the
+  platform turning one down. `completeClaim` flips the claimed contact to
+  `verified`, or records `invalidated` when the contact is no longer on that
+  profile and `refused` / `contact_owned` when someone else already proved it.
+  Completing a finished claim replays the recorded result. It does not attach a
+  login or move history — the platform's merge core is not modelled.
+  `.allowReturnOrigin(origin)` widens the allowed `returnTo` origins (the test
+  app's own origin is allowed by default); a `returnTo` anywhere else is dropped
+  silently, exactly as the platform drops it. `claimUrl` carries a one-time
+  opaque handle, so never assert it contains the claim id, and `deliver: true`
+  comes back as `delivered`. `.suppressClaimDelivery()` models the platform
+  sending nothing (a suppressed quota, a bounced address): `deliver: true` then
+  returns `delivered: false` with the `claimUrl` still valid, so the app's own
+  fallback delivery can be tested.
+
+  ```ts
+  const claim = await integrations.identities.claims.create({
+    flow: "invite",
+    identityId: person.id,
+    kind: "phone",
+    externalId: "+15550100",
+  });
+  app.identities.completeClaim(claim.claimId, { clerkUserId: "user_1" });
+  expect((await integrations.identities.claims.get(claim.claimId)).state).toBe("completed");
+  ```
+
 - `app.payments` — checkouts created through payments-sdk:
   `.checkouts`, `.latest()`, `.setProducts()`, `.markPaid(id)`,
   `.setSessionStatus(id, status)`, `.setPaymentLinkStatus(id, status)`,
@@ -409,11 +440,16 @@ describe the code, and the owner can't tell from them what is or isn't covered.
   A–Z→a–z; Turkish İ is left unchanged), requires E.164 phone values, and
   always writes an unverified link. A guest lookup of a verified link returns
   `{ identityId: null, reason: "verified_conflict" }`; staff provenance may
-  resolve either verified or unverified links. `attachLink` accepts only
-  channel kinds (line/facebook/instagram/email/phone); login keys must be
-  seeded via `app.identities.seedVerifiedLink`. `attachLink(..., { verified:
+  resolve either verified or unverified links. `attachLink` records a contact or
+  channel id (line/facebook/instagram/email/phone); login keys must be seeded
+  via `app.identities.seedVerifiedLink`. `attachLink(..., { verified:
 true })` remains source-compatible but the simulator (like the control plane)
-  ignores that flag and returns `verified: false`. `update` replaces the
+  ignores that flag and returns `verified: false`. An **unverified** email or
+  phone may be recorded on several identities (a household sharing one number);
+  a verified holder makes a further _verified_ attach conflict, but unverified
+  copies still succeed, and `resolveOrCreate` prefers the verified owner and
+  otherwise the earliest unverified holder. Channel and login kinds stay
+  single-owner and 409 on a second holder. `update` replaces the
   `profile` object (not a merge), like the control plane. Inspect via
   `app.identities`; merge/archive are privileged setup operations, with only
   test-only merge modeling exposed above.

package/dist/index.d.mts

@@ -105,6 +105,32 @@ interface CapturedIdentityLink {
  * the control plane that `client.identities` talks to in tests. Identities and
  * links created by app code under test land here; assert on them like `inbox`.
  */
+interface CapturedIdentityClaim {
+    claimId: string;
+    flow: "invite" | "assist" | "transfer";
+    /** The profile the claim connects the customer to. */
+    identityId: string;
+    kind: "email" | "phone";
+    externalId: string;
+    returnTo: string | null;
+    /** The app's reference for the staff member, for assist/transfer claims. */
+    staffActorRef: string | null;
+    state: "pending" | "completed" | "expired" | "invalidated" | "refused";
+    refusalReason: string | null;
+    completedIdentityId: string | null;
+    /** Set by completeClaim; models the Clerk account that proved the contact. */
+    claimantClerkUserId: string | null;
+    /**
+     * Hosted claim link. Its path carries a one-time opaque handle, NOT the claim
+     * id — the platform never makes the customer's page derivable from an id an
+     * app already holds.
+     */
+    claimUrl: string;
+    /** Whether the platform sent the link itself (only when `deliver` was asked). */
+    delivered: boolean | null;
+    expiresAt: string;
+    createdAt: string;
+}
 interface TestDirectory {
     /** All identities, oldest first. */
     all(): CapturedIdentity[];
@@ -126,6 +152,43 @@ interface TestDirectory {
      * identity. The production integrations SDK does not expose merge operations.
      */
     merge(sourceIdentityId: string, canonicalIdentityId: string): void;
+    /** Every profile-connection claim the app has opened, oldest first. */
+    claims(): CapturedIdentityClaim[];
+    /** A single claim by id, or undefined. */
+    claim(claimId: string): CapturedIdentityClaim | undefined;
+    /**
+     * Test setup only: turn on the org's staff-assistance opt-in. Without it,
+     * `claims.create` refuses `assist` and `transfer` with 403, like the platform.
+     */
+    enableStaffAssist(enabled?: boolean): void;
+    /**
+     * Test setup only: model the platform failing to send a claim link it was
+     * asked to deliver (a suppressed quota, a bounced address). `deliver: true`
+     * then comes back `delivered: false` with the `claimUrl` still valid, so an
+     * app's own fallback delivery can be tested.
+     */
+    suppressClaimDelivery(enabled?: boolean): void;
+    /**
+     * Test setup only: allow a claim `returnTo` on this origin. The harness app's
+     * own origin is allowed by default; anything else is dropped silently, like
+     * the platform's allowed-origins check.
+     */
+    allowReturnOrigin(origin: string): void;
+    /**
+     * Test setup only: model the customer finishing the platform-hosted claim —
+     * Clerk proof plus their confirmation. Flips the claimed contact to verified,
+     * or records `invalidated` (the contact was removed from that profile) or
+     * `refused` with `contact_owned` (someone else already proved it). Replaying a
+     * finished claim returns the recorded result unchanged.
+     *
+     * It does NOT attach a login link or move history: the platform's merge core
+     * is not modelled here, only the ownership decision the app can observe.
+     */
+    completeClaim(claimId: string, params: {
+        clerkUserId: string;
+    }): CapturedIdentityClaim;
+    /** Test setup only: model reception or the platform refusing a claim. */
+    refuseClaim(claimId: string, reason: string): CapturedIdentityClaim;
     clear(): void;
     get count(): number;
 }

package/dist/index.d.ts

@@ -105,6 +105,32 @@ interface CapturedIdentityLink {
  * the control plane that `client.identities` talks to in tests. Identities and
  * links created by app code under test land here; assert on them like `inbox`.
  */
+interface CapturedIdentityClaim {
+    claimId: string;
+    flow: "invite" | "assist" | "transfer";
+    /** The profile the claim connects the customer to. */
+    identityId: string;
+    kind: "email" | "phone";
+    externalId: string;
+    returnTo: string | null;
+    /** The app's reference for the staff member, for assist/transfer claims. */
+    staffActorRef: string | null;
+    state: "pending" | "completed" | "expired" | "invalidated" | "refused";
+    refusalReason: string | null;
+    completedIdentityId: string | null;
+    /** Set by completeClaim; models the Clerk account that proved the contact. */
+    claimantClerkUserId: string | null;
+    /**
+     * Hosted claim link. Its path carries a one-time opaque handle, NOT the claim
+     * id — the platform never makes the customer's page derivable from an id an
+     * app already holds.
+     */
+    claimUrl: string;
+    /** Whether the platform sent the link itself (only when `deliver` was asked). */
+    delivered: boolean | null;
+    expiresAt: string;
+    createdAt: string;
+}
 interface TestDirectory {
     /** All identities, oldest first. */
     all(): CapturedIdentity[];
@@ -126,6 +152,43 @@ interface TestDirectory {
      * identity. The production integrations SDK does not expose merge operations.
      */
     merge(sourceIdentityId: string, canonicalIdentityId: string): void;
+    /** Every profile-connection claim the app has opened, oldest first. */
+    claims(): CapturedIdentityClaim[];
+    /** A single claim by id, or undefined. */
+    claim(claimId: string): CapturedIdentityClaim | undefined;
+    /**
+     * Test setup only: turn on the org's staff-assistance opt-in. Without it,
+     * `claims.create` refuses `assist` and `transfer` with 403, like the platform.
+     */
+    enableStaffAssist(enabled?: boolean): void;
+    /**
+     * Test setup only: model the platform failing to send a claim link it was
+     * asked to deliver (a suppressed quota, a bounced address). `deliver: true`
+     * then comes back `delivered: false` with the `claimUrl` still valid, so an
+     * app's own fallback delivery can be tested.
+     */
+    suppressClaimDelivery(enabled?: boolean): void;
+    /**
+     * Test setup only: allow a claim `returnTo` on this origin. The harness app's
+     * own origin is allowed by default; anything else is dropped silently, like
+     * the platform's allowed-origins check.
+     */
+    allowReturnOrigin(origin: string): void;
+    /**
+     * Test setup only: model the customer finishing the platform-hosted claim —
+     * Clerk proof plus their confirmation. Flips the claimed contact to verified,
+     * or records `invalidated` (the contact was removed from that profile) or
+     * `refused` with `contact_owned` (someone else already proved it). Replaying a
+     * finished claim returns the recorded result unchanged.
+     *
+     * It does NOT attach a login link or move history: the platform's merge core
+     * is not modelled here, only the ownership decision the app can observe.
+     */
+    completeClaim(claimId: string, params: {
+        clerkUserId: string;
+    }): CapturedIdentityClaim;
+    /** Test setup only: model reception or the platform refusing a claim. */
+    refuseClaim(claimId: string, reason: string): CapturedIdentityClaim;
     clear(): void;
     get count(): number;
 }

package/dist/index.js

@@ -106,6 +106,31 @@ function globalSingleton(key, create) {
   return holder[symbol];
 }
 
+// src/constants.ts
+var TEST_DOMAIN_SUFFIX = ".stardeck.test";
+var CONTROL_PLANE_TEST_URL = "https://control-plane.stardeck.test";
+var DATA_STORE_TEST_HOST = "db.stardeck.test";
+var DATA_STORE_TEST_URL = `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`;
+var STORAGE_TEST_URL = "https://storage.stardeck.test";
+var STORAGE_TEST_HOST = "storage.stardeck.test";
+var APP_TEST_ORIGIN = "http://localhost:3333";
+var TEST_ENV_DEFAULTS = {
+  CONTROL_PLANE_URL: CONTROL_PLANE_TEST_URL,
+  DEPLOYMENT_SECRET: "stardeck-test-deployment-secret",
+  ORGANIZATION_ID: "00000000-0000-4000-8000-00000000000a",
+  PROJECT_ID: "00000000-0000-4000-8000-00000000000b",
+  DEPLOYMENT_ID: "00000000-0000-4000-8000-00000000000c",
+  STORAGE_URL: STORAGE_TEST_URL
+};
+var DEFAULT_TEST_USER = {
+  id: "test-user-1",
+  email: "test-user@example.com",
+  name: "Test User",
+  role: "member",
+  permissions: []
+};
+var DEFAULT_SCHEMA_PATH = "./src/generated/data-store-schema.sql";
+
 // src/state.ts
 var state = globalSingleton("state", () => ({
   db: null,
@@ -117,6 +142,10 @@ var state = globalSingleton("state", () => ({
   emailCounter: 0,
   identities: /* @__PURE__ */ new Map(),
   identityLinks: [],
+  identityClaims: /* @__PURE__ */ new Map(),
+  identityStaffAssistEnabled: false,
+  identitySuppressClaimDelivery: false,
+  identityAllowedReturnOrigins: /* @__PURE__ */ new Set([APP_TEST_ORIGIN]),
   checkouts: [],
   checkoutCounter: 0,
   sessionStatuses: /* @__PURE__ */ new Map(),
@@ -158,30 +187,6 @@ function requireDb() {
   return state.db;
 }
 
-// src/constants.ts
-var TEST_DOMAIN_SUFFIX = ".stardeck.test";
-var CONTROL_PLANE_TEST_URL = "https://control-plane.stardeck.test";
-var DATA_STORE_TEST_HOST = "db.stardeck.test";
-var DATA_STORE_TEST_URL = `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`;
-var STORAGE_TEST_URL = "https://storage.stardeck.test";
-var STORAGE_TEST_HOST = "storage.stardeck.test";
-var TEST_ENV_DEFAULTS = {
-  CONTROL_PLANE_URL: CONTROL_PLANE_TEST_URL,
-  DEPLOYMENT_SECRET: "stardeck-test-deployment-secret",
-  ORGANIZATION_ID: "00000000-0000-4000-8000-00000000000a",
-  PROJECT_ID: "00000000-0000-4000-8000-00000000000b",
-  DEPLOYMENT_ID: "00000000-0000-4000-8000-00000000000c",
-  STORAGE_URL: STORAGE_TEST_URL
-};
-var DEFAULT_TEST_USER = {
-  id: "test-user-1",
-  email: "test-user@example.com",
-  name: "Test User",
-  role: "member",
-  permissions: []
-};
-var DEFAULT_SCHEMA_PATH = "./src/generated/data-store-schema.sql";
-
 // src/simulator/hmac.ts
 var import_node_crypto = __toESM(require("crypto"));
 var TIMESTAMP_TOLERANCE_SECONDS = 300;
@@ -232,8 +237,8 @@ function json(body, status = 200) {
 function success(data) {
   return json({ success: true, data });
 }
-function failure(error, status = 400) {
-  return json({ success: false, error }, status);
+function failure(error, status = 400, code) {
+  return json({ success: false, error, ...code ? { code } : {} }, status);
 }
 async function readJsonBody(request) {
   try {
@@ -721,6 +726,12 @@ var TRUSTED_LINK_KINDS = /* @__PURE__ */ new Set([
   "dashboard_user"
 ]);
 var RESOLVE_KINDS = /* @__PURE__ */ new Set(["phone", "email", "line"]);
+var CLAIM_KINDS = /* @__PURE__ */ new Set(["email", "phone"]);
+var CLAIM_FLOWS = /* @__PURE__ */ new Set(["invite", "assist", "transfer"]);
+var DUPLICABLE_UNVERIFIED_KINDS = /* @__PURE__ */ new Set(["email", "phone"]);
+var CLAIM_TTL_MS = 48 * 60 * 60 * 1e3;
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var STAFF_ASSISTANCE_NOT_ENABLED = "STAFF_ASSISTANCE_NOT_ENABLED";
 var E164_PHONE = /^\+[1-9]\d{1,14}$/;
 var SEARCH_DEFAULT_LIMIT = 50;
 var SEARCH_MAX_LIMIT = 100;
@@ -803,6 +814,11 @@ function matchingLinks(kind, externalId) {
     (link) => link.kind === kind && comparableExternalId(link.kind, link.externalId) === comparable
   );
 }
+function sortedMatchingLinks(kind, externalId) {
+  return matchingLinks(kind, externalId).sort(
+    (a, b) => Number(b.verified) - Number(a.verified) || a.createdAt.localeCompare(b.createdAt) || state.identityLinks.indexOf(a) - state.identityLinks.indexOf(b)
+  );
+}
 function normalizedLinkKey(link) {
   return `${link.kind}:${comparableExternalId(link.kind, link.externalId)}`;
 }
@@ -916,9 +932,10 @@ async function handleAttachLink(identityId, request) {
   );
   if ("error" in normalized) return failure(normalized.error);
   const { kind, externalId } = normalized;
-  const [existing] = matchingLinks(kind, externalId);
-  if (existing) {
-    if (existing.identityId === identityId) return success({ link: existing });
+  const matches = matchingLinks(kind, externalId);
+  const ownRow = matches.find((link2) => link2.identityId === identityId);
+  if (ownRow) return success({ link: ownRow });
+  if (!DUPLICABLE_UNVERIFIED_KINDS.has(kind) && matches.length > 0) {
     return failure("identifier already linked to another identity", 409);
   }
   const link = createUnverifiedLink(identityId, kind, externalId);
@@ -935,7 +952,7 @@ async function handleResolve(request) {
   if (body.displayName !== void 0 && typeof body.displayName !== "string") {
     return failure("displayName must be a string");
   }
-  const links = matchingLinks(normalized.kind, normalized.externalId);
+  const links = sortedMatchingLinks(normalized.kind, normalized.externalId);
   if (links.length > 0) {
     const canonicalIds = /* @__PURE__ */ new Set();
     for (const link of links) {
@@ -946,12 +963,15 @@ async function handleResolve(request) {
         return failure(`cannot resolve identity link: ${message}`, 409);
       }
     }
-    if (canonicalIds.size !== 1) {
+    const verifiedOwners = new Set(
+      links.filter((link) => link.verified).map((link) => link.identityId)
+    );
+    if (verifiedOwners.size > 1 || !DUPLICABLE_UNVERIFIED_KINDS.has(normalized.kind) && canonicalIds.size !== 1) {
       return failure("identifier is linked to multiple identities", 409);
     }
-    const canonicalId = [...canonicalIds][0];
-    const hasVerifiedLink = links.some((link) => link.verified);
-    if (provenance === "guest" && hasVerifiedLink) {
+    const [chosen] = links;
+    const canonicalId = canonicalIdentity(chosen.identityId).id;
+    if (provenance === "guest" && chosen.verified) {
       return success({ identityId: null, reason: "verified_conflict" });
     }
     return success({ identityId: canonicalId, created: false });
@@ -1053,6 +1073,116 @@ async function handleAliases(request) {
   }
   return success({ aliases });
 }
+function claimView(claim) {
+  const state_ = claim.state === "pending" && Date.parse(claim.expiresAt) <= Date.now() ? "expired" : claim.state;
+  return {
+    claimId: claim.claimId,
+    flow: claim.flow,
+    state: state_,
+    refusalReason: claim.refusalReason,
+    completedIdentityId: claim.completedIdentityId,
+    expiresAt: claim.expiresAt
+  };
+}
+function validateClaimStaff(flow, staff) {
+  if (flow === "invite") {
+    if (staff !== void 0) return { error: "staff is only accepted for assist or transfer" };
+    return { staffActorRef: null };
+  }
+  if (!staff || typeof staff !== "object") {
+    return { error: `staff is required for a ${flow} claim` };
+  }
+  const { actorRef, grant } = staff;
+  if (typeof actorRef !== "string" || actorRef.length === 0) {
+    return { error: "staff.actorRef is required" };
+  }
+  if (grant !== flow) return { error: `staff.grant must be '${flow}' for a ${flow} claim` };
+  return { staffActorRef: actorRef };
+}
+async function handleCreateClaim(request) {
+  const body = await readJsonBody(request);
+  const flow = body.flow;
+  if (typeof flow !== "string" || !CLAIM_FLOWS.has(flow)) {
+    return failure("flow must be one of: invite, assist, transfer");
+  }
+  if (typeof body.identityId !== "string" || !UUID.test(body.identityId)) {
+    return failure("identityId must be a uuid");
+  }
+  const normalized = normalizeLinkInput(
+    body.kind,
+    body.externalId,
+    CLAIM_KINDS,
+    "kind must be one of: email, phone"
+  );
+  if ("error" in normalized) return failure(normalized.error);
+  let returnTo = null;
+  if (body.returnTo !== void 0) {
+    if (typeof body.returnTo !== "string") return failure("returnTo must be a string");
+    let parsed;
+    try {
+      parsed = new URL(body.returnTo);
+    } catch {
+      return failure("returnTo must be an absolute URL");
+    }
+    returnTo = state.identityAllowedReturnOrigins.has(parsed.origin) ? body.returnTo : null;
+  }
+  if (body.deliver !== void 0 && typeof body.deliver !== "boolean") {
+    return failure("deliver must be a boolean");
+  }
+  const staff = validateClaimStaff(flow, body.staff);
+  if ("error" in staff) return failure(staff.error);
+  if (flow !== "invite" && !state.identityStaffAssistEnabled) {
+    return failure(
+      "staff-assisted profile claiming is not enabled for this project",
+      403,
+      STAFF_ASSISTANCE_NOT_ENABLED
+    );
+  }
+  const identity = state.identities.get(body.identityId);
+  if (!identity || identity.type !== "person" || identity.status !== "active") {
+    return failure("identity not found", 404);
+  }
+  const holdsContact = matchingLinks(normalized.kind, normalized.externalId).some(
+    (link) => link.identityId === identity.id
+  );
+  if (!holdsContact) {
+    return failure("identity does not hold that contact", 409);
+  }
+  const claimId = import_node_crypto3.default.randomUUID();
+  const deliver = body.deliver === true;
+  const handle = import_node_crypto3.default.randomBytes(32).toString("base64url");
+  const claim = {
+    claimId,
+    flow,
+    identityId: identity.id,
+    kind: normalized.kind,
+    externalId: normalized.externalId,
+    returnTo,
+    staffActorRef: staff.staffActorRef,
+    state: "pending",
+    refusalReason: null,
+    completedIdentityId: null,
+    claimantClerkUserId: null,
+    claimUrl: `${CONTROL_PLANE_TEST_URL}/claim/${handle}`,
+    delivered: deliver ? !state.identitySuppressClaimDelivery : null,
+    expiresAt: new Date(Date.now() + CLAIM_TTL_MS).toISOString(),
+    createdAt: now()
+  };
+  state.identityClaims.set(claimId, claim);
+  return success({
+    claimId,
+    claimUrl: claim.claimUrl,
+    expiresAt: claim.expiresAt,
+    // Absent unless asked for: an app delivering its own link must not read a
+    // missing field as "nothing was sent".
+    ...deliver ? { delivered: claim.delivered } : {}
+  });
+}
+function handleGetClaim(claimId) {
+  const claim = state.identityClaims.get(claimId);
+  if (!claim) return failure("claim not found", 404);
+  return success(claimView(claim));
+}
 async function handleIdentitiesRequest(request, subPath) {
   const method = request.method;
   if (subPath === "" || subPath === "/") {
@@ -1068,6 +1198,13 @@ async function handleIdentitiesRequest(request, subPath) {
   if (subPath === "/search" && method === "GET") {
     return handleSearch(request);
   }
+  if (subPath === "/claims" && method === "POST") {
+    return handleCreateClaim(request);
+  }
+  const claimMatch = subPath.match(/^\/claims\/([^/]+)$/);
+  if (claimMatch && method === "GET") {
+    return handleGetClaim(decodeURIComponent(claimMatch[1]));
+  }
   const linksMatch = subPath.match(/^\/([^/]+)\/links$/);
   if (linksMatch && method === "POST") {
     return handleAttachLink(linksMatch[1], request);
@@ -1092,11 +1229,13 @@ function seedVerifiedLink(identityId, params) {
   );
   if ("error" in normalized) throw new Error(normalized.error);
   const { kind, externalId } = normalized;
-  const [existing] = matchingLinks(kind, externalId);
+  const matches = matchingLinks(kind, externalId);
+  const blocker = matches.find(
+    (link2) => link2.identityId !== identityId && (link2.verified || !DUPLICABLE_UNVERIFIED_KINDS.has(link2.kind))
+  );
+  if (blocker) throw new Error("identifier already linked to another identity");
+  const existing = matches.find((link2) => link2.identityId === identityId);
   if (existing) {
-    if (existing.identityId !== identityId) {
-      throw new Error("identifier already linked to another identity");
-    }
     existing.verified = true;
     return existing;
   }
@@ -1126,7 +1265,12 @@ function merge(sourceIdentityId, canonicalIdentityId) {
   );
   for (const sourceLink of sourceLinks) {
     const key = normalizedLinkKey(sourceLink);
-    if (otherLinks.some((otherLink) => normalizedLinkKey(otherLink) === key)) {
+    const conflicting = otherLinks.some(
+      (otherLink) => normalizedLinkKey(otherLink) === key && // Same partial rule as the index: a third identity's UNVERIFIED copy of a
+      // shared email/phone is allowed to coexist and must not block the merge.
+      (!DUPLICABLE_UNVERIFIED_KINDS.has(key.split(":")[0]) || otherLink.verified && sourceLink.verified)
+    );
+    if (conflicting) {
       throw new Error("merge would conflict with a link owned by another identity");
     }
   }
@@ -1153,6 +1297,45 @@ function merge(sourceIdentityId, canonicalIdentityId) {
   source.mergedIntoId = canonical.id;
   source.updatedAt = now();
 }
+function requireClaim(claimId) {
+  const claim = state.identityClaims.get(claimId);
+  if (!claim) throw new Error("claim not found");
+  return claim;
+}
+function completeClaim(claimId, params) {
+  const claim = requireClaim(claimId);
+  if (claim.state !== "pending") return claim;
+  if (Date.parse(claim.expiresAt) <= Date.now()) {
+    claim.state = "expired";
+    return claim;
+  }
+  if (!params.clerkUserId) throw new Error("clerkUserId is required");
+  const rows = matchingLinks(claim.kind, claim.externalId);
+  const target = rows.find((link) => link.identityId === claim.identityId);
+  if (!target) {
+    claim.state = "invalidated";
+    return claim;
+  }
+  const otherVerified = rows.find((link) => link.verified && link.identityId !== claim.identityId);
+  if (otherVerified) {
+    claim.state = "refused";
+    claim.refusalReason = "contact_owned";
+    return claim;
+  }
+  target.verified = true;
+  claim.state = "completed";
+  claim.completedIdentityId = claim.identityId;
+  claim.claimantClerkUserId = params.clerkUserId;
+  return claim;
+}
+function refuseClaim(claimId, reason) {
+  const claim = requireClaim(claimId);
+  if (claim.state !== "pending") return claim;
+  if (!reason) throw new Error("a refusal reason is required");
+  claim.state = "refused";
+  claim.refusalReason = reason;
+  return claim;
+}
 function createDirectory() {
   return {
     all: () => [...state.identities.values()],
@@ -1160,9 +1343,26 @@ function createDirectory() {
     links: (identityId) => linksFor(identityId),
     seedVerifiedLink,
     merge,
+    claims: () => [...state.identityClaims.values()],
+    claim: (claimId) => state.identityClaims.get(claimId),
+    enableStaffAssist: (enabled = true) => {
+      state.identityStaffAssistEnabled = enabled;
+    },
+    suppressClaimDelivery: (enabled = true) => {
+      state.identitySuppressClaimDelivery = enabled;
+    },
+    allowReturnOrigin: (origin) => {
+      state.identityAllowedReturnOrigins.add(new URL(origin).origin);
+    },
+    completeClaim,
+    refuseClaim,
     clear: () => {
       state.identities.clear();
       state.identityLinks = [];
+      state.identityClaims.clear();
+      state.identityStaffAssistEnabled = false;
+      state.identitySuppressClaimDelivery = false;
+      state.identityAllowedReturnOrigins = /* @__PURE__ */ new Set([APP_TEST_ORIGIN]);
     },
     get count() {
       return state.identities.size;
@@ -1201,7 +1401,7 @@ async function importNextServer() {
 async function callRoute(handler, options = {}) {
   const { NextRequest } = await importNextServer();
   const path = options.path ?? "/api/test-route";
-  const url = new URL(`http://localhost:3333${path}`);
+  const url = new URL(`${APP_TEST_ORIGIN}${path}`);
   for (const [key, value] of Object.entries(options.searchParams ?? {})) {
     url.searchParams.set(key, value);
   }
@@ -2976,8 +3176,7 @@ async function createTestApp(options = {}) {
       state.refreshSessions.clear();
       state.emails = [];
       state.emailCounter = 0;
-      state.identities.clear();
-      state.identityLinks = [];
+      directory.clear();
       payments.clear();
       storage.clear();
       messages.clear();
@@ -2991,8 +3190,7 @@ async function createTestApp(options = {}) {
       state.refreshSessions.clear();
       state.emails = [];
       state.emailCounter = 0;
-      state.identities.clear();
-      state.identityLinks = [];
+      directory.clear();
       payments.clear();
       storage.clear();
       messages.clear();