bazis 0.102.0 → 0.104.0

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.102.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.104.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/infra/connectors/codex.ts

@@ -5,12 +5,18 @@ import { reader, requireValue } from "../connectorConfig";
 import { CodexAppServerClient } from "./codex/CodexAppServerClient";
 import type { CodexClient, CodexConfigShape } from "./codex/contracts";
 
-export const CODEX_APP_SERVER: InjectionToken<CodexClient> = createToken<CodexClient>("CodexClient");
+/**
+ * Codex App Server client of the `codexAppServerConnect()` connector,
+ * injected by type like the other infra clients:
+ * `constructor(private readonly codex: ICodex)`.
+ */
+export interface ICodex extends CodexClient {}
+export const ICodex = createToken<ICodex>("ICodex") as InjectionToken<CodexClient>;
 
 /** App Server is a full executor; it does not implement the raw AgentModelProvider port. */
 export function codexAppServerConnect(config: AppConfig<CodexConfigShape>): InfraConnector<CodexClient> {
   return {
-    token: CODEX_APP_SERVER, config, phase: 0,
+    token: ICodex, config, phase: 0,
     create(configs) {
       const view = reader(config, configs);
       return new CodexAppServerClient({

package/core/infra/index.ts

@@ -7,7 +7,7 @@ export { Infra, infraModule, type InfraManifest } from "./Infra";
 export { InfraError, errorMessage, type ConnectionDescription, type InfraConnector } from "./InfraConnector";
 export { InfraLifecycle } from "./InfraLifecycle";
 export { reader, requireValue, settingNames, type ConfigReader } from "./connectorConfig";
-export { codexAppServerConnect, CODEX_APP_SERVER } from "./connectors/codex";
+export { codexAppServerConnect, ICodex } from "./connectors/codex";
 export { CodexError, RU_CODEX_MESSAGES, type CodexErrorCode, CODEX_MODEL_ID, CODEX_REASONING_EFFORT, type CodexClient, type CodexConfigShape, type CodexLogin, type CodexLoginMethod, type CodexModel, type CodexStatus, type CodexRunInput, type CodexChatMessage, type CodexTool, type CodexToolCall, type CodexToolResult } from "./connectors/codex/contracts";
 
 export { postgres, IPostgres, postgresConnectionOptions, type PostgresConfigShape, type PostgresSslMode, type PostgresConnectorOptions } from "./connectors/postgres";

package/core/orm/buildOrmProviders.ts

@@ -1,8 +1,9 @@
 import { DI, HOSTED_SERVICE, type InjectionToken, type ModuleOwnedContributionSnapshot, type ProviderDefinition, type ProviderDependencyList, type ServiceResolver } from "../di";
 import { getGeneratedClassDeps } from "../di/module/autoDeps";
 import { resolveDependencyList } from "../di/internal/resolveDependencyList";
-import { HEALTH_CHECK, StartupReport } from "../kernel";
+import { ConfigRegistry, HEALTH_CHECK, StartupReport } from "../kernel";
 import { DbContextOptions, OrmError, type DatabaseProvider, type DbContext } from "../../library/orm";
+import { bindEncryptedColumns } from "./encryptedWith";
 import { OrmLifecycle } from "./OrmLifecycle";
 import { ownedStoreLifecycleFor, ownedStoreLifecycleHealthFor } from "./OrmOwnedStoreLifecycle";
 import { effectiveOrmModuleConfig, ownedStoreRegistrations } from "./ownedStoreContributions";
@@ -22,13 +23,22 @@ type OrmBuildConfig<TContext extends DbContext> = OrmModuleConfig<TContext> & {
 function createContextOptions<TContext extends DbContext>(
   config: OrmBuildConfig<TContext>,
   provider: DatabaseProvider,
+  serviceProvider: unknown,
 ): DbContextOptions {
-  return new DbContextOptions({
+  return bindKeys(new DbContextOptions({
     provider,
     entities: config.entities ?? [],
     validateOnSave: config.validateOnSave,
     executionStrategy: config.executionStrategy,
-  });
+  }), serviceProvider);
+}
+
+/** Binds the keys of `encryptedWith` columns from the application configuration. */
+function bindKeys(options: DbContextOptions, serviceProvider: unknown): DbContextOptions {
+  const services = serviceProvider as { has?(token: unknown): boolean; resolve?(token: unknown): unknown };
+  const registry = services.has?.(ConfigRegistry) ? services.resolve?.(ConfigRegistry) as ConfigRegistry : undefined;
+  bindEncryptedColumns(options, registry);
+  return options;
 }
 
 const contextDependencies = new WeakMap<object, ProviderDependencyList>();
@@ -103,7 +113,7 @@ export function buildOrmModuleProviders<TContext extends DbContext>(
       DI.scoped(
         DI.factoryProviderWithResolver(config.context, [token, SERVICE_PROVIDER] as const, (resolver, provider: DatabaseProvider, serviceProvider) => {
           const current = effectiveConfigFor(serviceProvider, registrationIdentity, config);
-          return constructContext(current.context, createContextOptions(current, provider), resolver);
+          return constructContext(current.context, createContextOptions(current, provider, serviceProvider), resolver);
         }),
       ),
       DI.singleton(
@@ -119,7 +129,7 @@ export function buildOrmModuleProviders<TContext extends DbContext>(
             });
             return ownedStoreLifecycleFor(container, provider, records);
           }
-          return createOrmLifecycle(current, createContextOptions(current, provider), false, serviceProvider);
+          return createOrmLifecycle(current, createContextOptions(current, provider, serviceProvider), false, serviceProvider);
         }),
       ),
     ];
@@ -137,12 +147,12 @@ export function buildOrmModuleProviders<TContext extends DbContext>(
     DI.scoped(DI.factoryProviderWithResolver(config.context, [SERVICE_PROVIDER], (resolver, serviceProvider) => {
       const current = effectiveConfigFor(serviceProvider, registrationIdentity, config);
       const context = current === config ? config.context : current.context;
-      return constructContext(context, current === config && optionsAtModuleCall !== undefined ? optionsAtModuleCall : createContextOptions(current, provider), resolver);
+      return constructContext(context, current === config && optionsAtModuleCall !== undefined ? bindKeys(optionsAtModuleCall, serviceProvider) : createContextOptions(current, provider, serviceProvider), resolver);
     })),
     // Standalone mode: the context owns its provider and closes it.
     DI.singleton(DI.factoryProvider(HOSTED_SERVICE, [SERVICE_PROVIDER], (serviceProvider) => {
       const current = effectiveConfigFor(serviceProvider, registrationIdentity, config);
-      return createOrmLifecycle(current, current === config && optionsAtModuleCall !== undefined ? optionsAtModuleCall : createContextOptions(current, provider), true, serviceProvider);
+      return createOrmLifecycle(current, current === config && optionsAtModuleCall !== undefined ? bindKeys(optionsAtModuleCall, serviceProvider) : createContextOptions(current, provider, serviceProvider), true, serviceProvider);
     })),
   ];
   return providers;

package/core/orm/encryptedWith.ts

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import { Secret, type ConfigDefinition, type ConfigRegistry } from "../kernel";
+import { OrmError, type DbContextOptions, type ValueConverter } from "../../library/orm";
+import { aesGcmConverter } from "../../library/orm/Metadata/ValueConverter";
+
+interface PendingKey {
+  readonly config: ConfigDefinition<object>;
+  readonly field: string;
+  /** The secret once bound, the configuration it came from, and its fingerprint for a second binding. */
+  secret?: string;
+  registry?: ConfigRegistry;
+  fingerprint?: string;
+}
+
+const pending = new WeakMap<object, PendingKey>();
+
+/**
+ * AES-256-GCM encryption of a string column with a key from the application
+ * configuration. The key is read when the ORM starts — after every
+ * configuration source, secret files included, is loaded — so a missing key
+ * stops the start instead of failing on the first request:
+ *
+ * ```ts
+ * export const cryptoConfig = defineConfig("crypto", { default: { phoneKey: secret("dev-…") }, production: { phoneKey: secret() } });
+ *
+ * @HasConversion(encryptedWith(cryptoConfig, "phoneKey"))
+ * @Column({ type: "text" })
+ * phone = "";
+ * ```
+ *
+ * The secret must be random (`openssl rand -base64 32`): it is hashed with
+ * SHA-256, not stretched like a password. Equal values are stored differently,
+ * so the column cannot be compared or sorted in SQL.
+ */
+export function encryptedWith<T extends object>(config: ConfigDefinition<T>, field: keyof T & string): ValueConverter<string, string> {
+  const binding: PendingKey = { config: config as ConfigDefinition<object>, field };
+  const converter = aesGcmConverter(() => {
+    if (binding.secret === undefined) {
+      throw new OrmError(`encryptedWith(${label(binding)}): the key is not bound yet; the column is used outside a started application.`);
+    }
+    return binding.secret;
+  });
+  pending.set(converter, binding);
+  return converter;
+}
+
+/**
+ * Binds the keys of `encryptedWith` columns of a context to the application
+ * configuration. Called by the ORM providers at startup; binding the same
+ * column again with another key (two applications in one process) is refused.
+ */
+export function bindEncryptedColumns(options: DbContextOptions, registry: ConfigRegistry | undefined): void {
+  for (const entity of options.model.entities) {
+    for (const property of entity.properties) {
+      const binding = property.converter === undefined ? undefined : pending.get(property.converter);
+      if (binding === undefined || (registry !== undefined && binding.registry === registry)) continue;
+      const where = `${entity.name}.${property.propertyName}: encryptedWith(${label(binding)})`;
+      if (registry === undefined) throw new OrmError(`${where}: the application configuration is not available.`);
+      let view: { get(key: string): unknown };
+      try {
+        view = registry.get(binding.config) as { get(key: string): unknown };
+      } catch {
+        throw new OrmError(`${where}: the config "${prefixOf(binding)}" is not declared in the application; add it to \`config\` of the module that owns ${entity.name} or to runApp({ config }).`);
+      }
+      const value = view.get(binding.field);
+      const secret = value instanceof Secret ? value.reveal() : value;
+      if (typeof secret !== "string" || secret.length === 0) throw new OrmError(`${where}: the key is empty; set a random secret (openssl rand -base64 32).`);
+      const fingerprint = createHash("sha256").update(secret).digest("hex");
+      if (binding.fingerprint !== undefined && binding.fingerprint !== fingerprint) {
+        throw new OrmError(`${where}: the column is already bound to another key in this process.`);
+      }
+      binding.secret = secret;
+      binding.registry = registry;
+      binding.fingerprint = fingerprint;
+    }
+  }
+}
+
+function prefixOf(binding: PendingKey): string {
+  return binding.config.token.description.replace(/^Config:/, "");
+}
+
+function label(binding: PendingKey): string {
+  return `${prefixOf(binding)}.${binding.field}`;
+}

package/core/orm/index.ts

@@ -11,6 +11,7 @@ export { IRepository, repositoryFor } from "./repository";
 export { registerRepositories } from "./registerRepositories";
 export { paginate, type PageResult } from "./listQuery";
 export { databaseErrorStatus } from "./databaseErrorStatus";
+export { encryptedWith } from "./encryptedWith";
 
 import { registerModuleMetadataExpander, type BazisModuleRef } from "../di";
 import { registerModuleDescriber } from "../kernel/report/moduleTree";

package/library/orm/Metadata/ModelBuilder.ts

@@ -184,6 +184,15 @@ export class ModelBuilder {
       if (indexNames.has(index.name)) throw new ModelBuildError(`Entity "${ctor.name}": duplicate index name "${index.name}".`);
       indexNames.add(index.name);
     }
+    // Encryption with a random nonce stores equal values differently: such a
+    // column cannot identify a row or be unique.
+    for (const property of properties) {
+      if (property.converter?.comparable !== false) continue;
+      if (property.isKey) throw new ModelBuildError(`Entity "${ctor.name}": key "${property.propertyName}" cannot be encrypted: equal values are stored differently.`);
+      if (indexes.some((index) => index.unique && index.columns.includes(property.columnName))) {
+        throw new ModelBuildError(`Entity "${ctor.name}": a unique index on encrypted "${property.propertyName}" cannot work: equal values are stored differently. Put it on a keyed hash (HMAC) column.`);
+      }
+    }
     return model;
   }
 

package/library/orm/Metadata/ValueConverter.ts

@@ -7,40 +7,63 @@ import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:
 export interface ValueConverter<TModel = unknown, TProvider = unknown> {
   toProvider(value: TModel): TProvider;
   fromProvider(value: TProvider): TModel;
+  /**
+   * `false`: equal values are stored differently (encryption with a random
+   * nonce), so a condition or an ordering on the column cannot work in SQL;
+   * the query fails instead of silently matching nothing.
+   */
+  readonly comparable?: boolean;
+}
+
+/** Thrown by an encrypted column that cannot be read: another key, or the stored value was changed. */
+export class DecryptionError extends Error {
+  constructor() {
+    super("cannot decrypt the value: it was encrypted with another key, or the stored value was changed");
+    this.name = "DecryptionError";
+  }
+}
+
+/**
+ * AES-256-GCM string encryption with a key that is read on first use.
+ * The database stores base64(nonce|ciphertext|tag); the key is the SHA-256 of
+ * the secret, so the secret must be random (32 bytes), not a password.
+ */
+export function aesGcmConverter(secret: () => string): ValueConverter<string, string> {
+  let key: Buffer | undefined;
+  const keyOf = (): Buffer => (key ??= createHash("sha256").update(secret()).digest());
+  return {
+    comparable: false,
+    toProvider(plaintext: string): string {
+      const iv = randomBytes(12);
+      const cipher = createCipheriv("aes-256-gcm", keyOf(), iv);
+      const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+      return Buffer.concat([iv, encrypted, cipher.getAuthTag()]).toString("base64");
+    },
+    fromProvider(stored: string): string {
+      // Before 0.104.0 an empty string was stored as is.
+      if (stored === "") return "";
+      const buf = Buffer.from(stored, "base64");
+      if (buf.length < 28) throw new DecryptionError();
+      const decipher = createDecipheriv("aes-256-gcm", keyOf(), buf.subarray(0, 12));
+      decipher.setAuthTag(buf.subarray(buf.length - 16));
+      try {
+        return Buffer.concat([decipher.update(buf.subarray(12, buf.length - 16)), decipher.final()]).toString("utf8");
+      } catch {
+        throw new DecryptionError();
+      }
+    },
+  };
 }
 
 /** Built-in converters (no external dependencies: Node/Bun `crypto`). */
 export const ValueConverters = {
   /**
-   * AES-256-GCM at-rest string encryption. The database stores base64(nonce|ciphertext|tag).
-   * `secret` is the application password/key (derived through SHA-256).
+   * AES-256-GCM at-rest string encryption with a key given in code, for the ORM
+   * without an application. In an application take the key from its
+   * configuration: `encryptedWith(cryptoConfig, "phoneKey")` from `bazis/core/orm`.
    */
   encrypted(secret: string): ValueConverter<string, string> {
-    const key = createHash("sha256").update(secret).digest();
-    return {
-      toProvider(plaintext: string): string {
-        if (plaintext === "") {
-          return "";
-        }
-        const iv = randomBytes(12);
-        const cipher = createCipheriv("aes-256-gcm", key, iv);
-        const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
-        const tag = cipher.getAuthTag();
-        return Buffer.concat([iv, encrypted, tag]).toString("base64");
-      },
-      fromProvider(stored: string): string {
-        if (stored === "") {
-          return "";
-        }
-        const buf = Buffer.from(stored, "base64");
-        const iv = buf.subarray(0, 12);
-        const tag = buf.subarray(buf.length - 16);
-        const ciphertext = buf.subarray(12, buf.length - 16);
-        const decipher = createDecipheriv("aes-256-gcm", key, iv);
-        decipher.setAuthTag(tag);
-        return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
-      },
-    };
+    return aesGcmConverter(() => secret);
   },
 
   /** JSON <-> string through serialization (for custom structures on top of a text column). */

package/library/orm/Providers/propertyConversion.ts

@@ -1,3 +1,4 @@
+import { OrmError } from "../errors";
 import type { PropertyModel } from "../Metadata/types";
 import type { SqlDialect, SqlParam } from "./types";
 
@@ -7,8 +8,26 @@ export function encodeProperty(property: PropertyModel, value: unknown, dialect:
   return dialect.encode(modelValue, property.type);
 }
 
-/** Decodes a column value: dialect -> converter. */
-export function decodeProperty(property: PropertyModel, value: unknown, dialect: SqlDialect): unknown {
+/** Decodes a column value: dialect -> converter. A converter failure names the entity and the property. */
+export function decodeProperty(property: PropertyModel, value: unknown, dialect: SqlDialect, owner?: string): unknown {
   const providerValue = dialect.decode(value, property.type);
-  return property.converter ? property.converter.fromProvider(providerValue) : providerValue;
+  if (!property.converter) return providerValue;
+  try {
+    return property.converter.fromProvider(providerValue);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new OrmError(`Cannot read ${owner ?? "entity"}.${property.propertyName}: ${reason}`, { cause: error });
+  }
+}
+
+/**
+ * A condition or an ordering on a column whose converter stores equal values
+ * differently (encryption with a random nonce) cannot work in SQL.
+ */
+export function assertComparable(property: PropertyModel, owner: string): void {
+  if (property.converter?.comparable !== false) return;
+  throw new OrmError(
+    `${owner}.${property.propertyName} is encrypted with a random nonce: it cannot be compared or sorted in SQL. ` +
+      `To find rows by it, store a separate column with a keyed hash of the value (HMAC) and compare that.`,
+  );
 }

package/library/orm/Query/SqlTranslator.ts

@@ -2,7 +2,7 @@ import { OrmError } from "../errors";
 import { renderPostgresOnConflictDoNothing, renderPostgresSkipLocked } from "../Providers/PostgresDialect";
 import type { EntityModel, PropertyModel } from "../Metadata/types";
 import type { SqlDialect, SqlParam } from "../Providers/types";
-import { encodeProperty } from "../Providers/propertyConversion";
+import { assertComparable, encodeProperty } from "../Providers/propertyConversion";
 import type { Condition } from "./conditions";
 import type { QueryPlan } from "./QueryPlan";
 
@@ -121,7 +121,9 @@ export class SqlTranslator {
       return "";
     }
     const parts = plan.orders.map((order) => {
-      const column = this.requireProperty(order.property).columnName;
+      const property = this.requireProperty(order.property);
+      assertComparable(property, this.model.name);
+      const column = property.columnName;
       return `${this.dialect.quoteId(column)}${order.descending ? " DESC" : " ASC"}`;
     });
     return ` ORDER BY ${parts.join(", ")}`;
@@ -144,6 +146,7 @@ export class SqlTranslator {
     switch (condition.kind) {
       case "compare": {
         const property = this.requireProperty(condition.property);
+        assertComparable(property, this.model.name);
         const placeholder = this.dialect.parameter(params.length);
         params.push(encode(property, condition.value));
         // startsWith/endsWith/contains escape wildcards with `\`; this works
@@ -153,6 +156,7 @@ export class SqlTranslator {
       }
       case "in": {
         const property = this.requireProperty(condition.property);
+        assertComparable(property, this.model.name);
         if (condition.values.length === 0) {
           return "0 = 1"; // an empty IN is always false
         }
@@ -167,7 +171,7 @@ export class SqlTranslator {
         if (condition.properties.length === 0 || condition.values.length === 0) return "0 = 1";
         return `(${condition.values.map((tuple) => {
           if (tuple.length !== condition.properties.length) throw new OrmError("Tuple predicate component count mismatch.");
-          return `(${tuple.map((value, index) => { const property = this.requireProperty(condition.properties[index]!); const placeholder = this.dialect.parameter(params.length); params.push(encode(property, value)); return `${this.dialect.quoteId(property.columnName)} = ${placeholder}`; }).join(" AND ")})`;
+          return `(${tuple.map((value, index) => { const property = this.requireProperty(condition.properties[index]!); assertComparable(property, this.model.name); const placeholder = this.dialect.parameter(params.length); params.push(encode(property, value)); return `${this.dialect.quoteId(property.columnName)} = ${placeholder}`; }).join(" AND ")})`;
         }).join(" OR ")})`;
       }
       case "null": {

package/library/orm/Query/materialize.ts

@@ -11,7 +11,7 @@ export function materialize<T extends object>(model: EntityModel, row: Row, dial
   const entity = new model.ctor() as Record<string, unknown>;
   for (const property of model.properties) {
     if (property.columnName in row) {
-      entity[property.propertyName] = decodeProperty(property, row[property.columnName], dialect);
+      entity[property.propertyName] = decodeProperty(property, row[property.columnName], dialect, model.name);
     }
   }
   return entity as T;
@@ -32,7 +32,7 @@ export function materializeProjection(
     }
     const column = alias in row ? alias : property.columnName;
     if (column in row) {
-      result[alias] = decodeProperty(property, row[column], dialect);
+      result[alias] = decodeProperty(property, row[column], dialect, model.name);
     }
   }
   return result;

package/library/orm/index.ts

@@ -45,7 +45,7 @@ export {
   type ScalarLogicalFieldType,
 } from "./Metadata/DynamicModelBuilder";
 export { pluralize } from "./Metadata/conventions";
-export { ValueConverters, type ValueConverter } from "./Metadata/ValueConverter";
+export { DecryptionError, ValueConverters, type ValueConverter } from "./Metadata/ValueConverter";
 export type {
   ColumnOptionsType,
   ColumnType,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.102.0",
+  "version": "0.104.0",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",