@aidc-toolkit/utility 1.0.24-beta → 1.0.26-beta

package/dist/string.d.ts

@@ -0,0 +1,25 @@
+/**
+ * String validation interface. To ensure signature compatibility in implementing classes, string validation is
+ * controlled by validation interfaces specific to each validator type.
+ */
+export interface StringValidation {
+}
+/**
+ * String validator interface.
+ *
+ * @template TStringValidation
+ * String validation type.
+ */
+export interface StringValidator<TStringValidation extends StringValidation = StringValidation> {
+    /**
+     * Validate a string and throw an error if validation fails.
+     *
+     * @param s
+     * String.
+     *
+     * @param validation
+     * String validation parameters.
+     */
+    validate: (s: string, validation?: TStringValidation) => void;
+}
+//# sourceMappingURL=string.d.ts.map

package/dist/string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../src/string.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,gBAAgB;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,iBAAiB,SAAS,gBAAgB,GAAG,gBAAgB;IAC1F;;;;;;;;OAQG;IACH,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACjE"}

package/dist/string.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=string.js.map

package/dist/string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.js","sourceRoot":"","sources":["../src/string.ts"],"names":[],"mappings":""}

package/dist/transformer.d.ts

@@ -0,0 +1,347 @@
+import { type IndexedCallback } from "./iterable-utility.js";
+/**
+ * Transformer primitive type.
+ */
+export type TransformerPrimitive = string | number | bigint | boolean;
+/**
+ * Transformer input type, one of:
+ *
+ * - TInput (primitive type)
+ * - Iterable\<TInput\>
+ *
+ * @template TInput
+ * Transformer input primitive type.
+ */
+export type TransformerInput<TInput extends TransformerPrimitive> = TInput | Iterable<TInput>;
+/**
+ * Transformer output, based on transformer input:
+ *
+ * - If type TTransformerInput is primitive, result is type TOutput.
+ * - If type TTransformerInput is Iterable, result is type Iterable\<TOutput\>.
+ *
+ * @template TTransformerInput
+ * Transformer input type.
+ *
+ * @template TOutput
+ * Output base type.
+ */
+export type TransformerOutput<TTransformerInput extends TransformerInput<TransformerPrimitive>, TOutput> = TTransformerInput extends (TTransformerInput extends TransformerInput<infer TInput> ? TInput : never) ? TOutput : Iterable<TOutput>;
+/**
+ * Transformer that transforms values in a numeric domain to values in a range equal to the domain or to another range
+ * defined by a callback function. In other words, the domain determines valid input values and, without a callback, the
+ * range of valid output values.
+ *
+ * The concept is similar to {@link https://en.wikipedia.org/wiki/Format-preserving_encryption | format-preserving
+ * encryption}, where input values within a specified domain (e.g., {@link
+ * https://en.wikipedia.org/wiki/Payment_card_number | payment card numbers} ranging from 8-19 digits) are transformed
+ * into values in the same domain, typically for storage in a database where the data type and length are already fixed
+ * and exfiltration of the data can have significant repercussions.
+ *
+ * Two subclasses are supported directly by this class: {@linkcode IdentityTransformer} (which operates based on a
+ * domain only) and {@linkcode EncryptionTransformer} (which operates based on a domain and a tweak). If an application
+ * is expected to make repeated use of a transformer with the same domain and (optional) tweak and can't manage the
+ * transformer object, an in-memory cache is available via the {@linkcode get | get()} method. Properties in {@linkcode
+ * IdentityTransformer} and {@linkcode EncryptionTransformer} are read-only once constructed, so there is no issue with
+ * their shared use.
+ */
+export declare abstract class Transformer {
+    /**
+     * Transformers cache, mapping a domain to another map, which maps an optional tweak to a transformer.
+     */
+    private static readonly TRANSFORMER_MAPS_MAP;
+    /**
+     * Domain.
+     */
+    private readonly _domain;
+    /**
+     * Constructor.
+     *
+     * @param domain
+     * Domain.
+     */
+    constructor(domain: number | bigint);
+    /**
+     * Get a transformer, constructing it if necessary. The type returned is {@linkcode IdentityTransformer} if tweak is
+     * undefined, {@linkcode EncryptionTransformer} if tweak is defined. Note that although an {@linkcode
+     * EncryptionTransformer} with a zero tweak operates as an {@linkcode IdentityTransformer}, {@linkcode
+     * EncryptionTransformer} is still the type returned if a zero tweak is explicitly specified.
+     *
+     * @param domain
+     * Domain.
+     *
+     * @param tweak
+     * Tweak.
+     *
+     * @returns
+     * {@linkcode IdentityTransformer} if tweak is undefined, {@linkcode EncryptionTransformer} if tweak is defined.
+     */
+    static get(domain: number | bigint, tweak?: number | bigint): Transformer;
+    /**
+     * Get the domain.
+     */
+    get domain(): bigint;
+    /**
+     * Validate that a value is within the domain.
+     *
+     * @param value
+     * Value.
+     */
+    private validate;
+    /**
+     * Do the work of transforming a value forward.
+     *
+     * @param value
+     * Value.
+     *
+     * @returns
+     * Transformed value.
+     */
+    protected abstract doForward(value: bigint): bigint;
+    /**
+     * Validate that a value is within the domain and do the work of transforming it forward.
+     *
+     * @param value
+     * Value.
+     *
+     * @returns
+     * Transformed value.
+     */
+    private validateDoForward;
+    /**
+     * Validate that a value is within the domain, do the work of transforming it forward, and apply a callback.
+     *
+     * @param transformerCallback
+     * Called after each value is transformed to convert it to its final value.
+     *
+     * @param value
+     * Value.
+     *
+     * @param index
+     * Index in sequence (0 for single transformation).
+     *
+     * @returns
+     * Transformed value.
+     */
+    private validateDoForwardCallback;
+    /**
+     * Transform value(s) forward.
+     *
+     * @template TTransformerInput
+     * Value(s) input type.
+     *
+     * @param valueOrValues
+     * Value(s). If this is an instance of {@linkcode Sequence}, the minimum and maximum values are validated prior to
+     * transformation. Otherwise, the individual value(s) is/are validated at the time of transformation.
+     *
+     * @returns
+     * Transformed value(s).
+     */
+    forward<TTransformerInput extends TransformerInput<number | bigint>>(valueOrValues: TTransformerInput): TransformerOutput<TTransformerInput, bigint>;
+    /**
+     * Transform value(s) forward, optionally applying a transformation.
+     *
+     * @template TTransformerInput
+     * Value(s) input type.
+     *
+     * @template TOutput
+     * Transformation callback output type.
+     *
+     * @param valueOrValues
+     * Value(s). If this is an instance of {@linkcode Sequence}, the minimum and maximum values are validated prior to
+     * transformation. Otherwise, the individual value(s) is/are validated at the time of transformation.
+     *
+     * @param transformerCallback
+     * Called after each value is transformed to convert it to its final value.
+     *
+     * @returns
+     * Transformed value(s).
+     */
+    forward<TTransformerInput extends TransformerInput<number | bigint>, TOutput>(valueOrValues: TTransformerInput, transformerCallback: IndexedCallback<bigint, TOutput>): TransformerOutput<TTransformerInput, TOutput>;
+    /**
+     * Do the work of transforming a value in reverse.
+     *
+     * @param transformedValue
+     * Transformed value.
+     *
+     * @returns
+     * Value.
+     */
+    protected abstract doReverse(transformedValue: bigint): bigint;
+    /**
+     * Transform a value in reverse.
+     *
+     * @param transformedValue
+     * Transformed value.
+     *
+     * @returns
+     * Value.
+     */
+    reverse(transformedValue: number | bigint): bigint;
+}
+/**
+ * Identity transformer. Values are transformed to themselves.
+ */
+export declare class IdentityTransformer extends Transformer {
+    /**
+     * @inheritDoc
+     */
+    protected doForward(value: bigint): bigint;
+    /**
+     * @inheritDoc
+     */
+    protected doReverse(transformedValue: bigint): bigint;
+}
+/**
+ * Encryption transformer. Values are transformed using repeated shuffle and xor operations, similar to those found in
+ * many cryptography algorithms, particularly AES. While sufficient for obfuscation of numeric sequences (e.g., serial
+ * number generation, below), if true format-preserving encryption is required, a more robust algorithm such as {@link
+ * https://doi.org/10.6028/NIST.SP.800-38Gr1.2pd | FF1} is recommended. Furthermore, no work has been done to mitigate
+ * {@link https://timing.attacks.cr.yp.to/index.html | timing attacks} for key detection.
+ *
+ * The purpose of the encryption transformer is to generate pseudo-random values in a deterministic manner to obscure
+ * the sequence of values generated over time. A typical example is for serial number generation, where knowledge of the
+ * sequence can infer production volumes (e.g., serial number 1000 implies that at least 1,000 units have been
+ * manufactured) or can be used in counterfeiting (e.g., a counterfeiter can generate serial numbers 1001, 1002, ...
+ * with reasonable confidence that they would be valid if queried).
+ *
+ * The domain and the tweak together determine the encryption key, which in turn determines the number of rounds of
+ * shuffle and xor operations. The minimum number of rounds is 4, except where the domain is less than or equal to 256,
+ * which results in single-byte operations. To ensure that the operations are effective for single-byte domains, the
+ * number of rounds is 1 and only the xor operation is applied (shuffling a single byte is an identity operation).
+ *
+ * Another exception is when there is a tweak value of 0; this results in identity operations where the output value is
+ * identical to the input value, as no shuffle or xor takes place.
+ */
+export declare class EncryptionTransformer extends Transformer {
+    /**
+     * Individual bits, pre-calculated for performance.
+     */
+    private static readonly BITS;
+    /**
+     * Inverse individual bits, pre-calculated for performance.
+     */
+    private static readonly INVERSE_BITS;
+    /**
+     * Number of bytes covered by the domain.
+     */
+    private readonly _domainBytes;
+    /**
+     * Xor bytes array generated from the domain and tweak.
+     */
+    private readonly _xorBytes;
+    /**
+     * Bits array generated from the domain and tweak.
+     */
+    private readonly _bits;
+    /**
+     * Inverse bits array generated from the domain and tweak.
+     */
+    private readonly _inverseBits;
+    /**
+     * Number of rounds (length of arrays) generated from the domain and tweak.
+     */
+    private readonly _rounds;
+    /**
+     * Constructor.
+     *
+     * @param domain
+     * Domain.
+     *
+     * @param tweak
+     * Tweak.
+     */
+    constructor(domain: number | bigint, tweak: number | bigint);
+    /**
+     * Convert a value to a byte array big enough to handle the entire domain.
+     *
+     * @param value
+     * Value.
+     *
+     * @returns
+     * Big-endian byte array equivalent to the value.
+     */
+    private valueToBytes;
+    /**
+     * Convert a byte array to a value.
+     *
+     * @param bytes
+     * Big-endian byte array equivalent to the value.
+     *
+     * @returns
+     * Value.
+     */
+    private static bytesToValue;
+    /**
+     * Shuffle a byte array.
+     *
+     * The input array to the forward operation (output from the reverse operation) is `bytes` and the output array from
+     * the forward operation (input to the reverse operation) is `bytes'`.
+     *
+     * The shuffle operation starts by testing the bit at `bits[round]` for each `byte` in `bytes`. The indexes for all
+     * bytes with that bit set are put into one array (`shuffleIndexes1`) and the rest are put into another
+     * (`shuffleIndexes0`). The two arrays are concatenated and used to shuffle the input array, using their values
+     * (`shuffleIndex`) and the indexes of those values (`index`) in the concatenated array.
+     *
+     * Forward shuffling moves the entry at `shuffleIndex` to the `index` position.
+     *
+     * Reverse shuffling moves the entry at `index` to the `shuffleIndex` position.
+     *
+     * As each byte is moved, the bit at `bits[round]` is preserved in its original position. This ensures that the
+     * process is reversible.
+     *
+     * @param bytes
+     * Byte array.
+     *
+     * @param round
+     * Round number.
+     *
+     * @param forward
+     * True if operating forward (encrypting), false if operating in reverse (decrypting).
+     *
+     * @returns
+     * Shuffled byte array.
+     */
+    private shuffle;
+    /**
+     * Xor a byte array.
+     *
+     * The input array to the forward operation (output from the reverse operation) is `bytes` and the output array from
+     * the forward operation (input to the reverse operation) is `bytes'`.
+     *
+     * Forward:
+     * - `bytes'[0] = bytes[0] ^ xorBytes[round]`
+     * - `bytes'[1] = bytes[1] ^ bytes'[0]`
+     * - `bytes'[2] = bytes[2] ^ bytes'[1]`
+     * - `...`
+     * - `bytes'[domainBytes - 1] = bytes[domainBytes - 1] ^ bytes'[domainBytes - 2]`
+     *
+     * Reverse:
+     * - `bytes[0] = bytes'[0] ^ xorBytes[round]`
+     * - `bytes[1] = bytes'[1] ^ bytes'[0]`
+     * - `bytes[2] = bytes'[2] ^ bytes'[1]`
+     * - `...`
+     * - `bytes[domainBytes - 1] = bytes'[domainBytes - 1] ^ bytes'[domainBytes - 2]`
+     *
+     * @param bytes
+     * Byte array.
+     *
+     * @param round
+     * Round number.
+     *
+     * @param forward
+     * True if operating forward (encrypting), false if operating in reverse (decrypting).
+     *
+     * @returns
+     * Xored byte array.
+     */
+    private xor;
+    /**
+     * @inheritDoc
+     */
+    protected doForward(value: bigint): bigint;
+    /**
+     * @inheritDoc
+     */
+    protected doReverse(transformedValue: bigint): bigint;
+}
+//# sourceMappingURL=transformer.d.ts.map

package/dist/transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformer.d.ts","sourceRoot":"","sources":["../src/transformer.ts"],"names":[],"mappings":"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"}