@darkbio/crypto 0.17.3 → 0.19.1

package/dist/rand.d.ts

@@ -1,8 +1,9 @@
 /**
- * Generate cryptographically secure random bytes.
+ * Generates cryptographically secure random bytes.
  *
- * @param bytes - Number of random bytes to generate (max 64 MiB)
- * @returns A Uint8Array containing the random bytes
+ * @param bytes - Number of random bytes to generate, at most 64 MiB
+ * @returns A new array filled with random bytes
+ * @throws If `bytes` is not a whole number between 0 and 64 MiB
  */
 export declare function generate(bytes: number): Promise<Uint8Array>;
 //# sourceMappingURL=rand.d.ts.map

package/dist/rand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rand.d.ts","sourceRoot":"","sources":["../src/rand.ts"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAGjE"}
+{"version":3,"file":"rand.d.ts","sourceRoot":"","sources":["../src/rand.ts"],"names":[],"mappings":"AAwBA;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAGjE"}

package/dist/xdsa.d.ts

@@ -1,14 +1,24 @@
 import { Codec } from './cbor.js';
-/** Size of the secret key in bytes (64). */
+/**
+ * Size of the secret key seed in bytes, the 32-byte ML-DSA-65 seed followed by
+ * the 32-byte Ed25519 seed.
+ */
 export declare const SECRET_KEY_SIZE = 64;
-/** Size of the public key in bytes (1984). */
+/**
+ * Size of the public key in bytes, the 1952-byte ML-DSA-65 key followed by the
+ * 32-byte Ed25519 key.
+ */
 export declare const PUBLIC_KEY_SIZE = 1984;
-/** Size of a signature in bytes (3373). */
+/**
+ * Size of a signature in bytes, the 3309-byte ML-DSA-65 signature followed by
+ * the 64-byte Ed25519 signature.
+ */
 export declare const SIGNATURE_SIZE = 3373;
-/** Size of a fingerprint in bytes (32). */
+/** Size of a key fingerprint in bytes. */
 export declare const FINGERPRINT_SIZE = 32;
 /**
- * Get the size constants (requires WASM initialization).
+ * Returns the sizes in bytes as the Rust library defines them, the same values
+ * as the constants of this module.
  */
 export declare function sizes(): Promise<{
     secretKey: number;
@@ -16,12 +26,14 @@ export declare function sizes(): Promise<{
     signature: number;
     fingerprint: number;
 }>;
-/**
- * Fingerprint is a 32-byte unique identifier for an xDSA key.
- * Backed by an opaque WASM handle.
- */
+/** A 256-bit unique identifier for an xDSA key. */
 export declare class Fingerprint {
-    /** Creates a fingerprint from a 32-byte array. */
+    private constructor();
+    /**
+     * Creates a fingerprint from a 32-byte array.
+     *
+     * @throws If `bytes` is not 32 bytes long
+     */
     static fromBytes(bytes: Uint8Array): Promise<Fingerprint>;
     /** Converts a fingerprint into a 32-byte array. */
     toBytes(): Uint8Array;
@@ -30,74 +42,118 @@ export declare class Fingerprint {
     /** Reports whether another fingerprint is the same. */
     equals(other: Fingerprint): boolean;
 }
-/**
- * Signature is a 3373-byte xDSA signature.
- * Backed by an opaque WASM handle.
- */
+/** An xDSA signature, an ML-DSA-65 signature paired with an Ed25519 one. */
 export declare class Signature {
-    /** Creates a signature from a 3373-byte array. */
+    private constructor();
+    /**
+     * Creates a signature from a 3373-byte array. The halves are only checked
+     * when the signature is verified.
+     *
+     * @throws If `bytes` is not 3373 bytes long
+     */
     static fromBytes(bytes: Uint8Array): Promise<Signature>;
     /** Converts a signature into a 3373-byte array. */
     toBytes(): Uint8Array;
 }
 /**
- * PublicKey contains a composite ML-DSA-65 + Ed25519 public key for
+ * An xDSA public key, an ML-DSA-65 key paired with an Ed25519 key, for
  * verifying quantum resistant digital signatures.
- * Backed by an opaque WASM handle — key material stays in WASM memory.
  */
 export declare class PublicKey {
-    /** Creates a public key from a 1984-byte array. */
+    private constructor();
+    /**
+     * Creates a public key from a 1984-byte array.
+     *
+     * @throws If `bytes` is not 1984 bytes long or not a valid composite key
+     */
     static fromBytes(bytes: Uint8Array): Promise<PublicKey>;
-    /** Parses a PEM string into a public key. */
+    /**
+     * Parses a PEM string into a public key. The input must be exactly one
+     * `PUBLIC KEY` block, with no leading whitespace, strict base64 and LF or
+     * CRLF line endings throughout.
+     *
+     * @throws If the PEM is malformed or holds another kind of key
+     */
     static fromPem(pem: string): Promise<PublicKey>;
     /** Converts a public key into a 1984-byte array. */
     toBytes(): Uint8Array;
-    /** Serializes a public key into a PEM string. */
+    /** Serializes a public key into a `PUBLIC KEY` PEM block with LF line endings. */
     toPem(): string;
     /** Reports whether another public key is the same. */
     equals(other: PublicKey): boolean;
     /** Returns a 256-bit unique identifier for this key. */
     fingerprint(): Fingerprint;
     /**
-     * Verifies a digital signature of the message.
+     * Verifies a digital signature of the message. Both the ML-DSA-65 and the
+     * Ed25519 halves must verify.
      *
-     * @returns true if the signature is valid, false otherwise (never throws)
+     * @param message - The signed message
+     * @param signature - The signature to check
+     * @returns True if the signature is valid for this key and message, false
+     *   otherwise
      */
     verify(message: Uint8Array, signature: Signature): boolean;
 }
 /**
- * SecretKey contains a composite ML-DSA-65 + Ed25519 private key for
- * creating quantum resistant digital signatures.
- * Backed by an opaque WASM handle — key material stays in WASM memory.
+ * An xDSA secret key, an ML-DSA-65 key paired with an Ed25519 key, for
+ * creating quantum resistant digital signatures. The key stays in WASM memory
+ * unless {@link SecretKey.toBytes} or {@link SecretKey.toPem} copies it out.
  */
 export declare class SecretKey {
-    /** Creates a new, random private key. */
+    private inner;
+    private constructor();
+    /** Generates a new, random secret key. */
     static generate(): Promise<SecretKey>;
-    /** Creates a private key from a 64-byte seed. */
+    /**
+     * Creates a secret key from a 64-byte seed.
+     *
+     * @throws If `bytes` is not 64 bytes long
+     */
     static fromBytes(bytes: Uint8Array): Promise<SecretKey>;
-    /** Parses a PEM string into a private key. */
+    /**
+     * Parses a PEM string into a secret key. The input must be exactly one
+     * `PRIVATE KEY` block, with no leading whitespace, strict base64 and LF or
+     * CRLF line endings throughout.
+     *
+     * @throws If the PEM is malformed or holds another kind of key
+     */
     static fromPem(pem: string): Promise<SecretKey>;
-    /** Converts a secret key into a 64-byte array. */
+    /** Converts a secret key into its 64-byte seed. */
     toBytes(): Uint8Array;
-    /** Serializes a private key into a PEM string. */
+    /** Serializes a secret key into a `PRIVATE KEY` PEM block with LF line endings. */
     toPem(): string;
     /** Retrieves the public counterpart of the secret key. */
     publicKey(): PublicKey;
-    /** Returns a 256-bit unique identifier for this key. */
+    /** Returns a 256-bit unique identifier for this key, the same as its public key's. */
     fingerprint(): Fingerprint;
-    /** Creates a digital signature of the message. */
+    /**
+     * Creates a digital signature of the message.
+     *
+     * @param message - The message to sign
+     * @returns The signature
+     */
     sign(message: Uint8Array): Signature;
+    /**
+     * Wipes the secret key held in WASM memory. Every later use of this key
+     * throws, and disposing it again does nothing. Copies already exported, such
+     * as by {@link SecretKey.toBytes}, are not affected. Without a dispose, the
+     * key is only wiped if the garbage collector finalizes it, which is not
+     * guaranteed.
+     */
+    dispose(): void;
 }
-/** The COSE algorithm identifier of the key type. */
+/** Private COSE algorithm identifier of composite ML-DSA-65 + Ed25519 signatures. */
 export declare const ALGORITHM_ID = -70000;
 /**
- * Codec of a public key as its bytes. Only the CBOR type is checked here, the
- * size and the key material are the Rust key's call.
+ * Codec of a public key as its 1984 bytes. Decoding throws a
+ * {@link CodecError} unless the bytes are a valid key. Calling its decode
+ * directly needs any async function of this package to have run first.
  */
 export declare const publicKey: Codec<PublicKey>;
 /**
- * Codec of a fingerprint as its bytes. Only the CBOR type is checked here,
- * the size is the Rust fingerprint's call.
+ * Codec of a fingerprint as its 32 bytes. Decoding throws a {@link CodecError}
+ * unless the value is 32 bytes. Calling its decode directly needs any async
+ * function of this package to have run first.
  */
 export declare const fingerprint: Codec<Fingerprint>;
 //# sourceMappingURL=xdsa.d.ts.map

package/dist/xdsa.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xdsa.d.ts","sourceRoot":"","sources":["../src/xdsa.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAqB,KAAK,KAAK,EAAE,MAAM,WAAW,CAAC;AAG1D,4CAA4C;AAC5C,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC,8CAA8C;AAC9C,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC,2CAA2C;AAC3C,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC,2CAA2C;AAC3C,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC;;GAEG;AACH,wBAAsB,KAAK,IAAI,OAAO,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CAQD;AAED;;;GAGG;AACH,qBAAa,WAAW;IAStB,kDAAkD;WACrC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAK/D,mDAAmD;IACnD,OAAO,IAAI,UAAU;IAIrB,8CAA8C;IAC9C,KAAK,IAAI,MAAM;IAIf,uDAAuD;IACvD,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;CAGpC;AAED;;;GAGG;AACH,qBAAa,SAAS;IASpB,kDAAkD;WACrC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IAK7D,mDAAmD;IACnD,OAAO,IAAI,UAAU;CAGtB;AAED;;;;GAIG;AACH,qBAAa,SAAS;IASpB,mDAAmD;WACtC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IAK7D,6CAA6C;WAChC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAKrD,oDAAoD;IACpD,OAAO,IAAI,UAAU;IAIrB,iDAAiD;IACjD,KAAK,IAAI,MAAM;IAIf,sDAAsD;IACtD,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;IAIjC,wDAAwD;IACxD,WAAW,IAAI,WAAW;IAI1B;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO;CAG3D;AAED;;;;GAIG;AACH,qBAAa,SAAS;IASpB,yCAAyC;WAC5B,QAAQ,IAAI,OAAO,CAAC,SAAS,CAAC;IAK3C,iDAAiD;WACpC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IAK7D,8CAA8C;WACjC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAKrD,kDAAkD;IAClD,OAAO,IAAI,UAAU;IAIrB,kDAAkD;IAClD,KAAK,IAAI,MAAM;IAIf,0DAA0D;IAC1D,SAAS,IAAI,SAAS;IAItB,wDAAwD;IACxD,WAAW,IAAI,WAAW;IAI1B,kDAAkD;IAClD,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS;CAGrC;AAED,qDAAqD;AACrD,eAAO,MAAM,YAAY,SAAS,CAAC;AAEnC;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,SAAS,CAoBtC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,WAAW,CAoB1C,CAAC"}
+{"version":3,"file":"xdsa.d.ts","sourceRoot":"","sources":["../src/xdsa.ts"],"names":[],"mappings":"AA6CA,OAAO,EAAqB,KAAK,KAAK,EAAE,MAAM,WAAW,CAAC;AAG1D;;;GAGG;AACH,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC;;;GAGG;AACH,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC,0CAA0C;AAC1C,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC;;;GAGG;AACH,wBAAsB,KAAK,IAAI,OAAO,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CAQD;AAED,mDAAmD;AACnD,qBAAa,WAAW;IAItB,OAAO;IASP;;;;OAIG;WACU,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAK/D,mDAAmD;IACnD,OAAO,IAAI,UAAU;IAIrB,8CAA8C;IAC9C,KAAK,IAAI,MAAM;IAIf,uDAAuD;IACvD,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;CAGpC;AAED,4EAA4E;AAC5E,qBAAa,SAAS;IAIpB,OAAO;IASP;;;;;OAKG;WACU,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IAK7D,mDAAmD;IACnD,OAAO,IAAI,UAAU;CAGtB;AAED;;;GAGG;AACH,qBAAa,SAAS;IAIpB,OAAO;IASP;;;;OAIG;WACU,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IAK7D;;;;;;OAMG;WACU,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAKrD,oDAAoD;IACpD,OAAO,IAAI,UAAU;IAIrB,kFAAkF;IAClF,KAAK,IAAI,MAAM;IAIf,sDAAsD;IACtD,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;IAIjC,wDAAwD;IACxD,WAAW,IAAI,WAAW;IAI1B;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO;CAG3D;AAED;;;;GAIG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAA4B;IAEzC,OAAO;IAYP,0CAA0C;WAC7B,QAAQ,IAAI,OAAO,CAAC,SAAS,CAAC;IAK3C;;;;OAIG;WACU,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IAK7D;;;;;;OAMG;WACU,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAKrD,mDAAmD;IACnD,OAAO,IAAI,UAAU;IAIrB,mFAAmF;IACnF,KAAK,IAAI,MAAM;IAIf,0DAA0D;IAC1D,SAAS,IAAI,SAAS;IAItB,sFAAsF;IACtF,WAAW,IAAI,WAAW;IAI1B;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS;IAIpC;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;CAKhB;AAED,qFAAqF;AACrF,eAAO,MAAM,YAAY,SAAS,CAAC;AAEnC;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,SAAS,CAoBtC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,WAAW,CAoB1C,CAAC"}

package/dist/xhpke.d.ts

@@ -1,14 +1,18 @@
 import { Codec } from './cbor.js';
-/** Size of the secret key seed in bytes (32). */
+/** Size of the secret key seed in bytes. */
 export declare const SECRET_KEY_SIZE = 32;
-/** Size of the public key in bytes (1216). */
+/** Size of the public key in bytes. */
 export declare const PUBLIC_KEY_SIZE = 1216;
-/** Size of the encapsulated key in bytes (1120). */
+/**
+ * Size of the encapsulated key in bytes, the prefix of every
+ * {@link PublicKey.seal} output.
+ */
 export declare const ENCAP_KEY_SIZE = 1120;
-/** Size of a fingerprint in bytes (32). */
+/** Size of a key fingerprint in bytes. */
 export declare const FINGERPRINT_SIZE = 32;
 /**
- * Get the size constants (requires WASM initialization).
+ * Returns the sizes in bytes as the Rust library defines them, the same values
+ * as the constants of this module.
  */
 export declare function sizes(): Promise<{
     secretKey: number;
@@ -16,12 +20,14 @@ export declare function sizes(): Promise<{
     encapKey: number;
     fingerprint: number;
 }>;
-/**
- * Fingerprint is a 32-byte unique identifier for an xHPKE key.
- * Backed by an opaque WASM handle.
- */
+/** A 256-bit unique identifier for an xHPKE key. */
 export declare class Fingerprint {
-    /** Creates a fingerprint from a 32-byte array. */
+    private constructor();
+    /**
+     * Creates a fingerprint from a 32-byte array.
+     *
+     * @throws If `bytes` is not 32 bytes long
+     */
     static fromBytes(bytes: Uint8Array): Promise<Fingerprint>;
     /** Converts a fingerprint into a 32-byte array. */
     toBytes(): Uint8Array;
@@ -30,103 +36,203 @@ export declare class Fingerprint {
     /** Reports whether another fingerprint is the same. */
     equals(other: Fingerprint): boolean;
 }
-/**
- * PublicKey contains an X-Wing public key for hybrid post-quantum encryption.
- * Backed by an opaque WASM handle — key material stays in WASM memory.
- */
+/** An X-Wing public key for encrypting HPKE messages. */
 export declare class PublicKey {
-    /** Creates a public key from a 1216-byte array. */
+    private constructor();
+    /**
+     * Creates a public key from a 1216-byte array.
+     *
+     * @throws If `bytes` is not 1216 bytes long or not a valid X-Wing key
+     */
     static fromBytes(bytes: Uint8Array): Promise<PublicKey>;
-    /** Parses a PEM string into a public key. */
+    /**
+     * Parses a PEM string into a public key. The input must be exactly one
+     * `PUBLIC KEY` block, with no leading whitespace, strict base64 and LF or
+     * CRLF line endings throughout.
+     *
+     * @throws If the PEM is malformed or holds another kind of key
+     */
     static fromPem(pem: string): Promise<PublicKey>;
     /** Converts a public key into a 1216-byte array. */
     toBytes(): Uint8Array;
-    /** Serializes a public key into a PEM string. */
+    /** Serializes a public key into a `PUBLIC KEY` PEM block with LF line endings. */
     toPem(): string;
     /** Reports whether another public key is the same. */
     equals(other: PublicKey): boolean;
-    /** Returns a 256-bit unique identifier for this key (SHA256 of raw public key). */
+    /**
+     * Returns a 256-bit unique identifier for this key, the SHA-256 hash of the
+     * public key bytes.
+     */
     fingerprint(): Fingerprint;
     /**
      * Creates an HPKE sender context for multi-message encryption to this
-     * public key. Returns a stateful Sender and the 1120-byte encapsulated
-     * key that must be transmitted to the recipient.
+     * public key. Messages it seals must be opened in order by a
+     * {@link Receiver} created from the returned encapsulated key.
+     *
+     * HPKE runs in base mode, which does not authenticate the sender. The
+     * recipient cannot verify who created the context.
+     *
+     * @param domain - Application domain, fixed for every message of the context
+     * @returns The stateful sender and the 1120-byte encapsulated key, which
+     *   must be transmitted to the recipient
      */
     newSender(domain: Uint8Array): {
         sender: Sender;
         encapKey: Uint8Array;
     };
     /**
-     * Seal (encrypt) a message to this public key.
+     * Encrypts a message to this public key, also authenticating a second
+     * message that is not included in the output. Opening it with
+     * {@link SecretKey.open} needs the same second message and domain.
+     *
+     * HPKE runs in base mode, which does not authenticate the sender. The
+     * recipient cannot verify who sealed the message.
      *
      * @param msgToSeal - The message to encrypt
-     * @param msgToAuth - Additional data to authenticate (but not encrypt)
-     * @param domain - Application domain for context separation
-     * @returns Sealed data (encapsulated key + ciphertext)
+     * @param msgToAuth - The message to authenticate but not include
+     * @param domain - Application domain, which both sides must agree on
+     * @returns The 1120-byte encapsulated key followed by the ciphertext
      */
     seal(msgToSeal: Uint8Array, msgToAuth: Uint8Array, domain: Uint8Array): Uint8Array;
 }
 /**
- * SecretKey contains an X-Wing private key for hybrid post-quantum encryption.
- * Backed by an opaque WASM handle — key material stays in WASM memory.
+ * An X-Wing secret key for decrypting HPKE messages. The key stays in WASM
+ * memory unless {@link SecretKey.toBytes} or {@link SecretKey.toPem} copies it
+ * out.
  */
 export declare class SecretKey {
-    /** Creates a new, random private key. */
+    private inner;
+    private constructor();
+    /** Generates a new, random secret key. */
     static generate(): Promise<SecretKey>;
-    /** Creates a private key from a 32-byte seed. */
+    /**
+     * Creates a secret key from a 32-byte seed.
+     *
+     * @throws If `bytes` is not 32 bytes long
+     */
     static fromBytes(bytes: Uint8Array): Promise<SecretKey>;
-    /** Parses a PEM string into a private key. */
+    /**
+     * Parses a PEM string into a secret key. The input must be exactly one
+     * `PRIVATE KEY` block, with no leading whitespace, strict base64 and LF or
+     * CRLF line endings throughout.
+     *
+     * @throws If the PEM is malformed or holds another kind of key
+     */
     static fromPem(pem: string): Promise<SecretKey>;
-    /** Converts a private key into a 32-byte seed. */
+    /** Converts a secret key into its 32-byte seed. */
     toBytes(): Uint8Array;
-    /** Serializes a private key into a PEM string. */
+    /** Serializes a secret key into a `PRIVATE KEY` PEM block with LF line endings. */
     toPem(): string;
     /** Retrieves the public counterpart of the secret key. */
     publicKey(): PublicKey;
-    /** Returns a 256-bit unique identifier for this key (SHA256 of raw public key). */
+    /**
+     * Returns a 256-bit unique identifier for this key, the SHA-256 hash of the
+     * public key bytes.
+     */
     fingerprint(): Fingerprint;
     /**
-     * Creates an HPKE receiver context for multi-message decryption.
+     * Creates an HPKE receiver context for multi-message decryption. Messages
+     * must be opened in the order the {@link Sender} sealed them.
+     *
+     * HPKE runs in base mode, which does not authenticate the sender. The
+     * recipient cannot verify who created the context.
+     *
+     * @param encapKey - The 1120-byte encapsulated key from {@link PublicKey.newSender}
+     * @param domain - The same application domain the sender uses
+     * @returns The stateful receiver
+     * @throws If `encapKey` is not 1120 bytes long or is malformed
      */
     newReceiver(encapKey: Uint8Array, domain: Uint8Array): Receiver;
     /**
-     * Open (decrypt) a sealed message with this secret key.
+     * Decrypts a message sealed to this key and checks the second message it
+     * authenticates.
+     *
+     * HPKE runs in base mode, which does not authenticate the sender. The
+     * recipient cannot verify who sealed the message.
      *
-     * @param sealed - The sealed data from `seal()`
-     * @param msgToAuth - The same additional authenticated data used during sealing
+     * @param sealed - The 1120-byte encapsulated key followed by the
+     *   ciphertext, as {@link PublicKey.seal} returns them
+     * @param msgToAuth - The same second message used during sealing
      * @param domain - The same application domain used during sealing
      * @returns The decrypted message
+     * @throws If the data is malformed, sealed to another key or tampered with,
+     *   or `msgToAuth` or `domain` differ
      */
     open(sealed: Uint8Array, msgToAuth: Uint8Array, domain: Uint8Array): Uint8Array;
+    /**
+     * Wipes the secret key held in WASM memory. Every later use of this key
+     * throws, and disposing it again does nothing. Copies already exported, such
+     * as by {@link SecretKey.toBytes}, and receivers already created from it are
+     * not affected. Without a dispose, the key is only wiped if the garbage
+     * collector finalizes it, which is not guaranteed.
+     */
+    dispose(): void;
 }
 /**
- * Sender is a stateful HPKE encryption context for multi-message
- * communication. Created via `PublicKey.newSender()`.
+ * A stateful HPKE encryption context for multi-message communication, created
+ * by {@link PublicKey.newSender}. Each seal uses the next nonce in the
+ * sequence, so identical messages encrypt differently. The matching
+ * {@link Receiver} must open messages in the order they were sealed.
  */
 export declare class Sender {
-    private readonly inner;
-    /** Encrypts a message using the next nonce in the sequence. */
+    private inner;
+    private constructor();
+    private get wasm();
+    /**
+     * Encrypts a message using the next nonce in the sequence.
+     *
+     * @param msgToSeal - The message to encrypt
+     * @param msgToAuth - The message to authenticate but not include
+     * @returns The ciphertext
+     */
     seal(msgToSeal: Uint8Array, msgToAuth: Uint8Array): Uint8Array;
+    /**
+     * Wipes the keys of this context held in WASM memory. Every later use of the
+     * sender throws, and disposing it again does nothing. Without a dispose, the
+     * keys are only wiped if the garbage collector finalizes the sender, which is
+     * not guaranteed.
+     */
+    dispose(): void;
 }
 /**
- * Receiver is a stateful HPKE decryption context for multi-message
- * communication. Created via `SecretKey.newReceiver()`.
+ * A stateful HPKE decryption context for multi-message communication, created
+ * by {@link SecretKey.newReceiver}. Messages must be opened in the order the
+ * {@link Sender} sealed them.
  */
 export declare class Receiver {
-    private readonly inner;
-    /** Decrypts a message using the next nonce in the sequence. */
+    private inner;
+    private constructor();
+    private get wasm();
+    /**
+     * Decrypts a message using the next nonce in the sequence.
+     *
+     * @param msgToOpen - The ciphertext from {@link Sender.seal}
+     * @param msgToAuth - The same second message used during sealing
+     * @returns The decrypted message
+     * @throws If the message is out of order or was tampered with, or
+     *   `msgToAuth` differs
+     */
     open(msgToOpen: Uint8Array, msgToAuth: Uint8Array): Uint8Array;
+    /**
+     * Wipes the keys of this context held in WASM memory. Every later use of the
+     * receiver throws, and disposing it again does nothing. Without a dispose,
+     * the keys are only wiped if the garbage collector finalizes the receiver,
+     * which is not guaranteed.
+     */
+    dispose(): void;
 }
-/** The COSE algorithm identifier of the key type. */
+/** Private COSE algorithm identifier of X-Wing (ML-KEM-768 + X25519). */
 export declare const ALGORITHM_ID = -70001;
 /**
- * Codec of a public key as its bytes. Only the CBOR type is checked here, the
- * size and the key material are the Rust key's call.
+ * Codec of a public key as its 1216 bytes. Decoding throws a
+ * {@link CodecError} unless the bytes are a valid key. Calling its decode
+ * directly needs any async function of this package to have run first.
  */
 export declare const publicKey: Codec<PublicKey>;
 /**
- * Codec of a fingerprint as its bytes. Only the CBOR type is checked here,
- * the size is the Rust fingerprint's call.
+ * Codec of a fingerprint as its 32 bytes. Decoding throws a {@link CodecError}
+ * unless the value is 32 bytes. Calling its decode directly needs any async
+ * function of this package to have run first.
  */
 export declare const fingerprint: Codec<Fingerprint>;
 //# sourceMappingURL=xhpke.d.ts.map

package/dist/xhpke.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darkbio/crypto",
-  "version": "0.17.3",
+  "version": "0.19.1",
   "author": "Péter Szilágyi <peter@dark.bio>",
   "description": "Cryptography primitives and wrappers",
   "repository": {
@@ -21,11 +21,12 @@
     "dist"
   ],
   "scripts": {
-    "build:wasm": "wasm-pack build crates/wasm --target web --out-dir ../../src/wasm",
+    "build:wasm": "wasm-pack build crates/wasm --target web --out-dir ../../src/wasm -- --locked",
     "build:ts": "node node_modules/typescript/bin/tsc && vite build",
     "build": "npm run build:wasm && npm run build:ts",
     "test": "vitest",
     "test:browser": "vitest --browser.enabled --browser.name=chromium",
+    "test:types": "node node_modules/typescript/bin/tsc -p tests/types",
     "check": "node node_modules/typescript/bin/tsc --noEmit"
   },
   "dependencies": {
@@ -35,6 +36,7 @@
     "@typescript/typescript6": "^6.0.2",
     "@vitest/browser-playwright": "^5.0.0",
     "playwright": "^1.62.1",
+    "prettier": "^3.9.9",
     "typescript": "^7.0.2",
     "vite": "^8.2.2",
     "vite-plugin-dts": "^5.1.0",