@wemush/wols 0.1.0 → 1.3.0

package/dist/cjs/compact-url.js

@@ -17,6 +17,8 @@ exports.getCodeFromSpecies = getCodeFromSpecies;
 exports.registerSpeciesCode = registerSpeciesCode;
 exports.toCompactUrl = toCompactUrl;
 exports.parseCompactUrl = parseCompactUrl;
+exports.parseCompactUrlOrThrow = parseCompactUrlOrThrow;
+exports.parseCompactUrlOrNull = parseCompactUrlOrNull;
 const errors_js_1 = require("./errors.js");
 /**
  * Standard species codes from the WOLS specification
@@ -269,4 +271,66 @@ function parseCompactUrl(url) {
         data: result,
     };
 }
+// =============================================================================
+// CONVENIENCE METHODS (v1.2.0)
+// =============================================================================
+/**
+ * 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
+ */
+function parseCompactUrlOrThrow(url) {
+    const result = parseCompactUrl(url);
+    if (!result.success) {
+        throw result.error;
+    }
+    return result.data;
+}
+/**
+ * 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
+ */
+function parseCompactUrlOrNull(url) {
+    // Guard against null/undefined/non-string input to prevent runtime errors
+    if (url === null || url === undefined || typeof url !== 'string') {
+        return null;
+    }
+    const result = parseCompactUrl(url);
+    return result.success ? result.data : null;
+}
 //# sourceMappingURL=compact-url.js.map

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

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

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

@@ -0,0 +1,110 @@
+/**
+ * WOLS Decryption Module (WOLS v1.3.0 encrypted format)
+ *
+ * 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 { 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 label to its exact plaintext (the embedded JSON-LD string).
+ *
+ * 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
+ * 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);
+ * ```
+ *
+ * @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.
+ *
+ * `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 decryptFields(value: FieldEncryptedSpecimen | Record<string, unknown>, options: DecryptionOptions): Promise<DecryptResult<Specimen>>;
+//# sourceMappingURL=decrypt.d.ts.map

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

@@ -0,0 +1 @@
+{"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"}