@proteinjs/db 1.35.0 → 1.36.0

package/index.ts

@@ -29,6 +29,22 @@ export * from './src/schema/SchemaOperations';
 export * from './src/schema/SchemaMetadata';
 export * from './src/schema/TableManager';
 
+export * from './src/encryption/MasterKeyProvider';
+export * from './src/encryption/InMemoryMasterKeyProvider';
+export * from './src/encryption/DbEncryptionConfig';
+export * from './src/encryption/DataEncryptionKeyTable';
+export * from './src/encryption/DataKeyStore';
+export * from './src/encryption/EncryptionEnvelope';
+export * from './src/encryption/SearchTokenizer';
+export * from './src/encryption/EncryptedColumns';
+export * from './src/encryption/EncryptedColumnQueryError';
+export * from './src/encryption/EncryptedColumnQueryTransform';
+export * from './src/TableQueryTransformProvider';
+export * from './src/encryption/EncryptionRecordHooks';
+export * from './src/encryption/EncryptionTokenMaintenance';
+export * from './src/encryption/EncryptionLifecycleWalker';
+export * from './src/encryption/EncryptionDerivedTableRegistry';
+
 export * from './src/tables/tables';
 export * from './src/tables/MigrationTable';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.35.0",
+  "version": "1.36.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -41,7 +41,7 @@
     "test": "jest --passWithNoTests"
   },
   "dependencies": {
-    "@proteinjs/db-query": "^1.7.2",
+    "@proteinjs/db-query": "^1.8.0",
     "@proteinjs/logger": "^1.0.21",
     "@proteinjs/reflection": "^1.2.0",
     "@proteinjs/serializer": "^1.1.10",
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "521d5d1ca2f86f0ed2bef0309b0dde30506f132b"
+  "gitHead": "b25c88ae26fffd1c784b4c7b1174825b52751987"
 }

package/src/Db.ts

@@ -187,7 +187,8 @@ export class Db<R extends Record = Record> implements DbService<R> {
     await addDefaultFieldValues(table, recordCopy, this.runAsSystem);
     recordCopy = await this.tableWatcherRunner.runBeforeInsertTableWatchers(table, recordCopy);
     await this.addColumnInsertHooks(table, recordCopy);
-    const recordSerializer = new RecordSerializer(table);
+    const encryptionContext = await this.encryptionWriteContext(table, recordCopy);
+    const recordSerializer = new RecordSerializer(table, encryptionContext);
     const serializedRecord = await recordSerializer.serialize(recordCopy);
     const generateInsert = (config: DbDriverDmlStatementConfig) =>
       new StatementFactory<T>().insert(
@@ -196,6 +197,17 @@ export class Db<R extends Record = Record> implements DbService<R> {
         this.statementConfigFactory.getStatementConfig(config)
       );
     await this.dbDriver.runDml(generateInsert, this.transactionForDriver());
+    if (encryptionContext) {
+      // The same write that stored the ciphertext maintains its search tokens (rides the
+      // ambient transaction when there is one).
+      const { EncryptionTokenMaintenance } = await import('./encryption/EncryptionTokenMaintenance');
+      await new EncryptionTokenMaintenance().afterInsert(
+        table,
+        recordCopy,
+        encryptionContext.keyOwner,
+        this.newSystemDb()
+      );
+    }
     await this.runColumnAfterInsertHooks(table, recordCopy);
     await this.tableWatcherRunner.runAfterInsertTableWatchers(table, recordCopy as T);
     return recordCopy as T;
@@ -229,17 +241,22 @@ export class Db<R extends Record = Record> implements DbService<R> {
     }
 
     recordCopy = await this.tableWatcherRunner.runBeforeUpdateTableWatchers(table, recordCopy, qb);
-    const recordSerializer = new RecordSerializer<T>(table);
-    const serializedRecord = await recordSerializer.serialize(recordCopy);
-    delete serializedRecord['id'];
-    const generateUpdate = (config: DbDriverDmlStatementConfig) =>
-      new StatementFactory<T>().update(
-        table.name,
-        serializedRecord as Partial<T>,
-        qb,
-        this.statementConfigFactory.getStatementConfig(config)
-      );
-    const recordUpdateCount = await this.dbDriver.runDml(generateUpdate, this.transactionForDriver());
+    let recordUpdateCount: number;
+    if (await this.updateTouchesEncryptedColumns(table, recordCopy)) {
+      recordUpdateCount = await this.updateEncrypted(table, recordCopy, qb);
+    } else {
+      const recordSerializer = new RecordSerializer<T>(table);
+      const serializedRecord = await recordSerializer.serialize(recordCopy);
+      delete serializedRecord['id'];
+      const generateUpdate = (config: DbDriverDmlStatementConfig) =>
+        new StatementFactory<T>().update(
+          table.name,
+          serializedRecord as Partial<T>,
+          qb,
+          this.statementConfigFactory.getStatementConfig(config)
+        );
+      recordUpdateCount = await this.dbDriver.runDml(generateUpdate, this.transactionForDriver());
+    }
     if (!this.runAsSystem && recordUpdateCount === 0) {
       const id = this.singleRowIdTarget(record, query);
       if (id !== undefined) {
@@ -380,6 +397,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
     const recordDeleteCount = await this.dbDriver.runDml(generateDelete, this.transactionForDriver());
     await this.runCascadeDeletions(table, recordsToDelete);
     await this.runColumnReverseCascadeDeletions(table, recordsToDelete);
+    await this.deleteEncryptionTokenRows(table, recordsToDeleteIds as string[]);
     await this.tableWatcherRunner.runAfterDeleteTableWatchers(table, recordDeleteCount, recordsToDelete, qb, deleteQb);
     return recordDeleteCount;
   }
@@ -701,6 +719,21 @@ export class Db<R extends Record = Record> implements DbService<R> {
         await column.options.addToQuery(qb, this.runAsSystem, operation);
       }
     }
+
+    // The column-transform phase of the query model (`QueryBuilder.applyColumnTransforms`):
+    // each column's own query contract (`Column.queryTransform` — e.g. an encrypted
+    // column's condition/sort translation) is applied by the builder, with this
+    // operation's runtime — or rejected loudly at query-build time. Runs on every
+    // query/update/delete/count, so callers keep writing exactly what they write today.
+    // Imported at call time (module-graph discipline — see Db.init).
+    const { TableQueryTransformProvider } = await import('./TableQueryTransformProvider');
+    await qb.applyColumnTransforms(
+      new TableQueryTransformProvider(this.getTable, {
+        runAsSystem: this.runAsSystem,
+        query: (verifyTable, verifyQb) => this.query(verifyTable, verifyQb as any),
+        systemQuery: (derivedTable, derivedQb) => this.newSystemDb().query(derivedTable, derivedQb as any),
+      })
+    );
   }
 
   private async addColumnInsertHooks(table: Table<any>, record: any) {
@@ -852,6 +885,98 @@ export class Db<R extends Record = Record> implements DbService<R> {
     await hook();
   }
 
+  /**
+   * The encryption context of a write, when the payload touches encrypted columns: the key
+   * owner (the row's permission-source scope owner) whose data key the values encrypt
+   * under. Undefined for writes that touch no encrypted column — the serializer then runs
+   * exactly as before.
+   */
+  private async encryptionWriteContext(table: Table<any>, record: any): Promise<{ keyOwner: string } | undefined> {
+    const { EncryptedColumns } = await import('./encryption/EncryptedColumns');
+    const encryptedColumns = new EncryptedColumns();
+    encryptedColumns.ensureSchema(table);
+    if (!encryptedColumns.recordTouchesEncryptedColumns(table, record)) {
+      return undefined;
+    }
+
+    const { EncryptionRecordHooks } = await import('./encryption/EncryptionRecordHooks');
+    return { keyOwner: await new EncryptionRecordHooks().resolveKeyOwnerForWrite(table, record) };
+  }
+
+  private async updateTouchesEncryptedColumns(table: Table<any>, record: any): Promise<boolean> {
+    const { EncryptedColumns } = await import('./encryption/EncryptedColumns');
+    const encryptedColumns = new EncryptedColumns();
+    encryptedColumns.ensureSchema(table);
+    return encryptedColumns.recordTouchesEncryptedColumns(table, record);
+  }
+
+  /**
+   * Update path for payloads touching encrypted columns. Ciphertext is keyed per row OWNER
+   * (the row's scope owner), so one UPDATE statement cannot serve target rows of different
+   * owners: the target set is snapshotted (through the caller's own filtered query — the
+   * same query-then-act shape `delete` uses), grouped by owner, and updated one DML per
+   * owner group with that owner's ciphertext, companions, and search tokens.
+   */
+  private async updateEncrypted<T extends R>(
+    table: Table<T>,
+    recordCopy: Partial<T>,
+    qb: QueryBuilder<T>
+  ): Promise<number> {
+    const targetRows = await this._query(table, qb);
+    if (targetRows.length === 0) {
+      return 0;
+    }
+
+    const { EncryptionRecordHooks } = await import('./encryption/EncryptionRecordHooks');
+    const { EncryptionTokenMaintenance } = await import('./encryption/EncryptionTokenMaintenance');
+    const hooks = new EncryptionRecordHooks();
+    const idsByOwner = new Map<string, string[]>();
+    for (const row of targetRows) {
+      const owner = await hooks.resolveKeyOwnerForWrite(table, row);
+      const ids = idsByOwner.get(owner) ?? [];
+      ids.push(row.id);
+      idsByOwner.set(owner, ids);
+    }
+
+    let recordUpdateCount = 0;
+    const tokenMaintenance = new EncryptionTokenMaintenance();
+    for (const [owner, ids] of Array.from(idsByOwner.entries())) {
+      const recordSerializer = new RecordSerializer<T>(table, { keyOwner: owner });
+      const serializedRecord = await recordSerializer.serialize(recordCopy);
+      delete serializedRecord['id'];
+      const groupQb = new QueryBuilderFactory()
+        .getQueryBuilder(table)
+        .condition({ field: 'id', operator: 'IN', value: ids as T[keyof T][] });
+      const generateUpdate = (config: DbDriverDmlStatementConfig) =>
+        new StatementFactory<T>().update(
+          table.name,
+          serializedRecord as Partial<T>,
+          groupQb,
+          this.statementConfigFactory.getStatementConfig(config)
+        );
+      recordUpdateCount += await this.dbDriver.runDml(generateUpdate, this.transactionForDriver());
+      await tokenMaintenance.afterUpdate(table, ids, recordCopy, owner, this.newSystemDb());
+    }
+
+    return recordUpdateCount;
+  }
+
+  /** Deleted rows take their search-token rows with them (no-op for tables without contains columns). */
+  private async deleteEncryptionTokenRows(table: Table<any>, deletedIds: string[]): Promise<void> {
+    const { EncryptionTokenMaintenance } = await import('./encryption/EncryptionTokenMaintenance');
+    await new EncryptionTokenMaintenance().afterDelete(table, deletedIds, this.newSystemDb());
+  }
+
+  /**
+   * A system instance riding THIS instance's driver and transaction context — for framework
+   * machinery beside a caller's operation (search-token upkeep, token-table reads): the
+   * derived tables are default-deny for callers, and the ops must ride the caller's ambient
+   * transaction.
+   */
+  private newSystemDb(): Db<any> {
+    return new Db<any>(this.dbDriver, this.getTable, this.transactionContextFactory, true);
+  }
+
   /**
    * A fresh instance for self-wrapping RMW verbs (`updateArrayMembership`, `updatePreserving`)
    * in a transaction. `runTransaction` carries the open transaction as INSTANCE state, and these

package/src/Record.ts

@@ -47,12 +47,18 @@ export function withRecordColumns<T extends Record>(
 
 export type SerializedRecord = { [columnName: string]: any };
 
+/** Who a row being written belongs to — the data key its encrypted columns encrypt under
+ *  (see `EncryptionRecordHooks`). Resolved by `Db` for writes touching encrypted columns. */
+export type RecordEncryptionContext = { keyOwner: string };
+
 export class RecordSerializer<T extends Record> {
   private logger = new Logger({ name: this.constructor.name });
   private table: Table<T>;
+  private encryptionContext?: RecordEncryptionContext;
 
-  constructor(table: Table<T>) {
+  constructor(table: Table<T>, encryptionContext?: RecordEncryptionContext) {
     this.table = table;
+    this.encryptionContext = encryptionContext;
   }
 
   async serialize(record: any): Promise<SerializedRecord> {
@@ -82,20 +88,31 @@ export class RecordSerializer<T extends Record> {
       this.logger.warn({ message: `Fields were omitted during serialization`, obj: { omittedFields } });
     }
 
+    // The transparent encryption seam (`ColumnOptions.encrypted`): encrypted columns'
+    // serialized values become ciphertext envelopes, search/sort companions are derived
+    // beside them. Imported at call time — this module sits below the encryption machinery
+    // in the package's module graph.
+    const { EncryptionRecordHooks } = await import('./encryption/EncryptionRecordHooks');
+    await new EncryptionRecordHooks().onSerialize(this.table, serialized, this.encryptionContext);
     return serialized;
   }
 
   async deserialize(serializedRecord: SerializedRecord): Promise<T> {
+    // The transparent decryption seam: ciphertext envelopes decrypt (self-describing — the
+    // envelope names its key), framework companion columns drop out of the result.
+    const { EncryptionRecordHooks } = await import('./encryption/EncryptionRecordHooks');
+    const prepared = await new EncryptionRecordHooks().onDeserialize(this.table, serializedRecord);
+
     const deserialized: any = {};
     const fieldSerializer = new FieldSerializer(this.table);
     const omittedFields: string[] = [];
-    for (const columnName in serializedRecord) {
-      const serializedFieldValue = serializedRecord[columnName];
+    for (const columnName in prepared) {
+      const serializedFieldValue = prepared[columnName];
       try {
         const { fieldPropertyName, fieldValue } = await fieldSerializer.deserialize(
           columnName,
           serializedFieldValue,
-          serializedRecord
+          prepared
         );
         deserialized[fieldPropertyName] = fieldValue;
       } catch (MissingFieldError) {

package/src/Table.ts

@@ -2,9 +2,10 @@ import { Loadable, SourceRepository } from '@proteinjs/reflection';
 import { CustomSerializableObject } from '@proteinjs/serializer';
 import { isRecordColumn, Record } from './Record';
 import { TableSerializerId } from './serializers/TableSerializer';
-import { QueryBuilder } from '@proteinjs/db-query';
+import { ColumnQueryTransform, QueryBuilder } from '@proteinjs/db-query';
 import { Identity, TableOperationsAuth } from './auth/TableAuth';
 import { Db } from './Db';
+import { EncryptionDerivedTableRegistry } from './encryption/EncryptionDerivedTableRegistry';
 
 export const isTable = (obj: any) => obj.__serializerId === TableSerializerId;
 
@@ -14,13 +15,38 @@ export const tableByName = (name: string) => {
   const tables = getTables();
   for (const table of tables) {
     if (table.name == name) {
-      return table;
+      return ensureEncryptionSchema(table);
     }
   }
 
+  // Framework-DERIVED tables (search-token tables beside encrypted columns) are synthesized
+  // from column config rather than declared in source, so the reflection registry never
+  // sees them (see EncryptionDerivedTableRegistry — a runtime-cycle-free, type-only import).
+  const derivedTable = EncryptionDerivedTableRegistry.get(name);
+  if (derivedTable) {
+    return derivedTable;
+  }
+
   throw new Error(`Unable to find table: ${name}`);
 };
 
+/**
+ * Table instances are constructed ad hoc all over consumer code, and the encryption-derived
+ * physical schema (companion columns — see `EncryptedColumns.ensureSchema`) is injected
+ * per-instance at the seams that use an instance. Name-based resolution is one of those
+ * seams: statement generation and driver column-type lookups resolve the REGISTRY's
+ * instance through here, which must carry the same derived columns as the instance the
+ * caller handed the Db. Idempotent (marker-checked); a call-time require keeps the module
+ * graph acyclic at load time.
+ */
+const ensureEncryptionSchema = (table: Table<any>): Table<any> => {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { EncryptedColumns } =
+    require('./encryption/EncryptedColumns') as typeof import('./encryption/EncryptedColumns');
+  new EncryptedColumns().ensureSchema(table);
+  return table;
+};
+
 export const getColumnPropertyName = (table: Table<any>, columnName: string) => {
   for (const columnPropertyName in table.columns) {
     const column = table.columns[columnPropertyName];
@@ -126,6 +152,20 @@ export type Columns<T> = {
   [P in OptionalProps<T>]?: Column<T[P] | undefined, any>;
 };
 
+/**
+ * What a column's query transform runs WITH: the current operation's authority and its
+ * driver/transaction-riding query runners. Supplied by `Db` per operation
+ * (`Db.addColumnQueries`), so a transform's own reads behave like part of the query that
+ * carried them.
+ */
+export interface ColumnQueryRuntime {
+  runAsSystem: boolean;
+  /** Query with the CALLER's authority (auth + column queries apply). */
+  query: (table: Table<any>, qb: QueryBuilder<any>) => Promise<any[]>;
+  /** System-authority query — for framework-derived tables that are default-deny to callers. */
+  systemQuery: (table: Table<any>, qb: QueryBuilder<any>) => Promise<any[]>;
+}
+
 export type Column<T, Serialized> = {
   name: string;
   /**
@@ -137,6 +177,21 @@ export type Column<T, Serialized> = {
   options?: ColumnOptions;
   serialize?: (fieldValue: T | null | undefined) => Promise<Serialized | null | undefined>;
   deserialize?: (serializedFieldValue: Serialized | null, serializedRecord: any) => Promise<T | null | void>;
+  /**
+   * The column's QUERY-side contract, paralleling `serialize`/`deserialize` on the storage
+   * side: how uses of this column in a query (conditions, ORDER BY, aggregation, GROUP BY)
+   * translate into uses of what the database actually stores and indexes for it — see
+   * `ColumnQueryTransform` (@proteinjs/db-query). Applied by
+   * `QueryBuilder.applyColumnTransforms` on every query, through
+   * `TableQueryTransformProvider`.
+   *
+   * A factory rather than a bare transform: translation may consult derived index state
+   * (e.g. an encrypted column's token table), so a transform is built per operation with
+   * the operation's `ColumnQueryRuntime` — its driver-riding query runners and authority.
+   * Derived by the framework for encrypted columns (`EncryptedColumns.ensureSchema`);
+   * any column may supply one.
+   */
+  queryTransform?: (runtime: ColumnQueryRuntime) => ColumnQueryTransform;
   beforeDelete?: (
     table: Table<any>,
     columnPropertyName: string,
@@ -146,8 +201,60 @@ export type Column<T, Serialized> = {
   ) => Promise<void>;
 };
 
+/**
+ * Capabilities of an encrypted column. Nested INSIDE the `encrypted` declaration on purpose:
+ * `searchable` and `sortKey` only mean anything on an encrypted column (a plaintext column
+ * is inherently searchable and sortable through normal SQL), so the invalid state — a
+ * search/sort capability declared without encryption — is unrepresentable.
+ */
+export type EncryptedColumnConfig = {
+  /**
+   * Index the value for native querying over ciphertext (derived automatically at the
+   * database layer — see `EncryptedColumns`):
+   * - `'contains'` — word + trigram search tokens, keyed-fingerprinted per owner, serving
+   *   the LIKE contains/prefix family with exact results (candidate cover + decrypt-verify).
+   * - `'equality'` — one whole-value fingerprint companion column serving `=` / `IN` /
+   *   get-by-value as a single indexed lookup (and value uniqueness, per owner).
+   * Encrypted columns that are never queried by value declare neither and carry no
+   * derivatives — the default.
+   */
+  searchable?: 'contains' | 'equality';
+  /**
+   * Native ORDER BY at any scale through a DECLARED bounded reveal: an ordered
+   * representation of the value's first `revealPrefix` characters (normalized) is stored
+   * beside the ciphertext and the database sorts on it. The leak, stated plainly: raw
+   * database access can see each value's first `revealPrefix` characters — nothing else.
+   * A conscious, schema-author-declared tradeoff; never the default. Rows sharing a prefix
+   * tie-break app-side within the returned page.
+   */
+  sortKey?: { revealPrefix: number };
+};
+
 export type ColumnOptions = {
   unique?: { unique: boolean; indexName?: string };
+  /**
+   * Whether this column's values are stored encrypted (AES-256-GCM under per-owner data
+   * keys wrapped by the deployment's master key — see `DbEncryptionConfig`). The value is
+   * either `false` (plaintext — said out loud) or a config object:
+   *
+   * ```ts
+   * encrypted: false                             // plaintext (explicit)
+   * encrypted: {}                                // encrypted, never queried by value
+   * encrypted: { searchable: 'contains' }        // + indexed contains/prefix search
+   * encrypted: { searchable: 'equality' }        // + indexed exact-match lookup
+   * encrypted: { sortKey: { revealPrefix: 3 } }  // + native ORDER BY via a declared bounded reveal
+   * ```
+   *
+   * Everything downstream — the transparent encrypt/decrypt seam, companion index
+   * derivation, query translation, loud contract rejections, lifecycle backfills — is
+   * derived automatically at the database layer; callers never write an encrypt or decrypt
+   * call. Query shapes outside the contract are rejected at query-build time
+   * (`EncryptionQueryTranslator`).
+   *
+   * When `DbEncryptionConfig.requireEncryptedDeclarations` is on, every text-holding
+   * column MUST carry this declaration — registration fails loudly otherwise.
+   */
+  encrypted?: false | EncryptedColumnConfig;
   /**
    * The column in the reference table `table` is the primary key of the table (`id` unless otherwise specified in the Table definition)
    *

package/src/TableQueryTransformProvider.ts

@@ -0,0 +1,31 @@
+import { ColumnQueryTransform, ColumnQueryTransformProvider } from '@proteinjs/db-query';
+import { Column, ColumnQueryRuntime, Table } from './Table';
+
+/**
+ * The Table-model side of db-query's column query-transform seam: resolves a
+ * (tableName, columnProperty) pair to the column's own `Column.queryTransform`, built with
+ * the current operation's `ColumnQueryRuntime`. `Db.addColumnQueries` hands one of these
+ * to `QueryBuilder.applyColumnTransforms` on every query, so a column's query contract is
+ * consulted wherever the column is used — including inside subquery values on other
+ * tables, resolved through the same table registry the statement layer uses.
+ */
+export class TableQueryTransformProvider implements ColumnQueryTransformProvider {
+  constructor(
+    private getTable: (tableName: string) => Table<any>,
+    private runtime: ColumnQueryRuntime
+  ) {}
+
+  getTransform(tableName: string, columnPropertyName: string): ColumnQueryTransform | undefined {
+    let table: Table<any>;
+    try {
+      table = this.getTable(tableName);
+    } catch {
+      // Not a registered table (e.g. an aggregate '*' field, or a name outside the model) —
+      // nothing to consult.
+      return undefined;
+    }
+
+    const column = (table.columns as any)[columnPropertyName] as Column<any, any> | undefined;
+    return column?.queryTransform?.(this.runtime);
+  }
+}

package/src/encryption/Base64Url.ts

@@ -0,0 +1,14 @@
+/**
+ * Base64url (RFC 4648 §5) over Buffers, hand-rolled because the package's @types/node
+ * predates the 'base64url' BufferEncoding. URL/filename-safe alphabet, no padding — safe
+ * inside the colon-delimited ciphertext envelope and as index-column values.
+ */
+export class Base64Url {
+  static encode(bytes: Buffer): string {
+    return bytes.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+  }
+
+  static decode(encoded: string): Buffer {
+    return Buffer.from(encoded.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+  }
+}

package/src/encryption/DataEncryptionKeyTable.ts

@@ -0,0 +1,40 @@
+import { Table } from '../Table';
+import { Record, withRecordColumns } from '../Record';
+import { IntegerColumn, StringColumn } from '../Columns';
+
+/**
+ * One wrapped per-owner data key version (see `DataKeyStore`).
+ *
+ * - `active` — encrypts new writes (the highest active version) and fingerprints queries.
+ * - `retired` — decrypt-only: envelopes referencing it still unwrap, but no new writes or
+ *   query fingerprints use it. A rotation walk moves every row off a version, then retires it.
+ *
+ * Crypto-shred = deleting an owner's rows here: every envelope naming that owner becomes
+ * permanently unreadable, including inside backups.
+ */
+export interface DataEncryptionKey extends Record {
+  /** The key owner (a user id — the row's permission-source scope owner). */
+  owner: string;
+  /** Monotonic per-owner version; envelopes name (owner, version). */
+  version: number;
+  /** The data-key material, wrapped by the master key (`MasterKeyProvider`). */
+  wrappedKey: string;
+  status: 'active' | 'retired';
+}
+
+export class DataEncryptionKeyTable extends Table<DataEncryptionKey> {
+  public name = 'data_encryption_key';
+  public columns: Table<DataEncryptionKey>['columns'] = withRecordColumns<DataEncryptionKey>({
+    owner: new StringColumn('owner', { nullable: false }, 36),
+    version: new IntegerColumn('version', { nullable: false }),
+    wrappedKey: new StringColumn('wrapped_key', { nullable: false }, 'MAX'),
+    status: new StringColumn('status', { nullable: false }, 16),
+  });
+  /** (owner, version) is the identity an envelope names — the race loser on concurrent
+   *  first-write key creation fails here and re-reads the winner's key. */
+  public indexes: { columns: (keyof DataEncryptionKey)[]; name?: string; unique?: boolean }[] = [
+    { columns: ['owner', 'version'], name: 'data_encryption_key_owner_version_unique', unique: true },
+  ];
+  // No auth block: default-deny for every non-system caller. Key rows are framework
+  // machinery, only ever touched through system paths (DataKeyStore).
+}