@wemush/wols 1.2.0 → 1.3.0

package/dist/cjs/crypto/index.js

@@ -2,15 +2,28 @@
 /**
  * WOLS Crypto Module
  *
- * Provides AES-256-GCM encryption and decryption for specimens.
+ * AES-256-GCM encryption and decryption for specimens in the WOLS v1.3.0
+ * encrypted format (`wemush://v1/encrypted/{id}?e=&iv=&kdf=...`).
  *
  * @module crypto
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.decryptSpecimen = exports.isEncrypted = exports.encryptSpecimen = void 0;
+exports.derivePassphraseKey = exports.base64UrlDecode = exports.base64UrlEncode = exports.parseEncryptedUrl = exports.decryptFields = exports.decryptField = exports.decryptPlaintext = exports.decryptSpecimen = exports.toEncryptedUrl = exports.isEncryptedField = exports.isEncryptedSpecimen = exports.isEncrypted = exports.encryptFields = exports.encryptSpecimen = void 0;
 var encrypt_js_1 = require("./encrypt.js");
 Object.defineProperty(exports, "encryptSpecimen", { enumerable: true, get: function () { return encrypt_js_1.encryptSpecimen; } });
+Object.defineProperty(exports, "encryptFields", { enumerable: true, get: function () { return encrypt_js_1.encryptFields; } });
 Object.defineProperty(exports, "isEncrypted", { enumerable: true, get: function () { return encrypt_js_1.isEncrypted; } });
+Object.defineProperty(exports, "isEncryptedSpecimen", { enumerable: true, get: function () { return encrypt_js_1.isEncryptedSpecimen; } });
+Object.defineProperty(exports, "isEncryptedField", { enumerable: true, get: function () { return encrypt_js_1.isEncryptedField; } });
+Object.defineProperty(exports, "toEncryptedUrl", { enumerable: true, get: function () { return encrypt_js_1.toEncryptedUrl; } });
 var decrypt_js_1 = require("./decrypt.js");
 Object.defineProperty(exports, "decryptSpecimen", { enumerable: true, get: function () { return decrypt_js_1.decryptSpecimen; } });
+Object.defineProperty(exports, "decryptPlaintext", { enumerable: true, get: function () { return decrypt_js_1.decryptPlaintext; } });
+Object.defineProperty(exports, "decryptField", { enumerable: true, get: function () { return decrypt_js_1.decryptField; } });
+Object.defineProperty(exports, "decryptFields", { enumerable: true, get: function () { return decrypt_js_1.decryptFields; } });
+Object.defineProperty(exports, "parseEncryptedUrl", { enumerable: true, get: function () { return decrypt_js_1.parseEncryptedUrl; } });
+var shared_js_1 = require("./shared.js");
+Object.defineProperty(exports, "base64UrlEncode", { enumerable: true, get: function () { return shared_js_1.base64UrlEncode; } });
+Object.defineProperty(exports, "base64UrlDecode", { enumerable: true, get: function () { return shared_js_1.base64UrlDecode; } });
+Object.defineProperty(exports, "derivePassphraseKey", { enumerable: true, get: function () { return shared_js_1.derivePassphraseKey; } });
 //# sourceMappingURL=index.js.map

package/dist/cjs/crypto/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/crypto/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH,2CAA4D;AAAnD,6GAAA,eAAe,OAAA;AAAE,yGAAA,WAAW,OAAA;AACrC,2CAA+C;AAAtC,6GAAA,eAAe,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/crypto/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,2CAOsB;AANpB,6GAAA,eAAe,OAAA;AACf,2GAAA,aAAa,OAAA;AACb,yGAAA,WAAW,OAAA;AACX,iHAAA,mBAAmB,OAAA;AACnB,8GAAA,gBAAgB,OAAA;AAChB,4GAAA,cAAc,OAAA;AAEhB,2CAOsB;AANpB,6GAAA,eAAe,OAAA;AACf,8GAAA,gBAAgB,OAAA;AAChB,0GAAA,YAAY,OAAA;AACZ,2GAAA,aAAa,OAAA;AACb,+GAAA,iBAAiB,OAAA;AAGnB,yCAAoF;AAA3E,4GAAA,eAAe,OAAA;AAAE,4GAAA,eAAe,OAAA;AAAE,gHAAA,mBAAmB,OAAA"}

package/dist/cjs/crypto/shared.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared primitives for the WOLS encrypted format (v1.3.0).
+ *
+ * Uses only WebCrypto (`globalThis.crypto.subtle`), so it runs unchanged in
+ * Node.js 20+, browsers, Deno, Bun and workers.
+ *
+ * `base64UrlEncode`, `base64UrlDecode` and `derivePassphraseKey` are public
+ * (re-exported from the package root and `@wemush/wols/crypto`); everything
+ * else here is internal to the crypto module.
+ *
+ * @module crypto/shared
+ */
+import { WolsDecryptionError } from '../errors.js';
+import type { DecryptionFailureReason, RawEncryptionKey } from '../types.js';
+/** Default PBKDF2 iteration count used when generating. */
+export declare const DEFAULT_PBKDF2_ITERATIONS = 600000;
+/** Iteration count pre-1.3.0 payloads used when they recorded none. */
+export declare const LEGACY_PBKDF2_ITERATIONS = 100000;
+/** Generators MUST use at least this many PBKDF2 iterations (WOLS v1.3.0). */
+export declare const MIN_GENERATE_ITERATIONS = 100000;
+/** Decoders MUST reject fewer PBKDF2 iterations than this (WOLS v1.3.0). */
+export declare const MIN_DECODE_ITERATIONS = 10000;
+/** Default largest PBKDF2 iteration count accepted from a label when decoding. */
+export declare const DEFAULT_MAX_DECODE_ITERATIONS = 10000000;
+/**
+ * WOLS 1.3.0 ceiling: decoders reject more than this many iterations (alone,
+ * or in total across a field-encrypted label), and generators never exceed it.
+ * A configured `maxIterations` may be lower, never higher.
+ */
+export declare const MAX_ITERATIONS = 10000000;
+/** WebCrypto's PBKDF2 `iterations` is an unsigned long; nothing above this is derivable. */
+export declare const MAX_PBKDF2_ITERATIONS = 4294967295;
+/** Per-label PBKDF2 salt length generated (spec minimum: 16 bytes). */
+export declare const SALT_LENGTH = 16;
+/** AES-GCM appends a 16-byte authentication tag, so no valid ciphertext is shorter. */
+export declare const GCM_TAG_LENGTH = 16;
+/** AES-GCM IV length in bytes. */
+export declare const IV_LENGTH = 12;
+/** Raw AES-256 key length in bytes. */
+export declare const RAW_KEY_LENGTH = 32;
+/** Prefix of every encrypted-format URL. */
+export declare const ENCRYPTED_URL_PREFIX = "wemush://v1/encrypted/";
+/**
+ * Library-wide salt used by pre-1.3.0 releases. Only for decoding legacy
+ * payloads behind `allowLegacy`; never used when generating.
+ */
+export declare const LEGACY_PBKDF2_SALT: Uint8Array<ArrayBuffer>;
+/**
+ * Create a decryption error carrying a stable `details.reason` category.
+ */
+export declare function decryptionError(reason: DecryptionFailureReason, message: string, details?: Record<string, unknown>): WolsDecryptionError;
+/**
+ * Whether WebCrypto (`globalThis.crypto.subtle`) is available. It is global in
+ * browsers, workers, Deno, Bun and Node.js 19+ (Node 18 needs
+ * `--experimental-global-webcrypto`).
+ */
+export declare function hasWebCrypto(): boolean;
+/** Message used when WebCrypto is missing. */
+export declare const NO_WEBCRYPTO_MESSAGE: string;
+/** Throw a WolsEncryptionError when WebCrypto is missing (encryption paths). */
+export declare function assertWebCrypto(): void;
+/**
+ * Encode bytes as base64url (RFC 4648 §5) without padding.
+ *
+ * @since 1.3.0
+ */
+export declare function base64UrlEncode(bytes: Uint8Array | ArrayBuffer): string;
+/**
+ * Decode base64url (RFC 4648 §5). Padded input is accepted.
+ *
+ * @throws Error if the input is not valid base64url
+ * @since 1.3.0
+ */
+export declare function base64UrlDecode(value: string): Uint8Array<ArrayBuffer>;
+/** Cryptographically random bytes from WebCrypto. */
+export declare function randomBytes(length: number): Uint8Array<ArrayBuffer>;
+/**
+ * Derive a 256-bit key from a passphrase with PBKDF2-HMAC-SHA256.
+ *
+ * Exposed for debugging and interoperability testing (it reproduces the
+ * conformance `derive` vectors). Returns the raw key bytes.
+ *
+ * @param passphrase - Passphrase; normalized to Unicode NFC, then UTF-8 encoded (WOLS 1.3.0)
+ * @param salt - Salt bytes (the label's decoded `salt` parameter)
+ * @param iterations - PBKDF2 iteration count (positive integer)
+ * @since 1.3.0
+ */
+export declare function derivePassphraseKey(passphrase: string, salt: Uint8Array | ArrayBuffer, iterations: number): Promise<Uint8Array<ArrayBuffer>>;
+/**
+ * Field-level AES-GCM additional data (WOLS 1.3.0): UTF-8 of the label's full
+ * `id`, a line feed, and the top-level field name, e.g. "wemush:clx1a2b3c4\nstrain".
+ * Binds each encrypted value to its label and field.
+ */
+export declare function fieldAad(id: string, field: string): Uint8Array<ArrayBuffer>;
+/**
+ * Fields that identify or type a label. They are never encrypted, and a label
+ * in which any of them is an encrypted object is refused (WOLS 1.3.0).
+ */
+export declare const IDENTIFYING_FIELDS: readonly string[];
+/** Import 32 raw key bytes as an AES-GCM key. */
+export declare function importAesKey(bytes: Uint8Array | ArrayBuffer, usage: 'encrypt' | 'decrypt'): Promise<CryptoKey>;
+/**
+ * Check whether a value is a WebCrypto CryptoKey without relying on the
+ * global `CryptoKey` constructor (absent in some runtimes).
+ */
+export declare function isCryptoKey(value: unknown): value is CryptoKey;
+/**
+ * Resolve a raw key (bytes or CryptoKey) to an AES-256-GCM CryptoKey.
+ * Returns an error message string when the key is unusable.
+ */
+export declare function resolveRawKey(key: RawEncryptionKey, usage: 'encrypt' | 'decrypt'): Promise<CryptoKey | string>;
+/** Whether a key value is a passphrase (selects kdf=pbkdf2). */
+export declare function isPassphrase(key: unknown): key is string;
+/** Whether a key value is raw key material (selects kdf=raw). */
+export declare function isRawKey(key: unknown): key is RawEncryptionKey;
+//# sourceMappingURL=shared.d.ts.map

package/dist/cjs/crypto/shared.d.ts.map

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

package/dist/cjs/crypto/shared.js

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * Shared primitives for the WOLS encrypted format (v1.3.0).
+ *
+ * Uses only WebCrypto (`globalThis.crypto.subtle`), so it runs unchanged in
+ * Node.js 20+, browsers, Deno, Bun and workers.
+ *
+ * `base64UrlEncode`, `base64UrlDecode` and `derivePassphraseKey` are public
+ * (re-exported from the package root and `@wemush/wols/crypto`); everything
+ * else here is internal to the crypto module.
+ *
+ * @module crypto/shared
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDENTIFYING_FIELDS = exports.NO_WEBCRYPTO_MESSAGE = exports.LEGACY_PBKDF2_SALT = exports.ENCRYPTED_URL_PREFIX = exports.RAW_KEY_LENGTH = exports.IV_LENGTH = exports.GCM_TAG_LENGTH = exports.SALT_LENGTH = exports.MAX_PBKDF2_ITERATIONS = exports.MAX_ITERATIONS = exports.DEFAULT_MAX_DECODE_ITERATIONS = exports.MIN_DECODE_ITERATIONS = exports.MIN_GENERATE_ITERATIONS = exports.LEGACY_PBKDF2_ITERATIONS = exports.DEFAULT_PBKDF2_ITERATIONS = void 0;
+exports.decryptionError = decryptionError;
+exports.hasWebCrypto = hasWebCrypto;
+exports.assertWebCrypto = assertWebCrypto;
+exports.base64UrlEncode = base64UrlEncode;
+exports.base64UrlDecode = base64UrlDecode;
+exports.randomBytes = randomBytes;
+exports.derivePassphraseKey = derivePassphraseKey;
+exports.fieldAad = fieldAad;
+exports.importAesKey = importAesKey;
+exports.isCryptoKey = isCryptoKey;
+exports.resolveRawKey = resolveRawKey;
+exports.isPassphrase = isPassphrase;
+exports.isRawKey = isRawKey;
+const errors_js_1 = require("../errors.js");
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+/** Default PBKDF2 iteration count used when generating. */
+exports.DEFAULT_PBKDF2_ITERATIONS = 600_000;
+/** Iteration count pre-1.3.0 payloads used when they recorded none. */
+exports.LEGACY_PBKDF2_ITERATIONS = 100_000;
+/** Generators MUST use at least this many PBKDF2 iterations (WOLS v1.3.0). */
+exports.MIN_GENERATE_ITERATIONS = 100_000;
+/** Decoders MUST reject fewer PBKDF2 iterations than this (WOLS v1.3.0). */
+exports.MIN_DECODE_ITERATIONS = 10_000;
+/** Default largest PBKDF2 iteration count accepted from a label when decoding. */
+exports.DEFAULT_MAX_DECODE_ITERATIONS = 10_000_000;
+/**
+ * WOLS 1.3.0 ceiling: decoders reject more than this many iterations (alone,
+ * or in total across a field-encrypted label), and generators never exceed it.
+ * A configured `maxIterations` may be lower, never higher.
+ */
+exports.MAX_ITERATIONS = 10_000_000;
+/** WebCrypto's PBKDF2 `iterations` is an unsigned long; nothing above this is derivable. */
+exports.MAX_PBKDF2_ITERATIONS = 0xffff_ffff;
+/** Per-label PBKDF2 salt length generated (spec minimum: 16 bytes). */
+exports.SALT_LENGTH = 16;
+/** AES-GCM appends a 16-byte authentication tag, so no valid ciphertext is shorter. */
+exports.GCM_TAG_LENGTH = 16;
+/** AES-GCM IV length in bytes. */
+exports.IV_LENGTH = 12;
+/** Raw AES-256 key length in bytes. */
+exports.RAW_KEY_LENGTH = 32;
+/** Prefix of every encrypted-format URL. */
+exports.ENCRYPTED_URL_PREFIX = 'wemush://v1/encrypted/';
+/**
+ * Library-wide salt used by pre-1.3.0 releases. Only for decoding legacy
+ * payloads behind `allowLegacy`; never used when generating.
+ */
+exports.LEGACY_PBKDF2_SALT = new TextEncoder().encode('@wemush/wols/crypto/v1');
+// =============================================================================
+// ERRORS
+// =============================================================================
+/**
+ * Create a decryption error carrying a stable `details.reason` category.
+ */
+function decryptionError(reason, message, details = {}) {
+    return new errors_js_1.WolsDecryptionError(reason, message, details);
+}
+/**
+ * Whether WebCrypto (`globalThis.crypto.subtle`) is available. It is global in
+ * browsers, workers, Deno, Bun and Node.js 19+ (Node 18 needs
+ * `--experimental-global-webcrypto`).
+ */
+function hasWebCrypto() {
+    const c = globalThis.crypto;
+    return (typeof c?.subtle === 'object' && c.subtle !== null && typeof c.getRandomValues === 'function');
+}
+/** Message used when WebCrypto is missing. */
+exports.NO_WEBCRYPTO_MESSAGE = 'WebCrypto (globalThis.crypto.subtle) is not available in this runtime. ' +
+    'Use Node.js 20+, a modern browser, Deno or Bun.';
+/** Throw a WolsEncryptionError when WebCrypto is missing (encryption paths). */
+function assertWebCrypto() {
+    if (!hasWebCrypto()) {
+        throw new errors_js_1.WolsEncryptionError(errors_js_1.WolsErrorCode.ENCRYPTION_ERROR, exports.NO_WEBCRYPTO_MESSAGE);
+    }
+}
+// =============================================================================
+// BASE64URL
+// =============================================================================
+/**
+ * Encode bytes as base64url (RFC 4648 §5) without padding.
+ *
+ * @since 1.3.0
+ */
+function base64UrlEncode(bytes) {
+    const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    let binary = '';
+    for (const byte of view) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]*={0,2}$/;
+/**
+ * Decode base64url (RFC 4648 §5). Padded input is accepted.
+ *
+ * @throws Error if the input is not valid base64url
+ * @since 1.3.0
+ */
+function base64UrlDecode(value) {
+    if (!BASE64URL_PATTERN.test(value)) {
+        throw new Error('Invalid base64url string');
+    }
+    const unpadded = value.replace(/=+$/, '');
+    if (unpadded.length % 4 === 1) {
+        throw new Error('Invalid base64url length');
+    }
+    const base64 = unpadded.replace(/-/g, '+').replace(/_/g, '/');
+    const binary = atob(base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '='));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+// =============================================================================
+// RANDOMNESS
+// =============================================================================
+/** Cryptographically random bytes from WebCrypto. */
+function randomBytes(length) {
+    const bytes = new Uint8Array(length);
+    crypto.getRandomValues(bytes);
+    return bytes;
+}
+// =============================================================================
+// KEYS
+// =============================================================================
+/** Copy a byte view into a fresh ArrayBuffer-backed Uint8Array (WebCrypto-safe). */
+function toOwnedBytes(bytes) {
+    const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    const copy = new Uint8Array(view.length);
+    copy.set(view);
+    return copy;
+}
+/**
+ * Derive a 256-bit key from a passphrase with PBKDF2-HMAC-SHA256.
+ *
+ * Exposed for debugging and interoperability testing (it reproduces the
+ * conformance `derive` vectors). Returns the raw key bytes.
+ *
+ * @param passphrase - Passphrase; normalized to Unicode NFC, then UTF-8 encoded (WOLS 1.3.0)
+ * @param salt - Salt bytes (the label's decoded `salt` parameter)
+ * @param iterations - PBKDF2 iteration count (positive integer)
+ * @since 1.3.0
+ */
+async function derivePassphraseKey(passphrase, salt, iterations) {
+    if (!Number.isInteger(iterations) || iterations < 1 || iterations > exports.MAX_PBKDF2_ITERATIONS) {
+        throw new Error(`PBKDF2 iterations must be an integer from 1 to ${exports.MAX_PBKDF2_ITERATIONS}, got ${iterations}`);
+    }
+    const material = await crypto.subtle.importKey('raw', 
+    // WOLS 1.3.0: NFC so composed and decomposed input derive the same key.
+    new TextEncoder().encode(passphrase.normalize('NFC')), 'PBKDF2', false, ['deriveBits']);
+    const bits = await crypto.subtle.deriveBits({ name: 'PBKDF2', hash: 'SHA-256', salt: toOwnedBytes(salt), iterations }, material, 256);
+    return new Uint8Array(bits);
+}
+/**
+ * Field-level AES-GCM additional data (WOLS 1.3.0): UTF-8 of the label's full
+ * `id`, a line feed, and the top-level field name, e.g. "wemush:clx1a2b3c4\nstrain".
+ * Binds each encrypted value to its label and field.
+ */
+function fieldAad(id, field) {
+    return new TextEncoder().encode(`${id}\n${field}`);
+}
+/**
+ * Fields that identify or type a label. They are never encrypted, and a label
+ * in which any of them is an encrypted object is refused (WOLS 1.3.0).
+ */
+exports.IDENTIFYING_FIELDS = [
+    '@context',
+    '@type',
+    'id',
+    'version',
+    'type',
+    'species',
+];
+/** Import 32 raw key bytes as an AES-GCM key. */
+async function importAesKey(bytes, usage) {
+    return crypto.subtle.importKey('raw', toOwnedBytes(bytes), { name: 'AES-GCM' }, false, [usage]);
+}
+/**
+ * Check whether a value is a WebCrypto CryptoKey without relying on the
+ * global `CryptoKey` constructor (absent in some runtimes).
+ */
+function isCryptoKey(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'algorithm' in value &&
+        'usages' in value &&
+        'type' in value &&
+        !(value instanceof Uint8Array) &&
+        !(value instanceof ArrayBuffer));
+}
+/**
+ * Resolve a raw key (bytes or CryptoKey) to an AES-256-GCM CryptoKey.
+ * Returns an error message string when the key is unusable.
+ */
+async function resolveRawKey(key, usage) {
+    if (isCryptoKey(key)) {
+        const algorithm = key.algorithm;
+        if (algorithm.name !== 'AES-GCM' || algorithm.length !== 256) {
+            return `CryptoKey must be AES-GCM with length 256, got ${algorithm.name ?? 'unknown'}/${algorithm.length ?? '?'}`;
+        }
+        if (!key.usages.includes(usage)) {
+            return `CryptoKey does not allow '${usage}'`;
+        }
+        return key;
+    }
+    const length = key instanceof Uint8Array ? key.length : key.byteLength;
+    if (length !== exports.RAW_KEY_LENGTH) {
+        return `Raw key must be exactly ${exports.RAW_KEY_LENGTH} bytes, got ${length}`;
+    }
+    return importAesKey(key, usage);
+}
+/** Whether a key value is a passphrase (selects kdf=pbkdf2). */
+function isPassphrase(key) {
+    return typeof key === 'string';
+}
+/** Whether a key value is raw key material (selects kdf=raw). */
+function isRawKey(key) {
+    return key instanceof Uint8Array || key instanceof ArrayBuffer || isCryptoKey(key);
+}
+//# sourceMappingURL=shared.js.map

package/dist/cjs/crypto/shared.js.map

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

package/dist/cjs/errors.d.ts

@@ -0,0 +1,133 @@
+/**
+ * WOLS Error Types
+ *
+ * This module defines all error classes and error codes
+ * used by the WOLS TypeScript library.
+ *
+ * @module errors
+ */
+import type { DecryptionFailureReason, ValidationError } from './types.js';
+/**
+ * WOLS error codes (stable, for programmatic handling).
+ */
+export declare enum WolsErrorCode {
+    /** General parse error */
+    PARSE_ERROR = "WOLS_PARSE_ERROR",
+    /** Invalid JSON syntax */
+    INVALID_JSON = "WOLS_INVALID_JSON",
+    /** Not a valid WOLS format */
+    INVALID_FORMAT = "WOLS_INVALID_FORMAT",
+    /** Missing or invalid @context field */
+    INVALID_CONTEXT = "WOLS_INVALID_CONTEXT",
+    /** Missing or invalid @type field */
+    INVALID_TYPE = "WOLS_INVALID_TYPE",
+    /** ID doesn't match wemush:[a-z0-9]+ pattern */
+    INVALID_ID_FORMAT = "WOLS_INVALID_ID_FORMAT",
+    /** Version not valid semver */
+    INVALID_VERSION = "WOLS_INVALID_VERSION",
+    /** Type not in SpecimenType enum */
+    INVALID_SPECIMEN_TYPE = "WOLS_INVALID_SPECIMEN_TYPE",
+    /** Required field is missing */
+    REQUIRED_FIELD = "WOLS_REQUIRED_FIELD",
+    /** Date not in ISO 8601 format */
+    INVALID_DATE_FORMAT = "WOLS_INVALID_DATE_FORMAT",
+    /** Strain generation format is invalid */
+    INVALID_GENERATION = "WOLS_INVALID_GENERATION",
+    /** Invalid compact URL format */
+    INVALID_URL = "WOLS_INVALID_URL",
+    /** Encryption operation failed */
+    ENCRYPTION_ERROR = "WOLS_ENCRYPTION_ERROR",
+    /** Decryption operation failed */
+    DECRYPTION_ERROR = "WOLS_DECRYPTION_ERROR",
+    /** Invalid encryption key */
+    INVALID_KEY = "WOLS_INVALID_KEY",
+    /** Payload exceeds QR code capacity */
+    SIZE_EXCEEDED = "WOLS_SIZE_EXCEEDED",
+    /** Unknown or unspecified error */
+    UNKNOWN_ERROR = "WOLS_UNKNOWN_ERROR"
+}
+/**
+ * Base WOLS error class.
+ * All WOLS-specific errors extend this class.
+ */
+export declare class WolsError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: WolsErrorCode;
+    /** Additional error details */
+    readonly details: Record<string, unknown> | undefined;
+    constructor(code: WolsErrorCode, message: string, details?: Record<string, unknown>);
+    /**
+     * Convert error to JSON for serialization.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Parse error (JSON/format issues).
+ * Thrown when parsing JSON or WOLS data fails.
+ */
+export declare class WolsParseError extends WolsError {
+    /** Character position in the input where error occurred */
+    readonly position: number | undefined;
+    constructor(code: WolsErrorCode, message: string, details?: Record<string, unknown> & {
+        position?: number;
+    });
+}
+/**
+ * Validation error (schema violations).
+ * Thrown when specimen data fails validation.
+ */
+export declare class WolsValidationError extends WolsError {
+    /** Array of validation errors */
+    readonly errors: ValidationError[];
+    constructor(message: string, errors: ValidationError[]);
+}
+/**
+ * Encryption/decryption error.
+ * Thrown when crypto operations fail.
+ */
+export declare class WolsEncryptionError extends WolsError {
+    constructor(code: WolsErrorCode, message: string, details?: Record<string, unknown>);
+}
+/**
+ * Decryption failure with a stable, typed {@link DecryptionFailureReason}.
+ *
+ * It extends `WolsEncryptionError` on purpose: 1.2.x returned a
+ * `WolsEncryptionError` for decryption failures, so existing
+ * `instanceof WolsEncryptionError` checks keep matching. Encryption misuse is
+ * thrown as a plain `WolsEncryptionError`; decryption failures are returned as
+ * this subclass, so check `instanceof WolsDecryptionError` to tell them apart.
+ * Malformed encrypted URLs are reported here too (`invalid-url`), not as
+ * `WolsParseError`, so every decryption input problem has one error type.
+ *
+ * Returned (never thrown) by `decryptSpecimen`, `decryptPlaintext`,
+ * `decryptField` and `decryptFields`. `reason` is also copied into
+ * `details.reason` for code that reads the generic error shape.
+ *
+ * @example
+ * ```typescript
+ * const r = await decryptSpecimen(url, { key });
+ * if (!r.success && r.error.reason === 'legacy-format') {
+ *   // a pre-1.3.0 label: retry with { allowLegacy: true } during migration
+ * }
+ * ```
+ *
+ * @since 1.3.0
+ */
+export declare class WolsDecryptionError extends WolsEncryptionError {
+    /** Stable failure category */
+    readonly reason: DecryptionFailureReason;
+    constructor(reason: DecryptionFailureReason, message: string, details?: Record<string, unknown>);
+}
+/**
+ * Create a required field error.
+ */
+export declare function requiredFieldError(field: string, path?: string): WolsValidationError;
+/**
+ * Create an invalid format error.
+ */
+export declare function invalidFormatError(field: string, expected: string, path?: string): WolsValidationError;
+/**
+ * Create a parse error from a caught exception.
+ */
+export declare function parseErrorFromException(error: unknown, _input?: string): WolsParseError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAM3E;;GAEG;AACH,oBAAY,aAAa;IACvB,0BAA0B;IAC1B,WAAW,qBAAqB;IAChC,0BAA0B;IAC1B,YAAY,sBAAsB;IAClC,8BAA8B;IAC9B,cAAc,wBAAwB;IACtC,wCAAwC;IACxC,eAAe,yBAAyB;IACxC,qCAAqC;IACrC,YAAY,sBAAsB;IAClC,gDAAgD;IAChD,iBAAiB,2BAA2B;IAC5C,+BAA+B;IAC/B,eAAe,yBAAyB;IACxC,oCAAoC;IACpC,qBAAqB,+BAA+B;IACpD,gCAAgC;IAChC,cAAc,wBAAwB;IACtC,kCAAkC;IAClC,mBAAmB,6BAA6B;IAChD,0CAA0C;IAC1C,kBAAkB,4BAA4B;IAC9C,iCAAiC;IACjC,WAAW,qBAAqB;IAChC,kCAAkC;IAClC,gBAAgB,0BAA0B;IAC1C,kCAAkC;IAClC,gBAAgB,0BAA0B;IAC1C,6BAA6B;IAC7B,WAAW,qBAAqB;IAChC,uCAAuC;IACvC,aAAa,uBAAuB;IACpC,mCAAmC;IACnC,aAAa,uBAAuB;CACrC;AAMD;;;GAGG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;gBAE1C,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAYnF;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQlC;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,SAAS;IAC3C,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;gBAGpC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;CAU5D;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IAChD,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC;gBAEvB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE;CASvD;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQpF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,mBAAoB,SAAQ,mBAAmB;IAC1D,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;gBAE7B,MAAM,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAahG;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAc,GAAG,mBAAmB,CAQ3F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,MAAc,GACnB,mBAAmB,CAQrB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc,CAoBvF"}

package/dist/cjs/errors.js

@@ -8,7 +8,7 @@
  * @module errors
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WolsEncryptionError = exports.WolsValidationError = exports.WolsParseError = exports.WolsError = exports.WolsErrorCode = void 0;
+exports.WolsDecryptionError = exports.WolsEncryptionError = exports.WolsValidationError = exports.WolsParseError = exports.WolsError = exports.WolsErrorCode = void 0;
 exports.requiredFieldError = requiredFieldError;
 exports.invalidFormatError = invalidFormatError;
 exports.parseErrorFromException = parseErrorFromException;
@@ -138,6 +138,44 @@ class WolsEncryptionError extends WolsError {
     }
 }
 exports.WolsEncryptionError = WolsEncryptionError;
+/**
+ * Decryption failure with a stable, typed {@link DecryptionFailureReason}.
+ *
+ * It extends `WolsEncryptionError` on purpose: 1.2.x returned a
+ * `WolsEncryptionError` for decryption failures, so existing
+ * `instanceof WolsEncryptionError` checks keep matching. Encryption misuse is
+ * thrown as a plain `WolsEncryptionError`; decryption failures are returned as
+ * this subclass, so check `instanceof WolsDecryptionError` to tell them apart.
+ * Malformed encrypted URLs are reported here too (`invalid-url`), not as
+ * `WolsParseError`, so every decryption input problem has one error type.
+ *
+ * Returned (never thrown) by `decryptSpecimen`, `decryptPlaintext`,
+ * `decryptField` and `decryptFields`. `reason` is also copied into
+ * `details.reason` for code that reads the generic error shape.
+ *
+ * @example
+ * ```typescript
+ * const r = await decryptSpecimen(url, { key });
+ * if (!r.success && r.error.reason === 'legacy-format') {
+ *   // a pre-1.3.0 label: retry with { allowLegacy: true } during migration
+ * }
+ * ```
+ *
+ * @since 1.3.0
+ */
+class WolsDecryptionError extends WolsEncryptionError {
+    /** Stable failure category */
+    reason;
+    constructor(reason, message, details) {
+        super(reason === 'invalid-key' ? WolsErrorCode.INVALID_KEY : WolsErrorCode.DECRYPTION_ERROR, message, { ...details, reason });
+        this.name = 'WolsDecryptionError';
+        this.reason = reason;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, WolsDecryptionError);
+        }
+    }
+}
+exports.WolsDecryptionError = WolsDecryptionError;
 // =============================================================================
 // ERROR FACTORY FUNCTIONS
 // =============================================================================

package/dist/cjs/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAmMH,gDAQC;AAKD,gDAYC;AAKD,0DAoBC;AAjPD,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF;;GAEG;AACH,IAAY,aAmCX;AAnCD,WAAY,aAAa;IACvB,0BAA0B;IAC1B,iDAAgC,CAAA;IAChC,0BAA0B;IAC1B,mDAAkC,CAAA;IAClC,8BAA8B;IAC9B,uDAAsC,CAAA;IACtC,wCAAwC;IACxC,yDAAwC,CAAA;IACxC,qCAAqC;IACrC,mDAAkC,CAAA;IAClC,gDAAgD;IAChD,6DAA4C,CAAA;IAC5C,+BAA+B;IAC/B,yDAAwC,CAAA;IACxC,oCAAoC;IACpC,qEAAoD,CAAA;IACpD,gCAAgC;IAChC,uDAAsC,CAAA;IACtC,kCAAkC;IAClC,iEAAgD,CAAA;IAChD,0CAA0C;IAC1C,+DAA8C,CAAA;IAC9C,iCAAiC;IACjC,iDAAgC,CAAA;IAChC,kCAAkC;IAClC,2DAA0C,CAAA;IAC1C,kCAAkC;IAClC,2DAA0C,CAAA;IAC1C,6BAA6B;IAC7B,iDAAgC,CAAA;IAChC,uCAAuC;IACvC,qDAAoC,CAAA;IACpC,mCAAmC;IACnC,qDAAoC,CAAA;AACtC,CAAC,EAnCW,aAAa,6BAAb,aAAa,QAmCxB;AAED,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;AAEhF;;;GAGG;AACH,MAAa,SAAU,SAAQ,KAAK;IAClC,2CAA2C;IAClC,IAAI,CAAgB;IAC7B,+BAA+B;IACtB,OAAO,CAAsC;IAEtD,YAAY,IAAmB,EAAE,OAAe,EAAE,OAAiC;QACjF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,IAAI,SAAS,CAAC;QAEpC,uEAAuE;QACvE,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC;IACJ,CAAC;CACF;AA7BD,8BA6BC;AAED;;;GAGG;AACH,MAAa,cAAe,SAAQ,SAAS;IAC3C,2DAA2D;IAClD,QAAQ,CAAqB;IAEtC,YACE,IAAmB,EACnB,OAAe,EACf,OAAyD;QAEzD,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,SAAS,CAAC;QAE/C,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;CACF;AAjBD,wCAiBC;AAED;;;GAGG;AACH,MAAa,mBAAoB,SAAQ,SAAS;IAChD,iCAAiC;IACxB,MAAM,CAAoB;IAEnC,YAAY,OAAe,EAAE,MAAyB;QACpD,KAAK,CAAC,aAAa,CAAC,cAAc,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;CACF;AAbD,kDAaC;AAED;;;GAGG;AACH,MAAa,mBAAoB,SAAQ,SAAS;IAChD,YAAY,IAAmB,EAAE,OAAe,EAAE,OAAiC;QACjF,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAElC,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;CACF;AATD,kDASC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAa,mBAAoB,SAAQ,mBAAmB;IAC1D,8BAA8B;IACrB,MAAM,CAA0B;IAEzC,YAAY,MAA+B,EAAE,OAAe,EAAE,OAAiC;QAC7F,KAAK,CACH,MAAM,KAAK,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,gBAAgB,EACrF,OAAO,EACP,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,CACvB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;CACF;AAjBD,kDAiBC;AAED,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF;;GAEG;AACH,SAAgB,kBAAkB,CAAC,KAAa,EAAE,OAAe,KAAK;IACpE,OAAO,IAAI,mBAAmB,CAAC,mBAAmB,KAAK,cAAc,EAAE;QACrE;YACE,IAAI;YACJ,IAAI,EAAE,aAAa,CAAC,cAAc;YAClC,OAAO,EAAE,UAAU,KAAK,eAAe;SACxC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAgB,kBAAkB,CAChC,KAAa,EACb,QAAgB,EAChB,OAAe,KAAK;IAEpB,OAAO,IAAI,mBAAmB,CAAC,uBAAuB,KAAK,eAAe,QAAQ,EAAE,EAAE;QACpF;YACE,IAAI;YACJ,IAAI,EAAE,aAAa,CAAC,cAAc;YAClC,OAAO,EAAE,YAAY,QAAQ,EAAE;SAChC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAgB,uBAAuB,CAAC,KAAc,EAAE,MAAe;IACrE,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,iDAAiD;QACjD,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAEjE,MAAM,OAAO,GAA4B,EAAE,aAAa,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QAC1E,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC;QACjC,CAAC;QAED,OAAO,IAAI,cAAc,CAAC,aAAa,CAAC,YAAY,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC;IAED,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,IAAI,cAAc,CAAC,aAAa,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC"}