@brashkie/signalis-core 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -638,6 +638,113 @@ declare function constantTimeEq(a: Buffer, b: Buffer): boolean;
  * is fine and avoids a NAPI hop.
  */
 declare function nativeSecureRandom(size: number): Buffer;
+/**
+ * Base64 encoding (RFC 4648).
+ *
+ * Two variants are available:
+ * - **Standard** (`encode`/`decode`) — uses `A-Z a-z 0-9 + /` with `=` padding.
+ *   Suitable for MIME, email, and general payloads.
+ * - **URL-safe** (`encodeUrlSafe`/`decodeUrlSafe`) — uses `-` and `_` instead
+ *   of `+` and `/`, and omits padding. Safe for URLs, filenames, HTTP headers.
+ *
+ * @example
+ * ```ts
+ * const encoded = Base64.encode(Buffer.from('hello'));      // "aGVsbG8="
+ * const decoded = Base64.decode(encoded);                    // <Buffer 68 65 6c 6c 6f>
+ * const url = Base64.encodeUrlSafe(Buffer.from('hello'));    // "aGVsbG8" (no padding)
+ * ```
+ */
+declare const Base64: Readonly<{
+    /**
+     * Encode bytes to standard Base64 (with `=` padding).
+     */
+    encode(input: Buffer): string;
+    /**
+     * Decode a standard Base64 string back to bytes.
+     *
+     * @throws {RangeError} on invalid characters, wrong length, or invalid padding.
+     */
+    decode(input: string): Buffer;
+    /**
+     * Encode bytes to URL-safe Base64 without padding.
+     * Uses `-` and `_` instead of `+` and `/`.
+     */
+    encodeUrlSafe(input: Buffer): string;
+    /**
+     * Decode a URL-safe Base64 string (no padding) back to bytes.
+     *
+     * @throws {RangeError} on invalid characters or wrong length.
+     */
+    decodeUrlSafe(input: string): Buffer;
+}>;
+/**
+ * Hex (Base16) encoding.
+ *
+ * - Encoding produces lowercase output by default.
+ * - Decoding is case-insensitive.
+ *
+ * @example
+ * ```ts
+ * const encoded = Hex.encode(Buffer.from([0xde, 0xad, 0xbe, 0xef]));  // "deadbeef"
+ * const decoded = Hex.decode('DEADBEEF');                              // <Buffer de ad be ef>
+ * Hex.isValid('deadbeef');   // true
+ * Hex.isValid('nope!');      // false
+ * ```
+ */
+declare const Hex: Readonly<{
+    /**
+     * Encode bytes to a lowercase hex string.
+     */
+    encode(input: Buffer): string;
+    /**
+     * Encode bytes to an uppercase hex string.
+     * (Rare, but included for legacy protocols.)
+     */
+    encodeUpper(input: Buffer): string;
+    /**
+     * Decode a hex string to bytes. Case-insensitive.
+     *
+     * @throws {RangeError} on odd-length input or non-hex characters.
+     */
+    decode(input: string): Buffer;
+    /**
+     * Cheap validation: is this a well-formed hex string?
+     */
+    isValid(input: string): boolean;
+}>;
+/**
+ * UTF-8 encoding with strict validation.
+ *
+ * - `encode` converts a string to its UTF-8 byte representation.
+ * - `decode` validates strictly — invalid UTF-8 throws (does NOT silently
+ *   replace with U+FFFD like `Buffer.toString('utf-8')` does).
+ * - `isValid` is a cheap check without allocation.
+ *
+ * @example
+ * ```ts
+ * const bytes = Utf8.encode('Hola 🦀');     // <Buffer 48 6f 6c 61 20 f0 9f a6 80>
+ * const text = Utf8.decode(bytes);           // "Hola 🦀"
+ * Utf8.isValid(Buffer.from([0xff]));         // false
+ * ```
+ */
+declare const Utf8: Readonly<{
+    /**
+     * Encode a string to its UTF-8 byte representation.
+     */
+    encode(input: string): Buffer;
+    /**
+     * Decode UTF-8 bytes to a string.
+     *
+     * @throws {RangeError} on invalid UTF-8 (truncated multi-byte, lone surrogate,
+     *   invalid start byte, etc.). Unlike `Buffer.toString('utf-8')`, this does
+     *   NOT silently substitute U+FFFD.
+     */
+    decode(input: Buffer): string;
+    /**
+     * Check whether the given bytes are valid UTF-8.
+     */
+    isValid(input: Buffer): boolean;
+}>;
 
 /**
  * Typed error classes for signalis-core.
@@ -938,7 +1045,7 @@ declare const AES_GCM_RECOMMENDED_MESSAGES_PER_KEY = 4294967296;
  *
  * Bumped on every release.
  */
-declare const VERSION: "0.2.0";
+declare const VERSION: "0.4.0";
 
 /**
  * Default export — provides all primitives and helpers under one namespace.
@@ -949,6 +1056,7 @@ declare const VERSION: "0.2.0";
  *
  * const kp = sc.Curve25519.generateKeyPair();
  * const nonce = sc.secureRandom(12);
+ * const b64 = sc.Base64.encode(nonce);
  * ```
  */
 declare const SignalisCore: Readonly<{
@@ -1005,6 +1113,15 @@ declare const SignalisCore: Readonly<{
         KEY_SIZE: 32;
         IV_SIZE: 16;
     }>;
+    ChaCha20Poly1305: Readonly<{
+        encrypt(key: Buffer, nonce: Buffer, plaintext: Buffer): Buffer;
+        decrypt(key: Buffer, nonce: Buffer, ciphertext: Buffer): Buffer;
+        encryptWithAad(key: Buffer, nonce: Buffer, plaintext: Buffer, aad: Buffer): Buffer;
+        decryptWithAad(key: Buffer, nonce: Buffer, ciphertext: Buffer, aad: Buffer): Buffer;
+        KEY_SIZE: 32;
+        NONCE_SIZE: 12;
+        TAG_SIZE: 16;
+    }>;
     HMAC: Readonly<{
         sha256(key: Buffer, data: Buffer): Buffer;
         verifySha256(key: Buffer, data: Buffer, expectedTag: Buffer): boolean;
@@ -1016,6 +1133,7 @@ declare const SignalisCore: Readonly<{
         OUTPUT_SIZE: 32;
     }>;
     secureRandom: typeof secureRandom;
+    nativeSecureRandom: typeof nativeSecureRandom;
     randomNonce: typeof randomNonce;
     randomIv: typeof randomIv;
     randomKey: typeof randomKey;
@@ -1023,9 +1141,27 @@ declare const SignalisCore: Readonly<{
     fromHex: typeof fromHex;
     toBase64: typeof toBase64;
     fromBase64: typeof fromBase64;
+    Base64: Readonly<{
+        encode(input: Buffer): string;
+        decode(input: string): Buffer;
+        encodeUrlSafe(input: Buffer): string;
+        decodeUrlSafe(input: string): Buffer;
+    }>;
+    Hex: Readonly<{
+        encode(input: Buffer): string;
+        encodeUpper(input: Buffer): string;
+        decode(input: string): Buffer;
+        isValid(input: string): boolean;
+    }>;
+    Utf8: Readonly<{
+        encode(input: string): Buffer;
+        decode(input: Buffer): string;
+        isValid(input: Buffer): boolean;
+    }>;
     constantTimeEqual: typeof constantTimeEqual;
-    VERSION: "0.2.0";
+    constantTimeEq: typeof constantTimeEq;
+    VERSION: "0.4.0";
     nativeVersion: string;
 }>;
 
-export { AES_256_CBC_IV_SIZE, AES_256_GCM_NONCE_SIZE, AES_256_GCM_TAG_SIZE, AES_256_KEY_SIZE, AES_BLOCK_SIZE, AES_CBC, AES_GCM, AES_GCM_MAX_PLAINTEXT_SIZE, AES_GCM_RECOMMENDED_MESSAGES_PER_KEY, type AesCbcParams, type AesGcmParams, AuthenticationError, CHACHA20_POLY1305_KEY_SIZE, CHACHA20_POLY1305_NONCE_SIZE, CHACHA20_POLY1305_TAG_SIZE, CURVE25519_PRIVATE_KEY_SIZE, CURVE25519_PUBLIC_KEY_SIZE, CURVE25519_SHARED_SECRET_SIZE, ChaCha20Poly1305, CryptoError, Curve25519, ED25519_PRIVATE_KEY_SIZE, ED25519_PUBLIC_KEY_SIZE, ED25519_SEED_SIZE, ED25519_SIGNATURE_SIZE, Ed25519, type Encoding, HKDF, HKDF_MAX_OUTPUT_SIZE, HKDF_PRK_SIZE, HMAC, HMAC_SHA256_TAG_SIZE, type HkdfParams, KeyDerivationError, type KeyPair, LengthError, type PrivateKey, type PseudoRandomKey, type PublicKey, SHA256, SHA256_BLOCK_SIZE, SHA256_OUTPUT_SIZE, type SharedSecret, SignalisError, type Signature, SignatureError, VERSION, ValidationError, XED25519_PRIVATE_KEY_SIZE, XED25519_PUBLIC_KEY_SIZE, XED25519_RANDOM_SIZE, XED25519_SIGNATURE_SIZE, XEd25519, asPrivateKey, asPublicKey, asSharedSecret, asSignature, assertBuffer, assertBufferLength, assertBufferOfSize, assertHkdfLength, assertPositiveInteger, bufferToString, buffersSameLength, concat, constantTimeEq, constantTimeEqual, SignalisCore as default, fromBase64, fromBase64Url, fromHex, nativeSecureRandom, nativeVersion, randomIv, randomKey, randomNonce, secureRandom, stringToBuffer, toBase64, toBase64Url, toHex, xor, zeroize };
+export { AES_256_CBC_IV_SIZE, AES_256_GCM_NONCE_SIZE, AES_256_GCM_TAG_SIZE, AES_256_KEY_SIZE, AES_BLOCK_SIZE, AES_CBC, AES_GCM, AES_GCM_MAX_PLAINTEXT_SIZE, AES_GCM_RECOMMENDED_MESSAGES_PER_KEY, type AesCbcParams, type AesGcmParams, AuthenticationError, Base64, CHACHA20_POLY1305_KEY_SIZE, CHACHA20_POLY1305_NONCE_SIZE, CHACHA20_POLY1305_TAG_SIZE, CURVE25519_PRIVATE_KEY_SIZE, CURVE25519_PUBLIC_KEY_SIZE, CURVE25519_SHARED_SECRET_SIZE, ChaCha20Poly1305, CryptoError, Curve25519, ED25519_PRIVATE_KEY_SIZE, ED25519_PUBLIC_KEY_SIZE, ED25519_SEED_SIZE, ED25519_SIGNATURE_SIZE, Ed25519, type Encoding, HKDF, HKDF_MAX_OUTPUT_SIZE, HKDF_PRK_SIZE, HMAC, HMAC_SHA256_TAG_SIZE, Hex, type HkdfParams, KeyDerivationError, type KeyPair, LengthError, type PrivateKey, type PseudoRandomKey, type PublicKey, SHA256, SHA256_BLOCK_SIZE, SHA256_OUTPUT_SIZE, type SharedSecret, SignalisError, type Signature, SignatureError, Utf8, VERSION, ValidationError, XED25519_PRIVATE_KEY_SIZE, XED25519_PUBLIC_KEY_SIZE, XED25519_RANDOM_SIZE, XED25519_SIGNATURE_SIZE, XEd25519, asPrivateKey, asPublicKey, asSharedSecret, asSignature, assertBuffer, assertBufferLength, assertBufferOfSize, assertHkdfLength, assertPositiveInteger, bufferToString, buffersSameLength, concat, constantTimeEq, constantTimeEqual, SignalisCore as default, fromBase64, fromBase64Url, fromHex, nativeSecureRandom, nativeVersion, randomIv, randomKey, randomNonce, secureRandom, stringToBuffer, toBase64, toBase64Url, toHex, xor, zeroize };

package/dist/index.mjs

@@ -725,6 +725,123 @@ function nativeSecureRandom(size) {
   }
   return native.secureRandom(size);
 }
+var Base64 = Object.freeze({
+  /**
+   * Encode bytes to standard Base64 (with `=` padding).
+   */
+  encode(input) {
+    if (!Buffer.isBuffer(input)) {
+      throw new TypeError("Base64.encode: input must be a Buffer");
+    }
+    return native.base64Encode(input);
+  },
+  /**
+   * Decode a standard Base64 string back to bytes.
+   *
+   * @throws {RangeError} on invalid characters, wrong length, or invalid padding.
+   */
+  decode(input) {
+    if (typeof input !== "string") {
+      throw new TypeError("Base64.decode: input must be a string");
+    }
+    return native.base64Decode(input);
+  },
+  /**
+   * Encode bytes to URL-safe Base64 without padding.
+   * Uses `-` and `_` instead of `+` and `/`.
+   */
+  encodeUrlSafe(input) {
+    if (!Buffer.isBuffer(input)) {
+      throw new TypeError("Base64.encodeUrlSafe: input must be a Buffer");
+    }
+    return native.base64EncodeUrlSafe(input);
+  },
+  /**
+   * Decode a URL-safe Base64 string (no padding) back to bytes.
+   *
+   * @throws {RangeError} on invalid characters or wrong length.
+   */
+  decodeUrlSafe(input) {
+    if (typeof input !== "string") {
+      throw new TypeError("Base64.decodeUrlSafe: input must be a string");
+    }
+    return native.base64DecodeUrlSafe(input);
+  }
+});
+var Hex = Object.freeze({
+  /**
+   * Encode bytes to a lowercase hex string.
+   */
+  encode(input) {
+    if (!Buffer.isBuffer(input)) {
+      throw new TypeError("Hex.encode: input must be a Buffer");
+    }
+    return native.hexEncode(input);
+  },
+  /**
+   * Encode bytes to an uppercase hex string.
+   * (Rare, but included for legacy protocols.)
+   */
+  encodeUpper(input) {
+    if (!Buffer.isBuffer(input)) {
+      throw new TypeError("Hex.encodeUpper: input must be a Buffer");
+    }
+    return native.hexEncodeUpper(input);
+  },
+  /**
+   * Decode a hex string to bytes. Case-insensitive.
+   *
+   * @throws {RangeError} on odd-length input or non-hex characters.
+   */
+  decode(input) {
+    if (typeof input !== "string") {
+      throw new TypeError("Hex.decode: input must be a string");
+    }
+    return native.hexDecode(input);
+  },
+  /**
+   * Cheap validation: is this a well-formed hex string?
+   */
+  isValid(input) {
+    if (typeof input !== "string") {
+      throw new TypeError("Hex.isValid: input must be a string");
+    }
+    return native.hexIsValid(input);
+  }
+});
+var Utf8 = Object.freeze({
+  /**
+   * Encode a string to its UTF-8 byte representation.
+   */
+  encode(input) {
+    if (typeof input !== "string") {
+      throw new TypeError("Utf8.encode: input must be a string");
+    }
+    return native.utf8Encode(input);
+  },
+  /**
+   * Decode UTF-8 bytes to a string.
+   *
+   * @throws {RangeError} on invalid UTF-8 (truncated multi-byte, lone surrogate,
+   *   invalid start byte, etc.). Unlike `Buffer.toString('utf-8')`, this does
+   *   NOT silently substitute U+FFFD.
+   */
+  decode(input) {
+    if (!Buffer.isBuffer(input)) {
+      throw new TypeError("Utf8.decode: input must be a Buffer");
+    }
+    return native.utf8Decode(input);
+  },
+  /**
+   * Check whether the given bytes are valid UTF-8.
+   */
+  isValid(input) {
+    if (!Buffer.isBuffer(input)) {
+      throw new TypeError("Utf8.isValid: input must be a Buffer");
+    }
+    return native.utf8IsValid(input);
+  }
+});
 
 // src/types.ts
 function asPublicKey(buf) {
@@ -812,7 +929,7 @@ function xor(a, b) {
 }
 
 // src/index.ts
-var VERSION = "0.2.0";
+var VERSION = "0.4.0";
 var SignalisCore = Object.freeze({
   // Crypto primitives
   Curve25519,
@@ -821,22 +938,29 @@ var SignalisCore = Object.freeze({
   HKDF,
   AES_GCM,
   AES_CBC,
+  ChaCha20Poly1305,
   HMAC,
   SHA256,
   // Random
   secureRandom: secureRandom2,
+  nativeSecureRandom,
   randomNonce,
   randomIv,
   randomKey,
-  // Encoding
+  // Encoding (JS-side legacy helpers — use Base64/Hex/Utf8 for native)
   toHex,
   fromHex,
   toBase64,
   fromBase64,
+  // Encoding (NEW v0.4.0 — native, RFC-compliant)
+  Base64,
+  Hex,
+  Utf8,
   // Security
   constantTimeEqual,
+  constantTimeEq: constantTimeEq2,
   // Version
-  VERSION: "0.2.0",
+  VERSION,
   nativeVersion
 });
 var index_default = SignalisCore;
@@ -851,6 +975,7 @@ export {
   AES_GCM_MAX_PLAINTEXT_SIZE,
   AES_GCM_RECOMMENDED_MESSAGES_PER_KEY,
   AuthenticationError,
+  Base64,
   CHACHA20_POLY1305_KEY_SIZE,
   CHACHA20_POLY1305_NONCE_SIZE,
   CHACHA20_POLY1305_TAG_SIZE,
@@ -870,6 +995,7 @@ export {
   HKDF_PRK_SIZE,
   HMAC,
   HMAC_SHA256_TAG_SIZE,
+  Hex,
   KeyDerivationError,
   LengthError,
   SHA256,
@@ -877,6 +1003,7 @@ export {
   SHA256_OUTPUT_SIZE,
   SignalisError,
   SignatureError,
+  Utf8,
   VERSION,
   ValidationError,
   XED25519_PRIVATE_KEY_SIZE,