@wemush/wols 0.1.0

package/dist/esm/compact-url.js

@@ -0,0 +1,264 @@
+/**
+ * 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 { WolsErrorCode, WolsParseError } from './errors.js';
+/**
+ * Standard species codes from the WOLS specification
+ *
+ * @see https://github.com/wemush/open-standard for additional codes
+ */
+export const SPECIES_CODES = {
+    POSTR: 'Pleurotus ostreatus',
+    PCITRI: 'Pleurotus citrinopileatus',
+    PDJAR: 'Pleurotus djamor',
+    PERYN: 'Pleurotus eryngii',
+    HERIN: 'Hericium erinaceus',
+    GLUCI: 'Ganoderma lucidum',
+    LPUDE: 'Laetiporus pudens',
+    LLENC: 'Lentinula edodes',
+    APOLY: 'Agrocybe polyphylla',
+    STRUG: 'Stropharia rugosoannulata',
+};
+/**
+ * Reverse lookup map: species name → code
+ */
+const SPECIES_TO_CODE = {};
+// Initialize reverse lookup
+for (const [code, species] of Object.entries(SPECIES_CODES)) {
+    SPECIES_TO_CODE[species] = code;
+}
+/**
+ * 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 function getSpeciesFromCode(code) {
+    return SPECIES_CODES[code];
+}
+/**
+ * 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 function getCodeFromSpecies(species) {
+    return SPECIES_TO_CODE[species];
+}
+/**
+ * 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 function registerSpeciesCode(code, species) {
+    // Remove old reverse lookup if code is being overwritten
+    const oldSpecies = SPECIES_CODES[code];
+    if (oldSpecies !== undefined) {
+        delete SPECIES_TO_CODE[oldSpecies];
+    }
+    SPECIES_CODES[code] = species;
+    SPECIES_TO_CODE[species] = code;
+}
+/**
+ * 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 function toCompactUrl(specimen) {
+    // Extract ID without prefix
+    const idWithoutPrefix = specimen.id.replace(/^wemush:/, '');
+    // Start building URL
+    let url = `wemush://v1/${idWithoutPrefix}`;
+    // Build query parameters
+    const params = new URLSearchParams();
+    // Species: use code if known, otherwise full name
+    const speciesCode = getCodeFromSpecies(specimen.species);
+    if (speciesCode !== undefined) {
+        params.set('s', speciesCode);
+    }
+    else {
+        params.set('s', specimen.species);
+    }
+    // Type
+    params.set('ty', specimen.type);
+    // Stage (if present)
+    if (specimen.stage !== undefined) {
+        params.set('st', specimen.stage);
+    }
+    // Timestamp: convert ISO date to Unix timestamp
+    if (specimen.created !== undefined) {
+        const timestamp = Math.floor(new Date(specimen.created).getTime() / 1000);
+        params.set('t', timestamp.toString());
+    }
+    // Optional: Batch
+    if (specimen.batch !== undefined) {
+        params.set('b', specimen.batch);
+    }
+    // Optional: Strain name
+    if (specimen.strain?.name !== undefined) {
+        params.set('sn', specimen.strain.name);
+    }
+    // Optional: Strain generation
+    if (specimen.strain?.generation !== undefined) {
+        params.set('sg', specimen.strain.generation);
+    }
+    // Append query string
+    const queryString = params.toString();
+    if (queryString) {
+        url += `?${queryString}`;
+    }
+    return url;
+}
+/**
+ * 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 function parseCompactUrl(url) {
+    // Validate URL scheme
+    if (!url.startsWith('wemush://')) {
+        return {
+            success: false,
+            error: new WolsParseError(WolsErrorCode.INVALID_URL, 'URL must start with wemush://', {
+                url,
+            }),
+        };
+    }
+    // Parse URL parts
+    const withoutScheme = url.slice('wemush://'.length);
+    const [pathPart, queryPart] = withoutScheme.split('?');
+    if (!pathPart) {
+        return {
+            success: false,
+            error: new WolsParseError(WolsErrorCode.INVALID_URL, 'Invalid compact URL format: missing path', { url }),
+        };
+    }
+    // Parse path: v1/{id}
+    const pathSegments = pathPart.split('/');
+    if (pathSegments.length < 2 || !pathSegments[1]) {
+        return {
+            success: false,
+            error: new WolsParseError(WolsErrorCode.INVALID_URL, 'Invalid compact URL format: missing specimen ID', { url }),
+        };
+    }
+    const version = pathSegments[0] === 'v1' ? '1.1.0' : '1.0.0';
+    const idWithoutPrefix = pathSegments[1];
+    // Parse query parameters
+    const params = new URLSearchParams(queryPart ?? '');
+    // Extract species (resolve code if known)
+    const speciesParam = params.get('s');
+    let species;
+    if (speciesParam !== null) {
+        const resolvedSpecies = getSpeciesFromCode(speciesParam);
+        species = resolvedSpecies ?? speciesParam;
+    }
+    else {
+        return {
+            success: false,
+            error: new WolsParseError(WolsErrorCode.INVALID_URL, 'Invalid compact URL format: missing species parameter', { url }),
+        };
+    }
+    // Build result object
+    const result = {
+        id: `wemush:${idWithoutPrefix}`,
+        species,
+        version,
+    };
+    // Extract type
+    const typeParam = params.get('ty');
+    if (typeParam !== null) {
+        result.type = typeParam;
+    }
+    // Extract stage
+    const stageParam = params.get('st');
+    if (stageParam !== null) {
+        result.stage = stageParam;
+    }
+    // Extract timestamp
+    const timestampParam = params.get('t');
+    if (timestampParam !== null) {
+        result.timestamp = parseInt(timestampParam, 10);
+    }
+    // Extract batch
+    const batchParam = params.get('b');
+    if (batchParam !== null) {
+        result.batch = batchParam;
+    }
+    // Extract strain info
+    const strainNameParam = params.get('sn');
+    const strainGenParam = params.get('sg');
+    if (strainNameParam !== null) {
+        result.strain = {
+            name: strainNameParam,
+        };
+        if (strainGenParam !== null) {
+            result.strain.generation = strainGenParam;
+        }
+    }
+    return {
+        success: true,
+        data: result,
+    };
+}
+//# sourceMappingURL=compact-url.js.map

package/dist/esm/compact-url.js.map

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

package/dist/esm/crypto/decrypt.js

@@ -0,0 +1,122 @@
+/**
+ * WOLS Decryption Module
+ *
+ * Provides AES-256-GCM decryption for encrypted specimens using Web Crypto API.
+ * Supports both password-based (PBKDF2) and raw CryptoKey decryption.
+ *
+ * @module crypto/decrypt
+ */
+import { WolsEncryptionError, WolsErrorCode } from '../errors.js';
+import { parseSpecimen } from '../parser.js';
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+/** Salt for PBKDF2 key derivation (must match encrypt.ts) */
+const PBKDF2_SALT = new TextEncoder().encode('@wemush/wols/crypto/v1');
+/** Number of PBKDF2 iterations (must match encrypt.ts) */
+const PBKDF2_ITERATIONS = 100_000;
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+/**
+ * Convert base64url string to ArrayBuffer
+ */
+function fromBase64Url(base64url) {
+    // Convert base64url to base64
+    const base64 = base64url
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+        .padEnd(base64url.length + ((4 - (base64url.length % 4)) % 4), '=');
+    // Decode base64 to binary string
+    const binaryString = atob(base64);
+    // Convert to ArrayBuffer
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes.buffer;
+}
+/**
+ * Derive a CryptoKey from a password using PBKDF2
+ */
+async function deriveKey(password) {
+    const encoder = new TextEncoder();
+    const passwordBytes = encoder.encode(password);
+    // Import password as key material
+    const keyMaterial = await crypto.subtle.importKey('raw', passwordBytes, 'PBKDF2', false, [
+        'deriveKey',
+    ]);
+    // Derive AES-256-GCM key
+    return crypto.subtle.deriveKey({
+        name: 'PBKDF2',
+        salt: PBKDF2_SALT,
+        iterations: PBKDF2_ITERATIONS,
+        hash: 'SHA-256',
+    }, keyMaterial, { name: 'AES-GCM', length: 256 }, false, ['decrypt']);
+}
+// =============================================================================
+// DECRYPTION FUNCTIONS
+// =============================================================================
+/**
+ * Decrypt an encrypted specimen using AES-256-GCM
+ *
+ * @param encrypted - The encrypted specimen wrapper
+ * @param options - Decryption options (key required)
+ * @returns Promise resolving to ParseResult with decrypted specimen or error
+ *
+ * @example
+ * ```typescript
+ * import { decryptSpecimen } from '@wemush/wols/crypto';
+ *
+ * const result = await decryptSpecimen(encrypted, {
+ *   key: 'my-secret-password',
+ * });
+ *
+ * if (result.success) {
+ *   console.log(result.data);
+ * } else {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+export async function decryptSpecimen(encrypted, options) {
+    const { key } = options;
+    // Validate encrypted specimen structure
+    if (!encrypted.payload) {
+        return {
+            success: false,
+            error: new WolsEncryptionError(WolsErrorCode.DECRYPTION_ERROR, 'Missing encrypted payload', {
+                path: ['payload'],
+            }),
+        };
+    }
+    if (!encrypted.iv) {
+        return {
+            success: false,
+            error: new WolsEncryptionError(WolsErrorCode.DECRYPTION_ERROR, 'Missing initialization vector (IV)', { path: ['iv'] }),
+        };
+    }
+    try {
+        // Get or derive the decryption key
+        const cryptoKey = typeof key === 'string' ? await deriveKey(key) : key;
+        // Decode payload and IV from base64url
+        const ciphertext = fromBase64Url(encrypted.payload);
+        const ivBuffer = fromBase64Url(encrypted.iv);
+        const iv = new Uint8Array(ivBuffer);
+        // Decrypt
+        const plaintext = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, cryptoKey, ciphertext);
+        // Decode plaintext to string
+        const json = new TextDecoder().decode(plaintext);
+        // Parse the decrypted JSON back into a specimen
+        return parseSpecimen(json);
+    }
+    catch (error) {
+        // Handle decryption errors (wrong key, tampered data, etc.)
+        const errorMessage = error instanceof Error ? error.message : 'Unknown decryption error';
+        return {
+            success: false,
+            error: new WolsEncryptionError(WolsErrorCode.DECRYPTION_ERROR, `Decryption failed: ${errorMessage}`),
+        };
+    }
+}
+//# sourceMappingURL=decrypt.js.map

package/dist/esm/crypto/decrypt.js.map

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

package/dist/esm/crypto/encrypt.js

@@ -0,0 +1,147 @@
+/**
+ * WOLS Encryption Module
+ *
+ * Provides AES-256-GCM encryption for specimens using Web Crypto API.
+ * Supports both password-based (PBKDF2) and raw CryptoKey encryption.
+ *
+ * @module crypto/encrypt
+ */
+import { serializeSpecimen } from '../specimen.js';
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+/** Salt for PBKDF2 key derivation (fixed for deterministic key from same password) */
+const PBKDF2_SALT = new TextEncoder().encode('@wemush/wols/crypto/v1');
+/** Number of PBKDF2 iterations */
+const PBKDF2_ITERATIONS = 100_000;
+/** IV length in bytes (96 bits = 12 bytes recommended for GCM) */
+const IV_LENGTH = 12;
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+/**
+ * Convert ArrayBuffer to base64url string
+ */
+function toBase64Url(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let binary = '';
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/**
+ * Derive a CryptoKey from a password using PBKDF2
+ */
+async function deriveKey(password) {
+    const encoder = new TextEncoder();
+    const passwordBytes = encoder.encode(password);
+    // Import password as key material
+    const keyMaterial = await crypto.subtle.importKey('raw', passwordBytes, 'PBKDF2', false, [
+        'deriveKey',
+    ]);
+    // Derive AES-256-GCM key
+    return crypto.subtle.deriveKey({
+        name: 'PBKDF2',
+        salt: PBKDF2_SALT,
+        iterations: PBKDF2_ITERATIONS,
+        hash: 'SHA-256',
+    }, keyMaterial, { name: 'AES-GCM', length: 256 }, false, ['encrypt']);
+}
+/**
+ * Generate a random initialization vector
+ */
+function generateIV() {
+    const buffer = new ArrayBuffer(IV_LENGTH);
+    const iv = new Uint8Array(buffer);
+    crypto.getRandomValues(iv);
+    return { iv, ivBuffer: buffer };
+}
+// =============================================================================
+// ENCRYPTION FUNCTIONS
+// =============================================================================
+/**
+ * Encrypt a specimen using AES-256-GCM
+ *
+ * @param specimen - The specimen to encrypt
+ * @param options - Encryption options (key required)
+ * @returns Promise resolving to encrypted specimen wrapper
+ *
+ * @example
+ * ```typescript
+ * import { encryptSpecimen } from '@wemush/wols/crypto';
+ *
+ * const encrypted = await encryptSpecimen(specimen, {
+ *   key: 'my-secret-password',
+ * });
+ * // Returns: { encrypted: true, payload: "...", iv: "...", algorithm: "AES-256-GCM" }
+ * ```
+ */
+export async function encryptSpecimen(specimen, options) {
+    const { key, fields } = options;
+    // If partial encryption requested, handle separately
+    if (fields !== undefined && fields.length > 0) {
+        return encryptPartial(specimen, options);
+    }
+    // Get or derive the encryption key
+    const cryptoKey = typeof key === 'string' ? await deriveKey(key) : key;
+    // Serialize the specimen to JSON
+    const plaintext = serializeSpecimen(specimen);
+    const plaintextBytes = new TextEncoder().encode(plaintext);
+    // Generate random IV
+    const { iv, ivBuffer } = generateIV();
+    // Encrypt
+    const ciphertext = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, cryptoKey, plaintextBytes);
+    // Return encrypted specimen
+    return {
+        encrypted: true,
+        payload: toBase64Url(ciphertext),
+        iv: toBase64Url(ivBuffer),
+        algorithm: 'AES-256-GCM',
+    };
+}
+/**
+ * Encrypt only specific fields of a specimen
+ *
+ * Returns a specimen-like object with specified fields encrypted.
+ */
+async function encryptPartial(specimen, options) {
+    const { key, fields = [] } = options;
+    // Get or derive the encryption key
+    const cryptoKey = typeof key === 'string' ? await deriveKey(key) : key;
+    // Clone the specimen
+    const result = { ...specimen };
+    // Encrypt each specified field
+    for (const field of fields) {
+        const value = result[field];
+        if (value !== undefined) {
+            const plaintext = JSON.stringify(value);
+            const plaintextBytes = new TextEncoder().encode(plaintext);
+            const { iv, ivBuffer } = generateIV();
+            const ciphertext = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, cryptoKey, plaintextBytes);
+            result[field] = {
+                encrypted: true,
+                payload: toBase64Url(ciphertext),
+                iv: toBase64Url(ivBuffer),
+                algorithm: 'AES-256-GCM',
+            };
+        }
+    }
+    // Cast to EncryptedSpecimen for return type consistency
+    // In partial mode, this is actually a hybrid object
+    return result;
+}
+/**
+ * Type guard to check if an object is an encrypted specimen
+ */
+export function isEncrypted(value) {
+    if (value === null || value === undefined) {
+        return false;
+    }
+    if (typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    return obj['encrypted'] === true;
+}
+//# sourceMappingURL=encrypt.js.map

package/dist/esm/crypto/encrypt.js.map

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

package/dist/esm/crypto/index.js

@@ -0,0 +1,10 @@
+/**
+ * WOLS Crypto Module
+ *
+ * Provides AES-256-GCM encryption and decryption for specimens.
+ *
+ * @module crypto
+ */
+export { encryptSpecimen, isEncrypted } from './encrypt.js';
+export { decryptSpecimen } from './decrypt.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","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"}