@wemush/wols 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,170 @@
+# Changelog
+
+All notable changes to `@wemush/wols` are documented here. This project follows
+[Semantic Versioning](https://semver.org/), except that its major and minor versions match the
+WOLS specification version it implements. A spec minor release can require breaking changes, and
+those are listed below.
+
+## [1.3.0]
+
+Brings the library in line with the [WOLS 1.3.0 specification](https://github.com/wemush/open-standard/blob/main/SPECIFICATION.md).
+Implements WOLS `1.3.0-rc.2` (open-standard tag `1.3.0-rc.2`, commit `9d200c9`). All `MUST` and `SHOULD` cases in the shared conformance vectors pass:
+
+| Vector file       | MUST  | SHOULD |
+| ----------------- | ----- | ------ |
+| `embedded.json`   | 12/12 | 1/1    |
+| `primordia.json`  | 4/4   | 1/1    |
+| `generation.json` | 9/9   | 1/1    |
+| `encrypted.json`  | 19/19 | 2/2    |
+| `field-encryption.json` | 6/6 | —    |
+
+### WOLS 1.3.0-rc.2 encryption rules
+
+These rules were added on top of `rc.1` before 1.3.0 was published. Field-level ciphertexts made by
+earlier unpublished 1.3.0 builds don't decrypt under them. Because nothing was released, no
+migration is needed.
+
+- **NFC passphrases.** The passphrase is normalized to Unicode NFC, then UTF-8 encoded, before
+  PBKDF2. This applies to encryption, decryption and `derivePassphraseKey`.
+- **Field-level AAD.** Each encrypted field is bound to its label and field name. The AES-GCM
+  additional data is the UTF-8 of `"{id}\n{field}"`, and every field gets its own random IV.
+  Values that are swapped between fields or copied from another label fail authentication.
+  `decryptField` now takes a third argument, `{ id, field }`. The URL format has no AAD and keeps
+  the decrypted-`id` check.
+- **Identifying fields.** `@context`, `@type`, `id`, `version`, `type` and `species` are never
+  encrypted. `decryptFields` refuses a label that has an encrypted identifying field, with reason
+  `identifying-field`.
+- **Iterations.**
+  - Generation defaults to 600,000 iterations. Anything from 100,000 to 10,000,000 is allowed.
+  - Decoding rejects fewer than 10,000 or more than 10,000,000, before deriving any key.
+    `maxIterations` may be set lower, never higher.
+  - For field-level decryption, the 10,000,000 limit applies to the label's total across distinct
+    salt and iteration-count pairs.
+- **ID path encoding.** Malformed percent-escapes and invalid UTF-8 in the URL path are rejected
+  with reason `invalid-encoding`. `+` is a literal character.
+- **New failure reasons:** `invalid-encoding` and `identifying-field`.
+- **Vectors.** The vectors are re-vendored from `1.3.0-rc.2` and verified against upstream's
+  `SHA256SUMS`, which is now vendored too. This adds `field-encryption.json` and its
+  `decryptFields` operation, and 10 new `encrypted.json` cases.
+
+### ⚠️ Breaking changes
+
+**Encrypted generation.** The encrypted format follows the 1.3.0 wire format:
+
+```
+wemush://v1/encrypted/{id}?e=&iv=&kdf=pbkdf2|raw[&salt=&i=][&sig=]
+```
+
+- **Passphrase keys use a random per-label salt.** The fixed `@wemush/wols/crypto/v1` salt is no
+  longer used when generating. Every passphrase-encrypted label gets a fresh 16-byte salt, and the
+  label records `kdf=pbkdf2`, `salt` and `i`.
+  - Labels created by 1.3.0 **cannot** be decrypted by 1.2.x, so upgrade readers before writers.
+  - Labels created by 1.2.x have no `kdf`. They fail with reason `legacy-format` unless you pass
+    `allowLegacy: true`. Legacy labels are never generated.
+- **Generation iterations default to 600,000 and must be between 100,000 and 10,000,000**
+  (previously 100,000 by default, with a minimum of 10,000). `encryptSpecimen` throws outside that
+  range. Decoders reject `i` below 10,000 or above 10,000,000.
+- **`EncryptedSpecimen` no longer includes `cryptoVersion`** in generated output. It now has `kdf`,
+  `salt` (pbkdf2), `iterations` (pbkdf2), `id`, and `url`. The deprecated `tag` and
+  `cryptoVersion` fields will be removed in 2.0.
+- **Field-level encryption** values have the 1.3.0 shape
+  `{ encrypted, algorithm, payload, iv, kdf, salt?, iterations? }` instead of
+  `{ ..., cryptoVersion }`.
+- **Field-level encryption is strict.** Naming a field the specimen doesn't have (for example a
+  typo), naming the same field twice, or naming an inherited property such as `constructor` now
+  throws. In 1.2.x such a field was skipped silently and left in cleartext. `@context`, `@type`,
+  `id` and `version` can't be encrypted.
+- **`encryptSpecimen(s, { fields: [...] })`** called with a literal `fields` array is now typed as
+  returning `FieldEncryptedSpecimen`, which is what it returns at runtime.
+- **`CryptoKey` keys** must be AES-GCM with a length of 256 and allow `encrypt` or `decrypt`. That
+  applies to decrypting legacy labels too.
+- **WebCrypto is required.** Node.js 18 has no global `crypto` by default. Use Node.js 20 or later,
+  a browser, Deno or Bun. On a runtime without WebCrypto, encryption throws and decryption returns
+  `unsupported-environment`.
+
+**Validation and creation.**
+
+- **The default `idMode` is now `'any'`** (previously `'strict'`): any non-empty suffix after
+  `wemush:` is accepted, as the spec requires. This loosens validation. Pass `idMode: 'strict'`,
+  `'ulid'` or `'uuid'` to opt into a format check.
+- **`createSpecimen({ type: 'PRIMORDIA' })`** now resolves to `FRUITING`, sets
+  `stage: 'PRIMORDIA'` when no stage was supplied, and warns through `console.warn` unless you pass
+  `onWarning`.
+- **`registerTypeAlias('PRIMORDIA', …)`** throws for any type other than `FRUITING`.
+- **`isEncrypted`** now narrows to `EncryptedSpecimen | EncryptedField`. Use `isEncryptedSpecimen`
+  or `isEncryptedField` to tell them apart.
+
+### Added
+
+- **Encrypted URLs.** `encryptSpecimen` returns `url`. `decryptSpecimen` accepts the URL or the
+  object.
+- **Raw keys (`kdf=raw`).** Pass 32 key bytes (`Uint8Array` or `ArrayBuffer`) or an AES-GCM 256
+  `CryptoKey` as `key`. A passphrase string selects `kdf=pbkdf2`.
+- **`encryptFields(specimen, { key, fields })`** returns a typed `FieldEncryptedSpecimen`.
+  `decryptFields` returns a validated `Specimen`. `encryptSpecimen`'s `fields` option is
+  deprecated.
+- **Typed decryption errors.** A failed decryption carries a `WolsDecryptionError` whose `reason` is a
+  `DecryptionFailureReason`, also copied into `details.reason`. The decryption functions return
+  `DecryptResult<T>`, which is assignable to `ParseResult<T>`. They never throw.
+- **Decryption hardening.**
+  - Every parameter, encoding, the IV length and the key type are checked before PBKDF2 runs, so a
+    hostile label costs no key derivation.
+  - `maxIterations` (default 10,000,000) bounds the iteration count a label can demand.
+    `decryptFields` validates every field first, derives once per distinct salt, and bounds the
+    whole document's total.
+  - The decrypted `id` must equal `wemush:{id}` from the URL path.
+  - Unknown `kdf` values are rejected, as are `salt` or `i` with `kdf=raw`, a `salt` on a legacy
+    label, ciphertext shorter than the GCM tag, and plaintext starting with a byte order mark.
+  - Padded base64url is accepted.
+- **`toEncryptedUrl` enforces the generator rules.** Every value must be canonical unpadded
+  base64url, and the IV must be 12 bytes. It refuses an iteration count outside 100,000 to
+  2^32-1, a salt shorter than 16 bytes or byte-equal to the legacy salt, and `salt` with
+  `kdf=raw`.
+- **New exports:**
+  - Functions: `encryptFields`, `decryptPlaintext` (exact plaintext), `toEncryptedUrl`,
+    `parseEncryptedUrl`, `decryptField`, `decryptFields`, `isEncryptedSpecimen`,
+    `isEncryptedField`, `derivePassphraseKey`, `base64UrlEncode`, `base64UrlDecode`,
+    `resolveTypeAndStage`.
+  - Classes: `WolsDecryptionError`.
+- **`strain.transferDepth`** counts every transfer from the original culture.
+  - It must be a non-negative integer, and validation warns when it is less than
+    `clonalGeneration`.
+  - It round-trips through `serializeSpecimen` and `parseSpecimen`.
+- **`createSpecimen` accepts `created`**, as an ISO 8601 string or a `Date`. Invalid values throw.
+  When `created` is omitted the field is left out, as before.
+- **`createSpecimen(input, { onWarning })`** receives non-fatal warnings. Without it, warnings go
+  to `console.warn`.
+- **`resolveTypeAndStage(type, stage?)`** is the single implementation of the reserved `PRIMORDIA`
+  rule. `createSpecimen` and `serializeSpecimen` both use it. `resolveTypeAlias` and
+  `mapToWolsType` still map the type only.
+- **Conformance suite.**
+  - The WOLS vectors are vendored in `tests/conformance/vectors`, pinned to upstream commit
+    `3066545`. Run them with `npm run test:conformance`.
+  - `SOURCE.json` records each file's SHA-256 and case count. The runner fails when the vendored
+    files or their contents differ from it, when a file has no `MUST` cases, or when a case uses an
+    operation it doesn't know.
+  - `npm run conformance:update` refreshes the vectors. It discovers upstream files through the
+    GitHub API, validates everything before writing anything, and removes stale files.
+- `CHANGELOG.md`.
+
+### Changed
+
+- **`PRIMORDIA` supplied as a type** is never serialized as a `type`. `serializeSpecimen` resolves
+  it on hand-built objects too.
+- `isValidSpecimenId(id, strict?)` accepts any non-empty suffix by default, matching `idMode`.
+- **`strain.clonalGeneration` accepts `0`** for the original culture. It previously required
+  `>= 1`, which contradicted the spec.
+- **`strain.generation` accepts `P<n>`** (for example `P1`).
+- `WOLS_VERSION` is `1.3.0`, so new specimens are stamped with `version: "1.3.0"`.
+- Growth-stage validation messages list all seven stages.
+
+### Fixed
+
+- **`require('@wemush/wols')` works** ([#9](https://github.com/wemush/specimen-labels-js/pull/9)).
+  It was broken in 1.2.0 because `dist/cjs` was loaded as ESM. CommonJS consumers now also get
+  CommonJS type declarations.
+
+### Unchanged
+
+- The compact URL format. Its parameter and species-code registries aren't settled yet.
+- `sig` is preserved when parsing and generating encrypted URLs, but it isn't verified.

package/README.md

@@ -12,7 +12,8 @@ Official TypeScript library for **WOLS** (WeMush Open Labeling Standard) - the o
 - 📜 **Parse** - Parse JSON/QR data back to typed specimens
 - 📱 **QR Codes** - Generate QR codes for specimens (PNG, SVG, Data URL)
 - 🔗 **Compact URLs** - Create short URLs for space-constrained labels
-- 🔐 **Encryption** - AES-256-GCM encryption for sensitive data
+- 🔐 **Encryption** - WOLS 1.3.0 encrypted format (AES-256-GCM, per-label PBKDF2 salt or raw keys)
+- 🧪 **Conformance** - Passes every `MUST` vector in the WOLS 1.3.0 conformance suite
 
 ## Installation
 
@@ -51,7 +52,7 @@ console.log(specimen['@context']); // "https://wemush.com/wols/v1"
 
 ## Core Module API
 
-### `createSpecimen(input: SpecimenInput): Specimen`
+### `createSpecimen(input: SpecimenInput, options?): Specimen`
 
 Creates a new specimen with auto-generated ID and JSON-LD fields.
 
@@ -59,8 +60,9 @@ Creates a new specimen with auto-generated ID and JSON-LD fields.
 const specimen = createSpecimen({
   type: 'SPAWN',
   species: 'Hericium erinaceus',
-  strain: { name: "Lion's Mane", generation: 'F2' },
+  strain: { name: "Lion's Mane", generation: 'F2', clonalGeneration: 3, transferDepth: 4 },
   stage: 'INOCULATION',
+  created: '2025-12-16T10:30:00Z',
   batch: 'BATCH-2024-001',
   organization: 'org_123',
   custom: { substrate: 'hardwood' },
@@ -69,15 +71,53 @@ const specimen = createSpecimen({
 
 **Parameters:**
 
-- `type` - Specimen type: `'CULTURE'`, `'SPAWN'`, `'SUBSTRATE'`, `'FRUITING'`, `'HARVEST'`
+- `type` - Specimen type: `'CULTURE'`, `'SPAWN'`, `'SUBSTRATE'`, `'FRUITING'`, `'HARVEST'`, or an alias such as `'LC'`, `'GRAIN_SPAWN'`, `'BAG'`, `'PINNING'` (case-insensitive)
 - `species` - Scientific species name
 - `strain` - String (auto-expands to `{ name: string }`) or full `Strain` object
-- `stage` - Growth stage: `'INOCULATION'`, `'COLONIZATION'`, `'FRUITING'`, `'HARVEST'`
+- `stage` - Growth stage: `'INOCULATION'`, `'INCUBATION'`, `'COLONIZATION'`, `'PRIMORDIA'`, `'FRUITING'`, `'SENESCENCE'`, `'HARVEST'`
+- `created` - Creation timestamp, an ISO 8601 string or a `Date` (omitted when not supplied; invalid values throw)
 - `batch` - Batch identifier
 - `organization` - Organization ID
 - `creator` - Creator user ID
 - `custom` - Custom vendor-specific fields
 
+**Options:**
+
+- `onWarning(warning)` - Receives non-fatal warnings. If omitted, warnings go to `console.warn`.
+
+#### `PRIMORDIA` as a type
+
+`PRIMORDIA` is a growth stage, not a specimen type. Because people often supply it as a type,
+WOLS 1.3.0 makes it a reserved alias. When `type` is `PRIMORDIA` (in any case), the library:
+
+- resolves the type to `FRUITING`
+- sets `stage: 'PRIMORDIA'` if no stage was supplied, and never overrides a supplied stage
+- emits a `PRIMORDIA_AS_TYPE` warning that recommends `type: 'FRUITING', stage: 'PRIMORDIA'`
+- never serializes `PRIMORDIA` as a `type`. `serializeSpecimen` applies the same resolution to hand-built objects.
+
+```typescript
+const s = createSpecimen(
+  { type: 'primordia', species: 'Pleurotus ostreatus' },
+  { onWarning: w => log.info(w.message) }
+);
+// s.type === 'FRUITING', s.stage === 'PRIMORDIA'
+```
+
+`validateSpecimen` still rejects `type: "PRIMORDIA"` in a serialized label.
+
+#### Generation, subculture, and transfer depth
+
+`strain` carries three independent counters (WOLS 1.3.0):
+
+| Field              | Meaning                                                    | Original culture |
+| ------------------ | ---------------------------------------------------------- | ---------------- |
+| `generation`       | Filial generation (`P`, `F1`, `G2`, `3`, …)                | `P`              |
+| `clonalGeneration` | Culture-to-culture subcultures                             | `0`              |
+| `transferDepth`    | Transfers of any kind (subculture, to grain, to substrate) | `0`              |
+
+Both counters must be non-negative integers. Validation warns when `transferDepth` is less
+than `clonalGeneration`.
+
 ### `serializeSpecimen(specimen: Specimen): string`
 
 Serializes a specimen to a JSON-LD string, suitable for QR encoding.
@@ -119,6 +159,11 @@ if (!result.valid) {
 
 - `allowUnknownFields` - Allow unknown fields in custom namespace
 - `level` - Validation strictness: `'strict'` or `'lenient'`
+- `idMode` - ID check. Every mode requires the `wemush:` prefix.
+  - `'any'` (default): any non-empty suffix, as WOLS requires. CUIDs, ULIDs, UUIDs and human-readable IDs are all accepted.
+  - `'strict'` (opt-in): the suffix must be a CUID-style `[a-z0-9]+`.
+  - `'ulid'` / `'uuid'` (opt-in): the suffix must be a ULID or a UUID.
+- `customIdValidator` - Your own `(id) => boolean` check, which takes precedence over `idMode`
 
 ## QR Code Module API
 
@@ -189,57 +234,148 @@ if (result.success) {
 
 ## Encryption Module API
 
-Encrypt specimens using AES-256-GCM for secure data handling.
+Implements the WOLS 1.3.0 encrypted format with WebCrypto, so it works in Node.js 20+, browsers,
+Deno and Bun.
+
+```
+wemush://v1/encrypted/{id}?e={ciphertext}&iv={iv}&kdf=pbkdf2|raw[&salt={salt}&i={iterations}][&sig={signature}]
+```
+
+- AES-256-GCM. `e` is the ciphertext with the 16-byte tag appended. `iv` is a fresh random 12-byte IV for every encryption.
+- Every binary value is base64url without padding. Decoders also accept padded input.
+- `{id}` is the specimen ID without the `wemush:` prefix, percent-encoded as one URL path segment (`encodeURIComponent`). Decoders percent-decode it as UTF-8 before the `id` check, keep `+` as a literal character, and reject malformed escapes or invalid UTF-8. It is cleartext, so don't put sensitive data in it.
+- Passphrases are normalized to Unicode NFC before PBKDF2, so a passphrase typed in composed or decomposed form (for example `ü` as one code point, or `u` plus a combining mark) gives the same key.
 
 ```typescript
-import { encryptSpecimen, decryptSpecimen, isEncrypted } from '@wemush/wols';
+import { encryptSpecimen, decryptSpecimen } from '@wemush/wols';
 // Or import from submodule:
 // import { encryptSpecimen } from '@wemush/wols/crypto';
 ```
 
 ### `encryptSpecimen(specimen, options): Promise<EncryptedSpecimen>`
 
-Encrypt a specimen with a password or CryptoKey.
+Encrypts the whole label. The kind of `key` you pass selects the key derivation:
+
+| `key`                                                               | `kdf`    | Behavior                                                                                 |
+| ------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------- |
+| passphrase `string`                                                 | `pbkdf2` | PBKDF2-HMAC-SHA256 over the NFC-normalized passphrase, a fresh random 16-byte salt per label, 600,000 iterations by default |
+| 32-byte `Uint8Array` / `ArrayBuffer`, or an AES-GCM 256 `CryptoKey` | `raw`    | Key shared out of band. No `salt` or `i`.                                                |
 
 ```typescript
-const encrypted = await encryptSpecimen(specimen, {
-  key: 'my-secret-password',
-});
+const enc = await encryptSpecimen(specimen, { key: 'correct horse battery staple' });
+enc.url;
+// "wemush://v1/encrypted/clx1a2b3c4?e=...&iv=...&kdf=pbkdf2&salt=...&i=600000"
 
-console.log(encrypted);
-// { encrypted: true, payload: "...", iv: "...", algorithm: "AES-256-GCM" }
+const raw = await encryptSpecimen(specimen, { key: crypto.getRandomValues(new Uint8Array(32)) });
+raw.url; // "wemush://v1/encrypted/clx1a2b3c4?e=...&iv=...&kdf=raw"
 ```
 
-### `decryptSpecimen(encrypted, options): Promise<ParseResult<Specimen>>`
+The result also carries `payload`, `iv`, `kdf`, `salt`, `iterations` and `id`. Put `url` in the QR code.
+
+**Options:**
+
+- `key` - A passphrase (`kdf=pbkdf2`), or raw key bytes or a `CryptoKey` (`kdf=raw`)
+- `iterations` - PBKDF2 iterations. Passphrase keys only. The default is 600,000, and anything
+  from 100,000 to 10,000,000 is allowed.
+- `fields` - **Deprecated.** Use `encryptFields` instead.
+
+### `encryptFields(specimen, { key, fields }): Promise<FieldEncryptedSpecimen>`
 
-Decrypt an encrypted specimen.
+Field-level encryption. Each named field's value is replaced in place with
+`{ encrypted: true, algorithm: "AES-256-GCM", payload, iv, kdf, salt?, iterations? }`, and the rest
+of the label stays in cleartext. Every name in `fields` must be a field the specimen actually has.
+A misspelled or missing field throws instead of being left unprotected. `@context`, `@type`, `id`,
+`version`, `type` and `species` identify the label, so they can't be encrypted. The result is typed
+precisely: the named fields are `EncryptedField`, and every other field keeps its cleartext type.
 
 ```typescript
-const result = await decryptSpecimen(encrypted, {
-  key: 'my-secret-password',
-});
+const partial = await encryptFields(specimen, { key: passphrase, fields: ['strain'] });
+partial.species; // cleartext
+partial.strain; // { encrypted: true, kdf: 'pbkdf2', ... }
 
-if (result.success) {
-  console.log(result.data.species);
-} else {
-  console.error('Decryption failed:', result.error.message);
-}
+const restored = await decryptFields(partial, { key: passphrase });
+if (restored.success) restored.data.strain?.name; // a validated Specimen
 ```
 
-### `isEncrypted(value): boolean`
+Each value is bound to its label and field. The AES-GCM additional data is the UTF-8 encoding of
+the label's full `id`, a line feed, and the field name, for example `"wemush:clx1a2b3c4\nstrain"`.
+Every field gets its own random IV. A value moved to another field, copied from another label, or
+left behind after the `id` changes fails with `authentication-failed`.
+
+`decryptFields` refuses a label in which an identifying field is encrypted (`identifying-field`).
+It never substitutes a decrypted value for one. Before deriving any key, it adds up the iterations
+of each distinct salt and iteration-count pair, and refuses the label when the total exceeds
+`maxIterations`.
+
+To decrypt one value, pass its binding: `decryptField(partial.strain, { key }, { id: partial.id, field: 'strain' })`.
 
-Check if a value is an encrypted specimen.
+### `decryptSpecimen(input, options): Promise<DecryptResult<Specimen>>`
+
+`input` can be an encrypted URL or an `EncryptedSpecimen` object. Use `decryptPlaintext` to get the
+exact decrypted JSON string instead. Decryption never throws. A failure carries a
+`WolsDecryptionError` with a typed `reason`:
 
 ```typescript
-if (isEncrypted(data)) {
-  // Handle encrypted specimen
+const result = await decryptSpecimen(url, { key: 'correct horse battery staple' });
+
+if (result.success) {
+  console.log(result.data.species);
+} else if (result.error.reason === 'legacy-format') {
+  // a pre-1.3.0 label: see "Legacy labels" below
+} else {
+  console.error(result.error.reason, result.error.message);
 }
 ```
 
-**Encryption Options:**
+**Options:**
 
-- `key` - Password string (uses PBKDF2) or `CryptoKey`
-- `fields` - Encrypt only specific fields (partial encryption)
+- `key` - The passphrase or raw key
+- `allowLegacy` - Decrypt pre-1.3.0 labels (see below)
+- `maxIterations` - The largest PBKDF2 iteration count accepted from a label. The default and the
+  maximum are both 10,000,000. You can set it lower, never higher. The count comes from the label,
+  so this caps how much CPU a hostile QR code can cost. A server that decodes untrusted labels
+  should set it close to the count it generates with. `decryptFields` applies it to the whole
+  label: fields that share a salt share one key derivation, and the total across distinct salts
+  must stay under the limit.
+
+Every cheap check runs before key derivation, so a malformed label costs no PBKDF2 work. The
+failure reasons are:
+
+| `reason` | When |
+| --- | --- |
+| `id-mismatch` | The decrypted specimen's `id` isn't `wemush:{id}` from the URL path |
+| `authentication-failed` | The key is wrong, or the ciphertext was tampered with |
+| `insufficient-iterations` / `excessive-iterations` | `i` is below 10,000, or above `maxIterations` (alone, or in total for field-level) |
+| `missing-parameter` | `e` or `iv` is missing, or `kdf=pbkdf2` lacks `salt` or `i` |
+| `unexpected-parameter` | `kdf=raw` has `salt` or `i`, or a legacy label has `salt` |
+| `invalid-parameter` | Bad base64url, `i` that isn't plain decimal digits, an IV that isn't 12 bytes, ciphertext shorter than the tag, a duplicate parameter |
+| `invalid-encoding` | The ID in the URL path has a malformed percent-escape or isn't valid UTF-8 |
+| `identifying-field` | A field-level label has an encrypted `@context`, `@type`, `id`, `version`, `type` or `species` |
+| `unsupported-kdf` | `kdf` is something other than `pbkdf2` or `raw` |
+| `invalid-key` | The key doesn't fit the label, for example a passphrase for a `raw` label |
+| `legacy-format` | No `kdf`: a pre-1.3.0 label, and `allowLegacy` wasn't set |
+| `invalid-plaintext` | The decrypted bytes aren't UTF-8 JSON (or start with a BOM), or aren't a valid specimen |
+| `invalid-url` | Not a `wemush://v1/encrypted/...` URL |
+| `unsupported-environment` | The runtime has no WebCrypto |
+
+The `id` check applies to the URL form and to objects that carry an `id`. An object without `id`
+isn't bound to any ID, so prefer URLs for input you don't trust.
+
+After a label authenticates, error messages and `details` can contain decrypted content, such as
+the mismatched `id` or the specimen validation errors. Don't forward them to untrusted parties.
+
+**Legacy labels:** payloads from before 1.3.0 have no `kdf`. They were encrypted with a fixed
+library-wide salt, and they fail with `legacy-format` by default. Pass `{ allowLegacy: true }` only
+when you are decrypting labels you know are old, for example during a migration. Re-encrypt them
+with `encryptSpecimen`. Legacy labels are never generated.
+
+### Other helpers
+
+- `toEncryptedUrl(encrypted)` / `parseEncryptedUrl(url)` - convert between the URL and the object form. `toEncryptedUrl` refuses objects that would make a non-conformant label: values that aren't canonical unpadded base64url, an IV that isn't 12 bytes, fewer than 100,000 iterations, a salt that is short or byte-equal to the legacy salt, or `salt` with `kdf=raw`.
+- `decryptField(field, options)` - decrypt a single encrypted field value
+- `isEncryptedSpecimen(value)` / `isEncryptedField(value)` - tell a whole-label encryption from a field-level one. `isEncrypted(value)` matches either.
+- `derivePassphraseKey(passphrase, salt, iterations)` - raw PBKDF2 output, for debugging interoperability. It doesn't apply the label rules.
+- `base64UrlEncode(bytes)` / `base64UrlDecode(str)`
 
 ## Types
 
@@ -257,7 +393,13 @@ import type {
   ValidationResult,
   ValidationError,
   EncryptedSpecimen,
+  EncryptedField,
+  FieldEncryptedSpecimen,
   EncryptionOptions,
+  FieldEncryptionOptions,
+  DecryptionOptions,
+  DecryptionFailureReason,
+  DecryptResult,
   QRCodeOptions,
 } from '@wemush/wols';
 ```
@@ -287,7 +429,38 @@ if (!result.success) {
 
 ## WOLS Specification
 
-This library implements **WOLS v1.1.0**. For the full specification, see the [WOLS Specification](https://wemush.com/open-standard).
+This library implements **WOLS v1.3.0**. For the full specification, see the
+[WOLS Specification](https://github.com/wemush/open-standard/blob/main/SPECIFICATION.md).
+
+### Conformance
+
+The shared [WOLS conformance vectors](https://github.com/wemush/open-standard/tree/main/conformance)
+are vendored in `tests/conformance/vectors` and run with `npm test` (or `npm run test:conformance`).
+Every `MUST` case passes. `SHOULD` cases are reported but don't fail the build. See
+[`tests/conformance/README.md`](tests/conformance/README.md) for how to refresh the vectors.
+
+### Upgrading from 1.2
+
+See [CHANGELOG.md](CHANGELOG.md). Every change that can break a 1.2.x caller:
+
+- **Encrypted generation changed.** Passphrase encryption now uses a random per-label salt and
+  records `kdf`, `salt` and `i`. Labels made by 1.3.0 can't be read by 1.2.x, so upgrade readers
+  before writers. 1.2.x labels fail with `legacy-format` unless you pass `allowLegacy: true`.
+- Passphrase encryption defaults to 600,000 iterations and allows 100,000 to 10,000,000. It used
+  to default to 100,000, with a minimum of 10,000. Passphrases are now normalized to NFC.
+- A `CryptoKey` must now be AES-GCM with a length of 256 and allow `encrypt` or `decrypt`. That
+  applies to legacy labels too.
+- Field-level encryption (`fields`) throws for a field the specimen doesn't have. It used to skip
+  the field silently, leaving it in cleartext. Field values use the 1.3.0 shape (`kdf`, `salt`,
+  `iterations` instead of `cryptoVersion`).
+- The default `idMode` is now `'any'`. Pass `idMode: 'strict'` to keep the old CUID-style check.
+  This loosens validation, so if `validateSpecimen` gates untrusted input, decide which mode you
+  want.
+- `createSpecimen({ type: 'PRIMORDIA' })` now sets `stage: 'PRIMORDIA'` and warns through
+  `console.warn` unless you pass `onWarning`. `registerTypeAlias('PRIMORDIA', …)` with anything other
+  than `FRUITING` throws.
+- `isEncrypted` now narrows to `EncryptedSpecimen | EncryptedField`.
+- The encryption functions need a global WebCrypto, which means Node.js 20 or later.
 
 ## License
 

package/dist/cjs/compact-url.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Compact URL Format Functions
+ *
+ * This module provides functions to generate and parse compact URL format
+ * for WOLS specimens. The compact format is designed for small QR codes
+ * (petri dishes, culture tubes) where space is limited.
+ *
+ * Format: wemush://v1/{id}?s={species_code}&st={stage}&t={timestamp}
+ *
+ * @module compact-url
+ */
+import type { Specimen, ParseResult, SpecimenRef } from './types.js';
+/**
+ * Standard species codes from the WOLS specification
+ *
+ * @see https://github.com/wemush/open-standard for additional codes
+ */
+export declare const SPECIES_CODES: Record<string, string>;
+/**
+ * Get the full species name from a species code
+ *
+ * @param code - Species code (e.g., "POSTR")
+ * @returns Species name or undefined if code is unknown
+ *
+ * @example
+ * ```typescript
+ * getSpeciesFromCode('POSTR') // Returns "Pleurotus ostreatus"
+ * getSpeciesFromCode('XXXXX') // Returns undefined
+ * ```
+ */
+export declare function getSpeciesFromCode(code: string): string | undefined;
+/**
+ * Get the species code from a species name
+ *
+ * @param species - Full species name (e.g., "Pleurotus ostreatus")
+ * @returns Species code or undefined if species is not registered
+ *
+ * @example
+ * ```typescript
+ * getCodeFromSpecies('Pleurotus ostreatus') // Returns "POSTR"
+ * getCodeFromSpecies('Unknown species') // Returns undefined
+ * ```
+ */
+export declare function getCodeFromSpecies(species: string): string | undefined;
+/**
+ * Register a custom species code
+ *
+ * Use this to add species codes that are not in the standard WOLS list.
+ *
+ * @param code - Species code (uppercase, 5 characters recommended)
+ * @param species - Full species name
+ *
+ * @example
+ * ```typescript
+ * registerSpeciesCode('CCOMA', 'Coprinus comatus');
+ * getSpeciesFromCode('CCOMA') // Returns "Coprinus comatus"
+ * ```
+ */
+export declare function registerSpeciesCode(code: string, species: string): void;
+/**
+ * Generate a compact URL from a specimen
+ *
+ * The compact URL format is designed for small QR codes:
+ * ```
+ * wemush://v1/{id}?s={species_code}&st={stage}&t={timestamp}
+ * ```
+ *
+ * @param specimen - The specimen to encode
+ * @returns Compact URL string
+ *
+ * @example
+ * ```typescript
+ * const specimen = createSpecimen({
+ *   type: 'CULTURE',
+ *   species: 'Pleurotus ostreatus',
+ *   stage: 'COLONIZATION'
+ * });
+ *
+ * const url = toCompactUrl(specimen);
+ * // wemush://v1/clx1a2b3c4?s=POSTR&st=COLONIZATION&ty=CULTURE&t=1734307200
+ * ```
+ */
+export declare function toCompactUrl(specimen: Specimen): string;
+/**
+ * Parse a compact URL into a SpecimenRef
+ *
+ * Returns a reference object containing the minimal information
+ * encoded in the compact URL. Use the id to fetch full specimen
+ * data from the API if needed.
+ *
+ * @param url - Compact URL to parse (wemush://v1/...)
+ * @returns ParseResult with SpecimenRef on success, error on failure
+ *
+ * @example
+ * ```typescript
+ * const result = parseCompactUrl('wemush://v1/clx1a2b3c4?s=POSTR&st=COLONIZATION');
+ *
+ * if (result.success) {
+ *   console.log(result.data.species); // "Pleurotus ostreatus"
+ * }
+ * ```
+ */
+export declare function parseCompactUrl(url: string): ParseResult<SpecimenRef>;
+/**
+ * Parse a compact URL, throwing an error on failure.
+ *
+ * This is a convenience wrapper around parseCompactUrl() for cases
+ * where you prefer exceptions over result types.
+ *
+ * @param url - Compact URL to parse (wemush://v1/...)
+ * @returns SpecimenRef on success
+ * @throws WolsParseError on parse failure
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const ref = parseCompactUrlOrThrow('wemush://v1/clx1a2b3c4?s=POSTR');
+ *   console.log(ref.species); // "Pleurotus ostreatus"
+ * } catch (err) {
+ *   console.error('Failed to parse:', err.message);
+ * }
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function parseCompactUrlOrThrow(url: string): SpecimenRef;
+/**
+ * Parse a compact URL, returning null on failure.
+ *
+ * This is a convenience wrapper around parseCompactUrl() for cases
+ * where you want to handle failures with nullish coalescing.
+ *
+ * @param url - Compact URL to parse (wemush://v1/...)
+ * @returns SpecimenRef on success, null on failure
+ *
+ * @example
+ * ```typescript
+ * const ref = parseCompactUrlOrNull('wemush://v1/clx1a2b3c4?s=POSTR');
+ * if (ref !== null) {
+ *   console.log(ref.species);
+ * }
+ *
+ * // Or with nullish coalescing:
+ * const species = parseCompactUrlOrNull(url)?.species ?? 'Unknown';
+ * ```
+ *
+ * @since 1.2.0
+ */
+export declare function parseCompactUrlOrNull(url: string): SpecimenRef | null;
+//# sourceMappingURL=compact-url.d.ts.map

package/dist/cjs/compact-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact-url.d.ts","sourceRoot":"","sources":["../../src/compact-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAA6B,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAWhD,CAAC;AAYF;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEtE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CASvE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAsDvD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC,WAAW,CAAC,CA6GrE;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAM/D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAOrE"}