@pplethai/cli 0.6.0 → 0.8.0

package/templates/golden-path/test/harness.ts

@@ -1,31 +1,98 @@
 import { env } from "cloudflare:test";
+import { callRegistry as dispatchRegistry, type CallRegistryOptions } from "../src/dev-registry";
 import type { Env } from "../src/env";
-import { createApp } from "../src/index";
+import worker, { createApp } from "../src/index";
 
 // A placeholder bearer. In tests `import.meta.env.DEV` is true, so the Worker
 // signs in as the default persona and ignores the token — the value only
 // matters on the real PPLE ID path, where tests pass an explicit one.
 export const DEV_TOKEN = "dev";
 
+/** What `callService` sent. The App Key and the user token are not kept. */
+export interface RecordedServiceCall {
+  /** Path and query, under the services origin. */
+  path: string;
+  method: string;
+  /** Headers other than `authorization` and `x-pple-user-token`. */
+  headers: Record<string, string>;
+}
+
+/**
+ * The Workers runtime builds this. Tests only need the methods a handler may
+ * call; the rest exists on the real context and nowhere a test can construct.
+ */
+export function testExecutionContext(): ExecutionContext {
+  return {
+    waitUntil() {},
+    passThroughOnException() {},
+    props: {},
+    exports: {},
+  } as unknown as ExecutionContext;
+}
+
 export interface Fakes {
   /** Handles GET {SSO_BASE_URL}/oidc/v1/userinfo */
   sso?: (req: Request) => Response | Promise<Response>;
   /** Handles POST {NOTIFY_API_BASE}/notifications */
   notify?: (req: Request) => Response | Promise<Response>;
+  /**
+   * Handles `{PPLE_SERVICES_URL}/<provider>/<name>/…` for `callService` and
+   * `readDataset`. Answer as the platform, or refuse with `serviceRefusal`
+   * and any `x-pple-error` code.
+   */
+  services?: (req: Request) => Response | Promise<Response>;
 }
 
+const SECRET_HEADERS = new Set(["authorization", "x-pple-user-token"]);
+
 /**
- * A copy of the Worker wired to fake PPLE ID / notification services (via an
- * injected fetch) and the real local D1 + R2 from the test runtime. Records
- * the requests sent to the notification endpoint so tests can assert the wire
- * shape — above all that every send states its audience.
+ * A platform refusal the services fake can return. `code` is not checked:
+ * a test can refuse with any `x-pple-error` value.
+ */
+export function serviceRefusal(code: string, status: number): Response {
+  return new Response(JSON.stringify({ error: code }), {
+    status,
+    headers: {
+      "content-type": "application/json",
+      "x-pple-error": code,
+    },
+  });
+}
+
+/**
+ * A copy of the Worker wired to fake PPLE ID, notifications, and Platform
+ * Services (via an injected fetch) and the real local D1 + R2 from the test
+ * runtime. Records the requests sent to the notification endpoint, and the
+ * path, method, and non-secret headers of each Service call.
  */
 export function makeHarness(fakes: Fakes = {}, envOverrides: Partial<Env> = {}) {
-  const calls = { notify: [] as Request[] };
+  const calls = {
+    notify: [] as Request[],
+    services: [] as RecordedServiceCall[],
+  };
+
+  const testEnv: Env = {
+    ...env,
+    SSO_BASE_URL: "https://sso.test",
+    NOTIFY_API_BASE: "",
+    // No DEV_PERSONA ⇒ the default persona. Pass { DEV_PERSONA: "none" } to
+    // exercise the real PPLE ID path instead.
+    ...envOverrides,
+  };
+
+  const servicesBase = (testEnv.PPLE_SERVICES_URL ?? "").replace(/\/+$/, "");
 
   const fetchImpl: typeof fetch = async (input, init) => {
     const req = new Request(input as RequestInfo, init);
     const url = new URL(req.url);
+    if (servicesBase && isServicesUrl(req.url, servicesBase)) {
+      calls.services.push({
+        path: url.pathname + url.search,
+        method: req.method,
+        headers: publicHeaders(req.headers),
+      });
+      return fakes.services ? fakes.services(req) : new Response(null, { status: 502 });
+    }
     if (url.pathname.endsWith("/oidc/v1/userinfo")) {
       return fakes.sso ? fakes.sso(req) : new Response(null, { status: 502 });
     }
@@ -38,15 +105,6 @@ export function makeHarness(fakes: Fakes = {}, envOverrides: Partial<Env> = {})
 
   const app = createApp({ fetchImpl });
 
-  const testEnv: Env = {
-    ...env,
-    SSO_BASE_URL: "https://sso.test",
-    NOTIFY_API_BASE: "",
-    // No DEV_PERSONA ⇒ the default persona. Pass { DEV_PERSONA: "none" } to
-    // exercise the real PPLE ID path instead.
-    ...envOverrides,
-  };
-
   const request = (
     path: string,
     init: RequestInit = {},
@@ -57,5 +115,32 @@ export function makeHarness(fakes: Fakes = {}, envOverrides: Partial<Env> = {})
     return app.request(path, { ...init, headers }, testEnv);
   };
 
-  return { app, request, testEnv, calls };
+  const execution = testExecutionContext();
+
+  /**
+   * Call `registry[name]` the way the platform does: the tail path and the
+   * `x-pple-*` facts. `persona` and `consumer` override this harness's env.
+   * An entry with no fetch-shaped handler throws `registry handler missing`
+   * — the platform wrapper's error. pple-services turns that into
+   * `provider_unavailable` (502) for the Consumer; this does not, because
+   * that response is not what the Provider's handler sees.
+   */
+  const callRegistry = (name: string, path: string, options: CallRegistryOptions = {}) =>
+    dispatchRegistry(worker, testEnv, execution, name, path, options);
+
+  return { app, request, testEnv, calls, fetchImpl, callRegistry };
+}
+
+function isServicesUrl(url: string, base: string): boolean {
+  return url === base || url.startsWith(`${base}/`) || url.startsWith(`${base}?`);
+}
+
+function publicHeaders(headers: Headers): Record<string, string> {
+  const recorded: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    const name = key.toLowerCase();
+    if (SECRET_HEADERS.has(name)) return;
+    recorded[name] = value;
+  });
+  return recorded;
 }

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

@@ -0,0 +1,323 @@
+// 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,
+} from "../src/legal-identity";
+import { makeHarness, serviceRefusal } 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("posts to platform/legal-identity with the App Key and the user token, and no body", async () => {
+    let seen: { authorization: string | null; userToken: string | null; body: string } | undefined;
+    const h = makeHarness(
+      {
+        services: async (req) => {
+          seen = {
+            authorization: req.headers.get("authorization"),
+            userToken: req.headers.get("x-pple-user-token"),
+            body: await req.text(),
+          };
+          return Response.json({ source: "kyc", name: "นาย ก", idCardNumber: "1100000000008" });
+        },
+      },
+      env,
+    );
+
+    expect(await getLegalIdentity(h.testEnv, "user-token", h.fetchImpl)).toEqual({
+      ok: true,
+      legalIdentity: { source: "kyc", name: "นาย ก", idCardNumber: "1100000000008" },
+    });
+    expect(seen).toEqual({
+      authorization: "Bearer app-key",
+      userToken: "user-token",
+      body: "",
+    });
+    expect(h.calls.services).toEqual([
+      { path: "/platform/legal-identity", method: "POST", headers: {} },
+    ]);
+  });
+
+  it("maps each platform code, and keeps needs_beta as its own reason", async () => {
+    type Mapped =
+      | "invalid_app_key"
+      | "not_granted"
+      | "needs_beta"
+      | "user_token_invalid"
+      | "upstream_unavailable";
+    const mapped: [string, number, Mapped][] = [
+      ["invalid_app_key", 401, "invalid_app_key"],
+      ["not_granted", 403, "not_granted"],
+      ["needs_beta", 403, "needs_beta"],
+      ["user_token_invalid", 401, "user_token_invalid"],
+      ["not_listed", 404, "upstream_unavailable"],
+      ["identity_unavailable", 503, "upstream_unavailable"],
+      ["provider_unavailable", 502, "upstream_unavailable"],
+      ["provider_timeout", 504, "upstream_unavailable"],
+    ];
+    let next = serviceRefusal("invalid_app_key", 401);
+    const h = makeHarness({ services: () => next }, env);
+    for (const [code, status, reason] of mapped) {
+      next = serviceRefusal(code, status);
+      expect(await getLegalIdentity(h.testEnv, "user-token", h.fetchImpl)).toEqual({ ok: false, reason });
+    }
+
+    // A code this helper does not name is still a platform refusal.
+    next = serviceRefusal("identity_not_enabled", 403);
+    expect(await getLegalIdentity(h.testEnv, "user-token", h.fetchImpl)).toEqual({
+      ok: false,
+      reason: "upstream_unavailable",
+    });
+  });
+
+  it("maps this Service's own answers, which carry no x-pple-error", async () => {
+    type Answer = "not_verified" | "user_token_invalid" | "upstream_unavailable";
+    const answers: [string, number, Answer][] = [
+      ["not_verified", 404, "not_verified"],
+      ["user_token_invalid", 401, "user_token_invalid"],
+      ["upstream_unavailable", 502, "upstream_unavailable"],
+    ];
+    let next = Response.json({ error: "not_verified" }, { status: 404 });
+    const h = makeHarness(
+      {
+        services: (req) => {
+          expect(req.headers.get("x-pple-error")).toBeNull();
+          return next;
+        },
+      },
+      env,
+    );
+    for (const [error, status, reason] of answers) {
+      next = Response.json({ error }, { status });
+      expect(await getLegalIdentity(h.testEnv, "user-token", h.fetchImpl)).toEqual({ ok: false, reason });
+    }
+
+    // The old reason is not read off a Provider body.
+    next = Response.json({ error: "identity_not_enabled" }, { status: 403 });
+    expect(await getLegalIdentity(h.testEnv, "user-token", h.fetchImpl)).toEqual({
+      ok: false,
+      reason: "upstream_unavailable",
+    });
+    // needs_beta is a platform code. Without the header it is not that reason.
+    next = Response.json({ error: "needs_beta" }, { status: 403 });
+    expect(await getLegalIdentity(h.testEnv, "user-token", h.fetchImpl)).toEqual({
+      ok: false,
+      reason: "upstream_unavailable",
+    });
+  });
+
+  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",
+    );
+  });
+});

package/templates/golden-path/test/membership.test.ts

@@ -0,0 +1,105 @@
+// Actor membership (ADR-0028): userinfo onto the Persona path, and the
+// member-only Persona that makes member and internal differ offline.
+
+import { describe, expect, it } from "vitest";
+import { DEV_PERSONAS } from "../src/dev-personas";
+import { passesLevel } from "../src/levels";
+import { makeHarness } from "./harness";
+
+const AD = {
+  user: { id: 7, role: "hq", mobile: "0810000007" },
+  actualPpleUser: { id: 7, role: "hq", mobile: "0810000007" },
+  activeRole: "hq",
+  eligibleRoles: ["hq"],
+  eligibleProvinces: ["all"],
+};
+
+function signedIn(membership: unknown) {
+  return makeHarness(
+    {
+      sso: () =>
+        Response.json({
+          sub: "u-42",
+          name: "Somchai",
+          ad: AD,
+          ...(membership === undefined ? {} : { membership }),
+        }),
+    },
+    { DEV_PERSONA: "none" },
+  );
+}
+
+describe("actor.membership", () => {
+  it("keeps memberSince from userinfo and drops the address", async () => {
+    const h = signedIn({
+      type: "yearly",
+      memberSince: "2020-05-01",
+      registeredAddress: { province: "เชียงใหม่", district: "เมืองเชียงใหม่" },
+    });
+    const me = await (await h.request("/api/me", {}, "valid-token")).json<{
+      actor: { membership: { memberSince: string } | null };
+      effective: Record<string, unknown>;
+    }>();
+    expect(me.actor.membership).toEqual({ memberSince: "2020-05-01" });
+    expect(JSON.stringify(me)).not.toContain("registeredAddress");
+    expect(me.effective.membership).toBeUndefined();
+  });
+
+  it.each([
+    ["missing", undefined],
+    ["null", null],
+    ["an empty object", {}],
+    ["a datetime", { memberSince: "2020-05-01T00:00:00.000Z" }],
+  ] as const)("is null when userinfo membership is %s", async (_label, membership) => {
+    const h = signedIn(membership);
+    const me = await (await h.request("/api/me", {}, "valid-token")).json<{
+      actor: { membership: unknown };
+    }>();
+    expect(me.actor.membership).toBeNull();
+  });
+
+  it("gives every Persona a membership, and member has no Role", () => {
+    for (const persona of Object.values(DEV_PERSONAS)) {
+      expect(persona.actor.membership === null || typeof persona.actor.membership?.memberSince === "string").toBe(
+        true,
+      );
+      expect("membership" in persona.effective).toBe(false);
+      expect(typeof persona.effective.sub).toBe("string");
+      if (persona.effective.isDelegated) {
+        expect(persona.effective.sub).not.toBe(persona.actor.sub);
+      } else {
+        expect(persona.effective.sub).toBe(persona.actor.sub);
+      }
+    }
+    expect(DEV_PERSONAS.member).toMatchObject({
+      actor: { sub: "dev-member", membership: { memberSince: "2024-06-01" } },
+      effective: { sub: "dev-member", activeRole: "", isDelegated: false, extraRoles: [] },
+    });
+    expect(DEV_PERSONAS["hq-staff"]?.actor.membership).toEqual({ memberSince: "2024-01-01" });
+    expect(DEV_PERSONAS.unverified?.actor.membership).toBeNull();
+    expect(DEV_PERSONAS["kyc-pending"]?.actor.membership).toBeNull();
+    expect(DEV_PERSONAS["kyc-verified-nonmember"]?.actor.membership).toBeNull();
+  });
+
+  it("lets a member pass member and not internal, and staff pass both", () => {
+    const persona = DEV_PERSONAS.member;
+    if (!persona) throw new Error("member persona missing");
+    expect(passesLevel(null, "public")).toBe(true);
+    expect(passesLevel(null, "member")).toBe(false);
+    expect(passesLevel(persona, "public")).toBe(true);
+    expect(passesLevel(persona, "member")).toBe(true);
+    expect(passesLevel(persona, "internal")).toBe(false);
+    expect(passesLevel(persona, { roles: ["pple-ad:hq"] })).toBe(false);
+    expect(passesLevel(DEV_PERSONAS["hq-staff"]!, "internal")).toBe(true);
+    expect(passesLevel(DEV_PERSONAS["hq-staff"]!, "member")).toBe(true);
+    expect(passesLevel(DEV_PERSONAS.unverified!, "member")).toBe(false);
+    expect(passesLevel(DEV_PERSONAS["kyc-verified-nonmember"]!, "member")).toBe(false);
+    expect(passesLevel(DEV_PERSONAS.delegate!, "member")).toBe(true);
+    expect(passesLevel(DEV_PERSONAS.delegate!, { subs: ["dev-delegate"] })).toBe(true);
+    expect(passesLevel(DEV_PERSONAS.delegate!, { subs: ["dev-province-coordinator"] })).toBe(true);
+    expect(DEV_PERSONAS.delegate?.effective.sub).toBe("dev-province-coordinator");
+    expect(passesLevel(DEV_PERSONAS["hq-staff"]!, { subs: ["dev-province-coordinator"] })).toBe(false);
+    expect(passesLevel(DEV_PERSONAS["platform-admin"]!, { roles: ["pple-ad:mp"] })).toBe(false);
+    expect(passesLevel(DEV_PERSONAS["platform-admin"]!, { roles: ["pple-ad:platform:admin"] })).toBe(true);
+  });
+});