@stardeck-customer-apps/testing 0.16.0 → 0.17.0

package/SKILL.md

@@ -350,8 +350,9 @@ externalId })` helper models a trusted platform/channel link, and
   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.
+  Completing a finished claim replays the recorded result. Completion attaches
+  the claimant's login to the profile (moving it off any profile it was on), but
+  does not 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
@@ -359,7 +360,22 @@ externalId })` helper models a trusted platform/channel link, and
   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.
+  fallback delivery can be tested. Bearer links are on by default, like the platform;
+  `.enableBearerLinks(false)` models a project whose admin turned them off. A bearer claim is raised against a
+  profile with no contact at all, so it takes no `kind`/`externalId`/`deliver`
+  (sending one is refused, not ignored) and `completeClaim` connects whoever
+  completes it — unless another login already holds that profile, which comes
+  back `refused` / `owned_elsewhere`. That refusal is the one a leaked bearer
+  link runs into, so test it. A profile that holds an email or phone is refused
+  at `create` with a 409 (send an `invite`); one that gains a contact before
+  the link is used completes as `refused` / `protected`, and a link still
+  outstanding when `.enableBearerLinks(false)` runs completes as `refused` /
+  `expired`. People seeded with only a `dashboard_user` link (team members) are
+  left out of `identities.list()` and `search()`, as on the platform.
+  `search({ attributes })` matches profile attributes exactly and by JSON type
+  (`5` never matches `"5"`) and rejects nested, array, `null` or more than 10
+  keys (or a `__proto__` key) with a `ValidationError` whose message matches the
+  platform's, like the platform.
 
   ```ts
   const claim = await integrations.identities.claims.create({
@@ -372,6 +388,17 @@ externalId })` helper models a trusted platform/channel link, and
   expect((await integrations.identities.claims.get(claim.claimId)).state).toBe("completed");
   ```
 
+  ```ts
+  // A name on a card, no email or phone: the link IS the authorisation.
+  const bearer = await integrations.identities.claims.create({
+    flow: "bearer",
+    identityId: walkIn.id,
+  });
+  expect(app.identities.completeClaim(bearer.claimId, { clerkUserId: "user_2" }).state).toBe(
+    "completed"
+  );
+  ```
+
 - `app.payments` — checkouts created through payments-sdk:
   `.checkouts`, `.latest()`, `.setProducts()`, `.markPaid(id)`,
   `.setSessionStatus(id, status)`, `.setPaymentLinkStatus(id, status)`,
@@ -450,7 +477,10 @@ true })` remains source-compatible but the simulator (like the control plane)
   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
+  `profile` object (not a merge), like the control plane. A person with a
+  seeded `dashboard_user` link is a team member: changing their `displayName`
+  or `profile.email` is refused with a 409 `ValidationError`, and a new
+  `profile` without `email` keeps the current one, as on the platform. Inspect via
   `app.identities`; merge/archive are privileged setup operations, with only
   test-only merge modeling exposed above.
 - `session.user.identityId` is the platform-provisioned cross-app customer key.

package/dist/index.d.mts

@@ -107,11 +107,12 @@ interface CapturedIdentityLink {
  */
 interface CapturedIdentityClaim {
     claimId: string;
-    flow: "invite" | "assist" | "transfer";
+    flow: "invite" | "assist" | "transfer" | "bearer";
     /** The profile the claim connects the customer to. */
     identityId: string;
-    kind: "email" | "phone";
-    externalId: string;
+    /** The recorded contact this claim was raised against. Null for `bearer` only. */
+    kind: "email" | "phone" | null;
+    externalId: string | null;
     returnTo: string | null;
     /** The app's reference for the staff member, for assist/transfer claims. */
     staffActorRef: string | null;
@@ -161,6 +162,12 @@ interface TestDirectory {
      * `claims.create` refuses `assist` and `transfer` with 403, like the platform.
      */
     enableStaffAssist(enabled?: boolean): void;
+    /**
+     * Test setup only: set the project's bearer-link opt-in. It is on by default,
+     * like the platform; pass `false` to model an org that switched it off, and
+     * `claims.create({ flow: "bearer" })` is then refused with 403.
+     */
+    enableBearerLinks(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`

package/dist/index.d.ts

@@ -107,11 +107,12 @@ interface CapturedIdentityLink {
  */
 interface CapturedIdentityClaim {
     claimId: string;
-    flow: "invite" | "assist" | "transfer";
+    flow: "invite" | "assist" | "transfer" | "bearer";
     /** The profile the claim connects the customer to. */
     identityId: string;
-    kind: "email" | "phone";
-    externalId: string;
+    /** The recorded contact this claim was raised against. Null for `bearer` only. */
+    kind: "email" | "phone" | null;
+    externalId: string | null;
     returnTo: string | null;
     /** The app's reference for the staff member, for assist/transfer claims. */
     staffActorRef: string | null;
@@ -161,6 +162,12 @@ interface TestDirectory {
      * `claims.create` refuses `assist` and `transfer` with 403, like the platform.
      */
     enableStaffAssist(enabled?: boolean): void;
+    /**
+     * Test setup only: set the project's bearer-link opt-in. It is on by default,
+     * like the platform; pass `false` to model an org that switched it off, and
+     * `claims.create({ flow: "bearer" })` is then refused with 403.
+     */
+    enableBearerLinks(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`

package/dist/index.js

@@ -144,6 +144,7 @@ var state = globalSingleton("state", () => ({
   identityLinks: [],
   identityClaims: /* @__PURE__ */ new Map(),
   identityStaffAssistEnabled: false,
+  identityBearerLinksEnabled: true,
   identitySuppressClaimDelivery: false,
   identityAllowedReturnOrigins: /* @__PURE__ */ new Set([APP_TEST_ORIGIN]),
   checkouts: [],
@@ -727,14 +728,16 @@ var TRUSTED_LINK_KINDS = /* @__PURE__ */ new Set([
 ]);
 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 CLAIM_FLOWS = /* @__PURE__ */ new Set(["invite", "assist", "transfer", "bearer"]);
 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 BEARER_LINKS_NOT_ENABLED = "BEARER_LINKS_NOT_ENABLED";
 var E164_PHONE = /^\+[1-9]\d{1,14}$/;
 var SEARCH_DEFAULT_LIMIT = 50;
 var SEARCH_MAX_LIMIT = 100;
+var TEAM_ACCOUNT_FIELDS_MESSAGE = "This person's name and email come from their team account. Change them in Members settings.";
 function asciiLowercaseTrim(value) {
   const trimmed = value.trim();
   let out = "";
@@ -854,11 +857,21 @@ function createUnverifiedLink(identityId, kind, externalId) {
   state.identityLinks.push(link);
   return link;
 }
+function isTeamOnly(identityId) {
+  const kinds = linksFor(identityId).map((link) => link.kind);
+  return kinds.includes("dashboard_user") && !kinds.includes("project_auth_user");
+}
+function isCurrentTeamMember(identityId) {
+  return linksFor(identityId).some((link) => link.kind === "dashboard_user" && link.verified);
+}
+function hasRecordedContact(identityId) {
+  return linksFor(identityId).some((link) => link.kind === "email" || link.kind === "phone");
+}
 function handleList(request) {
   const typeParam = new URL(request.url).searchParams.get("type");
   const type = typeParam === "person" || typeParam === "account" ? typeParam : void 0;
   const identities = [...state.identities.values()].filter(
-    (identity) => identity.status !== "merged"
+    (identity) => identity.status !== "merged" && !isTeamOnly(identity.id)
   );
   return success({ identities: type ? identities.filter((i) => i.type === type) : identities });
 }
@@ -902,11 +915,18 @@ async function handleUpdate(identityId, request) {
   const identity = state.identities.get(identityId);
   if (!identity) return failure("identity not found", 404);
   const body = await readJsonBody(request);
+  const profile = body.profile;
+  if (isCurrentTeamMember(identityId)) {
+    const changesName = body.displayName !== void 0 && body.displayName !== identity.displayName;
+    const changesEmail = profile !== void 0 && Object.hasOwn(profile, "email") && profile.email !== identity.profile.email;
+    if (changesName || changesEmail) return failure(TEAM_ACCOUNT_FIELDS_MESSAGE, 409);
+  }
   if (body.displayName !== void 0) {
     identity.displayName = body.displayName;
   }
-  if (body.profile !== void 0) {
-    identity.profile = body.profile;
+  if (profile !== void 0) {
+    const keptEmail = isCurrentTeamMember(identityId) && !Object.hasOwn(profile, "email") && Object.hasOwn(identity.profile, "email");
+    identity.profile = keptEmail ? { ...profile, email: identity.profile.email } : profile;
   }
   if (body.externalRef !== void 0) {
     identity.externalRef = body.externalRef;
@@ -1008,6 +1028,36 @@ function identityMatchesQuery(identity, query) {
     (link) => link.identityId === identity.id && comparableExternalId(link.kind, link.externalId).toLowerCase().includes(query)
   );
 }
+function parseSearchAttributes(raw) {
+  if (raw === null) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return "attributes: attributes must be a JSON object";
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return "attributes: attributes must be a JSON object";
+  }
+  if (Object.hasOwn(parsed, "__proto__")) return "attributes: attribute keys may not be __proto__";
+  const entries = Object.entries(parsed);
+  if (entries.length > 10) return "attributes: attributes may filter on at most 10 keys";
+  for (const [key, value] of entries) {
+    if (!["string", "number", "boolean"].includes(typeof value)) {
+      return `attributes.${key}: attribute values must be a string, number or boolean`;
+    }
+    if (key.length < 1 || key.length > 100) {
+      return `attributes.${key}: attribute keys must be 1-100 characters`;
+    }
+    if (typeof value === "string" && value.length > 500) {
+      return `attributes.${key}: attribute values must be at most 500 characters`;
+    }
+  }
+  return parsed;
+}
+function identityMatchesAttributes(identity, attributes) {
+  return Object.entries(attributes).every(([key, value]) => identity.profile[key] === value);
+}
 function handleSearch(request) {
   const url = new URL(request.url);
   const query = (url.searchParams.get("query") ?? "").trim().toLowerCase();
@@ -1020,10 +1070,14 @@ function handleSearch(request) {
       return failure(`limit must be between 1 and ${SEARCH_MAX_LIMIT}`);
     }
   }
+  const attributes = parseSearchAttributes(url.searchParams.get("attributes"));
+  if (typeof attributes === "string") {
+    return json({ success: false, error: "Invalid query parameters", details: attributes }, 400);
+  }
   const rawCursor = url.searchParams.get("cursor");
   const cursor = rawCursor ? decodeSearchCursor(rawCursor, query) : null;
   if (rawCursor && !cursor) return failure("cursor is invalid");
-  const identities = [...state.identities.values()].filter((identity) => identity.status === "active" && identity.mergedIntoId === null).filter((identity) => identityMatchesQuery(identity, query)).sort(compareIdentityOrder);
+  const identities = [...state.identities.values()].filter((identity) => identity.status === "active" && identity.mergedIntoId === null).filter((identity) => !isTeamOnly(identity.id)).filter((identity) => identityMatchesQuery(identity, query)).filter((identity) => identityMatchesAttributes(identity, attributes)).sort(compareIdentityOrder);
   const start = cursor ? identities.findIndex((identity) => compareIdentityOrder(identity, cursor) > 0) : 0;
   const pageStart = start < 0 ? identities.length : start;
   const items = identities.slice(pageStart, pageStart + limit);
@@ -1099,15 +1153,92 @@ function validateClaimStaff(flow, staff) {
   if (grant !== flow) return { error: `staff.grant must be '${flow}' for a ${flow} claim` };
   return { staffActorRef: actorRef };
 }
+function parseReturnTo(raw) {
+  if (raw === void 0) return { returnTo: null };
+  if (typeof raw !== "string") return { error: "returnTo must be a string" };
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return { error: "returnTo must be an absolute URL" };
+  }
+  return { returnTo: state.identityAllowedReturnOrigins.has(parsed.origin) ? raw : null };
+}
+function claimableIdentity(identityId) {
+  const identity = state.identities.get(identityId);
+  if (!identity || identity.type !== "person" || identity.status !== "active") return null;
+  return identity;
+}
+function mintClaim(params) {
+  const claimId = import_node_crypto3.default.randomUUID();
+  const handle = import_node_crypto3.default.randomBytes(32).toString("base64url");
+  const claim = {
+    claimId,
+    flow: params.flow,
+    identityId: params.identityId,
+    kind: params.kind,
+    externalId: params.externalId,
+    returnTo: params.returnTo,
+    staffActorRef: params.staffActorRef,
+    state: "pending",
+    refusalReason: null,
+    completedIdentityId: null,
+    claimantClerkUserId: null,
+    claimUrl: `${CONTROL_PLANE_TEST_URL}/claim/${handle}`,
+    delivered: params.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".
+    ...params.deliver ? { delivered: claim.delivered } : {}
+  });
+}
+function createBearerClaim(body, returnTo) {
+  for (const field of ["kind", "externalId", "deliver", "staff"]) {
+    if (body[field] !== void 0) {
+      return failure(`a bearer claim takes no ${field}: it is raised against no contact`);
+    }
+  }
+  if (!state.identityBearerLinksEnabled) {
+    return failure(
+      "profile invite links are not enabled for this project",
+      403,
+      BEARER_LINKS_NOT_ENABLED
+    );
+  }
+  const identity = claimableIdentity(body.identityId);
+  if (!identity) return failure("identity not found", 404);
+  if (hasRecordedContact(identity.id)) {
+    return failure("identity has an email or phone on record; send an invite claim instead", 409);
+  }
+  return mintClaim({
+    flow: "bearer",
+    identityId: identity.id,
+    kind: null,
+    externalId: null,
+    returnTo,
+    staffActorRef: null,
+    deliver: false
+  });
+}
 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");
+    return failure("flow must be one of: invite, assist, transfer, bearer");
   }
   if (typeof body.identityId !== "string" || !UUID.test(body.identityId)) {
     return failure("identityId must be a uuid");
   }
+  const parsedReturnTo = parseReturnTo(body.returnTo);
+  if ("error" in parsedReturnTo) return failure(parsedReturnTo.error);
+  if (flow === "bearer") return createBearerClaim(body, parsedReturnTo.returnTo);
   const normalized = normalizeLinkInput(
     body.kind,
     body.externalId,
@@ -1115,17 +1246,6 @@ async function handleCreateClaim(request) {
     "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");
   }
@@ -1138,44 +1258,22 @@ async function handleCreateClaim(request) {
       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 identity = claimableIdentity(body.identityId);
+  if (!identity) 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,
+  return mintClaim({
     flow,
     identityId: identity.id,
     kind: normalized.kind,
     externalId: normalized.externalId,
-    returnTo,
+    returnTo: parsedReturnTo.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 } : {}
+    deliver: body.deliver === true
   });
 }
 function handleGetClaim(claimId) {
@@ -1310,6 +1408,7 @@ function completeClaim(claimId, params) {
     return claim;
   }
   if (!params.clerkUserId) throw new Error("clerkUserId is required");
+  if (claim.flow === "bearer") return completeBearerClaim(claim, params.clerkUserId);
   const rows = matchingLinks(claim.kind, claim.externalId);
   const target = rows.find((link) => link.identityId === claim.identityId);
   if (!target) {
@@ -1322,12 +1421,55 @@ function completeClaim(claimId, params) {
     claim.refusalReason = "contact_owned";
     return claim;
   }
+  if (claim.flow !== "transfer" && ownedByAnotherLogin(claim.identityId, params.clerkUserId)) {
+    claim.state = "refused";
+    claim.refusalReason = "owned_elsewhere";
+    return claim;
+  }
   target.verified = true;
+  connectLogin(claim, params.clerkUserId);
   claim.state = "completed";
   claim.completedIdentityId = claim.identityId;
   claim.claimantClerkUserId = params.clerkUserId;
   return claim;
 }
+function ownedByAnotherLogin(identityId, clerkUserId) {
+  return linksFor(identityId).some(
+    (link) => link.kind === "project_auth_user" && link.externalId !== clerkUserId
+  );
+}
+function connectLogin(claim, clerkUserId) {
+  const isLogin = (link) => link.identityId === claim.identityId && link.kind === "project_auth_user";
+  if (claim.flow === "transfer") {
+    state.identityLinks = state.identityLinks.filter(
+      (link) => !isLogin(link) || link.externalId === clerkUserId
+    );
+  }
+  state.identityLinks = state.identityLinks.filter(
+    (link) => link.kind !== "project_auth_user" || link.externalId !== clerkUserId || link.identityId === claim.identityId
+  );
+  if (!state.identityLinks.some((link) => isLogin(link) && link.externalId === clerkUserId)) {
+    createUnverifiedLink(claim.identityId, "project_auth_user", clerkUserId).verified = true;
+  }
+}
+function completeBearerClaim(claim, clerkUserId) {
+  const identity = state.identities.get(claim.identityId);
+  if (!identity || identity.type !== "person" || identity.status !== "active") {
+    claim.state = "invalidated";
+    return claim;
+  }
+  const refusal = !state.identityBearerLinksEnabled ? "expired" : hasRecordedContact(claim.identityId) ? "protected" : ownedByAnotherLogin(claim.identityId, clerkUserId) ? "owned_elsewhere" : null;
+  if (refusal) {
+    claim.state = "refused";
+    claim.refusalReason = refusal;
+    return claim;
+  }
+  connectLogin(claim, clerkUserId);
+  claim.state = "completed";
+  claim.completedIdentityId = claim.identityId;
+  claim.claimantClerkUserId = clerkUserId;
+  return claim;
+}
 function refuseClaim(claimId, reason) {
   const claim = requireClaim(claimId);
   if (claim.state !== "pending") return claim;
@@ -1348,6 +1490,9 @@ function createDirectory() {
     enableStaffAssist: (enabled = true) => {
       state.identityStaffAssistEnabled = enabled;
     },
+    enableBearerLinks: (enabled = true) => {
+      state.identityBearerLinksEnabled = enabled;
+    },
     suppressClaimDelivery: (enabled = true) => {
       state.identitySuppressClaimDelivery = enabled;
     },
@@ -1361,6 +1506,7 @@ function createDirectory() {
       state.identityLinks = [];
       state.identityClaims.clear();
       state.identityStaffAssistEnabled = false;
+      state.identityBearerLinksEnabled = true;
       state.identitySuppressClaimDelivery = false;
       state.identityAllowedReturnOrigins = /* @__PURE__ */ new Set([APP_TEST_ORIGIN]);
     },