WOLS v1.2.0 brings flexible ID validation, type aliases, expanded growth stages, and migration utilities—all driven by production integration feedback from the WeMush platform.
WOLS v1.1 adds clonal generation tracking to monitor culture health over transfers, adopts JSON-LD for interoperability with agricultural data systems, and ships production-ready Python and TypeScript libraries. The spec is CC 4.0. The tooling is Apache 2.0. Both are free forever.
Today, I'm releasing something I've been building for two years: the WeMush Open Labeling Standard and the platform that uses it. Here's why it exists and what it means for the future of mycology.
Today we're releasing WOLS v1.4.0. Where v1.2.0 was about making the standard easier to integrate, v1.3.0 and v1.4.0 are about making implementations agree with each other, and making labels you can trust. The headlines: encrypted labels have one fully specified format, labels can now carry an Ed25519 signature, and the TypeScript and Python libraries pass the same conformance vectors and decrypt each other's labels in CI.
v1.3.0 went out on November 15 without its own announcement, and v1.4.0 followed on November 17. This post covers both.
This release includes:
WOLS Specification v1.4.0, the open standard itself
@wemush/wols v1.4.0, the TypeScript/JavaScript library
wols v1.4.0, the Python library
Upgrading from 1.2? v1.3.0 brought breaking changes, especially for encrypted labels. Read Breaking Changes before you upgrade, and upgrade every scanner and reader before you print encrypted labels with the new version.
Upgrading from 1.3? 1.4.0 doesn't change the wire format. See Upgrading from 1.3.
What's WOLS?
New to WOLS? Expand for background.
WOLS (WeMush Open Labeling Standard) is an open specification for encoding specimen data in QR codes and digital labels for mushroom cultivation and research. It lets growers, researchers, and labs share specimen data in a standardized, interoperable format, regardless of which software they use.
The specification is open source under CC BY 4.0, and the official libraries are Apache 2.0.
The Story Behind v1.3.0 and v1.4.0
Integrating the WeMush Platform turned up places where WOLS implementations disagreed. We recorded them in the Interoperability Notes. The biggest gap was encryption. WOLS 1.2.0 named AES-256-GCM but never said how to derive a key, where the IV goes, or how to encode the bytes. Each library chose differently, so even with the same secret, neither could read the other's encrypted labels.
v1.3.0 closed that gap and several smaller ones, and added a way to check the result. It also left one thing open: the format reserved a place for a signature without saying how to make one. v1.4.0 fills that in.
What's New
1. A Fully Specified Encrypted Format (v1.3.0)
In plain terms: if you encrypt labels, any app that follows WOLS can read them with the right passphrase or key. Encryption hides the values on a label, but on its own it doesn't stop someone from changing the parts that stay visible. That's what signatures, below, are for. The implementer details follow.
e is the AES-256-GCM ciphertext with its authentication tag appended.
iv is a 12-byte random IV, carried in its own parameter.
kdf is either pbkdf2 (a key derived from a passphrase) or raw (a 32-byte key shared out of band).
salt and i carry a per-label random salt and the PBKDF2 iteration count when kdf=pbkdf2.
All binary values use base64url without padding.
Passphrases are normalized to Unicode NFC before derivation, so the same passphrase typed on different platforms produces the same key. Generators use at least 100,000 PBKDF2 iterations and default to 600,000. Decoders reject counts below 10,000 or above 10,000,000, and check that limit before deriving a key. A crafted label can therefore make a scanner do at most 10 million iterations of key derivation, whether in one URL or summed across a label's encrypted fields. That bound is still about 17 times the default, so run decryption off the main thread.
The ID suffix is percent-encoded in an encrypted URL. After decryption, the specimen's id must equal wemush: followed by the percent-decoded suffix. Field-level encryption, where individual fields inside an embedded label are encrypted, is specified too. Each encrypted value is bound to its label id and field name through AES-GCM additional authenticated data, so a value moved to another field or copied from another label fails to decrypt. The identifying fields (@context, @type, id, version, type, and species) can't be encrypted, and decoders cap the total iteration cost of a label.
Encryption keeps values secret and binds each one to its label and field.
It doesn't make the cleartext parts of a label tamper-evident. Someone can still change the visible fields, remove an encrypted field, or restore an older value of one. The ID, and which fields are encrypted, stay visible.
Anyone who can see a label can try passphrases against it offline, as often as they like. The iteration count only slows each guess down. Use a long random passphrase, or a random 32-byte key with kdf=raw.
A passphrase or key protects every label made with it, and printed labels can't be re-keyed. Share it only with the people who need it.
Labels made by one library decrypt in the other. Both libraries pass the same shared encryption and field-level encryption vectors. Beyond that, each library's CI encrypts labels and has the other library decrypt them, across a shared 51-case matrix (passphrase and raw-key URLs, and field-level encryption), in both directions. It runs against both the published release and the main branch of the other library.
2. Signed Labels (v1.4.0)
In plain terms: an issuer can now sign a label with a private key. Anyone holding the issuer's public key can check that the label came from that issuer and hasn't been changed since. That covers the visible fields too, which encryption alone doesn't protect.
Signatures work on embedded labels (in a top-level signature member) and on encrypted URLs (in a final sig parameter). Both hold a token of the form {kid}.{signature}, where the kid names the key that signed it, such as mushoh-2026.
How signing works, for implementers.
Algorithm: Ed25519 (RFC 8032, pure). Verifiers reject a signature whose S isn't less than the group order, so each signature has exactly one valid form.
What's signed: "WOLS-SIG-v1" LF form LF kid LF body. The form (embedded or encrypted-url) and the kid are both signed, so a signature can't be moved to another form or another kid.
Embedded labels are signed over the RFC 8785 (JCS) canonical form of the label as parsed, without its top-level signature. Whitespace and member order don't matter; every member, including ones a library doesn't recognize, is covered.
Encrypted URLs are signed over their exact bytes before &sig=, which must come last. Nothing is re-normalized.
Malformed input: label text that isn't an I-JSON object (duplicate member names, lone surrogates, NaN or overflowing numbers) is malformed for verification, signed or not, and signers refuse to sign it.
Compact URLs can't be signed in 1.4.0. Their parameters aren't normative yet, so there are no fixed bytes to sign.
A verifier looks the kid up only in a trust store that you supply: a map from kid to public key, built from sources you already trust. A public key, URL, or hint inside a label is ignored, because whoever edits a label controls all of it. Verification makes no network requests.
Issuers may publish their public keys at https://{issuer-host}/.well-known/wols-keys.json, and both libraries can build a trust store from that document. Choose the host yourself, not from a label. Entries for algorithms a library doesn't support are skipped, so issuers can add keys for future algorithms without breaking today's verifiers.
Five results
Verification never throws for a bad signature. It returns exactly one status:
Status
Meaning
valid
The key your trust store lists for the kid signed exactly these bytes
invalid
The kid is trusted, but the signature doesn't match: the label was changed, or signed by someone else
unknown-kid
The kid isn't in your trust store
unsigned
No signature. Anyone can strip one, so if you require signatures, treat this as a failure
malformed
The label or its signature breaks the format rules
Only valid means authenticated.
What a signature doesn't prove
Freshness. There is no timestamp or expiry. An older, validly signed label can be reprinted or swapped in, and it still verifies.
That the label belongs on this item. A valid label can be copied onto another bag.
That the content is true. The signer vouches for it, nothing more.
That the signer knew the plaintext of encrypted values. Signatures cover the ciphertext as printed. To authenticate the plaintext too, sign the embedded label first, then encrypt it.
Printed labels can't be re-signed or recalled. Rotate keys by issuing a new kid and keeping the old public key trusted while its labels are in circulation. If a key is compromised, remove its kid from every trust store; its labels then verify as unknown-kid.
Signing and verifying in code
TypeScript:
typescript
import { createTrustStore, getSigningPublicKey, serializeSpecimen, signSpecimen, verifySpecimen } from '@wemush/wols';
const seed = crypto.getRandomValues(new Uint8Array(32)); // keep this secret
const publicKey = await getSigningPublicKey(seed); // publish this under your kid
const signedLabel = await signSpecimen(serializeSpecimen(specimen), { privateKey: seed, kid: 'mushoh-2026' });
const trustStore = await createTrustStore({ 'mushoh-2026': { alg: 'Ed25519', publicKey } });
const result = await verifySpecimen(scannedText, trustStore); // label text or encrypted URL, as scanned
if (result.status === 'valid') console.log(`Signed by ${result.kid}`);
Python (pip install "wols[crypto]"):
python
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from wols.crypto import SignatureStatus, TrustedKey, sign_specimen, verify_specimen
private_key = Ed25519PrivateKey.generate() # keep it offline
public_key = private_key.public_key().public_bytes_raw()
signed_label = sign_specimen(specimen, private_key, "mushoh-2026")
trust_store = {"mushoh-2026": TrustedKey(public_key)}
result = verify_specimen(scanned_text, trust_store) # label text or URL, as scanned
if result.status is SignatureStatus.VALID:
print("signed by", result.kid)
Encrypted URLs are signed with signEncryptedUrl / sign_encrypted_url. Pass the label text or URL to the verifier exactly as scanned, and display the values from the label you verified. Decoding and decryption never verify signatures, and never fail because of one.
3. PRIMORDIA as a Type (v1.3.0)
The 1.2.0 specification said implementations must reject PRIMORDIA as a specimen type, while its own alias table mapped it to FRUITING. The libraries split on it. Now, PRIMORDIA supplied as a type resolves to FRUITING and sets stage to PRIMORDIA when no stage was given. Implementations emit a warning and never write PRIMORDIA as a type. The recommended form is still type: "FRUITING", stage: "PRIMORDIA".
4. transferDepth: Three Counters, Three Meanings (v1.3.0)
Labels have been using one number to mean different things. v1.3.0 added strain.transferDepth and spells out how the three counters differ:
generation is the filial (sexual) generation, such as P or F1. It changes only when a new strain is bred from spores or a cross, never on a transfer of the same genetics.
clonalGeneration counts culture-to-culture subcultures, such as agar to agar or agar to liquid culture. The original culture is 0. Expansion to grain or substrate doesn't increment it.
transferDepth counts every transfer from the original culture, of any kind.
Here's the specification's example: a grain spawn bag made from the third agar subculture of an F1 culture, with one grain-to-grain transfer.
That's three subcultures, culture to grain, and grain to grain. Systems that track a single per-transfer counter must now write it as transferDepth, not as generation.
generation is always a string. The Python library's 1.3.0 release wrote it as a number, so 1.4.0 decoders read a numeric generation as its decimal string, with a warning, instead of rejecting the label. Generators still write only strings.
5. Any Non-Empty ID Suffix (v1.3.0)
The specification already said implementations must accept any non-empty suffix after wemush:. The libraries now do so by default, so ULIDs, UUIDs, and other formats validate without extra options. Strict checks remain available as an opt-in. If you relied on the old default to reject malformed IDs, see Breaking Changes.
Conformance Vectors
The spec ships with conformance test vectors: shared, language-neutral test cases in plain JSON. They cover embedded label validation and ID formats, PRIMORDIA handling, generation tracking, the encrypted format, field-level encryption, and, new in 1.4.0, signatures: 112 cases for signing, verifying, and loading key sets. An independent verifier written against the specification text checks that the vectors match the spec.
Both reference libraries pass every vector. If you're building your own WOLS implementation, in any language, you can run the same vectors against it: vendor conformance/vectors/ (check it against SHA256SUMS), map each case's operation to your API, and compare the result with expected. The README describes the case format. Compact URL vectors aren't included yet.
Breaking Changes
Both libraries' version numbers follow the specification, so minor releases can contain breaking changes. If you pin ~1.2 or ~=1.2, read this before upgrading.
Upgrading from 1.2
Upgrade readers before writers. The 1.2.x libraries can't decrypt labels made by 1.3.0 or later. Upgrade every scanner and reader before you print encrypted labels with the new version.
Encrypted labels from 1.2.0. Because the 1.2.0 libraries chose different encrypted formats, the labels they produced aren't interchangeable. That includes embedded labels whose fields were encrypted with a 1.2.0 library. The new libraries never generate those formats. Each one can still read its own 1.2.0 format, but only when you turn on an explicit option, so a legacy label is never read by accident. Neither library can read the other's old format.
Python: decrypt_specimen(url, secret, allow_legacy=True), or decrypt_specimen_fields(..., allow_legacy=True) for encrypted fields
A legacy encrypted label has no kdf. Legacy labels are also weaker than new ones: they have no field binding, and TypeScript 1.2.0 labels share one fixed salt, which makes passphrase guessing cheaper. Turn the legacy option on only while you migrate: read each legacy label with the new version of the library that made it, then re-encrypt it. Both READMEs have a "Migrating from 1.2" section that walks through it.
Python keys. A str passed to encrypt_specimen or decrypt_specimen is a passphrase, not a base64 key. To use a raw key, pass RawKey(key) (new in 1.4.0, and it accepts base64 text) or the 32 key bytes. Otherwise your code keeps running, but it makes passphrase labels that a reader holding the raw key can't decrypt.
Looser ID validation by default. Both libraries now accept any non-empty ID suffix. To keep a format check, pass idMode: 'strict' (or 'ulid' / 'uuid') in TypeScript, or id_mode= in Python.
TypeScript runtime and API. WebCrypto is required, so use Node.js 20 or later, a browser, Deno, or Bun. decryptField now takes a third argument, { id, field }.
Unaffected: compact URLs, and embedded labels without encrypted fields.
Upgrading from 1.3
1.4.0 adds signing and verification and doesn't change the wire format. 1.3.0 labels decode the same way, and the 1.3.0 libraries read labels written by 1.4.0. Things that may affect callers:
New labels say "version": "1.4.0".@wemush/wols 1.3.0 accepts them silently. wols 1.3.0 reads them but reports an INVALID_VERSION warning from validate_specimen.
Migration helpers.migrate() on a 1.3.0 label now needs a registered 1.3.0 to 1.4.0 handler. Setting version is enough: registerMigration('1.3.0', '1.4.0', s => ({ ...s, version: '1.4.0' })) in TypeScript, or register_migration("1.3.0", "1.4.0", lambda d: {**d, "version": "1.4.0"}) in Python.
Numeric strain.generation now decodes as its decimal string with a warning, where 1.3.0 rejected the label (TypeScript) or kept the number (Python).
Legacy labels with a non-NFC passphrase. TypeScript 1.2.x labels made with a decomposed passphrase decrypt again with allowLegacy.
v1.3.0 was the first version to go through our new release process. Normative changes ship as release candidates first: 1.3.0 went through 1.3.0-rc.1 and 1.3.0-rc.2, and rc.2 picked up fixes from implementation feedback, including NFC passphrases, iteration limits, and field-level binding. v1.4.0 went through 1.4.0-rc.1. A 1.3.1-rc.1 clarification candidate was folded into 1.4.0 instead of getting its own release, so there is no 1.3.1.
We also adopted a wire-format compatibility rule: a final release must not break decoding of a label that an earlier final release allowed. Printed labels can't be recalled, so this rule holds even when we move quickly. The rule starts with 1.3.0. The 1.2.0 encrypted format was never fully specified, which is why reading it is optional and works only in the library that made it. While WOLS is young, it runs under a founding phase, described in GOVERNANCE.md, with decisions made in public pull requests and discussions.
Upgrade
Upgrade your readers and scanners first, then the systems that print encrypted or signed labels.
Compact URLs still differ between the two libraries, they can't be signed yet, and phone cameras don't open wemush:// links. Proposals for v1.5.0 include:
Compact URL and species code registries, so every implementation emits and reads the same parameters and codes, followed by compact URL conformance vectors and compact signing
An HTTPS resolver form equivalent to the compact URL, which native phone cameras can open
IoT sensor integration, advanced analytics, and supply chain features
v1.5.0 isn't scheduled yet, and its normative changes will ship as release candidates first. See the roadmap for the full list, and tell us what you need in GitHub Discussions.
Thank You
v1.3.0 closed the biggest gaps between implementations, and v1.4.0 lets you prove where a label came from. The conformance vectors and cross-library CI keep both libraries in step. If you build on WOLS, we want to hear how it goes.
Happy cultivating! 🍄
The WeMush Open Labeling Standard is licensed under CC BY 4.0 (specification) and Apache 2.0 (code). Built with 🍄 by cultivators, for cultivators.