@jscv-solutions/node-crypto 0.0.0-stage → 1.0.0-rc.1

package/dist/esm/shared/algorithms.js

@@ -0,0 +1,21 @@
+/**
+ * Algorithm identifier validation shared by every namespace.
+ *
+ * Identifiers are lowercase kebab-case strings (for example `sha-256`,
+ * `argon2id`). Anything a function does not support — unknown names and
+ * malformed identifiers alike — throws an `UnsupportedAlgorithmError`.
+ * Identifiers are public names and safe to include in messages.
+ */
+import { UnsupportedAlgorithmError } from './errors.js';
+/**
+ * Asserts the received identifier is one of the supported identifiers.
+ *
+ * @param algorithm - Identifier passed by the caller.
+ * @param supported - Identifiers the calling function supports.
+ * @throws {UnsupportedAlgorithmError} WHEN the identifier is unsupported.
+ */
+export function assertSupportedAlgorithm(algorithm, supported) {
+    if (!supported.includes(algorithm)) {
+        throw new UnsupportedAlgorithmError(`Unsupported algorithm '${algorithm}'. Supported algorithms: ${supported.join(', ')}.`);
+    }
+}

package/dist/esm/shared/deprecation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Deprecation signalling shared by every namespace.
+ *
+ * A deprecated algorithm is marked with the JSDoc `@deprecated` tag at
+ * its declaration site and calls `emitDeprecationWarning` on first use.
+ * Warnings go through `process.emitWarning` (never `console.warn`) so
+ * they honor `--no-warnings` and `--disable-warning`, and each stable
+ * warning code is emitted at most once per process. The algorithm name
+ * is public and safe to include in the message.
+ */
+/**
+ * Derives the stable process-warning code for a deprecated algorithm.
+ *
+ * @param algorithm - Lowercase kebab-case algorithm identifier.
+ * @returns The stable warning code for the algorithm.
+ */
+export declare function deprecationCodeFor(algorithm: string): string;
+/**
+ * Emits the deprecation warning for an algorithm, once per process.
+ *
+ * @param algorithm - Lowercase kebab-case algorithm identifier.
+ */
+export declare function emitDeprecationWarning(algorithm: string): void;

package/dist/esm/shared/deprecation.js

@@ -0,0 +1,34 @@
+/**
+ * Deprecation signalling shared by every namespace.
+ *
+ * A deprecated algorithm is marked with the JSDoc `@deprecated` tag at
+ * its declaration site and calls `emitDeprecationWarning` on first use.
+ * Warnings go through `process.emitWarning` (never `console.warn`) so
+ * they honor `--no-warnings` and `--disable-warning`, and each stable
+ * warning code is emitted at most once per process. The algorithm name
+ * is public and safe to include in the message.
+ */
+const emittedCodes = new Set();
+/**
+ * Derives the stable process-warning code for a deprecated algorithm.
+ *
+ * @param algorithm - Lowercase kebab-case algorithm identifier.
+ * @returns The stable warning code for the algorithm.
+ */
+export function deprecationCodeFor(algorithm) {
+    const token = algorithm.toUpperCase().replace(/-/g, '_');
+    return `NODE_CRYPTO_DEPRECATED_${token}`;
+}
+/**
+ * Emits the deprecation warning for an algorithm, once per process.
+ *
+ * @param algorithm - Lowercase kebab-case algorithm identifier.
+ */
+export function emitDeprecationWarning(algorithm) {
+    const code = deprecationCodeFor(algorithm);
+    if (emittedCodes.has(code)) {
+        return;
+    }
+    emittedCodes.add(code);
+    process.emitWarning(`The '${algorithm}' algorithm is deprecated and will be removed in a future major release.`, { code, type: 'DeprecationWarning' });
+}

package/dist/esm/shared/encodings.d.ts

@@ -0,0 +1,30 @@
+import type { Encoding } from './typings/encodings.js';
+/**
+ * Encodes bytes as text with the requested encoding.
+ *
+ * @param data - Bytes to encode.
+ * @param encoding - Target text encoding.
+ * @returns The encoded text (`base64url` output is unpadded).
+ */
+export declare function encodeBytes(data: Uint8Array, encoding: Encoding): string;
+/**
+ * Decodes text back into bytes, strictly validating the input.
+ *
+ * @param text - Encoded text to decode.
+ * @param encoding - Text encoding the input claims to use.
+ * @returns The decoded bytes.
+ * @throws {InvalidEncodingError} WHEN the text breaks the encoding rules.
+ */
+export declare function decodeText(text: string, encoding: Encoding): Buffer;
+/**
+ * Checks text against the alphabet and shape rules of an encoding.
+ *
+ * `base64` follows the padded canonical form. `base64url` accepts the
+ * unpadded form the encoder emits (whose length is never one past a
+ * multiple of four) as well as correctly padded input.
+ *
+ * @param text - Candidate encoded text.
+ * @param encoding - Encoding whose rules apply.
+ * @returns Whether the text is well formed for the encoding.
+ */
+export declare function isWellFormed(text: string, encoding: Encoding): boolean;

package/dist/esm/shared/encodings.js

@@ -0,0 +1,64 @@
+/**
+ * Binary-to-text encodings shared by every namespace.
+ *
+ * Supported encodings are `hex`, `base64` and `base64url`. Decoding is
+ * strict: input outside the encoding alphabet (or breaking its length
+ * and padding rules) throws an `InvalidEncodingError` instead of being
+ * silently truncated the way `Buffer.from` would on its own. Error
+ * messages never echo the offending input.
+ */
+import { InvalidEncodingError } from './errors.js';
+const HEXPattern = /^[0-9a-fA-F]*$/;
+const base64Pattern = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+const base64UrlPaddedPattern = /^(?:[A-Za-z0-9\-_]{4})*(?:[A-Za-z0-9\-_]{2}==|[A-Za-z0-9\-_]{3}=)?$/;
+const base64UrlUnpaddedPattern = /^[A-Za-z0-9\-_]*$/;
+/**
+ * Encodes bytes as text with the requested encoding.
+ *
+ * @param data - Bytes to encode.
+ * @param encoding - Target text encoding.
+ * @returns The encoded text (`base64url` output is unpadded).
+ */
+export function encodeBytes(data, encoding) {
+    const buffer = Buffer.from(data);
+    const text = buffer.toString(encoding);
+    return text;
+}
+/**
+ * Decodes text back into bytes, strictly validating the input.
+ *
+ * @param text - Encoded text to decode.
+ * @param encoding - Text encoding the input claims to use.
+ * @returns The decoded bytes.
+ * @throws {InvalidEncodingError} WHEN the text breaks the encoding rules.
+ */
+export function decodeText(text, encoding) {
+    if (!isWellFormed(text, encoding)) {
+        throw new InvalidEncodingError(`Invalid ${encoding} string: input breaks the ${encoding} rules.`);
+    }
+    const buffer = Buffer.from(text, encoding);
+    return buffer;
+}
+/**
+ * Checks text against the alphabet and shape rules of an encoding.
+ *
+ * `base64` follows the padded canonical form. `base64url` accepts the
+ * unpadded form the encoder emits (whose length is never one past a
+ * multiple of four) as well as correctly padded input.
+ *
+ * @param text - Candidate encoded text.
+ * @param encoding - Encoding whose rules apply.
+ * @returns Whether the text is well formed for the encoding.
+ */
+export function isWellFormed(text, encoding) {
+    if (encoding === 'hex') {
+        return text.length % 2 === 0 && HEXPattern.test(text);
+    }
+    if (encoding === 'base64') {
+        return text.length % 4 === 0 && base64Pattern.test(text);
+    }
+    if (text.includes('=')) {
+        return text.length % 4 === 0 && base64UrlPaddedPattern.test(text);
+    }
+    return text.length % 4 !== 1 && base64UrlUnpaddedPattern.test(text);
+}

package/dist/esm/shared/errors.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Error model shared by every namespace of the library.
+ *
+ * Every error thrown by the library is an instance of `NodeCryptoError`
+ * (or a subclass) and carries a stable string `code` that callers can
+ * switch on. Codes are part of the public contract: never rename or
+ * remove one without a major release.
+ *
+ * Message hygiene: constructors accept a message built by the throwing
+ * code. Callers MUST NOT interpolate secrets, passwords, keys or
+ * plaintext into messages. Algorithm identifiers and package names are
+ * public and safe to include.
+ */
+import type { ErrorCode } from './typings/errors.js';
+/**
+ * Base class for every error thrown by the library.
+ */
+export declare class NodeCryptoError extends Error {
+    /** Stable machine-readable failure identifier. */
+    readonly code: ErrorCode;
+    /**
+     * Creates a library error with a stable code.
+     *
+     * @param message - Human-readable description without secrets.
+     * @param code - Stable machine-readable failure identifier.
+     * @param options - Optional error options (for example `cause`).
+     */
+    constructor(message: string, code: ErrorCode, options?: ErrorOptions);
+}
+/**
+ * A function received an argument of the wrong type or range.
+ */
+export declare class InvalidArgumentError extends NodeCryptoError {
+    /**
+     * Creates an invalid-argument error.
+     *
+     * @param message - Human-readable description without secrets.
+     * @param options - Optional error options (for example `cause`).
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Encoded text contains characters outside its alphabet or breaks the
+ * encoding rules (for example odd-length hexadecimal).
+ */
+export declare class InvalidEncodingError extends NodeCryptoError {
+    /**
+     * Creates an invalid-encoding error.
+     *
+     * @param message - Human-readable description without echoing the input.
+     * @param options - Optional error options (for example `cause`).
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * An optional peer dependency (for example `bcrypt`) is not installed,
+ * so the requested operation cannot run.
+ */
+export declare class MissingPeerDependencyError extends NodeCryptoError {
+    /**
+     * Creates a missing-peer-dependency error.
+     *
+     * @param message - Description naming the package and how to install it.
+     * @param options - Optional error options (for example `cause`).
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * The caller passed an algorithm identifier the function does not support.
+ */
+export declare class UnsupportedAlgorithmError extends NodeCryptoError {
+    /**
+     * Creates an unsupported-algorithm error.
+     *
+     * @param message - Description naming the received identifier.
+     * @param options - Optional error options (for example `cause`).
+     */
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/esm/shared/errors.js

@@ -0,0 +1,81 @@
+/**
+ * Base class for every error thrown by the library.
+ */
+export class NodeCryptoError extends Error {
+    /** Stable machine-readable failure identifier. */
+    code;
+    /**
+     * Creates a library error with a stable code.
+     *
+     * @param message - Human-readable description without secrets.
+     * @param code - Stable machine-readable failure identifier.
+     * @param options - Optional error options (for example `cause`).
+     */
+    constructor(message, code, options) {
+        super(message, options);
+        this.name = 'NodeCryptoError';
+        this.code = code;
+    }
+}
+/**
+ * A function received an argument of the wrong type or range.
+ */
+export class InvalidArgumentError extends NodeCryptoError {
+    /**
+     * Creates an invalid-argument error.
+     *
+     * @param message - Human-readable description without secrets.
+     * @param options - Optional error options (for example `cause`).
+     */
+    constructor(message, options) {
+        super(message, 'INVALID_ARGUMENT', options);
+        this.name = 'InvalidArgumentError';
+    }
+}
+/**
+ * Encoded text contains characters outside its alphabet or breaks the
+ * encoding rules (for example odd-length hexadecimal).
+ */
+export class InvalidEncodingError extends NodeCryptoError {
+    /**
+     * Creates an invalid-encoding error.
+     *
+     * @param message - Human-readable description without echoing the input.
+     * @param options - Optional error options (for example `cause`).
+     */
+    constructor(message, options) {
+        super(message, 'INVALID_ENCODING', options);
+        this.name = 'InvalidEncodingError';
+    }
+}
+/**
+ * An optional peer dependency (for example `bcrypt`) is not installed,
+ * so the requested operation cannot run.
+ */
+export class MissingPeerDependencyError extends NodeCryptoError {
+    /**
+     * Creates a missing-peer-dependency error.
+     *
+     * @param message - Description naming the package and how to install it.
+     * @param options - Optional error options (for example `cause`).
+     */
+    constructor(message, options) {
+        super(message, 'MISSING_PEER_DEPENDENCY', options);
+        this.name = 'MissingPeerDependencyError';
+    }
+}
+/**
+ * The caller passed an algorithm identifier the function does not support.
+ */
+export class UnsupportedAlgorithmError extends NodeCryptoError {
+    /**
+     * Creates an unsupported-algorithm error.
+     *
+     * @param message - Description naming the received identifier.
+     * @param options - Optional error options (for example `cause`).
+     */
+    constructor(message, options) {
+        super(message, 'UNSUPPORTED_ALGORITHM', options);
+        this.name = 'UnsupportedAlgorithmError';
+    }
+}

package/dist/esm/shared/inputs.d.ts

@@ -0,0 +1,9 @@
+import type { CryptoInput } from './typings/inputs.js';
+/**
+ * Normalizes accepted input into a fresh Buffer of bytes.
+ *
+ * @param input - String (UTF-8), Buffer or Uint8Array holding the data.
+ * @returns A Buffer copy of the input bytes.
+ * @throws {InvalidArgumentError} WHEN the input has an unexpected type.
+ */
+export declare function toBytes(input: CryptoInput): Buffer;

package/dist/esm/shared/inputs.js

@@ -0,0 +1,26 @@
+/**
+ * Input handling shared by every namespace.
+ *
+ * Wherever a function accepts data it accepts `CryptoInput`: a UTF-8
+ * string, a Buffer or a Uint8Array. Normalization copies the bytes, so
+ * later mutation of a caller-provided view cannot affect the operation.
+ */
+import { InvalidArgumentError } from './errors.js';
+/**
+ * Normalizes accepted input into a fresh Buffer of bytes.
+ *
+ * @param input - String (UTF-8), Buffer or Uint8Array holding the data.
+ * @returns A Buffer copy of the input bytes.
+ * @throws {InvalidArgumentError} WHEN the input has an unexpected type.
+ */
+export function toBytes(input) {
+    if (typeof input === 'string') {
+        const buffer = Buffer.from(input, 'utf8');
+        return buffer;
+    }
+    if (input instanceof Uint8Array) {
+        const buffer = Buffer.from(input);
+        return buffer;
+    }
+    throw new InvalidArgumentError('Invalid input: expected a string, Buffer or Uint8Array.');
+}

package/dist/esm/shared/peer-loading.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Loads a peer dependency asynchronously with dynamic `import`.
+ *
+ * @param specifier - Bare peer specifier to load (for example `bcrypt`).
+ * @returns The loaded peer module.
+ * @throws {MissingPeerDependencyError} WHEN the peer cannot be resolved.
+ */
+export declare function loadPeer(specifier: string): Promise<unknown>;
+/**
+ * Loads a peer dependency synchronously with the per-format loader.
+ *
+ * @param specifier - Bare peer specifier to load (for example `bcrypt`).
+ * @returns The loaded peer module.
+ * @throws {MissingPeerDependencyError} WHEN the peer cannot be resolved.
+ */
+export declare function loadPeerSync(specifier: string): unknown;

package/dist/esm/shared/peer-loading.js

@@ -0,0 +1,92 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Lazy loading for optional peer dependencies (currently `bcrypt`).
+ *
+ * Peers load only when an operation needing them is first invoked, so
+ * callers without the peer installed can still use every other
+ * namespace. Async callers use dynamic `import`; sync callers use the
+ * per-format `#sync-require` loader (native `require` in CJS,
+ * `createRequire` anchored at the loader file in ESM). A peer that
+ * cannot be resolved throws a `MissingPeerDependencyError` naming the
+ * package to install; any other load failure propagates unchanged.
+ */
+import { loadSyncPeer } from '#sync-require';
+import { MissingPeerDependencyError } from './errors.js';
+/**
+ * Extracts the Node.js error code from an unknown load failure.
+ *
+ * @param error - Failure raised while loading the peer.
+ * @returns The error code when present, otherwise undefined.
+ */
+function errorCodeOf(error) {
+    if (typeof error !== 'object' || error === null) {
+        return undefined;
+    }
+    if (!('code' in error)) {
+        return undefined;
+    }
+    const code = error.code;
+    return typeof code === 'string' ? code : undefined;
+}
+/**
+ * Reports whether a load failure means the peer is not installed.
+ *
+ * @param error - Failure raised while loading the peer.
+ * @returns Whether the peer module could not be resolved.
+ */
+function isPeerMissing(error) {
+    const code = errorCodeOf(error);
+    return code === 'MODULE_NOT_FOUND' || code === 'ERR_MODULE_NOT_FOUND';
+}
+/**
+ * Builds the missing-peer error naming the package to install.
+ *
+ * @param specifier - Bare peer specifier that could not be resolved.
+ * @param error - Original resolution failure, kept as `cause`.
+ * @returns The missing-peer-dependency error.
+ */
+function missingPeerError(specifier, error) {
+    return new MissingPeerDependencyError(`Optional peer dependency '${specifier}' is not installed. Install '${specifier}' to use this feature.`, { cause: error });
+}
+/**
+ * Loads a peer dependency asynchronously with dynamic `import`.
+ *
+ * @param specifier - Bare peer specifier to load (for example `bcrypt`).
+ * @returns The loaded peer module.
+ * @throws {MissingPeerDependencyError} WHEN the peer cannot be resolved.
+ */
+export function loadPeer(specifier) {
+    const peer = import(__rewriteRelativeImportExtension(specifier)).catch((error) => {
+        if (isPeerMissing(error)) {
+            throw missingPeerError(specifier, error);
+        }
+        throw error;
+    });
+    return peer;
+}
+/**
+ * Loads a peer dependency synchronously with the per-format loader.
+ *
+ * @param specifier - Bare peer specifier to load (for example `bcrypt`).
+ * @returns The loaded peer module.
+ * @throws {MissingPeerDependencyError} WHEN the peer cannot be resolved.
+ */
+export function loadPeerSync(specifier) {
+    try {
+        const peer = loadSyncPeer(specifier);
+        return peer;
+    }
+    catch (error) {
+        if (isPeerMissing(error)) {
+            throw missingPeerError(specifier, error);
+        }
+        throw error;
+    }
+}

package/dist/esm/shared/require-sync-esm.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Loads a peer dependency synchronously for ESM callers.
+ *
+ * @param specifier - Bare peer specifier to load (for example `bcrypt`).
+ * @returns The loaded peer module.
+ */
+export declare function loadSyncPeer(specifier: string): unknown;

package/dist/esm/shared/require-sync-esm.js

@@ -0,0 +1,20 @@
+/**
+ * Synchronous peer loader for ECMAScript module callers.
+ *
+ * This file is compiled only in the ESM build and the typecheck program
+ * (see the `#sync-require` mapping and the per-build `exclude` lists), so
+ * `import.meta` never reaches CommonJS output. The `createRequire` anchor
+ * is this file, so the peer resolves from the consumer's installation.
+ */
+import { createRequire } from 'node:module';
+const peerRequire = createRequire(import.meta.url);
+/**
+ * Loads a peer dependency synchronously for ESM callers.
+ *
+ * @param specifier - Bare peer specifier to load (for example `bcrypt`).
+ * @returns The loaded peer module.
+ */
+export function loadSyncPeer(specifier) {
+    const peer = peerRequire(specifier);
+    return peer;
+}

package/dist/esm/shared/typings/encodings.d.ts

@@ -0,0 +1,2 @@
+/** Text encodings the library reads and writes. */
+export type Encoding = 'hex' | 'base64' | 'base64url';

package/dist/esm/shared/typings/errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Stable string codes identifying every failure of the library. Codes
+ * are part of the public contract: never rename or remove one without
+ * a major release.
+ */
+export type ErrorCode =
+  | 'INVALID_ARGUMENT'
+  | 'INVALID_ENCODING'
+  | 'MISSING_PEER_DEPENDENCY'
+  | 'UNSUPPORTED_ALGORITHM';

package/dist/esm/shared/typings/inputs.d.ts

@@ -0,0 +1,2 @@
+/** Data accepted wherever a function takes input bytes. */
+export type CryptoInput = string | Buffer | Uint8Array;