@cipherstash/stack 0.18.0 → 1.0.0-rc.0

package/dist/chunk-X3JRXEIB.js

@@ -0,0 +1,98 @@
+// src/eql/v3/table.ts
+var EncryptedTable = class {
+  constructor(tableName, columnBuilders) {
+    this.tableName = tableName;
+    this.columnBuilders = columnBuilders;
+  }
+  tableName;
+  columnBuilders;
+  build() {
+    const builtColumns = /* @__PURE__ */ Object.create(null);
+    for (const builder of Object.values(this.columnBuilders)) {
+      const name = builder.getName();
+      if (Object.hasOwn(builtColumns, name)) {
+        throw new Error(
+          `[eql/v3]: duplicate column name "${name}" in table "${this.tableName}" \u2014 two columns resolve to the same DB name`
+        );
+      }
+      builtColumns[name] = builder.build();
+    }
+    return {
+      tableName: this.tableName,
+      columns: builtColumns
+    };
+  }
+  /**
+   * Map each column's JS property name to its DB column name (`getName()`).
+   * The model path matches user models by property name but must address the
+   * encrypt config and FFI by DB name — `build()` keys columns by DB name, so
+   * the two only agree when property == name. This recovers the mapping that
+   * `build()` discards.
+   *
+   * NULL PROTOTYPE — load-bearing. Callers index this map by a column name that
+   * ultimately comes from the database (`addJsonbCastsV3`, `filterColumnName`,
+   * the mutation transform). On a plain object literal, a column named
+   * `constructor` / `toString` / `valueOf` / `__proto__` resolves to an
+   * inherited `Object.prototype` member, which is truthy — so a *plaintext*
+   * column with such a name would be mistaken for a mapped encrypted column and
+   * its `Object.prototype` value interpolated into the emitted select string.
+   * `encryptedTable()` rejects such names as JS *properties*, but nothing
+   * constrains the DB column names a table may contain.
+   */
+  buildColumnKeyMap() {
+    const map = /* @__PURE__ */ Object.create(null);
+    for (const [property, builder] of Object.entries(this.columnBuilders)) {
+      map[property] = builder.getName();
+    }
+    return map;
+  }
+};
+var RESERVED_TABLE_KEYS = /* @__PURE__ */ new Set([
+  "tableName",
+  "columnBuilders",
+  "_columnType",
+  "build",
+  "buildColumnKeyMap"
+]);
+function isReservedTableKey(tableBuilder, colName) {
+  return RESERVED_TABLE_KEYS.has(colName) || colName in tableBuilder;
+}
+function encryptedTable(tableName, columns) {
+  const tableBuilder = new EncryptedTable(
+    tableName,
+    columns
+  );
+  for (const [colName, colBuilder] of Object.entries(columns)) {
+    if (isReservedTableKey(tableBuilder, colName)) {
+      throw new Error(
+        `Column name "${colName}" collides with a reserved EncryptedTable property`
+      );
+    }
+    ;
+    tableBuilder[colName] = colBuilder;
+  }
+  return tableBuilder;
+}
+function buildEncryptConfig(...tables) {
+  const config = {
+    v: 1,
+    tables: {}
+  };
+  for (const tb of tables) {
+    const tableDef = tb.build();
+    if (Object.hasOwn(config.tables, tableDef.tableName)) {
+      throw new Error(
+        `[eql/v3]: duplicate table name "${tableDef.tableName}" passed to buildEncryptConfig \u2014 each table must have a unique name`
+      );
+    }
+    config.tables[tableDef.tableName] = tableDef.columns;
+  }
+  return config;
+}
+
+export {
+  EncryptedTable,
+  encryptedTable,
+  buildEncryptConfig
+};
+//# sourceMappingURL=chunk-X3JRXEIB.js.map

package/dist/chunk-X3JRXEIB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/eql/v3/table.ts"],"sourcesContent":["import type { ColumnSchema, EncryptConfig } from '@/schema'\nimport type { Encrypted } from '@/types'\nimport type {\n  EncryptedV3TableColumn,\n  PlaintextForColumn,\n  QueryTypesForColumn,\n} from './columns'\n\ninterface TableDefinition {\n  tableName: string\n  columns: Record<string, ColumnSchema>\n}\n\n/**\n * A v3 encrypted table. Mirrors the v2 `EncryptedTable` but only accepts v3\n * column builders. Emits the same `{ tableName, columns }` definition shape.\n */\nexport class EncryptedTable<T extends EncryptedV3TableColumn> {\n  /** @internal Type-level brand so TypeScript can infer `T` from `EncryptedTable<T>`. */\n  declare readonly _columnType: T\n\n  constructor(\n    public readonly tableName: string,\n    public readonly columnBuilders: T,\n  ) {}\n\n  build(): TableDefinition {\n    // NULL PROTOTYPE — load-bearing, for the same reason as\n    // {@link buildColumnKeyMap}. Keys are DB column names, which the database\n    // supplies. On a plain object literal, `builtColumns['__proto__'] = schema`\n    // REPARENTS the object rather than adding an own key, so the column never\n    // reaches the encrypt config — `decryptModel` then skips it and its\n    // ciphertext is returned undecrypted. `encryptedTable()` rejects such names\n    // as JS properties, but nothing constrains a table's DB column names.\n    const builtColumns: Record<string, ColumnSchema> = Object.create(null)\n    for (const builder of Object.values(this.columnBuilders)) {\n      // Key by the column's DB name (`getName()`), NOT the JS property name.\n      // `encrypt`/`decrypt` look columns up in the config by `column.getName()`,\n      // so a camelCase JS key mapping to a snake_case DB column (e.g.\n      // `createdOn: types.Date('created_on')`) must register under\n      // `created_on` or the FFI reports \"column not found in Encrypt config\".\n      const name = builder.getName()\n      // Two JS properties resolving to the same DB name would silently overwrite\n      // here (later wins), dropping the first column's config. Fail loudly —\n      // matching the duplicate-tableName guard in buildEncryptConfig and the\n      // reserved-key guard in encryptedTable.\n      if (Object.hasOwn(builtColumns, name)) {\n        throw new Error(\n          `[eql/v3]: duplicate column name \"${name}\" in table \"${this.tableName}\" — two columns resolve to the same DB name`,\n        )\n      }\n      builtColumns[name] = builder.build()\n    }\n    return {\n      tableName: this.tableName,\n      columns: builtColumns,\n    }\n  }\n\n  /**\n   * Map each column's JS property name to its DB column name (`getName()`).\n   * The model path matches user models by property name but must address the\n   * encrypt config and FFI by DB name — `build()` keys columns by DB name, so\n   * the two only agree when property == name. This recovers the mapping that\n   * `build()` discards.\n   *\n   * NULL PROTOTYPE — load-bearing. Callers index this map by a column name that\n   * ultimately comes from the database (`addJsonbCastsV3`, `filterColumnName`,\n   * the mutation transform). On a plain object literal, a column named\n   * `constructor` / `toString` / `valueOf` / `__proto__` resolves to an\n   * inherited `Object.prototype` member, which is truthy — so a *plaintext*\n   * column with such a name would be mistaken for a mapped encrypted column and\n   * its `Object.prototype` value interpolated into the emitted select string.\n   * `encryptedTable()` rejects such names as JS *properties*, but nothing\n   * constrains the DB column names a table may contain.\n   */\n  buildColumnKeyMap(): Record<string, string> {\n    const map = Object.create(null) as Record<string, string>\n    for (const [property, builder] of Object.entries(this.columnBuilders)) {\n      map[property] = builder.getName()\n    }\n    return map\n  }\n}\n\n/**\n * Own instance members of {@link EncryptedTable} that a column name must not\n * shadow. Because {@link encryptedTable} copies column builders onto the\n * instance for accessor access (`users.email`), a column named e.g. `build`\n * would otherwise overwrite the method that {@link buildEncryptConfig} relies\n * on. `_columnType` is a type-only `declare` (no runtime property) so it is\n * listed explicitly here rather than caught by the `in` check below.\n */\nconst RESERVED_TABLE_KEYS = new Set([\n  'tableName',\n  'columnBuilders',\n  '_columnType',\n  'build',\n  'buildColumnKeyMap',\n])\n\n/**\n * Whether a column name would collide with a reserved property on the table\n * object — either an own member ({@link RESERVED_TABLE_KEYS}) or any inherited\n * `Object.prototype` member (`constructor`, `toString`, `valueOf`,\n * `hasOwnProperty`, …). The `in` check covers the prototype chain so assigning\n * the column as an own property can never shadow a prototype method/accessor.\n */\nfunction isReservedTableKey(tableBuilder: object, colName: string): boolean {\n  return RESERVED_TABLE_KEYS.has(colName) || colName in tableBuilder\n}\n\n/**\n * Define a v3 encrypted table. Intentionally shadows the v2 `encryptedTable`\n * name but lives on the `/eql/v3` subpath — the importer picks the model by\n * import path. The returned object is also a column accessor (`users.email`).\n */\nexport function encryptedTable<T extends EncryptedV3TableColumn>(\n  tableName: string,\n  columns: T,\n): EncryptedTable<T> & T {\n  const tableBuilder = new EncryptedTable(\n    tableName,\n    columns,\n  ) as EncryptedTable<T> & T\n\n  for (const [colName, colBuilder] of Object.entries(columns)) {\n    if (isReservedTableKey(tableBuilder, colName)) {\n      throw new Error(\n        `Column name \"${colName}\" collides with a reserved EncryptedTable property`,\n      )\n    }\n    ;(tableBuilder as EncryptedV3TableColumn)[colName] = colBuilder\n  }\n\n  return tableBuilder\n}\n\n/**\n * Build an `EncryptConfig` (`v: 1`) from one or more v3 tables. Emits the same\n * shape as v2's `buildEncryptConfig`.\n */\nexport function buildEncryptConfig(\n  ...tables: Array<EncryptedTable<EncryptedV3TableColumn>>\n): EncryptConfig {\n  const config: EncryptConfig = {\n    v: 1,\n    tables: {},\n  }\n\n  for (const tb of tables) {\n    const tableDef = tb.build()\n    // Config tables are keyed by name, so a duplicate would silently overwrite\n    // the earlier table. Fail loudly instead. (v3-only additive guard; v2's\n    // buildEncryptConfig keeps its existing silent-overwrite behavior.)\n    if (Object.hasOwn(config.tables, tableDef.tableName)) {\n      throw new Error(\n        `[eql/v3]: duplicate table name \"${tableDef.tableName}\" passed to buildEncryptConfig — each table must have a unique name`,\n      )\n    }\n    config.tables[tableDef.tableName] = tableDef.columns\n  }\n\n  return config\n}\n\n/**\n * Infer the plaintext (decrypted) shape from a v3 table schema. Each column maps\n * to the TypeScript type of its domain's `castAs` kind.\n */\nexport type InferPlaintext<T extends EncryptedTable<EncryptedV3TableColumn>> =\n  T extends EncryptedTable<infer C>\n    ? { [K in keyof C]: PlaintextForColumn<C[K]> }\n    : never\n\n/**\n * Infer the encrypted shape from a v3 table schema. See {@link InferPlaintext}\n * for why no key-remap filter is needed in the flat single-type model.\n */\nexport type InferEncrypted<T extends EncryptedTable<EncryptedV3TableColumn>> =\n  T extends EncryptedTable<infer C> ? { [K in keyof C]: Encrypted } : never\n\n// ---------------------------------------------------------------------------\n// Typed-client surface helpers (@cipherstash/stack/v3)\n// ---------------------------------------------------------------------------\n\n/** Any v3 table, regardless of its column map. */\nexport type AnyV3Table = EncryptedTable<EncryptedV3TableColumn>\n\n/** Union of the concrete column builders declared on a v3 table. */\nexport type ColumnsOf<T extends AnyV3Table> =\n  T extends EncryptedTable<infer C> ? C[keyof C] : never\n\n/**\n * Union of the *queryable* column builders on a v3 table. Storage-only columns\n * (whose {@link QueryTypesForColumn} is `never`) are filtered out, so they can't\n * be passed to a query method.\n */\nexport type QueryableColumnsOf<T extends AnyV3Table> =\n  T extends EncryptedTable<infer C>\n    ? {\n        [K in keyof C]: [QueryTypesForColumn<C[K]>] extends [never]\n          ? never\n          : C[K]\n      }[keyof C]\n    : never\n\n/**\n * The accepted input model for {@link import('@/encryption/v3').TypedEncryptionClient.encryptModel}.\n * `T` is inferred from the argument: keys that name a schema column are pinned to\n * the column's plaintext type (nullable if the field is nullable), so a wrong-typed\n * field fails assignability; all other keys pass through unchanged.\n */\nexport type V3ModelInput<Table extends AnyV3Table, T> = {\n  [K in keyof T]: K extends keyof InferPlaintext<Table>\n    ? null extends T[K]\n      ? InferPlaintext<Table>[K] | null\n      : InferPlaintext<Table>[K]\n    : T[K]\n}\n\n/** The encrypted result model: schema columns become `Encrypted`, others pass through. */\nexport type V3EncryptedModel<Table extends AnyV3Table, T> = {\n  [K in keyof T]: K extends keyof InferPlaintext<Table>\n    ? null extends T[K]\n      ? Encrypted | null\n      : Encrypted\n    : T[K]\n}\n\n/**\n * The decrypted result model: schema columns become their plaintext type, others\n * pass through. Structurally identical to {@link V3ModelInput} — decrypt yields\n * the same plaintext shape encrypt accepts — so it is aliased rather than\n * re-declared to keep the input and output shapes from silently drifting when\n * one copy is edited. The distinct name is kept for call-site readability.\n */\nexport type V3DecryptedModel<Table extends AnyV3Table, T> = V3ModelInput<\n  Table,\n  T\n>\n"],"mappings":";AAiBO,IAAM,iBAAN,MAAuD;AAAA,EAI5D,YACkB,WACA,gBAChB;AAFgB;AACA;AAAA,EACf;AAAA,EAFe;AAAA,EACA;AAAA,EAGlB,QAAyB;AAQvB,UAAM,eAA6C,uBAAO,OAAO,IAAI;AACrE,eAAW,WAAW,OAAO,OAAO,KAAK,cAAc,GAAG;AAMxD,YAAM,OAAO,QAAQ,QAAQ;AAK7B,UAAI,OAAO,OAAO,cAAc,IAAI,GAAG;AACrC,cAAM,IAAI;AAAA,UACR,oCAAoC,IAAI,eAAe,KAAK,SAAS;AAAA,QACvE;AAAA,MACF;AACA,mBAAa,IAAI,IAAI,QAAQ,MAAM;AAAA,IACrC;AACA,WAAO;AAAA,MACL,WAAW,KAAK;AAAA,MAChB,SAAS;AAAA,IACX;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBA,oBAA4C;AAC1C,UAAM,MAAM,uBAAO,OAAO,IAAI;AAC9B,eAAW,CAAC,UAAU,OAAO,KAAK,OAAO,QAAQ,KAAK,cAAc,GAAG;AACrE,UAAI,QAAQ,IAAI,QAAQ,QAAQ;AAAA,IAClC;AACA,WAAO;AAAA,EACT;AACF;AAUA,IAAM,sBAAsB,oBAAI,IAAI;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AASD,SAAS,mBAAmB,cAAsB,SAA0B;AAC1E,SAAO,oBAAoB,IAAI,OAAO,KAAK,WAAW;AACxD;AAOO,SAAS,eACd,WACA,SACuB;AACvB,QAAM,eAAe,IAAI;AAAA,IACvB;AAAA,IACA;AAAA,EACF;AAEA,aAAW,CAAC,SAAS,UAAU,KAAK,OAAO,QAAQ,OAAO,GAAG;AAC3D,QAAI,mBAAmB,cAAc,OAAO,GAAG;AAC7C,YAAM,IAAI;AAAA,QACR,gBAAgB,OAAO;AAAA,MACzB;AAAA,IACF;AACA;AAAC,IAAC,aAAwC,OAAO,IAAI;AAAA,EACvD;AAEA,SAAO;AACT;AAMO,SAAS,sBACX,QACY;AACf,QAAM,SAAwB;AAAA,IAC5B,GAAG;AAAA,IACH,QAAQ,CAAC;AAAA,EACX;AAEA,aAAW,MAAM,QAAQ;AACvB,UAAM,WAAW,GAAG,MAAM;AAI1B,QAAI,OAAO,OAAO,OAAO,QAAQ,SAAS,SAAS,GAAG;AACpD,YAAM,IAAI;AAAA,QACR,mCAAmC,SAAS,SAAS;AAAA,MACvD;AAAA,IACF;AACA,WAAO,OAAO,SAAS,SAAS,IAAI,SAAS;AAAA,EAC/C;AAEA,SAAO;AACT;","names":[]}