@pithy-sh/core 0.13.0 → 0.15.0

package/src/processing/activity.ts

@@ -0,0 +1,289 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { ConsentPurposeId } from "../consent/purpose";
+import { fromZodError, ValidationError } from "../error/pithyError";
+import { PrivacyClassName } from "../privacy/classes";
+import { type BasisSource, LegalBasis } from "./vocabulary";
+
+/**
+ * Processing activities: what a Worker does with personal data, why, and on what legal basis — the declarations the
+ * GDPR Article 30 record is derived from.
+ *
+ * ## Declared where the processing is
+ *
+ * A capability states the activities it performs, under its own `name` (`auth.account`), the rule consent purposes,
+ * tables and error codes follow. The adopter adds their own in the `processing` block of a Worker's
+ * `pithy.config.ts`, and may replace a capability's legal basis there.
+ *
+ * ## A missing basis is a gap, never a guess
+ *
+ * `legalBasis` is optional. An activity without one is reported as a gap in the record, and nothing fills it in.
+ */
+
+/** An activity id: `<domain>.<name>`, lowercase, the domain being the declaring capability's name. */
+export const ProcessingActivityId = z
+  .string()
+  .regex(
+    /^[a-z][a-z0-9-]*\.[a-z][a-z0-9_.-]*$/,
+    "A processing activity id is `<domain>.<name>`: lowercase, the domain being the declaring capability's name.",
+  )
+  .max(128)
+  .describe(
+    "A processing activity id, `<domain>.<name>` — `auth.account`. The domain is the declaring capability's name, or the adopter's own domain for an activity declared in `pithy.config.ts`.",
+  );
+export type ProcessingActivityId = z.infer<typeof ProcessingActivityId>;
+
+/** Someone outside the Worker's own code who receives personal data for an activity. */
+export const ProcessingRecipient = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .max(120)
+      .describe("Who receives it, as an auditor would name them — `Stripe`, `Cloudflare Email Service`."),
+    receives: z
+      .string()
+      .min(1)
+      .max(500)
+      .describe("What they receive, in one sentence — `The buyer's email address and what they bought.`"),
+    classes: z
+      .array(PrivacyClassName)
+      .default([])
+      .describe("The data classes in what they receive — `pii`, `phi`, or an adopter's own."),
+  })
+  .describe("One recipient of personal data: who it is, what it receives, and the classes in it.");
+export type ProcessingRecipient = z.output<typeof ProcessingRecipient>;
+export type ProcessingRecipientInput = z.input<typeof ProcessingRecipient>;
+
+/** A consent purpose belongs with a consent basis and nowhere else. */
+function consentPurposeNeedsConsent(
+  value: { legalBasis?: LegalBasis | undefined; consentPurpose?: string | undefined },
+  ctx: z.RefinementCtx,
+): void {
+  if (value.consentPurpose !== undefined && value.legalBasis !== "consent") {
+    ctx.addIssue({
+      code: "custom",
+      path: ["consentPurpose"],
+      message:
+        "`consentPurpose` names the purpose a `consent` basis rests on. Set `legalBasis` to `consent`, or drop it.",
+    });
+  }
+}
+
+/** One processing activity, as a capability or the adopter declares it. */
+export const ProcessingActivity = z
+  .object({
+    id: ProcessingActivityId,
+    purpose: z
+      .string()
+      .min(1)
+      .max(500)
+      .describe(
+        "Why the data is processed, in one sentence an auditor reads — `Keep an account and sign its holder in.`",
+      ),
+    classes: z
+      .array(PrivacyClassName)
+      .default([])
+      .describe(
+        "The data classes the activity uses — `pii`, `phi`, or an adopter's own. Cross-checked against the classes the Worker's schemas store.",
+      ),
+    legalBasis: LegalBasis.optional().describe(
+      "The lawful basis it rests on. Absent is reported as a gap in the processing record, never filled in.",
+    ),
+    consentPurpose: ConsentPurposeId.optional().describe(
+      "For a `consent` basis, the consent purpose the activity rests on — `email.marketing`. The record cites its grant counts.",
+    ),
+    recipients: z
+      .array(ProcessingRecipient)
+      .default([])
+      .describe(
+        "Who receives the data beyond Cloudflare, which the record always lists — a payment rail, a mail provider. Built from the resolved config, so a rail that is off is not named.",
+      ),
+  })
+  .superRefine(consentPurposeNeedsConsent)
+  .describe("One processing activity: its purpose, the data classes it uses, its legal basis and its recipients.");
+export type ProcessingActivity = z.output<typeof ProcessingActivity>;
+export type ProcessingActivityInput = z.input<typeof ProcessingActivity>;
+
+/** The adopter's replacement for a capability's legal basis. */
+export const ProcessingOverride = z
+  .object({
+    legalBasis: LegalBasis.describe("The basis that replaces the capability's own."),
+    consentPurpose: ConsentPurposeId.optional().describe(
+      "For a `consent` basis, the consent purpose it rests on. Left out, a capability's own purpose is kept.",
+    ),
+  })
+  .strict()
+  .superRefine(consentPurposeNeedsConsent)
+  .describe("A legal basis the adopter states for a capability's activity, replacing the one it declares.");
+export type ProcessingOverride = z.infer<typeof ProcessingOverride>;
+
+/** The `processing` block, as a Worker's `pithy.config.ts` writes it. */
+export const ProcessingPolicy = z
+  .object({
+    activities: z
+      .array(ProcessingActivity)
+      .optional()
+      .describe(
+        "Your own processing activities, beside the ones composed capabilities declare. Each under your own domain.",
+      ),
+    overrides: z
+      .record(ProcessingActivityId, ProcessingOverride)
+      .optional()
+      .describe(
+        'A legal basis per capability activity, replacing the one it declares: `{ "auth.account": { legalBasis: "legitimate-interests" } }`.',
+      ),
+  })
+  .strict()
+  .describe("What this Worker does with personal data beyond what its capabilities declare, and the bases you state.");
+export type ProcessingPolicy = z.output<typeof ProcessingPolicy>;
+export type ProcessingPolicyInput = z.input<typeof ProcessingPolicy>;
+
+/** The domain half of an activity id: `auth` for `auth.account`. */
+export function activityDomain(id: string): string {
+  const dot = id.indexOf(".");
+  return dot === -1 ? id : id.slice(0, dot);
+}
+
+/**
+ * Parse one declarer's activities and refuse what the record could not attribute: an invalid activity, one under a
+ * domain that is not the declarer's, or two with one id. `domain` is the declaring capability's name, or `null` for
+ * the adopter's own, which may use any domain but a reserved one.
+ */
+export function parseProcessingActivities(
+  declarer: string,
+  activities: readonly ProcessingActivityInput[],
+  domain: string | null,
+  reserved: ReadonlySet<string> = new Set(),
+): ProcessingActivity[] {
+  const seen = new Set<string>();
+  return activities.map((input) => {
+    const parsed = ProcessingActivity.safeParse(input);
+    if (!parsed.success) {
+      throw new ValidationError({
+        message: `${declarer} declares a processing activity that is not valid: ${parsed.error.issues[0]?.message ?? "invalid"}.`,
+        action:
+          "Give it an id of the form `<domain>.<name>` and a purpose; name a consent purpose only under a consent basis.",
+      });
+    }
+    const activity = parsed.data;
+    const own = activityDomain(activity.id);
+    if (domain !== null && own !== domain) {
+      throw new ValidationError({
+        message: `The ${declarer} capability declares the processing activity "${activity.id}" outside its own domain.`,
+        action: `Name it under ${domain}. — a capability declares activities only under its own name.`,
+      });
+    }
+    if (domain === null && reserved.has(own)) {
+      throw new ValidationError({
+        message: `The processing activity "${activity.id}" is under ${own}., which a composed capability owns.`,
+        action: "Name your own activities under your own domain, such as your app's name.",
+      });
+    }
+    if (seen.has(activity.id)) {
+      throw new ValidationError({
+        message: `${declarer} declares the processing activity "${activity.id}" twice.`,
+        action: "Declare each activity once.",
+      });
+    }
+    seen.add(activity.id);
+    return activity;
+  });
+}
+
+/** Parse a `processing` block, or refuse it naming what is wrong. `undefined` is the empty policy. */
+export function parseProcessingPolicy(input: unknown): ProcessingPolicy {
+  if (input === undefined) return {};
+  const parsed = ProcessingPolicy.safeParse(input);
+  if (!parsed.success) {
+    throw fromZodError(parsed.error, {
+      message: "The processing block in pithy.config.ts does not parse.",
+      action: "Fix the field named, then deploy again.",
+    });
+  }
+  return parsed.data;
+}
+
+/** One activity as it takes effect: who declared it, its basis after any override, and where that came from. */
+export interface ResolvedActivity {
+  readonly id: string;
+  readonly purpose: string;
+  readonly classes: readonly string[];
+  readonly legalBasis: LegalBasis | null;
+  readonly basisSource: BasisSource | null;
+  readonly consentPurpose: string | null;
+  readonly recipients: readonly ProcessingRecipient[];
+  /** The capability that declared it, or `config` for the adopter's own. */
+  readonly declaredBy: string;
+}
+
+/** What resolving reads off a composed capability. */
+interface ActivityDeclarer {
+  readonly name: string;
+  readonly processing?: readonly ProcessingActivity[];
+}
+
+/** One declared activity, before any override. */
+function resolved(activity: ProcessingActivity, declaredBy: string, source: BasisSource): ResolvedActivity {
+  return {
+    id: activity.id,
+    purpose: activity.purpose,
+    classes: [...activity.classes],
+    legalBasis: activity.legalBasis ?? null,
+    basisSource: activity.legalBasis === undefined ? null : source,
+    consentPurpose: activity.consentPurpose ?? null,
+    recipients: activity.recipients.map((recipient) => ({ ...recipient, classes: [...recipient.classes] })),
+    declaredBy,
+  };
+}
+
+/**
+ * Every activity as it takes effect over a composition: each capability's, in composition order, then the adopter's,
+ * with the block's overrides applied. Refuses an adopter activity under a composed capability's domain, an id declared
+ * twice, and an override naming an activity no composed capability declares. Called when a Worker assembles.
+ */
+export function resolveProcessing(
+  policy: ProcessingPolicy,
+  capabilities: readonly ActivityDeclarer[],
+): ResolvedActivity[] {
+  const reserved = new Set(capabilities.map((capability) => capability.name));
+  const own = parseProcessingActivities("pithy.config.ts", policy.activities ?? [], null, reserved);
+  const declared = capabilities.flatMap((capability) =>
+    (capability.processing ?? []).map((activity) => resolved(activity, capability.name, "capability")),
+  );
+  const ids = new Set<string>();
+  for (const activity of declared) {
+    if (ids.has(activity.id)) {
+      throw new ValidationError({
+        message: `The processing activity "${activity.id}" is declared twice.`,
+        action: "Declare each activity once.",
+      });
+    }
+    ids.add(activity.id);
+  }
+  const overrides = policy.overrides ?? {};
+  for (const id of Object.keys(overrides)) {
+    if (own.some((activity) => activity.id === id)) {
+      throw new ValidationError({
+        message: `The processing block overrides "${id}", which is declared in the same block.`,
+        action: `State its legal basis on the activity itself.`,
+      });
+    }
+    if (!ids.has(id)) {
+      throw new ValidationError({
+        message: `The processing block overrides "${id}", which no composed capability declares.`,
+        action: "Name an activity a composed capability declares. `GET /control-plane/processing` lists them.",
+      });
+    }
+  }
+  const overridden = declared.map((activity): ResolvedActivity => {
+    const override = overrides[activity.id];
+    if (override === undefined) return activity;
+    const consentPurpose =
+      override.legalBasis === "consent" ? (override.consentPurpose ?? activity.consentPurpose) : null;
+    return { ...activity, legalBasis: override.legalBasis, basisSource: "config", consentPurpose };
+  });
+  return [...overridden, ...own.map((activity) => resolved(activity, "config", "config"))];
+}

package/src/processing/composed.ts

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "../capability/capability";
+import { parseProcessingPolicy, type ResolvedActivity, resolveProcessing } from "./activity";
+
+/**
+ * The processing activities as this Worker resolved them at assembly, reachable from module scope, so the control
+ * plane reads the same record `createBackend` refused or accepted. One Worker assembles one backend; a second assembly
+ * in one isolate replaces the first wholesale, as `../retention/composed.ts` does for the retention policy.
+ */
+
+/** Parse and resolve a Worker's `processing` block over what it composes, or refuse it. */
+export function effectiveProcessing(block: unknown, capabilities: readonly Capability[]): ResolvedActivity[] {
+  return resolveProcessing(parseProcessingPolicy(block), capabilities);
+}
+
+let recorded: readonly ResolvedActivity[] | null = null;
+
+/** Record the resolved activities. Called once by `createBackend`. */
+export function recordProcessing(activities: readonly ResolvedActivity[]): void {
+  recorded = activities;
+}
+
+/** Forget them. For a test that needs the un-assembled state back. */
+export function forgetProcessing(): void {
+  recorded = null;
+}
+
+/** The resolved activities, or `null` before any backend has been assembled in this isolate. */
+export function composedProcessing(): readonly ResolvedActivity[] | null {
+  return recorded;
+}

package/src/processing/vocabulary.ts

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/** The processing record's closed vocabularies, apart from the walk that fills them, so a browser may import them. */
+
+/** What kind of gap the record names. */
+export const PROCESSING_GAP_KINDS = [
+  "no-legal-basis",
+  "no-consent-purpose",
+  "class-not-stored",
+  "class-unclaimed",
+  "phi-not-covered",
+  "no-standing-grant",
+] as const;
+export type ProcessingGapKindId = (typeof PROCESSING_GAP_KINDS)[number];
+
+/** Where a recipient came from. */
+export const RECIPIENT_SOURCES = ["platform", "binding", "declared"] as const;
+export type RecipientSource = (typeof RECIPIENT_SOURCES)[number];
+
+/** Where a legal basis came from: the declaring capability, or the `processing` block. */
+export const BASIS_SOURCES = ["capability", "config"] as const;
+export type BasisSource = (typeof BASIS_SOURCES)[number];
+
+/** The six lawful bases of GDPR Article 6(1), (a) to (f), in that order. */
+export const LEGAL_BASES = [
+  "consent",
+  "contract",
+  "legal-obligation",
+  "vital-interests",
+  "public-task",
+  "legitimate-interests",
+] as const;
+
+/** One lawful basis for processing. */
+export const LegalBasis = z
+  .enum(LEGAL_BASES)
+  .describe(
+    "The lawful basis of GDPR Article 6(1): `consent` (a), `contract` (b), `legal-obligation` (c), `vital-interests` (d), `public-task` (e) or `legitimate-interests` (f). A `consent` basis names the consent purpose it rests on.",
+  );
+export type LegalBasis = z.infer<typeof LegalBasis>;

package/src/queue/consumer.ts

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { ExecutionContext } from "@cloudflare/workers-types";
+import type { Logger } from "../logger/logger";
+
+/**
+ * **A capability's queue consumer, and how one Worker's `queue` export finds it (#824).**
+ *
+ * A Worker has one `queue` handler for every queue it consumes, the way it has one `email` and one `scheduled`.
+ * Which capability a message belongs to cannot be read off the batch: `batch.queue` is the provisioned name,
+ * `<project>-<env>-<thing>`, which no capability knows at runtime and which a long name truncates. So the message
+ * says it: every body a capability sends carries its own name under {@link QUEUE_CAPABILITY_FIELD}, built with
+ * {@link queueBody}, and the dispatcher hands each capability exactly the messages that name it.
+ *
+ * **A message no composed capability claims is acknowledged and logged**, never retried. Retrying cannot make a
+ * capability appear, so a retry would only walk the message to its dead-letter queue and count it as a delivery
+ * failure it never was.
+ *
+ * **A handler that throws costs its own messages, and nothing else.** Every other capability's messages are still
+ * handed over; the first failure is rethrown after the pass, so the invocation is recorded as failed and the runtime
+ * retries what was neither acknowledged nor retried.
+ */
+
+/**
+ * One delivered message, as much of the runtime's as a consumer touches. Stated here rather than imported, so the
+ * Workers types' `Message` — a word half the kit uses for other things — never becomes a name the kit reaches for.
+ */
+export interface QueueMessage {
+  /** The runtime's id for this delivery. */
+  readonly id: string;
+  /** The body as sent. */
+  readonly body: unknown;
+  /** How many times this message has been delivered, this one included. Starts at 1. */
+  readonly attempts: number;
+  /** Settle it: delivered, never to be seen again. */
+  ack(): void;
+  /** Settle it: deliver it again after the delay, or to the dead-letter queue once retries are spent. */
+  retry(options?: { delaySeconds?: number }): void;
+}
+
+/** One batch the runtime hands a Worker's `queue` export. */
+export interface QueueBatch {
+  /** The provisioned queue's name. */
+  readonly queue: string;
+  /** Its messages. */
+  readonly messages: readonly QueueMessage[];
+}
+
+/** The body field that names the capability a queue message belongs to. */
+export const QUEUE_CAPABILITY_FIELD = "capability";
+
+/** A capability's queue handler: the messages that name it, from one batch. */
+export type CapabilityQueueHandler = (
+  messages: readonly QueueMessage[],
+  env: Record<string, unknown>,
+  ctx: ExecutionContext,
+) => Promise<void>;
+
+/** A message body, stamped with the capability it belongs to so the Worker's one `queue` export can route it. */
+export function queueBody<const Capability extends string, const Body extends Record<string, unknown>>(
+  capability: Capability,
+  body: Body,
+): Body & { capability: Capability } {
+  return { ...body, capability };
+}
+
+/** The capability a message body names, or null when it names none. */
+export function queueMessageCapability(body: unknown): string | null {
+  if (typeof body !== "object" || body === null) return null;
+  const value = (body as Record<string, unknown>)[QUEUE_CAPABILITY_FIELD];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/** Hand each composed capability the messages of one batch that name it. */
+export async function dispatchQueueBatch(
+  batch: QueueBatch,
+  handlers: ReadonlyMap<string, CapabilityQueueHandler>,
+  env: Record<string, unknown>,
+  ctx: ExecutionContext,
+  log?: Pick<Logger, "warn">,
+): Promise<void> {
+  const claimed = new Map<string, QueueMessage[]>();
+  for (const message of batch.messages) {
+    const capability = queueMessageCapability(message.body);
+    if (capability === null || !handlers.has(capability)) {
+      log?.warn("queue message unclaimed", { queue: batch.queue, messageId: message.id, capability });
+      message.ack();
+      continue;
+    }
+    const list = claimed.get(capability) ?? [];
+    list.push(message);
+    claimed.set(capability, list);
+  }
+  const failures: unknown[] = [];
+  for (const [capability, messages] of claimed) {
+    try {
+      await handlers.get(capability)?.(messages, env, ctx);
+    } catch (error) {
+      failures.push(error);
+    }
+  }
+  if (failures[0] !== undefined) throw failures[0];
+}

package/src/retention/composed.ts

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "../capability/capability";
+import type { PurgeSubject } from "../capability/purge";
+import { privacyInventory } from "../privacy/inventory";
+import { type EffectiveRetention, parseRetentionPolicy, type RetentionComposition, resolveRetention } from "./policy";
+
+/**
+ * **The retention policy as this Worker resolved it, reachable from module scope** — so a purge, a prune and
+ * an inactivity pass, each running in a Workflow the runtime constructs with `env` alone, read the same policy the
+ * routes do. The reasoning, and the cost, are `../capability/composition.ts`'s: `createBackend` runs at module load,
+ * one Worker assembles one backend, and a second assembly in one isolate replaces the first wholesale.
+ */
+
+/**
+ * What resolving reads off a composition: each capability's window, and every lifecycle action it audits — the
+ * transitions it declares, then the ones its erasure records.
+ */
+export function retentionComposition(capabilities: readonly Capability[]): RetentionComposition {
+  return {
+    purgeWindows: capabilities.flatMap((capability) => (capability.purgeWindow ? [capability.purgeWindow] : [])),
+    lifecycleActions: capabilities.flatMap((capability) => {
+      const actions = capability.erasureRecords?.auditActions;
+      const erasure = actions ? [...actions.deleted, actions.step, actions.failed, actions.purged] : [];
+      return [...(capability.lifecycleAuditActions ?? []), ...erasure];
+    }),
+  };
+}
+
+/**
+ * Parse and resolve a Worker's `retention` block over what it composes, or refuse it. What `createBackend` calls at
+ * assembly and `pithy doctor` calls on the same config, so both report — or refuse — one policy.
+ */
+export function effectiveRetention(block: unknown, capabilities: readonly Capability[]): EffectiveRetention {
+  return resolveRetention(parseRetentionPolicy(block), retentionComposition(capabilities));
+}
+
+/** The resolved policy, or null before any backend has been assembled in this isolate. */
+let recorded: EffectiveRetention | null = null;
+
+/** Record the resolved policy. Called once by `createBackend`, beside `recordComposition`. */
+export function recordRetention(retention: EffectiveRetention): void {
+  recorded = retention;
+}
+
+/** Forget it. For a test that needs the un-assembled state back. */
+export function forgetRetention(): void {
+  recorded = null;
+}
+
+/**
+ * The resolved policy — or, before any assembly, `null`. A caller with a capability's own default in hand falls back
+ * to it, which is exactly what an empty block means.
+ */
+export function composedRetention(): EffectiveRetention | null {
+  return recorded;
+}
+
+/**
+ * The privacy classes a subject's rows hold: every class marked on a schema of a capability that erases that
+ * subject in its purge — the capabilities that hold rows keyed to the subject. What the class ages are read against:
+ * an account holds `pii` when a capability holding its rows marks a field `pii`.
+ */
+export function subjectClasses(capabilities: readonly Capability[], subject: PurgeSubject): string[] {
+  const holders = new Set(
+    capabilities
+      .filter((capability) => capability.purge?.some((contribution) => contribution.subject === subject))
+      .map((capability) => capability.name),
+  );
+  const classes = privacyInventory(capabilities)
+    .schemas.filter((schema) => holders.has(schema.capability))
+    .flatMap((schema) => schema.fields.map((field) => field.class));
+  return [...new Set(classes)].sort();
+}