@prisma-next/extension-cipherstash 0.0.1

package/src/execution/codec-runtime.ts

@@ -0,0 +1,209 @@
+/**
+ * Cipherstash storage codec runtime — wraps the `EncryptedString`
+ * envelope at the SQL codec boundary.
+ *
+ * Responsibilities are intentionally thin:
+ *
+ * - `decode(wire, ctx)` constructs a fresh envelope carrying the wire
+ *   ciphertext + the cell's `(table, column)` from `ctx.column` + the
+ *   SDK reference captured at codec construction time. The envelope's
+ *   `decrypt({signal?})` later routes through the captured SDK; callers
+ *   can also `await decryptAll(rows)` to coalesce decrypts across many
+ *   envelopes into one bulk SDK call.
+ *
+ * - `encode(envelope, ctx)` extracts the ciphertext from the envelope's
+ *   handle. The bulk-encrypt middleware populates the ciphertext slot
+ *   before the codec runs; an envelope whose ciphertext
+ *   slot is empty at encode time is a programmer error (the middleware
+ *   was not registered, or this codec instance was used in a non-
+ *   cipherstash context).
+ *
+ * The wire format wraps the SDK's JSON ciphertext payload in the
+ * Postgres composite literal `("...escaped JSON...")` because EQL
+ * defines `eql_v2_encrypted` as `CREATE TYPE eql_v2_encrypted AS (data
+ * jsonb)`, not as a domain over jsonb. The default `pg` driver encodes
+ * JS objects as JSON which Postgres then rejects when coercing into the
+ * composite. Mirrors the reference Drizzle integration at
+ * `reference/cipherstash/.../drizzle/src/pg/index.ts`.
+ *
+ * The codec captures the SDK at construction time, so multi-tenant
+ * deployments construct one extension instance per tenant — each with
+ * its own SDK — rather than sharing a module-singleton codec.
+ */
+
+import type { JsonValue } from '@prisma-next/contract/types';
+import { type AnyCodecDescriptor, CodecImpl } from '@prisma-next/framework-components/codec';
+import type { Codec, SqlCodecCallContext } from '@prisma-next/sql-relational-core/ast';
+import { CIPHERSTASH_STRING_CODEC_ID } from '../extension-metadata/constants';
+import { EncryptedString } from './envelope';
+import type { CipherstashSdk } from './sdk';
+
+const CIPHERSTASH_STRING_TARGET_TYPE = 'eql_v2_encrypted' as const;
+// Cipherstash columns intentionally declare no codec traits.
+//
+// The framework's `equality` trait gates the built-in `eq` / `neq` /
+// `in` / `notIn` comparison methods (see `COMPARISON_METHODS_META` in
+// `packages/3-extensions/sql-orm-client/src/types.ts`). Those built-
+// ins lower to standard SQL `=` / `!=` / `IN`, which is wrong for
+// cipherstash columns because EQL ciphers contain randomized nonces
+// and do not byte-equal under `=`. Declaring `equality` here would
+// silently expose the wrong-SQL footgun; declaring `[]` makes
+// `email.eq(...)` undefined at the column accessor and forces callers
+// onto the cipherstash-namespaced operator surface
+// (`email.cipherstashEq(...)` — see `./operators.ts`). The trait
+// declaration is regression-pinned by `test/equality-trait-removal.test.ts`.
+//
+// The user-visible `EncryptedString({ equality: true })` flag in PSL
+// / TS authoring is unrelated to this codec trait — it controls
+// whether the codec lifecycle hook contributes a per-column search-
+// config migration op for the column's `unique` index. The two
+// `equality` concepts share only their name.
+const CIPHERSTASH_STRING_TRAITS = [] as const;
+
+/**
+ * Encode the SDK ciphertext payload as a Postgres composite literal
+ * `("...escaped JSON...")`. Embedded `"` are doubled per the composite
+ * text-format escape rules.
+ */
+function encodeEqlV2EncryptedWire(payload: unknown): string {
+  const json = JSON.stringify(payload);
+  if (json === undefined) {
+    throw new Error(
+      'cipherstash codec: ciphertext payload is not JSON-serializable. ' +
+        'The CipherStash SDK must return a JSON-encodable bulk-encrypt result.',
+    );
+  }
+  const escaped = json.replaceAll('"', '""');
+  return `("${escaped}")`;
+}
+
+/**
+ * Inverse of {@link encodeEqlV2EncryptedWire}. Postgres returns
+ * `eql_v2_encrypted` cells in composite text format; some pg clients
+ * pre-parse composite cells into `{ data: ... }` row objects. Both
+ * shapes — and `null`/`undefined` passthrough — are accepted.
+ */
+function decodeEqlV2EncryptedWire(wire: unknown): unknown {
+  if (wire === null || wire === undefined) return wire;
+  if (typeof wire === 'object') {
+    if ('data' in wire) {
+      return (wire as { data: unknown }).data;
+    }
+    return wire;
+  }
+  if (typeof wire !== 'string') {
+    throw new Error(
+      `cipherstash codec: unexpected wire shape for eql_v2_encrypted: ${typeof wire}`,
+    );
+  }
+  const trimmed = wire.trim();
+  if (!trimmed.startsWith('(') || !trimmed.endsWith(')')) {
+    throw new Error(
+      `cipherstash codec: expected composite literal "(...)" but got: ${trimmed.slice(0, 40)}`,
+    );
+  }
+  const inner = trimmed.slice(1, -1);
+  const unquoted =
+    inner.startsWith('"') && inner.endsWith('"') ? inner.slice(1, -1).replaceAll('""', '"') : inner;
+  return JSON.parse(unquoted);
+}
+
+export class CipherstashStringCodec
+  extends CodecImpl<
+    typeof CIPHERSTASH_STRING_CODEC_ID,
+    typeof CIPHERSTASH_STRING_TRAITS,
+    unknown,
+    EncryptedString
+  >
+  implements
+    Codec<
+      typeof CIPHERSTASH_STRING_CODEC_ID,
+      typeof CIPHERSTASH_STRING_TRAITS,
+      unknown,
+      EncryptedString
+    >
+{
+  readonly sdk: CipherstashSdk | undefined;
+
+  constructor(descriptor: AnyCodecDescriptor, sdk: CipherstashSdk | undefined) {
+    super(descriptor);
+    this.sdk = sdk;
+  }
+
+  async encode(value: EncryptedString, _ctx: SqlCodecCallContext): Promise<unknown> {
+    const handle = value.expose();
+    if (handle.ciphertext === undefined) {
+      throw new Error(
+        'cipherstash codec: envelope has no ciphertext at encode time. ' +
+          'Register the bulk-encrypt middleware in the runtime so envelopes are encrypted before encoding.',
+      );
+    }
+    return encodeEqlV2EncryptedWire(handle.ciphertext);
+  }
+
+  async decode(wire: unknown, ctx: SqlCodecCallContext): Promise<EncryptedString> {
+    if (this.sdk === undefined) {
+      throw new Error(
+        'cipherstash codec: decode called on the metadata-only codec instance. ' +
+          'Construct a runtime descriptor via `createCipherstashRuntimeDescriptor({ sdk })` and use that instead.',
+      );
+    }
+    const column = ctx.column;
+    if (!column) {
+      throw new Error(
+        'cipherstash codec: decode requires ctx.column to construct a routing-aware envelope. ' +
+          'The SQL runtime populates ctx.column for projected columns; aggregate/computed cells are not supported by this codec.',
+      );
+    }
+    return EncryptedString.fromInternal({
+      ciphertext: decodeEqlV2EncryptedWire(wire),
+      table: column.table,
+      column: column.name,
+      sdk: this.sdk,
+    });
+  }
+
+  encodeJson(_value: EncryptedString): JsonValue {
+    return { $encryptedString: '<opaque>' };
+  }
+
+  decodeJson(_json: JsonValue): EncryptedString {
+    throw new Error(
+      'cipherstash codec: decodeJson is not supported; envelopes do not round-trip through JSON.',
+    );
+  }
+}
+
+/**
+ * Variance-erased descriptor placeholder used by `createCipherstashStringCodec`
+ * so legacy callers that need a bare `Codec` instance (e.g. extension control-
+ * plane wiring that built up a flat list of codecs) can keep constructing one
+ * directly. Production runtime descriptors should resolve the per-instance
+ * codec through `CipherstashStringDescriptor.factory(params)(ctx)`.
+ */
+const FALLBACK_DESCRIPTOR: AnyCodecDescriptor = {
+  codecId: CIPHERSTASH_STRING_CODEC_ID,
+  traits: CIPHERSTASH_STRING_TRAITS,
+  targetTypes: [CIPHERSTASH_STRING_TARGET_TYPE],
+  meta: {
+    db: { sql: { postgres: { nativeType: CIPHERSTASH_STRING_TARGET_TYPE } } },
+  },
+  paramsSchema: {
+    '~standard': {
+      version: 1,
+      vendor: 'cipherstash',
+      validate: (value: unknown) => ({ value }),
+    },
+  },
+  isParameterized: false,
+  renderOutputType: () => 'EncryptedString',
+  factory: () => () => {
+    throw new Error('cipherstash codec: fallback descriptor factory is not callable');
+  },
+};
+
+export function createCipherstashStringCodec(sdk: CipherstashSdk): CipherstashStringCodec {
+  return new CipherstashStringCodec(FALLBACK_DESCRIPTOR, sdk);
+}
+
+export { CIPHERSTASH_STRING_CODEC_ID };

package/src/execution/decrypt-all.ts

@@ -0,0 +1,217 @@
+/**
+ * `decryptAll` — read-side bulk-decrypt walker.
+ *
+ * Public utility users invoke after `findMany` (or any other read
+ * surface) to materialize the plaintext for every `EncryptedString`
+ * envelope reachable from the result set in a fixed number of bulk SDK
+ * round-trips:
+ *
+ *     const rows = await db.select(...).from(User).execute();
+ *     await decryptAll(rows);
+ *     // every envelope's `decrypt()` now returns plaintext synchronously.
+ *
+ * Why a separate utility (rather than middleware that auto-decrypts on
+ * every read): the framework`s streaming-read path cannot bulk-amortize
+ * decryption across rows it`s yielding incrementally — by the time row
+ * N is yielded, rows 1..N-1 have already been delivered to the caller.
+ * The `decryptAll` shape lets the caller buffer the result set
+ * explicitly (with `await stream.toArray()`) and then opt into bulk
+ * decryption in one round-trip per `(table, column)` group. The runtime
+ * descriptor wrapper deliberately does NOT register an implicit-decrypt
+ * middleware for this reason.
+ *
+ * **Walker shape**.
+ *
+ * - Recursive on plain objects + plain arrays only. Date / Map / Set /
+ *   typed arrays / Buffer / function / etc. are not recursed into:
+ *   cipherstash envelopes are user data and would not normally embed
+ *   inside these host containers; if a future caller needs to bulk-
+ *   decrypt envelopes inside such a container they extract them into a
+ *   plain row first. The narrow scope keeps the walker`s behavior
+ *   trivially predictable and avoids the cycle / iterator / lazy-eval
+ *   surface those exotic types bring.
+ * - Cycle-safe via a `WeakSet` of visited objects/arrays; the same
+ *   envelope appearing in N positions is collected once.
+ * - Skips envelopes whose plaintext slot is already populated
+ *   (write-side envelopes from `EncryptedString.from(plaintext)`, or
+ *   read-side envelopes already materialized by a prior
+ *   `decrypt()` / `decryptAll(...)`). The skip means a re-run is a
+ *   no-op and a mixed write/read row tree only round-trips for the
+ *   envelopes that need it.
+ *
+ * **Grouping**. Envelopes are grouped by `(sdk, table, column)` —
+ * routing key plus the envelope handle`s SDK reference. The SDK split
+ * preserves the per-tenant SDK isolation `runtime.ts`'s docblock spells
+ * out: each tenant constructs its own runtime descriptor with its own
+ * SDK so per-tenant key material never crosses runtimes. Envelopes from
+ * different tenants happening to share `(table, column)` therefore
+ * still receive separate `bulkDecrypt` calls.
+ *
+ * **Cancellation**. `opts.signal` is forwarded by identity to every
+ * `bulkDecrypt` call via `ifDefined` — the same shape the bulk-encrypt
+ * middleware and `EncryptedString.decrypt({ signal? })` use. The
+ * walker also races each SDK promise against `opts.signal` via
+ * `raceCipherstashAbort` so an abort surfaces `RUNTIME.ABORTED
+ * { phase: 'decrypt-all' }` promptly even when the SDK body itself
+ * ignores the signal. A pre-check before the first SDK round-trip
+ * short-circuits when the signal is already aborted at entry; the
+ * no-envelopes-reachable fast path returns immediately without
+ * observing the signal.
+ */
+
+import { ifDefined } from '@prisma-next/utils/defined';
+import { checkCipherstashAborted, raceCipherstashAbort } from './abort';
+import { EncryptedString, isHandleDecrypted, setHandlePlaintextCache } from './envelope';
+import type { CipherstashRoutingKey, CipherstashSdk } from './sdk';
+
+export interface DecryptAllOptions {
+  readonly signal?: AbortSignal;
+}
+
+interface BulkDecryptTarget {
+  readonly envelope: EncryptedString;
+  readonly ciphertext: unknown;
+  readonly sdk: CipherstashSdk;
+  readonly routingKey: CipherstashRoutingKey;
+}
+
+/**
+ * Walk a result set and bulk-decrypt every `EncryptedString` envelope
+ * reachable from it. After the returned promise resolves, every touched
+ * envelope's `decrypt()` returns the cached plaintext synchronously
+ * without consulting the SDK.
+ *
+ * The walker is a no-op when no envelopes are reachable (returns
+ * without making any SDK call), so it is cheap to call defensively
+ * after queries that may or may not contain encrypted columns.
+ */
+export async function decryptAll(rows: unknown, opts?: DecryptAllOptions): Promise<void> {
+  const targets = collectTargets(rows);
+  if (targets.length === 0) {
+    return;
+  }
+  const groups = groupTargets(targets);
+  for (const group of groups.values()) {
+    const first = group[0];
+    if (!first) continue;
+    const ciphertexts = group.map((t) => t.ciphertext);
+    checkCipherstashAborted(opts?.signal, 'decrypt-all');
+    const plaintexts = await raceCipherstashAbort(
+      first.sdk.bulkDecrypt({
+        routingKey: first.routingKey,
+        ciphertexts,
+        ...ifDefined('signal', opts?.signal),
+      }),
+      opts?.signal,
+      'decrypt-all',
+    );
+    if (plaintexts.length !== group.length) {
+      throw new Error(
+        `cipherstash decryptAll: SDK returned ${plaintexts.length} plaintexts ` +
+          `for routing key (${first.routingKey.table}, ${first.routingKey.column}) ` +
+          `but ${group.length} were requested.`,
+      );
+    }
+    for (let i = 0; i < group.length; i++) {
+      const target = group[i];
+      const plaintext = plaintexts[i];
+      if (!target || plaintext === undefined) continue;
+      setHandlePlaintextCache(target.envelope, plaintext);
+    }
+  }
+}
+
+function collectTargets(root: unknown): BulkDecryptTarget[] {
+  const targets: BulkDecryptTarget[] = [];
+  const seenObjects = new WeakSet<object>();
+  const seenEnvelopes = new WeakSet<EncryptedString>();
+  visit(root, seenObjects, (envelope) => {
+    if (seenEnvelopes.has(envelope)) return;
+    seenEnvelopes.add(envelope);
+    if (isHandleDecrypted(envelope)) return;
+    const handle = envelope.expose();
+    if (handle.table === undefined || handle.column === undefined) {
+      throw new Error(
+        'cipherstash decryptAll: envelope is missing (table, column) routing context. ' +
+          'Read-side envelopes constructed via codec.decode always carry routing context; ' +
+          'this typically means the envelope was constructed manually outside the codec path.',
+      );
+    }
+    if (handle.sdk === undefined) {
+      throw new Error(
+        'cipherstash decryptAll: envelope is missing the SDK reference needed to decrypt. ' +
+          'Read-side envelopes constructed via codec.decode always carry an SDK reference; ' +
+          'this typically means the envelope was constructed manually outside the codec path.',
+      );
+    }
+    targets.push({
+      envelope,
+      ciphertext: handle.ciphertext,
+      sdk: handle.sdk,
+      routingKey: { table: handle.table, column: handle.column },
+    });
+  });
+  return targets;
+}
+
+function visit(
+  value: unknown,
+  seen: WeakSet<object>,
+  found: (envelope: EncryptedString) => void,
+): void {
+  if (value === null || value === undefined) return;
+  if (value instanceof EncryptedString) {
+    found(value);
+    return;
+  }
+  if (typeof value !== 'object') return;
+  if (seen.has(value)) return;
+  // Walker is intentionally scoped to plain arrays + plain objects.
+  // Date / Map / Set / typed arrays / Buffer / Error / class instances
+  // are passed over so the walker`s shape stays trivially predictable
+  // and immune to host-object iterator surprises.
+  if (Array.isArray(value)) {
+    seen.add(value);
+    for (const item of value) {
+      visit(item, seen, found);
+    }
+    return;
+  }
+  if (!isPlainObject(value)) {
+    return;
+  }
+  seen.add(value);
+  for (const key of Object.keys(value)) {
+    visit((value as Record<string, unknown>)[key], seen, found);
+  }
+}
+
+function isPlainObject(value: object): boolean {
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype;
+}
+
+function groupTargets(targets: ReadonlyArray<BulkDecryptTarget>): Map<string, BulkDecryptTarget[]> {
+  // Group by `(sdk identity, table, column)`. The SDK identity portion
+  // of the key uses a per-SDK index issued on first encounter so
+  // grouping never depends on object reference equality colliding
+  // accidentally (different SDK instances always partition into
+  // different groups even if their `(table, column)` matches).
+  const sdkIndex = new Map<CipherstashSdk, number>();
+  const groups = new Map<string, BulkDecryptTarget[]>();
+  for (const target of targets) {
+    let idx = sdkIndex.get(target.sdk);
+    if (idx === undefined) {
+      idx = sdkIndex.size;
+      sdkIndex.set(target.sdk, idx);
+    }
+    const id = `${idx}\u0000${target.routingKey.table}\u0000${target.routingKey.column}`;
+    let group = groups.get(id);
+    if (!group) {
+      group = [];
+      groups.set(id, group);
+    }
+    group.push(target);
+  }
+  return groups;
+}

package/src/execution/envelope.ts

@@ -0,0 +1,263 @@
+/**
+ * `EncryptedString` envelope and its package-internal handle helpers.
+ *
+ * The envelope is the user-facing input/output type for cipherstash-
+ * backed columns. It wraps an `EncryptedStringHandle` (plaintext slot,
+ * ciphertext slot, routing key, SDK reference) holding the per-cell
+ * lifecycle state.
+ *
+ * ## Encapsulation pattern (Rust `secrecy` style)
+ *
+ * Storage is a `#private` instance field. The blessed read path is the
+ * explicit `expose()` method — same shape as the Rust `secrecy` crate's
+ * `SecretBox<T>::expose_secret`. Calling `expose()` is a deliberate
+ * opt-in: the caller is announcing "I want the wrapped state". The
+ * envelope does not — and is not meant to — make that *impossible*; it
+ * is meant to make accidental exposure (logger output, error envelopes,
+ * stringification, JSON serialization, primitive coercion) impossible
+ * unless the caller goes through `expose()`.
+ *
+ * Concretely the class overrides every coercion / serialization vector
+ * that would otherwise reveal the handle:
+ *
+ *   - `toJSON()`                                    — `JSON.stringify`
+ *   - `toString()`                                  — `String(envelope)`
+ *   - `valueOf()`                                   — legacy primitive coercion
+ *   - `[Symbol.toPrimitive]()`                      — template literals, `+`
+ *   - `[Symbol.for('nodejs.util.inspect.custom')]()` — `console.log`,
+ *                                                     Node REPL, debuggers
+ *
+ * All five return the same `[REDACTED]` placeholder. Without these
+ * overrides, modern Node runtimes surface `#private` fields in
+ * `util.inspect` output by default, which would silently re-expose
+ * the handle through `console.log(envelope)` (and any error message
+ * that interpolates an envelope).
+ *
+ * ## Lifecycle
+ *
+ * The handle has two flavours:
+ *   - **Write side** — `EncryptedString.from(plaintext)` populates the
+ *     `plaintext` slot and leaves `ciphertext` empty. The bulk-encrypt
+ *     middleware populates `ciphertext` post-SDK and intentionally
+ *     leaves the plaintext slot in place (zeroing JS strings is
+ *     best-effort and GC-driven lifecycle is sufficient here). As a
+ *     side effect a write-side envelope's `decrypt()` returns the
+ *     original plaintext synchronously without an SDK round-trip.
+ *   - **Read side** — `EncryptedString.fromInternal({...})` (called from
+ *     the codec `decode` body) populates `ciphertext`, `(table, column)`
+ *     from `SqlCodecCallContext.column`, and an `sdk` reference so
+ *     `decrypt({signal?})` can issue the SDK's single-cell decrypt.
+ */
+
+import { ifDefined } from '@prisma-next/utils/defined';
+import { checkCipherstashAborted, raceCipherstashAbort } from './abort';
+import type { CipherstashSdk } from './sdk';
+
+/**
+ * The mutable state of an `EncryptedString` — exposed by `expose()` for
+ * callers that explicitly opt in. Mutating these slots from outside the
+ * package is supported (we don't stop you) but unusual; the framework's
+ * own lifecycle mutators (`setHandleCiphertext`, `setHandleRoutingKey`,
+ * etc.) are the conventional path.
+ */
+export interface EncryptedStringHandle {
+  plaintext: string | undefined;
+  ciphertext: unknown;
+  table: string | undefined;
+  column: string | undefined;
+  sdk: CipherstashSdk | undefined;
+}
+
+const REDACTED = '[REDACTED]';
+
+export interface EncryptedStringFromInternalArgs {
+  readonly ciphertext: unknown;
+  readonly table: string;
+  readonly column: string;
+  readonly sdk: CipherstashSdk;
+}
+
+export class EncryptedString {
+  readonly #handle: EncryptedStringHandle;
+
+  private constructor(handle: EncryptedStringHandle) {
+    this.#handle = handle;
+  }
+
+  /**
+   * Construct a write-side envelope from plaintext. Bulk-encrypt
+   * middleware populates the handle's ciphertext slot before the codec
+   * encodes the envelope to wire format.
+   */
+  static from(plaintext: string): EncryptedString {
+    return new EncryptedString({
+      plaintext,
+      ciphertext: undefined,
+      table: undefined,
+      column: undefined,
+      sdk: undefined,
+    });
+  }
+
+  /**
+   * Construct a read-side envelope from a wire ciphertext + the column
+   * identity + the SDK used to decrypt the cell. Called from the codec
+   * `decode` body.
+   */
+  static fromInternal(args: EncryptedStringFromInternalArgs): EncryptedString {
+    return new EncryptedString({
+      plaintext: undefined,
+      ciphertext: args.ciphertext,
+      table: args.table,
+      column: args.column,
+      sdk: args.sdk,
+    });
+  }
+
+  /**
+   * Explicitly retrieve the wrapped handle. Modelled on Rust `secrecy`'s
+   * `SecretBox<T>::expose_secret`: the handle is reachable, but you have
+   * to ask for it by name. Callers reach for `expose()` when they need
+   * to inspect or transport the ciphertext envelope, debug lifecycle
+   * state, or wire ad-hoc tooling around the SDK reference.
+   *
+   * Mutating the returned handle is supported but unusual — the
+   * framework's lifecycle mutators (`setHandleCiphertext`,
+   * `setHandleRoutingKey`, etc.) are the conventional path during
+   * encrypt / decrypt flow.
+   */
+  expose(): EncryptedStringHandle {
+    return this.#handle;
+  }
+
+  /**
+   * Decrypt and return the plaintext.
+   *
+   * - If the handle's `plaintext` slot is already populated (write-side
+   *   envelopes from `from(plaintext)`, or read-side envelopes already
+   *   materialized by `decryptAll(...)` or a prior `decrypt()`), returns
+   *   the cached plaintext synchronously without consulting the SDK.
+   * - Otherwise (read-side handle without a cached plaintext), invokes
+   *   the SDK's single-cell `decrypt` with the handle's routing context.
+   *   The caller-supplied `signal` is forwarded to the SDK by identity
+   *   per the umbrella cancellation contract; the SDK promise is also
+   *   raced against the signal so an abort surfaces a `RUNTIME.ABORTED
+   *   { phase: 'decrypt' }` envelope promptly even if the SDK body
+   *   ignores the signal. The cached-plaintext fast path returns
+   *   synchronously without consulting the signal — no IO, no abort
+   *   observation point.
+   */
+  async decrypt(opts?: { signal?: AbortSignal }): Promise<string> {
+    if (this.#handle.plaintext !== undefined) {
+      return this.#handle.plaintext;
+    }
+    if (
+      !this.#handle.sdk ||
+      this.#handle.table === undefined ||
+      this.#handle.column === undefined
+    ) {
+      throw new Error(
+        'EncryptedString.decrypt(): envelope has no cached plaintext and no SDK binding. ' +
+          'This typically means the bulk-encrypt middleware did not run before the encode site.',
+      );
+    }
+    checkCipherstashAborted(opts?.signal, 'decrypt');
+    const plaintext = await raceCipherstashAbort(
+      this.#handle.sdk.decrypt({
+        ciphertext: this.#handle.ciphertext,
+        table: this.#handle.table,
+        column: this.#handle.column,
+        ...ifDefined('signal', opts?.signal),
+      }),
+      opts?.signal,
+      'decrypt',
+    );
+    this.#handle.plaintext = plaintext;
+    return plaintext;
+  }
+
+  toJSON(): string {
+    return REDACTED;
+  }
+
+  toString(): string {
+    return REDACTED;
+  }
+
+  valueOf(): string {
+    return REDACTED;
+  }
+
+  [Symbol.toPrimitive](): string {
+    return REDACTED;
+  }
+
+  [Symbol.for('nodejs.util.inspect.custom')](): string {
+    return REDACTED;
+  }
+}
+
+/**
+ * Populate the handle's ciphertext slot. Called by the bulk-encrypt
+ * middleware after the SDK returns the encrypted batch.
+ *
+ * The plaintext slot is intentionally retained — zeroing in JS is
+ * best-effort (strings are immutable) and the GC-driven lifecycle is
+ * sufficient.
+ */
+export function setHandleCiphertext(envelope: EncryptedString, ciphertext: unknown): void {
+  envelope.expose().ciphertext = ciphertext;
+}
+
+/**
+ * Populate the handle's plaintext slot with a freshly-decrypted value
+ * (read-side caching path used by `decryptAll` and by `decrypt()`'s own
+ * memoization).
+ */
+export function setHandlePlaintextCache(envelope: EncryptedString, plaintext: string): void {
+  envelope.expose().plaintext = plaintext;
+}
+
+/**
+ * Stamp the encrypt-side `(table, column)` routing context onto a
+ * write-side envelope's handle. Called by the bulk-encrypt middleware
+ * before grouping envelopes into per-routing-key bulk-encrypt batches.
+ *
+ * Idempotent for matching reassignments (re-stamping the same
+ * `(table, column)` is a no-op, which covers envelopes reconstructed
+ * via `fromInternal` on the read side and re-stamped on the way back
+ * in). Conflicting reassignments throw a descriptive error: an
+ * envelope reused across plans with a different routing context is a
+ * programming error — silently keeping the stale binding would lower
+ * to the wrong bulk-encrypt batch.
+ */
+export function setHandleRoutingKey(
+  envelope: EncryptedString,
+  table: string,
+  column: string,
+): void {
+  const handle = envelope.expose();
+  if (handle.table === undefined) {
+    handle.table = table;
+  } else if (handle.table !== table) {
+    throw new Error(
+      `cipherstash envelope: routing-key table conflict — handle already bound to "${handle.table}", refusing to rebind to "${table}". Re-encode the value or construct a fresh envelope for the new routing target.`,
+    );
+  }
+  if (handle.column === undefined) {
+    handle.column = column;
+  } else if (handle.column !== column) {
+    throw new Error(
+      `cipherstash envelope: routing-key column conflict on table "${handle.table}" — handle already bound to "${handle.column}", refusing to rebind to "${column}". Re-encode the value or construct a fresh envelope for the new routing target.`,
+    );
+  }
+}
+
+/**
+ * `true` when the handle already carries a usable plaintext (write-side
+ * construction or post-`decrypt` caching). Used by `decryptAll` to skip
+ * envelopes that don't need a round-trip.
+ */
+export function isHandleDecrypted(envelope: EncryptedString): boolean {
+  return envelope.expose().plaintext !== undefined;
+}