@pplethai/cli 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pplethai/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "repository": {
     "type": "git",

package/templates/golden-path/CLAUDE.md

@@ -62,6 +62,35 @@ Where the token comes from:
 - **Add a DB table** by writing a new migration and running
   `npm run db:migrate:local`.
 
+## KYC Status and Legal Identity
+
+**KYC Status** is `actor.kyc`. Gate on `actor.kyc.verified`. It is never on
+`effective`. After someone returns from `/kyc`, re-read userinfo — `?kyc=` is
+a UI hint only. `kyc.verified` means PPLE ID knows a real person behind the
+account; it does not prove the account holder is the cardholder, and an app
+that needs that check adds its own.
+
+A **Legal Identity** (name and citizen ID) is not in userinfo. Call
+`getLegalIdentity(env, token)` only at the moment it is needed, such as
+checkout, and copy it onto that record, such as the receipt. Not on page
+views, and nowhere else — do not log, cache, or store it aside from that
+record. `idCardNumber` may be `null` for a member without a KYC record; send
+them through `/kyc` (`kycStartUrl`) if the app needs the number.
+
+Under delegation the Legal Identity is the actor's. If delegated use should
+be blocked, check `effective.isDelegated`.
+
+A **Legal Identity Grant** comes from a Platform Admin, and the app must be
+Beta or Live. Ask a Platform Admin. `getLegalIdentity` reasons:
+`not_configured` (bindings missing), `invalid_app_key`, `not_granted` (no
+grant, or Draft or retired), `not_verified`, `user_token_invalid`,
+`identity_not_enabled` (granted here, not allowlisted on pple-sso),
+`upstream_unavailable`.
+
+Locally, try `DEV_PERSONA=unverified`, `kyc-pending`, or
+`kyc-verified-nonmember`. Member Personas are verified via membership and the
+offline helper returns `idCardNumber: null`.
+
 ## Before you finish
 
 Run these and make sure they pass:

package/templates/golden-path/shared/api.ts

@@ -13,11 +13,28 @@ import { z } from "zod";
  *   never on `actor`. Under Delegation these are the supervisor's values and
  *   `isDelegated` is true. See docs/adr/0012 and CONTEXT.md.
  */
+/**
+ * KYC Status (CONTEXT.md). Whether PPLE ID knows a real person behind this
+ * account. It carries no name and no citizen ID, and it belongs to the human,
+ * so it sits on the actor — a delegate does not inherit a supervisor's status.
+ * `verified` does not prove the account holder is the cardholder.
+ */
+export const KycStatusSchema = z.object({
+  status: z.enum(["none", "pending_review", "verified", "rejected"]),
+  verified: z.boolean(),
+  verifiedAt: z.string().nullable(),
+  /** `membership` for an active member, `kyc` for a national-ID check, or null. */
+  source: z.enum(["membership", "kyc"]).nullable(),
+});
+export type KycStatus = z.infer<typeof KycStatusSchema>;
+
 export const ActorSchema = z.object({
   sub: z.string(),
   name: z.string().nullable(),
   /** Thai mobile number, the join key across PPLE systems. May be null. */
   mobile: z.string().nullable(),
+  /** Never copied onto `effective`. See KycStatusSchema. */
+  kyc: KycStatusSchema,
 });
 export type Actor = z.infer<typeof ActorSchema>;
 

package/templates/golden-path/src/auth.ts

@@ -85,9 +85,18 @@ interface RawAd {
   eligibleProvinces?: unknown;
 }
 
+interface RawKyc {
+  status?: string;
+  verified?: boolean;
+  verifiedAt?: string | null;
+  source?: string | null;
+}
+
 interface RawUserInfo {
   sub?: string;
   name?: string;
+  /** KYC Status of the human who logged in. Absent until PPLE ID sends it. */
+  kyc?: RawKyc;
   ad?: RawAd;
 }
 
@@ -108,6 +117,21 @@ function extraRolesOf(person: RawPerson | undefined): string[] {
   return roles;
 }
 
+const KYC_STATUSES = ["none", "pending_review", "verified", "rejected"] as const;
+const KYC_SOURCES = ["membership", "kyc"] as const;
+
+/** A missing or odd `kyc` is "PPLE ID has not verified this person", not an error. */
+function kycOf(raw: RawKyc | undefined): Identity["actor"]["kyc"] {
+  const status = KYC_STATUSES.find((s) => s === raw?.status) ?? "none";
+  const source = KYC_SOURCES.find((s) => s === raw?.source) ?? null;
+  return {
+    status,
+    verified: raw?.verified === true,
+    verifiedAt: typeof raw?.verifiedAt === "string" ? raw.verifiedAt : null,
+    source,
+  };
+}
+
 function toIdentity(body: RawUserInfo): Identity {
   const ad = body.ad;
   const effectivePerson = ad?.user;
@@ -122,6 +146,9 @@ function toIdentity(body: RawUserInfo): Identity {
       sub: body.sub as string,
       name: body.name ?? null,
       mobile: actualPerson?.mobile ?? null,
+      // The human's own KYC Status. A delegated session still reports the
+      // actor's, never the supervisor's, and effective never carries it.
+      kyc: kycOf(body.kyc),
     },
     effective: {
       isDelegated:

package/templates/golden-path/src/dev-personas.ts

@@ -11,14 +11,32 @@
 // The rule your app code must follow (docs/adr/0012): gate authorization on
 // `effective`, use `actor` for audit/display only, and honor
 // `effective.isDelegated`.
-import type { Identity } from "../shared/api";
+import type { Identity, KycStatus } from "../shared/api";
 
 export const DEFAULT_DEV_PERSONA = "hq-staff";
 
+/** An active member: verified through membership, not a national-ID check. */
+function memberKyc(verifiedAt: string): KycStatus {
+  return { status: "verified", verified: true, verifiedAt, source: "membership" };
+}
+
+const citizen: Identity["effective"] = {
+  isDelegated: false,
+  activeRole: "",
+  eligibleRoles: [],
+  provinces: [],
+  extraRoles: [],
+};
+
 export const DEV_PERSONAS: Record<string, Identity> = {
   // Party HQ staff: every province in scope, no special capabilities. Default.
   "hq-staff": {
-    actor: { sub: "dev-hq-staff", name: "Local Dev (HQ)", mobile: "0800000001" },
+    actor: {
+      sub: "dev-hq-staff",
+      name: "Local Dev (HQ)",
+      mobile: "0800000001",
+      kyc: memberKyc("2024-01-01T00:00:00.000Z"),
+    },
     effective: {
       isDelegated: false,
       activeRole: "hq",
@@ -34,6 +52,7 @@ export const DEV_PERSONAS: Record<string, Identity> = {
       sub: "dev-province-coordinator",
       name: "Local Dev (จังหวัด)",
       mobile: "0800000002",
+      kyc: memberKyc("2024-02-01T00:00:00.000Z"),
     },
     effective: {
       isDelegated: false,
@@ -50,6 +69,7 @@ export const DEV_PERSONAS: Record<string, Identity> = {
       sub: "dev-platform-admin",
       name: "Local Dev (Admin)",
       mobile: "0800000003",
+      kyc: memberKyc("2024-03-01T00:00:00.000Z"),
     },
     effective: {
       isDelegated: false,
@@ -62,8 +82,14 @@ export const DEV_PERSONAS: Record<string, Identity> = {
 
   // A delegate acting for a supervisor: effective.* are the SUPERVISOR's role
   // and scope, actor.* is the delegate human, and isDelegated is true.
+  // KYC Status is the delegate's own, not the province coordinator's.
   delegate: {
-    actor: { sub: "dev-delegate", name: "Local Dev (ผู้รับมอบ)", mobile: "0800000004" },
+    actor: {
+      sub: "dev-delegate",
+      name: "Local Dev (ผู้รับมอบ)",
+      mobile: "0800000004",
+      kyc: memberKyc("2024-04-01T00:00:00.000Z"),
+    },
     effective: {
       isDelegated: true,
       activeRole: "province",
@@ -72,6 +98,44 @@ export const DEV_PERSONAS: Record<string, Identity> = {
       extraRoles: [],
     },
   },
+
+  // No KYC Status at all.
+  unverified: {
+    actor: {
+      sub: "dev-unverified",
+      name: "Local Dev (ยังไม่ยืนยัน)",
+      mobile: "0800000005",
+      kyc: { status: "none", verified: false, verifiedAt: null, source: null },
+    },
+    effective: { ...citizen },
+  },
+
+  // Submitted a national ID and waiting on review.
+  "kyc-pending": {
+    actor: {
+      sub: "dev-kyc-pending",
+      name: "Local Dev (รอตรวจ)",
+      mobile: "0800000006",
+      kyc: { status: "pending_review", verified: false, verifiedAt: null, source: null },
+    },
+    effective: { ...citizen },
+  },
+
+  // Verified with a national ID, and not a party member.
+  "kyc-verified-nonmember": {
+    actor: {
+      sub: "dev-kyc-verified",
+      name: "Local Dev (ยืนยันด้วยบัตร)",
+      mobile: "0800000007",
+      kyc: {
+        status: "verified",
+        verified: true,
+        verifiedAt: "2024-05-01T00:00:00.000Z",
+        source: "kyc",
+      },
+    },
+    effective: { ...citizen },
+  },
 };
 
 /** Resolve the configured persona; an unknown name warns and falls back to the

package/templates/golden-path/src/env.ts

@@ -14,6 +14,12 @@ export interface Env {
   NOTIFY_API_BASE: string;
   NOTIFY_API_KEY?: string;
 
+  // Platform Services (ADR-0022). The App Key is a secret; the URL is plain.
+  // Both are empty until the platform binds them. Legal Identity reads them
+  // in src/legal-identity.ts.
+  PPLE_SERVICES_URL?: string;
+  PPLE_APP_KEY?: string;
+
   // Local development only: which mock persona to sign in as (src/dev-personas.ts).
   // Unset means the default persona; "none" turns the bypass off. Never set in
   // production — the dev bypass is compiled out of the deployed Worker anyway.

package/templates/golden-path/src/legal-identity.ts

@@ -0,0 +1,161 @@
+// Legal Identity (CONTEXT.md). A Builder App reads a person's name and
+// citizen ID through Platform Services, only under a Legal Identity Grant,
+// only at the moment it needs them. This module fetches that record. It does
+// not store it.
+//
+// Offline (`npm run dev` with a Persona) the answer is a fixed fake. Member
+// Personas have no citizen ID, matching production. The one ID this module
+// invents fails the Thai checksum, so it can never be mistaken for a real one.
+
+import type { KycStatus } from "../shared/api";
+import { resolveDevPersona } from "./dev-personas";
+
+export interface LegalIdentity {
+  source: "membership" | "kyc";
+  name: string;
+  /** Null for a member who never did a national-ID check. */
+  idCardNumber: string | null;
+}
+
+export type LegalIdentityReason =
+  | "not_configured"
+  | "invalid_app_key"
+  | "not_granted"
+  | "not_verified"
+  | "user_token_invalid"
+  | "identity_not_enabled"
+  | "upstream_unavailable";
+
+export type LegalIdentityResult =
+  | { ok: true; legalIdentity: LegalIdentity }
+  | { ok: false; reason: LegalIdentityReason };
+
+interface LegalIdentityEnv {
+  PPLE_SERVICES_URL?: string;
+  PPLE_APP_KEY?: string;
+  /** Which Persona is signed in. `"none"` uses the real Platform Service. */
+  DEV_PERSONA?: string;
+}
+
+/** The only name the offline path returns. */
+export const OFFLINE_LEGAL_NAME = "บุคคลทดสอบ ออฟไลน์";
+
+/**
+ * 13 digits that fail the Thai national-ID checksum (expected check digit 8).
+ * The offline path uses this and nothing that would pass.
+ */
+export const OFFLINE_INVALID_ID = "1100000000000";
+
+const REASONS: readonly LegalIdentityReason[] = [
+  "invalid_app_key",
+  "not_granted",
+  "not_verified",
+  "user_token_invalid",
+  "identity_not_enabled",
+  "upstream_unavailable",
+];
+
+/** True when `id` is 13 digits and its check digit matches. */
+export function thaiIdChecksumValid(id: string): boolean {
+  if (!/^\d{13}$/.test(id)) return false;
+  let sum = 0;
+  for (let i = 0; i < 12; i++) sum += Number(id[i]) * (13 - i);
+  return (11 - (sum % 11)) % 10 === Number(id[12]);
+}
+
+/**
+ * The caller's Legal Identity, or why it isn't available.
+ *
+ * `not_configured` means PPLE_SERVICES_URL or PPLE_APP_KEY is missing — the
+ * same idea as a notification send before its key is bound. The other reasons
+ * are what `pple-services` answers.
+ */
+export async function getLegalIdentity(
+  env: LegalIdentityEnv,
+  token: string,
+  fetchImpl: typeof fetch = globalThis.fetch.bind(globalThis),
+): Promise<LegalIdentityResult> {
+  // Same seam as authenticate: a Persona stands in for PPLE ID, and the
+  // block is dead-code-eliminated from the production build (ADR-0011).
+  if (import.meta.env.DEV && env.DEV_PERSONA !== "none") {
+    return offlineLegalIdentity(env.DEV_PERSONA);
+  }
+
+  if (!env.PPLE_SERVICES_URL || !env.PPLE_APP_KEY) {
+    return { ok: false, reason: "not_configured" };
+  }
+
+  let res: Response;
+  try {
+    res = await fetchImpl(`${env.PPLE_SERVICES_URL.replace(/\/$/, "")}/legal-identity`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${env.PPLE_APP_KEY}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ token }),
+    });
+  } catch {
+    return { ok: false, reason: "upstream_unavailable" };
+  }
+
+  const body = (await res.json().catch(() => ({}))) as {
+    error?: string;
+    source?: string;
+    name?: string;
+    idCardNumber?: string | null;
+  };
+  // The error string wins over the status: 401 is both an App Key rejection
+  // and a user-token rejection, and only the body says which.
+  const reason = REASONS.find((r) => r === body.error);
+  if (reason) return { ok: false, reason };
+  if (!res.ok) return { ok: false, reason: "upstream_unavailable" };
+
+  if (typeof body.name !== "string" || body.name === "") {
+    return { ok: false, reason: "upstream_unavailable" };
+  }
+  const source = body.source === "membership" || body.source === "kyc" ? body.source : null;
+  if (!source) return { ok: false, reason: "upstream_unavailable" };
+  const idCardNumber = typeof body.idCardNumber === "string" ? body.idCardNumber : null;
+  return { ok: true, legalIdentity: { source, name: body.name, idCardNumber } };
+}
+
+function offlineLegalIdentity(personaName: string | undefined): LegalIdentityResult {
+  const persona = resolveDevPersona(personaName);
+  const kyc: KycStatus = persona.actor.kyc;
+  if (!kyc.verified || (kyc.source !== "membership" && kyc.source !== "kyc")) {
+    return { ok: false, reason: "not_verified" };
+  }
+  // Members have a name and no citizen ID until they do KYC. Anyone else gets
+  // the one invalid ID, and a checksum that accidentally passed is dropped.
+  let idCardNumber = kyc.source === "membership" ? null : OFFLINE_INVALID_ID;
+  if (idCardNumber && thaiIdChecksumValid(idCardNumber)) idCardNumber = null;
+  return {
+    ok: true,
+    legalIdentity: { source: kyc.source, name: OFFLINE_LEGAL_NAME, idCardNumber },
+  };
+}
+
+/**
+ * Where a "start KYC" button sends the person. Locally that is straight back
+ * to `returnTo` with `?kyc=cancelled` — there is no PPLE ID to open. In
+ * production it is `{ssoBaseUrl}/kyc`, which is the shape pple-today owns
+ * (PPLEThai/pple-today#500).
+ */
+export function kycStartUrl(input: {
+  ssoBaseUrl: string;
+  clientId: string;
+  returnTo: string;
+  dev?: boolean;
+}): string {
+  const dev = input.dev ?? import.meta.env.DEV;
+  if (dev) {
+    const back = new URL(input.returnTo);
+    back.searchParams.set("kyc", "cancelled");
+    return back.toString();
+  }
+  const url = new URL("/kyc", input.ssoBaseUrl);
+  url.searchParams.set("client_id", input.clientId);
+  url.searchParams.set("return_to", input.returnTo);
+  return url.toString();
+}

package/templates/golden-path/test/legal-identity.test.ts

@@ -0,0 +1,256 @@
+// KYC Status on the actor, and getLegalIdentity (issue #216). Every refusal
+// the helper can return is named here. The offline path never yields a
+// citizen ID that would pass the Thai checksum.
+
+import { describe, expect, it, vi } from "vitest";
+import { DEV_PERSONAS } from "../src/dev-personas";
+import {
+  getLegalIdentity,
+  kycStartUrl,
+  OFFLINE_INVALID_ID,
+  OFFLINE_LEGAL_NAME,
+  thaiIdChecksumValid,
+  type LegalIdentityReason,
+} from "../src/legal-identity";
+import { makeHarness } from "./harness";
+
+describe("actor.kyc", () => {
+  it("gives every Persona a KYC Status, and members are verified via membership", () => {
+    for (const persona of Object.values(DEV_PERSONAS)) {
+      expect(persona.actor.kyc).toEqual(
+        expect.objectContaining({
+          status: expect.any(String),
+          verified: expect.any(Boolean),
+        }),
+      );
+      expect("kyc" in persona.effective).toBe(false);
+    }
+    expect(DEV_PERSONAS["hq-staff"]!.actor.kyc).toMatchObject({
+      status: "verified",
+      verified: true,
+      source: "membership",
+    });
+    expect(DEV_PERSONAS.unverified!.actor.kyc.status).toBe("none");
+    expect(DEV_PERSONAS["kyc-pending"]!.actor.kyc.status).toBe("pending_review");
+    expect(DEV_PERSONAS["kyc-verified-nonmember"]!.actor.kyc).toMatchObject({
+      status: "verified",
+      source: "kyc",
+    });
+  });
+
+  it("keeps the delegate's KYC Status, not the supervisor's", async () => {
+    const delegate = makeHarness({}, { DEV_PERSONA: "delegate" });
+    const supervisor = makeHarness({}, { DEV_PERSONA: "province-coordinator" });
+    const delegateMe = await (await delegate.request("/api/me")).json<{
+      actor: { kyc: { verifiedAt: string; source: string } };
+      effective: Record<string, unknown>;
+    }>();
+    const supervisorMe = await (await supervisor.request("/api/me")).json<{
+      actor: { kyc: { verifiedAt: string } };
+    }>();
+    expect(delegateMe.actor.kyc.verifiedAt).toBe("2024-04-01T00:00:00.000Z");
+    expect(delegateMe.actor.kyc.verifiedAt).not.toBe(supervisorMe.actor.kyc.verifiedAt);
+    expect(delegateMe.actor.kyc.source).toBe("membership");
+    expect(delegateMe.effective.kyc).toBeUndefined();
+  });
+
+  it("parses userinfo kyc onto the actor only, including a delegated session", async () => {
+    const h = makeHarness(
+      {
+        sso: () =>
+          Response.json({
+            sub: "u-delegate",
+            name: "Nok",
+            kyc: {
+              status: "verified",
+              verified: true,
+              verifiedAt: "2024-06-01T00:00:00.000Z",
+              source: "kyc",
+            },
+            ad: {
+              user: { id: 9, role: "province", mobile: "0810000009" },
+              actualPpleUser: { id: 14, role: "delegate", mobile: "0810000014" },
+              activeRole: "province",
+              eligibleRoles: ["province"],
+              eligibleProvinces: ["เชียงใหม่"],
+            },
+          }),
+      },
+      { DEV_PERSONA: "none" },
+    );
+    const me = await (await h.request("/api/me", {}, "valid-token")).json<{
+      actor: { kyc: { source: string; verifiedAt: string } };
+      effective: Record<string, unknown>;
+    }>();
+    expect(me.actor.kyc).toEqual({
+      status: "verified",
+      verified: true,
+      verifiedAt: "2024-06-01T00:00:00.000Z",
+      source: "kyc",
+    });
+    expect(me.effective.kyc).toBeUndefined();
+  });
+
+  it("defaults a userinfo payload with no kyc to none", async () => {
+    const h = makeHarness(
+      {
+        sso: () =>
+          Response.json({
+            sub: "u-42",
+            name: "Somchai",
+            ad: {
+              user: { id: 7, role: "hq", mobile: "0810000007" },
+              actualPpleUser: { id: 7, role: "hq", mobile: "0810000007" },
+              activeRole: "hq",
+              eligibleRoles: ["hq"],
+              eligibleProvinces: ["all"],
+            },
+          }),
+      },
+      { DEV_PERSONA: "none" },
+    );
+    const me = await (await h.request("/api/me", {}, "valid-token")).json<{
+      actor: { kyc: { status: string; verified: boolean; source: null } };
+    }>();
+    expect(me.actor.kyc).toEqual({
+      status: "none",
+      verified: false,
+      verifiedAt: null,
+      source: null,
+    });
+  });
+});
+
+describe("getLegalIdentity offline", () => {
+  it("never returns a checksum-valid citizen ID", async () => {
+    expect(thaiIdChecksumValid(OFFLINE_INVALID_ID)).toBe(false);
+    // A known-valid check digit for the same first 12 digits is 8.
+    expect(thaiIdChecksumValid("1100000000008")).toBe(true);
+
+    for (const name of Object.keys(DEV_PERSONAS)) {
+      const result = await getLegalIdentity({ DEV_PERSONA: name }, "ignored");
+      if (!result.ok) {
+        expect(result.reason).toBe("not_verified");
+        continue;
+      }
+      expect(result.legalIdentity.name).toBe(OFFLINE_LEGAL_NAME);
+      if (result.legalIdentity.idCardNumber !== null) {
+        expect(thaiIdChecksumValid(result.legalIdentity.idCardNumber)).toBe(false);
+      }
+    }
+
+    const member = await getLegalIdentity({ DEV_PERSONA: "hq-staff" }, "t");
+    expect(member).toEqual({
+      ok: true,
+      legalIdentity: { source: "membership", name: OFFLINE_LEGAL_NAME, idCardNumber: null },
+    });
+    const card = await getLegalIdentity({ DEV_PERSONA: "kyc-verified-nonmember" }, "t");
+    expect(card).toEqual({
+      ok: true,
+      legalIdentity: { source: "kyc", name: OFFLINE_LEGAL_NAME, idCardNumber: OFFLINE_INVALID_ID },
+    });
+    expect(await getLegalIdentity({ DEV_PERSONA: "unverified" }, "t")).toEqual({
+      ok: false,
+      reason: "not_verified",
+    });
+    expect(await getLegalIdentity({ DEV_PERSONA: "kyc-pending" }, "t")).toEqual({
+      ok: false,
+      reason: "not_verified",
+    });
+  });
+});
+
+describe("getLegalIdentity against Platform Services", () => {
+  const env = {
+    DEV_PERSONA: "none",
+    PPLE_SERVICES_URL: "https://services.test",
+    PPLE_APP_KEY: "app-key",
+  };
+
+  it("is not_configured until both bindings exist, and does not call out", async () => {
+    const fetchImpl = vi.fn<typeof fetch>();
+    expect(await getLegalIdentity({ DEV_PERSONA: "none" }, "tok", fetchImpl)).toEqual({
+      ok: false,
+      reason: "not_configured",
+    });
+    expect(
+      await getLegalIdentity({ DEV_PERSONA: "none", PPLE_SERVICES_URL: "https://services.test" }, "tok", fetchImpl),
+    ).toEqual({ ok: false, reason: "not_configured" });
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it("names every error the service can return", async () => {
+    const reasons: LegalIdentityReason[] = [
+      "invalid_app_key",
+      "not_granted",
+      "not_verified",
+      "user_token_invalid",
+      "identity_not_enabled",
+      "upstream_unavailable",
+    ];
+    for (const reason of reasons) {
+      const status = reason === "invalid_app_key" || reason === "user_token_invalid" ? 401 : 403;
+      const fetchImpl = vi.fn<typeof fetch>(async () => Response.json({ error: reason }, { status }));
+      expect(await getLegalIdentity(env, "user-token", fetchImpl)).toEqual({ ok: false, reason });
+      const [url, init] = fetchImpl.mock.calls[0]!;
+      expect(url).toBe("https://services.test/legal-identity");
+      expect(new Headers(init?.headers).get("authorization")).toBe("Bearer app-key");
+      expect(JSON.parse(String(init?.body))).toEqual({ token: "user-token" });
+    }
+  });
+
+  it("returns the Legal Identity the service answered with", async () => {
+    const fetchImpl = vi.fn<typeof fetch>(async () =>
+      Response.json({ source: "kyc", name: "นาย ก", idCardNumber: "1100000000008" }),
+    );
+    expect(await getLegalIdentity(env, "user-token", fetchImpl)).toEqual({
+      ok: true,
+      legalIdentity: { source: "kyc", name: "นาย ก", idCardNumber: "1100000000008" },
+    });
+  });
+
+  it("treats a transport failure and a body-less error as upstream_unavailable", async () => {
+    const down = vi.fn<typeof fetch>(async () => {
+      throw new Error("network");
+    });
+    expect(await getLegalIdentity(env, "user-token", down)).toEqual({
+      ok: false,
+      reason: "upstream_unavailable",
+    });
+
+    const odd = vi.fn<typeof fetch>(async () => new Response("nope", { status: 502 }));
+    expect(await getLegalIdentity(env, "user-token", odd)).toEqual({
+      ok: false,
+      reason: "upstream_unavailable",
+    });
+  });
+});
+
+describe("local KYC redirect", () => {
+  it("sends a local click straight back with ?kyc=cancelled", () => {
+    const back = kycStartUrl({
+      ssoBaseUrl: "https://id.example",
+      clientId: "zitadel-app",
+      returnTo: "https://app.example/checkout?step=1#pay",
+      dev: true,
+    });
+    const url = new URL(back);
+    expect(url.origin + url.pathname).toBe("https://app.example/checkout");
+    expect(url.searchParams.get("step")).toBe("1");
+    expect(url.searchParams.get("kyc")).toBe("cancelled");
+    expect(url.hash).toBe("#pay");
+  });
+
+  it("points production at PPLE ID /kyc", () => {
+    expect(
+      kycStartUrl({
+        ssoBaseUrl: "https://id.example",
+        clientId: "zitadel-app",
+        returnTo: "https://app.example/checkout",
+        dev: false,
+      }),
+    ).toBe(
+      "https://id.example/kyc?client_id=zitadel-app&return_to=https%3A%2F%2Fapp.example%2Fcheckout",
+    );
+  });
+});