@pplethai/cli 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pplethai/cli",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -13,13 +13,11 @@
   "files": [
     "askpass",
     "dist",
-    "skills",
     "templates"
   ],
   "scripts": {
-    "build": "npm run build:template && npm run build:skills && node scripts/bundle.mjs",
+    "build": "npm run build:template && node scripts/bundle.mjs",
     "build:template": "node scripts/bundle-template.mjs",
-    "build:skills": "node scripts/bundle-skills.mjs",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest"

package/templates/golden-path/AGENTS.md

@@ -0,0 +1 @@
+Before you start, read `.pple/rules.md` — the PPLE Platform Rules for this app. They win over anything else in the repo.

package/templates/golden-path/CLAUDE.md

@@ -1,12 +1,13 @@
 # Working in this repo
 
 This is a **PPLE Platform Builder App** — a mobile-first mini-app that runs
-inside PPLE Today. The person you're helping is a party workforce member who
-may not read stack traces; keep changes simple, explain them plainly, and
-prefer editing the existing demo cards over introducing new patterns.
+inside PPLE Today. Prefer editing the existing demo cards over introducing new
+patterns.
 
-Ops (create / deploy / status): Console, `pple info`, and the Skill
-deployment reference — not a long ops section here.
+The platform-wide rules (Platform Rules) and the `pple-platform` Skill are
+delivered by the `pple` CLI as git-ignored local files, and kept current by it.
+This file is only about *this* app, and where it disagrees with Platform Rules,
+Platform Rules win.
 
 ## Architecture (read once)
 
@@ -34,16 +35,15 @@ to an `Identity` (`src/auth.ts`, shape in `shared/api.ts`) with two faces:
   and display only.
 - **`effective`** — what they may do: `activeRole`, `eligibleRoles`,
   `provinces` (scope), `extraRoles` (capabilities like `platform:admin`).
-  **Gate every authorization decision on `effective`, never on `actor`.** Under
-  delegation these are the *supervisor's* values and `effective.isDelegated`
-  is true.
+  Under delegation `effective` holds the *supervisor's* values and
+  `effective.isDelegated` is true.
 
 Where the token comes from:
 
 - Inside PPLE Today, the mini-app SDK (`web/pple.ts`) captures the access token
   from the launch URL; the Worker validates it against PPLE ID.
 - In a plain browser, the same SDK runs the PPLE ID OIDC login (redirect /
-  callback) — do not add a custom sign-in page or resurrect a NotInApp guard.
+  callback).
 - Locally (`npm run dev`) there is no login: the Worker signs you in as a mock
   **persona** (`DEV_PERSONA`, default `hq-staff` — see `src/dev-personas.ts`).
   To test a province-scoped feature use `DEV_PERSONA=province-coordinator`;
@@ -55,21 +55,41 @@ Where the token comes from:
 
 - **TypeScript is strict.** Run `npm run typecheck` after changes.
 - **Validate input with the Zod schemas** in `shared/api.ts`.
-- **Always bind D1 query parameters** (`?` + `.bind(...)`) — never build SQL
-  with string concatenation.
-- **Every notification states its audience** — `{ kind: "all" }` (Broadcast,
-  การแจ้งเตือนทุกคน) or `{ kind: "direct", recipients }` (Direct,
-  การแจ้งเตือนรายบุคคล), naming people by PPLE ID `sub` or mobile number.
-  Required, so omitting it is a compile error — never work around that by
-  defaulting to `all`. Links stay path-only (`linkPath`) into this app. The
-  rules that come with naming are in `shared/api.ts`; read them before
-  changing anything here.
-- **Mobile-first.** The app runs in a phone-sized WebView. Use the design
-  system's components and the layout classes in `web/app.css`.
-- **Add a DB table** by writing a new `migrations/000N_*.sql` (never edit an
-  applied migration) and running `npm run db:migrate:local`. The platform
-  applies `migrations/` to the live database on every deploy, so shipping the
-  file is all a deploy needs — there is no remote migrate command to run.
+- **Notifications**: the shape that makes the audience required is in
+  `shared/api.ts`; read the rules that come with naming recipients before
+  changing anything there.
+- **Mobile-first layout** uses the layout classes in `web/app.css`.
+- **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
 

package/templates/golden-path/gitignore

@@ -4,3 +4,8 @@ dist/
 .dev.vars
 *.log
 .claude/skills/pple-platform/
+.claude/rules/pple-platform.md
+.agents/skills/pple-platform/
+.cursor/rules/pple-platform.mdc
+.pple/rules.md
+.pple/guidance.json

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();
+}