yamlock 0.3.0 → 1.0.0

package/dist/crypto/utils.js

@@ -1,5 +1,11 @@
 import { createHash, getCipherInfo, getCiphers, randomBytes } from 'node:crypto';
 
+import {
+  YAMLOCK_ERROR_CODES,
+  YamlockPayloadError,
+  YamlockValidationError
+} from '../errors.js';
+
 export const YAMLOCK_PREFIX = 'yl';
 export const YAMLOCK_DELIMITER = '|';
 export const DEFAULT_ALGORITHM = 'aes-256-cbc';
@@ -26,20 +32,32 @@ export function listSupportedAlgorithms() {
  */
 export function ensureAlgorithm(algorithm) {
   if (!algorithm) {
-    throw new Error('Encryption algorithm is required.');
+    throw new YamlockValidationError('Encryption algorithm is required.', {
+      code: YAMLOCK_ERROR_CODES.UNSUPPORTED_ALGORITHM
+    });
   }
 
   if (!listSupportedAlgorithms().includes(algorithm)) {
-    throw new Error(`Unsupported algorithm: ${algorithm}`);
+    throw new YamlockValidationError(`Unsupported algorithm: ${algorithm}`, {
+      code: YAMLOCK_ERROR_CODES.UNSUPPORTED_ALGORITHM
+    });
   }
 
   return algorithm;
 }
 
 function normalizeAlgorithmInput(input) {
-  if (!input || typeof input === 'string') {
+  if (input === undefined || typeof input === 'string') {
     return { algorithm: input };
   }
+
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+    throw new YamlockValidationError(
+      'Algorithm options must be an object or algorithm string.',
+      { code: YAMLOCK_ERROR_CODES.INVALID_OPTIONS }
+    );
+  }
+
   return input;
 }
 
@@ -61,6 +79,19 @@ export function resolveAlgorithmOptions(input) {
   const ivLength = normalized.ivLength ?? preset.ivLength ?? cipherInfo.ivLength ?? 16;
   const authTagLength = normalized.authTagLength ?? preset.authTagLength ?? 0;
 
+  for (const [name, value, minimum] of [
+    ['keyLength', keyLength, 1],
+    ['ivLength', ivLength, 0],
+    ['authTagLength', authTagLength, 0]
+  ]) {
+    if (!Number.isInteger(value) || value < minimum) {
+      throw new YamlockValidationError(
+        `${name} must be an integer greater than or equal to ${minimum}.`,
+        { code: YAMLOCK_ERROR_CODES.INVALID_OPTIONS }
+      );
+    }
+  }
+
   return {
     algorithm: algorithmName,
     keyLength,
@@ -76,13 +107,19 @@ export function resolveAlgorithmOptions(input) {
  * @returns {Buffer}
  */
 export function deriveKey(secret, { algorithm, keyLength }) {
-  if (secret === undefined || secret === null || secret === '') {
-    throw new Error('Encryption key is required to derive a cipher key.');
+  if (
+    (!Buffer.isBuffer(secret) && typeof secret !== 'string') ||
+    secret.length === 0
+  ) {
+    throw new YamlockValidationError(
+      'Encryption key must be a non-empty string or Buffer.',
+      { code: YAMLOCK_ERROR_CODES.INVALID_KEY }
+    );
   }
 
   const baseBuffer = Buffer.isBuffer(secret)
     ? secret
-    : Buffer.from(String(secret), 'utf8');
+    : Buffer.from(secret, 'utf8');
 
   const normalizedAlgorithm = ensureAlgorithm(algorithm);
   const requiredLength = keyLength ?? getCipherInfo(normalizedAlgorithm)?.keyLength ?? 32;
@@ -129,11 +166,14 @@ export function generateIv({ algorithm, ivLength }) {
  * @returns {string}
  */
 export function encodeFieldPathSalt(fieldPath) {
-  if (!fieldPath) {
-    throw new Error('Field path is required to create a salt.');
+  if (typeof fieldPath !== 'string' || fieldPath.length === 0) {
+    throw new YamlockValidationError(
+      'Field path must be a non-empty string.',
+      { code: YAMLOCK_ERROR_CODES.INVALID_FIELD_PATH }
+    );
   }
 
-  return Buffer.from(String(fieldPath), 'utf8').toString('base64');
+  return Buffer.from(fieldPath, 'utf8').toString('base64');
 }
 
 /**
@@ -143,7 +183,9 @@ export function encodeFieldPathSalt(fieldPath) {
  */
 export function decodeFieldPathSalt(salt) {
   if (!salt) {
-    throw new Error('Salt value is required.');
+    throw new YamlockPayloadError('Salt value is required.', {
+      code: YAMLOCK_ERROR_CODES.INVALID_PAYLOAD
+    });
   }
 
   return Buffer.from(String(salt), 'base64').toString('utf8');
@@ -160,7 +202,10 @@ export function decodeFieldPathSalt(salt) {
  */
 export function formatPayload({ algorithm, salt, iv, data }) {
   if (!algorithm || !salt || !iv || !data) {
-    throw new Error('Algorithm, salt, IV, and data are required to format payload.');
+    throw new YamlockValidationError(
+      'Algorithm, salt, IV, and data are required to format payload.',
+      { code: YAMLOCK_ERROR_CODES.INVALID_OPTIONS }
+    );
   }
 
   return [
@@ -191,17 +236,23 @@ export function isYamlockPayload(candidate) {
  */
 export function parsePayload(value) {
   if (!isYamlockPayload(value)) {
-    throw new Error('Value is not a yamlock payload.');
+    throw new YamlockPayloadError('Value is not a yamlock payload.', {
+      code: YAMLOCK_ERROR_CODES.INVALID_PAYLOAD
+    });
   }
 
   const parts = value.split(YAMLOCK_DELIMITER);
   if (parts.length !== 5) {
-    throw new Error('Malformed yamlock payload.');
+    throw new YamlockPayloadError('Malformed yamlock payload.', {
+      code: YAMLOCK_ERROR_CODES.INVALID_PAYLOAD
+    });
   }
 
   const [, algorithm, salt, ivBase64, dataBase64] = parts;
   if (!algorithm || !salt || !ivBase64 || !dataBase64) {
-    throw new Error('Malformed yamlock payload segments.');
+    throw new YamlockPayloadError('Malformed yamlock payload segments.', {
+      code: YAMLOCK_ERROR_CODES.INVALID_PAYLOAD
+    });
   }
 
   return {

package/dist/errors.js

@@ -0,0 +1,59 @@
+const ERROR_CODE_PATTERN = /^ERR_[A-Z0-9_]+$/;
+
+export const YAMLOCK_ERROR_CODES = Object.freeze({
+  ALREADY_ENCRYPTED: 'ERR_ALREADY_ENCRYPTED',
+  AUTHENTICATION_FAILED: 'ERR_AUTHENTICATION_FAILED',
+  CIRCULAR_CONFIG: 'ERR_CIRCULAR_CONFIG',
+  DECRYPTION_FAILED: 'ERR_DECRYPTION_FAILED',
+  FIELD_PATH_MISMATCH: 'ERR_FIELD_PATH_MISMATCH',
+  INVALID_CONFIG_OPTIONS: 'ERR_INVALID_CONFIG_OPTIONS',
+  INVALID_CONFIG_ROOT: 'ERR_INVALID_CONFIG_ROOT',
+  INVALID_EXISTING_PAYLOAD_POLICY: 'ERR_INVALID_EXISTING_PAYLOAD_POLICY',
+  INVALID_FIELD_PATH: 'ERR_INVALID_FIELD_PATH',
+  INVALID_KEY: 'ERR_INVALID_KEY',
+  INVALID_MODE: 'ERR_INVALID_MODE',
+  INVALID_NON_STRING_POLICY: 'ERR_INVALID_NON_STRING_POLICY',
+  INVALID_OPTIONS: 'ERR_INVALID_OPTIONS',
+  INVALID_PATH_SEGMENTS: 'ERR_INVALID_PATH_SEGMENTS',
+  INVALID_PATH_SERIALIZER: 'ERR_INVALID_PATH_SERIALIZER',
+  INVALID_PATHS: 'ERR_INVALID_PATHS',
+  INVALID_PAYLOAD: 'ERR_INVALID_PAYLOAD',
+  INVALID_VALUE: 'ERR_INVALID_VALUE',
+  NON_STRING_VALUE: 'ERR_NON_STRING_VALUE',
+  PATH_COLLISION: 'ERR_PATH_COLLISION',
+  PAYLOAD_TOO_LARGE: 'ERR_PAYLOAD_TOO_LARGE',
+  UNSUPPORTED_ALGORITHM: 'ERR_UNSUPPORTED_ALGORITHM',
+  UNSUPPORTED_CONFIG_VALUE: 'ERR_UNSUPPORTED_CONFIG_VALUE',
+  UNSUPPORTED_PAYLOAD: 'ERR_UNSUPPORTED_PAYLOAD',
+  UNSUPPORTED_PAYLOAD_VERSION: 'ERR_UNSUPPORTED_PAYLOAD_VERSION',
+  VALUE_TOO_LARGE: 'ERR_VALUE_TOO_LARGE'
+});
+
+export class YamlockError extends Error {
+  constructor(message, { code, cause } = {}) {
+    if (typeof code !== 'string' || !ERROR_CODE_PATTERN.test(code)) {
+      throw new TypeError('YamlockError requires an ERR_* code.');
+    }
+
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = new.target.name;
+    this.code = code;
+  }
+}
+
+export class YamlockValidationError extends YamlockError {}
+
+export class YamlockPayloadError extends YamlockError {}
+
+export class YamlockAuthenticationError extends YamlockPayloadError {
+  constructor(message = 'Payload authentication failed.', options = {}) {
+    super(message, {
+      ...options,
+      code: YAMLOCK_ERROR_CODES.AUTHENTICATION_FAILED
+    });
+  }
+}
+
+export class YamlockDecryptionError extends YamlockError {}
+
+export class YamlockConfigError extends YamlockValidationError {}

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import type { Buffer } from 'node:buffer';
+
+export type YamlockKey = string | Buffer;
+export type YamlockPathSegment = string | number;
+export type YamlockFormatVersion = 1 | 2;
+export type YamlockNonStringPolicy = 'ignore' | 'stringify' | 'error';
+export type YamlockExistingPayloadPolicy = 'preserve' | 'error' | 'encrypt';
+export type YamlockConfig = Record<string, unknown> | unknown[];
+
+export interface YamlockCryptoOptions {
+  algorithm?: string;
+  keyLength?: number;
+  ivLength?: number;
+  authTagLength?: number;
+  formatVersion?: YamlockFormatVersion;
+}
+
+export type YamlockCryptoOptionsInput = string | YamlockCryptoOptions;
+
+export interface ProcessConfigCommonOptions {
+  key: YamlockKey;
+  algorithm?: YamlockCryptoOptionsInput;
+  algorithmOptions?: YamlockCryptoOptions;
+  formatVersion?: YamlockFormatVersion;
+  nonStringPolicy?: YamlockNonStringPolicy;
+  pathSerializer?: (segments: YamlockPathSegment[]) => string;
+  paths?: string[];
+  parentPath?: YamlockPathSegment[];
+}
+
+export interface EncryptProcessConfigOptions extends ProcessConfigCommonOptions {
+  mode: 'encrypt';
+  existingPayloadPolicy?: YamlockExistingPayloadPolicy;
+}
+
+export interface DecryptProcessConfigOptions extends ProcessConfigCommonOptions {
+  mode: 'decrypt';
+  existingPayloadPolicy?: never;
+}
+
+export type ProcessConfigOptions =
+  | EncryptProcessConfigOptions
+  | DecryptProcessConfigOptions;
+
+export const YAMLOCK_ERROR_CODES: Readonly<{
+  ALREADY_ENCRYPTED: 'ERR_ALREADY_ENCRYPTED';
+  AUTHENTICATION_FAILED: 'ERR_AUTHENTICATION_FAILED';
+  CIRCULAR_CONFIG: 'ERR_CIRCULAR_CONFIG';
+  DECRYPTION_FAILED: 'ERR_DECRYPTION_FAILED';
+  FIELD_PATH_MISMATCH: 'ERR_FIELD_PATH_MISMATCH';
+  INVALID_CONFIG_OPTIONS: 'ERR_INVALID_CONFIG_OPTIONS';
+  INVALID_CONFIG_ROOT: 'ERR_INVALID_CONFIG_ROOT';
+  INVALID_EXISTING_PAYLOAD_POLICY: 'ERR_INVALID_EXISTING_PAYLOAD_POLICY';
+  INVALID_FIELD_PATH: 'ERR_INVALID_FIELD_PATH';
+  INVALID_KEY: 'ERR_INVALID_KEY';
+  INVALID_MODE: 'ERR_INVALID_MODE';
+  INVALID_NON_STRING_POLICY: 'ERR_INVALID_NON_STRING_POLICY';
+  INVALID_OPTIONS: 'ERR_INVALID_OPTIONS';
+  INVALID_PATH_SEGMENTS: 'ERR_INVALID_PATH_SEGMENTS';
+  INVALID_PATH_SERIALIZER: 'ERR_INVALID_PATH_SERIALIZER';
+  INVALID_PATHS: 'ERR_INVALID_PATHS';
+  INVALID_PAYLOAD: 'ERR_INVALID_PAYLOAD';
+  INVALID_VALUE: 'ERR_INVALID_VALUE';
+  NON_STRING_VALUE: 'ERR_NON_STRING_VALUE';
+  PATH_COLLISION: 'ERR_PATH_COLLISION';
+  PAYLOAD_TOO_LARGE: 'ERR_PAYLOAD_TOO_LARGE';
+  UNSUPPORTED_ALGORITHM: 'ERR_UNSUPPORTED_ALGORITHM';
+  UNSUPPORTED_CONFIG_VALUE: 'ERR_UNSUPPORTED_CONFIG_VALUE';
+  UNSUPPORTED_PAYLOAD: 'ERR_UNSUPPORTED_PAYLOAD';
+  UNSUPPORTED_PAYLOAD_VERSION: 'ERR_UNSUPPORTED_PAYLOAD_VERSION';
+  VALUE_TOO_LARGE: 'ERR_VALUE_TOO_LARGE';
+}>;
+
+export type YamlockErrorCode =
+  (typeof YAMLOCK_ERROR_CODES)[keyof typeof YAMLOCK_ERROR_CODES];
+
+export interface YamlockErrorOptions {
+  code: YamlockErrorCode | `ERR_${string}`;
+  cause?: unknown;
+}
+
+export class YamlockError extends Error {
+  constructor(message: string, options: YamlockErrorOptions);
+  code: YamlockErrorCode | `ERR_${string}`;
+}
+
+export class YamlockValidationError extends YamlockError {}
+export class YamlockPayloadError extends YamlockError {}
+
+export class YamlockAuthenticationError extends YamlockPayloadError {
+  constructor(message?: string, options?: { cause?: unknown });
+  code: 'ERR_AUTHENTICATION_FAILED';
+}
+
+export class YamlockDecryptionError extends YamlockError {}
+export class YamlockConfigError extends YamlockValidationError {}
+
+export function encryptValue(
+  value: string,
+  key: YamlockKey,
+  fieldPath: string,
+  algorithmOptions?: YamlockCryptoOptionsInput
+): string;
+
+export function decryptValue(
+  encryptedValue: string,
+  key: YamlockKey,
+  fieldPath: string,
+  algorithmOptions?: YamlockCryptoOptionsInput
+): string;
+
+export function processConfig<T extends YamlockConfig>(
+  node: T,
+  options: ProcessConfigOptions & { nonStringPolicy: 'stringify' }
+): YamlockConfig;
+
+export function processConfig<T extends YamlockConfig>(
+  node: T,
+  options: ProcessConfigOptions
+): T;
+
+export function serializePath(segments: YamlockPathSegment[]): string;
+export function getSupportedAlgorithms(): string[];

package/dist/index.js

@@ -1,4 +1,14 @@
 export { encryptValue } from './crypto/encrypt.js';
 export { decryptValue } from './crypto/decrypt.js';
 export { processConfig } from './utils/config.js';
+export { serializePath } from './utils/path.js';
 export { listSupportedAlgorithms as getSupportedAlgorithms } from './crypto/utils.js';
+export {
+  YAMLOCK_ERROR_CODES,
+  YamlockAuthenticationError,
+  YamlockConfigError,
+  YamlockDecryptionError,
+  YamlockError,
+  YamlockPayloadError,
+  YamlockValidationError
+} from './errors.js';