@pithy-sh/core 0.13.0 → 0.14.0

package/dist/controlPlane/http/holds.js

@@ -0,0 +1,98 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { countActiveHolds, listHolds, placeHold, releaseHold } from "../../retention/holds.js";
+import { ControlPlaneAuditActions, safeEmit } from "../audit/actions.js";
+import { caller } from "./handlers.js";
+//#region src/controlPlane/http/holds.ts
+/**
+* The legal-hold routes: place, release, list.
+*
+* Placing and releasing are each audited under `controlplane/*`, which the retention floor keeps at least a year,
+* with the subject, the hold and the reason. A hold suspends every purge, prune and inactivity deletion touching its
+* subject; the capabilities that erase read it through `retention/holds.ts`. **Nothing here shortens a retention**:
+* a hold can only preserve, and its release returns the subject to the policy the Worker was deployed with.
+*/
+/** The default page of `GET /control-plane/holds`. */
+const DEFAULT_HOLD_LIMIT = 100;
+/** A hold, as the routes answer it. */
+function holdView(hold) {
+	return {
+		id: hold.id,
+		subjectType: hold.subjectType,
+		subjectId: hold.subjectId,
+		reason: hold.reason,
+		placedBy: hold.placedBy,
+		placedAt: hold.placedAt.toISOString(),
+		state: hold.state,
+		releasedAt: hold.releasedAt?.toISOString() ?? null,
+		releasedBy: hold.releasedBy,
+		releaseReason: hold.releaseReason
+	};
+}
+/** The audit event for a placement or a release: the subject as the resource, the hold and the reason beside it. */
+async function auditHold(c, action, hold, reason) {
+	const context = caller(c);
+	await safeEmit(c.var.emit, {
+		action,
+		outcome: "success",
+		severity: "warning",
+		actorType: "control-plane",
+		actorId: context.subject,
+		resourceType: hold.subjectType === "audit" ? "audit_trail" : hold.subjectType,
+		resourceId: hold.subjectId,
+		requestId: c.req.header("cf-ray"),
+		ip: c.req.header("cf-connecting-ip"),
+		userAgent: c.req.header("user-agent"),
+		metadata: {
+			holdId: hold.id,
+			subjectType: hold.subjectType,
+			reason
+		}
+	}, c.var.log);
+}
+/** `POST /control-plane/holds` — place a hold. */
+function placeHoldHandler(deps) {
+	return async (c, body) => {
+		const context = caller(c);
+		const hold = await placeHold(deps.database(c), {
+			subjectType: body.subjectType,
+			subjectId: body.subjectId,
+			reason: body.reason,
+			actor: { subject: context.subject },
+			at: deps.now()
+		});
+		await auditHold(c, ControlPlaneAuditActions.holdPlaced, hold, body.reason);
+		return c.json({ hold: holdView(hold) }, 201);
+	};
+}
+/** `POST /control-plane/holds/:holdId/release` — release a hold, with a reason. */
+function releaseHoldHandler(deps) {
+	return async (c, params, body) => {
+		const context = caller(c);
+		const hold = await releaseHold(deps.database(c), {
+			id: params.holdId,
+			reason: body.reason,
+			actor: { subject: context.subject },
+			at: deps.now()
+		});
+		await auditHold(c, ControlPlaneAuditActions.holdReleased, hold, body.reason);
+		return c.json({ hold: holdView(hold) });
+	};
+}
+/** `GET /control-plane/holds` — every hold, standing first. Read-only. */
+function listHoldsHandler(deps) {
+	return async (c, query) => {
+		caller(c);
+		const db = deps.database(c);
+		const holds = await listHolds(db, {
+			...query.state ? { state: query.state } : {},
+			limit: query.limit ?? DEFAULT_HOLD_LIMIT
+		});
+		return c.json({
+			active: await countActiveHolds(db),
+			holds: holds.map(holdView)
+		});
+	};
+}
+//#endregion
+export { holdView, listHoldsHandler, placeHoldHandler, releaseHoldHandler };

package/dist/controlPlane/http/presence.d.ts

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Context, MiddlewareHandler } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import type { ControlPlanePresenceTicketRequest } from "../../presence/http/schemas";
+import { type ControlPlaneRequirementResolver } from "./guard";
+import type { ControlPlaneHandlerDeps } from "./handlers";
+/**
+ * `POST /control-plane/presence/tickets` — a ticket into any room this Worker composes, for a management
+ * client.
+ *
+ * **The scope is the room kind's, and the gate checks it.** Which scope a call needs is named in its body, so
+ * {@link presenceTicketRequirement} reads the kind from a copy of the body before the gate verifies, and the
+ * gate then verifies against that kind's scope exactly as it would against a route's own: one allowed row
+ * when it covers, one denial row naming the kind's scope when it does not, never both. Presence adds no scope
+ * of its own: a connection that may read a record may see who else has it open.
+ *
+ * A body that names no declared kind needs only a verified caller, so an unverified one is refused before any
+ * kind is looked at, and a verified one then gets the handler's 404 — the manifest lists every kind, so its
+ * existence is no secret.
+ */
+export declare function presenceTicketRequirement(deps: ControlPlaneHandlerDeps): ControlPlaneRequirementResolver;
+/** The gate the route wears: {@link requireControlPlaneFor} over the room kind's scope. */
+export declare function presenceTicketGate(deps: ControlPlaneHandlerDeps): MiddlewareHandler<PithyHonoEnv>;
+/** The handler, behind {@link presenceTicketGate}: the kind's scope is already verified, so it mints. */
+export declare function presenceTicketHandler(deps: ControlPlaneHandlerDeps): (c: Context<PithyHonoEnv>, body: ControlPlanePresenceTicketRequest) => Promise<Response>;
+//# sourceMappingURL=presence.d.ts.map

package/dist/controlPlane/http/presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/presence.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAIhE,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,6BAA6B,CAAC;AAErF,OAAO,EAAE,KAAK,+BAA+B,EAA0B,MAAM,SAAS,CAAC;AACvF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,+BAA+B,CAOxG;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,uBAAuB,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAEjG;AAgBD,yGAAyG;AACzG,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,uBAAuB,OAChD,OAAO,CAAC,YAAY,CAAC,QAAQ,iCAAiC,KAAG,OAAO,CAAC,QAAQ,CAAC,CAapG"}

package/dist/controlPlane/http/presence.js

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { NotFoundError } from "../../error/pithyError.js";
+import { ANY_VERIFIED_CALLER } from "../scope/scope.js";
+import { issuePresenceTicket, roomKind } from "../../presence/http/routes.js";
+import { requireControlPlaneFor } from "./guard.js";
+//#region src/controlPlane/http/presence.ts
+/**
+* `POST /control-plane/presence/tickets` — a ticket into any room this Worker composes, for a management
+* client.
+*
+* **The scope is the room kind's, and the gate checks it.** Which scope a call needs is named in its body, so
+* {@link presenceTicketRequirement} reads the kind from a copy of the body before the gate verifies, and the
+* gate then verifies against that kind's scope exactly as it would against a route's own: one allowed row
+* when it covers, one denial row naming the kind's scope when it does not, never both. Presence adds no scope
+* of its own: a connection that may read a record may see who else has it open.
+*
+* A body that names no declared kind needs only a verified caller, so an unverified one is refused before any
+* kind is looked at, and a verified one then gets the handler's 404 — the manifest lists every kind, so its
+* existence is no secret.
+*/
+function presenceTicketRequirement(deps) {
+	return async (c) => {
+		const kind = await bodyKind(c.req.raw);
+		const presence = kind === void 0 ? void 0 : deps.composedPresence().get(kind);
+		if (kind === void 0 || !presence) return ANY_VERIFIED_CALLER;
+		return roomKind(presence, kind).scope;
+	};
+}
+/** The gate the route wears: {@link requireControlPlaneFor} over the room kind's scope. */
+function presenceTicketGate(deps) {
+	return requireControlPlaneFor(presenceTicketRequirement(deps));
+}
+/**
+* The body's `kind`, read from a copy so the route's validator still reads the original. Only to choose a
+* scope: the validator is what parses the body, and anything unreadable here is simply no kind.
+*/
+async function bodyKind(request) {
+	try {
+		const body = await request.clone().json();
+		const kind = typeof body === "object" && body !== null ? body.kind : void 0;
+		return typeof kind === "string" ? kind : void 0;
+	} catch {
+		return;
+	}
+}
+/** The handler, behind {@link presenceTicketGate}: the kind's scope is already verified, so it mints. */
+function presenceTicketHandler(deps) {
+	return async (c, body) => {
+		const presence = deps.composedPresence().get(body.kind);
+		if (!presence) throw new NotFoundError({
+			message: "That room kind does not exist.",
+			params: { kind: body.kind }
+		});
+		const room = roomKind(presence, body.kind);
+		const ticket = await issuePresenceTicket(c, presence, {
+			kind: room.kind,
+			recordId: body.recordId,
+			ref: body.participant.ref,
+			name: body.participant.name,
+			origin: "control-plane"
+		});
+		return c.json(ticket, 201);
+	};
+}
+//#endregion
+export { presenceTicketGate, presenceTicketHandler, presenceTicketRequirement };

package/dist/controlPlane/http/processing.d.ts

@@ -0,0 +1,73 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Context } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import { type ControlPlaneHandlerDeps } from "./handlers";
+/**
+ * `GET /control-plane/processing` — the record of processing activities, GDPR Article 30. Each activity's purpose,
+ * classes, legal basis, recipients, retention and measures, and every gap named. Read-only.
+ */
+export declare function processingHandler(deps: ControlPlaneHandlerDeps): (c: Context<PithyHonoEnv>) => Promise<Response & import("hono").TypedResponse<{
+    environment: string;
+    generatedAt: string;
+    version: string | null;
+    activities: {
+        id: string;
+        purpose: string;
+        declaredBy: string;
+        classes: string[];
+        legalBasis: "consent" | "contract" | "legal-obligation" | "legitimate-interests" | "public-task" | "vital-interests" | null;
+        basisSource: "capability" | "config" | null;
+        consent: {
+            purpose: string;
+            noticeVersion: number | null;
+            explicit: boolean | null;
+            grants: number | null;
+            withdrawals: number | null;
+            standing: number | null;
+        } | null;
+        recipients: {
+            name: string;
+            receives: string;
+            classes: string[];
+            source: "binding" | "declared" | "platform";
+        }[];
+        retention: {
+            classAges: {
+                class: string;
+                days: number;
+            }[];
+            purgeWindows: {
+                subject: "organization" | "user";
+                days: number;
+                source: "capability" | "floor" | "policy";
+            }[];
+        } | null;
+        measures: ("audit-logging" | "change-history" | "csrf" | "data-protection" | "key-rotation" | "management-access" | "route-verification")[];
+        gaps: {
+            kind: "class-not-stored" | "class-unclaimed" | "no-consent-purpose" | "no-legal-basis" | "no-standing-grant" | "phi-not-covered";
+            subject: string;
+            detail: string;
+        }[];
+    }[];
+    recipients: {
+        name: string;
+        receives: string;
+        classes: string[];
+        source: "binding" | "declared" | "platform";
+    }[];
+    measures: {
+        control: "audit-logging" | "change-history" | "csrf" | "data-protection" | "key-rotation" | "management-access" | "route-verification";
+        title: string;
+        soc2: string[];
+        iso27001: string[];
+        state: "evidenced" | "gap" | "not-derivable" | null;
+    }[];
+    gaps: {
+        kind: "class-not-stored" | "class-unclaimed" | "no-consent-purpose" | "no-legal-basis" | "no-standing-grant" | "phi-not-covered";
+        subject: string;
+        detail: string;
+    }[];
+    notDerivable: string[];
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">>;
+//# sourceMappingURL=processing.d.ts.map

package/dist/controlPlane/http/processing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processing.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/processing.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE,OAAO,EAAE,KAAK,uBAAuB,EAAU,MAAM,YAAY,CAAC;AAGlE;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,uBAAuB,OAC5C,OAAO,CAAC,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mEAIvC"}

package/dist/controlPlane/http/processing.js

@@ -0,0 +1,17 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { caller } from "./handlers.js";
+import { readProcessingRecord } from "../processing/read.js";
+//#region src/controlPlane/http/processing.ts
+/**
+* `GET /control-plane/processing` — the record of processing activities, GDPR Article 30. Each activity's purpose,
+* classes, legal basis, recipients, retention and measures, and every gap named. Read-only.
+*/
+function processingHandler(deps) {
+	return async (c) => {
+		const context = caller(c);
+		return c.json(await readProcessingRecord(c, deps, context));
+	};
+}
+//#endregion
+export { processingHandler };