@cratis/chronicle 6.1.1 → 6.3.0

package/projections/modelBound/variantOf.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+
+/** Metadata stored by the variantOf class decorator. */
+export interface VariantOfMetadata {
+    /** The type anchoring the logical identity every variant of this group shares. */
+    readonly identity: Function;
+    /** The property name on this variant used as its own key, and as the correlation property for reclassified joins. */
+    readonly key: string;
+}
+
+const METADATA_KEY = 'chronicle:projection:variantOf';
+
+/**
+ * Class decorator that declares a read model to be one of several mutually exclusive
+ * representations of the same logical entity. Entering one variant removes the entity
+ * from every sibling variant of the same identity.
+ * @param identity - The type anchoring the logical identity shared by every variant. Does not need to be a read model itself.
+ * @param key - The property name on this variant used as its own key.
+ * @returns A class decorator.
+ */
+export function variantOf(identity: Function, key: string): ClassDecorator {
+    return (target: object) => {
+        const metadata: VariantOfMetadata = { identity, key };
+        Reflect.defineMetadata(METADATA_KEY, metadata, target);
+    };
+}
+
+/**
+ * Retrieves variantOf metadata stored on the given class constructor.
+ * @param target - The class constructor.
+ * @returns The variantOf metadata, or undefined if the class is not a variant.
+ */
+export function getVariantOfMetadata(target: Function): VariantOfMetadata | undefined {
+    return Reflect.getMetadata(METADATA_KEY, target);
+}

package/readModels/ReadModels.spec.ts

@@ -33,7 +33,8 @@ function createReadModels(readModelType: Constructor, releaseResponse: Record<st
         constraints: [],
         projections: [],
         webhooks: [],
-        eventTypeMigrations: []
+        eventTypeMigrations: [],
+        globalForHandlers: []
     } as IClientArtifactsProvider;
 
     const readModels = new ReadModels('test-store', 'test-namespace', connection, clientArtifacts, 'default-sink');

package/reducers/Reducers.spec.ts

@@ -62,7 +62,8 @@ function createArtifacts(reducers: Constructor[]): IClientArtifactsProvider {
         constraints: [],
         projections: [],
         webhooks: [],
-        eventTypeMigrations: []
+        eventTypeMigrations: [],
+        globalForHandlers: []
     };
 }
 

package/schemas/JsonSchema.ts

@@ -16,6 +16,25 @@ export interface ComplianceSchemaMetadata {
     details: string;
 }
 
+/**
+ * Represents a single security classification recorded on a schema node.
+ *
+ * This is the security counterpart to {@link ComplianceSchemaMetadata} - written under its own,
+ * separate `security` schema key rather than merged into `compliance`. See
+ * `Source/confidentiality/SecurityMetadataType.ts` for why.
+ */
+export interface SecuritySchemaMetadata {
+    /**
+     * The type of security metadata (e.g. 'EncryptedSubject', 'EncryptedNamespace', 'EncryptedGlobal').
+     */
+    metadataType: string;
+
+    /**
+     * Any additional details - can be empty.
+     */
+    details: string;
+}
+
 /**
  * Represents a JSON Schema object.
  */
@@ -31,4 +50,5 @@ export type JsonSchema = {
     additionalProperties?: boolean | JsonSchema;
     enum?: Array<string | number | boolean | null>;
     compliance?: ComplianceSchemaMetadata[];
+    security?: SecuritySchemaMetadata[];
 };

package/schemas/JsonSchemaGenerator.confidentiality.spec.ts

@@ -0,0 +1,194 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { ConceptAs, field } from '@cratis/fundamentals';
+import { describe, expect, it } from 'vitest';
+import { pii } from '../compliance/pii';
+import { encrypted } from '../confidentiality/encrypted';
+import { EncryptionScope } from '../confidentiality/EncryptionScope';
+import { PIIAndEncryptedCombinedNotSupported } from '../confidentiality/PIIAndEncryptedCombinedNotSupported';
+import { getReadModelMetadata, readModel } from '../readModels/readModel';
+import { JsonSchema } from './JsonSchema';
+
+// See JsonSchemaGenerator.spec.ts for why decorators are applied as plain function calls here
+// rather than `@decorator` syntax, and why order matters.
+
+function schemaFor(target: Function): JsonSchema {
+    return getReadModelMetadata(target)!.schema;
+}
+
+describe('JsonSchemaGenerator - security metadata', () => {
+    describe('when a class is marked @encrypted() at the class level', () => {
+        class PartnerCredentials {
+            apiKey = '';
+            webhookSecret = '';
+        }
+        encrypted()(PartnerCredentials);
+
+        readModel()(PartnerCredentials);
+        const schema = schemaFor(PartnerCredentials);
+
+        it('should mark every one of its own properties as EncryptedSubject', () => {
+            expect(schema.properties!.apiKey.security).toEqual([{ metadataType: 'EncryptedSubject', details: '' }]);
+            expect(schema.properties!.webhookSecret.security).toEqual([{ metadataType: 'EncryptedSubject', details: '' }]);
+        });
+
+        it('should not write anything to the compliance key', () => {
+            expect(schema.properties!.apiKey.compliance).toBeUndefined();
+            expect(schema.properties!.webhookSecret.compliance).toBeUndefined();
+        });
+    });
+
+    describe('when only a single property is marked @encrypted()', () => {
+        class Integration {
+            apiKey = '';
+            name = '';
+        }
+        encrypted(EncryptionScope.Subject, 'Partner API key')(Integration.prototype, 'apiKey');
+        readModel()(Integration);
+        const schema = schemaFor(Integration);
+
+        it('should mark the decorated property as EncryptedSubject', () => {
+            expect(schema.properties!.apiKey.security).toEqual([{ metadataType: 'EncryptedSubject', details: 'Partner API key' }]);
+        });
+
+        it('should leave the other property without security metadata', () => {
+            expect(schema.properties!.name.security).toBeUndefined();
+        });
+    });
+
+    describe.each([
+        [EncryptionScope.Subject, 'EncryptedSubject'],
+        [EncryptionScope.Namespace, 'EncryptedNamespace'],
+        [EncryptionScope.Global, 'EncryptedGlobal']
+    ])('when a property is marked @encrypted() with scope %s', (scope, expectedMetadataType) => {
+        class Secret {
+            value = '';
+        }
+        encrypted(scope)(Secret.prototype, 'value');
+        readModel()(Secret);
+        const schema = schemaFor(Secret);
+
+        it(`should resolve to metadataType ${expectedMetadataType}`, () => {
+            expect(schema.properties!.value.security).toEqual([{ metadataType: expectedMetadataType, details: '' }]);
+        });
+    });
+
+    describe('when a property is typed as a ConceptAs<T> marked @encrypted()', () => {
+        class ApiKey extends ConceptAs<string> {
+            constructor(value: string) {
+                super(value);
+            }
+        }
+        encrypted(EncryptionScope.Namespace, 'Shared namespace key')(ApiKey);
+
+        class Configuration {
+            key: ApiKey = new ApiKey('');
+        }
+        readModel()(Configuration);
+        const schema = schemaFor(Configuration);
+
+        it('should mark the concept-typed property as EncryptedNamespace', () => {
+            expect(schema.properties!.key.security).toEqual([{ metadataType: 'EncryptedNamespace', details: 'Shared namespace key' }]);
+        });
+    });
+
+    describe('when a property typed as a nested composite value object is marked @encrypted()', () => {
+        class ContactDetails {
+            phone = '';
+            fax = '';
+        }
+        class Vendor {
+            contact: ContactDetails = new ContactDetails();
+        }
+        encrypted(EncryptionScope.Subject, 'Vendor contact information')(Vendor.prototype, 'contact');
+        readModel()(Vendor);
+        const schema = schemaFor(Vendor);
+
+        it('should push the security metadata down onto every leaf property', () => {
+            expect(schema.properties!.contact.properties!.phone.security).toEqual([{ metadataType: 'EncryptedSubject', details: 'Vendor contact information' }]);
+            expect(schema.properties!.contact.properties!.fax.security).toEqual([{ metadataType: 'EncryptedSubject', details: 'Vendor contact information' }]);
+        });
+
+        it('should not leave security metadata on the container node itself', () => {
+            expect(schema.properties!.contact.security).toBeUndefined();
+        });
+    });
+
+    describe('when an array element is a ConceptAs<T> marked @encrypted()', () => {
+        class Token extends ConceptAs<string> {
+            constructor(value: string) {
+                super(value);
+            }
+        }
+        encrypted(EncryptionScope.Subject, 'Rotating token')(Token);
+
+        class Session {
+            tokens: Token[] = [];
+        }
+        field(Array, { enumerable: true, genericArguments: [Token] })(Session.prototype, 'tokens');
+        readModel()(Session);
+        const schema = schemaFor(Session);
+
+        it('should carry the element concept security metadata onto the item schema', () => {
+            expect(schema.properties!.tokens.items!.security).toEqual([{ metadataType: 'EncryptedSubject', details: 'Rotating token' }]);
+        });
+
+        it('should not leave coarse security metadata on the array container itself', () => {
+            expect(schema.properties!.tokens.security).toBeUndefined();
+        });
+    });
+
+    describe('when a property is marked both @pii() and @encrypted()', () => {
+        class ConflictedValue {
+            value = '';
+        }
+        pii()(ConflictedValue.prototype, 'value');
+        encrypted()(ConflictedValue.prototype, 'value');
+
+        it('should throw PIIAndEncryptedCombinedNotSupported when generating the schema', () => {
+            expect(() => { readModel()(ConflictedValue); }).toThrow(PIIAndEncryptedCombinedNotSupported);
+        });
+    });
+
+    describe('when a class-level @pii() combines with a property-level @encrypted() on the same property', () => {
+        class MixedClass {
+            value = '';
+        }
+        pii()(MixedClass);
+        encrypted()(MixedClass.prototype, 'value');
+
+        it('should throw PIIAndEncryptedCombinedNotSupported when generating the schema', () => {
+            expect(() => { readModel()(MixedClass); }).toThrow(PIIAndEncryptedCombinedNotSupported);
+        });
+    });
+
+    describe('when a class carries only @pii() properties alongside a class that carries only @encrypted() properties', () => {
+        class OnlyPii {
+            ssn = '';
+        }
+        pii()(OnlyPii.prototype, 'ssn');
+        readModel()(OnlyPii);
+
+        class OnlyEncrypted {
+            apiKey = '';
+        }
+        encrypted()(OnlyEncrypted.prototype, 'apiKey');
+        readModel()(OnlyEncrypted);
+
+        it('should not throw for either type', () => {
+            expect(() => schemaFor(OnlyPii)).not.toThrow();
+            expect(() => schemaFor(OnlyEncrypted)).not.toThrow();
+        });
+
+        it('should keep compliance and security metadata on separate schema keys', () => {
+            const piiSchema = schemaFor(OnlyPii);
+            const encryptedSchema = schemaFor(OnlyEncrypted);
+            expect(piiSchema.properties!.ssn.compliance).toEqual([{ metadataType: 'PII', details: '' }]);
+            expect(piiSchema.properties!.ssn.security).toBeUndefined();
+            expect(encryptedSchema.properties!.apiKey.security).toEqual([{ metadataType: 'EncryptedSubject', details: '' }]);
+            expect(encryptedSchema.properties!.apiKey.compliance).toBeUndefined();
+        });
+    });
+});

package/schemas/JsonSchemaGenerator.ts

@@ -3,10 +3,13 @@
 
 import 'reflect-metadata';
 import { ConceptAs, Constructor, Fields, Guid } from '@cratis/fundamentals';
-import { ComplianceSchemaMetadata, JsonSchema } from './JsonSchema';
+import { ComplianceSchemaMetadata, JsonSchema, SecuritySchemaMetadata } from './JsonSchema';
 import { TypeIntrospector } from '../types';
 import { ComplianceMetadata } from '../compliance/ComplianceMetadata';
 import { ComplianceMetadataResolver } from '../compliance/ComplianceMetadataResolver';
+import { SecurityMetadata } from '../confidentiality/SecurityMetadata';
+import { SecurityMetadataResolver } from '../confidentiality/SecurityMetadataResolver';
+import { PIIAndEncryptedCombinedNotSupported } from '../confidentiality/PIIAndEncryptedCombinedNotSupported';
 
 /**
  * Generates JSON schemas for class constructors using reflection metadata.
@@ -54,11 +57,15 @@ export class JsonSchemaGenerator {
             // the runtime type was unavailable (e.g. esbuild/tsx omits design:paramtypes).
             if (Object.keys(propertySchema).length > 0) {
                 // An array of concept elements resolves and applies its own item-level compliance
-                // inside mapRuntimeTypeToSchema - the general property/type/declaring-class walk
-                // below is skipped for it, mirroring the C# generator's enumerable-of-concept branch.
+                // and security metadata inside mapRuntimeTypeToSchema - the general
+                // property/type/declaring-class walk below is skipped for it, mirroring the C#
+                // generator's enumerable-of-concept branch.
                 if (!this.isConceptArrayMember(target, memberName, memberType)) {
-                    const metadata = this.collectComplianceMetadata(prototype, memberName, memberType);
-                    this.addComplianceMetadataToSchema(propertySchema, metadata);
+                    const complianceMetadata = this.collectComplianceMetadata(prototype, memberName, memberType);
+                    const securityMetadata = this.collectSecurityMetadata(prototype, memberName, memberType);
+                    this.throwIfBothCompliantAndSecure(memberName, complianceMetadata, securityMetadata);
+                    this.addComplianceMetadataToSchema(propertySchema, complianceMetadata);
+                    this.addSecurityMetadataToSchema(propertySchema, securityMetadata);
                 }
                 schemaProperties[memberName] = propertySchema;
             }
@@ -132,13 +139,16 @@ export class JsonSchemaGenerator {
         const elementType = this.getArrayElementType(declaringType, propertyName);
 
         // An array whose element is a ConceptAs<T> loses its classification the moment it is put in
-        // a list unless the element concept's own compliance metadata is carried onto the item schema -
-        // a value that would be encrypted as a scalar would otherwise be persisted in the clear as a
-        // list element. Mirrors the C# generator's explicit enumerable-of-concept branch.
+        // a list unless the element concept's own compliance/security metadata is carried onto the
+        // item schema - a value that would be encrypted as a scalar would otherwise be persisted in
+        // the clear as a list element. Mirrors the C# generator's explicit enumerable-of-concept branch.
         if (elementType && this.isConceptAs(elementType)) {
             const itemSchema = this.mapRuntimeTypeToSchema(elementType);
-            const metadata = ComplianceMetadataResolver.getMetadataForType(elementType);
-            this.addComplianceMetadataToSchema(itemSchema, metadata);
+            const complianceMetadata = ComplianceMetadataResolver.getMetadataForType(elementType);
+            const securityMetadata = SecurityMetadataResolver.getMetadataForType(elementType);
+            this.throwIfBothCompliantAndSecure(elementType.name, complianceMetadata, securityMetadata);
+            this.addComplianceMetadataToSchema(itemSchema, complianceMetadata);
+            this.addSecurityMetadataToSchema(itemSchema, securityMetadata);
             return { type: 'array', items: itemSchema };
         }
 
@@ -299,4 +309,99 @@ export class JsonSchemaGenerator {
     private static hasComplianceMetadataOfType(compliance: ComplianceSchemaMetadata[], metadataType: string): boolean {
         return compliance.some(item => item.metadataType === metadataType);
     }
+
+    /**
+     * Collects security metadata for a property from every source compliance metadata is resolved
+     * from: the property itself, its declaring class, and its own type (the concept case). This is
+     * the security counterpart to {@link collectComplianceMetadata} - a deliberately separate walk
+     * rather than a shared one, over a completely separate `@encrypted()` decorator vocabulary.
+     * @param target - The class prototype the property is declared on.
+     * @param propertyKey - The property name.
+     * @param propertyType - The property's runtime type, when resolved.
+     * @returns The collected security metadata, in property → declaring-class → type order.
+     */
+    private static collectSecurityMetadata(target: object, propertyKey: string, propertyType?: Function): SecurityMetadata[] {
+        const metadata: SecurityMetadata[] = [];
+
+        // Property-level security decorator.
+        if (SecurityMetadataResolver.hasMetadataFor(target, propertyKey)) {
+            metadata.push(...SecurityMetadataResolver.getMetadataFor(target, propertyKey));
+        }
+
+        // Declaring class-level security decorator - a class-level @encrypted() marks every one of
+        // its own properties, the same way a class-level @pii() does for compliance.
+        const declaringClass = (target as { constructor?: Function }).constructor;
+        if (declaringClass) {
+            metadata.push(...SecurityMetadataResolver.getMetadataForType(declaringClass));
+        }
+
+        // Type-level security decorator on the property's own type (e.g., @encrypted on a ConceptAs).
+        if (propertyType) {
+            metadata.push(...SecurityMetadataResolver.getMetadataForType(propertyType));
+        }
+
+        return metadata;
+    }
+
+    /**
+     * Adds security metadata to a schema node, descending into an object's properties so that the
+     * metadata always lands on the leaves that actually hold a value. This is the security
+     * counterpart to {@link addComplianceMetadataToSchema} - see its remarks for why metadata is
+     * pushed to leaves and why an array is left as a container.
+     * @param schema - The schema node to add to.
+     * @param metadata - The security metadata to add.
+     */
+    private static addSecurityMetadataToSchema(schema: JsonSchema, metadata: SecurityMetadata[]): void {
+        if (metadata.length === 0) {
+            return;
+        }
+
+        if (schema.properties && Object.keys(schema.properties).length > 0) {
+            for (const propertySchema of Object.values(schema.properties)) {
+                this.addSecurityMetadataToSchema(propertySchema, metadata);
+            }
+            return;
+        }
+
+        const security = schema.security ?? [];
+        for (const item of metadata) {
+            const metadataType = item.metadataType.value.toString();
+            if (!this.hasSecurityMetadataOfType(security, metadataType)) {
+                security.push({ metadataType, details: item.details });
+            }
+        }
+
+        if (security.length > 0) {
+            schema.security = security;
+        }
+    }
+
+    /**
+     * Checks whether a security array already carries metadata of a given type.
+     * @param security - The security array to check.
+     * @param metadataType - The metadata type to look for.
+     * @returns True when the metadata type is already present, false if not.
+     */
+    private static hasSecurityMetadataOfType(security: SecuritySchemaMetadata[], metadataType: string): boolean {
+        return security.some(item => item.metadataType === metadataType);
+    }
+
+    /**
+     * Rejects a property or type that resolved both compliance and security metadata.
+     * @param name - The property or type name, used in the thrown error.
+     * @param complianceMetadata - The compliance metadata collected for the property/type.
+     * @param securityMetadata - The security metadata collected for the property/type.
+     * @remarks
+     * This is not merely redundant - it corrupts the value. The kernel applies every matching
+     * handler for a property in sequence, so a value marked both ways is encrypted first under the
+     * PII key and then again under the Encrypted key; releasing it decrypts with the wrong key
+     * against ciphertext, which fails loudly rather than returning a wrong value. Checked here, at
+     * schema-generation time, the same point C#'s `EncryptedMetadataProvider.ThrowIfAlsoPII` checks
+     * it - this client has no compile-time analyzer, so this runtime check is the only backstop.
+     */
+    private static throwIfBothCompliantAndSecure(name: string, complianceMetadata: ComplianceMetadata[], securityMetadata: SecurityMetadata[]): void {
+        if (complianceMetadata.length > 0 && securityMetadata.length > 0) {
+            throw new PIIAndEncryptedCombinedNotSupported(name);
+        }
+    }
 }

package/types/DecoratorType.ts

@@ -30,5 +30,8 @@ export enum DecoratorType {
     Webhook = 'webhook',
 
     /** Event type migration artifacts discovered through the eventTypeMigration decorator. */
-    EventTypeMigration = 'eventTypeMigration'
+    EventTypeMigration = 'eventTypeMigration',
+
+    /** Global read model variant handler artifacts discovered through the globalFor decorator. */
+    GlobalForHandler = 'globalForHandler'
 }