@dynamatix/gb-schemas 2.17.13 → 2.20.1

package/dist/shared/encryption/encryption.config.js

@@ -0,0 +1,76 @@
+/**
+ * Immutable configuration for the field-level encryption layer.
+ *
+ * The master key is supplied via the `GH_ENCRYPTION_MASTER_KEY` environment
+ * variable as a base64-encoded 96-byte value and acts as the `local` KMS
+ * provider key for MongoDB Client-Side Field Level Encryption. Validation is
+ * fail-fast: a missing or malformed key throws at bootstrap so services never
+ * start half-configured. Key material is never echoed in error messages.
+ */
+export class EncryptionConfig {
+    constructor(
+    /** Decoded 96-byte master key used as the `local` KMS provider key. */
+    masterKey, 
+    /** `db.collection` namespace of the key vault. */
+    keyVaultNamespace, 
+    /** keyAltName used to resolve/provision the single shared DEK. */
+    keyAltName) {
+        this.masterKey = masterKey;
+        this.keyVaultNamespace = keyVaultNamespace;
+        this.keyAltName = keyAltName;
+    }
+    /**
+     * Builds a validated configuration from an environment map.
+     *
+     * @param env - Environment map, typically `process.env`.
+     * @returns A frozen, validated {@link EncryptionConfig}.
+     * @throws Error when the env var is missing, not base64, or not 96 bytes.
+     * @example
+     * ```ts
+     * const config = EncryptionConfig.load(process.env);
+     * const service = new EncryptionService(config);
+     * ```
+     */
+    static load(env) {
+        const raw = env[EncryptionConfig.MASTER_KEY_ENV_VAR];
+        if (!raw) {
+            throw new Error(`${EncryptionConfig.MASTER_KEY_ENV_VAR} is not set. ` +
+                'Provide a base64-encoded 96-byte master key.');
+        }
+        const masterKey = EncryptionConfig.decodeMasterKey(raw);
+        return new EncryptionConfig(masterKey, EncryptionConfig.KEY_VAULT_NAMESPACE, EncryptionConfig.KEY_ALT_NAME);
+    }
+    /**
+     * Decodes and validates the base64 master key without ever including the
+     * supplied value in error messages.
+     *
+     * @param raw - Raw base64 string from the environment.
+     * @returns The decoded 96-byte key.
+     * @throws Error when the value is not strict base64 or has a wrong length.
+     * @example
+     * ```ts
+     * // internal use only — called by EncryptionConfig.load()
+     * ```
+     */
+    static decodeMasterKey(raw) {
+        const decoded = Buffer.from(raw, 'base64');
+        if (decoded.length === 0 || decoded.toString('base64') !== raw.replace(/\s/g, '')) {
+            throw new Error(`${EncryptionConfig.MASTER_KEY_ENV_VAR} is not valid base64. ` +
+                '(value withheld from this message)');
+        }
+        if (decoded.length !== EncryptionConfig.MASTER_KEY_BYTES) {
+            throw new Error(`${EncryptionConfig.MASTER_KEY_ENV_VAR} must decode to exactly ` +
+                `${EncryptionConfig.MASTER_KEY_BYTES} bytes, got ${decoded.length}. ` +
+                '(value withheld from this message)');
+        }
+        return decoded;
+    }
+}
+/** Fixed key vault namespace shared by every Gatehouse service. */
+EncryptionConfig.KEY_VAULT_NAMESPACE = 'encryption.__keyVault';
+/** Alt name of the single shared data encryption key (DEK). */
+EncryptionConfig.KEY_ALT_NAME = 'gatehouse-dek';
+/** Name of the environment variable carrying the master key. */
+EncryptionConfig.MASTER_KEY_ENV_VAR = 'GH_ENCRYPTION_MASTER_KEY';
+/** Required master key length in bytes for the `local` KMS provider. */
+EncryptionConfig.MASTER_KEY_BYTES = 96;

package/dist/shared/encryption/encryption.init.d.ts

@@ -0,0 +1,66 @@
+import { MongoClient } from 'mongodb';
+import { EncryptionService } from './encryption.service.js';
+/**
+ * Process-wide bootstrap for the encryption layer, mirroring the
+ * `initializeWorkflowMiddleware` pattern used elsewhere in this package.
+ *
+ * Consumer services call {@link EncryptionBootstrap.initialize} exactly once
+ * at startup (right after connecting to MongoDB); everything else — the
+ * Mongoose plugin, repositories, adapters — obtains the shared singleton via
+ * {@link EncryptionBootstrap.getService}.
+ */
+export declare class EncryptionBootstrap {
+    private static service;
+    private constructor();
+    /**
+     * Initializes the singleton {@link EncryptionService} from the
+     * environment and a connected client. Idempotent: repeated calls return
+     * the already-initialized instance.
+     *
+     * @param client - A connected {@link MongoClient}.
+     * @param env - Environment map, defaults to `process.env`.
+     * @returns The initialized singleton service.
+     * @throws Error when `GH_ENCRYPTION_MASTER_KEY` is missing or malformed.
+     * @example
+     * ```ts
+     * await mongoose.connect(uri);
+     * await EncryptionBootstrap.initialize(
+     *     mongoose.connection.getClient() as unknown as MongoClient
+     * );
+     * ```
+     */
+    static initialize(client: MongoClient, env?: Record<string, string | undefined>): Promise<EncryptionService>;
+    /**
+     * Returns the initialized singleton service.
+     *
+     * @returns The shared {@link EncryptionService}.
+     * @throws Error when called before {@link initialize}.
+     * @example
+     * ```ts
+     * const ciphertext = await EncryptionBootstrap.getService().encrypt(value);
+     * ```
+     */
+    static getService(): EncryptionService;
+    /**
+     * Reports whether the encryption layer has been bootstrapped.
+     *
+     * @returns `true` after a successful {@link initialize} call.
+     * @example
+     * ```ts
+     * if (!EncryptionBootstrap.isInitialized()) {
+     *     await EncryptionBootstrap.initialize(client);
+     * }
+     * ```
+     */
+    static isInitialized(): boolean;
+    /**
+     * Tears down the singleton (used by tests and graceful shutdown).
+     *
+     * @example
+     * ```ts
+     * await EncryptionBootstrap.reset();
+     * ```
+     */
+    static reset(): Promise<void>;
+}
+//# sourceMappingURL=encryption.init.d.ts.map

package/dist/shared/encryption/encryption.init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.init.d.ts","sourceRoot":"","sources":["../../../shared/encryption/encryption.init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;;;;;GAQG;AACH,qBAAa,mBAAmB;IAC5B,OAAO,CAAC,MAAM,CAAC,OAAO,CAAkC;IAExD,OAAO;IAEP;;;;;;;;;;;;;;;;OAgBG;WACiB,UAAU,CAC1B,MAAM,EAAE,WAAW,EACnB,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACtD,OAAO,CAAC,iBAAiB,CAAC;IAU7B;;;;;;;;;OASG;WACW,UAAU,IAAI,iBAAiB;IAU7C;;;;;;;;;;OAUG;WACW,aAAa,IAAI,OAAO;IAItC;;;;;;;OAOG;WACiB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAM7C"}

package/dist/shared/encryption/encryption.init.js

@@ -0,0 +1,86 @@
+import { EncryptionConfig } from './encryption.config.js';
+import { EncryptionService } from './encryption.service.js';
+/**
+ * Process-wide bootstrap for the encryption layer, mirroring the
+ * `initializeWorkflowMiddleware` pattern used elsewhere in this package.
+ *
+ * Consumer services call {@link EncryptionBootstrap.initialize} exactly once
+ * at startup (right after connecting to MongoDB); everything else — the
+ * Mongoose plugin, repositories, adapters — obtains the shared singleton via
+ * {@link EncryptionBootstrap.getService}.
+ */
+export class EncryptionBootstrap {
+    constructor() { }
+    /**
+     * Initializes the singleton {@link EncryptionService} from the
+     * environment and a connected client. Idempotent: repeated calls return
+     * the already-initialized instance.
+     *
+     * @param client - A connected {@link MongoClient}.
+     * @param env - Environment map, defaults to `process.env`.
+     * @returns The initialized singleton service.
+     * @throws Error when `GH_ENCRYPTION_MASTER_KEY` is missing or malformed.
+     * @example
+     * ```ts
+     * await mongoose.connect(uri);
+     * await EncryptionBootstrap.initialize(
+     *     mongoose.connection.getClient() as unknown as MongoClient
+     * );
+     * ```
+     */
+    static async initialize(client, env = process.env) {
+        if (EncryptionBootstrap.service) {
+            return EncryptionBootstrap.service;
+        }
+        const service = new EncryptionService(EncryptionConfig.load(env));
+        await service.init(client);
+        EncryptionBootstrap.service = service;
+        return service;
+    }
+    /**
+     * Returns the initialized singleton service.
+     *
+     * @returns The shared {@link EncryptionService}.
+     * @throws Error when called before {@link initialize}.
+     * @example
+     * ```ts
+     * const ciphertext = await EncryptionBootstrap.getService().encrypt(value);
+     * ```
+     */
+    static getService() {
+        if (!EncryptionBootstrap.service) {
+            throw new Error('Encryption is not initialized. Call EncryptionBootstrap.initialize(client) ' +
+                '(initializeEncryption) at service bootstrap first.');
+        }
+        return EncryptionBootstrap.service;
+    }
+    /**
+     * Reports whether the encryption layer has been bootstrapped.
+     *
+     * @returns `true` after a successful {@link initialize} call.
+     * @example
+     * ```ts
+     * if (!EncryptionBootstrap.isInitialized()) {
+     *     await EncryptionBootstrap.initialize(client);
+     * }
+     * ```
+     */
+    static isInitialized() {
+        return EncryptionBootstrap.service !== null;
+    }
+    /**
+     * Tears down the singleton (used by tests and graceful shutdown).
+     *
+     * @example
+     * ```ts
+     * await EncryptionBootstrap.reset();
+     * ```
+     */
+    static async reset() {
+        if (EncryptionBootstrap.service) {
+            await EncryptionBootstrap.service.close();
+            EncryptionBootstrap.service = null;
+        }
+    }
+}
+EncryptionBootstrap.service = null;

package/dist/shared/encryption/encryption.plugin.d.ts

@@ -0,0 +1,225 @@
+/// <reference path="../../value-objects/pound.d.ts" />
+/// <reference path="../../value-objects/account-number.d.ts" />
+/// <reference path="encrypted-field-map.d.ts" />
+/// <reference path="../../value-objects/sort-code.d.ts" />
+/// <reference types="mongoose/types/aggregate.js" />
+/// <reference types="mongoose/types/callback.js" />
+/// <reference types="mongoose/types/collection.js" />
+/// <reference types="mongoose/types/connection.js" />
+/// <reference types="mongoose/types/cursor.js" />
+/// <reference types="mongoose/types/document.js" />
+/// <reference types="mongoose/types/error.js" />
+/// <reference types="mongoose/types/expressions.js" />
+/// <reference types="mongoose/types/helpers.js" />
+/// <reference types="mongoose/types/middlewares.js" />
+/// <reference types="mongoose/types/indexes.js" />
+/// <reference types="mongoose/types/models.js" />
+/// <reference types="mongoose/types/mongooseoptions.js" />
+/// <reference types="mongoose/types/pipelinestage.js" />
+/// <reference types="mongoose/types/populate.js" />
+/// <reference types="mongoose/types/query.js" />
+/// <reference types="mongoose/types/schemaoptions.js" />
+/// <reference types="mongoose/types/session.js" />
+/// <reference types="mongoose/types/types.js" />
+/// <reference types="mongoose/types/utility.js" />
+/// <reference types="mongoose/types/validation.js" />
+/// <reference types="mongoose/types/virtuals.js" />
+/// <reference types="mongoose/types/schematypes.js" />
+/// <reference types="mongoose/types/inferschematype.js" />
+/// <reference types="mongoose/types/inferrawdoctype.js" />
+import { Schema } from 'mongoose';
+/**
+ * Global Mongoose plugin routing `ghEncrypt: true` fields through the
+ * {@link EncryptionService} — plumbing only, no crypto in hooks.
+ *
+ * Write hooks (`save`, `insertMany`, update/replace queries) encrypt
+ * annotated values to BSON Binary subtype 6; read hooks (`find`, `findOne`,
+ * `findOneAnd*`, `distinct`) decrypt hydrated docs and `.lean()` results.
+ * Filters and sorts on encrypted paths fail loud via
+ * {@link EncryptionFilterGuard}. When {@link EncryptionBootstrap} is not
+ * initialized, every hook is a transparent pass-through so consumers that
+ * have not opted in keep working on plaintext.
+ *
+ * Annotated paths are re-typed to `Mixed` (original type stashed in
+ * `ghOriginalType`) so ciphertext survives Mongoose casting. Aggregation is
+ * not interceptable and is handled per call site (Enc-5).
+ */
+export declare class EncryptionPlugin {
+    private constructor();
+    /**
+     * Applies the plugin to a schema: validates and collects annotated
+     * paths, re-types them to `Mixed`, and registers guard/write/read hooks.
+     * No-op for schemas without annotations; safe to call more than once
+     * (encrypt/decrypt transforms are idempotent).
+     *
+     * @param schema - The Mongoose schema to instrument.
+     * @example
+     * ```ts
+     * const applicantSchema = new mongoose.Schema({
+     *     firstName: { type: String, ghEncrypt: true }
+     * });
+     * EncryptionPlugin.apply(applicantSchema);
+     * ```
+     */
+    static apply(schema: Schema): void;
+    /**
+     * Re-types one annotated path to `Mixed` so Binary ciphertext is not
+     * mangled by the original String/Number cast, stashing the original
+     * BSON type in `ghOriginalType` for the field-map/tooling.
+     *
+     * @param schema - The owning schema.
+     * @param entry - The annotated path being re-typed.
+     * @example
+     * ```ts
+     * // internal use only — called by apply()
+     * ```
+     */
+    private static retypeToMixed;
+    /**
+     * Registers fail-loud filter/sort guards on every query hook.
+     *
+     * @param schema - The owning schema.
+     * @param paths - Encrypted dot paths of the schema.
+     * @example
+     * ```ts
+     * // internal use only — called by apply()
+     * ```
+     */
+    private static registerGuardHooks;
+    /**
+     * Registers encrypt-on-write hooks: `save`, `insertMany` and the
+     * update/replace query family (`$set`, `$setOnInsert`, dot paths,
+     * parent-object values and full replacement docs).
+     *
+     * @param schema - The owning schema.
+     * @param paths - Encrypted dot paths of the schema.
+     * @example
+     * ```ts
+     * // internal use only — called by apply()
+     * ```
+     */
+    private static registerWriteHooks;
+    /**
+     * Registers decrypt-on-read hooks: `find`, the `findOne*` family,
+     * `distinct`, plus post-`save`/`insertMany` restores so callers keep
+     * seeing plaintext on the documents they just persisted.
+     *
+     * @param schema - The owning schema.
+     * @param paths - Encrypted dot paths of the schema.
+     * @example
+     * ```ts
+     * // internal use only — called by apply()
+     * ```
+     */
+    private static registerReadHooks;
+    /**
+     * Encrypts annotated values inside an update object: exact dot-path
+     * keys, parent-object values containing encrypted leaves, and full
+     * replacement documents (updates without atomic operators).
+     *
+     * @param update - The mutable update object from `Query.getUpdate()`.
+     * @param paths - Encrypted dot paths of the schema.
+     * @example
+     * ```ts
+     * // internal use only — called by the update-query pre hook
+     * ```
+     */
+    private static encryptUpdate;
+    /**
+     * Applies a value transform to every encrypted path of one target,
+     * dispatching between hydrated documents (getter-free `get`/`set`) and
+     * plain objects (`.lean()` results, insert payloads).
+     *
+     * @param target - Hydrated document or plain object; non-objects no-op.
+     * @param paths - Encrypted dot paths of the schema.
+     * @param transform - Value transform (encrypt or decrypt).
+     * @example
+     * ```ts
+     * // internal use only
+     * ```
+     */
+    private static transformTarget;
+    /**
+     * Applies a transform to every encrypted path of one hydrated document.
+     *
+     * @param doc - The hydrated Mongoose document.
+     * @param paths - Encrypted dot paths of the schema.
+     * @param transform - Value transform (encrypt or decrypt).
+     * @example
+     * ```ts
+     * // internal use only
+     * ```
+     */
+    private static transformDocument;
+    /**
+     * Transforms one dot path on a hydrated document, reading with getters
+     * disabled so value-object formatters never leak into ciphertext.
+     *
+     * @param doc - The hydrated Mongoose document.
+     * @param path - Encrypted dot path.
+     * @param transform - Value transform (encrypt or decrypt).
+     * @example
+     * ```ts
+     * // internal use only
+     * ```
+     */
+    private static transformDocPath;
+    /**
+     * Transforms one segmented path on a plain object, descending nested
+     * objects and fanning out over arrays.
+     *
+     * @param target - Plain object (or array element) being walked.
+     * @param segments - Remaining path segments.
+     * @param transform - Value transform (encrypt or decrypt).
+     * @example
+     * ```ts
+     * // internal use only
+     * ```
+     */
+    private static transformPlain;
+    /**
+     * Builds the encrypt transform: plaintext → Binary; ciphertext and the
+     * uninitialized-bootstrap case pass through untouched.
+     *
+     * @returns Async value transform used by all write hooks.
+     * @example
+     * ```ts
+     * // internal use only
+     * ```
+     */
+    private static encryptTransform;
+    /**
+     * Builds the decrypt transform: Binary → plaintext; non-ciphertext and
+     * the uninitialized-bootstrap case pass through untouched.
+     *
+     * @returns Async value transform used by all read hooks.
+     * @example
+     * ```ts
+     * // internal use only
+     * ```
+     */
+    private static decryptTransform;
+    /**
+     * Returns the bootstrapped service, or `null` when encryption is not
+     * initialized (pass-through mode for non-opted-in consumers).
+     *
+     * @returns The active {@link EncryptionService} or `null`.
+     * @example
+     * ```ts
+     * // internal use only
+     * ```
+     */
+    private static activeService;
+    /**
+     * Duck-type check for BSON Binary subtype 6 (encrypted) values.
+     *
+     * @param value - Candidate value.
+     * @returns `true` when the value is ciphertext.
+     * @example
+     * ```ts
+     * // internal use only
+     * ```
+     */
+    private static isCiphertext;
+}
+//# sourceMappingURL=encryption.plugin.d.ts.map

package/dist/shared/encryption/encryption.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.plugin.d.ts","sourceRoot":"","sources":["../../../shared/encryption/encryption.plugin.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,OAAO,EAAE,MAAM,EAAmB,MAAM,UAAU,CAAC;AAuBnD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAgB;IACzB,OAAO;IAEP;;;;;;;;;;;;;;OAcG;WACW,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAczC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAc5B;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAUjC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAiBjC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAgChC;;;;;;;;;;;OAWG;mBACkB,aAAa;IA0BlC;;;;;;;;;;;;OAYG;mBACkB,eAAe;IAiBpC;;;;;;;;;;OAUG;mBACkB,iBAAiB;IAQtC;;;;;;;;;;;OAWG;mBACkB,gBAAgB;IAarC;;;;;;;;;;;OAWG;mBACkB,cAAc;IAuBnC;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAU/B;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAU/B;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAI5B;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;CAO9B"}