@prisma-next/extension-cipherstash 0.0.1

package/src/middleware/bulk-encrypt.ts

@@ -0,0 +1,192 @@
+/**
+ * Bulk-encrypt middleware for cipherstash envelopes.
+ *
+ * The middleware sits in the SQL runtime's `beforeExecute` chain and:
+ *
+ * 1. Walks the lowered query AST (`InsertAst` / `UpdateAst`) and stamps
+ *    `(table, column)` routing context onto every `EncryptedString`
+ *    envelope embedded in a `ParamRef`. The handle's `(table, column)`
+ *    slots are the canonical input to {@link groupByRoutingKey}; this
+ *    walk is the single place the AST's structural column metadata gets
+ *    attached to the envelopes the SDK will see.
+ *
+ * 2. Iterates `params.entries()` to collect every cipherstash-codec'd
+ *    `ParamRef` whose value is an `EncryptedString`, groups them by
+ *    routing key, and issues exactly one `sdk.bulkEncrypt(...)` call
+ *    per group. Routing-key derivation is `(table, column)` —
+ *    homogeneous batches only.
+ *
+ * 3. Stamps each returned ciphertext onto the envelope's handle via
+ *    `setHandleCiphertext` and writes the envelope back through
+ *    `params.replaceValues` so the runtime's `currentParams()` view
+ *    reflects the post-mutation slot. The handle's `plaintext` slot
+ *    is **retained** — `envelope.decrypt()` continues to return the
+ *    plaintext synchronously without consulting the SDK.
+ *
+ * Cancellation: `ctx.signal` is forwarded by identity to every
+ * `bulkEncrypt` call via `ifDefined`; the SDK is responsible for
+ * honoring it. The awaiting middleware also races the SDK promise
+ * against `ctx.signal` via `raceCipherstashAbort` so a caller-side
+ * abort surfaces a `RUNTIME.ABORTED { phase: 'bulk-encrypt' }`
+ * envelope promptly even when the SDK body itself ignores the signal.
+ * A pre-flight `checkCipherstashAborted` short-circuits before any
+ * SDK round-trip is scheduled when the signal is already aborted at
+ * entry.
+ */
+
+import type {
+  AnyQueryAst,
+  ColumnRef,
+  DefaultValueExpr,
+  InsertAst,
+  ParamRef,
+  UpdateAst,
+} from '@prisma-next/sql-relational-core/ast';
+import type {
+  ParamRefHandle,
+  SqlParamRefMutator,
+} from '@prisma-next/sql-relational-core/middleware';
+import type { SqlMiddleware } from '@prisma-next/sql-runtime';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { checkCipherstashAborted, raceCipherstashAbort } from '../execution/abort';
+import { EncryptedString, setHandleCiphertext, setHandleRoutingKey } from '../execution/envelope';
+import { type BulkEncryptTarget, groupByRoutingKey } from '../execution/routing';
+import type { CipherstashSdk } from '../execution/sdk';
+import { CIPHERSTASH_STRING_CODEC_ID } from '../extension-metadata/constants';
+
+/**
+ * Construct the bulk-encrypt middleware. The returned middleware is
+ * stateless aside from the captured `sdk` reference; one instance per
+ * runtime extension is the expected pattern.
+ */
+export function bulkEncryptMiddleware(sdk: CipherstashSdk): SqlMiddleware {
+  return {
+    name: 'cipherstash.bulk-encrypt',
+    familyId: 'sql',
+    async beforeExecute(plan, ctx, params) {
+      if (!params) {
+        return;
+      }
+
+      stampRoutingKeysFromAst(plan.ast);
+
+      const targets = collectTargets(params);
+      if (targets.length === 0) {
+        return;
+      }
+
+      const groups = groupByRoutingKey(targets);
+      for (const [groupKey, group] of groups) {
+        const first = group[0];
+        if (!first) continue;
+        const routingKey = first.routingKey;
+
+        checkCipherstashAborted(ctx.signal, 'bulk-encrypt');
+        const ciphertexts = await raceCipherstashAbort(
+          sdk.bulkEncrypt({
+            routingKey,
+            values: group.map((t) => t.plaintext),
+            ...ifDefined('signal', ctx.signal),
+          }),
+          ctx.signal,
+          'bulk-encrypt',
+        );
+
+        if (ciphertexts.length !== group.length) {
+          throw new Error(
+            `cipherstash bulk-encrypt: SDK returned ${ciphertexts.length} ciphertexts ` +
+              `for routing key ${groupKey} but ${group.length} were requested.`,
+          );
+        }
+
+        params.replaceValues(
+          group.map((t, i) => {
+            const ciphertext = ciphertexts[i];
+            setHandleCiphertext(t.envelope, ciphertext);
+            return { ref: t.ref, newValue: t.envelope };
+          }),
+        );
+      }
+    },
+  };
+}
+
+function collectTargets(
+  params: SqlParamRefMutator,
+): BulkEncryptTarget<ParamRefHandle<string | undefined>>[] {
+  const targets: BulkEncryptTarget<ParamRefHandle<string | undefined>>[] = [];
+  for (const entry of params.entries()) {
+    if (entry.codecId !== CIPHERSTASH_STRING_CODEC_ID) continue;
+    const value = entry.value;
+    if (!(value instanceof EncryptedString)) continue;
+    const handle = value.expose();
+    if (handle.plaintext === undefined) {
+      throw new Error(
+        'cipherstash bulk-encrypt: encountered an envelope with no plaintext on the write path. ' +
+          'Use `EncryptedString.from(plaintext)` to construct write-side envelopes.',
+      );
+    }
+    if (handle.table === undefined || handle.column === undefined) {
+      throw new Error(
+        'cipherstash bulk-encrypt: envelope reached the bulk-encrypt phase without a (table, column) ' +
+          "routing context. The middleware's AST walk only handles `InsertAst` and `UpdateAst`; " +
+          'cipherstash envelopes embedded in other plan shapes (e.g. raw SQL) must stamp routing ' +
+          'context explicitly via `setHandleRoutingKey` before execute.',
+      );
+    }
+    targets.push({
+      ref: entry.ref,
+      plaintext: handle.plaintext,
+      envelope: value,
+      routingKey: { table: handle.table, column: handle.column },
+    });
+  }
+  return targets;
+}
+
+function stampRoutingKeysFromAst(ast: AnyQueryAst | undefined): void {
+  if (!ast) return;
+  switch (ast.kind) {
+    case 'insert':
+      stampInsert(ast);
+      return;
+    case 'update':
+      stampUpdate(ast);
+      return;
+    default:
+      return;
+  }
+}
+
+function stampInsert(ast: InsertAst): void {
+  const tableName = ast.table.name;
+  for (const row of ast.rows) {
+    for (const [column, value] of Object.entries(row)) {
+      stampParamRefIfEnvelope(value, tableName, column);
+    }
+  }
+  if (ast.onConflict?.action.kind === 'do-update-set') {
+    for (const [column, value] of Object.entries(ast.onConflict.action.set)) {
+      stampParamRefIfEnvelope(value, tableName, column);
+    }
+  }
+}
+
+function stampUpdate(ast: UpdateAst): void {
+  const tableName = ast.table.name;
+  for (const [column, value] of Object.entries(ast.set)) {
+    stampParamRefIfEnvelope(value, tableName, column);
+  }
+}
+
+function stampParamRefIfEnvelope(
+  value: ColumnRef | ParamRef | DefaultValueExpr,
+  table: string,
+  column: string,
+): void {
+  if (value.kind !== 'param-ref') return;
+  const inner = value.value;
+  if (inner instanceof EncryptedString) {
+    setHandleRoutingKey(inner, table, column);
+  }
+}

package/src/migration/call-classes.ts

@@ -0,0 +1,350 @@
+/**
+ * Cipherstash migration IR — renderable `*Call` classes for the codec
+ * lifecycle hook + the public `@prisma-next/extension-cipherstash/migration`
+ * factory functions.
+ *
+ * Each `*Call` implements the framework `OpFactoryCall` interface (ADR
+ * 195) directly, so cipherstash's contributions flow through the postgres
+ * planner as first-class IR nodes — no `RawSqlCall` wrap, no detour
+ * through the unstructured-op fallback. The codec hook
+ * (`./cipherstash-codec.ts`) returns Calls; the postgres planner adds
+ * them to its call list and renders them via `renderCallsToTypeScript`.
+ *
+ * Public factory functions (`cipherstashAddSearchConfig` /
+ * `cipherstashRemoveSearchConfig`) are re-exported from
+ * `@prisma-next/extension-cipherstash/migration`. Users authoring a
+ * hand-written migration can call them directly:
+ *
+ * ```ts
+ * import { cipherstashAddSearchConfig } from '@prisma-next/extension-cipherstash/migration';
+ *
+ * createTable('public', 'user', [...]);
+ * cipherstashAddSearchConfig({ table: 'user', column: 'email', index: 'unique' });
+ * ```
+ *
+ * Round-trip invariant: `toOp()` produces the same op shape the codec
+ * hook would emit directly — `ops.json` stays byte-identical;
+ * `migration.ts` carries a factory call instead of an opaque
+ * `rawSql({...})` block.
+ */
+
+import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control';
+import type {
+  MigrationOperationClass,
+  OpFactoryCall,
+} from '@prisma-next/framework-components/control';
+import { type ImportRequirement, jsonToTsSource, TsExpression } from '@prisma-next/ts-render';
+import { ifDefined } from '@prisma-next/utils/defined';
+
+const CIPHERSTASH_MIGRATION_MODULE = '@prisma-next/extension-cipherstash/migration';
+
+/** Mirrors `eql_v2.add_search_config(table, column, index_name, cast_as)`. */
+const DEFAULT_CAST_AS = 'text';
+
+/**
+ * Two-valued enumeration matching the EQL search-config indices the
+ * cipherstash codec emits — one per enabled flag in
+ * `Encrypted<string>`'s `typeParams`:
+ *
+ *   - `equality: true`        → `'unique'` index
+ *   - `freeTextSearch: true`  → `'match'`  index
+ */
+export type CipherstashSearchIndex = 'unique' | 'match';
+
+/**
+ * Args shape accepted by the public `cipherstashAddSearchConfig` /
+ * `cipherstashRemoveSearchConfig` factory functions.
+ *
+ * `castAs` defaults to `'text'` — matches the cipherstash codec hook's
+ * canonical output and the EQL bundle's expected cast for
+ * `eql_v2_encrypted` columns. Override only if you know the runtime
+ * cast for your column differs.
+ */
+export interface CipherstashSearchConfigArgs {
+  readonly table: string;
+  readonly column: string;
+  readonly index: CipherstashSearchIndex;
+  readonly castAs?: string;
+}
+
+type CipherstashOp = SqlMigrationPlanOperation<unknown>;
+type OpStep = CipherstashOp['execute'][number];
+
+/**
+ * Escape a string so it can be embedded inside a Postgres single-quoted
+ * literal. Identifiers in our IR are unlikely to contain apostrophes,
+ * but doubling them keeps the emitted SQL safe under any future
+ * relaxation.
+ */
+function sqlLiteral(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+function invariantIdFor(
+  tableName: string,
+  fieldName: string,
+  action: 'add-search-config' | 'remove-search-config',
+  indexName: CipherstashSearchIndex,
+): string {
+  return `cipherstash-codec:${tableName}.${fieldName}:${action}:${indexName}@v1`;
+}
+
+/**
+ * Base class for cipherstash migration IR nodes.
+ *
+ * Each instance is *both* an `OpFactoryCall` (renderable to TypeScript,
+ * lowerable to a runtime op via `toOp()`) and a structurally-valid
+ * {@link CipherstashOp} — `id`, `label`, `operationClass`,
+ * `invariantId`, `target`, `precheck`, `execute`, `postcheck` are
+ * stored as enumerable own properties, populated in the concrete
+ * subclass constructors. So when the planner-rendered `migration.ts`
+ * runs and the user's `operations` getter returns Call instances
+ * directly, both `MigrationOpSchema` validation (which checks `id` /
+ * `label` / `operationClass`) and `JSON.stringify` (which writes
+ * `ops.json`) see the runtime op shape unchanged.
+ *
+ * The cipherstash-specific identity fields (`factoryName`, `table`,
+ * `column`, `index`, `castAs`) live on the subclass prototype as
+ * accessor getters and on a per-instance backing record kept in a
+ * private slot (`#args`). Accessor properties on the class are
+ * non-enumerable, and the backing record is a private field, so
+ * `Object.keys(call)` and `canonicalizeJson(...)` see only the op
+ * fields — `ops.json` and `migrationHash` stay byte-stable.
+ */
+abstract class CipherstashOpFactoryCallNode extends TsExpression implements OpFactoryCall {
+  abstract get factoryName(): string;
+  abstract readonly operationClass: MigrationOperationClass;
+  abstract readonly label: string;
+  abstract readonly id: string;
+  abstract readonly invariantId: string;
+  abstract readonly target: { readonly id: string };
+  abstract readonly precheck: readonly OpStep[];
+  abstract readonly execute: readonly OpStep[];
+  abstract readonly postcheck: readonly OpStep[];
+
+  importRequirements(): readonly ImportRequirement[] {
+    return [{ moduleSpecifier: CIPHERSTASH_MIGRATION_MODULE, symbol: this.factoryName }];
+  }
+
+  /**
+   * Re-expose the runtime op view for callers that prefer to lower
+   * Calls explicitly (notably {@link renderOps} on the postgres lane).
+   * The returned object is a plain copy of this Call's op-shaped
+   * fields.
+   */
+  toOp(): CipherstashOp {
+    return {
+      id: this.id,
+      label: this.label,
+      operationClass: this.operationClass,
+      invariantId: this.invariantId,
+      target: this.target,
+      precheck: this.precheck,
+      execute: this.execute,
+      postcheck: this.postcheck,
+    };
+  }
+
+  protected freeze(): void {
+    Object.freeze(this);
+  }
+}
+
+/**
+ * `cipherstashAddSearchConfig` — register an EQL search-config row for
+ * the given column / index combination. Lowers to a `SELECT
+ * eql_v2.add_search_config('<table>', '<column>', '<index>',
+ * '<castAs>')` op, classified `'additive'`.
+ */
+interface AddArgs {
+  readonly table: string;
+  readonly column: string;
+  readonly index: CipherstashSearchIndex;
+  readonly castAs: string;
+}
+
+export class CipherstashAddSearchConfigCall extends CipherstashOpFactoryCallNode {
+  readonly id: string;
+  readonly label: string;
+  readonly operationClass: 'additive';
+  readonly invariantId: string;
+  readonly target: { readonly id: string };
+  readonly precheck: readonly OpStep[];
+  readonly execute: readonly OpStep[];
+  readonly postcheck: readonly OpStep[];
+
+  // Private slot keeps the renderer-side args off the enumerable
+  // own-property surface; the public accessors below expose them
+  // read-only on the prototype, so neither `Object.keys` nor
+  // `canonicalizeJson` walks them.
+  readonly #args: AddArgs;
+
+  constructor(
+    table: string,
+    column: string,
+    index: CipherstashSearchIndex,
+    castAs: string = DEFAULT_CAST_AS,
+  ) {
+    super();
+    this.#args = { table, column, index, castAs };
+    // Property assignment order is fixed (id → label → operationClass
+    // → invariantId → target → precheck → execute → postcheck) so
+    // `JSON.stringify(call)` lays out keys in the byte order the
+    // baseline `ops.json` carries.
+    this.id = `cipherstash-codec.${table}.${column}.add-search-config.${index}`;
+    this.label = `Enable cipherstash search on ${table}.${column}`;
+    this.operationClass = 'additive';
+    this.invariantId = invariantIdFor(table, column, 'add-search-config', index);
+    this.target = { id: 'postgres' };
+    this.precheck = [];
+    this.execute = [
+      {
+        description: `Register cipherstash ${index} search config for ${table}.${column}`,
+        sql: `SELECT eql_v2.add_search_config(${sqlLiteral(table)}, ${sqlLiteral(column)}, ${sqlLiteral(index)}, ${sqlLiteral(castAs)});`,
+      },
+    ];
+    this.postcheck = [];
+    this.freeze();
+  }
+
+  get factoryName(): 'cipherstashAddSearchConfig' {
+    return 'cipherstashAddSearchConfig';
+  }
+
+  get table(): string {
+    return this.#args.table;
+  }
+
+  get column(): string {
+    return this.#args.column;
+  }
+
+  get index(): CipherstashSearchIndex {
+    return this.#args.index;
+  }
+
+  get castAs(): string {
+    return this.#args.castAs;
+  }
+
+  renderTypeScript(): string {
+    const args = {
+      table: this.#args.table,
+      column: this.#args.column,
+      index: this.#args.index,
+      ...ifDefined('castAs', this.#args.castAs !== DEFAULT_CAST_AS ? this.#args.castAs : undefined),
+    };
+    return `cipherstashAddSearchConfig(${jsonToTsSource(args)})`;
+  }
+}
+
+/**
+ * `cipherstashRemoveSearchConfig` — invert
+ * {@link CipherstashAddSearchConfigCall} for the same (table, column,
+ * index) tuple. Lowers to `SELECT eql_v2.remove_search_config('<table>',
+ * '<column>', '<index>')`, classified `'destructive'`.
+ *
+ * No `castAs` argument — `eql_v2.remove_search_config` takes only the
+ * three identifying fields; the cast was applied at the index's add
+ * site.
+ */
+interface RemoveArgs {
+  readonly table: string;
+  readonly column: string;
+  readonly index: CipherstashSearchIndex;
+}
+
+export class CipherstashRemoveSearchConfigCall extends CipherstashOpFactoryCallNode {
+  readonly id: string;
+  readonly label: string;
+  readonly operationClass: 'destructive';
+  readonly invariantId: string;
+  readonly target: { readonly id: string };
+  readonly precheck: readonly OpStep[];
+  readonly execute: readonly OpStep[];
+  readonly postcheck: readonly OpStep[];
+
+  readonly #args: RemoveArgs;
+
+  constructor(table: string, column: string, index: CipherstashSearchIndex) {
+    super();
+    this.#args = { table, column, index };
+    this.id = `cipherstash-codec.${table}.${column}.remove-search-config.${index}`;
+    this.label = `Disable cipherstash search on ${table}.${column}`;
+    this.operationClass = 'destructive';
+    this.invariantId = invariantIdFor(table, column, 'remove-search-config', index);
+    this.target = { id: 'postgres' };
+    this.precheck = [];
+    this.execute = [
+      {
+        description: `Remove cipherstash ${index} search config for ${table}.${column}`,
+        sql: `SELECT eql_v2.remove_search_config(${sqlLiteral(table)}, ${sqlLiteral(column)}, ${sqlLiteral(index)});`,
+      },
+    ];
+    this.postcheck = [];
+    this.freeze();
+  }
+
+  get factoryName(): 'cipherstashRemoveSearchConfig' {
+    return 'cipherstashRemoveSearchConfig';
+  }
+
+  get table(): string {
+    return this.#args.table;
+  }
+
+  get column(): string {
+    return this.#args.column;
+  }
+
+  get index(): CipherstashSearchIndex {
+    return this.#args.index;
+  }
+
+  renderTypeScript(): string {
+    return `cipherstashRemoveSearchConfig(${jsonToTsSource({
+      table: this.#args.table,
+      column: this.#args.column,
+      index: this.#args.index,
+    })})`;
+  }
+}
+
+/**
+ * Public factory: register a cipherstash search-config row.
+ *
+ * Use from a hand-written migration when you need to wire EQL
+ * search-config alongside a `createTable` / `addColumn`. The
+ * `Encrypted<string>` codec hook calls this factory automatically when
+ * planning a contract diff that adds a `searchable: true` column.
+ *
+ * Returns the {@link CipherstashAddSearchConfigCall} IR node, which
+ * implements `OpFactoryCall` and is itself a `SqlMigrationPlanOperation`
+ * (its readonly op-shaped fields are populated in the constructor) — so
+ * the same value flows through both the renderer (planner-time IR) and
+ * the runtime ops list (`Migration.operations`) without an extra
+ * lowering step at the call site.
+ */
+export function cipherstashAddSearchConfig(
+  args: CipherstashSearchConfigArgs,
+): CipherstashAddSearchConfigCall {
+  return new CipherstashAddSearchConfigCall(
+    args.table,
+    args.column,
+    args.index,
+    args.castAs ?? DEFAULT_CAST_AS,
+  );
+}
+
+/**
+ * Public factory: invert {@link cipherstashAddSearchConfig} for the
+ * same (table, column, index) tuple.
+ *
+ * Returns the {@link CipherstashRemoveSearchConfigCall} IR node — see
+ * {@link cipherstashAddSearchConfig} for the rationale.
+ */
+export function cipherstashRemoveSearchConfig(
+  args: CipherstashSearchConfigArgs,
+): CipherstashRemoveSearchConfigCall {
+  return new CipherstashRemoveSearchConfigCall(args.table, args.column, args.index);
+}

package/src/migration/cipherstash-codec.ts

@@ -0,0 +1,157 @@
+/**
+ * Control hooks for the `cipherstash:string@1` codec.
+ *
+ * Implements `CodecControlHooks.onFieldEvent`. Reacts to per-field
+ * added / dropped / altered events as the *application* emitter diffs
+ * the prior contract against the new contract; the returned Calls flow
+ * through the SQL planner's IR alongside structural DDL and render as
+ * `cipherstashAddSearchConfig({...})` / `cipherstashRemoveSearchConfig({...})`
+ * calls in the user's `migration.ts` (ADR 195 two-renderer pattern).
+ *
+ * Trigger: a field uses the `cipherstash:string@1` codec. The planner
+ * already dispatches per `(table, field)` based on the field's
+ * `codecId` (new field for `'added'` / `'altered'`, prior field for
+ * `'dropped'`), so this hook only fires when a cipherstash field is
+ * involved. Per field the hook emits **one
+ * `cipherstashAddSearchConfig` Call per enabled flag** in `typeParams`
+ * (and one `cipherstashRemoveSearchConfig` Call per previously-enabled
+ * flag on drop / altered-off).
+ *
+ * Flag → EQL index mapping:
+ *
+ *   - `equality: true`        → `'unique'` index
+ *   - `freeTextSearch: true`  → `'match'`  index
+ *
+ * One Call per flag (rather than a single multi-statement Call per
+ * field) keeps each Call independently invertible by a paired
+ * `cipherstashRemoveSearchConfig` Call carrying the same index name,
+ * and the op-graph stays per-flag granular for diffing.
+ *
+ * `'altered'` events decompose into per-flag deltas:
+ *   - flag flipped on  → emit `cipherstashAddSearchConfig({...})`.
+ *   - flag flipped off → emit `cipherstashRemoveSearchConfig({...})`.
+ *   - flag unchanged   → no Call.
+ *
+ * `invariantId` template (carried on the Call's `toOp()` output):
+ *   `cipherstash-codec:<table>.<field>:<action>:<index>@v1`
+ *   `<action>` ∈ `'add-search-config' | 'remove-search-config'`,
+ *   `<index>` ∈ `'unique' | 'match'`.
+ * Stable across regenerations because every input is deterministic.
+ */
+
+import type { CodecControlHooks, FieldEventContext } from '@prisma-next/family-sql/control';
+import type { OpFactoryCall } from '@prisma-next/framework-components/control';
+import { CIPHERSTASH_STRING_CODEC_ID } from '../extension-metadata/constants';
+import {
+  type CipherstashSearchIndex,
+  cipherstashAddSearchConfig,
+  cipherstashRemoveSearchConfig,
+} from './call-classes';
+
+type FlagName = 'equality' | 'freeTextSearch';
+
+const FLAG_TO_INDEX: Readonly<Record<FlagName, CipherstashSearchIndex>> = {
+  equality: 'unique',
+  freeTextSearch: 'match',
+};
+
+const ALL_FLAGS: ReadonlyArray<FlagName> = ['equality', 'freeTextSearch'];
+
+function isEnabled(
+  typeParams: Readonly<Record<string, unknown>> | undefined,
+  flag: FlagName,
+): boolean {
+  return typeParams !== undefined && typeParams[flag] === true;
+}
+
+/**
+ * Hook entry point. Called by `planFieldEventOperations` for every per-
+ * field delta dispatched to `cipherstash:string@1`. Pure and
+ * synchronous; callers replay it deterministically when re-emitting.
+ */
+function onFieldEvent(
+  event: 'added' | 'dropped' | 'altered',
+  ctx: FieldEventContext,
+): readonly OpFactoryCall[] {
+  const { tableName, fieldName, priorField, newField } = ctx;
+
+  if (event === 'added') {
+    if (newField === undefined) return [];
+    const calls: OpFactoryCall[] = [];
+    for (const flag of ALL_FLAGS) {
+      if (isEnabled(newField.typeParams, flag)) {
+        calls.push(
+          cipherstashAddSearchConfig({
+            table: tableName,
+            column: fieldName,
+            index: FLAG_TO_INDEX[flag],
+          }),
+        );
+      }
+    }
+    return calls;
+  }
+
+  if (event === 'dropped') {
+    if (priorField === undefined) return [];
+    const calls: OpFactoryCall[] = [];
+    for (const flag of ALL_FLAGS) {
+      if (isEnabled(priorField.typeParams, flag)) {
+        calls.push(
+          cipherstashRemoveSearchConfig({
+            table: tableName,
+            column: fieldName,
+            index: FLAG_TO_INDEX[flag],
+          }),
+        );
+      }
+    }
+    return calls;
+  }
+
+  if (priorField === undefined || newField === undefined) return [];
+  const calls: OpFactoryCall[] = [];
+  for (const flag of ALL_FLAGS) {
+    const before = isEnabled(priorField.typeParams, flag);
+    const after = isEnabled(newField.typeParams, flag);
+    if (after && !before) {
+      calls.push(
+        cipherstashAddSearchConfig({
+          table: tableName,
+          column: fieldName,
+          index: FLAG_TO_INDEX[flag],
+        }),
+      );
+    } else if (before && !after) {
+      calls.push(
+        cipherstashRemoveSearchConfig({
+          table: tableName,
+          column: fieldName,
+          index: FLAG_TO_INDEX[flag],
+        }),
+      );
+    }
+  }
+  return calls;
+}
+
+/**
+ * The DDL type for an `Encrypted<string>` column is always
+ * `eql_v2_encrypted` regardless of any `typeParams` flags: the
+ * search-config wiring is delivered by the codec hook's
+ * `cipherstashAddSearchConfig` Calls (separate rows in
+ * `eql_v2_configuration`), not by the column type itself. Returning
+ * `nativeType` unchanged tells the planner "no expansion required" —
+ * see `expandParameterizedTypeSql` in
+ * `packages/3-targets/3-targets/postgres/src/core/migrations/planner-ddl-builders.ts`,
+ * which only requires this hook to *exist* for any column carrying
+ * `typeParams`. Without it, the planner refuses to render the column
+ * (the existing arktype-json extension wires the same identity hook).
+ */
+const expandNativeType: NonNullable<CodecControlHooks['expandNativeType']> = ({ nativeType }) =>
+  nativeType;
+
+export const cipherstashStringCodecHooks: CodecControlHooks = { onFieldEvent, expandNativeType };
+
+/** Re-export the codec id alongside the hooks so wiring sites import them together. */
+export { CIPHERSTASH_STRING_CODEC_ID };