@dynamatix/gb-schemas 2.19.1 → 2.20.2

package/dist/shared/encryption/encryption-filter.guard.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Fail-loud guard for queries that touch RANDOM-encrypted fields.
+ *
+ * RANDOM ciphertext is unqueryable: any filter, equality, range, regex or
+ * sort on an encrypted path would silently match nothing (or garbage).
+ * The guard converts that class of production data bug into an immediate,
+ * descriptive error at the call site — in CI, not in front of a customer.
+ */
+export declare class EncryptionFilterGuard {
+    private constructor();
+    /**
+     * Asserts that neither the filter nor the sort of a query references an
+     * encrypted path. Recurses through `$and` / `$or` / `$nor` branches and
+     * flags parent-object matches (e.g. filtering on a whole subdocument
+     * that contains encrypted leaves).
+     *
+     * @param filter - The query filter as returned by `Query.getFilter()`.
+     * @param sort - The sort spec (object or string form) from query options.
+     * @param encryptedPaths - Dot paths of all encrypted fields of the model.
+     * @throws Error naming the offending path when the query is unsafe.
+     * @example
+     * ```ts
+     * EncryptionFilterGuard.assertQuerySafe(
+     *     { $or: [{ firstName: 'Ann' }] }, undefined, ['firstName']
+     * ); // → throws: firstName is RANDOM-encrypted and cannot be filtered
+     * ```
+     */
+    static assertQuerySafe(filter: Record<string, unknown> | null | undefined, sort: Record<string, unknown> | string | null | undefined, encryptedPaths: string[]): void;
+    /**
+     * Recursively walks one filter node, throwing on any encrypted-path key.
+     *
+     * @param node - Filter object or logical-operator branch.
+     * @param encryptedPaths - Dot paths of all encrypted fields.
+     * @throws Error when a key covers an encrypted path.
+     * @example
+     * ```ts
+     * // internal use only — called by assertQuerySafe()
+     * ```
+     */
+    private static walkFilter;
+    /**
+     * Asserts that no sort key covers an encrypted path (random ciphertext
+     * has no meaningful order).
+     *
+     * @param sort - Sort spec in object (`{ field: 1 }`) or string (`'-field'`) form.
+     * @param encryptedPaths - Dot paths of all encrypted fields.
+     * @throws Error when a sort key covers an encrypted path.
+     * @example
+     * ```ts
+     * // internal use only — called by assertQuerySafe()
+     * ```
+     */
+    private static assertSortSafe;
+    /**
+     * Matches a filter/sort key against the encrypted paths, including
+     * parent-object keys (`bankWizardCheck` covers its encrypted leaves)
+     * and child keys under an encrypted leaf.
+     *
+     * @param key - The filter or sort key to test.
+     * @param encryptedPaths - Dot paths of all encrypted fields.
+     * @returns The covered encrypted path, or `undefined` when safe.
+     * @example
+     * ```ts
+     * // internal use only
+     * ```
+     */
+    private static matchEncryptedPath;
+}
+//# sourceMappingURL=encryption-filter.guard.d.ts.map

package/dist/shared/encryption/encryption-filter.guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption-filter.guard.d.ts","sourceRoot":"","sources":["../../../shared/encryption/encryption-filter.guard.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qBAAa,qBAAqB;IAC9B,OAAO;IAEP;;;;;;;;;;;;;;;;OAgBG;WACW,eAAe,CACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAClD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EACzD,cAAc,EAAE,MAAM,EAAE,GACzB,IAAI;IAOP;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,UAAU;IAkBzB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAqB7B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;CAKpC"}

package/dist/shared/encryption/encryption-filter.guard.js

@@ -0,0 +1,103 @@
+/**
+ * Fail-loud guard for queries that touch RANDOM-encrypted fields.
+ *
+ * RANDOM ciphertext is unqueryable: any filter, equality, range, regex or
+ * sort on an encrypted path would silently match nothing (or garbage).
+ * The guard converts that class of production data bug into an immediate,
+ * descriptive error at the call site — in CI, not in front of a customer.
+ */
+export class EncryptionFilterGuard {
+    constructor() { }
+    /**
+     * Asserts that neither the filter nor the sort of a query references an
+     * encrypted path. Recurses through `$and` / `$or` / `$nor` branches and
+     * flags parent-object matches (e.g. filtering on a whole subdocument
+     * that contains encrypted leaves).
+     *
+     * @param filter - The query filter as returned by `Query.getFilter()`.
+     * @param sort - The sort spec (object or string form) from query options.
+     * @param encryptedPaths - Dot paths of all encrypted fields of the model.
+     * @throws Error naming the offending path when the query is unsafe.
+     * @example
+     * ```ts
+     * EncryptionFilterGuard.assertQuerySafe(
+     *     { $or: [{ firstName: 'Ann' }] }, undefined, ['firstName']
+     * ); // → throws: firstName is RANDOM-encrypted and cannot be filtered
+     * ```
+     */
+    static assertQuerySafe(filter, sort, encryptedPaths) {
+        EncryptionFilterGuard.assertSortSafe(sort, encryptedPaths);
+        if (filter) {
+            EncryptionFilterGuard.walkFilter(filter, encryptedPaths);
+        }
+    }
+    /**
+     * Recursively walks one filter node, throwing on any encrypted-path key.
+     *
+     * @param node - Filter object or logical-operator branch.
+     * @param encryptedPaths - Dot paths of all encrypted fields.
+     * @throws Error when a key covers an encrypted path.
+     * @example
+     * ```ts
+     * // internal use only — called by assertQuerySafe()
+     * ```
+     */
+    static walkFilter(node, encryptedPaths) {
+        for (const [key, value] of Object.entries(node)) {
+            if (key === '$and' || key === '$or' || key === '$nor') {
+                for (const branch of value ?? []) {
+                    EncryptionFilterGuard.walkFilter(branch, encryptedPaths);
+                }
+                continue;
+            }
+            const hit = EncryptionFilterGuard.matchEncryptedPath(key, encryptedPaths);
+            if (hit) {
+                throw new Error(`Query filter references '${key}': '${hit}' is RANDOM-encrypted and can never be ` +
+                    'filtered, matched or compared. Query a plaintext predicate field instead.');
+            }
+        }
+    }
+    /**
+     * Asserts that no sort key covers an encrypted path (random ciphertext
+     * has no meaningful order).
+     *
+     * @param sort - Sort spec in object (`{ field: 1 }`) or string (`'-field'`) form.
+     * @param encryptedPaths - Dot paths of all encrypted fields.
+     * @throws Error when a sort key covers an encrypted path.
+     * @example
+     * ```ts
+     * // internal use only — called by assertQuerySafe()
+     * ```
+     */
+    static assertSortSafe(sort, encryptedPaths) {
+        if (!sort) {
+            return;
+        }
+        const keys = typeof sort === 'string'
+            ? sort.split(/\s+/).filter(Boolean).map((key) => key.replace(/^-/, ''))
+            : Object.keys(sort);
+        for (const key of keys) {
+            const hit = EncryptionFilterGuard.matchEncryptedPath(key, encryptedPaths);
+            if (hit) {
+                throw new Error(`Sort key '${key}': '${hit}' is RANDOM-encrypted — ciphertext has no meaningful ` +
+                    'order. Sort on a plaintext field instead.');
+            }
+        }
+    }
+    /**
+     * Matches a filter/sort key against the encrypted paths, including
+     * parent-object keys (`bankWizardCheck` covers its encrypted leaves)
+     * and child keys under an encrypted leaf.
+     *
+     * @param key - The filter or sort key to test.
+     * @param encryptedPaths - Dot paths of all encrypted fields.
+     * @returns The covered encrypted path, or `undefined` when safe.
+     * @example
+     * ```ts
+     * // internal use only
+     * ```
+     */
+    static matchEncryptedPath(key, encryptedPaths) {
+        return encryptedPaths.find((path) => key === path || path.startsWith(`${key}.`) || key.startsWith(`${path}.`));
+    }
+}

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"}