zibri 2.3.0 → 2.4.1

package/src/auth/encryption/encryption.utilities.ts

@@ -0,0 +1,65 @@
+
+/**
+ * A string with encrypted data stored inside of it.
+ */
+export type EncryptionString = string & {
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    __brand: 'encryption'
+};
+
+/**
+ * The content stored inside an encryption string.
+ */
+export type EncryptionContent = {
+    /**
+     * The name of the encryption strategy.
+     */
+    strategyName: string,
+    /**
+     * The version of the encryption strategy.
+     */
+    version: string,
+    /**
+     * The id of the key that has been used.
+     */
+    keyId: string,
+    /**
+     * The actual encrypted value.
+     */
+    encryptedValue: string
+};
+
+/**
+ * Utilities around handling encryption.
+ */
+export abstract class EncryptionUtilities {
+    /**
+     * Creates an encryption string from the given content.
+     * @param data - The content to store inside the encryption string.
+     * @returns The encryption string in the form "strategyName.version.encryptedValue".
+     */
+    static contentToEncryptionString(data: EncryptionContent): EncryptionString {
+        return [data.strategyName, data.version, data.keyId, data.encryptedValue].join('.') as EncryptionString;
+    }
+    /**
+     * Resolves the content of the given encryption string.
+     * @param encrypted - The encryption string to resolve the content of.
+     * @returns The encryption content inside the given string.
+     * @throws If the encryption string is invalid.
+     */
+    static encryptionStringToContent(encrypted: EncryptionString): EncryptionContent {
+        const [strategyName, version, keyId, ...encryptedValueParts] = encrypted.split('.');
+        const encryptedValue: string = encryptedValueParts.join('.');
+
+        if (!strategyName || !version || !keyId || !encryptedValue) {
+            throw new Error('Invalid encryption string');
+        }
+
+        return {
+            strategyName,
+            version,
+            keyId,
+            encryptedValue
+        };
+    }
+}

package/src/auth/encryption/strategies/aes-gcm.encryption-strategy.ts

@@ -0,0 +1,115 @@
+import { CipherGCM, CipherGCMTypes, createCipheriv, createDecipheriv, DecipherGCM, randomBytes } from 'node:crypto';
+
+import { EncryptionContent, EncryptionString, EncryptionUtilities } from '../encryption.utilities';
+import { BaseDecryptOptions, BaseEncryptOptions, EncryptionStrategyInterface } from './encryption-strategy.interface';
+
+/**
+ * Options for encrypting with the default aes-256-gcm encryption strategy implementation of Zibri.
+ */
+type AesGcmEncryptOptions = BaseEncryptOptions<Buffer> & {
+    /**
+     * The "Additional authenticated data" can be used to store something like a user id
+     * on the encrypted value that needs to be provided when decrypting.
+     */
+    aad?: string
+};
+
+/**
+ * Options for encrypting with the default aes-256-gcm encryption strategy implementation of Zibri.
+ */
+type AesGcmDecryptOptions = BaseDecryptOptions<Buffer> & {
+    /**
+     * The "Additional authenticated data" can be used to store something like a user id
+     * on the encrypted value that needs to be provided when decrypting.
+     */
+    aad?: string
+};
+
+/**
+ * Default aes-256-gcm encryption strategy implementation of Zibri.
+ */
+export class AesGcmEncryptionStrategy implements EncryptionStrategyInterface<
+    Buffer,
+    AesGcmEncryptOptions,
+    AesGcmDecryptOptions
+> {
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly name: CipherGCMTypes = 'aes-256-gcm';
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly version: string = 'v1';
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    encrypt(value: string, options: AesGcmEncryptOptions): EncryptionString {
+        const iv: Buffer = randomBytes(12);
+        const cipher: CipherGCM = createCipheriv(this.name, options.key, iv);
+
+        if (options.aad !== undefined) {
+            cipher.setAAD(Buffer.from(options.aad, 'utf8'));
+        }
+
+        const encrypted: Buffer = Buffer.concat([
+            cipher.update(value, 'utf8'),
+            cipher.final()
+        ]);
+
+        const tag: Buffer = cipher.getAuthTag();
+
+        const encryptedValue: string = [
+            iv.toString('base64'),
+            tag.toString('base64'),
+            encrypted.toString('base64')
+        ].join('.');
+
+        return EncryptionUtilities.contentToEncryptionString({
+            version: this.version,
+            strategyName: this.name,
+            keyId: options.keyId,
+            encryptedValue
+        });
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    decrypt(value: EncryptionString, options: AesGcmDecryptOptions): string {
+        const content: EncryptionContent = EncryptionUtilities.encryptionStringToContent(value);
+        const [ivB64, tagB64, ...contentB64Parts] = content.encryptedValue.split('.');
+
+        const contentB64: string = contentB64Parts.join('.');
+        if (!ivB64 || !tagB64 || !contentB64) {
+            throw new Error('Invalid encrypted value');
+        }
+
+        const decipher: DecipherGCM = createDecipheriv(
+            this.name,
+            options.key,
+            Buffer.from(ivB64, 'base64')
+        );
+
+        if (options.aad !== undefined) {
+            decipher.setAAD(Buffer.from(options.aad, 'utf8'));
+        }
+
+        decipher.setAuthTag(Buffer.from(tagB64, 'base64'));
+
+        const decrypted: Buffer = Buffer.concat([
+            decipher.update(Buffer.from(contentB64, 'base64')),
+            decipher.final()
+        ]);
+
+        return decrypted.toString('utf8');
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    generateRandomKey(): Buffer {
+        return randomBytes(32);
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    serializeKey(key: Buffer): Buffer {
+        return key;
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    deserializeKey(raw: Buffer): Buffer {
+        return raw;
+    }
+}

package/src/auth/encryption/strategies/encryption-strategy-entity.model.ts

@@ -0,0 +1,52 @@
+import { BaseEntity } from '../../../entity/base-entity.model';
+import { Entity } from '../../../entity/decorators/entity.decorator';
+import { Property } from '../../../entity/decorators/property.decorator';
+import { OmitStrict } from '../../../types/omit-strict.type';
+import { EncryptionKey, EncryptionKeyCreateData } from '../encryption-key.model';
+
+/**
+ * The status that an encryption strategy can have.
+ */
+export enum EncryptionStrategyStatus {
+    ACTIVE = 'ACTIVE',
+    DEFAULT = 'DEFAULT',
+    DEPRECATED = 'DEPRECATED'
+}
+
+/**
+ * The encryption strategy entity that is stored in the db.
+ */
+@Entity({ allowOrphan: true })
+export class EncryptionStrategyEntity extends BaseEntity {
+    /**
+     * The name of the strategy.
+     */
+    @Property.string()
+    name!: string;
+    /**
+     * The version of the strategy.
+     */
+    @Property.string()
+    version!: string;
+    /**
+     * The status of the strategy.
+     */
+    @Property.string({ enum: EncryptionStrategyStatus })
+    status!: EncryptionStrategyStatus;
+    /**
+     * The keys for this strategy.
+     */
+    @Property.oneToMany({ target: () => EncryptionKey, inverseSide: 'strategy' })
+    keys!: EncryptionKey[];
+}
+
+/**
+ * The data for creating a new encryption strategy.
+ */
+export type EncryptionStrategyEntityCreateData = OmitStrict<EncryptionStrategyEntity, 'id' | 'keys'>
+    & {
+        /**
+         * The keys for this strategy.
+         */
+        keys: EncryptionKeyCreateData[]
+    };

package/src/auth/encryption/strategies/encryption-strategy.interface.ts

@@ -0,0 +1,67 @@
+import { EncryptionString } from '../encryption.utilities';
+
+/**
+ * The base options required for encrypting a value.
+ */
+export type BaseEncryptOptions<TKey> = {
+    /**
+     * The id of the key to use.
+     */
+    keyId: string,
+    /**
+     * The actual key value.
+     */
+    key: TKey
+};
+
+/**
+ * The base options required for decrypting a value.
+ */
+export type BaseDecryptOptions<TKey> = {
+    /**
+     * The id of the key to use.
+     */
+    keyId: string,
+    /**
+     * The actual key value.
+     */
+    key: TKey
+};
+
+/**
+ * Interface for an encryption strategy.
+ */
+export interface EncryptionStrategyInterface<
+    TKey,
+    TEncryptOptions extends BaseEncryptOptions<TKey> = BaseEncryptOptions<TKey>,
+    TDecryptOptions extends BaseDecryptOptions<TKey> = BaseDecryptOptions<TKey>
+> {
+    /**
+     * The name of the strategy.
+     */
+    readonly name: string,
+    /**
+     * The version of the strategy.
+     */
+    readonly version: string,
+    /**
+     * Encrypts the given value with the given options.
+     */
+    encrypt: (value: string, options: TEncryptOptions) => EncryptionString | Promise<EncryptionString>,
+    /**
+     * Decrypts the given value with the given options.
+     */
+    decrypt: (value: EncryptionString, options: TDecryptOptions) => string | Promise<string>,
+    /**
+     * Generates a new random key.
+     */
+    generateRandomKey: () => TKey | Promise<TKey>,
+    /**
+     * Serializes the given key into a Buffer.
+     */
+    serializeKey: (key: TKey) => Buffer | Promise<Buffer>,
+    /**
+     * Resolves a key from the given Buffer.
+     */
+    deserializeKey: (raw: Buffer) => TKey | Promise<TKey>
+}

package/src/auth/hash/hash-service.interface.ts

@@ -0,0 +1,39 @@
+import { HashString } from './hash.utilities';
+import { HashStrategyInterface } from './strategies/hash-strategy.interface';
+import { AnyObject } from '../../entity/any-object.model';
+import { Newable } from '../../types/newable.type';
+
+/**
+ * Options for hashing a value.
+ */
+export type HashOptions<THashOptions extends AnyObject> = {
+    /**
+     * The strategy to use.
+     */
+    strategy: Newable<HashStrategyInterface<THashOptions>>,
+    /**
+     * Options for the strategy.
+     */
+    strategyOptions?: THashOptions
+};
+
+/**
+ * Interface for a hash service.
+ */
+export interface HashServiceInterface {
+    /**
+     * Hashes the given value with the given options.
+     */
+    hash: <THashOptions extends AnyObject>(
+        value: string,
+        options?: HashOptions<THashOptions>
+    ) => HashString | Promise<HashString>,
+    /**
+     * Checks whether or not the given value equals the given hash.
+     */
+    equal: (value: string, hash: HashString) => boolean | Promise<boolean>,
+    /**
+     * Checks if the given hash should  be rehashed.
+     */
+    needsRehash: (hash: HashString) => boolean | Promise<boolean>
+}

package/src/auth/hash/hash.service.test.ts

@@ -0,0 +1,60 @@
+import { afterAll, beforeAll, describe, expect, test } from '@jest/globals';
+
+import { HashService } from './hash.service';
+import { HashString } from './hash.utilities';
+import { HashStrategyEntity, HashStrategyStatus } from './strategies/hash-strategy-entity.model';
+import { StartedTestServer, startTestServer } from '../../__testing__/test-server/start-test-server.function';
+import { Repository } from '../../data-source/repository';
+import { repositoryTokenFor } from '../../di/decorators/inject-repository.decorator';
+import { ZIBRI_DI_TOKENS } from '../../di/default/zibri-di-tokens.default';
+import { inject } from '../../di/inject.function';
+
+describe('HashService', () => {
+    let server: StartedTestServer;
+    let hashService: HashService;
+    let strategyRepository: Repository<HashStrategyEntity>;
+
+    beforeAll(async () => {
+        server = await startTestServer();
+        strategyRepository = inject(repositoryTokenFor(HashStrategyEntity));
+        hashService = inject(ZIBRI_DI_TOKENS.HASH_SERVICE) as HashService;
+    }, 15000);
+
+    afterAll(async () => {
+        await server?.shutdown();
+    });
+
+    test('creates strategy metadata on first hash', async () => {
+        const strategiesBeforeHash: HashStrategyEntity[] = await strategyRepository.findAll();
+        expect(strategiesBeforeHash).toHaveLength(0);
+
+        const hashed: HashString = await hashService.hash('hello');
+        expect(hashed).toBeTruthy();
+
+        const strategies: HashStrategyEntity[] = await strategyRepository.findAll();
+        expect(strategies).toHaveLength(1);
+        expect(strategies[0]).toMatchObject({
+            status: HashStrategyStatus.DEFAULT
+        });
+    });
+
+    test('does not duplicate strategy metadata on subsequent hashes', async () => {
+        await hashService.hash('first');
+        await hashService.hash('second');
+
+        const strategies: HashStrategyEntity[] = await strategyRepository.findAll();
+        expect(strategies).toHaveLength(1);
+    });
+
+    test('verifies a hash correctly', async () => {
+        const hashed: HashString = await hashService.hash('secret');
+
+        await expect(hashService.equal('secret', hashed)).resolves.toBe(true);
+        await expect(hashService.equal('wrong', hashed)).resolves.toBe(false);
+    });
+
+    test('detects whether a hash needs rehashing', async () => {
+        const hashed: HashString = await hashService.hash('secret');
+        expect(await hashService.needsRehash(hashed)).toBe(false);
+    });
+});

package/src/auth/hash/hash.service.ts

@@ -0,0 +1,164 @@
+import { HashOptions, HashServiceInterface } from './hash-service.interface';
+import { HashContent, HashString, HashUtilities } from './hash.utilities';
+import { HashStrategyEntity, HashStrategyEntityCreateData, HashStrategyStatus } from './strategies/hash-strategy-entity.model';
+import { HashStrategyInterface } from './strategies/hash-strategy.interface';
+import { Repository } from '../../data-source/repository';
+import { InjectRepository } from '../../di/decorators/inject-repository.decorator';
+import { Inject } from '../../di/decorators/inject.decorator';
+import { Injectable } from '../../di/decorators/injectable.decorator';
+import { ZIBRI_DI_TOKENS } from '../../di/default/zibri-di-tokens.default';
+import { inject } from '../../di/inject.function';
+import { register } from '../../di/register.function';
+import { OnAppInit } from '../../global/on-app-init.interface';
+import type { Newable } from '../../types/newable.type';
+
+/**
+ * Default hash service implementation of Zibri.
+ */
+@Injectable({ register: 'onUse' })
+export class HashService implements HashServiceInterface, OnAppInit {
+    private readonly strategies: HashStrategyInterface<Record<string, unknown>>[] = [];
+
+    private hasCreatedInitialDefaultStrategy: boolean = false;
+
+    constructor(
+        @InjectRepository(HashStrategyEntity)
+        private readonly hashStrategyRepository: Repository<HashStrategyEntity, HashStrategyEntityCreateData>,
+        @Inject(ZIBRI_DI_TOKENS.HASH_STRATEGIES)
+        private readonly hashStrategies: Newable<HashStrategyInterface<Record<string, unknown>>>[]
+    ) {}
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    async onAppInit(): Promise<void> {
+        if (!this.hashStrategies.length) {
+            throw new Error('Needs to provide at least one hash strategy.');
+        }
+        for (const strategy of this.hashStrategies) {
+            register({ token: strategy, useClass: strategy });
+            this.strategies.push(inject(strategy));
+        }
+        this.validateNoDuplicateHashStrategy();
+        await this.validateNoMissingHashStrategy();
+        this.validateStrategyNamesAndVersions();
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    async hash<THashOptions extends Record<string, unknown>>(
+        value: string,
+        options?: HashOptions<THashOptions>
+    ): Promise<HashString> {
+        if (!options) {
+            const strategy: HashStrategyInterface<Record<string, unknown>> = await this.findDefaultStrategy();
+            if (!this.hasCreatedInitialDefaultStrategy && !(await this.hashStrategyRepository.findAll()).length) {
+                await this.hashStrategyRepository.create({
+                    name: strategy.name,
+                    version: strategy.version,
+                    status: HashStrategyStatus.DEFAULT
+                });
+                this.hasCreatedInitialDefaultStrategy = true;
+            }
+            else if (!(await this.hashStrategyRepository.findAll({ where: { name: strategy.name, version: strategy.version } })).length) {
+                await this.hashStrategyRepository.create({
+                    name: strategy.name,
+                    version: strategy.version,
+                    status: HashStrategyStatus.ACTIVE
+                });
+            }
+            return await strategy.hash(value, options);
+        }
+
+        const strategy: HashStrategyInterface<Record<string, unknown>> | undefined = this.strategies.find(
+            s => s instanceof options.strategy
+        );
+        if (!strategy) {
+            throw new Error(`The given strategy ${options.strategy.name} was not provided as part of ZIBRI_DI_TOKENS.HASH_STRATEGIES`);
+        }
+        return await strategy.hash(value, options.strategyOptions);
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    async equal(value: string, hash: HashString): Promise<boolean> {
+        const strategy: HashStrategyInterface<Record<string, unknown>> = this.findStrategyForHash(hash);
+        return await strategy.equal(value, hash);
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    async needsRehash(hash: HashString): Promise<boolean> {
+        const strategy: HashStrategyInterface<Record<string, unknown>> = this.findStrategyForHash(hash);
+        return (await this.hashStrategyRepository.findOne(
+            { where: { name: strategy.name, version: strategy.version } }
+        )).status === HashStrategyStatus.DEPRECATED;
+    }
+
+    private findStrategy(name: string, version: string): HashStrategyInterface<Record<string, unknown>> {
+        const res: HashStrategyInterface<Record<string, unknown>> | undefined = this.strategies.find(
+            s => s.name === name && s.version === version
+        );
+        if (!res) {
+            throw new Error(`No strategy found for ${name} (${version})`);
+        }
+        return res;
+    }
+
+    private async findDefaultStrategy(): Promise<HashStrategyInterface<Record<string, unknown>>> {
+        const entity: HashStrategyEntity | undefined = await this.hashStrategyRepository.findOne(
+            { where: { status: HashStrategyStatus.DEFAULT } },
+            false
+        );
+        return entity
+            ? this.findStrategy(entity.name, entity.version)
+            : this.strategies[0];
+    }
+
+    private findStrategyForHash(hash: HashString): HashStrategyInterface<Record<string, unknown>> {
+        const content: HashContent = HashUtilities.hashToContent(hash);
+        return this.findStrategy(content.strategyName, content.version);
+    }
+
+    private validateNoDuplicateHashStrategy(): void {
+        // validate that there is no strategy with the same name and version
+        const duplicateStrategies: HashStrategyInterface<Record<string, unknown>>[] = this.strategies.filter(
+            s => this.strategies.filter(hs => hs.name === s.name && hs.version === s.version).length > 1
+        );
+        if (duplicateStrategies.length) {
+            throw new Error(
+                [
+                    'There are duplicate hash strategies:',
+                    [...new Set(duplicateStrategies)].map(s => `- ${s.name} (${s.version})`)
+                ].join('\n')
+            );
+        }
+    }
+
+    private async validateNoMissingHashStrategy(): Promise<void> {
+        const strategies: HashStrategyEntity[] = await this.hashStrategyRepository.findAll();
+        const missingStrategies: HashStrategyEntity[] = strategies.filter(
+            s => !this.strategies.some(hs => hs.name === s.name && hs.version === s.version)
+        );
+        if (missingStrategies.length) {
+            const message: string[] = ['Error initializing hash service.', 'There are missing strategies:'];
+            for (const strategy of missingStrategies) {
+                message.push(`  - ${strategy.name} (${strategy.version})`);
+            }
+            message.push('Did you remove them?');
+            throw new Error(message.join('\n'));
+        }
+    }
+
+    private validateStrategyNamesAndVersions(): void {
+        const strategiesWithDotsInNameOrVersion: HashStrategyInterface<Record<string, unknown>>[] = this.strategies.filter(
+            s => s.name.includes('.') || s.version.includes('.')
+        );
+        if (!strategiesWithDotsInNameOrVersion.length) {
+            return;
+        }
+        const message: string[] = [
+            'Error initializing hash service.',
+            'There are strategies that use dots in either the version or the name:'
+        ];
+        for (const strategy of strategiesWithDotsInNameOrVersion) {
+            message.push(`  - ${strategy.name} (${strategy.version})`);
+        }
+        throw new Error(message.join('\n'));
+    }
+}

package/src/auth/hash/hash.utilities.ts

@@ -0,0 +1,60 @@
+
+/**
+ * A string with hashed data stored inside of it.
+ */
+export type HashString = string & {
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    __brand: 'hash'
+};
+
+/**
+ * The content stored inside a hashed string.
+ */
+export type HashContent = {
+    /**
+     * The name of the hash strategy.
+     */
+    strategyName: string,
+    /**
+     * The version of the hash strategy.
+     */
+    version: string,
+    /**
+     * The actual hashed value.
+     */
+    hashedValue: string
+};
+
+/**
+ * Utilities around handling hashing.
+ */
+export abstract class HashUtilities {
+    /**
+     * Creates a hash string from the given content.
+     * @param data - The content to store inside the hash string.
+     * @returns The hash string in the form "strategyName.version.hashedValue".
+     */
+    static contentToHash(data: HashContent): HashString {
+        return [data.strategyName, data.version, data.hashedValue].join('.') as HashString;
+    }
+    /**
+     * Resolves the content of the given hash string.
+     * @param hash - The hash string to resolve the content of.
+     * @returns The hash content inside the given string.
+     * @throws If the hash string is invalid.
+     */
+    static hashToContent(hash: HashString): HashContent {
+        const [strategyName, version, ...hashedValueParts] = hash.split('.');
+        const hashedValue: string = hashedValueParts.join('.');
+
+        if (!strategyName || !version || !hashedValue) {
+            throw new Error('Invalid hash string');
+        }
+
+        return {
+            strategyName,
+            version,
+            hashedValue
+        };
+    }
+}

package/src/auth/hash/strategies/bcrypt.hash-strategy.ts

@@ -0,0 +1,39 @@
+import { compare, hash } from 'bcryptjs';
+
+import { HashStrategyInterface } from './hash-strategy.interface';
+import { HashContent, HashString, HashUtilities } from '../hash.utilities';
+
+/**
+ * Options for hashing via the bcrypt hash strategy.
+ */
+export type BcryptHashOptions = {
+    /**
+     * How many rounds should be used for the salt.
+     */
+    rounds?: number
+};
+
+/**
+ * Default bcrypt hash strategy implementation of zibri.
+ */
+export class BcryptHashStrategy implements HashStrategyInterface<BcryptHashOptions> {
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly name: string = 'bcrypt';
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly version: string = 'v1';
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    async hash(
+        value: string,
+        options: BcryptHashOptions | undefined
+    ): Promise<HashString> {
+        const hashedValue: string = await hash(value, options?.rounds ?? 10);
+        return HashUtilities.contentToHash({ strategyName: this.name, version: this.version, hashedValue });
+    }
+
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    async equal(value: string, hash: HashString): Promise<boolean> {
+        const content: HashContent = HashUtilities.hashToContent(hash);
+        return await compare(value, content.hashedValue);
+    }
+}