@pithy-sh/core 0.11.0 → 0.13.0

package/src/data/codecs.ts

@@ -85,46 +85,78 @@ export const JsonDate = z.codec(z.union([z.string(), z.number(), z.date()]), z.d
 });
 
 /**
- * sqliteJson: T ↔ JSON string, validated by `schema` on both sides. Decode
- * accepts a JSON string or an already-parsed value; the result is validated
- * against `schema` before it reaches the app.
+ * sqliteJson's decode: a JSON string is parsed, an already-parsed value passes through. One function for every
+ * column, so `isSqliteJson` can tell the kit's codec from any other by its decode.
  *
- * **Both `JSON` functions throw**, and both were reachable. `JSON.parse` throws a
- * `SyntaxError` on any string that is not a JSON document — which a column holding
- * text an older writer put there, or a payload a customer's Worker returned, can be.
- * `JSON.stringify` throws a `TypeError` on a `BigInt` and on a cycle, either of
- * which a `schema` can legitimately admit. Both become an issue (#358).
+ * **`JSON.parse` throws**, and it was reachable: a column holding text an older writer put there, or a payload a
+ * customer's Worker returned, need not be a JSON document. That becomes an issue (#358).
  */
-export function sqliteJson<T extends z.ZodType>(schema: T) {
-  return z.codec(z.union([z.string(), schema]), schema, {
-    decode: (value, payload): z.input<T> => {
-      if (typeof value !== "string") return value as z.input<T>;
-      try {
-        return JSON.parse(value) as z.input<T>;
-      } catch {
-        payload.issues.push({ code: "invalid_format", format: "json", input: value, message: "Not valid JSON." });
-        return z.NEVER;
-      }
-    },
-    encode: (value, payload): string => {
-      // The offending value is deliberately not carried onto the issue: it is the thing JSON could not
-      // hold, so a reporter that renders an issue would be the second place to trip over it.
-      try {
-        const json = JSON.stringify(value);
-        if (typeof json === "string") return json;
-      } catch {
-        // Falls through to the one push below. A `BigInt`, a cycle and an `undefined` result are the
-        // same answer — this value does not survive the round trip — and they deserve the same issue.
-      }
-      payload.issues.push({
-        code: "invalid_format",
-        format: "json",
-        input: undefined,
-        message: "Not serializable as JSON.",
-      });
-      return z.NEVER;
-    },
+function decodeJson(value: unknown, payload: Payload<unknown>): unknown {
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    payload.issues.push({ code: "invalid_format", format: "json", input: value, message: "Not valid JSON." });
+    return z.NEVER;
+  }
+}
+
+/**
+ * sqliteJson's encode. **`JSON.stringify` throws** on a `BigInt` and on a cycle, either of which a schema can
+ * legitimately admit, so that becomes an issue too (#358).
+ */
+function encodeJson(value: unknown, payload: Payload<unknown>): string {
+  // The offending value is deliberately not carried onto the issue: it is the thing JSON could not hold, so a
+  // reporter that renders an issue would be the second place to trip over it.
+  try {
+    const json = JSON.stringify(value);
+    if (typeof json === "string") return json;
+  } catch {
+    // Falls through to the one push below. A `BigInt`, a cycle and an `undefined` result are the same answer —
+    // this value does not survive the round trip — and they deserve the same issue.
+  }
+  payload.issues.push({
+    code: "invalid_format",
+    format: "json",
+    input: undefined,
+    message: "Not serializable as JSON.",
   });
+  return z.NEVER;
+}
+
+/**
+ * sqliteJson: T ↔ JSON string, validated by `schema` on both sides. Decode accepts a JSON string or an
+ * already-parsed value; the result is validated against `schema` before it reaches the app.
+ */
+export function sqliteJson<T extends z.ZodType>(schema: T): SqliteJson<T> {
+  return z.codec(z.union([z.string(), schema]), schema, {
+    decode: decodeJson as (value: string | z.output<T>, payload: Payload<string | z.output<T>>) => z.input<T>,
+    encode: encodeJson as (value: z.input<T>, payload: Payload<z.input<T>>) => string,
+  }) as SqliteJson<T>;
+}
+
+/**
+ * Names the type `sqliteJson` returns, and nothing else. A type only: no value carries it. `Redacted<T>` reads a JSON
+ * column's fields through it, as `redact` reads them through {@link isSqliteJson}, so an adopter's codec of the same
+ * shape is opaque to both.
+ */
+declare const kitJsonColumn: unique symbol;
+
+/** What `sqliteJson(schema)` returns: the kit's JSON column over `schema`. Clones keep it, as they return `this`. */
+export type SqliteJson<T extends z.ZodType> = z.ZodCodec<z.ZodUnion<[z.ZodString, T]>, T> & {
+  readonly [kitJsonColumn]: T;
+};
+
+/** The schema a kit JSON column decodes to, or `never` for any other node. */
+export type SqliteJsonSchema<S> = S extends { readonly [kitJsonColumn]: infer T } ? T : never;
+
+/**
+ * Whether a schema is a JSON column `sqliteJson` built, or a clone of one (`.describe()`, `.meta()`), read by its
+ * decode. `redact` walks such a column's fields one by one, and treats every other codec as opaque.
+ */
+export function isSqliteJson(schema: z.ZodType): boolean {
+  const def = schema._zod.def as { type: string; transform?: unknown };
+  return def.type === "pipe" && def.transform === decodeJson;
 }
 
 export const MAX_TIMEZONE_LENGTH = 64;

package/src/error/extend.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import type { MessageParams } from "../i18n/catalog";
+import type { UnmarkedString } from "../privacy/types";
 import type { ErrorPayload, KitErrorDomain } from "./payload";
 import { ExtendedErrorPayload } from "./payload";
 import { InternalError } from "./pithyError";
@@ -95,11 +96,11 @@ export function defineErrorPayload<const Code extends `${string}/${string}`>(
     /** The HTTP status this code maps to. A 4xx or a 5xx — an error is not a success. */
     status: number;
     /** Public, safe-to-expose summary. Sent to clients and shown in the terminal. */
-    message: string;
-    /** Operator remediation hint. Becomes the CLI action line. Never sent to a client. */
-    action?: string;
-    /** Internal context for logs + audit. NEVER serialized to clients — the HTTP codec strips it. */
-    detail?: string;
+    message: UnmarkedString;
+    /** Operator remediation hint. Becomes the CLI action line. Never sent to a client. Never a marked value (#132). */
+    action?: UnmarkedString;
+    /** Internal context for logs + audit. NEVER serialized to clients — the HTTP codec strips it. Never a marked value (#132). */
+    detail?: UnmarkedString;
     /**
      * Values a translating client interpolates into its own wording for this code. Client-facing:
      * these cross the boundary with `message`, unlike `action` and `detail`.

package/src/error/payload.ts

@@ -181,6 +181,38 @@ const AuthSessionNotFreshPublic = z
   })
   .describe("The session is authentic but the holder authenticated too long ago to attach a provider (403).");
 
+const AuthAccountSuspendedPublic = z
+  .object({
+    code: z
+      .literal("auth/account_suspended")
+      .describe(
+        "The account this credential belongs to is suspended, so the request is refused whatever it carries. An operator suspended it on purpose, with a reason, and the reason is the `message`. When the suspension has an end, `params.suspendedUntil` names it as ISO-8601; a suspension past its end is no longer one, and nothing has to clear it. A separate code from `auth/forbidden` so a client can render the screen that says what happened rather than a generic refusal.",
+      ),
+    status: z
+      .literal(403)
+      .describe(
+        "Forbidden — the credential is genuine and the account behind it may not act. Not 401: signing in again cannot help, and a client that read it as an expired token would loop.",
+      ),
+    ...publicFields,
+  })
+  .describe("The account is suspended (403).");
+
+const AuthAccountDeletedPublic = z
+  .object({
+    code: z
+      .literal("auth/account_deleted")
+      .describe(
+        "The account this credential belongs to is deleted and inside its purge window: it cannot sign in or act, and it can still be restored until the window closes. After the purge there is no account, and the credential is simply invalid.",
+      ),
+    status: z
+      .literal(403)
+      .describe(
+        "Forbidden — the account exists and may not act. Not 404, because until the purge runs it can come back, and not 401, because signing in again cannot help.",
+      ),
+    ...publicFields,
+  })
+  .describe("The account is deleted and awaiting its purge (403).");
+
 const NotFoundPublic = z
   .object({
     code: z.literal("core/not_found").describe("The requested resource does not exist."),
@@ -1493,6 +1525,54 @@ const OrganizationNominationInvalidPublic = z
   })
   .describe("No standing ownership offer this caller may accept (400).");
 
+const OrganizationLastOwnerPublic = z
+  .object({
+    code: z
+      .literal("organization/last_owner")
+      .describe(
+        "An operator write would leave the account with nobody holding the role a transfer of ownership confers: removing or demoting its only owner. An account with no owner is the unadministrable state membership administration exists to get out of, so the way out is to force ownership onto somebody else first, which `params.ownershipRoute` names.",
+      ),
+    status: z.literal(409).describe("Conflict — an account nobody owns is not a state to arrive at."),
+    ...publicFields,
+  })
+  .describe("The last owner cannot be removed or demoted (409).");
+
+const OrganizationAlreadyMemberPublic = z
+  .object({
+    code: z
+      .literal("organization/already_member")
+      .describe(
+        "An operator tried to add somebody who already holds a membership in the account. One membership per person per organization, so this is a refusal rather than a second row — and `params.role` names the role they already hold, because the next step is a role change rather than an add.",
+      ),
+    status: z.literal(409).describe("Conflict."),
+    ...publicFields,
+  })
+  .describe("That person is already a member (409).");
+
+const OrganizationSeatLimitReachedPublic = z
+  .object({
+    code: z
+      .literal("organization/seat_limit_reached")
+      .describe(
+        "The account holds as many members as its seat limit allows, so another one would exceed it. `params.seatLimit` names the limit. An operator add may override it, and the override is recorded; an invitation accepted against a full account is refused until a seat frees.",
+      ),
+    status: z.literal(409).describe("Conflict."),
+    ...publicFields,
+  })
+  .describe("The account has no free seat (409).");
+
+const OrganizationSuspendedPublic = z
+  .object({
+    code: z
+      .literal("organization/organization_suspended")
+      .describe(
+        "The organization this request acts in is suspended by an operator, so nobody can act in it until it is reinstated (#623). The caller's own account is not affected, and their other organizations are not either. `params.suspendedUntil`, when present, is when the suspension ends by itself, ISO-8601. Not `organization/forbidden`, because no role would let them, and not `organization/not_found`, because the caller is a proved member and already knows the organization exists.",
+      ),
+    status: z.literal(403).describe("Forbidden — the organization may not be acted in, whoever asks."),
+    ...publicFields,
+  })
+  .describe("The organization is suspended (403).");
+
 // --- @pithy-sh/artifacts: Git repositories, ownership, grants and short-lived tokens ---
 
 const ArtifactsNotFoundPublic = z
@@ -1758,6 +1838,8 @@ export const KitPublicErrorPayload = z
     ForbiddenPublic,
     AuthProviderUnavailablePublic,
     AuthSessionNotFreshPublic,
+    AuthAccountSuspendedPublic,
+    AuthAccountDeletedPublic,
     NotFoundPublic,
     ConflictPublic,
     RateLimitPublic,
@@ -1874,6 +1956,10 @@ export const KitPublicErrorPayload = z
     OrganizationLastAdministratorPublic,
     OrganizationSlugTakenPublic,
     OrganizationNominationInvalidPublic,
+    OrganizationLastOwnerPublic,
+    OrganizationAlreadyMemberPublic,
+    OrganizationSeatLimitReachedPublic,
+    OrganizationSuspendedPublic,
     ArtifactsNotFoundPublic,
     ArtifactsForbiddenPublic,
     ArtifactsInvalidNamePublic,
@@ -1914,6 +2000,12 @@ const AuthProviderUnavailable = AuthProviderUnavailablePublic.extend(internalFie
 const AuthSessionNotFresh = AuthSessionNotFreshPublic.extend(internalFields).describe(
   AuthSessionNotFreshPublic.description ?? "",
 );
+const AuthAccountSuspended = AuthAccountSuspendedPublic.extend(internalFields).describe(
+  AuthAccountSuspendedPublic.description ?? "",
+);
+const AuthAccountDeleted = AuthAccountDeletedPublic.extend(internalFields).describe(
+  AuthAccountDeletedPublic.description ?? "",
+);
 const NotFound = NotFoundPublic.extend(internalFields).describe(NotFoundPublic.description ?? "");
 const Conflict = ConflictPublic.extend(internalFields).describe(ConflictPublic.description ?? "");
 const RateLimit = RateLimitPublic.extend(internalFields).describe(RateLimitPublic.description ?? "");
@@ -2264,6 +2356,18 @@ const OrganizationSlugTaken = OrganizationSlugTakenPublic.extend(internalFields)
 const OrganizationNominationInvalid = OrganizationNominationInvalidPublic.extend(internalFields).describe(
   OrganizationNominationInvalidPublic.description ?? "",
 );
+const OrganizationLastOwner = OrganizationLastOwnerPublic.extend(internalFields).describe(
+  OrganizationLastOwnerPublic.description ?? "",
+);
+const OrganizationAlreadyMember = OrganizationAlreadyMemberPublic.extend(internalFields).describe(
+  OrganizationAlreadyMemberPublic.description ?? "",
+);
+const OrganizationSeatLimitReached = OrganizationSeatLimitReachedPublic.extend(internalFields).describe(
+  OrganizationSeatLimitReachedPublic.description ?? "",
+);
+const OrganizationSuspended = OrganizationSuspendedPublic.extend(internalFields).describe(
+  OrganizationSuspendedPublic.description ?? "",
+);
 
 const ArtifactsNotFound = ArtifactsNotFoundPublic.extend(internalFields).describe(
   ArtifactsNotFoundPublic.description ?? "",
@@ -2311,6 +2415,8 @@ export const KitErrorPayload = z
     Forbidden,
     AuthProviderUnavailable,
     AuthSessionNotFresh,
+    AuthAccountSuspended,
+    AuthAccountDeleted,
     NotFound,
     Conflict,
     RateLimit,
@@ -2427,6 +2533,10 @@ export const KitErrorPayload = z
     OrganizationLastAdministrator,
     OrganizationSlugTaken,
     OrganizationNominationInvalid,
+    OrganizationLastOwner,
+    OrganizationAlreadyMember,
+    OrganizationSeatLimitReached,
+    OrganizationSuspended,
     ArtifactsNotFound,
     ArtifactsForbidden,
     ArtifactsInvalidName,

package/src/error/pithyError.ts

@@ -3,6 +3,7 @@
 
 import type { z } from "zod";
 import type { MessageParams } from "../i18n/catalog";
+import type { UnmarkedString } from "../privacy/types";
 import type { ValidationIssue } from "./payload";
 import { ErrorPayload } from "./payload";
 
@@ -18,7 +19,20 @@ import { ErrorPayload } from "./payload";
 export class PithyError extends Error {
   readonly payload: ErrorPayload;
 
-  constructor(payload: ErrorPayload, options?: { cause?: unknown }) {
+  /**
+   * `message`, `action` and `detail` are each an {@link UnmarkedString} here and on every subclass's arguments
+   * (#132): a value marked with a privacy class is refused at compile time, because all three ride into every log
+   * line and audit row that carries this error. A template literal is a plain `string`, so interpolation is not caught — see
+   * `privacy/types.ts` for exactly what is.
+   */
+  constructor(
+    payload: ErrorPayload & {
+      message: UnmarkedString;
+      action?: UnmarkedString | undefined;
+      detail?: UnmarkedString | undefined;
+    },
+    options?: { cause?: unknown },
+  ) {
     const parsed = ErrorPayload.parse(payload);
     super(parsed.message, options);
     this.payload = parsed;
@@ -28,12 +42,12 @@ export class PithyError extends Error {
 
 /** Variable parts every subclass accepts; the `code`/`status` are fixed by the subclass. */
 interface ErrorArgs {
-  /** Override the public, safe-to-expose message. Defaults to a per-code summary. */
-  message?: string;
-  /** A remediation hint (CLI action line). */
-  action?: string;
-  /** Internal context for logs + audit. Never serialized to clients. */
-  detail?: string;
+  /** Override the public, safe-to-expose message. Defaults to a per-code summary. Never a privacy-marked value. */
+  message?: UnmarkedString;
+  /** A remediation hint (CLI action line). Never a privacy-marked value. */
+  action?: UnmarkedString;
+  /** Internal context for logs + audit. Never serialized to clients, and never a privacy-marked value (#132). */
+  detail?: UnmarkedString;
   /**
    * Values a translating client interpolates into its own wording for this code. Client-facing, so —
    * unlike `action` and `detail` — these cross the boundary with `message`. The `code` is the catalog

package/src/http/validation.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { zValidator } from "@hono/zod-validator";
-import type { ValidationTargets } from "hono";
+import type { Context, MiddlewareHandler, ValidationTargets } from "hono";
 import type { z } from "zod";
 import { fromZodError } from "../error/pithyError";
 
@@ -70,12 +70,44 @@ export interface RequestContract {
 export function validate<Target extends keyof ValidationTargets, Schema extends z.ZodType>(
   target: Target,
   schema: Schema,
+  onInvalid?: InvalidRequestListener,
 ) {
-  const middleware = zValidator(target, schema, validationHook);
   const contract: RequestContract = { target, schema };
-  return Object.assign(middleware, { [REQUEST_CONTRACT]: contract });
+  if (!onInvalid) return Object.assign(zValidator(target, schema, validationHook), { [REQUEST_CONTRACT]: contract });
+  // What each refused request sent, keyed by its context, so the listener is handed the input without
+  // reading the request raw — which no route may do.
+  const refusedInput = new WeakMap<Context, unknown>();
+  const middleware = zValidator(target, schema, (outcome: ValidationOutcome & { data?: unknown }, c: Context) => {
+    if (!outcome.success) refusedInput.set(c, outcome.data);
+    validationHook(outcome);
+  });
+  // Only a throw from the validator itself is a refusal of the request. Once `next` runs, a throw is the
+  // handler's, and is the handler's to record.
+  const listened: MiddlewareHandler = async (c, next) => {
+    let reached = false;
+    try {
+      return await middleware(c, async () => {
+        reached = true;
+        await next();
+      });
+    } catch (error) {
+      if (!reached) await onInvalid(c, error, refusedInput.get(c));
+      throw error;
+    }
+  };
+  return Object.assign(listened as typeof middleware, { [REQUEST_CONTRACT]: contract });
 }
 
+/**
+ * Told when {@link validate} refuses a request — a body that does not parse, or one that fails the schema —
+ * before the refusal is thrown. A route whose every attempt must be on the audit trail records the refusal
+ * here. It cannot turn the refusal into anything else: the error is thrown after it returns, and a listener
+ * that throws replaces it. `input` is what the request sent for the validated part, as it arrived; it is
+ * `undefined` when there was nothing to read, as for a body that is not JSON. Input validated by an earlier
+ * {@link validate} on the same route is readable with `c.req.valid(target)`.
+ */
+export type InvalidRequestListener = (c: Context, error: unknown, input: unknown) => Promise<void> | void;
+
 /** The contract a {@link validate} middleware carries, or `undefined` for any other handler. */
 export function requestContractOf(handler: unknown): RequestContract | undefined {
   if (typeof handler !== "function") return undefined;

package/src/index.ts

@@ -102,6 +102,7 @@ export {
   KEYS_ROTATE_SCOPE,
   MANIFEST_READ_SCOPE,
   MIGRATIONS_READ_SCOPE,
+  PRIVACY_READ_SCOPE,
   SEAM_SCOPES,
 } from "./controlPlane/scope/scope";
 export { exportPublicJwk, type MintControlPlaneToken, mintControlPlaneToken } from "./controlPlane/token/mint";

package/src/logger/logger.ts

@@ -3,6 +3,7 @@
 
 import type { ErrorPayload } from "../error/payload";
 import { PithyError } from "../error/pithyError";
+import type { Loggable, UnmarkedString } from "../privacy/types";
 import { LOG_LEVEL_ORDER, type LogFields, type LogLevel, type LogRecord } from "./record";
 
 /**
@@ -15,22 +16,28 @@ import { LOG_LEVEL_ORDER, type LogFields, type LogLevel, type LogRecord } from "
  * The reserved `error` field on any call may carry a `PithyError` or `ErrorPayload` — the engine lifts
  * it into the record's `error`, `detail` and all. A log is internal; this is the inverse of the HTTP
  * codec, which strips `detail`. The logger must never be wired to a client-facing surface.
+ *
+ * **A value marked with a privacy class does not compile here** (#132). Every method takes `F & Loggable<F>`,
+ * so a field holding a `pii()`/`phi()`/`secret()`/`pci()` value — the value itself, or one inside an object or
+ * an array, to the depth `privacy/types.ts` states — is refused at that key, and `redact(Schema, value)` is the
+ * way through. The message and a child's name take `UnmarkedString`, so `log.info(user.email)` is refused too. `LogFields` the schema stays permissive: a record that reaches a sink at runtime still parses,
+ * because a brand is a type and a parsed log line has none.
  */
 export interface Logger {
   /** Dev-time diagnostics. Dropped unless the logger's level is `debug`. */
-  debug(msg: string, fields?: LogFields): void;
+  debug<F extends LogFields = LogFields>(msg: UnmarkedString, fields?: F & Loggable<F>): void;
   /** Normal operational events. */
-  info(msg: string, fields?: LogFields): void;
+  info<F extends LogFields = LogFields>(msg: UnmarkedString, fields?: F & Loggable<F>): void;
   /** A recoverable problem worth attention. */
-  warn(msg: string, fields?: LogFields): void;
+  warn<F extends LogFields = LogFields>(msg: UnmarkedString, fields?: F & Loggable<F>): void;
   /** A failure that was observed. Pass `{ error }` (a PithyError) to carry its full payload. */
-  error(msg: string, fields?: LogFields): void;
+  error<F extends LogFields = LogFields>(msg: UnmarkedString, fields?: F & Loggable<F>): void;
   /**
    * A namespaced sub-logger. `name` composes as `parent:child`; bound `fields` merge into every record
    * the child emits. Omit `name` (pass `undefined`) to bind fields only — how request-correlation
    * attaches `request`/`method`/`path` without renaming the logger.
    */
-  child(name?: string, fields?: LogFields): Logger;
+  child<F extends LogFields = LogFields>(name?: UnmarkedString, fields?: F & Loggable<F>): Logger;
 }
 
 /** A sink receives a finished {@link LogRecord}. Adapters supply one; the engine builds records and calls it. */

package/src/privacy/blindIndex.ts

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type EncryptionConfig, keyBytes } from "../crypto/envelope";
+import { FIELD_KEYS_BINDING } from "../crypto/fieldKeys";
+import { type BlindIndexNormalizer, normalizeForIndex } 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 function blindIndexLabel(normalizer: BlindIndexNormalizer): string {
+  return `pithy/blind-index/${normalizer}`;
+}
+
+/** Unpadded base64url, the alphabet a blind index is written in. */
+function base64Url(bytes: Uint8Array): string {
+  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. */
+export async function blindIndexKey(
+  config: EncryptionConfig,
+  version: number,
+  normalizer: BlindIndexNormalizer,
+): Promise<CryptoKey> {
+  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: 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. */
+export async function blindIndexValue(
+  config: EncryptionConfig,
+  version: number,
+  normalizer: BlindIndexNormalizer,
+  value: string,
+): Promise<string> {
+  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. */
+export function blindIndexVersion(value: string): number | null {
+  const match = /^(\d+):/.exec(value);
+  return match ? Number(match[1]) : null;
+}