@wemush/wols 0.1.0 → 1.3.0

package/dist/types/crypto/decrypt.d.ts

@@ -1,33 +1,110 @@
 /**
- * WOLS Decryption Module
+ * WOLS Decryption Module (WOLS v1.3.0 encrypted format)
  *
- * Provides AES-256-GCM decryption for encrypted specimens using Web Crypto API.
- * Supports both password-based (PBKDF2) and raw CryptoKey decryption.
+ * Decrypts `wemush://v1/encrypted/...` URLs, the equivalent
+ * {@link EncryptedSpecimen} objects, and field-level {@link EncryptedField}
+ * values, using WebCrypto only.
+ *
+ * Failures never throw; they return `{ success: false, error }` where `error`
+ * is a {@link WolsDecryptionError} with a stable, typed `reason`.
+ *
+ * Every cheap check (parameter presence, encodings, IV length, iteration
+ * bounds, key type) runs before PBKDF2, so a malformed or hostile label costs
+ * no key derivation. The iteration count comes from the label and is bounded
+ * by `maxIterations` (default 10,000,000).
+ *
+ * Legacy payloads (no `kdf`, pre-1.3.0 fixed salt) are rejected with
+ * `legacy-format` unless `allowLegacy: true` is passed.
  *
  * @module crypto/decrypt
  */
-import type { Specimen, EncryptedSpecimen, DecryptionOptions, ParseResult } from '../types.js';
+import type { DecryptResult, DecryptionOptions, EncryptedField, EncryptedSpecimen, FieldEncryptedSpecimen, Specimen } from '../types.js';
+/**
+ * Parse an encrypted-format URL into an {@link EncryptedSpecimen} without decrypting.
+ *
+ * Only checks URL structure. Parameter rules (kdf, salt, iterations) are
+ * enforced on decryption. The path segment is percent-decoded to recover the ID.
+ *
+ * @since 1.3.0
+ */
+export declare function parseEncryptedUrl(url: string): DecryptResult<EncryptedSpecimen>;
 /**
- * Decrypt an encrypted specimen using AES-256-GCM
+ * Decrypt an encrypted label to its exact plaintext (the embedded JSON-LD string).
  *
- * @param encrypted - The encrypted specimen wrapper
- * @param options - Decryption options (key required)
- * @returns Promise resolving to ParseResult with decrypted specimen or error
+ * Enforces every v1.3.0 wire rule, including that the decrypted specimen's
+ * `id` equals `wemush:{id}` from the URL path. For object input the check is
+ * made against the object's `id`; an object without `id` is not bound to any
+ * ID, so prefer the URL form for untrusted input.
+ *
+ * @param input - `wemush://v1/encrypted/...` URL or an {@link EncryptedSpecimen}
+ * @param options - `key`, and optional `allowLegacy` and `maxIterations`
+ * @since 1.3.0
+ */
+export declare function decryptPlaintext(input: string | EncryptedSpecimen, options: DecryptionOptions): Promise<DecryptResult<string>>;
+/**
+ * Decrypt an encrypted label and parse it into a validated Specimen.
+ *
+ * @param input - `wemush://v1/encrypted/...` URL or an {@link EncryptedSpecimen}
+ * @param options - `key`, and optional `allowLegacy` and `maxIterations`
+ * @returns DecryptResult; on failure `error.reason` gives the category
  *
  * @example
  * ```typescript
- * import { decryptSpecimen } from '@wemush/wols/crypto';
+ * const result = await decryptSpecimen(url, { key: 'correct horse battery staple' });
+ * if (result.success) console.log(result.data.species);
+ * else console.error(result.error.reason, result.error.message);
+ * ```
  *
- * const result = await decryptSpecimen(encrypted, {
- *   key: 'my-secret-password',
- * });
+ * @since 1.3.0 Accepts encrypted URLs, raw key bytes, `allowLegacy` and `maxIterations`
+ */
+export declare function decryptSpecimen(input: string | EncryptedSpecimen, options: DecryptionOptions): Promise<DecryptResult<Specimen>>;
+/**
+ * Decrypt a single field-level {@link EncryptedField} to its original value.
  *
- * if (result.success) {
- *   console.log(result.data);
- * } else {
- *   console.error(result.error);
- * }
+ * `binding` names the label and field the value belongs to. It is the AES-GCM
+ * additional data (`"{id}\n{field}"`, WOLS 1.3.0), so a value moved to another
+ * field or copied from another label fails with `authentication-failed`.
+ * Legacy (pre-1.3.0) values, which have no `kdf`, carry no binding.
+ *
+ * @example
+ * ```typescript
+ * const r = await decryptField(partial.strain, { key }, { id: partial.id, field: 'strain' });
  * ```
+ *
+ * @since 1.3.0
+ */
+export declare function decryptField(field: EncryptedField, options: DecryptionOptions, binding: FieldBinding): Promise<DecryptResult<unknown>>;
+/** The label and top-level field an encrypted value belongs to. */
+export interface FieldBinding {
+    /** The label's full id, e.g. `"wemush:clx1a2b3c4"` */
+    id: string;
+    /** The top-level field name, e.g. `"strain"` */
+    field: string;
+}
+/**
+ * Decrypt every field-level encrypted value in a specimen produced by
+ * `encryptFields()`, and return the restored, validated Specimen.
+ *
+ * Before any key is derived:
+ * - a label whose identifying fields (`@context`, `@type`, `id`, `version`,
+ *   `type`, `species`) include an encrypted object is refused
+ *   (`identifying-field`); decrypted values never replace them
+ * - every encrypted field is validated
+ * - the iterations of each distinct (salt, iterations) pair are summed, and
+ *   the label is refused if the total exceeds `maxIterations` (10,000,000)
+ *
+ * Fields sharing a salt and iteration count share one derivation. Each value
+ * is authenticated against its AAD, `"{id}\n{field}"`, so swapped or copied
+ * values fail with `authentication-failed`.
+ *
+ * @example
+ * ```typescript
+ * const partial = await encryptFields(specimen, { key, fields: ['strain'] });
+ * const restored = await decryptFields(partial, { key });
+ * if (restored.success) restored.data.strain?.name;
+ * ```
+ *
+ * @since 1.3.0
  */
-export declare function decryptSpecimen(encrypted: EncryptedSpecimen, options: DecryptionOptions): Promise<ParseResult<Specimen>>;
+export declare function decryptFields(value: FieldEncryptedSpecimen | Record<string, unknown>, options: DecryptionOptions): Promise<DecryptResult<Specimen>>;
 //# sourceMappingURL=decrypt.d.ts.map

package/dist/types/crypto/decrypt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decrypt.d.ts","sourceRoot":"","sources":["../../../src/crypto/decrypt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAqE/F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAqDhC"}
+{"version":3,"file":"decrypt.d.ts","sourceRoot":"","sources":["../../../src/crypto/decrypt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EAEjB,sBAAsB,EAEtB,QAAQ,EACT,MAAM,aAAa,CAAC;AAwDrB;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAuE/E;AAwSD;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,GAAG,iBAAiB,EACjC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CA8BhC;AAeD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,GAAG,iBAAiB,EACjC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAIlC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAiBjC;AAED,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;CACf;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvD,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAyGlC"}

package/dist/types/crypto/encrypt.d.ts

@@ -1,32 +1,132 @@
 /**
- * WOLS Encryption Module
+ * WOLS Encryption Module (WOLS v1.3.0 encrypted format)
  *
- * Provides AES-256-GCM encryption for specimens using Web Crypto API.
- * Supports both password-based (PBKDF2) and raw CryptoKey encryption.
+ * AES-256-GCM via WebCrypto, so it runs in Node.js 20+, browsers, Deno and Bun.
+ *
+ * ## Wire format
+ *
+ * ```
+ * wemush://v1/encrypted/{id}?e={ciphertext}&iv={iv}&kdf={pbkdf2|raw}[&salt={salt}&i={iterations}]
+ * ```
+ *
+ * - `e`: ciphertext with the 16-byte GCM tag appended
+ * - `iv`: fresh random 12-byte IV per encryption
+ * - All binary values are base64url without padding
+ *
+ * ## Keys
+ *
+ * | `key` value | `kdf` | Notes |
+ * |-------------|-------|-------|
+ * | `string` passphrase | `pbkdf2` | PBKDF2-HMAC-SHA256, fresh random 16-byte salt per label, ≥100,000 iterations |
+ * | 32-byte `Uint8Array` / `ArrayBuffer` | `raw` | Key shared out of band |
+ * | AES-GCM 256 `CryptoKey` | `raw` | Key shared out of band |
+ *
+ * Pre-1.3.0 releases derived passphrase keys with a fixed library-wide salt.
+ * That scheme is never generated any more; see `allowLegacy` on decryption.
  *
  * @module crypto/encrypt
  */
-import type { Specimen, EncryptedSpecimen, EncryptionOptions } from '../types.js';
+import type { EncryptedField, EncryptedSpecimen, EncryptionOptions, FieldEncryptedSpecimen, FieldEncryptedSpecimenOf, FieldEncryptionOptions, Specimen } from '../types.js';
 /**
- * Encrypt a specimen using AES-256-GCM
+ * Build the encrypted-format URL for an encrypted specimen.
+ *
+ * Enforces the generator rules, so a hand-built object cannot produce a
+ * non-conformant label:
+ * - `payload` and `iv` are canonical unpadded base64url, the IV is 12 bytes,
+ *   and the payload is at least the 16-byte GCM tag
+ * - `kdf` is present: `pbkdf2` needs 100,000 to 2^32-1 iterations and a salt
+ *   of at least 16 bytes that is not the legacy library salt (compared as
+ *   bytes); `raw` must not carry `salt` or `iterations`
+ *
+ * Labels with more than 10,000,000 iterations are valid but exceed the
+ * decoders' default `maxIterations`, so readers must raise it.
+ *
+ * @throws WolsEncryptionError when the object would produce a non-conformant
+ *   label (including legacy payloads, which are never generated)
+ * @since 1.3.0
+ */
+export declare function toEncryptedUrl(encrypted: EncryptedSpecimen): string;
+/**
+ * Encrypt a whole specimen with AES-256-GCM (WOLS v1.3.0 encrypted format).
+ *
+ * The specimen's embedded JSON-LD serialization is encrypted and the result
+ * carries `url`, the `wemush://v1/encrypted/...` string to encode in a QR code.
+ * For field-level encryption use {@link encryptFields}.
  *
  * @param specimen - The specimen to encrypt
- * @param options - Encryption options (key required)
- * @returns Promise resolving to encrypted specimen wrapper
+ * @param options - `key` (passphrase or raw key) and optional `iterations`
+ * @throws WolsEncryptionError for an unusable key, too few iterations, an id
+ *   without a suffix, or a runtime without WebCrypto
  *
  * @example
  * ```typescript
- * import { encryptSpecimen } from '@wemush/wols/crypto';
+ * // Passphrase: kdf=pbkdf2 with a random per-label salt
+ * const enc = await encryptSpecimen(specimen, { key: 'correct horse battery staple' });
+ * enc.url; // 'wemush://v1/encrypted/clx1a2b3c4?e=...&iv=...&kdf=pbkdf2&salt=...&i=100000'
  *
- * const encrypted = await encryptSpecimen(specimen, {
- *   key: 'my-secret-password',
- * });
- * // Returns: { encrypted: true, payload: "...", iv: "...", algorithm: "AES-256-GCM" }
+ * // Raw 32-byte key: kdf=raw
+ * const raw = await encryptSpecimen(specimen, { key: crypto.getRandomValues(new Uint8Array(32)) });
  * ```
+ *
+ * @since 1.3.0 Per-label random salt, `kdf`, `id` and `url`; raw key bytes accepted.
+ *   The `fields` option is deprecated in favor of `encryptFields()`.
  */
+export declare function encryptSpecimen(specimen: Specimen, options: EncryptionOptions & {
+    fields: readonly string[];
+}): Promise<FieldEncryptedSpecimen>;
 export declare function encryptSpecimen(specimen: Specimen, options: EncryptionOptions): Promise<EncryptedSpecimen>;
 /**
- * Type guard to check if an object is an encrypted specimen
+ * Field-level encryption (WOLS v1.3.0): replace the value of each named field
+ * with an {@link EncryptedField} and leave the rest of the specimen in cleartext.
+ *
+ * One key (and, for passphrases, one random salt) per call; a fresh IV per field.
+ * Each value is bound to its label and field with AES-GCM additional data:
+ * the UTF-8 of `"{id}\n{field}"` (WOLS 1.3.0). A value moved to another field
+ * or copied into another label fails authentication. Restore with `decryptFields()`.
+ *
+ * The identifying fields (`@context`, `@type`, `id`, `version`, `type`,
+ * `species`) can't be encrypted.
+ *
+ * @param specimen - The specimen to partially encrypt
+ * @param options - `key`, `fields` (each must be present on the specimen), optional `iterations`
+ * @throws WolsEncryptionError when `fields` is empty, names a field the specimen
+ *   does not have, or names a field twice; or for an unusable key
+ *
+ * @example
+ * ```typescript
+ * const partial = await encryptFields(specimen, { key: passphrase, fields: ['strain'] });
+ * partial.species;  // still cleartext
+ * partial.strain;   // { encrypted: true, algorithm: 'AES-256-GCM', payload, iv, kdf: 'pbkdf2', salt, iterations }
+ * ```
+ *
+ * @since 1.3.0
+ */
+export declare function encryptFields<K extends keyof Specimen>(specimen: Specimen, options: FieldEncryptionOptions<K>): Promise<FieldEncryptedSpecimenOf<K>>;
+/**
+ * Whether a value is a field-level {@link EncryptedField}: an encrypted value
+ * with a `kdf` and no specimen `id` or `url`.
+ *
+ * The 1.3.0 shapes are told apart structurally: whole-label objects produced
+ * by `encryptSpecimen` and `parseEncryptedUrl` always carry `id`, and field
+ * values never do. Legacy (pre-1.3.0) values have no `kdf` and are reported
+ * as {@link isEncryptedSpecimen}, whether they were whole labels or fields.
+ * `decryptFields` handles legacy field values regardless (with `allowLegacy`).
+ *
+ * @since 1.3.0
+ */
+export declare function isEncryptedField(value: unknown): value is EncryptedField;
+/**
+ * Whether a value is a whole-label {@link EncryptedSpecimen} (v1.3.0 or legacy).
+ *
+ * @since 1.3.0
+ */
+export declare function isEncryptedSpecimen(value: unknown): value is EncryptedSpecimen;
+/**
+ * Whether a value carries the `encrypted: true` marker: either a whole-label
+ * {@link EncryptedSpecimen} or a field-level {@link EncryptedField}. Use
+ * {@link isEncryptedSpecimen} or {@link isEncryptedField} to tell them apart.
+ *
+ * @since 1.3.0 Narrows to `EncryptedSpecimen | EncryptedField`
  */
-export declare function isEncrypted(value: unknown): value is EncryptedSpecimen;
+export declare function isEncrypted(value: unknown): value is EncryptedSpecimen | EncryptedField;
 //# sourceMappingURL=encrypt.d.ts.map

package/dist/types/crypto/encrypt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encrypt.d.ts","sourceRoot":"","sources":["../../../src/crypto/encrypt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAwElF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAgC5B;AA+CD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAStE"}
+{"version":3,"file":"encrypt.d.ts","sourceRoot":"","sources":["../../../src/crypto/encrypt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EAEjB,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,QAAQ,EACT,MAAM,aAAa,CAAC;AA+IrB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,iBAAiB,GAAG,MAAM,CAmCnE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,iBAAiB,GAAG;IAAE,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACzD,OAAO,CAAC,sBAAsB,CAAC,CAAC;AACnC,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAuC9B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,MAAM,QAAQ,EAC1D,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAuDtC;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAOxE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAE9E;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,GAAG,cAAc,CAKvF"}

package/dist/types/crypto/index.d.ts

@@ -1,10 +1,12 @@
 /**
  * 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
  */
-export { encryptSpecimen, isEncrypted } from './encrypt.js';
-export { decryptSpecimen } from './decrypt.js';
+export { encryptSpecimen, encryptFields, isEncrypted, isEncryptedSpecimen, isEncryptedField, toEncryptedUrl, } from './encrypt.js';
+export { decryptSpecimen, decryptPlaintext, decryptField, decryptFields, parseEncryptedUrl, type FieldBinding, } from './decrypt.js';
+export { base64UrlEncode, base64UrlDecode, derivePassphraseKey } from './shared.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/crypto/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/crypto/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/crypto/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,eAAe,EACf,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/types/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/types/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/types/errors.d.ts

@@ -6,7 +6,7 @@
  *
  * @module errors
  */
-import type { ValidationError } from './types.js';
+import type { DecryptionFailureReason, ValidationError } from './types.js';
 /**
  * WOLS error codes (stable, for programmatic handling).
  */
@@ -88,6 +88,36 @@ export declare class WolsValidationError extends WolsError {
 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.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAMlD;;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;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"}
+{"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/types/index.d.ts

@@ -1,21 +1,29 @@
 /**
  * @wemush/wols - Official WOLS TypeScript Library
  *
- * WeMush Open Labeling Standard (WOLS) v1.1.0 implementation
+ * WeMush Open Labeling Standard (WOLS) v1.3.0 implementation
  * for biological specimen labeling and traceability.
  *
  * @packageDocumentation
  * @module @wemush/wols
- * @version 1.1.0
+ * @version 1.3.0
  */
 export { WOLS_VERSION, WOLS_CONTEXT } from './types.js';
-export type { Brand, SpecimenId, SpecimenType, GrowthStage, Strain, Specimen, SpecimenInput, ParseResult, ValidationResult, ValidationError, ValidationWarning, ValidationOptions, SpecimenRef, QRCodeOptions, EncryptionOptions, DecryptionOptions, EncryptedSpecimen, } from './types.js';
+export type { Brand, SpecimenId, SpecimenType, GrowthStage, Strain, Specimen, SpecimenInput, SpecimenMeta, CreateSpecimenOptions, ParseResult, ValidationResult, ValidationError, ValidationWarning, ValidationOptions, IdValidationMode, IdValidator, SpecimenRef, QRCodeOptions, EncryptionOptions, DecryptionOptions, EncryptedSpecimen, EncryptedField, EncryptionKdf, RawEncryptionKey, DecryptionFailureReason, DecryptResult, FieldEncryptedSpecimen, FieldEncryptionOptions, } from './types.js';
 export { asSpecimenId, isSpecimenType, isGrowthStage, isStrain, SPECIMEN_TYPES, GROWTH_STAGES, } from './types.js';
-export { WolsErrorCode, WolsError, WolsParseError, WolsValidationError, WolsEncryptionError, } from './errors.js';
-export { createSpecimen, serializeSpecimen } from './specimen.js';
+export { registerTypeAlias, resolveTypeAlias, getTypeAliases, resolveTypeAndStage, PRIMORDIA_TYPE_ALIAS, } from './types.js';
+export { WOLS_TO_PLATFORM_MAP, mapToWolsType, mapFromWolsType, registerPlatformType, } from './types.js';
+export { normalizeGeneration, isValidGeneration } from './types.js';
+export type { GenerationFormat } from './types.js';
+export { WolsErrorCode, WolsError, WolsParseError, WolsValidationError, WolsEncryptionError, WolsDecryptionError, } from './errors.js';
+export { createSpecimen, serializeSpecimen, PRIMORDIA_AS_TYPE_WARNING } from './specimen.js';
 export { validateSpecimen } from './validator.js';
 export { parseSpecimen } from './parser.js';
-export { toCompactUrl, parseCompactUrl, SPECIES_CODES, getSpeciesFromCode, getCodeFromSpecies, registerSpeciesCode, } from './compact-url.js';
-export { encryptSpecimen, isEncrypted, decryptSpecimen } from './crypto/index.js';
+export { toCompactUrl, parseCompactUrl, parseCompactUrlOrThrow, parseCompactUrlOrNull, SPECIES_CODES, getSpeciesFromCode, getCodeFromSpecies, registerSpeciesCode, } from './compact-url.js';
+export { encryptSpecimen, encryptFields, isEncrypted, isEncryptedSpecimen, isEncryptedField, toEncryptedUrl, decryptSpecimen, decryptPlaintext, decryptField, decryptFields, parseEncryptedUrl, type FieldBinding, base64UrlEncode, base64UrlDecode, derivePassphraseKey, } from './crypto/index.js';
 export { toQRCode, toQRCodeDataURL, toQRCodeSVG, isQRAvailable, isQRAvailableSync, } from './qr/index.js';
+export { isServer, isBrowser, isWebWorker, isDeno, isBun, getRuntimeEnvironment, supportsWebCrypto, supportsNodeCrypto, isCryptoSupported, supportsTextEncoding, supportsURLAPIs, } from './utils/environment.js';
+export type { RuntimeEnvironment } from './utils/environment.js';
+export { compareVersions, isOutdated, isNewer, getCurrentVersion, registerMigration, canMigrate, migrate, getMigrations, clearMigrations, } from './utils/migration.js';
+export type { VersionComparison, MigrationHandler } from './utils/migration.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAKxD,YAAY,EAEV,KAAK,EACL,UAAU,EAGV,YAAY,EACZ,WAAW,EACX,MAAM,EACN,QAAQ,EACR,aAAa,EAGb,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EAGjB,WAAW,EAGX,aAAa,EAGb,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAKpB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,aAAa,EACb,QAAQ,EACR,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AAKpB,OAAO,EACL,aAAa,EACb,SAAS,EACT,cAAc,EACd,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAKrB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAKlE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAKlD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAK5C,OAAO,EACL,YAAY,EACZ,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAKlF,OAAO,EACL,QAAQ,EACR,eAAe,EACf,WAAW,EACX,aAAa,EACb,iBAAiB,GAClB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAKxD,YAAY,EAEV,KAAK,EACL,UAAU,EAGV,YAAY,EACZ,WAAW,EACX,MAAM,EACN,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,qBAAqB,EAGrB,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EAGjB,gBAAgB,EAChB,WAAW,EAGX,WAAW,EAGX,aAAa,EAGb,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,uBAAuB,EACvB,aAAa,EACb,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAKpB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,aAAa,EACb,QAAQ,EACR,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AAKpB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAKpB,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAKnD,OAAO,EACL,aAAa,EACb,SAAS,EACT,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAKrB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAK7F,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAKlD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAK5C,OAAO,EACL,YAAY,EACZ,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EACL,eAAe,EACf,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,KAAK,YAAY,EACjB,eAAe,EACf,eAAe,EACf,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EACL,QAAQ,EACR,eAAe,EACf,WAAW,EACX,aAAa,EACb,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAKvB,OAAO,EACL,QAAQ,EACR,SAAS,EACT,WAAW,EACX,MAAM,EACN,KAAK,EACL,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAKjE,OAAO,EACL,eAAe,EACf,UAAU,EACV,OAAO,EACP,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,OAAO,EACP,aAAa,EACb,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/types/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,QAAQ,EAId,MAAM,YAAY,CAAC;AAyCpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAoGjE"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,QAAQ,EAKd,MAAM,YAAY,CAAC;AAyCpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAwGjE"}

package/dist/types/specimen.d.ts

@@ -2,19 +2,31 @@
  * Specimen Creation and Serialization
  *
  * This module provides functions to create and serialize
- * WOLS v1.1.0 compliant specimen objects.
+ * WOLS v1.3.0 compliant specimen objects.
  *
  * @module specimen
  */
-import type { Specimen, SpecimenInput } from './types.js';
+import type { CreateSpecimenOptions, Specimen, SpecimenInput } from './types.js';
+/**
+ * Warning code emitted when `PRIMORDIA` is supplied as a specimen type.
+ *
+ * @since 1.3.0
+ */
+export declare const PRIMORDIA_AS_TYPE_WARNING = "PRIMORDIA_AS_TYPE";
 /**
  * Create a new specimen with auto-generated ID and JSON-LD fields.
  *
- * This function creates a fully-formed WOLS v1.1.0 compliant Specimen
+ * This function creates a fully-formed WOLS v1.3.0 compliant Specimen
  * with automatic ID generation, version assignment, and JSON-LD context.
  *
+ * Type aliases resolve case-insensitively. `PRIMORDIA` supplied as a type
+ * resolves to `FRUITING`, sets `stage: 'PRIMORDIA'` when no stage was given
+ * (a supplied stage is never overridden), and emits a warning.
+ *
  * @param input - Specimen creation parameters
+ * @param options - `onWarning` receives non-fatal warnings (default: console.warn)
  * @returns Fully-formed Specimen with JSON-LD fields
+ * @throws Error if the type is unknown or `created` is not ISO 8601
  *
  * @example
  * ```typescript
@@ -44,9 +56,22 @@ import type { Specimen, SpecimenInput } from './types.js';
  *   species: 'Ganoderma lucidum',
  *   strain: 'Reishi Red',  // Auto-expands to { name: 'Reishi Red' }
  * });
+ *
+ * // PRIMORDIA as a type (v1.3.0) -> type FRUITING, stage PRIMORDIA, plus a warning
+ * const pinning = createSpecimen(
+ *   { type: 'PRIMORDIA', species: 'Pleurotus ostreatus' },
+ *   { onWarning: w => console.info(w.message) }
+ * );
+ *
+ * // Explicit creation timestamp (v1.3.0)
+ * const dated = createSpecimen({
+ *   type: 'CULTURE',
+ *   species: 'Pleurotus ostreatus',
+ *   created: '2025-12-16T10:30:00Z',
+ * });
  * ```
  */
-export declare function createSpecimen(input: SpecimenInput): Specimen;
+export declare function createSpecimen(input: SpecimenInput, options?: CreateSpecimenOptions): Specimen;
 /**
  * Serialize a specimen to JSON-LD string.
  *

package/dist/types/specimen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"specimen.d.ts","sourceRoot":"","sources":["../../src/specimen.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAU,MAAM,YAAY,CAAC;AA2BlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,QAAQ,CAwC7D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CA6C5D"}
+{"version":3,"file":"specimen.d.ts","sourceRoot":"","sources":["../../src/specimen.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,QAAQ,EACR,aAAa,EAGd,MAAM,YAAY,CAAC;AAWpB;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,sBAAsB,CAAC;AAkC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,aAAa,EACpB,OAAO,GAAE,qBAA0B,GAClC,QAAQ,CAmFV;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CA4D5D"}