@pithy-sh/core 0.10.0 → 0.12.0

package/src/crypto/fieldKeys.ts

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { remedy } from "../cli/command";
+import { InternalError } from "../error/pithyError";
+import { EncryptionConfig } from "./envelope";
+
+/**
+ * **The field key: what an app Worker seals its encrypted fields with** (#390).
+ *
+ * `PITHY_FIELD_KEYS` is an {@link EncryptionConfig}, the same versioned shape as secrets' master key, and it is a
+ * **different key on purpose**. Field encryption seals and opens inside the adopter's own Workers, so every Worker that
+ * holds an encrypted field must hold the key it uses. Were that the master key `SECRETS_ENCRYPTION_KEYS`, every such
+ * Worker would hold the key to the whole secrets vault, and one compromised would open it. A key of its own limits
+ * that to the fields: a Worker that holds an encrypted field and composes no `secrets` is bound this key and never
+ * the master key.
+ *
+ * It is not a second mechanism: `pithy secrets provision` mints it beside the master key, in the same format, binds
+ * it to every Worker that holds an encrypted field, and the manager's at-rest cron rotates it every
+ * {@link FIELD_KEY_ROTATION_DAYS} days.
+ */
+
+/** The binding an app Worker reads its field key through. Fixed across environments; only the store entry is scoped. */
+export const FIELD_KEYS_BINDING = "PITHY_FIELD_KEYS";
+
+/** How often the manager rotates the field key, in days. */
+export const FIELD_KEY_ROTATION_DAYS = 30;
+
+/** A Secrets Store binding: `.get()` resolves the plaintext inside the Worker. */
+export interface FieldKeyBinding {
+  get(): Promise<string>;
+}
+
+/**
+ * Where a field key comes from: the Worker's `env.PITHY_FIELD_KEYS` binding (a Secrets Store binding deployed, a JSON
+ * string from `.dev.vars` locally), or a config a caller already resolved.
+ */
+export type FieldKeys = FieldKeyBinding | string | EncryptionConfig;
+
+/**
+ * Resolve a field key to its config. A missing binding, text that is not JSON, and JSON that is not a key set are each
+ * refused, and **nothing read is ever echoed**: what failed to parse is the key set.
+ */
+export async function resolveFieldKeys(keys: FieldKeys | undefined): Promise<EncryptionConfig> {
+  let raw: unknown = keys;
+  if (keys === undefined || keys === null) {
+    throw new InternalError({
+      message: "This Worker holds an encrypted field and no field key.",
+      action: `Bind ${FIELD_KEYS_BINDING}. ${remedy("secrets provision").say((command) => `${command} binds it to every Worker with an encrypted field.`)}`,
+      detail: `${FIELD_KEYS_BINDING} binding is not configured`,
+    });
+  }
+  if (typeof keys === "object" && "get" in keys && typeof keys.get === "function") raw = await keys.get();
+  if (typeof raw === "string") {
+    try {
+      raw = JSON.parse(raw);
+    } catch {
+      throw new InternalError({ detail: `${FIELD_KEYS_BINDING} is not valid JSON` });
+    }
+  }
+  const parsed = EncryptionConfig.safeParse(raw);
+  if (!parsed.success) throw new InternalError({ detail: `${FIELD_KEYS_BINDING} is not a valid EncryptionConfig` });
+  return parsed.data;
+}
+
+/**
+ * Every live version in a key set, newest first, as numbers. A version key that is not an integer is refused rather
+ * than sorted as text, where `"10"` sorts before `"9"`.
+ */
+export function liveVersions(config: EncryptionConfig): number[] {
+  const versions = Object.keys(config.versions).map(Number);
+  if (!versions.every((version) => Number.isInteger(version))) {
+    throw new InternalError({ detail: `${FIELD_KEYS_BINDING}: a version key is not a stringified integer` });
+  }
+  return versions.sort((left, right) => right - left);
+}

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/entitlement/allowance.ts

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context } from "hono";
+import type { PithyHonoEnv } from "../capability/capability";
+import { InternalError, messageOf } from "../error/pithyError";
+import type { MeterLimit } from "./entitlement";
+
+/**
+ * The allowance readers — how much the current caller may have, and whether a switch is on.
+ *
+ *   const seats = await quota(c, "seats");                  // number, or null for unlimited
+ *   if (seats !== null && (await countMembers(orgId)) >= seats) throw new SeatLimitReached(…);
+ *   if (await feature(c, "auditExport")) { … }               // boolean, never null
+ *
+ * **Neither takes an entitlement key, and that is the point.** A route does not know which tier the
+ * caller's holder is on, and during an upgrade overlap it holds two. The provider resolves across every
+ * key the holder has and answers the higher, so an adopter compares numbers and never ranks tiers.
+ *
+ * **Read, never enforced.** A quota denies nothing on its own and a feature set to `false` denies
+ * nothing either — `requireEntitlement` still gates on the key alone. What a number means for a request
+ * is the adopter's code to decide, because only the adopter can count what it owns.
+ *
+ * **They live in core for the reason `requireEntitlement` does.** A reader that arrived with
+ * `@pithy-sh/payments` would be absent when payments is, and a route reading an allowance must then fail
+ * rather than read something. So with no provider composed — or one that declares no allowances — both
+ * throw `core/internal` naming the gap. Never `0`, which is a paywall shut for a reason nobody can see;
+ * never unlimited, which is a paywall that does not exist.
+ */
+
+/** The refusal when nothing on the request can answer an allowance. The adopter's wiring, so `core/internal`. */
+function noProvider(c: Context<PithyHonoEnv>, kind: "quota" | "feature", name: string): InternalError {
+  const provider = c.var.entitlements?.provider ?? null;
+  return new InternalError({
+    message: `No ${kind} "${name}" can be resolved here.`,
+    action: "Compose a payments capability that declares its entitlements in this Worker's pithy.config.ts.",
+    detail:
+      provider === null
+        ? `no entitlement provider is composed, so ${kind}("${name}") has nothing to read.`
+        : `${provider} resolves entitlements and declares no allowances, so ${kind}("${name}") has nothing to read.`,
+  });
+}
+
+/** How many of `name` the caller's holder may have: a whole number, or `null` for unlimited. */
+export async function quota(c: Context<PithyHonoEnv>, name: string): Promise<number | null> {
+  const resolver = c.var.entitlements;
+  if (!resolver?.quota) throw noProvider(c, "quota", name);
+  return resolver.quota(name);
+}
+
+/** Whether `name` is on for the caller's holder. Always a boolean. */
+export async function feature(c: Context<PithyHonoEnv>, name: string): Promise<boolean> {
+  const resolver = c.var.entitlements;
+  if (!resolver?.feature) throw noProvider(c, "feature", name);
+  return resolver.feature(name);
+}
+
+/**
+ * The ceiling a capability enforces on a meter it counts itself, for the current caller.
+ *
+ * **No provider, or one that binds nothing to this meter, is `{ enforced: false }`** — and the capability
+ * keeps its own configured ceiling. Enforcement is opt-in per meter because a cap that arrives by surprise
+ * breaks an adopter who was already over it.
+ *
+ * **A provider that throws refuses, and logs.** Storage already says which way round to err: over-counting
+ * briefly and reclaiming is the right way round, and under-counting has no recovery. Treating a failed read
+ * as unenforced would hand a customer an unbounded allowance for as long as the read kept failing. The cost
+ * is real and is stated rather than discovered: our bug becomes a refused write for a paying customer.
+ * Enforcement being opt-in is what bounds it — an adopter who would rather over-serve leaves the meter
+ * advisory.
+ */
+export async function meterLimit(c: Context<PithyHonoEnv>, meter: string): Promise<MeterLimit> {
+  const resolver = c.var.entitlements;
+  if (!resolver?.meterLimit) return { enforced: false };
+  try {
+    return await resolver.meterLimit(meter);
+  } catch (error) {
+    c.var.log?.error("meter limit resolution failed", { provider: resolver.provider, meter, cause: messageOf(error) });
+    throw new InternalError({
+      message: "Usage could not be checked, so nothing was written.",
+      action: "Read the preceding log line for why the allowance read failed.",
+      detail: `${resolver.provider} threw resolving the ${meter} meter's ceiling; refusing rather than serving unbounded.`,
+    });
+  }
+}

package/src/entitlement/entitlement.ts

@@ -132,8 +132,46 @@ export interface EntitlementResolver {
    * See {@link EntitlementHolder} for why this is a label and a tenant rather than the holder itself.
    */
   holder?(): Promise<EntitlementHolder | undefined>;
+  /**
+   * How many of `name` the current caller's holder may have — a whole number, or `null` for unlimited.
+   * Optional: a provider with no allowances omits it, and {@link import("./allowance").quota} refuses
+   * rather than inventing a number. A provider throws for a name it does not declare, never answers 0.
+   */
+  quota?(name: string): Promise<number | null>;
+  /** Whether `name` is on for the current caller's holder. Never null. Optional, as {@link quota} is. */
+  feature?(name: string): Promise<boolean>;
+  /**
+   * The ceiling a capability that counts its own rows enforces for `meter` — storage's bytes, media's
+   * items — or `{ enforced: false }` where the provider binds no ceiling to it. Optional, and absent is
+   * `{ enforced: false }`: a capability composed with no provider keeps its own configured behavior.
+   */
+  meterLimit?(meter: string): Promise<MeterLimit>;
 }
 
+/**
+ * What a provider says about one meter for the current caller: whether it binds a ceiling at all, and if
+ * it does, what the ceiling is and whose rows it covers. `limit: null` is unlimited — an enforced meter on
+ * a subject whose plan or override says so.
+ *
+ * Two states rather than a nullable number, because "this meter is advisory here" and "this subject is
+ * unlimited" are different facts and a capability must fall back to its own configured ceiling on the
+ * first and never on the second.
+ *
+ * **An enforced ceiling says which rows it is the whole of**, because a ceiling counted against the wrong
+ * rows is a different allowance. Under organization billing the plan's 10 GB is the company's: counted
+ * against one member's files it becomes 10 GB per member, and a paid quota is bypassed by an invitation.
+ * So `tenant` is the organization the ceiling was resolved for, exactly as {@link EntitlementHolder.tenant}
+ * is, and a capability sums every row it holds for that tenant, whoever wrote it. `null` means the holder
+ * is not a tenant: the ceiling is the caller's own, and the caller's rows are what count.
+ *
+ * It is a counting key, never a gate. A capability that would write a row for a different tenant than the
+ * one the ceiling covers refuses the write — that row would sit outside the sum, and under-counting has no
+ * recovery.
+ */
+export type MeterLimit =
+  | { readonly enforced: false }
+  | { readonly enforced: true; readonly limit: number | null; readonly tenant: string | null };
+
 /**
  * How a resolver's holder appears in a denial's `detail` and on the denial's audit row — and **nothing a
  * gate may compare**.

package/src/entitlement/meter.ts

@@ -0,0 +1,69 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "../capability/capability";
+import type { Logger } from "../logger/logger";
+
+/**
+ * The usage-meter seam — how a capability that writes the rows a meter counts asks whether one more is
+ * allowed, when there is no request to ask through.
+ *
+ * `@pithy-sh/email` enqueues from a route, from a Workflow step and from a cron, and only the first has a
+ * `c.var.entitlements`. So the meter it charges is found the way the ledger is found — among the composed
+ * capabilities, by a structural predicate — and it is handed the holder explicitly. Nothing here imports the
+ * provider: an email capability composed with no payments finds no meter and enqueues as it always did.
+ *
+ * **A meter refuses; it never bills.** `charge` either records the use or throws the provider's own refusal
+ * (`payments/quota_exceeded`, 402). What it counted is never reported to a store — the kit does not sell
+ * overage — so this seam has no way to read a count back out.
+ */
+
+/** Who a charge is against: the holder pair, exactly as the provider keys it. */
+export interface MeterSubject {
+  /** The kind of holder — `user` or `organization` under `@pithy-sh/payments`. */
+  readonly subjectType: string;
+  /** The holder's id. */
+  readonly subjectId: string;
+}
+
+/** One charge against one meter. */
+export interface MeterCharge {
+  /** Who uses it. */
+  readonly subject: MeterSubject;
+  /** Which meter — `emails`. */
+  readonly meter: string;
+  /** How many. A whole number from 1. */
+  readonly amount: number;
+  /** The clock. Defaults to now. */
+  readonly now?: Date;
+  /** Where a refused or failed charge is logged. Optional; the provider logs through its own when absent. */
+  readonly log?: Logger;
+}
+
+/** The meter a provider exposes. */
+export interface UsageMeter {
+  /** The capability answering — `payments`. */
+  readonly provider: string;
+  /**
+   * Record `amount` of `meter` against `subject`, or refuse. An advisory meter records nothing and refuses
+   * nothing. **A charge that cannot be checked refuses**, because under-counting has no recovery.
+   */
+  charge(env: Record<string, unknown>, charge: MeterCharge): Promise<void>;
+}
+
+/** A composed capability that provides a meter. */
+export interface UsageMeterProvider extends Capability {
+  /** The meter. */
+  readonly usageMeter: UsageMeter;
+}
+
+/** Whether a composed capability provides a usage meter. Structural, so no provider package is imported. */
+export function isUsageMeterProvider(capability: Capability): capability is UsageMeterProvider {
+  const meter = (capability as { usageMeter?: { charge?: unknown } }).usageMeter;
+  return typeof meter?.charge === "function";
+}
+
+/** The composed usage meter, or undefined when nothing composed provides one. */
+export function composedUsageMeter(capabilities: readonly Capability[]): UsageMeter | undefined {
+  return capabilities.find(isUsageMeterProvider)?.usageMeter;
+}

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`.