hyli-noir 0.0.2 → 0.2.0

package/README.md

@@ -1,35 +1,187 @@
-# Check Secret Noir
+# Hyli-noir
 
-This is a demonstration project that shows how to implement a secret checking system using Noir (a Domain Specific Language for SNARK proving systems) with a web frontend.
+A TypeScript/JavaScript library providing Noir-based zero-knowledge proof functionality for the Hyli ecosystem. This library enables secure secret verification through cryptographic proofs without revealing sensitive information.
 
-## Project Structure
+## Features
 
-- `/contract` - Contains the Noir smart contract code
-  - `src/main.nr` - The main Noir contract implementing the secret checking logic
-- `/frontend` - Web interface implementation
+- 🔐 **Zero-Knowledge Secret Verification**: Generate proofs that demonstrate knowledge of a password without revealing it
+- 🛡️ **Identity-Based Authentication**: Combine user identity with password hashing for secure authentication
+- 📦 **Blob Transaction Support**: Create and manage blob transactions containing encrypted secrets
+- ⚡ **Noir Circuit Integration**: Built on Noir's zero-knowledge proof system with UltraHonk backend
+- 🔧 **TypeScript Support**: Full TypeScript definitions and type safety
 
-## Features
+## Installation
+
+```bash
+npm install hyli-noir
+```
 
-- Zero-knowledge proof based secret verification
-- Web interface for submitting identity and password
-- Real-time proof verification display
-- Secure password handling through zero-knowledge proofs, settling on Hyle network.
+### Peer Dependencies
 
-## Setup and Running
+This library requires the following peer dependencies:
 
-1. Install dependencies:
 ```bash
-# In the frontend directory
-bun install
+npm install @aztec/bb.js@0.82.2 @noir-lang/noir_js@1.0.0-beta.2 @noir-lang/noir_wasm@1.0.0-beta.2
 ```
 
-2. Run the frontend development server:
+## Quick Start
+
+```typescript
+import { check_secret } from 'hyli-noir';
+
+// Hash a password
+const hashedPassword = await check_secret.hash_password('my-secret-password');
+
+// Generate identity hash
+const identityHash = await check_secret.identity_hash('user@example.com', 'my-secret-password');
+
+// Build a blob transaction
+const blob = await check_secret.build_blob('user@example.com', 'my-secret-password');
+
+// Generate a proof transaction
+const proofTx = await check_secret.build_proof_transaction(
+  'user@example.com',
+  'my-secret-password',
+  '0x1234567890abcdef...', // transaction hash
+  0, // blob index
+  1  // total blob count
+);
+```
+
+## API Reference
+
+### Core Functions
+
+#### `hash_password(password: string): Promise<Uint8Array>`
+
+Hashes a password using SHA-256.
+
+**Parameters:**
+- `password` - The password string to hash
+
+**Returns:** Promise resolving to a 32-byte Uint8Array containing the SHA-256 hash
+
+#### `identity_hash(identity: string, password: string): Promise<string>`
+
+Creates a combined hash of identity and password for authentication.
+
+**Parameters:**
+- `identity` - The user's identity string
+- `password` - The user's password string
+
+**Returns:** Promise resolving to a hex-encoded string of the combined hash
+
+#### `build_blob(identity: string, password: string): Promise<Blob>`
+
+Creates a blob transaction containing a secret derived from identity and password.
+
+**Parameters:**
+- `identity` - The user's identity string
+- `password` - The user's password string
+
+**Returns:** Promise resolving to a Blob object containing the encrypted secret
+
+#### `build_proof_transaction(identity, password, tx_hash, blob_index, tx_blob_count, circuit?): Promise<ProofTransaction>`
+
+Generates a zero-knowledge proof transaction demonstrating knowledge of the password.
+
+**Parameters:**
+- `identity` - The user's identity string
+- `password` - The user's password string
+- `tx_hash` - The blob transaction hash string
+- `blob_index` - The index of the blob in the transaction
+- `tx_blob_count` - Total number of blobs in the transaction
+- `circuit` - Optional compiled Noir circuit (defaults to check_secret circuit)
+
+**Returns:** Promise resolving to a ProofTransaction containing the generated proof
+
+#### `register_contract(node, circuit?): Promise<void>`
+
+Registers the Noir contract with the node if not already registered.
+
+**Parameters:**
+- `node` - The NodeApiHttpClient instance
+- `circuit` - Optional compiled Noir circuit (defaults to check_secret circuit)
+
+### Utility Functions
+
+#### `assert(condition: boolean, message: string): void`
+
+Throws an error if the condition is false.
+
+#### `sha256(data: Uint8Array): Promise<Uint8Array>`
+
+Computes SHA-256 hash of the input data.
+
+#### `stringToBytes(input: string): Uint8Array`
+
+Converts a string to Uint8Array using UTF-8 encoding.
+
+#### `encodeToHex(data: Uint8Array): string`
+
+Converts Uint8Array to hex string representation.
+
+## How It Works
+
+The library implements a zero-knowledge proof system for secret verification:
+
+1. **Password Hashing**: The user's password is hashed using SHA-256 to create a fixed-size secret
+2. **Identity Combination**: The identity is concatenated with the hashed password using a colon separator
+3. **Final Hash**: The combined value is hashed again to create the stored secret
+4. **Proof Generation**: A zero-knowledge proof is generated that demonstrates knowledge of the password without revealing it
+5. **Verification**: The proof can be verified against the stored hash without exposing the original password
+
+## Security Considerations
+
+- Passwords are never stored in plain text
+- The zero-knowledge proof system ensures password privacy
+- All cryptographic operations use industry-standard algorithms (SHA-256)
+- The system is designed to prevent replay attacks and unauthorized access
+
+## Development
+
+### Building Noir contract
+
+In `./check-jwt/`  folder if `./Prover.toml` is present and well constructed
+
 ```bash
-# In the frontend directory
-bun run dev
+nargo execute
 ```
+It builds and executes the circuit.
+
+In `./check-secret/`, to build without executing do
+
+```bash
+nargo build
+```
+
+### Building library
+
+```bash
+bun run build
+```
+
+### Publishing
+
+```bash
+bun run pub
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
 
-## Security
+For issues and questions:
+- GitHub Issues: [https://github.com/hyli-org/hyli-noir/issues](https://github.com/hyli-org/hyli-noir/issues)
+- Repository: [https://github.com/hyli-org/hyli-noir](https://github.com/hyli-org/hyli-noir)
 
-This example demonstrates zero-knowledge proof concepts for password verification. The password is never directly exposed in the verification process, enhancing security through cryptographic proofs.
+## Related Projects
 
+- [Hyli](https://github.com/hyli-org/hyli) - The main Hyli ecosystem
+- [Noir](https://noir-lang.org/) - Zero-knowledge proof language

package/dist/check_jwt.d.ts

@@ -0,0 +1,70 @@
+import { Fr } from "@aztec/bb.js";
+import { CompiledCircuit } from "@noir-lang/noir_js";
+import { Blob } from "hyli";
+export declare const contract_name = "check_jwt";
+/**
+ * Generates a cryptographic proof for a transaction using a JWT circuit.
+ *
+ * @param {Object} params - Parameters required for proof generation.
+ * @param {string} params.identity - The user's identity string.
+ * @param {number[]} params.stored_hash - The precomputed/stored hash.
+ * @param {string} params.tx - The transaction identifier or hash.
+ * @param {number} params.blob_index - The index of the blob within the transaction.
+ * @param {number} params.tx_blob_count - The total number of blobs in the transaction.
+ * @param {string} params.idToken - The signed JWT token.
+ * @param {JsonWebKey} params.jwtPubkey - The JWT public key in JWK format.
+ * @param {CompiledCircuit} params.circuit - The compiled circuit to execute (defaults to check-jwt).
+ *
+ * @returns {Promise<{ contract_name: string; program_id: number[]; verifier: string; proof: number[] }>}
+ * An object containing verifier details and the generated proof.
+ */
+export declare const build_proof_transaction: ({ identity, stored_hash, tx, blob_index, tx_blob_count, idToken, jwtPubkey, circuit, }: {
+    identity: string;
+    stored_hash: number[];
+    tx: string;
+    blob_index: number;
+    tx_blob_count: number;
+    idToken: string;
+    jwtPubkey: JsonWebKey;
+    circuit: CompiledCircuit;
+}) => Promise<{
+    contract_name: string;
+    program_id: number[];
+    verifier: string;
+    proof: number[];
+}>;
+/**
+ * Extracts and computes the modulus (n) from a JWK public key.
+ *
+ * @param {JsonWebKey} jwk - The public key in JWK format.
+ * @returns {Promise<bigint>} The modulus of the public key as a BigInt.
+ */
+export declare function jwk_pubkey_mod(jwk: JsonWebKey): Promise<bigint>;
+/**
+ * Extracts specific claims from a JWT.
+ *
+ * @param {string} jwt - A JWT string in the format header.payload.signature.
+ * @returns {{ email: string; nonce: string; kid: string }}
+ * An object containing the email, nonce, and key ID (kid).
+ */
+export declare const extract_jwt_claims: (jwt: string) => {
+    email: string;
+    nonce: string;
+    kid: string;
+};
+/**
+ * Builds a blob representing a JWT, used for proof generation in the circuit.
+ *
+ * @param {Uint8Array} mail_hash - The hashed email value.
+ * @param {string} nonce - The nonce value from the JWT.
+ * @param {string} pubkey - The public key (base64url encoded).
+ * @returns {Blob} A structured Blob object containing the JWT data.
+ */
+export declare const build_blob: (mail_hash: Uint8Array, nonce: string, pubkey: string) => Blob;
+/**
+ * Computes the Poseidon2 hash of a string.
+ *
+ * @param {string} string - The input string to be hashed.
+ * @returns {Promise<Fr>} The Poseidon2 hash result.
+ */
+export declare const poseidon_hash: (string: string) => Promise<Fr>;

package/dist/check_secret.d.ts

@@ -1,6 +1,27 @@
 import { CompiledCircuit } from "@noir-lang/types";
 import { Blob, ProofTransaction, NodeApiHttpClient } from "hyli";
+/**
+ * Hashes a password using SHA-256.
+ * The password is converted to a Uint8Array and hashed using SHA-256.
+ * The resulting hash is returned as a Uint8Array.
+ *
+ * @param password - The password string to hash
+ * @returns A Promise resolving to the Uint8Array of the computed hash
+ */
 export declare const hash_password: (password: string) => Promise<Uint8Array>;
+/**
+ * Hashes an identity and password together using SHA-256.
+ * The identity is concatenated with ':' and the hashed password.
+ * The resulting combined value is hashed again using SHA-256.
+ * The resulting hash is returned as a hexadecimal string that can be
+ * stored publicly.
+ *
+ * This function is mainly used to check the given password against a stored hash.
+ *
+ * @param identity - The user's identity string
+ * @param password - The user's password string
+ * @returns A Promise resolving to the hexadecimal string of the computed hash
+ */
 export declare const identity_hash: (identity: string, password: string) => Promise<string>;
 /**
  * Builds a blob transaction containing a secret derived from an identity and password.
@@ -39,8 +60,3 @@ export declare const build_proof_transaction: (identity: string, password: strin
  * @returns A Promise that resolves when the contract is registered
  */
 export declare const register_contract: (node: NodeApiHttpClient, circuit?: CompiledCircuit) => Promise<void>;
-export declare const assert: (condition: boolean, message: string) => void;
-export declare const sha256: (data: Uint8Array) => Promise<Uint8Array>;
-export declare const stringToBytes: (input: string) => Uint8Array;
-export declare const encodeToHex: (data: Uint8Array) => string;
-export declare function flattenFieldsAsArray(fields: string[]): Uint8Array;

package/dist/common.d.ts

@@ -0,0 +1,7 @@
+export declare const assert: (condition: boolean, message: string) => void;
+export declare const sha256: (data: Uint8Array) => Promise<Uint8Array>;
+export declare const stringToBytes: (input: string) => Uint8Array;
+export declare const encodeToHex: (data: Uint8Array) => string;
+export declare function flattenFieldsAsArray(fields: string[]): Uint8Array;
+export declare function bytesToBigInt(bytes: Uint8Array): bigint;
+export declare function b64urlToU8(s: string): Uint8Array;