@sebastienrousseau/crypto-typeorm 0.0.8

package/LICENSE

@@ -0,0 +1,8 @@
+This project is dual-licensed under either of:
+
+  * Apache License, Version 2.0 — see LICENSE-APACHE
+  * MIT license — see LICENSE-MIT
+
+at your option.
+
+SPDX-License-Identifier: Apache-2.0 OR MIT

package/README.md

@@ -0,0 +1,365 @@
+<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sebastienrousseau/crypto-service/main/assets/crypto-typeorm-logo.svg" alt="crypto-typeorm logo" width="360" />
+</p>
+
+<h1 align="center">@sebastienrousseau/crypto-typeorm</h1>
+
+<p align="center">
+  TypeORM column-level encryption with a single decorator, powered by crypto-lib.
+</p>
+
+<p align="center">
+  <a href="https://github.com/sebastienrousseau/crypto-service/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/crypto-service/ci.yml?branch=main&style=for-the-badge&logo=github" alt="Build" /></a>
+  <a href="https://coveralls.io/github/sebastienrousseau/crypto-service?branch=main"><img src="https://img.shields.io/coveralls/github/sebastienrousseau/crypto-service?branch=main&style=for-the-badge" alt="Coverage" /></a>
+  <a href="https://www.npmjs.com/package/@sebastienrousseau/crypto-typeorm"><img src="https://img.shields.io/npm/v/@sebastienrousseau/crypto-typeorm.svg?style=for-the-badge&color=f14041&logo=npm" alt="Registry" /></a>
+  <a href="https://sebastienrousseau.github.io/crypto-service/"><img src="https://img.shields.io/badge/docs-TypeDoc-blue.svg?style=for-the-badge&labelColor=555555&logo=typescript" alt="Docs" /></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/crypto-service" title="ossf-scorecard"><img src="https://img.shields.io/badge/OpenSSF-Scorecard-blue?style=for-the-badge&logo=openssf" alt="OpenSSF Scorecard" /></a>
+  <a href="https://github.com/sebastienrousseau/crypto-service/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg?style=for-the-badge" alt="License: Apache-2.0 OR MIT" /></a>
+  <a href="https://github.com/sebastienrousseau/crypto-service/blob/main/docs/POLICIES.md"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-93450a.svg?style=for-the-badge&logo=node.js" alt="Node.js 22 or newer" /></a>
+</p>
+
+---
+
+## Contents
+
+**Getting started**
+
+- [Install](#install) — installation via pnpm, npm, or yarn
+- [Requirements](#requirements) — runtime floor and environment prerequisites
+- [Quick Start](#quick-start) — minimal working usage sample
+
+**The Crypto Service ecosystem**
+
+- [The Crypto Service ecosystem](#the-crypto-service-ecosystem) — full 14-package suite overview
+
+**Package reference**
+
+- [Reference & Usage](#overview) — features, configuration, and capabilities
+- [Examples](#examples) — runnable sample code
+
+**Operational**
+
+- [Development](#development) — build, lint, format, and test targets
+- [Security](#security) — vulnerability disclosure and cryptographic invariants
+- [Documentation](#documentation) — TypeDoc API docs and ecosystem guides
+- [Stability guarantees](#stability-guarantees) — SemVer axis and release policy
+- [License](#license)
+
+---
+
+## Install
+
+```bash
+pnpm add @sebastienrousseau/crypto-typeorm
+# or
+npm install @sebastienrousseau/crypto-typeorm
+# or
+yarn add @sebastienrousseau/crypto-typeorm
+```
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Requirements
+
+- **Node.js**: `^22.0.0` or `>=24.0.0` (active and maintenance LTS releases)
+- **Package Manager**: `pnpm >=9` (recommended) or `npm >=10`
+- **TypeScript**: `>=5.0` (when compiling with TypeScript)
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Quick Start
+
+```ts
+import { Entity, PrimaryGeneratedColumn } from "typeorm";
+import { EncryptedColumn } from "@sebastienrousseau/crypto-typeorm";
+
+@Entity()
+class User {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @EncryptedColumn({
+    encrypt: { key: process.env.COLUMN_ENCRYPTION_KEY! },
+  })
+  ssn!: string;
+}
+```
+
+That is it. The `ssn` column is stored as an XChaCha20-Poly1305
+sealed box (Base64) and decrypted transparently on every read.
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## The Crypto Service ecosystem
+
+Crypto Service provides a complete cryptography stack across 14 specialized packages:
+
+| Package                                                                       | Role            | Description                                                                                                                            |
+| :---------------------------------------------------------------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
+| [`@sebastienrousseau/crypto-api`](../crypto-api)                              | API Schemas     | Shared TypeScript types and utilities for the Crypto Service Suite, defining the canonical API surface.                                |
+| [`@sebastienrousseau/crypto-cli`](../crypto-cli)                              | Terminal CLI    | An interactive command-line interface for cryptographic operations, supporting both legacy OpenPGP and modern post-quantum algorithms. |
+| [`@sebastienrousseau/crypto-edge`](../crypto-edge)                            | Edge Runtime    | Edge-runtime cryptographic operations using the Web Crypto API, optimized for Cloudflare Workers, Vercel Edge, and Deno.               |
+| [`@sebastienrousseau/crypto-kms`](../crypto-kms)                              | Cloud KMS       | Unified Key Management Service interface for AWS KMS, GCP Cloud KMS, Azure Key Vault, and HashiCorp Vault.                             |
+| [`@sebastienrousseau/crypto-lib`](../crypto-lib)                              | Core Library    | A modern cryptographic library for TypeScript, with post-quantum support, zero unsafe dependencies, and 100% test coverage.            |
+| [`@sebastienrousseau/crypto-middleware`](../crypto-middleware)                | Middleware      | Framework-agnostic cryptographic middleware for Express, Fastify, and Koa applications.                                                |
+| [`@sebastienrousseau/crypto-prisma`](../crypto-prisma)                        | ORM Adapter     | Transparent field-level encryption extension for Prisma Client, powered by XChaCha20-Poly1305.                                         |
+| [`@sebastienrousseau/crypto-react`](../crypto-react)                          | React Hooks     | React hooks and context provider for client-side cryptographic operations with zero boilerplate.                                       |
+| [`@sebastienrousseau/crypto-sdk`](../crypto-sdk)                              | Client SDK      | A zero-dependency, typed HTTP client for the Crypto Service REST API, with full post-quantum support.                                  |
+| [`@sebastienrousseau/crypto-server`](../crypto-server)                        | HTTP API        | A hardened Fastify REST API for cryptographic operations, with rate limiting, OpenAPI schemas, and post-quantum endpoints.             |
+| [`@sebastienrousseau/crypto-testing`](../crypto-testing)                      | Test Support    | Deterministic keys, fast mocks, and test fixtures for crypto-lib                                                                       |
+| **[`@sebastienrousseau/crypto-typeorm`](../crypto-typeorm)** _(this package)_ | **ORM Adapter** | **TypeORM column-level encryption with a single decorator, powered by crypto-lib.**                                                    |
+| [`@sebastienrousseau/crypto-vue`](../crypto-vue)                              | Vue Composables | Vue 3 composables for client-side cryptography                                                                                         |
+| [`@sebastienrousseau/crypto-wasm`](../crypto-wasm)                            | Acceleration    | WebAssembly performance accelerator for crypto-lib                                                                                     |
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Overview
+
+crypto-typeorm provides column-level encryption for TypeORM
+entities. Three integration styles are available: a `@EncryptedColumn`
+decorator that combines TypeORM's `@Column` with automatic
+encryption/decryption, an `EncryptionSubscriber` for centralised
+field configuration, and an `EncryptionTransformer` for manual
+`ValueTransformer` usage. All styles use XChaCha20-Poly1305 via
+crypto-lib's secretbox, with fresh random nonces on every write.
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Configuration
+
+All APIs accept an `EncryptionConfig` object:
+
+| Property                 | Type                    | Default                | Description                                                                                     |
+| :----------------------- | :---------------------- | :--------------------- | :---------------------------------------------------------------------------------------------- |
+| `key`                    | `string`                | **required**           | 256-bit key as a 64-char hex string                                                             |
+| `algorithm`              | `string`                | `"xchacha20-poly1305"` | Algorithm identifier                                                                            |
+| `fields`                 | `Map<string, string[]>` | `undefined`            | Per-entity field list (used by `EncryptionSubscriber`)                                          |
+| `context`                | `string`                | `""`                   | Column context bound into each ciphertext (`Entity.property`); set by `@EncryptedColumn`        |
+| `allowPlaintextFallback` | `boolean`               | `false`                | Return values that are not ciphertexts as-is instead of throwing; for plaintext migrations only |
+| `acceptLegacyCiphertext` | `boolean`               | `true`                 | Read ciphertexts written before the `v2:` format; turn off once every row has been re-written   |
+
+`@EncryptedColumn` reads `process.env.TYPEORM_ENCRYPTION_KEY` when
+no key is provided in decorator options.
+
+### Stored format and compatibility
+
+New values are written as `v2:` followed by the Base64 sealed box
+(24-byte nonce, ciphertext, 16-byte Poly1305 tag):
+
+- **Encryption key.** Values are sealed under a subkey derived from
+  `key` with HKDF-SHA-256 (info `crypto-typeorm/enc/v2`), not under
+  `key` itself.
+- **Associated data.** Each value is bound to
+  `crypto-typeorm/v2:<context>`. `@EncryptedColumn` uses
+  `ClassName.property` and `EncryptionSubscriber` uses
+  `EntityName.field`, so a ciphertext copied into another column or
+  entity fails to decrypt. The primary key is not bound: a
+  `ValueTransformer` never sees the row, and generated keys do not
+  exist yet at insert time, so two rows can still have the same
+  column's value swapped. A bare `EncryptionTransformer` without
+  `context` binds the empty context, shared with every other
+  context-less transformer; pass `context` explicitly.
+- **Class names.** The default context comes from the class name. If
+  a bundler renames classes, pin `encrypt.context` (or keep class
+  names) so values written before and after the build still match.
+- **Fail closed.** A value that does not decrypt throws
+  `FieldDecryptionError` (exported; it carries `context` and never
+  the stored value), from `EncryptionTransformer.from()` and from
+  `EncryptionSubscriber.afterLoad`. `allowPlaintextFallback: true`
+  returns a value that is not a ciphertext at all as-is, for the
+  duration of a plaintext migration; a `v2:` value that fails
+  authentication is rejected even then.
+- **Legacy values.** Ciphertexts written by earlier versions (bare
+  Base64, sealed with `key` and no associated data) are still read,
+  and never written. They are not bound to a column. Rewrite them in
+  the `v2:` format (as `examples/migration.ts` does for plaintext:
+  read each value, write it back through the transformer), then set
+  `acceptLegacyCiphertext: false`.
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Decorator API
+
+### `@EncryptedColumn(options?)`
+
+A property decorator that combines TypeORM's `@Column` with an
+`EncryptionTransformer`.
+
+```ts
+@EncryptedColumn()                              // uses TYPEORM_ENCRYPTION_KEY env var
+@EncryptedColumn({ encrypt: { key: "..." } })   // explicit key
+@EncryptedColumn({ type: "text", nullable: true, encrypt: { key: "..." } })
+@EncryptedColumn({ encrypt: { key: "...", context: "User.ssn" } }) // pinned context
+```
+
+Each value is bound to `ClassName.property` unless `encrypt.context`
+is given.
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Subscriber API
+
+### `EncryptionSubscriber`
+
+An `EntitySubscriberInterface` that encrypts/decrypts fields based
+on a centralised configuration.
+
+```ts
+import { DataSource } from "typeorm";
+import { EncryptionSubscriber } from "@sebastienrousseau/crypto-typeorm";
+
+const ds = new DataSource({
+  subscribers: [
+    new EncryptionSubscriber({
+      key: process.env.COLUMN_ENCRYPTION_KEY!,
+      fields: new Map([
+        ["User", ["ssn", "email"]],
+        ["Payment", ["cardNumber"]],
+      ]),
+    }),
+  ],
+});
+```
+
+| Hook           | Behaviour                           |
+| :------------- | :---------------------------------- |
+| `beforeInsert` | Encrypts configured fields in-place |
+| `beforeUpdate` | Encrypts configured fields in-place |
+| `afterLoad`    | Decrypts configured fields in-place |
+
+`afterLoad` throws `FieldDecryptionError` when a stored value is not
+a valid ciphertext for `EntityName.field`. To load rows that still
+hold plaintext during a gradual migration, set
+`allowPlaintextFallback: true` until every row has been rewritten.
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Transformer API
+
+### `EncryptionTransformer`
+
+A standard TypeORM `ValueTransformer` for manual use on any
+`@Column`.
+
+```ts
+import { Column, Entity, PrimaryGeneratedColumn } from "typeorm";
+import { EncryptionTransformer } from "@sebastienrousseau/crypto-typeorm";
+
+const transformer = new EncryptionTransformer({
+  key: process.env.COLUMN_ENCRYPTION_KEY!,
+  context: "Secret.value",
+});
+
+@Entity()
+class Secret {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Column({ type: "text", transformer })
+  value!: string;
+}
+```
+
+| Method        | Input                       | Output                                                    |
+| :------------ | :-------------------------- | :-------------------------------------------------------- |
+| `to(value)`   | plaintext or `null`         | `v2:` Base64 sealed box or `null`                         |
+| `from(value)` | stored ciphertext or `null` | plaintext string or `null`; throws `FieldDecryptionError` |
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Examples
+
+All examples are self-contained TypeScript files in the `examples/`
+directory. Run any example with:
+
+```bash
+npx ts-node examples/<name>.ts
+```
+
+| Category    | Example                                   | Purpose                                           |
+| :---------- | :---------------------------------------- | :------------------------------------------------ |
+| Decorator   | [decorator.ts](examples/decorator.ts)     | Using `@EncryptedColumn` on entity fields         |
+| Subscriber  | [subscriber.ts](examples/subscriber.ts)   | Centralised encryption via `EncryptionSubscriber` |
+| Transformer | [transformer.ts](examples/transformer.ts) | Manual `ValueTransformer` on `@Column`            |
+| Migration   | [migration.ts](examples/migration.ts)     | Encrypting existing plaintext columns             |
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Development
+
+```bash
+pnpm --filter @sebastienrousseau/crypto-typeorm run build
+pnpm --filter @sebastienrousseau/crypto-typeorm run test
+pnpm --filter @sebastienrousseau/crypto-typeorm run lint
+pnpm --filter @sebastienrousseau/crypto-typeorm run format
+```
+
+All 18 packages in the Crypto Service workspace maintain a **100% coverage floor** across statements, branches, functions, and lines.
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Security
+
+Report vulnerabilities privately via [GitHub Security Advisories](https://github.com/sebastienrousseau/crypto-service/security/advisories) or according to [`SECURITY.md`](../../SECURITY.md). Never report security issues publicly.
+
+Cryptographic operations use the `@noble/*` libraries, Node.js `crypto` and OpenPGP.js. `@noble/post-quantum` has not been independently audited and does not guarantee constant-time execution, and no module in this suite is FIPS 140-3 validated. Key zeroization is limited: JavaScript strings and garbage-collected buffers cannot be reliably wiped. See [`SECURITY.md`](../../SECURITY.md).
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Documentation
+
+- [Full Suite Documentation](https://sebastienrousseau.github.io/crypto-service/)
+- [API Reference (TypeDoc)](https://sebastienrousseau.github.io/crypto-service/)
+- [Developer Guide](../../DEVELOPMENT.md)
+- [Security Policy](../../SECURITY.md)
+- [Architecture & Design](../../ARCHITECTURE.md)
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Stability guarantees
+
+Versions advance strictly one step at a time on the `0.0.x` line (`v0.0.1` → `v0.0.2` → `v0.0.3` ... → `v0.0.999` → `v0.1.0`). Work for every release iteration begins on a dedicated `feat/v<version>` branch.
+
+All 18 packages in the workspace move in lockstep. Public API signatures, cipher output formats, and serialization schemas are strictly versioned. Breaking changes to serialized formats or algorithm defaults are considered major breaking changes. Minimum toolchain upgrades (e.g. Node.js LTS floor) are governed by [POLICIES.md](../../docs/POLICIES.md).
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## License
+
+Dual-licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) or [MIT](https://opensource.org/licenses/MIT), at your option.
+
+Copyright (c) 2022-2026 Sebastien Rousseau and The Crypto Service Suite contributors.
+
+<p align="right"><a href="#contents">Back to Top</a></p>

package/dist/codec.d.ts

@@ -0,0 +1,12 @@
+import type { EncryptionConfig } from "./types";
+export declare const CIPHERTEXT_PREFIX = "v2:";
+export interface ColumnCodec {
+    readonly legacyKey: string;
+    readonly encKey: string;
+    readonly allowPlaintextFallback: boolean;
+    readonly acceptLegacyCiphertext: boolean;
+}
+export declare function createColumnCodec(config: EncryptionConfig, owner?: string): ColumnCodec;
+export declare function sealColumn(codec: ColumnCodec, context: string, plaintext: string): string;
+export declare function openColumn(codec: ColumnCodec, context: string, stored: string): string;
+//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGhD,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAcvC,MAAM,WAAW,WAAW;IAE1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;IAEzC,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C;AAYD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,gBAAgB,EACxB,KAAK,SAA0B,GAC9B,WAAW,CAiBb;AAeD,wBAAgB,UAAU,CACxB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAOR;AA0BD,wBAAgB,UAAU,CACxB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,MAAM,CAaR"}

package/dist/codec.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CIPHERTEXT_PREFIX = void 0;
+exports.createColumnCodec = createColumnCodec;
+exports.sealColumn = sealColumn;
+exports.openColumn = openColumn;
+const crypto_lib_1 = require("@sebastienrousseau/crypto-lib");
+const errors_1 = require("./errors");
+exports.CIPHERTEXT_PREFIX = "v2:";
+const HEX_KEY_RE = /^[0-9a-fA-F]{64}$/;
+function createColumnCodec(config, owner = "EncryptionTransformer") {
+    if (!HEX_KEY_RE.test(config.key)) {
+        throw new Error(`${owner}: key must be a 64-character hex string (256 bits)`);
+    }
+    return {
+        legacyKey: config.key,
+        encKey: (0, crypto_lib_1.kdfDerive)({
+            algorithm: "hkdf-sha256",
+            password: Buffer.from(config.key, "hex"),
+            salt: new Uint8Array(32),
+            params: { info: "crypto-typeorm/enc/v2" },
+        }).derivedKey,
+        allowPlaintextFallback: config.allowPlaintextFallback === true,
+        acceptLegacyCiphertext: config.acceptLegacyCiphertext !== false,
+    };
+}
+function contextAad(context) {
+    return Buffer.from(`crypto-typeorm/v2:${context}`, "utf8");
+}
+function sealColumn(codec, context, plaintext) {
+    const { sealed } = crypto_lib_1.secretbox.seal(codec.encKey, plaintext, contextAad(context));
+    return exports.CIPHERTEXT_PREFIX + sealed;
+}
+function tryOpen(key, sealed, aad) {
+    try {
+        return Buffer.from(crypto_lib_1.secretbox.open(key, sealed, aad)).toString("utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function openColumn(codec, context, stored) {
+    if (stored.startsWith(exports.CIPHERTEXT_PREFIX)) {
+        const body = stored.slice(exports.CIPHERTEXT_PREFIX.length);
+        const plain = tryOpen(codec.encKey, body, contextAad(context));
+        if (plain === undefined)
+            throw new errors_1.FieldDecryptionError(context);
+        return plain;
+    }
+    const legacy = codec.acceptLegacyCiphertext
+        ? tryOpen(codec.legacyKey, stored)
+        : undefined;
+    if (legacy !== undefined)
+        return legacy;
+    if (codec.allowPlaintextFallback)
+        return stored;
+    throw new errors_1.FieldDecryptionError(context);
+}
+//# sourceMappingURL=codec.js.map

package/dist/decorator.d.ts

@@ -0,0 +1,7 @@
+import type { ColumnOptions } from "typeorm";
+import type { EncryptionConfig } from "./types";
+export interface EncryptedColumnOptions extends Omit<ColumnOptions, "transformer"> {
+    encrypt?: EncryptionConfig;
+}
+export declare function EncryptedColumn(options?: EncryptedColumnOptions): PropertyDecorator;
+//# sourceMappingURL=decorator.d.ts.map

package/dist/decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../src/decorator.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAgBhD,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAClD,aAAa,EACb,aAAa,CACd;IAKC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAgCD,wBAAgB,eAAe,CAC7B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,iBAAiB,CA0BnB"}

package/dist/decorator.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EncryptedColumn = EncryptedColumn;
+const typeorm_1 = require("typeorm");
+const codec_1 = require("./codec");
+const transformer_1 = require("./transformer");
+function EncryptedColumn(options) {
+    const { encrypt, ...columnOptions } = options ?? {};
+    const key = encrypt?.key ?? process.env.TYPEORM_ENCRYPTION_KEY;
+    if (!key) {
+        throw new Error("EncryptedColumn: encryption key is required. Provide it via " +
+            "options.encrypt.key or set the TYPEORM_ENCRYPTION_KEY env var.");
+    }
+    const config = { ...encrypt, key };
+    (0, codec_1.createColumnCodec)(config, "EncryptedColumn");
+    return (target, propertyKey) => {
+        const transformer = new transformer_1.EncryptionTransformer({
+            ...config,
+            context: encrypt?.context ?? `${target.constructor.name}.${String(propertyKey)}`,
+        });
+        (0, typeorm_1.Column)({ type: "text", ...columnOptions, transformer })(target, propertyKey);
+    };
+}
+//# sourceMappingURL=decorator.js.map

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class FieldDecryptionError extends Error {
+    readonly context: string;
+    constructor(context: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAwBA,qBAAa,oBAAqB,SAAQ,KAAK;IAE7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAGb,OAAO,EAAE,MAAM;CAK5B"}

package/dist/errors.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FieldDecryptionError = void 0;
+class FieldDecryptionError extends Error {
+    context;
+    constructor(context) {
+        super(`Cannot decrypt ${context || "column"}: not a valid ciphertext`);
+        this.name = "FieldDecryptionError";
+        this.context = context;
+    }
+}
+exports.FieldDecryptionError = FieldDecryptionError;
+//# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { EncryptedColumn } from "./decorator";
+export type { EncryptedColumnOptions } from "./decorator";
+export { EncryptionSubscriber } from "./subscriber";
+export { EncryptionTransformer } from "./transformer";
+export { FieldDecryptionError } from "./errors";
+export type { EncryptionConfig } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAGhD,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FieldDecryptionError = exports.EncryptionTransformer = exports.EncryptionSubscriber = exports.EncryptedColumn = void 0;
+var decorator_1 = require("./decorator");
+Object.defineProperty(exports, "EncryptedColumn", { enumerable: true, get: function () { return decorator_1.EncryptedColumn; } });
+var subscriber_1 = require("./subscriber");
+Object.defineProperty(exports, "EncryptionSubscriber", { enumerable: true, get: function () { return subscriber_1.EncryptionSubscriber; } });
+var transformer_1 = require("./transformer");
+Object.defineProperty(exports, "EncryptionTransformer", { enumerable: true, get: function () { return transformer_1.EncryptionTransformer; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "FieldDecryptionError", { enumerable: true, get: function () { return errors_1.FieldDecryptionError; } });
+//# sourceMappingURL=index.js.map

package/dist/subscriber.d.ts

@@ -0,0 +1,15 @@
+import type { EntitySubscriberInterface, InsertEvent, UpdateEvent, LoadEvent } from "typeorm";
+import type { EncryptionConfig } from "./types";
+export declare class EncryptionSubscriber implements EntitySubscriberInterface {
+    private readonly codec;
+    private readonly fields;
+    constructor(config: EncryptionConfig);
+    beforeInsert(event: InsertEvent<Record<string, unknown>>): void;
+    beforeUpdate(event: UpdateEvent<Record<string, unknown>>): void;
+    afterLoad(entity: Record<string, unknown>, event?: LoadEvent<Record<string, unknown>>): void;
+    private getEntityName;
+    private getFieldsFor;
+    private encryptFields;
+    private decryptFields;
+}
+//# sourceMappingURL=subscriber.d.ts.map

package/dist/subscriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriber.d.ts","sourceRoot":"","sources":["../src/subscriber.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,yBAAyB,EACzB,WAAW,EACX,WAAW,EACX,SAAS,EACV,MAAM,SAAS,CAAC;AAOjB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAmChD,qBAAa,oBAAqB,YAAW,yBAAyB;IAEpE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IAEpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;gBAOnC,MAAM,EAAE,gBAAgB;IAWpC,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI;IAO/D,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI;IAS/D,SAAS,CACP,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACzC,IAAI;IAQP,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,aAAa;CAQtB"}

package/dist/subscriber.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EncryptionSubscriber = void 0;
+const codec_1 = require("./codec");
+class EncryptionSubscriber {
+    codec;
+    fields;
+    constructor(config) {
+        if (!config.key) {
+            throw new Error("EncryptionSubscriber: key is required");
+        }
+        this.codec = (0, codec_1.createColumnCodec)(config, "EncryptionSubscriber");
+        this.fields = config.fields ?? new Map();
+    }
+    beforeInsert(event) {
+        this.encryptFields(event.entity);
+    }
+    beforeUpdate(event) {
+        if (event.entity) {
+            this.encryptFields(event.entity);
+        }
+    }
+    afterLoad(entity, event) {
+        void event;
+        this.decryptFields(entity);
+    }
+    getEntityName(entity) {
+        const ctor = entity?.constructor;
+        return ctor?.name && ctor.name !== "Object" ? ctor.name : undefined;
+    }
+    getFieldsFor(entity) {
+        const name = this.getEntityName(entity);
+        if (!name)
+            return { name: "", fields: [] };
+        return { name, fields: this.fields.get(name) ?? [] };
+    }
+    encryptFields(entity) {
+        const { name, fields } = this.getFieldsFor(entity);
+        for (const field of fields) {
+            const value = entity[field];
+            if (value === null || value === undefined)
+                continue;
+            const plaintext = typeof value === "string" ? value : JSON.stringify(value);
+            entity[field] = (0, codec_1.sealColumn)(this.codec, `${name}.${field}`, plaintext);
+        }
+    }
+    decryptFields(entity) {
+        const { name, fields } = this.getFieldsFor(entity);
+        for (const field of fields) {
+            const value = entity[field];
+            if (typeof value !== "string")
+                continue;
+            entity[field] = (0, codec_1.openColumn)(this.codec, `${name}.${field}`, value);
+        }
+    }
+}
+exports.EncryptionSubscriber = EncryptionSubscriber;
+//# sourceMappingURL=subscriber.js.map

package/dist/transformer.d.ts

@@ -0,0 +1,10 @@
+import type { ValueTransformer } from "typeorm";
+import type { EncryptionConfig } from "./types";
+export declare class EncryptionTransformer implements ValueTransformer {
+    private readonly codec;
+    private readonly context;
+    constructor(config: EncryptionConfig);
+    to(value: unknown): string | null;
+    from(value: unknown): string | null;
+}
+//# sourceMappingURL=transformer.d.ts.map

package/dist/transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformer.d.ts","sourceRoot":"","sources":["../src/transformer.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAOhD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AA0BhD,qBAAa,qBAAsB,YAAW,gBAAgB;IAE5D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IAEpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAOrB,MAAM,EAAE,gBAAgB;IAgBpC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAkBjC,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;CASpC"}

package/dist/transformer.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EncryptionTransformer = void 0;
+const codec_1 = require("./codec");
+class EncryptionTransformer {
+    codec;
+    context;
+    constructor(config) {
+        if (!config.key) {
+            throw new Error("EncryptionTransformer: key is required");
+        }
+        this.codec = (0, codec_1.createColumnCodec)(config);
+        this.context = config.context ?? "";
+    }
+    to(value) {
+        if (value === null || value === undefined) {
+            return null;
+        }
+        const plaintext = typeof value === "string" ? value : JSON.stringify(value);
+        return (0, codec_1.sealColumn)(this.codec, this.context, plaintext);
+    }
+    from(value) {
+        if (value === null || value === undefined) {
+            return null;
+        }
+        if (typeof value !== "string") {
+            return null;
+        }
+        return (0, codec_1.openColumn)(this.codec, this.context, value);
+    }
+}
+exports.EncryptionTransformer = EncryptionTransformer;
+//# sourceMappingURL=transformer.js.map

package/dist/types.d.ts

@@ -0,0 +1,9 @@
+export interface EncryptionConfig {
+    key: string;
+    algorithm?: string;
+    fields?: Map<string, string[]>;
+    context?: string;
+    allowPlaintextFallback?: boolean;
+    acceptLegacyCiphertext?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,gBAAgB;IAM/B,GAAG,EAAE,MAAM,CAAC;IAQZ,SAAS,CAAC,EAAE,MAAM,CAAC;IAenB,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAa/B,OAAO,CAAC,EAAE,MAAM,CAAC;IAUjB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IASjC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@sebastienrousseau/crypto-typeorm",
+  "version": "0.0.8",
+  "description": "TypeORM column-level encryption with a single decorator, powered by crypto-lib.",
+  "author": "Sebastien Rousseau <sebastienrousseau@users.noreply.github.com>",
+  "license": "MIT OR Apache-2.0",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map"
+  ],
+  "dependencies": {
+    "@sebastienrousseau/crypto-lib": "0.0.8"
+  },
+  "peerDependencies": {
+    "typeorm": "^1.1.1"
+  },
+  "devDependencies": {
+    "@sebastienrousseau/mocha-config": "^0.0.5",
+    "@types/chai": "^4.3.7",
+    "@types/chai-as-promised": "^8.0.2",
+    "@types/mocha": "^10.0.2",
+    "@types/node": "^26.6.3",
+    "c8": "^12.0.0",
+    "chai": "^4.5.0",
+    "chai-as-promised": "^7.1.2",
+    "mocha": "^10.8.2",
+    "rimraf": "^6.1.3",
+    "ts-node": "^10.9.2",
+    "typedoc": "^0.28.20",
+    "typeorm": "^1.1.1",
+    "typescript": "~5.9.3"
+  },
+  "keywords": [
+    "typeorm",
+    "encryption",
+    "column-encryption",
+    "crypto",
+    "decorator",
+    "transformer",
+    "subscriber",
+    "xchacha20-poly1305",
+    "secretbox"
+  ],
+  "homepage": "https://github.com/sebastienrousseau/crypto-service/tree/main/packages/crypto-typeorm",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sebastienrousseau/crypto-service.git",
+    "directory": "packages/crypto-typeorm"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "private": false,
+  "scripts": {
+    "build": "tsc --build tsconfig.json",
+    "clean": "rimraf ./coverage ./dist ./docs",
+    "test": "c8 --check-coverage --lines 100 --branches 100 --functions 100 --reporter=lcov --reporter=text mocha --config=.mocharc.cjs",
+    "docs": "typedoc",
+    "lint": "eslint --ext .ts src __tests__",
+    "lint:fix": "eslint --cache --fix --ext .ts src __tests__",
+    "format": "prettier --write src/**/*.ts",
+    "format:check": "prettier --check \"src/**/*.ts\""
+  }
+}