@proteinjs/db 1.35.1 → 1.36.0

package/src/encryption/EncryptedColumns.ts

@@ -0,0 +1,318 @@
+import { isInstanceOf } from '@proteinjs/util';
+import { Column, EncryptedColumnConfig, Table } from '../Table';
+import { Record, withRecordColumns } from '../Record';
+import {
+  DynamicReferenceColumn,
+  DynamicReferenceTableNameColumn,
+  ObjectColumn,
+  ReferenceArrayColumn,
+  ReferenceColumn,
+  StringColumn,
+  UuidColumn,
+} from '../Columns';
+import { EncryptedColumnConfigError } from './DbEncryptionConfig';
+import { EncryptionDerivedTableRegistry } from './EncryptionDerivedTableRegistry';
+
+/** One search-token row: a keyed fingerprint of one token of one encrypted column value. */
+export interface EncryptionSearchToken extends Record {
+  recordId: string;
+  columnName: string;
+  token: string;
+}
+
+/**
+ * The schema side of column encryption (`ColumnOptions.encrypted`): validation of the
+ * declaration, and derivation of the physical schema an encrypted column needs —
+ * automatically, at the framework seam, never by callers:
+ *
+ * - the ciphertext column itself widens to STRING(MAX) (envelopes outgrow declared widths);
+ * - `searchable: 'equality'` derives an indexed whole-value fingerprint companion column
+ *   (`<column>_enc_eq`); a `unique` declaration on the base column moves onto it (per-owner
+ *   value uniqueness — fingerprints are keyed per owner);
+ * - `searchable: 'contains'` derives a companion search-token TABLE (`<table>_enc_tok`) —
+ *   a plain indexed inverted index, portable across drivers (Spanner's native search
+ *   indexes are a named later optimization at the driver layer);
+ * - `sortKey: { revealPrefix: N }` derives an ordered-prefix companion column
+ *   (`<column>_enc_srt`) for native ORDER BY — the declared bounded reveal.
+ *
+ * `ensureSchema` is idempotent and runs wherever the physical schema is consulted
+ * (TableManager, the record serializer, the query translator).
+ */
+export class EncryptedColumns {
+  private static readonly SCHEMA_APPLIED_MARKER = '__encSchemaApplied';
+  private static readonly INTERNAL_COLUMN_MARKER = '__encInternalColumn';
+
+  /** Validate declarations and inject the derived physical schema (idempotent). */
+  ensureSchema(table: Table<any>): void {
+    if ((table as any)[EncryptedColumns.SCHEMA_APPLIED_MARKER]) {
+      return;
+    }
+
+    let hasContainsColumns = false;
+    for (const prop of Object.keys(table.columns)) {
+      const column = (table.columns as any)[prop] as Column<any, any>;
+      const config = this.validateDeclaration(table, prop, column);
+      if (!config) {
+        continue;
+      }
+
+      if (typeof (column as any).maxLength !== 'undefined') {
+        // Envelopes outgrow the declared plaintext width; the physical column is MAX.
+        (column as any).maxLength = 'MAX';
+      }
+
+      if (config.searchable === 'equality') {
+        this.injectEqualityCompanion(table, prop, column);
+      }
+      if (config.searchable === 'contains') {
+        hasContainsColumns = true;
+      }
+      if (config.sortKey) {
+        this.injectSortCompanion(table, prop, column, config.sortKey.revealPrefix);
+      }
+
+      // The column's QUERY-side contract (`Column.queryTransform` — the parallel of the
+      // storage-side serialize/deserialize seam), DERIVED from the declaration at this
+      // framework seam, never caller-declared. `QueryBuilder.applyColumnTransforms`
+      // consults it on every query. Call-time require: the transform pulls the key-store
+      // stack, which sits beside Db in the module graph.
+      column.queryTransform = (runtime) => {
+        const { EncryptedColumnQueryTransform } =
+          // eslint-disable-next-line @typescript-eslint/no-var-requires
+          require('./EncryptedColumnQueryTransform') as typeof import('./EncryptedColumnQueryTransform');
+        return new EncryptedColumnQueryTransform(table, prop, column, config, runtime);
+      };
+    }
+
+    if (hasContainsColumns) {
+      EncryptionDerivedTableRegistry.register(this.tokenTableShape(table));
+    }
+
+    // Marked only after full success: a validation throw above must re-validate (and
+    // re-throw, loudly) on every subsequent use, never half-apply.
+    (table as any)[EncryptedColumns.SCHEMA_APPLIED_MARKER] = true;
+  }
+
+  /**
+   * The mandatory-declaration gate (`DbEncryptionConfig.requireEncryptedDeclarations`):
+   * every text-holding column must declare `encrypted` (`false` or a config object), so no
+   * column can be added without deciding, and the encrypted set can never silently drift.
+   * Identifier-bearing column classes (uuids, references) are metadata by construction and
+   * are exempt.
+   */
+  validateDeclarations(table: Table<any>): void {
+    const undeclared: string[] = [];
+    for (const prop of Object.keys(table.columns)) {
+      const column = (table.columns as any)[prop] as Column<any, any>;
+      if (!this.isTextColumn(column) || this.isInternalColumn(column)) {
+        continue;
+      }
+
+      if (typeof column.options?.encrypted === 'undefined') {
+        undeclared.push(`${prop} ('${column.name}')`);
+      }
+    }
+
+    if (undeclared.length > 0) {
+      throw new EncryptedColumnConfigError(
+        `(${table.name}) Every text-holding column must declare 'encrypted' (false, or a config ` +
+          `object such as {} or { searchable: 'contains' }). Missing declarations: ${undeclared.join(', ')}`
+      );
+    }
+  }
+
+  /** The `encrypted` config object for a column property, or undefined when not encrypted. */
+  configFor(table: Table<any>, prop: string): EncryptedColumnConfig | undefined {
+    const column = (table.columns as any)[prop] as Column<any, any> | undefined;
+    const encrypted = column?.options?.encrypted;
+    return encrypted && typeof encrypted === 'object' ? encrypted : undefined;
+  }
+
+  /** Property names of this table's encrypted columns. */
+  encryptedProps(table: Table<any>): string[] {
+    return Object.keys(table.columns).filter((prop) => !!this.configFor(table, prop));
+  }
+
+  /** Property names declared `searchable: 'contains'`. */
+  containsProps(table: Table<any>): string[] {
+    return this.encryptedProps(table).filter((prop) => this.configFor(table, prop)!.searchable === 'contains');
+  }
+
+  /** Does this write payload touch any encrypted column? */
+  recordTouchesEncryptedColumns(table: Table<any>, record: any): boolean {
+    return this.encryptedProps(table).some((prop) => typeof record[prop] !== 'undefined');
+  }
+
+  hasEncryptedColumns(table: Table<any>): boolean {
+    return this.encryptedProps(table).length > 0;
+  }
+
+  /** The derived search-token table for `table`, or undefined when nothing is `contains`-searchable. */
+  tokenTableFor(table: Table<any>): Table<EncryptionSearchToken> | undefined {
+    this.ensureSchema(table);
+    return EncryptionDerivedTableRegistry.get(this.tokenTableName(table)) as Table<EncryptionSearchToken> | undefined;
+  }
+
+  tokenTableName(table: Table<any>): string {
+    return `${table.name}_enc_tok`;
+  }
+
+  /** Companion property names EQUAL their column names (several seams assume prop == name). */
+  eqCompanionProp(table: Table<any>, prop: string): string {
+    return `${((table.columns as any)[prop] as { name: string }).name}_enc_eq`;
+  }
+
+  sortCompanionProp(table: Table<any>, prop: string): string {
+    return `${((table.columns as any)[prop] as { name: string }).name}_enc_srt`;
+  }
+
+  /** Framework-derived companion columns are dropped from deserialized records and exempt from declaration checks. */
+  isInternalColumn(column: Column<any, any>): boolean {
+    return !!(column as any)[EncryptedColumns.INTERNAL_COLUMN_MARKER];
+  }
+
+  private validateDeclaration(
+    table: Table<any>,
+    prop: string,
+    column: Column<any, any>
+  ): EncryptedColumnConfig | undefined {
+    const encrypted = column.options?.encrypted;
+    if (typeof encrypted === 'undefined' || encrypted === false) {
+      return undefined;
+    }
+
+    if (typeof encrypted !== 'object') {
+      throw new EncryptedColumnConfigError(
+        `(${table.name}.${prop}) 'encrypted' must be false or a config object ` +
+          `(e.g. {}, { searchable: 'contains' }); got: ${JSON.stringify(encrypted)}`
+      );
+    }
+
+    if (!this.isTextColumn(column)) {
+      throw new EncryptedColumnConfigError(
+        `(${table.name}.${prop}) 'encrypted' is only supported on text columns (StringColumn family). ` +
+          `Identifier and reference columns are metadata by construction; JSON-typed columns must use a ` +
+          `string-serialized column type to encrypt.`
+      );
+    }
+
+    if (encrypted.searchable && encrypted.searchable !== 'contains' && encrypted.searchable !== 'equality') {
+      throw new EncryptedColumnConfigError(
+        `(${table.name}.${prop}) encrypted.searchable must be 'contains' or 'equality'; ` +
+          `got: ${JSON.stringify(encrypted.searchable)}`
+      );
+    }
+
+    if ((encrypted.searchable || encrypted.sortKey) && isInstanceOf(column, ObjectColumn)) {
+      throw new EncryptedColumnConfigError(
+        `(${table.name}.${prop}) encrypted.searchable / encrypted.sortKey require a plain string column ` +
+          `(the search and sort derivatives cover the value's text, not its serialization). ` +
+          `Object/array columns may declare encrypted: {} (encrypted, never queried by value).`
+      );
+    }
+
+    if (encrypted.sortKey) {
+      const revealPrefix = encrypted.sortKey.revealPrefix;
+      if (!Number.isInteger(revealPrefix) || revealPrefix < 1) {
+        throw new EncryptedColumnConfigError(
+          `(${table.name}.${prop}) encrypted.sortKey.revealPrefix must be a positive integer ` +
+            `(the number of leading characters whose order the sort column reveals); ` +
+            `got: ${JSON.stringify(revealPrefix)}`
+        );
+      }
+    }
+
+    if (column.options?.unique?.unique && encrypted.searchable !== 'equality') {
+      throw new EncryptedColumnConfigError(
+        `(${table.name}.${prop}) a unique constraint on an encrypted column requires ` +
+          `encrypted: { searchable: 'equality' } — uniqueness is enforced through a unique index on ` +
+          `the whole-value fingerprint (ciphertext is never equal, so a unique index on it cannot bite).`
+      );
+    }
+
+    return encrypted;
+  }
+
+  private injectEqualityCompanion(table: Table<any>, prop: string, column: Column<any, any>): void {
+    const companionProp = `${column.name}_enc_eq`;
+    const baseUnique = column.options?.unique?.unique === true;
+    const companion = new StringColumn(
+      `${column.name}_enc_eq`,
+      {
+        nullable: true,
+        ...(baseUnique ? { unique: { unique: true, indexName: `${table.name}_${column.name}_enc_eq_unique` } } : {}),
+        ui: { hidden: true },
+      },
+      64
+    );
+    this.injectCompanionColumn(table, companionProp, companion);
+    if (baseUnique) {
+      // Uniqueness moves to the fingerprint column (see validateDeclaration).
+      delete column.options!.unique;
+    } else {
+      table.indexes.push({
+        columns: [companionProp],
+        name: `${table.name}_${column.name}_enc_eq_idx`,
+      });
+    }
+  }
+
+  private injectSortCompanion(table: Table<any>, prop: string, column: Column<any, any>, revealPrefix: number): void {
+    const companion = new StringColumn(
+      `${column.name}_enc_srt`,
+      { nullable: true, ui: { hidden: true } },
+      Math.max(revealPrefix, 1)
+    );
+    this.injectCompanionColumn(table, `${column.name}_enc_srt`, companion);
+  }
+
+  private injectCompanionColumn(table: Table<any>, companionProp: string, companion: Column<any, any>): void {
+    if ((table.columns as any)[companionProp] && !this.isInternalColumn((table.columns as any)[companionProp])) {
+      throw new EncryptedColumnConfigError(
+        `(${table.name}) Column property '${companionProp}' collides with a framework-derived ` +
+          `encryption companion column. Rename the declared column.`
+      );
+    }
+
+    (companion as any)[EncryptedColumns.INTERNAL_COLUMN_MARKER] = true;
+    (table.columns as any)[companionProp] = companion;
+  }
+
+  /**
+   * The token table's SHAPE for `table`, independent of registration — the lifecycle
+   * walker's decrypt-out sweep needs it after the config stopped declaring any
+   * `searchable: 'contains'` column (when `tokenTableFor` no longer resolves).
+   */
+  tokenTableShape(table: Table<any>): Table<EncryptionSearchToken> {
+    const tokenTableName = this.tokenTableName(table);
+    const tokenTable = new (class extends Table<EncryptionSearchToken> {
+      public name = tokenTableName;
+      public columns: Table<EncryptionSearchToken>['columns'] = withRecordColumns<EncryptionSearchToken>({
+        recordId: new StringColumn('record_id', { nullable: false }, 36),
+        columnName: new StringColumn('column_name', { nullable: false }, 128),
+        token: new StringColumn('token', { nullable: false }, 64),
+      });
+      public indexes: { columns: (keyof EncryptionSearchToken)[]; name?: string; unique?: boolean }[] = [
+        { columns: ['token', 'columnName'], name: `${tokenTableName}_cover_idx` },
+        { columns: ['recordId'], name: `${tokenTableName}_record_idx` },
+      ];
+      // No auth block: default-deny for non-system callers; only framework system paths
+      // (EncryptionTokenMaintenance, the query translator's subqueries) touch token rows.
+    })();
+    return tokenTable;
+  }
+
+  private isTextColumn(column: Column<any, any>): boolean {
+    if (!isInstanceOf(column, StringColumn)) {
+      return false;
+    }
+
+    return !(
+      isInstanceOf(column, UuidColumn) ||
+      isInstanceOf(column, ReferenceColumn) ||
+      isInstanceOf(column, ReferenceArrayColumn) ||
+      isInstanceOf(column, DynamicReferenceColumn) ||
+      isInstanceOf(column, DynamicReferenceTableNameColumn)
+    );
+  }
+}

package/src/encryption/EncryptionDerivedTableRegistry.ts

@@ -0,0 +1,34 @@
+import type { Table } from '../Table';
+
+/**
+ * Registry of framework-DERIVED tables (search-token tables beside encrypted-searchable
+ * columns — see `EncryptedColumns`). Derived tables are synthesized from column config, not
+ * declared in source, so the reflection-backed table registry never sees them; `tableByName`
+ * consults this registry after the source registry misses.
+ *
+ * Lives on the global object so every live copy of this package (per-package installs)
+ * shares one registry — same pattern as `Db.getDefaultDbDriver`.
+ *
+ * Deliberately import-cycle-free: `Table` is a type-only import (erased at runtime), so
+ * `Table.ts` can import this module without closing a load-order loop.
+ */
+export class EncryptionDerivedTableRegistry {
+  private static readonly GLOBAL_KEY = '__proteinjs_db_encryptionDerivedTables';
+
+  static get(tableName: string): Table<any> | undefined {
+    return EncryptionDerivedTableRegistry.tables().get(tableName);
+  }
+
+  static register(table: Table<any>): void {
+    EncryptionDerivedTableRegistry.tables().set(table.name, table);
+  }
+
+  private static tables(): Map<string, Table<any>> {
+    const globalObject = globalThis as any;
+    if (!globalObject[EncryptionDerivedTableRegistry.GLOBAL_KEY]) {
+      globalObject[EncryptionDerivedTableRegistry.GLOBAL_KEY] = new Map<string, Table<any>>();
+    }
+
+    return globalObject[EncryptionDerivedTableRegistry.GLOBAL_KEY];
+  }
+}

package/src/encryption/EncryptionEnvelope.ts

@@ -0,0 +1,60 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';
+import { Base64Url } from './Base64Url';
+import type { DataKeyMaterial } from './DataKeyStore';
+
+/**
+ * The self-describing ciphertext envelope an encrypted column stores:
+ *
+ *   `pjenc:1:<ownerId>:<keyVersion>:<base64url(iv || authTag || ciphertext)>`
+ *
+ * Decrypt resolves the key FROM the envelope (owner + version), never from who is asking —
+ * a shared row decrypts for whoever the permission layer admits, and key rotation is a
+ * background rewrite. Cipher: AES-256-GCM (12-byte IV, 16-byte tag), the data key's cipher
+ * half (`DataKeyMaterial.cipherKey`).
+ */
+export class EncryptionEnvelope {
+  static readonly PREFIX = 'pjenc:1:';
+  private static readonly ENVELOPE_PATTERN = /^pjenc:1:([^:]+):(\d+):([A-Za-z0-9_-]+)$/;
+
+  encrypt(plaintext: string, key: DataKeyMaterial): string {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key.cipherKey, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    const payload = Base64Url.encode(Buffer.concat([iv, authTag, ciphertext]));
+    return `${EncryptionEnvelope.PREFIX}${key.owner}:${key.version}:${payload}`;
+  }
+
+  decrypt(envelope: string, key: DataKeyMaterial): string {
+    const parsed = this.parse(envelope);
+    if (!parsed) {
+      throw new Error(`Value is not a ciphertext envelope`);
+    }
+
+    const bytes = Base64Url.decode(parsed.payload);
+    const iv = bytes.subarray(0, 12);
+    const authTag = bytes.subarray(12, 28);
+    const ciphertext = bytes.subarray(28);
+    const decipher = createDecipheriv('aes-256-gcm', key.cipherKey, iv);
+    decipher.setAuthTag(authTag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+  }
+
+  /** Owner + version + payload when `value` is an envelope, else undefined. */
+  parse(value: unknown): { owner: string; version: number; payload: string } | undefined {
+    if (typeof value !== 'string') {
+      return undefined;
+    }
+
+    const match = EncryptionEnvelope.ENVELOPE_PATTERN.exec(value);
+    if (!match) {
+      return undefined;
+    }
+
+    return { owner: match[1], version: parseInt(match[2], 10), payload: match[3] };
+  }
+
+  isEnvelope(value: unknown): boolean {
+    return this.parse(value) !== undefined;
+  }
+}

package/src/encryption/EncryptionLifecycleWalker.ts

@@ -0,0 +1,243 @@
+import { QueryBuilder } from '@proteinjs/db-query';
+import { Logger } from '@proteinjs/logger';
+import type { Table } from '../Table';
+import { EncryptedColumns } from './EncryptedColumns';
+import { EncryptionEnvelope } from './EncryptionEnvelope';
+import { DataKeyStore } from './DataKeyStore';
+
+/**
+ * The config-lifecycle transitions, all riding this one walker:
+ * - `encrypt` — plaintext → `encrypted: {...}` adoption: rewrite rows whose stored value is
+ *   not yet an envelope (also how the initial adoption wave lands).
+ * - `retokenize` — a `searchable`/`sortKey` capability added later: rewrite every non-null
+ *   value so the write seam derives the new companions/tokens.
+ * - `decrypt` — `encrypted` → `false` (a deliberate, reviewed reclassification): rewrite
+ *   rows whose stored value is still an envelope; pass the affected columns explicitly
+ *   (the config no longer marks them). Stale token rows are swept.
+ * - `rotate-keys` — after `DataKeyStore.rotateKey`: rewrite rows whose envelope names an
+ *   older version (plaintext stragglers are encrypted too), then the caller retires the old
+ *   version.
+ */
+export type EncryptionWalkMode = 'encrypt' | 'retokenize' | 'decrypt' | 'rotate-keys';
+
+export interface EncryptionWalkSummary {
+  scanned: number;
+  rewritten: number;
+}
+
+export interface EncryptionWalkOptions {
+  /**
+   * Column property names to walk. Required for mode 'decrypt' (the config no longer marks
+   * the columns); defaults to every encrypted-declared column otherwise.
+   */
+  columns?: string[];
+  /** Resume after this row id (the walk is id-ordered; re-running from the start is also safe — done rows are skipped). */
+  startAfterId?: string;
+  windowSize?: number;
+  /** The driver to scan with; defaults to the process's default driver. */
+  dbDriver?: import('../Db').DbDriver;
+  /** The Db to rewrite through (must be a SYSTEM db); defaults to `getDbAsSystem()`. */
+  db?: import('../Db').Db<any>;
+}
+
+/**
+ * The reusable ONLINE backfill behind every encrypted-column config transition (and key
+ * rotation) — the migration-runner pattern: a server-side, id-ordered, windowed table walk
+ * that rewrites pending rows THROUGH the normal write seam (so encryption, companions, and
+ * search tokens all derive exactly as a live write would).
+ *
+ * Idempotent and resumable by construction: pending-ness is detected from the stored value
+ * itself (envelope or not, version current or not), so a re-run — after a crash, or just to
+ * be sure — skips completed rows and continues. Rows written by live traffic mid-walk are
+ * already in the new shape and skip too. Run it from a `Migration.run()` for deploy-coupled
+ * transitions.
+ */
+export class EncryptionLifecycleWalker {
+  private static readonly DEFAULT_WINDOW_SIZE = 200;
+  private logger = new Logger({ name: this.constructor.name });
+  private encryptedColumns = new EncryptedColumns();
+  private envelope = new EncryptionEnvelope();
+
+  async walkTable(
+    table: Table<any>,
+    mode: EncryptionWalkMode,
+    options: EncryptionWalkOptions = {}
+  ): Promise<EncryptionWalkSummary> {
+    this.encryptedColumns.ensureSchema(table);
+    const props = this.resolveProps(table, mode, options);
+    const { Db, getDbAsSystem } = await import('../Db');
+    const dbDriver = options.dbDriver ?? Db.getDefaultDbDriver();
+    const db = options.db ?? getDbAsSystem();
+    const windowSize = options.windowSize ?? EncryptionLifecycleWalker.DEFAULT_WINDOW_SIZE;
+    const columnNames = props.map((prop) => ({
+      prop,
+      columnName: ((table.columns as any)[prop] as { name: string }).name,
+    }));
+    const activeVersionByOwner = new Map<string, number>();
+
+    const summary: EncryptionWalkSummary = { scanned: 0, rewritten: 0 };
+    let cursor = options.startAfterId;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const rawRows = await this.rawWindow(table, dbDriver, columnNames, cursor, windowSize);
+      if (rawRows.length === 0) {
+        break;
+      }
+
+      for (const rawRow of rawRows) {
+        summary.scanned++;
+        const pendingProps: string[] = [];
+        for (const { prop, columnName } of columnNames) {
+          if (await this.isPending(mode, rawRow[columnName], activeVersionByOwner)) {
+            pendingProps.push(prop);
+          }
+        }
+
+        if (pendingProps.length === 0) {
+          continue;
+        }
+
+        await this.rewriteRow(table, db, rawRow['id'], pendingProps);
+        summary.rewritten++;
+      }
+
+      cursor = rawRows[rawRows.length - 1]['id'];
+      if (rawRows.length < windowSize) {
+        break;
+      }
+    }
+
+    if (mode === 'decrypt') {
+      await this.sweepTokenRows(
+        table,
+        db,
+        columnNames.map(({ columnName }) => columnName)
+      );
+    }
+
+    this.logger.info({
+      message: `Encryption lifecycle walk finished`,
+      obj: { table: table.name, mode, ...summary },
+    });
+    return summary;
+  }
+
+  private async isPending(
+    mode: EncryptionWalkMode,
+    rawValue: any,
+    activeVersionByOwner: Map<string, number>
+  ): Promise<boolean> {
+    if (rawValue === null || typeof rawValue === 'undefined') {
+      return false;
+    }
+
+    const parsed = this.envelope.parse(rawValue);
+    switch (mode) {
+      case 'encrypt':
+        return !parsed;
+      case 'retokenize':
+        return true;
+      case 'decrypt':
+        return !!parsed;
+      case 'rotate-keys': {
+        if (!parsed) {
+          return true; // plaintext straggler — encrypt under the current key
+        }
+        let activeVersion = activeVersionByOwner.get(parsed.owner);
+        if (typeof activeVersion === 'undefined') {
+          activeVersion = (await new DataKeyStore().getWriteKey(parsed.owner)).version;
+          activeVersionByOwner.set(parsed.owner, activeVersion);
+        }
+        return parsed.version < activeVersion;
+      }
+    }
+  }
+
+  /**
+   * Rewrite one row through the normal seam: read it (the deserialize hook decrypts — or
+   * passes plaintext through, the adoption path), write the pending columns back (the
+   * serialize hook re-derives ciphertext, companions, and tokens under the current config).
+   */
+  private async rewriteRow(
+    table: Table<any>,
+    db: import('../Db').Db<any>,
+    id: string,
+    pendingProps: string[]
+  ): Promise<void> {
+    const row = await db.get(table, { id });
+    if (!row) {
+      return; // deleted mid-walk
+    }
+
+    const payload: any = { id };
+    for (const prop of pendingProps) {
+      if (typeof row[prop] !== 'undefined') {
+        payload[prop] = row[prop];
+      }
+    }
+
+    if (Object.keys(payload).length === 1) {
+      return;
+    }
+
+    await db.update(table, payload);
+  }
+
+  /** Raw (un-deserialized) id-ordered window — pending-ness must see stored bytes, not decrypted values. */
+  private async rawWindow(
+    table: Table<any>,
+    dbDriver: import('../Db').DbDriver,
+    columnNames: { prop: string; columnName: string }[],
+    cursor: string | undefined,
+    windowSize: number
+  ): Promise<any[]> {
+    const { StatementConfigFactory } = await import('../StatementConfigFactory');
+    const statementConfigFactory = new StatementConfigFactory(dbDriver.getDbName());
+    const qb = new QueryBuilder(table.name).select({ fields: ['id', ...columnNames.map(({ prop }) => prop)] });
+    if (cursor) {
+      qb.condition({ field: 'id', operator: '>', value: cursor });
+    }
+    qb.sort([{ field: 'id' }]).paginate({ start: 0, end: windowSize });
+    return await dbDriver.runQuery((config) => qb.toSql(statementConfigFactory.getStatementConfig(config)));
+  }
+
+  /** After decrypt-out, the decrypted columns' token rows are stale — sweep them. */
+  private async sweepTokenRows(table: Table<any>, db: import('../Db').Db<any>, columnNames: string[]): Promise<void> {
+    const tokenTable = this.encryptedColumns.tokenTableFor(table) ?? this.encryptedColumns.tokenTableShape(table);
+    if (!(await db.tableExists(tokenTable))) {
+      return;
+    }
+
+    const deleteQb = new QueryBuilder(tokenTable.name).condition({
+      field: 'columnName',
+      operator: 'IN',
+      value: columnNames,
+    });
+    await db.delete(tokenTable, deleteQb);
+  }
+
+  private resolveProps(table: Table<any>, mode: EncryptionWalkMode, options: EncryptionWalkOptions): string[] {
+    if (options.columns && options.columns.length > 0) {
+      for (const prop of options.columns) {
+        if (!(table.columns as any)[prop]) {
+          throw new Error(`(${table.name}) Unknown column property to walk: ${prop}`);
+        }
+      }
+      return options.columns;
+    }
+
+    if (mode === 'decrypt') {
+      throw new Error(
+        `Mode 'decrypt' requires options.columns: after the config flips to encrypted: false, the ` +
+          `declaration no longer names the columns to decrypt.`
+      );
+    }
+
+    const props = this.encryptedColumns.encryptedProps(table);
+    if (props.length === 0) {
+      throw new Error(`(${table.name}) No encrypted columns declared — nothing to walk.`);
+    }
+
+    return props;
+  }
+}