@pplethai/cli 0.6.0 → 0.8.0

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

@@ -0,0 +1,276 @@
+// Offline Provider development (ADR-0026). Active only where
+// `import.meta.env.DEV` is true — `vite dev` and the template tests. The
+// production build drops this module the same way it drops the Persona
+// bypass (ADR-0011).
+//
+// `npm run dev` has no platform wrapper and no platform-call secret, so a
+// Builder can curl `/.pple/registry/<name>/…` directly. This delivers that
+// request to `registry[name]` the way the platform wrapper does: the tail
+// path, the method and body, and the `x-pple-*` facts. Incoming `x-pple-*`
+// headers are never trusted. Public traffic has them stripped before app
+// code, so dev and production agree that a Builder cannot invent platform
+// facts.
+//
+// Identity choice. An unset `DEV_PERSONA` uses the default Persona, as the
+// rest of local dev does. `DEV_PERSONA=none` sends no `x-pple-identity`,
+// which is what the platform does for an entry that declares
+// `userToken: none`. A name that is not a Persona does the same, and does
+// not fall back to the default: a registry call must not invent a caller.
+// `/api` still falls back, so a typo does not lock the Builder out of the
+// app. The Consumer is `DEV_CONSUMER`, or `dev-consumer`. The entry id is
+// `dev-provider/<name>` — a local app has no App Slug until the platform
+// creates it.
+//
+// A Dataset value is an object of page functions. `/.pple/registry/<name>/<objectType>`
+// calls that function with `{ cursor }` and answers with its page. A value with
+// no fetch-shaped handler, and a page map with no function for the segment,
+// throws `registry handler missing`, the error the platform wrapper throws.
+// `pple-services` turns that throw
+// into `provider_unavailable` (502). Nothing here invents that response:
+// locally there is no gateway in front of the handler, and the 502 is a
+// Consumer-facing answer the Provider's code never sees. Other `/.pple/`
+// paths (cron, the deploy probe) are not emulated; they reach app code with
+// platform headers stripped.
+
+import type { Identity } from "../shared/api";
+import { DEV_PERSONAS, DEFAULT_DEV_PERSONA } from "./dev-personas";
+import type { Env } from "./env";
+import { encodeIdentityHeader } from "./identity-header";
+import {
+  CONSUMER_HEADER,
+  ENTRY_HEADER,
+  IDENTITY_HEADER,
+  type DatasetPages,
+  type RegistryFetch,
+  type RegistryMap,
+} from "./registry";
+
+export const DEFAULT_DEV_CONSUMER = "dev-consumer";
+
+/** Local stand-in for the App Slug. The entry id is `${DEV_PROVIDER_SLUG}/<name>`. */
+export const DEV_PROVIDER_SLUG = "dev-provider";
+
+const REGISTRY_PATH_PREFIX = "/.pple/registry/";
+
+const HOP_BY_HOP = new Set([
+  "host",
+  "connection",
+  "keep-alive",
+  "transfer-encoding",
+  "te",
+  "trailer",
+  "upgrade",
+]);
+
+export interface DevWorker {
+  fetch: RegistryFetch;
+  registry?: RegistryMap;
+}
+
+export interface CallRegistryOptions {
+  /**
+   * Persona for `x-pple-identity`. `"none"` or an unknown name sends none.
+   * Omit to use the env's `DEV_PERSONA`.
+   */
+  persona?: string;
+  /** Consumer slug. Omit to use `DEV_CONSUMER`, then `dev-consumer`. */
+  consumer?: string;
+  /**
+   * Method and body, which the platform preserves. `x-pple-*`, Authorization
+   * and Cookie here are dropped: the call sets the platform facts itself.
+   */
+  init?: RequestInit;
+}
+
+/** The Identity a dev registry call carries, or null for `userToken: none`. */
+export function devRegistryIdentity(name: string | undefined): Identity | null {
+  const key = name?.trim() || DEFAULT_DEV_PERSONA;
+  if (key === "none") return null;
+  const persona = DEV_PERSONAS[key];
+  if (persona) return persona;
+  console.warn(
+    `Unknown DEV_PERSONA "${key}" on the emulated registry path; sending no Identity ` +
+      `(userToken: none). Valid personas: ${Object.keys(DEV_PERSONAS).join(", ")}.`,
+  );
+  return null;
+}
+
+export function devConsumerSlug(value: string | undefined): string {
+  const slug = value?.trim();
+  return slug ? slug : DEFAULT_DEV_CONSUMER;
+}
+
+/**
+ * Dev entry. Registry calls go to `user.registry`. Everything else is public
+ * traffic: `x-pple-*` is removed, then `user.fetch` runs.
+ */
+export async function devWorkerFetch(
+  user: DevWorker,
+  request: Request,
+  env: Env,
+  ctx: ExecutionContext,
+): Promise<Response> {
+  const url = new URL(request.url);
+  const parsed = parseRegistryPath(url.pathname);
+  if (!parsed) return user.fetch(stripPlatformHeaders(request), env, ctx);
+  if (!parsed.name) return emptyRegistryResponse();
+
+  const pages = datasetPages(user.registry, parsed.name);
+  if (pages) return runDatasetPage(pages, parsed.tail, request, env, ctx);
+
+  const headers = handlerHeaders(
+    request.headers,
+    registryFacts(parsed.name, devConsumerSlug(env.DEV_CONSUMER), devRegistryIdentity(env.DEV_PERSONA)),
+  );
+  const target = new URL(request.url);
+  target.pathname = parsed.tail;
+  return handlerFor(user.registry, parsed.name)(
+    forwardedRequest(target, request.method, headers, request.body),
+    env,
+    ctx,
+  );
+}
+
+/**
+ * Call `registry[name]` the way the platform wrapper does. See the file
+ * comment for a missing handler: this throws `registry handler missing`.
+ */
+export async function callRegistry(
+  user: DevWorker,
+  env: Env,
+  ctx: ExecutionContext,
+  name: string,
+  path: string,
+  options: CallRegistryOptions = {},
+): Promise<Response> {
+  if (!name) return emptyRegistryResponse();
+  const personaName = options.persona !== undefined ? options.persona : env.DEV_PERSONA;
+  const consumerName = options.consumer !== undefined ? options.consumer : env.DEV_CONSUMER;
+  const headers = handlerHeaders(
+    new Headers(options.init?.headers),
+    registryFacts(name, devConsumerSlug(consumerName), devRegistryIdentity(personaName)),
+  );
+  const method = options.init?.method ?? "GET";
+  const body = options.init?.body ?? null;
+  // No incoming Host: the pathname and query are the tail the platform sets.
+  const request = forwardedRequest(tailUrl(path), method, headers, body);
+  const pages = datasetPages(user.registry, name);
+  if (pages) return runDatasetPage(pages, new URL(request.url).pathname, request, env, ctx);
+  return handlerFor(user.registry, name)(request, env, ctx);
+}
+
+function registryFacts(
+  name: string,
+  consumer: string,
+  identity: Identity | null,
+): { consumer: string; entry: string; identity: Identity | null } {
+  return { consumer, entry: `${DEV_PROVIDER_SLUG}/${name}`, identity };
+}
+
+/** What the handler sees. Matches pple-services' header filter, minus the secret. */
+function handlerHeaders(
+  incoming: Headers,
+  facts: { consumer: string; entry: string; identity: Identity | null },
+): Headers {
+  const headers = new Headers();
+  for (const [key, value] of incoming) {
+    const lower = key.toLowerCase();
+    if (
+      lower === "authorization" ||
+      lower === "cookie" ||
+      lower.startsWith("x-pple-") ||
+      HOP_BY_HOP.has(lower)
+    ) {
+      continue;
+    }
+    headers.set(key, value);
+  }
+  headers.set(CONSUMER_HEADER, facts.consumer);
+  headers.set(ENTRY_HEADER, facts.entry);
+  if (facts.identity) headers.set(IDENTITY_HEADER, encodeIdentityHeader(facts.identity));
+  return headers;
+}
+
+function datasetPages(registry: RegistryMap | undefined, name: string): DatasetPages | null {
+  const value = registry?.[name];
+  if (typeof value !== "object" || value === null || typeof value.fetch === "function") return null;
+  return value as DatasetPages;
+}
+
+/**
+ * A Dataset page function is `{ cursor }` in, a page out. The path's single
+ * segment is the Object Type. No segment, or no function by that name, is
+ * the same missing-handler failure as a Service with nothing fetch-shaped.
+ */
+async function runDatasetPage(
+  pages: DatasetPages,
+  tail: string,
+  request: Request,
+  env: Env,
+  ctx: ExecutionContext,
+): Promise<Response> {
+  const objectType = tail.startsWith("/") ? tail.slice(1) : tail;
+  const fn = objectType.includes("/") || objectType === "" ? undefined : pages[objectType];
+  if (typeof fn !== "function") throw new Error("registry handler missing");
+  let cursor: string | null = null;
+  if (request.method !== "GET" && request.method !== "HEAD" && request.body) {
+    try {
+      const body = (await request.json()) as { cursor?: unknown };
+      if (body && typeof body.cursor === "string") cursor = body.cursor;
+    } catch {
+      cursor = null;
+    }
+  }
+  return Response.json(await fn({ cursor }, env, ctx));
+}
+
+function handlerFor(registry: RegistryMap | undefined, name: string): RegistryFetch {
+  const value = registry?.[name];
+  if (typeof value === "function") return value;
+  if (value && typeof value === "object" && typeof value.fetch === "function") {
+    const app = value as { fetch: RegistryFetch };
+    return (request, env, ctx) => app.fetch(request, env, ctx);
+  }
+  throw new Error("registry handler missing");
+}
+
+function parseRegistryPath(pathname: string): { name: string; tail: string } | null {
+  if (pathname !== "/.pple/registry" && !pathname.startsWith(REGISTRY_PATH_PREFIX)) return null;
+  const restPath = pathname.startsWith(REGISTRY_PATH_PREFIX)
+    ? pathname.slice(REGISTRY_PATH_PREFIX.length)
+    : "";
+  const slash = restPath.indexOf("/");
+  const name = slash === -1 ? restPath : restPath.slice(0, slash);
+  const tail = slash === -1 ? "/" : restPath.slice(slash) || "/";
+  return { name, tail };
+}
+
+function tailUrl(path: string): URL {
+  const raw = path.startsWith("/") ? path : `/${path}`;
+  return new URL(raw, "https://provider.invalid");
+}
+
+function forwardedRequest(url: URL, method: string, headers: Headers, body: BodyInit | null): Request {
+  const init: RequestInit & { duplex?: "half" } = { method, headers };
+  if (method !== "GET" && method !== "HEAD" && body != null) {
+    init.body = body;
+    init.duplex = "half";
+  }
+  return new Request(url, init);
+}
+
+function stripPlatformHeaders(request: Request): Request {
+  const headers = new Headers(request.headers);
+  let changed = false;
+  for (const key of [...headers.keys()]) {
+    if (key.toLowerCase().startsWith("x-pple-")) {
+      headers.delete(key);
+      changed = true;
+    }
+  }
+  return changed ? new Request(request, { headers }) : request;
+}
+
+function emptyRegistryResponse(): Response {
+  return new Response(null, { status: 404, headers: { "cache-control": "no-store" } });
+}

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

@@ -14,8 +14,25 @@ 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. `callService` reads them
+  // (src/call-service.ts); the Builder does not put the App Key on a request.
+  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.
   DEV_PERSONA?: string;
+
+  // Local development only: make offline `callService` and `readDataset`
+  // return a platform refusal instead of a mock (`not_granted`,
+  // `level_not_met`, …). A bare code applies to every entry;
+  // `<provider>/<name>=<code>` wins for that entry. Comma-separated.
+  // Compiled out with the offline path.
+  DEV_REGISTRY_ERROR?: string;
+
+  // Local development only: the Consumer slug on the emulated registry path.
+  // Unset means `dev-consumer`. Compiled out with the dev wrapper.
+  DEV_CONSUMER?: string;
 }

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

@@ -0,0 +1,17 @@
+// How a Provider test and the dev server build `x-pple-identity` (ADR-0024).
+//
+// Base64url (RFC 4648 §5, no padding) of the UTF-8 JSON `{ actor, effective }`.
+// A Thai name is not a reliable raw header value. `serviceCall` decodes this
+// exact encoding. The platform's copy is
+// `workers/src/services/identity-header.ts`; a test keeps the two strings
+// equal. One function, so the dev wrapper and `callRegistry` cannot drift.
+
+import type { Identity } from "../shared/api";
+
+/** Base64url of the Identity JSON. ASCII, so it survives an HTTP header. */
+export function encodeIdentityHeader(identity: Identity): string {
+  const bytes = new TextEncoder().encode(JSON.stringify(identity));
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}

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

@@ -9,8 +9,10 @@ import { CreateNoteSchema, NotificationSchema } from "../shared/api";
 import { authenticate } from "./auth";
 import { addNote, listNotes } from "./db";
 import type { Env } from "./env";
+import { devWorkerFetch } from "./dev-registry";
 import { getFile, listFiles, putFile } from "./files";
 import { sendNotification } from "./notify";
+import type { PpleWorker, RegistryFetch, RegistryMap } from "./registry";
 
 /** Test seam: real fetch by default, an injected fake in tests. */
 export interface AppOverrides {
@@ -113,4 +115,33 @@ export function createApp(overrides: AppOverrides = {}) {
   return app;
 }
 
-export default createApp();
+const api = createApp();
+
+const registry: RegistryMap = {};
+
+const appFetch: RegistryFetch = (request, env, ctx) => api.fetch(request, env, ctx);
+
+/**
+ * The Worker entry. `registry` is where a Service handler or a Dataset's page
+ * functions live, keyed by the entry name. A Hono app plugs straight in
+ * (`registry: { "<name>": app }`). A Dataset is an object of page functions
+ * (`registry: { "<name>": { "<objectType>": ({ cursor }, env, ctx) => page } }`).
+ * The platform calls a Service at `/.pple/registry/<name>/…` and a Dataset at
+ * `/.pple/registry/<name>/<objectType>`. Read a Service caller with
+ * `serviceCall(request)` from `./registry`.
+ *
+ * Under `vite dev` the same path is emulated locally. `import.meta.env.DEV`
+ * is false in `vite build`, so that branch and `dev-registry.ts` are absent
+ * from the deployed Worker, the same way the Persona bypass is (ADR-0011).
+ */
+const worker: PpleWorker = {
+  fetch(request, env, ctx) {
+    if (import.meta.env.DEV) {
+      return devWorkerFetch({ fetch: appFetch, registry }, request, env, ctx);
+    }
+    return appFetch(request, env, ctx);
+  },
+  registry,
+};
+
+export default worker;

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

@@ -0,0 +1,180 @@
+// Legal Identity (CONTEXT.md). A Builder App reads a person's name and
+// citizen ID from the Private Platform Service `platform/legal-identity`,
+// only under a Use Grant of that entry, 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 { callService, platformError, type PlatformErrorCode } from "./call-service";
+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"
+  | "needs_beta"
+  | "not_verified"
+  | "user_token_invalid"
+  | "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";
+
+/** What this Service itself answers, with no `x-pple-error` header. */
+const PROVIDER_REASONS = ["not_verified", "user_token_invalid", "upstream_unavailable"] as const;
+
+type ProviderReason = (typeof PROVIDER_REASONS)[number];
+
+/** 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.
+ *
+ * Offline (`npm run dev` with a Persona) this never calls out. Otherwise it
+ * wraps `callService(env, "platform/legal-identity", "", { method: "POST" },
+ * { userToken })`. `not_configured` means PPLE_SERVICES_URL or PPLE_APP_KEY
+ * is missing. `needs_beta` means the Use Grant is held and the app is still
+ * Draft. `not_listed`, `identity_unavailable`, `provider_unavailable` and
+ * `provider_timeout` are `upstream_unavailable`.
+ */
+export async function getLegalIdentity(
+  env: LegalIdentityEnv,
+  token: string,
+  fetchImpl?: typeof fetch,
+): 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 callService(
+      env,
+      "platform/legal-identity",
+      "",
+      { method: "POST" },
+      { userToken: token, ...(fetchImpl ? { fetchImpl } : {}) },
+    );
+  } catch {
+    return { ok: false, reason: "upstream_unavailable" };
+  }
+
+  // A platform refusal carries `x-pple-error`. This Service's own answers
+  // do not, so a body `error` is trusted only when the header is absent.
+  if (res.headers.get("x-pple-error")) {
+    return { ok: false, reason: platformReason(platformError(res)) };
+  }
+
+  const body = (await res.json().catch(() => ({}))) as {
+    error?: string;
+    source?: string;
+    name?: string;
+    idCardNumber?: string | null;
+  };
+  const provider = providerReason(body.error);
+  if (provider) return { ok: false, reason: provider };
+  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 platformReason(code: PlatformErrorCode | null): LegalIdentityReason {
+  switch (code) {
+    case "invalid_app_key":
+    case "not_granted":
+    case "needs_beta":
+    case "user_token_invalid":
+      return code;
+    default:
+      return "upstream_unavailable";
+  }
+}
+
+function providerReason(error: string | undefined): ProviderReason | null {
+  return PROVIDER_REASONS.find((reason) => reason === error) ?? null;
+}
+
+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/src/levels.ts

@@ -0,0 +1,132 @@
+// Whether an Identity passes a Dataset Access Level (ADR-0028).
+//
+// A copy of workers/src/shared/registry/levels.ts. This file is copied into
+// a Builder App, which cannot import the platform package. Offline reads
+// (#270) use this copy so a Persona sees the same refusals as production.
+// cli/test/registry-levels.test.ts keeps the two in step.
+
+export type AccessLevel =
+  | "public"
+  | "member"
+  | "internal"
+  | {
+      roles?: readonly string[];
+      subs?: readonly string[] | "swept";
+    };
+
+/** The Identity facts a level reads. Other Identity fields are ignored. */
+export interface LevelIdentity {
+  actor: {
+    sub: string;
+    /** Non-null only while PPLE ID reports an active party membership. */
+    membership: { memberSince: string } | null;
+  };
+  effective: {
+    isDelegated: boolean;
+    /**
+     * PPLE ID sub of the person whose authority is in effect.
+     * The Actor's own sub when nobody is delegating. Under Delegation, the
+     * supervisor's Zitadel sub, or null when that id is missing. Null matches
+     * no custom `subs`.
+     */
+    sub: string | null;
+    activeRole: string;
+    extraRoles: readonly string[];
+  };
+}
+
+export interface PassesLevelOptions {
+  /**
+   * The snapshot's subs when the level says `subs: "swept"`.
+   * The caller passes the list (#267, #269). This function never loads it.
+   * Absent means empty, so swept subs admit nobody until a sweep has landed.
+   */
+  sweptSubs?: readonly string[];
+}
+
+/**
+ * Live visibility stores `pple-ad:` plus the bare Active Role or Extra Role,
+ * the vocabulary `GET /role-options` returns. A custom level uses that
+ * same vocabulary, matched by exact string against that prefixed union.
+ * Eligible Roles are not part of the union.
+ */
+const ROLE_PREFIX = "pple-ad:";
+
+function bareRole(role: string): string {
+  return role.startsWith(ROLE_PREFIX) ? role.slice(ROLE_PREFIX.length) : role;
+}
+
+function viewerRoles(identity: LevelIdentity): Set<string> {
+  const roles = new Set<string>();
+  const add = (role: unknown) => {
+    if (typeof role !== "string" || role === "") return;
+    roles.add(`${ROLE_PREFIX}${bareRole(role)}`);
+  };
+  add(identity.effective.activeRole);
+  const extras = identity.effective.extraRoles;
+  if (Array.isArray(extras)) {
+    for (const extra of extras) add(extra);
+  }
+  return roles;
+}
+
+function passesInternal(identity: LevelIdentity): boolean {
+  return typeof identity.effective.activeRole === "string" && identity.effective.activeRole !== "";
+}
+
+function passesMember(identity: LevelIdentity): boolean {
+  // A delegate is read with the supervisor's authority at every level.
+  // A null membership (the lookup failed, or there is none) does not pass on its own.
+  if (identity.effective.isDelegated === true) return true;
+  if (identity.actor.membership !== null && identity.actor.membership !== undefined) return true;
+  return passesInternal(identity);
+}
+
+/**
+ * Custom `subs` match the Actor's `sub`. Under Delegation they also match
+ * `effective.sub`, the supervisor's PPLE ID sub.
+ *
+ * A null or empty Effective sub matches nothing: a supervisor without a
+ * Zitadel id does not pass a level that names them. A session that is not
+ * delegated matches the Actor only, even if `effective.sub` says someone else.
+ */
+function subsAdmit(identity: LevelIdentity, subs: readonly string[]): boolean {
+  if (typeof identity.actor.sub === "string" && identity.actor.sub !== "" && subs.includes(identity.actor.sub)) {
+    return true;
+  }
+  if (identity.effective.isDelegated !== true) return false;
+  const supervisor = identity.effective.sub;
+  if (typeof supervisor !== "string" || supervisor === "") return false;
+  return subs.includes(supervisor);
+}
+
+function subsMatch(
+  identity: LevelIdentity,
+  subs: unknown,
+  sweptSubs: readonly string[] | undefined,
+): boolean {
+  const list = subs === "swept" ? sweptSubs : subs;
+  if (!Array.isArray(list)) return false;
+  const names = list.filter((item): item is string => typeof item === "string");
+  return subsAdmit(identity, names);
+}
+
+function rolesMatch(identity: LevelIdentity, roles: unknown): boolean {
+  if (!Array.isArray(roles)) return false;
+  const viewer = viewerRoles(identity);
+  return roles.some((role) => typeof role === "string" && viewer.has(role));
+}
+
+export function passesLevel(
+  identity: LevelIdentity | null,
+  level: AccessLevel,
+  options?: PassesLevelOptions,
+): boolean {
+  if (level === "public") return true;
+  if (identity === null || identity === undefined) return false;
+  if (level === "member") return passesMember(identity);
+  if (level === "internal") return passesInternal(identity);
+  if (typeof level !== "object") return false;
+  if (rolesMatch(identity, level.roles)) return true;
+  return subsMatch(identity, level.subs, options?.sweptSubs);
+}