@pithy-sh/core 0.11.0 → 0.13.0

package/dist/logger/record.d.ts

@@ -107,6 +107,20 @@ export declare const LogRecord: z.ZodObject<{
         detail: z.ZodOptional<z.ZodString>;
         code: z.ZodLiteral<"auth/session_not_fresh">;
         status: z.ZodLiteral<403>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"auth/account_suspended">;
+        status: z.ZodLiteral<403>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"auth/account_deleted">;
+        status: z.ZodLiteral<403>;
     }, z.core.$strip>, z.ZodObject<{
         message: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
@@ -919,6 +933,34 @@ export declare const LogRecord: z.ZodObject<{
         detail: z.ZodOptional<z.ZodString>;
         code: z.ZodLiteral<"organization/nomination_invalid">;
         status: z.ZodLiteral<400>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"organization/last_owner">;
+        status: z.ZodLiteral<409>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"organization/already_member">;
+        status: z.ZodLiteral<409>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"organization/seat_limit_reached">;
+        status: z.ZodLiteral<409>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"organization/organization_suspended">;
+        status: z.ZodLiteral<403>;
     }, z.core.$strip>, z.ZodObject<{
         message: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;

package/dist/logger/record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/logger/record.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,QAAQ;;;;;EAE4F,CAAC;AAClH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAgD,CAAC;AAEtG;;;;GAIG;AACH,eAAO,MAAM,SAAS,wCAEsF,CAAC;AAC7G,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW+E,CAAC;AACtG,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAmBnD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAMzD"}
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/logger/record.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,QAAQ;;;;;EAE4F,CAAC;AAClH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAgD,CAAC;AAEtG;;;;GAIG;AACH,eAAO,MAAM,SAAS,wCAEsF,CAAC;AAC7G,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW+E,CAAC;AACtG,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAmBnD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAMzD"}

package/dist/privacy/blindIndex.d.ts

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { type EncryptionConfig } from "../crypto/envelope";
+import { type BlindIndexNormalizer } from "./encrypted";
+/**
+ * **A blind index: a keyed hash an encrypted column can be found by** (#390).
+ *
+ * An encrypted column cannot answer `WHERE email = ?`. A sibling column holding `HMAC(key, normalize(value))` can,
+ * for equality and nothing else. One rule here is shared by the app Worker that seals, `sealed().match` that looks
+ * up, and the rotator that re-indexes inside the manager, so the three cannot hash one value two ways.
+ *
+ * - **The key is derived, on the field key's own version axis.** Each version's index key is HKDF-SHA256 over that
+ *   version's field key, with the label `pithy/blind-index/<normalizer>`. One secret, one rotation.
+ * - **The value carries its version**: `<version>:<hmac>`, so the stale count reaches an index exactly as it reaches
+ *   an envelope, by reading the prefix.
+ * - **The normalizer is in the label**, so changing a field's normalizer cannot silently miss against old hashes: they
+ *   are hashes under a different key, and the change reads as a re-index.
+ */
+/** The HKDF label one normalizer's index keys are derived under. */
+export declare function blindIndexLabel(normalizer: BlindIndexNormalizer): string;
+/** The HMAC key for one version and normalizer: HKDF-SHA256 over that version's field key. */
+export declare function blindIndexKey(config: EncryptionConfig, version: number, normalizer: BlindIndexNormalizer): Promise<CryptoKey>;
+/** The blind index of `value` under `version`: `<version>:<hmac>`. The value is normalized first. */
+export declare function blindIndexValue(config: EncryptionConfig, version: number, normalizer: BlindIndexNormalizer, value: string): Promise<string>;
+/** The version a blind-index value was written under, or `null` for a value that is not one. */
+export declare function blindIndexVersion(value: string): number | null;
+//# sourceMappingURL=blindIndex.d.ts.map

package/dist/privacy/blindIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blindIndex.d.ts","sourceRoot":"","sources":["../../src/privacy/blindIndex.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,gBAAgB,EAAY,MAAM,oBAAoB,CAAC;AAErE,OAAO,EAAE,KAAK,oBAAoB,EAAqB,MAAM,aAAa,CAAC;AAE3E;;;;;;;;;;;;;GAaG;AAEH,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,UAAU,EAAE,oBAAoB,GAAG,MAAM,CAExE;AASD,8FAA8F;AAC9F,wBAAsB,aAAa,CACjC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,oBAAoB,GAC/B,OAAO,CAAC,SAAS,CAAC,CAmBpB;AAED,qGAAqG;AACrG,wBAAsB,eAAe,CACnC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,oBAAoB,EAChC,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG9D"}

package/dist/privacy/blindIndex.js

@@ -0,0 +1,57 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { keyBytes } from "../crypto/envelope.js";
+import { FIELD_KEYS_BINDING } from "../crypto/fieldKeys.js";
+import { normalizeForIndex } from "./encrypted.js";
+//#region src/privacy/blindIndex.ts
+/**
+* **A blind index: a keyed hash an encrypted column can be found by** (#390).
+*
+* An encrypted column cannot answer `WHERE email = ?`. A sibling column holding `HMAC(key, normalize(value))` can,
+* for equality and nothing else. One rule here is shared by the app Worker that seals, `sealed().match` that looks
+* up, and the rotator that re-indexes inside the manager, so the three cannot hash one value two ways.
+*
+* - **The key is derived, on the field key's own version axis.** Each version's index key is HKDF-SHA256 over that
+*   version's field key, with the label `pithy/blind-index/<normalizer>`. One secret, one rotation.
+* - **The value carries its version**: `<version>:<hmac>`, so the stale count reaches an index exactly as it reaches
+*   an envelope, by reading the prefix.
+* - **The normalizer is in the label**, so changing a field's normalizer cannot silently miss against old hashes: they
+*   are hashes under a different key, and the change reads as a re-index.
+*/
+/** The HKDF label one normalizer's index keys are derived under. */
+function blindIndexLabel(normalizer) {
+	return `pithy/blind-index/${normalizer}`;
+}
+/** Unpadded base64url, the alphabet a blind index is written in. */
+function base64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** The HMAC key for one version and normalizer: HKDF-SHA256 over that version's field key. */
+async function blindIndexKey(config, version, normalizer) {
+	const material = await crypto.subtle.importKey("raw", keyBytes(config, version, { keys: FIELD_KEYS_BINDING }), "HKDF", false, ["deriveBits"]);
+	const bits = await crypto.subtle.deriveBits({
+		name: "HKDF",
+		hash: "SHA-256",
+		salt: /* @__PURE__ */ new Uint8Array(0),
+		info: Uint8Array.from(new TextEncoder().encode(blindIndexLabel(normalizer)))
+	}, material, 256);
+	return crypto.subtle.importKey("raw", bits, {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+}
+/** The blind index of `value` under `version`: `<version>:<hmac>`. The value is normalized first. */
+async function blindIndexValue(config, version, normalizer, value) {
+	const key = await blindIndexKey(config, version, normalizer);
+	const mac = await crypto.subtle.sign("HMAC", key, Uint8Array.from(new TextEncoder().encode(normalizeForIndex(normalizer, value))));
+	return `${version}:${base64Url(new Uint8Array(mac))}`;
+}
+/** The version a blind-index value was written under, or `null` for a value that is not one. */
+function blindIndexVersion(value) {
+	const match = /^(\d+):/.exec(value);
+	return match ? Number(match[1]) : null;
+}
+//#endregion
+export { blindIndexKey, blindIndexLabel, blindIndexValue, blindIndexVersion };

package/dist/privacy/classes.d.ts

@@ -0,0 +1,142 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * **A field declares its own privacy class, and the declaration drives everything downstream** (#132).
+ *
+ * One marker, several consumers — the shape `@pithy-sh/vector` already uses, where `.meta({ filterable: true
+ * })` drives provisioning, the filter type, the drift check and the boot check. Here the marker drives the
+ * type gate on the three internal surfaces (the logger, `AuditEvent.metadata`, `PithyError.detail`), the
+ * masked view `redact` returns, the classification `classifyPrivacy` derives, and the inventory the control
+ * plane reports.
+ *
+ * ## What a marker does, in one call
+ *
+ * `pii(schema)` does two things. It attaches `.meta({ privacy: "pii" })`, which is **introspectable** — that is
+ * what `redact`, `classifyPrivacy` and the inventory read. And it applies Zod's `.brand()`, which changes the
+ * **inferred type** — that is what makes a log call carrying the value fail to compile. The brand lands on the
+ * field, not on the object, so extracting the field does not launder it: `user.email` is as branded as `user`.
+ *
+ * **A marker over another marker adds its class.** `pii(secret(x))` and `secret(pii(x))` are the same field: it
+ * carries both classes, in its `meta` (as a list, strongest first) and in its type (both brands). It is masked with the
+ * strongest one's placeholder and listed once per class. The same marker twice is one class.
+ *
+ * **The brand key is `privacy:<class>`, not the bare class name.** An adopter's own `.brand<"pii">()` for some
+ * unrelated purpose must not trip a gate it never opted into, and an adopter's `UserId` brand must not either:
+ * the gate reads a brand under the `privacy:` namespace and nothing else, which is the federated-key rule
+ * (`auth/invalid_token`, `pithy_auth_users`) applied one more time.
+ *
+ * **Nothing at runtime changes.** Zod's `.brand()` returns the same schema object — the brand exists only in
+ * the type — and `.meta()` returns a clone that parses exactly as its source. `Schema.parse(row)` returns the
+ * same data it did before the marker, and no column is added anywhere.
+ *
+ * ## The set is open
+ *
+ * Four classes ship named — `secret`, `pii`, `phi`, `pci` — and {@link definePrivacyClass} registers more
+ * (`genetic`, `biometric`, whatever a regulator names) without a change to core. A closed union is what #117
+ * records the cost of, and a healthcare adopter should not have to wait on us.
+ *
+ * ## Where `secret` stops and `@pithy-sh/secrets` starts
+ *
+ * Two different facts, kept apart on purpose. `@pithy-sh/secrets` decides **where a credential the Worker reads
+ * is stored** — its registry names a backend, and its reader redacts the value it hands back. `secret()` says
+ * **what a field in a data shape is** — a receipt, a magic-link token, a session id, a key hash — values that
+ * live in rows and payloads and that no secrets registry ever holds. Merging them would make core depend on a
+ * capability (principle 4) and would make a storage decision answer a classification question.
+ */
+/** The `meta` key a marker writes and every reader reads. */
+export declare const PRIVACY_META_KEY = "privacy";
+/** The prefix of every privacy brand, so the gate never reads a brand that means something else. */
+export declare const PRIVACY_BRAND_PREFIX = "privacy:";
+/** A class name: a lowercase identifier. It becomes a brand key, a config value and a report column. */
+export declare const PrivacyClassName: z.ZodString;
+export type PrivacyClassName = z.output<typeof PrivacyClassName>;
+/** The four classes the kit names, in the order every report lists them. */
+export declare const BUILT_IN_PRIVACY_CLASSES: readonly ["secret", "pii", "phi", "pci"];
+/** One of the four built-in class names. */
+export type BuiltInPrivacyClass = (typeof BUILT_IN_PRIVACY_CLASSES)[number];
+/** How a class masks a value: the string that stands in its place on every internal surface. */
+export type PrivacyMask = (value: unknown) => string;
+/** One registered class: its name, what it means, and how it masks. */
+export interface PrivacyClass {
+    /** The class name — the `meta` value and the brand's suffix. */
+    readonly name: string;
+    /** What the class means, in one sentence an auditor reads. */
+    readonly description: string;
+    /** The masked form of a value of this class. */
+    readonly mask: PrivacyMask;
+}
+/**
+ * The brand a marker puts on a schema's output type. Zod's own brand machinery, under the `privacy:` key.
+ *
+ * `"out"` on purpose: the **input** side stays unbranded, so `z.input` — the SQLite row shape, the Kysely
+ * table type, a KV write's pre-parse value — is exactly what it was. A row read from D1 parses into the
+ * branded app shape, and `Schema.encode()` hands Kysely the plain row back.
+ */
+export type Marked<S extends z.ZodType, C extends string> = z.core.$ZodBranded<S, `${typeof PRIVACY_BRAND_PREFIX}${C}`, "out">;
+/** A marker for one class: wraps a schema and returns it marked. Carries its class name for a reader. */
+export interface PrivacyMarker<C extends string> {
+    <S extends z.ZodType>(schema: S): Marked<S, C>;
+    /** The class this marker applies. */
+    readonly className: C;
+}
+/**
+ * Mask a primary account number to its first six and last four digits — `424242******4242`.
+ *
+ * **The one class whose mask is not a placeholder, because the masked form is the useful one.** First-six and
+ * last-four is the display PCI-DSS permits, and it is what an operator reading a log needs to match a
+ * complaint to a card without holding the card. Spaces and dashes are separators and are dropped; anything
+ * that is not 13 to 19 digits once they are is not a card number, and masks to `[pci]` rather than to a
+ * partial reveal of something else.
+ *
+ * Every payment rail Pithy ships is hosted, so no PAN ever reaches an adopter's Worker through the kit. The
+ * class is here for the adopter's own schemas.
+ */
+export declare function maskPan(value: unknown): string;
+/** The class a name refers to, or `undefined` for a name nothing registered. */
+export declare function privacyClass(name: string): PrivacyClass | undefined;
+/** Every registered class, built-ins first in their fixed order, then each adopter class in registration order. */
+export declare function privacyClasses(): PrivacyClass[];
+/**
+ * `names` from the strongest to the weakest, each once: `secret`, then `phi`, then `pci`, then each adopter class, then
+ * `pii`. An adopter registers a class because its data is more specific than `pii`, so it ranks above it; adopter
+ * classes rank among themselves by name. The order a marker records several classes in, whatever order they came.
+ */
+export declare function rankPrivacyClasses(names: Iterable<string>): string[];
+/**
+ * The strongest of `names`, the class a value is masked with when it carries several and is masked whole. See
+ * {@link rankPrivacyClasses}. `undefined` for none.
+ */
+export declare function strongestPrivacyClass(names: Iterable<string>): string | undefined;
+/**
+ * The classes a schema's own `privacy` meta records: one class as its name, several as a list, strongest first. Read
+ * from this exact schema, never through a wrapper. Empty where it records none.
+ */
+export declare function ownPrivacyClasses(schema: z.ZodType): string[];
+/** What {@link definePrivacyClass} takes. */
+export interface PrivacyClassSpec<C extends string> {
+    /** The class name: a lowercase identifier, unique across the isolate. */
+    name: C;
+    /** What the class means. Defaults to a sentence naming it as adopter-registered. */
+    description?: string;
+    /** How a value masks. Defaults to the `[name]` placeholder. */
+    mask?: PrivacyMask;
+}
+/**
+ * Register a class of the adopter's own — `genetic`, `biometric`, whatever their regulator names — and get its
+ * marker back. Usable exactly like the built-ins: the same `meta`, the same brand, the same gate, the same
+ * inventory row.
+ *
+ * **A duplicate is refused at registration**, a built-in name included. Two modules each believing they own
+ * `genetic` would disagree about its mask, and the one that loaded second would win silently.
+ */
+export declare function definePrivacyClass<const C extends string>(spec: PrivacyClassSpec<C>): PrivacyMarker<C>;
+/** Mark a field as a credential or bearer artifact. See {@link BUILT_INS}. */
+export declare const secret: PrivacyMarker<"secret">;
+/** Mark a field as personal data under GDPR or CCPA. */
+export declare const pii: PrivacyMarker<"pii">;
+/** Mark a field as Protected Health Information under HIPAA. */
+export declare const phi: PrivacyMarker<"phi">;
+/** Mark a field as cardholder data under PCI-DSS. Masks to first six and last four. */
+export declare const pci: PrivacyMarker<"pci">;
+//# sourceMappingURL=classes.d.ts.map

package/dist/privacy/classes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classes.d.ts","sourceRoot":"","sources":["../../src/privacy/classes.ts"],"names":[],"mappings":"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"}

package/dist/privacy/classes.js

@@ -0,0 +1,209 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ConflictError, ValidationError } from "../error/pithyError.js";
+import { z } from "zod";
+//#region src/privacy/classes.ts
+/**
+* **A field declares its own privacy class, and the declaration drives everything downstream** (#132).
+*
+* One marker, several consumers — the shape `@pithy-sh/vector` already uses, where `.meta({ filterable: true
+* })` drives provisioning, the filter type, the drift check and the boot check. Here the marker drives the
+* type gate on the three internal surfaces (the logger, `AuditEvent.metadata`, `PithyError.detail`), the
+* masked view `redact` returns, the classification `classifyPrivacy` derives, and the inventory the control
+* plane reports.
+*
+* ## What a marker does, in one call
+*
+* `pii(schema)` does two things. It attaches `.meta({ privacy: "pii" })`, which is **introspectable** — that is
+* what `redact`, `classifyPrivacy` and the inventory read. And it applies Zod's `.brand()`, which changes the
+* **inferred type** — that is what makes a log call carrying the value fail to compile. The brand lands on the
+* field, not on the object, so extracting the field does not launder it: `user.email` is as branded as `user`.
+*
+* **A marker over another marker adds its class.** `pii(secret(x))` and `secret(pii(x))` are the same field: it
+* carries both classes, in its `meta` (as a list, strongest first) and in its type (both brands). It is masked with the
+* strongest one's placeholder and listed once per class. The same marker twice is one class.
+*
+* **The brand key is `privacy:<class>`, not the bare class name.** An adopter's own `.brand<"pii">()` for some
+* unrelated purpose must not trip a gate it never opted into, and an adopter's `UserId` brand must not either:
+* the gate reads a brand under the `privacy:` namespace and nothing else, which is the federated-key rule
+* (`auth/invalid_token`, `pithy_auth_users`) applied one more time.
+*
+* **Nothing at runtime changes.** Zod's `.brand()` returns the same schema object — the brand exists only in
+* the type — and `.meta()` returns a clone that parses exactly as its source. `Schema.parse(row)` returns the
+* same data it did before the marker, and no column is added anywhere.
+*
+* ## The set is open
+*
+* Four classes ship named — `secret`, `pii`, `phi`, `pci` — and {@link definePrivacyClass} registers more
+* (`genetic`, `biometric`, whatever a regulator names) without a change to core. A closed union is what #117
+* records the cost of, and a healthcare adopter should not have to wait on us.
+*
+* ## Where `secret` stops and `@pithy-sh/secrets` starts
+*
+* Two different facts, kept apart on purpose. `@pithy-sh/secrets` decides **where a credential the Worker reads
+* is stored** — its registry names a backend, and its reader redacts the value it hands back. `secret()` says
+* **what a field in a data shape is** — a receipt, a magic-link token, a session id, a key hash — values that
+* live in rows and payloads and that no secrets registry ever holds. Merging them would make core depend on a
+* capability (principle 4) and would make a storage decision answer a classification question.
+*/
+/** The `meta` key a marker writes and every reader reads. */
+const PRIVACY_META_KEY = "privacy";
+/** The prefix of every privacy brand, so the gate never reads a brand that means something else. */
+const PRIVACY_BRAND_PREFIX = "privacy:";
+/** A class name: a lowercase identifier. It becomes a brand key, a config value and a report column. */
+const PrivacyClassName = z.string().regex(/^[a-z][a-z0-9_]*$/, "A privacy class name is a lowercase identifier: letters, digits and underscores.").describe("A privacy class name — `secret`, `pii`, `phi`, `pci`, or one an adopter registered with `definePrivacyClass`. A lowercase identifier.");
+/** The four classes the kit names, in the order every report lists them. */
+const BUILT_IN_PRIVACY_CLASSES = [
+	"secret",
+	"pii",
+	"phi",
+	"pci"
+];
+/** The placeholder every class but `pci` masks to: `[pii]`, `[phi]`, `[genetic]`. */
+function placeholder(name) {
+	return () => `[${name}]`;
+}
+/** The shortest and longest primary account numbers ISO/IEC 7812 issues. */
+const PAN_DIGITS = {
+	min: 13,
+	max: 19
+};
+/**
+* Mask a primary account number to its first six and last four digits — `424242******4242`.
+*
+* **The one class whose mask is not a placeholder, because the masked form is the useful one.** First-six and
+* last-four is the display PCI-DSS permits, and it is what an operator reading a log needs to match a
+* complaint to a card without holding the card. Spaces and dashes are separators and are dropped; anything
+* that is not 13 to 19 digits once they are is not a card number, and masks to `[pci]` rather than to a
+* partial reveal of something else.
+*
+* Every payment rail Pithy ships is hosted, so no PAN ever reaches an adopter's Worker through the kit. The
+* class is here for the adopter's own schemas.
+*/
+function maskPan(value) {
+	if (typeof value !== "string") return "[pci]";
+	const digits = value.replace(/[\s-]/g, "");
+	if (!/^\d+$/.test(digits) || digits.length < PAN_DIGITS.min || digits.length > PAN_DIGITS.max) return "[pci]";
+	return `${digits.slice(0, 6)}${"*".repeat(digits.length - 10)}${digits.slice(-4)}`;
+}
+/** The built-ins, stated once. The descriptions are what `pithy privacy` and the inventory docs read. */
+const BUILT_INS = {
+	secret: {
+		name: "secret",
+		description: "A credential or a bearer artifact — a session id, a magic-link token, a receipt, a key. The harm is impersonation, not exposure.",
+		mask: placeholder("secret")
+	},
+	pii: {
+		name: "pii",
+		description: "Personal data that identifies a person under GDPR or CCPA — an email address, a name, a phone number, a postal address.",
+		mask: placeholder("pii")
+	},
+	phi: {
+		name: "phi",
+		description: "Protected Health Information under HIPAA — a diagnosis, a treatment, a result, any health record tied to a person.",
+		mask: placeholder("phi")
+	},
+	pci: {
+		name: "pci",
+		description: "Cardholder data under PCI-DSS — a primary account number. Masks to its first six and last four digits.",
+		mask: maskPan
+	}
+};
+/**
+* Every registered class, by name. Module state, deliberately: a class is declared once, at module load, the
+* way a capability's error codes are — and an isolate holds one registry, so a class registered by the
+* adopter's schema module is known to the logger, the inventory and `redact` in the same isolate.
+*/
+const registry = new Map(Object.entries(BUILT_INS));
+/** The class a name refers to, or `undefined` for a name nothing registered. */
+function privacyClass(name) {
+	return registry.get(name);
+}
+/** Every registered class, built-ins first in their fixed order, then each adopter class in registration order. */
+function privacyClasses() {
+	return [...registry.values()];
+}
+/** The built-ins from the most harmful disclosure to the least: a credential, then health, then card, then identity. */
+const STRENGTH = [
+	"secret",
+	"phi",
+	"pci"
+];
+/**
+* `names` from the strongest to the weakest, each once: `secret`, then `phi`, then `pci`, then each adopter class, then
+* `pii`. An adopter registers a class because its data is more specific than `pii`, so it ranks above it; adopter
+* classes rank among themselves by name. The order a marker records several classes in, whatever order they came.
+*/
+function rankPrivacyClasses(names) {
+	const all = [...new Set(names)];
+	const builtIn = STRENGTH.filter((name) => all.includes(name));
+	const adopter = all.filter((name) => name !== "pii" && !STRENGTH.includes(name)).sort();
+	return [
+		...builtIn,
+		...adopter,
+		...all.includes("pii") ? ["pii"] : []
+	];
+}
+/**
+* The strongest of `names`, the class a value is masked with when it carries several and is masked whole. See
+* {@link rankPrivacyClasses}. `undefined` for none.
+*/
+function strongestPrivacyClass(names) {
+	return rankPrivacyClasses(names)[0];
+}
+/**
+* The classes a schema's own `privacy` meta records: one class as its name, several as a list, strongest first. Read
+* from this exact schema, never through a wrapper. Empty where it records none.
+*/
+function ownPrivacyClasses(schema) {
+	const value = schema.meta()?.[PRIVACY_META_KEY];
+	if (typeof value === "string") return [value];
+	if (Array.isArray(value)) return rankPrivacyClasses(value.filter((one) => typeof one === "string"));
+	return [];
+}
+/** Mark a schema with a class: the introspectable `meta`, and the type-level brand. */
+function marker(name) {
+	const mark = (schema) => {
+		const classes = rankPrivacyClasses([...ownPrivacyClasses(schema), name]);
+		const recorded = classes.length === 1 ? name : classes;
+		return schema.meta({
+			...schema.meta() ?? {},
+			[PRIVACY_META_KEY]: recorded
+		}).brand();
+	};
+	return Object.assign(mark, { className: name });
+}
+/**
+* Register a class of the adopter's own — `genetic`, `biometric`, whatever their regulator names — and get its
+* marker back. Usable exactly like the built-ins: the same `meta`, the same brand, the same gate, the same
+* inventory row.
+*
+* **A duplicate is refused at registration**, a built-in name included. Two modules each believing they own
+* `genetic` would disagree about its mask, and the one that loaded second would win silently.
+*/
+function definePrivacyClass(spec) {
+	if (!PrivacyClassName.safeParse(spec.name).success) throw new ValidationError({
+		message: `"${spec.name}" is not a privacy class name.`,
+		action: "Name the class with a lowercase identifier — letters, digits and underscores, e.g. `genetic`."
+	});
+	if (registry.has(spec.name)) throw new ConflictError({
+		message: `The privacy class "${spec.name}" is already registered.`,
+		action: `Register "${spec.name}" once, in one module, and import its marker everywhere else.`
+	});
+	registry.set(spec.name, {
+		name: spec.name,
+		description: spec.description ?? `An adopter-registered privacy class, "${spec.name}".`,
+		mask: spec.mask ?? placeholder(spec.name)
+	});
+	return marker(spec.name);
+}
+/** Mark a field as a credential or bearer artifact. See {@link BUILT_INS}. */
+const secret = marker("secret");
+/** Mark a field as personal data under GDPR or CCPA. */
+const pii = marker("pii");
+/** Mark a field as Protected Health Information under HIPAA. */
+const phi = marker("phi");
+/** Mark a field as cardholder data under PCI-DSS. Masks to first six and last four. */
+const pci = marker("pci");
+//#endregion
+export { BUILT_IN_PRIVACY_CLASSES, PRIVACY_BRAND_PREFIX, PRIVACY_META_KEY, PrivacyClassName, definePrivacyClass, maskPan, ownPrivacyClasses, pci, phi, pii, privacyClass, privacyClasses, rankPrivacyClasses, secret, strongestPrivacyClass };