@cratis/chronicle 6.2.0 → 6.3.1

package/confidentiality/EncryptedNotSupportedOnEventSourceId.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Error thrown when the {@link encrypted} decorator is applied to the `eventSourceId` property.
+ */
+export class EncryptedNotSupportedOnEventSourceId extends Error {
+    /**
+     * Initializes a new instance of the {@link EncryptedNotSupportedOnEventSourceId} class.
+     * @param typeName - The name of the type the decorator was applied to.
+     */
+    constructor(typeName: string) {
+        super(
+            `The @encrypted() decorator cannot be applied to 'eventSourceId' on '${typeName}' because it is the ` +
+            'event source identifier. Event source identifiers cannot be encrypted as they are required for event ' +
+            'correlation. If the identifier itself is sensitive, use a non-sensitive surrogate value as the event ' +
+            'source identifier and store the sensitive value in a separate property marked with @encrypted().'
+        );
+        this.name = 'EncryptedNotSupportedOnEventSourceId';
+    }
+}

package/confidentiality/EncryptionScope.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Defines the identity an `@encrypted()` value's encryption key is provisioned under.
+ *
+ * `@pii()` never gains any scope beyond {@link EncryptionScope.Subject} - GDPR compliance is always
+ * resolved against a compliance identity, and widening that would make the compliance subject
+ * boundary itself scope-dependent. `EncryptionScope` exists precisely because `@encrypted()` values
+ * have no data subject and no erasure obligation, so a wider key boundary is safe for them in a way
+ * it is not for PII.
+ */
+export enum EncryptionScope {
+    /**
+     * The key is provisioned per compliance identity (the same identity - subject or, when none is
+     * set, event source id - PII values on the same document resolve to), and is looked up the same
+     * way. This is the default.
+     */
+    Subject = 0,
+
+    /**
+     * The key is provisioned once per event store namespace, independent of any document's subject
+     * or compliance identity. Every `@encrypted(EncryptionScope.Namespace)` value in a namespace
+     * shares one key.
+     */
+    Namespace = 1,
+
+    /**
+     * The key is provisioned once for the whole Chronicle installation, independent of event store,
+     * namespace, or compliance identity. Every `@encrypted(EncryptionScope.Global)` value across
+     * every event store and namespace shares one key.
+     */
+    Global = 2
+}

package/confidentiality/PIIAndEncryptedCombinedNotSupported.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Error thrown when a property, or the type it resolves metadata from, carries both `@pii()` and
+ * `@encrypted()`.
+ *
+ * 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 (a padding/authentication error) rather than returning a wrong value. A value
+ * needs exactly one protection: `@pii()` when it is personal data with a lawful basis for erasure,
+ * `@encrypted()` when it is an operational secret with none.
+ */
+export class PIIAndEncryptedCombinedNotSupported extends Error {
+    /**
+     * Initializes a new instance of the {@link PIIAndEncryptedCombinedNotSupported} class.
+     * @param property - The name of the property (or type) carrying both decorators.
+     */
+    constructor(property: string) {
+        super(
+            `'${property}' carries both @pii() and @encrypted(). A value needs exactly one protection - combining ` +
+            'them would encrypt it twice, under two different keys, and it cannot be released correctly. Choose ' +
+            '@pii() for personal data with a lawful basis for erasure, or @encrypted() for an operational secret ' +
+            'with none.'
+        );
+        this.name = 'PIIAndEncryptedCombinedNotSupported';
+    }
+}

package/confidentiality/SecurityMetadata.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { SecurityMetadataType } from './SecurityMetadataType';
+
+/**
+ * Represents metadata related to security.
+ *
+ * This is the security counterpart to {@link ComplianceMetadata} - a deliberately separate type
+ * rather than a shared one. See {@link SecurityMetadataType} for why.
+ */
+export interface SecurityMetadata {
+    /**
+     * The type of security metadata.
+     */
+    readonly metadataType: SecurityMetadataType;
+
+    /**
+     * Any additional details - can be empty.
+     */
+    readonly details: string;
+}

package/confidentiality/SecurityMetadataResolver.ts

@@ -0,0 +1,54 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { SecurityMetadata } from './SecurityMetadata';
+import { getEncryptedMetadata, getTypeEncryptedMetadata } from './encrypted';
+
+/**
+ * Resolves security metadata for properties and types.
+ *
+ * This is the security counterpart to {@link ComplianceMetadataResolver} - a deliberately separate
+ * type rather than a shared one. See {@link SecurityMetadataType} for why.
+ */
+export class SecurityMetadataResolver {
+    /**
+     * Checks if a property has security metadata.
+     * @param target - The class prototype.
+     * @param propertyKey - The property name.
+     * @returns True if the property has security metadata; false otherwise.
+     */
+    static hasMetadataFor(target: object, propertyKey: string): boolean {
+        return getEncryptedMetadata(target, propertyKey) !== undefined;
+    }
+
+    /**
+     * Gets all security metadata for a property.
+     * @param target - The class prototype.
+     * @param propertyKey - The property name.
+     * @returns Array of security metadata.
+     */
+    static getMetadataFor(target: object, propertyKey: string): SecurityMetadata[] {
+        const metadata: SecurityMetadata[] = [];
+
+        const encryptedMetadata = getEncryptedMetadata(target, propertyKey);
+        if (encryptedMetadata) {
+            metadata.push(encryptedMetadata);
+        }
+
+        return metadata;
+    }
+
+    /**
+     * Gets security metadata for a type (e.g., ConceptAs types).
+     * @param type - The type constructor.
+     * @returns Array of security metadata.
+     */
+    static getMetadataForType(type: Function): SecurityMetadata[] {
+        const metadata: SecurityMetadata[] = [];
+        const encryptedMetadata = getTypeEncryptedMetadata(type);
+        if (encryptedMetadata) {
+            metadata.push(encryptedMetadata);
+        }
+        return metadata;
+    }
+}

package/confidentiality/SecurityMetadataType.ts

@@ -0,0 +1,56 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents a type of security metadata.
+ *
+ * This is the security counterpart to {@link ComplianceMetadataType} - a deliberately separate type
+ * rather than a shared one. A `@pii()` value and an `@encrypted()` value are never the same kind of
+ * thing: one is personal data with a GDPR erasure obligation, the other is an operational secret
+ * with none. Keeping the two vocabularies apart keeps that distinction visible at every call site
+ * that reads a schema's metadata.
+ */
+export class SecurityMetadataType {
+    /**
+     * The key is provisioned per compliance identity - the same identity, resolved the same way, a
+     * `@pii()` value on the same document would use. This is what `@encrypted()` (with no explicit
+     * scope, or `EncryptionScope.Subject`) resolves to.
+     */
+    static readonly EncryptedSubject = new SecurityMetadataType('EncryptedSubject');
+
+    /**
+     * The key is provisioned once per event store namespace. This is what
+     * `@encrypted(EncryptionScope.Namespace)` resolves to.
+     */
+    static readonly EncryptedNamespace = new SecurityMetadataType('EncryptedNamespace');
+
+    /**
+     * The key is provisioned once for the whole Chronicle installation. This is what
+     * `@encrypted(EncryptionScope.Global)` resolves to.
+     */
+    static readonly EncryptedGlobal = new SecurityMetadataType('EncryptedGlobal');
+
+    private readonly _value: string;
+
+    /**
+     * Initializes a new instance of SecurityMetadataType.
+     * @param value - The string value of the security metadata type.
+     */
+    constructor(value: string) {
+        this._value = value;
+    }
+
+    /**
+     * Gets the underlying string value.
+     */
+    get value(): string {
+        return this._value;
+    }
+
+    /**
+     * Returns the string representation of the security metadata type.
+     */
+    toString(): string {
+        return this._value;
+    }
+}

package/confidentiality/encrypted.spec.ts

@@ -0,0 +1,105 @@
+// 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 { describe, expect, it } from 'vitest';
+import { encrypted, getEncryptedMetadata, getTypeEncryptedMetadata, hasEncryptedMetadata, isEncrypted } from './encrypted';
+import { EncryptionScope } from './EncryptionScope';
+import { EncryptedNotSupportedOnEventSourceId } from './EncryptedNotSupportedOnEventSourceId';
+
+// Decorators are applied as plain function calls (rather than `@decorator` syntax) so these
+// fixtures don't depend on the test runner's decorator-syntax support.
+
+describe('encrypted', () => {
+    describe('when applied to the eventSourceId property', () => {
+        class SomeEvent {
+            eventSourceId = '';
+        }
+
+        it('should throw EncryptedNotSupportedOnEventSourceId', () => {
+            expect(() => encrypted()(SomeEvent.prototype, 'eventSourceId')).toThrow(EncryptedNotSupportedOnEventSourceId);
+        });
+
+        it('should describe why the property cannot be encrypted', () => {
+            expect(() => encrypted()(SomeEvent.prototype, 'eventSourceId')).toThrow(/event source identifier/);
+        });
+    });
+
+    describe('when applied to any other property with no explicit scope', () => {
+        class SomeEvent {
+            eventSourceId = '';
+            apiKey = '';
+        }
+        encrypted()(SomeEvent.prototype, 'apiKey');
+
+        it('should not throw', () => {
+            expect(() => encrypted()(SomeEvent.prototype, 'apiKey')).not.toThrow();
+        });
+
+        it('should default the scope to Subject', () => {
+            expect(getEncryptedMetadata(SomeEvent.prototype, 'apiKey')!.metadataType.value).toBe('EncryptedSubject');
+        });
+
+        it('should default details to an empty string', () => {
+            expect(getEncryptedMetadata(SomeEvent.prototype, 'apiKey')!.details).toBe('');
+        });
+
+        it('should report the property as having encrypted metadata', () => {
+            expect(hasEncryptedMetadata(SomeEvent.prototype, 'apiKey')).toBe(true);
+        });
+    });
+
+    describe('when applied with EncryptionScope.Namespace and details', () => {
+        class Configuration {
+            webhookSecret = '';
+        }
+        encrypted(EncryptionScope.Namespace, 'Shared per namespace')(Configuration.prototype, 'webhookSecret');
+
+        it('should resolve to EncryptedNamespace', () => {
+            expect(getEncryptedMetadata(Configuration.prototype, 'webhookSecret')!.metadataType.value).toBe('EncryptedNamespace');
+        });
+
+        it('should carry the details', () => {
+            expect(getEncryptedMetadata(Configuration.prototype, 'webhookSecret')!.details).toBe('Shared per namespace');
+        });
+    });
+
+    describe('when applied with EncryptionScope.Global', () => {
+        class License {
+            token = '';
+        }
+        encrypted(EncryptionScope.Global)(License.prototype, 'token');
+
+        it('should resolve to EncryptedGlobal', () => {
+            expect(getEncryptedMetadata(License.prototype, 'token')!.metadataType.value).toBe('EncryptedGlobal');
+        });
+    });
+
+    describe('when applied at the class level', () => {
+        class PartnerCredentials {
+            apiKey = '';
+        }
+        encrypted(EncryptionScope.Subject, 'Every field is a secret')(PartnerCredentials);
+
+        it('should report the type as encrypted', () => {
+            expect(isEncrypted(PartnerCredentials)).toBe(true);
+        });
+
+        it('should carry the scope and details on the type metadata', () => {
+            const metadata = getTypeEncryptedMetadata(PartnerCredentials)!;
+            expect(metadata.metadataType.value).toBe('EncryptedSubject');
+            expect(metadata.details).toBe('Every field is a secret');
+        });
+    });
+
+    describe('when a property has not been decorated', () => {
+        class Plain {
+            value = '';
+        }
+
+        it('should report no encrypted metadata', () => {
+            expect(hasEncryptedMetadata(Plain.prototype, 'value')).toBe(false);
+            expect(getEncryptedMetadata(Plain.prototype, 'value')).toBeUndefined();
+        });
+    });
+});

package/confidentiality/encrypted.ts

@@ -0,0 +1,143 @@
+// 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 type { SecurityMetadata } from './SecurityMetadata';
+import { SecurityMetadataType } from './SecurityMetadataType';
+import { EncryptionScope } from './EncryptionScope';
+import { EncryptedNotSupportedOnEventSourceId } from './EncryptedNotSupportedOnEventSourceId';
+import { TypeIntrospector } from '../types';
+
+/** The property name this client uses everywhere for the event source identifier. */
+const EVENT_SOURCE_ID_PROPERTY = 'eventSourceId';
+
+/** Metadata key for the encrypted decorator on properties. */
+const ENCRYPTED_PROPERTY_METADATA_KEY = 'chronicle:security:encrypted:property';
+
+/** Metadata key for the encrypted decorator on types. */
+const ENCRYPTED_TYPE_METADATA_KEY = 'chronicle:security:encrypted:type';
+
+function metadataTypeFor(scope: EncryptionScope): SecurityMetadataType {
+    switch (scope) {
+        case EncryptionScope.Subject:
+            return SecurityMetadataType.EncryptedSubject;
+        case EncryptionScope.Namespace:
+            return SecurityMetadataType.EncryptedNamespace;
+        case EncryptionScope.Global:
+            return SecurityMetadataType.EncryptedGlobal;
+    }
+}
+
+/**
+ * Decorator that marks a property or type as needing plain-confidentiality encryption at rest - a
+ * security measure, not a compliance one.
+ *
+ * Use `@encrypted()` for an operational secret that has no data subject and no lawful basis for
+ * erasure - an API key, a webhook signing secret, a partner credential. Use `@pii()` instead when
+ * the value is personal data about a natural person: only `@pii()` encrypts a value *and* enrolls it
+ * in GDPR right-to-erasure. Marking a secret `@pii()` would make it erasable on a request that was
+ * never about it; marking personal data `@encrypted()` would encrypt it but never erase it. The two
+ * are not interchangeable, and this decorator's key is never provisioned under the same identity a
+ * `@pii()` value for the same subject uses.
+ *
+ * All three {@link EncryptionScope} members are honored by the kernel: `EncryptionScope.Subject`
+ * (the default) provisions a key per compliance identity, exactly matching how a `@pii()` value on
+ * the same document is resolved; `EncryptionScope.Namespace` provisions one key shared by every
+ * value marked with it in a given event store namespace; `EncryptionScope.Global` provisions one key
+ * shared across the whole installation. Choosing a wider scope is safe for `@encrypted()` in a way
+ * it is not for `@pii()`, precisely because an operational secret has no data subject whose erasure
+ * request the wider key could ever need to honor separately from another subject's.
+ *
+ * This decorator can be used in two ways:
+ * - As a property decorator: `@encrypted() propertyName: type`
+ * - As a class decorator: `@encrypted() class TypeName { }`
+ *
+ * @param scope - The {@link EncryptionScope} the key is provisioned under - defaults to `EncryptionScope.Subject`.
+ * @param details - Optional details explaining why or to what purpose/extent the property/type needs encryption.
+ * @returns A decorator function that can be applied to either properties or classes (but not both on the same target).
+ *
+ * @example
+ * Property usage:
+ * ```typescript
+ * @readModel()
+ * class PartnerIntegration {
+ *     @encrypted()
+ *     apiKey: string = '';
+ *
+ *     @encrypted(EncryptionScope.Namespace)
+ *     webhookSigningSecret: string = '';
+ * }
+ * ```
+ */
+export function encrypted(scope: EncryptionScope = EncryptionScope.Subject, details?: string): PropertyDecorator & ClassDecorator {
+    return (target: object | Function, propertyKey?: string | symbol) => {
+        // Class decorator usage (for types like ConceptAs)
+        if (typeof target === 'function' && propertyKey === undefined) {
+            const metadata: SecurityMetadata = {
+                metadataType: metadataTypeFor(scope),
+                details: details ?? ''
+            };
+            Reflect.defineMetadata(ENCRYPTED_TYPE_METADATA_KEY, metadata, target);
+            return;
+        }
+
+        // Property decorator usage
+        if (propertyKey !== undefined) {
+            const key = propertyKey.toString();
+            const declaringType = (target as { constructor: Function }).constructor;
+
+            // Encrypting the event source identifier would make its own decryption key
+            // unfindable - the identifier is required, in the clear, to correlate events and
+            // look up the key that protects everything else. Mirrors @pii()'s
+            // PIINotSupportedOnEventSourceId guard, for the same reason.
+            if (key === EVENT_SOURCE_ID_PROPERTY) {
+                throw new EncryptedNotSupportedOnEventSourceId(declaringType.name);
+            }
+
+            TypeIntrospector.trackProperty(declaringType, key);
+            const metadata: SecurityMetadata = {
+                metadataType: metadataTypeFor(scope),
+                details: details ?? ''
+            };
+            Reflect.defineMetadata(ENCRYPTED_PROPERTY_METADATA_KEY, metadata, target, key);
+        }
+    };
+}
+
+/**
+ * Gets the encrypted security metadata for a property.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns The security metadata, or undefined if not decorated with @encrypted.
+ */
+export function getEncryptedMetadata(target: object, propertyKey: string): SecurityMetadata | undefined {
+    return Reflect.getMetadata(ENCRYPTED_PROPERTY_METADATA_KEY, target, propertyKey);
+}
+
+/**
+ * Checks whether a property has been decorated with @encrypted.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns True if the property has @encrypted decorator; false otherwise.
+ */
+export function hasEncryptedMetadata(target: object, propertyKey: string): boolean {
+    return Reflect.hasMetadata(ENCRYPTED_PROPERTY_METADATA_KEY, target, propertyKey);
+}
+
+/**
+ * Gets the encrypted security metadata for a type.
+ * @param type - The type constructor.
+ * @returns The security metadata, or undefined if not decorated with @encrypted.
+ */
+export function getTypeEncryptedMetadata(type: Function): SecurityMetadata | undefined {
+    return Reflect.getMetadata(ENCRYPTED_TYPE_METADATA_KEY, type);
+}
+
+/**
+ * Checks whether a type has been decorated with @encrypted.
+ * @param type - The type constructor.
+ * @returns True if the type has @encrypted decorator; false otherwise.
+ */
+export function isEncrypted(type: Function): boolean {
+    return Reflect.hasMetadata(ENCRYPTED_TYPE_METADATA_KEY, type);
+}

package/confidentiality/index.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export { SecurityMetadataType } from './SecurityMetadataType';
+export type { SecurityMetadata } from './SecurityMetadata';
+export { EncryptionScope } from './EncryptionScope';
+export { encrypted, getEncryptedMetadata, hasEncryptedMetadata, getTypeEncryptedMetadata, isEncrypted } from './encrypted';
+export { EncryptedNotSupportedOnEventSourceId } from './EncryptedNotSupportedOnEventSourceId';
+export { PIIAndEncryptedCombinedNotSupported } from './PIIAndEncryptedCombinedNotSupported';
+export { SecurityMetadataResolver } from './SecurityMetadataResolver';

package/dist/confidentiality/EncryptedNotSupportedOnEventSourceId.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Error thrown when the {@link encrypted} decorator is applied to the `eventSourceId` property.
+ */
+export declare class EncryptedNotSupportedOnEventSourceId extends Error {
+    /**
+     * Initializes a new instance of the {@link EncryptedNotSupportedOnEventSourceId} class.
+     * @param typeName - The name of the type the decorator was applied to.
+     */
+    constructor(typeName: string);
+}
+//# sourceMappingURL=EncryptedNotSupportedOnEventSourceId.d.ts.map

package/dist/confidentiality/EncryptedNotSupportedOnEventSourceId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptedNotSupportedOnEventSourceId.d.ts","sourceRoot":"","sources":["../../confidentiality/EncryptedNotSupportedOnEventSourceId.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,qBAAa,oCAAqC,SAAQ,KAAK;IAC3D;;;OAGG;gBACS,QAAQ,EAAE,MAAM;CAS/B"}

package/dist/confidentiality/EncryptedNotSupportedOnEventSourceId.js

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * Error thrown when the {@link encrypted} decorator is applied to the `eventSourceId` property.
+ */
+export class EncryptedNotSupportedOnEventSourceId extends Error {
+    /**
+     * Initializes a new instance of the {@link EncryptedNotSupportedOnEventSourceId} class.
+     * @param typeName - The name of the type the decorator was applied to.
+     */
+    constructor(typeName) {
+        super(`The @encrypted() decorator cannot be applied to 'eventSourceId' on '${typeName}' because it is the ` +
+            'event source identifier. Event source identifiers cannot be encrypted as they are required for event ' +
+            'correlation. If the identifier itself is sensitive, use a non-sensitive surrogate value as the event ' +
+            'source identifier and store the sensitive value in a separate property marked with @encrypted().');
+        this.name = 'EncryptedNotSupportedOnEventSourceId';
+    }
+}
+//# sourceMappingURL=EncryptedNotSupportedOnEventSourceId.js.map

package/dist/confidentiality/EncryptedNotSupportedOnEventSourceId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptedNotSupportedOnEventSourceId.js","sourceRoot":"","sources":["../../confidentiality/EncryptedNotSupportedOnEventSourceId.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG;;GAEG;AACH,MAAM,OAAO,oCAAqC,SAAQ,KAAK;IAC3D;;;OAGG;IACH,YAAY,QAAgB;QACxB,KAAK,CACD,uEAAuE,QAAQ,sBAAsB;YACrG,uGAAuG;YACvG,uGAAuG;YACvG,kGAAkG,CACrG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sCAAsC,CAAC;IACvD,CAAC;CACJ"}

package/dist/confidentiality/EncryptionScope.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Defines the identity an `@encrypted()` value's encryption key is provisioned under.
+ *
+ * `@pii()` never gains any scope beyond {@link EncryptionScope.Subject} - GDPR compliance is always
+ * resolved against a compliance identity, and widening that would make the compliance subject
+ * boundary itself scope-dependent. `EncryptionScope` exists precisely because `@encrypted()` values
+ * have no data subject and no erasure obligation, so a wider key boundary is safe for them in a way
+ * it is not for PII.
+ */
+export declare enum EncryptionScope {
+    /**
+     * The key is provisioned per compliance identity (the same identity - subject or, when none is
+     * set, event source id - PII values on the same document resolve to), and is looked up the same
+     * way. This is the default.
+     */
+    Subject = 0,
+    /**
+     * The key is provisioned once per event store namespace, independent of any document's subject
+     * or compliance identity. Every `@encrypted(EncryptionScope.Namespace)` value in a namespace
+     * shares one key.
+     */
+    Namespace = 1,
+    /**
+     * The key is provisioned once for the whole Chronicle installation, independent of event store,
+     * namespace, or compliance identity. Every `@encrypted(EncryptionScope.Global)` value across
+     * every event store and namespace shares one key.
+     */
+    Global = 2
+}
+//# sourceMappingURL=EncryptionScope.d.ts.map

package/dist/confidentiality/EncryptionScope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptionScope.d.ts","sourceRoot":"","sources":["../../confidentiality/EncryptionScope.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,oBAAY,eAAe;IACvB;;;;OAIG;IACH,OAAO,IAAI;IAEX;;;;OAIG;IACH,SAAS,IAAI;IAEb;;;;OAIG;IACH,MAAM,IAAI;CACb"}

package/dist/confidentiality/EncryptionScope.js

@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * Defines the identity an `@encrypted()` value's encryption key is provisioned under.
+ *
+ * `@pii()` never gains any scope beyond {@link EncryptionScope.Subject} - GDPR compliance is always
+ * resolved against a compliance identity, and widening that would make the compliance subject
+ * boundary itself scope-dependent. `EncryptionScope` exists precisely because `@encrypted()` values
+ * have no data subject and no erasure obligation, so a wider key boundary is safe for them in a way
+ * it is not for PII.
+ */
+export var EncryptionScope;
+(function (EncryptionScope) {
+    /**
+     * The key is provisioned per compliance identity (the same identity - subject or, when none is
+     * set, event source id - PII values on the same document resolve to), and is looked up the same
+     * way. This is the default.
+     */
+    EncryptionScope[EncryptionScope["Subject"] = 0] = "Subject";
+    /**
+     * The key is provisioned once per event store namespace, independent of any document's subject
+     * or compliance identity. Every `@encrypted(EncryptionScope.Namespace)` value in a namespace
+     * shares one key.
+     */
+    EncryptionScope[EncryptionScope["Namespace"] = 1] = "Namespace";
+    /**
+     * The key is provisioned once for the whole Chronicle installation, independent of event store,
+     * namespace, or compliance identity. Every `@encrypted(EncryptionScope.Global)` value across
+     * every event store and namespace shares one key.
+     */
+    EncryptionScope[EncryptionScope["Global"] = 2] = "Global";
+})(EncryptionScope || (EncryptionScope = {}));
+//# sourceMappingURL=EncryptionScope.js.map

package/dist/confidentiality/EncryptionScope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptionScope.js","sourceRoot":"","sources":["../../confidentiality/EncryptionScope.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG;;;;;;;;GAQG;AACH,MAAM,CAAN,IAAY,eAqBX;AArBD,WAAY,eAAe;IACvB;;;;OAIG;IACH,2DAAW,CAAA;IAEX;;;;OAIG;IACH,+DAAa,CAAA;IAEb;;;;OAIG;IACH,yDAAU,CAAA;AACd,CAAC,EArBW,eAAe,KAAf,eAAe,QAqB1B"}

package/dist/confidentiality/PIIAndEncryptedCombinedNotSupported.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Error thrown when a property, or the type it resolves metadata from, carries both `@pii()` and
+ * `@encrypted()`.
+ *
+ * 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 (a padding/authentication error) rather than returning a wrong value. A value
+ * needs exactly one protection: `@pii()` when it is personal data with a lawful basis for erasure,
+ * `@encrypted()` when it is an operational secret with none.
+ */
+export declare class PIIAndEncryptedCombinedNotSupported extends Error {
+    /**
+     * Initializes a new instance of the {@link PIIAndEncryptedCombinedNotSupported} class.
+     * @param property - The name of the property (or type) carrying both decorators.
+     */
+    constructor(property: string);
+}
+//# sourceMappingURL=PIIAndEncryptedCombinedNotSupported.d.ts.map

package/dist/confidentiality/PIIAndEncryptedCombinedNotSupported.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PIIAndEncryptedCombinedNotSupported.d.ts","sourceRoot":"","sources":["../../confidentiality/PIIAndEncryptedCombinedNotSupported.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,qBAAa,mCAAoC,SAAQ,KAAK;IAC1D;;;OAGG;gBACS,QAAQ,EAAE,MAAM;CAS/B"}

package/dist/confidentiality/PIIAndEncryptedCombinedNotSupported.js

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * Error thrown when a property, or the type it resolves metadata from, carries both `@pii()` and
+ * `@encrypted()`.
+ *
+ * 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 (a padding/authentication error) rather than returning a wrong value. A value
+ * needs exactly one protection: `@pii()` when it is personal data with a lawful basis for erasure,
+ * `@encrypted()` when it is an operational secret with none.
+ */
+export class PIIAndEncryptedCombinedNotSupported extends Error {
+    /**
+     * Initializes a new instance of the {@link PIIAndEncryptedCombinedNotSupported} class.
+     * @param property - The name of the property (or type) carrying both decorators.
+     */
+    constructor(property) {
+        super(`'${property}' carries both @pii() and @encrypted(). A value needs exactly one protection - combining ` +
+            'them would encrypt it twice, under two different keys, and it cannot be released correctly. Choose ' +
+            '@pii() for personal data with a lawful basis for erasure, or @encrypted() for an operational secret ' +
+            'with none.');
+        this.name = 'PIIAndEncryptedCombinedNotSupported';
+    }
+}
+//# sourceMappingURL=PIIAndEncryptedCombinedNotSupported.js.map

package/dist/confidentiality/PIIAndEncryptedCombinedNotSupported.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PIIAndEncryptedCombinedNotSupported.js","sourceRoot":"","sources":["../../confidentiality/PIIAndEncryptedCombinedNotSupported.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG;;;;;;;;;;GAUG;AACH,MAAM,OAAO,mCAAoC,SAAQ,KAAK;IAC1D;;;OAGG;IACH,YAAY,QAAgB;QACxB,KAAK,CACD,IAAI,QAAQ,2FAA2F;YACvG,qGAAqG;YACrG,sGAAsG;YACtG,YAAY,CACf,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qCAAqC,CAAC;IACtD,CAAC;CACJ"}