@wemush/wols 1.2.0 → 1.3.0

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"}