cas-typescript-sdk 1.0.44 → 1.0.46

package/README.md

@@ -1,23 +1,33 @@
-# cas-typescript-sdk
+# CAS TypeScript SDK
 
-[![image](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/7bXXCQj45q)
+[![image](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/UAGqKfmvUS)
 
-Ever wanted all of your most useful cryptographic operations in one module and not had to surf documentation for various packages? 
-CAS is here to provide a unified development experience as an abstract layer to the RustCrypto and Dalek-Cryptography suite of algorithms.
-The official NPM page can be found [here](https://www.npmjs.com/package/cas-typescript-sdk).
+## Overview
 
-**Note: All work is experimental and we understand some benchmarks might not be the most optimal.**
+CAS TypeScript SDK is a comprehensive cryptographic toolkit for Node.js, designed to provide developers with a unified, high-level interface to industry-standard cryptographic algorithms. This library acts as an abstraction layer over the powerful RustCrypto and Dalek-Cryptography suites, enabling secure and efficient cryptographic operations through a simple TypeScript API.
 
-## Consuming Library Documentation
-This Node.js NPM module is dependent on our Rust layer [cas-lib](https://github.com/Cryptographic-API-Services/cas-lib) that contains methods to run industry-standard cryptographic operations.
+- **Official NPM Package:** [cas-typescript-sdk](https://www.npmjs.com/package/cas-typescript-sdk)
 
-We utilize some smart people's existing work and we believe their documentation should be reviewed when possible.
+## Features
+- Modern cryptographic primitives: symmetric encryption, asymmetric encryption, digital signatures, hashing, password hashing, key exchange, and more
+- Seamless integration with [cas-lib](https://github.com/Cryptographic-API-Services/cas-lib) Rust FFI layer for optimal performance
+- TypeScript-first API for type safety and developer productivity
+- Unified interface: no need to manage multiple cryptography packages or surf disparate documentation
+- Built on trusted, open-source cryptography libraries
+
+## Documentation & References
+We build on the work of leading cryptography projects. For in-depth algorithm details and implementation notes, please refer to:
 - [Spin Research](https://github.com/SpinResearch)
 - [Dalek-Cryptography](https://github.com/dalek-cryptography)
 - [Rust Crypto](https://github.com/RustCrypto)
 
-## [Examples](./docs/EXAMPLES.md)
+## Usage Examples
+See practical usage and code samples in our [Examples](./docs/EXAMPLES.md).
 
 ## Disclaimer
-Many of the cryptographic crates that are utilized in our core FFI [layer](./src) have never had a security audit performed. Utilize this SDK at your own risk.
+This SDK leverages several cryptographic crates via our core FFI [layer](./src). Please note that many of these crates have not undergone formal security audits. Use this library at your own risk and always review the underlying cryptographic implementations for your security requirements.
+
+---
+For questions, support, or to contribute, join our Discord or visit the [GitHub repository](https://github.com/Cryptographic-API-Services/cas-typescript-sdk).
+
 

package/index.d.ts

@@ -36,6 +36,20 @@ export declare class CaSx25519SecretPublicKeyResult {
 }
 export type CASx25519SecretPublicKeyResult = CaSx25519SecretPublicKeyResult
 
+export declare class HpkeEncryptResult {
+  tag: Array<number>
+  ciphertext: Array<number>
+  encapsulatedKey: Array<number>
+  constructor(tag: Array<number>, ciphertext: Array<number>, encapsulatedKey: Array<number>)
+}
+
+export declare class HpkeKeyResult {
+  publicKey: Array<number>
+  secretKey: Array<number>
+  infoStr: Array<number>
+  constructor(publicKey: Array<number>, secretKey: Array<number>, infoStr: Array<number>)
+}
+
 export declare function aes128Decrypt(aesKey: Array<number>, nonce: Array<number>, ciphertext: Array<number>): Array<number>
 
 export declare function aes128Encrypt(aesKey: Array<number>, nonce: Array<number>, plaintext: Array<number>): Array<number>
@@ -80,12 +94,20 @@ export declare function blake2Sha512Verify(dataToHash: Array<number>, dataToVeri
 
 export declare function generateEd25519Keys(): Cased25519KeyPairResult
 
+export declare function generateInfoStr(): Array<number>
+
 export declare function generateRsaKeys(keySize: number): CasrsaKeyPairResult
 
 export declare function hmacSign(key: Array<number>, message: Array<number>): Array<number>
 
 export declare function hmacVerify(key: Array<number>, message: Array<number>, signature: Array<number>): boolean
 
+export declare function hpkeDecrypt(ciphertext: Array<number>, privateKey: Array<number>, encappedKey: Array<number>, tag: Array<number>, infoStr: Array<number>): Array<number>
+
+export declare function hpkeEncrypt(plaintext: Array<number>, publicKey: Array<number>, infoStr: Array<number>): HpkeEncryptResult
+
+export declare function hpkeGenerateKeypair(): HpkeKeyResult
+
 export declare function scryptHash(passwordToHash: string): string
 
 export declare function scryptVerify(hashedPassword: string, passwordToVerify: string): boolean

package/lib/hybrid/hpke.d.ts

@@ -0,0 +1,31 @@
+import { HpkeKeyResult, HpkeEncryptResult } from "../../index";
+export declare class HpkeWrapper {
+    /**
+     * Generate a new HPKE key pair along with an info string
+     * @returns HpkeKeyResult
+     */
+    generateKeyPair(): HpkeKeyResult;
+    /**
+     * Generate a new info string for HPKE
+     * @returns A byte array representing the info string
+     */
+    generateInfoString(): number[];
+    /**
+     * Encrypt a message using HPKE
+     * @param plaintext The message to encrypt
+     * @param publicKey The recipient's public key
+     * @param infoStr Additional information to include in the encryption
+     * @returns HpkeEncryptResult
+     */
+    encrypt(plaintext: number[], publicKey: number[], infoStr: number[]): HpkeEncryptResult;
+    /**
+     * Decrypt a message using HPKE
+     * @param ciphertext The encrypted message
+     * @param privateKey The recipient's private key
+     * @param encapsulatedKey The encapsulated key
+     * @param tag The tag
+     * @param infoStr Additional information to include in the decryption
+     * @returns The decrypted message
+     */
+    decrypt(ciphertext: number[], privateKey: number[], encapsulatedKey: number[], tag: number[], infoStr: number[]): number[];
+}

package/lib/hybrid/hpke.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HpkeWrapper = void 0;
+const index_1 = require("../../index");
+class HpkeWrapper {
+    /**
+     * Generate a new HPKE key pair along with an info string
+     * @returns HpkeKeyResult
+     */
+    generateKeyPair() {
+        return (0, index_1.hpkeGenerateKeypair)();
+    }
+    /**
+     * Generate a new info string for HPKE
+     * @returns A byte array representing the info string
+     */
+    generateInfoString() {
+        return (0, index_1.generateInfoStr)();
+    }
+    /**
+     * Encrypt a message using HPKE
+     * @param plaintext The message to encrypt
+     * @param publicKey The recipient's public key
+     * @param infoStr Additional information to include in the encryption
+     * @returns HpkeEncryptResult
+     */
+    encrypt(plaintext, publicKey, infoStr) {
+        return (0, index_1.hpkeEncrypt)(plaintext, publicKey, infoStr);
+    }
+    /**
+     * Decrypt a message using HPKE
+     * @param ciphertext The encrypted message
+     * @param privateKey The recipient's private key
+     * @param encapsulatedKey The encapsulated key
+     * @param tag The tag
+     * @param infoStr Additional information to include in the decryption
+     * @returns The decrypted message
+     */
+    decrypt(ciphertext, privateKey, encapsulatedKey, tag, infoStr) {
+        return (0, index_1.hpkeDecrypt)(ciphertext, privateKey, encapsulatedKey, tag, infoStr);
+    }
+}
+exports.HpkeWrapper = HpkeWrapper;

package/lib/hybrid/index.d.ts

@@ -0,0 +1,2 @@
+import { HpkeWrapper } from "./hpke";
+export { HpkeWrapper };

package/lib/hybrid/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HpkeWrapper = void 0;
+const hpke_1 = require("./hpke");
+Object.defineProperty(exports, "HpkeWrapper", { enumerable: true, get: function () { return hpke_1.HpkeWrapper; } });

package/lib/index.d.ts

@@ -7,3 +7,4 @@ export * from "./digital-signature";
 export * from "./sponges/index";
 export * from "./message/index";
 export * from "./signature/index";
+export * from "./hybrid/index";

package/lib/index.js

@@ -23,3 +23,4 @@ __exportStar(require("./digital-signature"), exports);
 __exportStar(require("./sponges/index"), exports);
 __exportStar(require("./message/index"), exports);
 __exportStar(require("./signature/index"), exports);
+__exportStar(require("./hybrid/index"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cas-typescript-sdk",
-  "version": "1.0.44",
+  "version": "1.0.46",
   "description": "",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/hybrid/hpke.rs

@@ -0,0 +1,63 @@
+use crate::hybrid::types::{HpkeEncryptResult, HpkeKeyResult};
+use cas_lib::hybrid::{cas_hybrid::CASHybrid, hpke::CASHPKE};
+use napi_derive::napi;
+
+#[napi]
+pub fn hpke_generate_keypair() -> HpkeKeyResult {
+    let (secret_key, public_key, info_str) = <CASHPKE as CASHybrid>::generate_key_pair();
+    HpkeKeyResult {
+        public_key: public_key,
+        secret_key: secret_key,
+        info_str: info_str
+    }
+}
+
+#[napi]
+pub fn generate_info_str() -> Vec<u8> {
+    return <CASHPKE as CASHybrid>::generate_info_str();
+}
+
+#[napi]
+pub fn hpke_encrypt(
+    plaintext: Vec<u8>,
+    public_key: Vec<u8>,
+    info_str: Vec<u8>,
+) -> HpkeEncryptResult {
+    let encrypt_result: (Vec<u8>, Vec<u8>, Vec<u8>) =
+        <CASHPKE as CASHybrid>::encrypt(plaintext, public_key, info_str);
+    return HpkeEncryptResult {
+        tag: encrypt_result.2,
+        ciphertext: encrypt_result.1,
+        encapsulated_key: encrypt_result.0,
+    }
+}
+
+#[napi]
+pub fn hpke_decrypt(
+    ciphertext: Vec<u8>,
+    private_key: Vec<u8>,
+    encapped_key: Vec<u8>,
+    tag: Vec<u8>,
+    info_str: Vec<u8>,
+) -> Vec<u8> {
+    return <CASHPKE as CASHybrid>::decrypt(ciphertext, private_key, encapped_key, tag, info_str);
+}
+
+#[test]
+pub fn hpke_encrypt_decrypt_test() {
+    let hpke_keypair = hpke_generate_keypair();
+    let plaintext = "This is a secret message".as_bytes().to_vec();
+    let encrypt_result = hpke_encrypt(
+        plaintext.clone(),
+        hpke_keypair.public_key,
+        hpke_keypair.info_str.clone(),
+    );
+    let decrypted_plaintext = hpke_decrypt(
+        encrypt_result.ciphertext,
+        hpke_keypair.secret_key,
+        encrypt_result.encapsulated_key,
+        encrypt_result.tag,
+        hpke_keypair.info_str,
+    );
+    assert_eq!(plaintext, decrypted_plaintext);
+}

package/src/hybrid/types.rs

@@ -0,0 +1,15 @@
+use napi_derive::napi;
+
+#[napi(constructor)]
+pub struct HpkeKeyResult {
+    pub public_key: Vec<u8>,
+    pub secret_key: Vec<u8>,
+    pub info_str: Vec<u8>
+}
+
+#[napi(constructor)]
+pub struct HpkeEncryptResult {
+    pub tag: Vec<u8>,
+    pub ciphertext: Vec<u8>,
+    pub encapsulated_key: Vec<u8>,
+}

package/src-ts/hybrid/hpke.ts

@@ -0,0 +1,44 @@
+import { hpkeGenerateKeypair, hpkeEncrypt, hpkeDecrypt, generateInfoStr, HpkeKeyResult, HpkeEncryptResult} from "../../index"
+
+export class HpkeWrapper {
+
+    /**
+     * Generate a new HPKE key pair along with an info string
+     * @returns HpkeKeyResult
+     */
+    public generateKeyPair(): HpkeKeyResult {
+        return hpkeGenerateKeypair();
+    }
+
+    /**
+     * Generate a new info string for HPKE
+     * @returns A byte array representing the info string
+     */
+    public generateInfoString(): number[] {
+        return generateInfoStr();
+    }
+
+    /**
+     * Encrypt a message using HPKE
+     * @param plaintext The message to encrypt
+     * @param publicKey The recipient's public key
+     * @param infoStr Additional information to include in the encryption
+     * @returns HpkeEncryptResult
+     */
+    public encrypt(plaintext: number[], publicKey: number[], infoStr: number[]): HpkeEncryptResult {
+        return hpkeEncrypt(plaintext, publicKey, infoStr);
+    }
+
+    /**
+     * Decrypt a message using HPKE
+     * @param ciphertext The encrypted message
+     * @param privateKey The recipient's private key
+     * @param encapsulatedKey The encapsulated key
+     * @param tag The tag
+     * @param infoStr Additional information to include in the decryption
+     * @returns The decrypted message
+     */
+    public decrypt(ciphertext: number[], privateKey: number[], encapsulatedKey: number[], tag: number[], infoStr: number[]): number[] {
+        return hpkeDecrypt(ciphertext, privateKey, encapsulatedKey, tag, infoStr);
+    }
+}

package/src-ts/hybrid/index.ts

@@ -0,0 +1,3 @@
+import { HpkeWrapper } from "./hpke";
+
+export { HpkeWrapper };

package/src-ts/index.ts

@@ -6,4 +6,5 @@ export * from "./asymmetric/index";
 export * from "./digital-signature";
 export * from "./sponges/index";
 export * from "./message/index";
-export * from "./signature/index";
+export * from "./signature/index";
+export * from "./hybrid/index";

package/test-ts/hybrid.test.spec.ts

@@ -0,0 +1,23 @@
+import { HpkeWrapper } from "../src-ts/hybrid/hpke";
+import { assert } from "chai";
+
+describe("Hybrid Encryption", () => {
+    it("HPKE Encrypt and Decrypt", () => {
+        const hpkeWrapper = new HpkeWrapper();
+        const keyPair = hpkeWrapper.generateKeyPair();
+        const encoder = new TextEncoder();
+        const message = "This is a secret message";
+        const messageBytes: Array<number> = Array.from(encoder.encode(message));
+        const encrypted = hpkeWrapper.encrypt(messageBytes, keyPair.publicKey, keyPair.infoStr);
+        const decrypted = hpkeWrapper.decrypt(
+            encrypted.ciphertext,
+            keyPair.secretKey,
+            encrypted.encapsulatedKey,
+            encrypted.tag,
+            keyPair.infoStr
+        );
+        const decoder = new TextDecoder();
+        const decryptedMessage = decoder.decode(new Uint8Array(decrypted));
+        assert.equal(decryptedMessage, message);
+    });
+});