feat: add SHA-3 and cSHAKE support to subtle.digest() (#942)

Author: boorad

.claude/agents/orchestrator.md

@@ -20,6 +20,7 @@ description: MUST BE USED for all multi-file operations (3+ files) or cross-doma
 ## When to Activate
 
 Use orchestrator for:
+
 - Tasks touching 3+ files
 - Cross-language operations (e.g., TypeScript + C++)
 - New feature development with multiple components
@@ -31,16 +32,19 @@ Use orchestrator for:
 When you receive a request:
 
 1. **Map all dependencies**
+
    - Which layers are affected? (JS, C++, native bridging)
    - What are the data flows?
    - Are there shared types or interfaces?
 
 2. **Identify parallelization opportunities**
+
    - Which tasks are independent?
    - What can run concurrently?
    - What must be sequential?
 
 3. **Create explicit task boundaries**
+
    - Each specialist gets a clear, focused scope
    - Define success criteria
    - Specify interfaces/contracts between tasks
@@ -54,6 +58,7 @@ When you receive a request:
 ## Orchestration Examples
 
 ### Example 1: New Crypto Feature (WebCrypto API)
+
 ```
 User Request: "Implement subtle.encrypt/decrypt for AES-GCM"
 
@@ -76,6 +81,7 @@ Wave 3 (Validation):
 ```
 
 ### Example 2: Refactoring to Modern C++
+
 ```
 User Request: "Migrate hash functions from OpenSSL 1.1.1 to 3.6+"
 
@@ -90,13 +96,14 @@ Wave 1 (Research):
 
 Wave 2 (Migration):
   - cpp-specialist: Update to EVP_* APIs, modernize C++ patterns
-  
+
 Wave 3 (Validation):
   - crypto-specialist: Ensure cryptographic correctness maintained
   - testing-specialist: Verify no regressions
 ```
 
 ### Example 3: Node.js Polyfill Feature
+
 ```
 User Request: "Add support for crypto.pbkdf2"
 
@@ -121,13 +128,17 @@ Wave 3 (Compatibility):
 ## Communication Protocol
 
 ### Input Format
+
 You receive tasks in natural language. Extract:
+
 - Goal (what needs to be accomplished)
 - Constraints (compatibility, performance, security)
 - Context (related code, dependencies)
 
 ### Output Format
+
 Provide:
+
 1. **Task Analysis**: What needs to be done and why
 2. **Dependency Map**: What depends on what
 3. **Wave Plan**: Sequential waves of parallel tasks
@@ -137,12 +148,13 @@ Provide:
 
 ## Rules You Must Follow
 
-1. **Never write code yourself** - always delegate to specialists
-2. **Always parallelize independent tasks** - maximize efficiency
-3. **Enforce architectural rules** from `.claude/rules/*.xml`
-4. **Track all metrics** - token usage, timing, cost estimates
-5. **Validate completeness** - ensure all requirements met before marking done
-6. **Report clearly** - synthesize specialist work into coherent summary
+1. **Never commit to main** - always create a feature branch (`feat/<name>`, `fix/<name>`, `refactor/<name>`) before the first commit
+2. **Never write code yourself** - always delegate to specialists
+3. **Always parallelize independent tasks** - maximize efficiency
+4. **Enforce architectural rules** from `.claude/rules/*.xml`
+5. **Track all metrics** - token usage, timing, cost estimates
+6. **Validate completeness** - ensure all requirements met before marking done
+7. **Report clearly** - synthesize specialist work into coherent summary
 
 ## Available Specialists
 
@@ -173,6 +185,7 @@ if (task spans multiple domains):
 ## Success Metrics
 
 Track and report:
+
 - Total tokens used across all specialists
 - Time elapsed (wall clock)
 - Estimated cost (if applicable)

.docs/implementation-coverage.md

@@ -105,7 +105,7 @@ These algorithms provide quantum-resistant cryptography.
   - ✅ `x509.validFrom`
   - ✅ `x509.validTo`
   - ✅ `x509.verify(publicKey)`
-- 🚧 node:crypto module methods and properties
+- ✅ node:crypto module methods and properties
   - ✅ `crypto.argon2(algorithm, parameters, callback)`
   - ✅ `crypto.argon2Sync(algorithm, parameters)`
   - ✅ `crypto.checkPrime(candidate[, options], callback)`
@@ -277,7 +277,7 @@ These ciphers are **not available in Node.js** but are provided by RNQC via libs
   - ✅ `subtle.decrypt(algorithm, key, data)`
   - ✅ `subtle.deriveBits(algorithm, baseKey, length)`
   - ✅ `subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)`
-  - 🚧 `subtle.digest(algorithm, data)`
+  - ✅ `subtle.digest(algorithm, data)`
   - ✅ `subtle.encapsulateBits(encapsulationAlgorithm, encapsulationKey)`
   - ✅ `subtle.encapsulateKey(encapsulationAlgorithm, encapsulationKey, sharedKeyAlgorithm, extractable, usages)`
   - 🚧 `subtle.encrypt(algorithm, key, data)`
@@ -331,15 +331,17 @@ These ciphers are **not available in Node.js** but are provided by RNQC via libs
 
 | Algorithm   | Status |
 | ----------- | :----: |
-| `cSHAKE128` |   ❌   |
-| `cSHAKE256` |   ❌   |
+| `cSHAKE128` |   ✅   |
+| `cSHAKE256` |   ✅   |
 | `SHA-1`     |   ✅   |
 | `SHA-256`   |   ✅   |
 | `SHA-384`   |   ✅   |
 | `SHA-512`   |   ✅   |
-| `SHA3-256`  |   ❌   |
-| `SHA3-384`  |   ❌   |
-| `SHA3-512`  |   ❌   |
+| `SHA3-256`  |   ✅   |
+| `SHA3-384`  |   ✅   |
+| `SHA3-512`  |   ✅   |
+
+> **Note:** `cSHAKE128` and `cSHAKE256` provide SHAKE128/SHAKE256 (XOF) functionality with empty customization, matching Node.js behavior. The `length` parameter (in bytes, must be a multiple of 8) is required to specify the output length.
 
 ## `subtle.encrypt`
 

CLAUDE.md

@@ -12,14 +12,17 @@ This project uses the **4-Layer Orchestra Architecture** for efficient multi-age
 ## Critical Principles
 
 ### 1. API Priority Order (NON-NEGOTIABLE)
+
 When implementing features, favor in this order:
+
 1. **WebCrypto API** - Modern standard, best for `subtle.*` methods
 2. **Node.js Implementation** - Use `$REPOS/node/deps/ncrypto` as reference
 3. **ncrypto** - submodule code reference at `$REPOS/ncrypto` (do work w/ OpenSSL)
 
 **Always check Node.js `deps/ncrypto` before implementing new features.**
 
 ### 2. Modern Stack Required
+
 - **React Native** - Mobile framework
 - **TypeScript** - Type system (strict mode, no `any`)
 - **Nitro Modules** - Native bridging
@@ -28,12 +31,21 @@ When implementing features, favor in this order:
 - **Bun 1.3+** - TypeScript package manager
 
 ### 3. Code Philosophy
+
 - Minimize code rather than add more
 - Prefer iteration and modularization over duplication
 - No comments unless code is sufficiently complex
 - Code should be self-documenting
 
-### 4. Security is Critical
+### 4. Never Commit to Main
+
+- **ALWAYS** create a feature branch before the first commit
+- Branch naming: `feat/<name>`, `fix/<name>`, `refactor/<name>`
+- All changes go through PRs — never push directly to main
+- If you find yourself on main, create a branch before committing
+
+### 5. Security is Critical
+
 - Constant-time comparisons for authentication tags
 - Cryptographically secure randomness (RAND_bytes)
 - AEAD modes preferred (AES-GCM)
@@ -45,6 +57,7 @@ When implementing features, favor in this order:
 For full details, see `.claude/rules/*.xml`:
 
 ### architecture.xml
+
 - Project context and goals
 - API priority order (WebCrypto → Node.js → ncrypto)
 - Tech stack requirements
@@ -53,6 +66,7 @@ For full details, see `.claude/rules/*.xml`:
 - Local codebase references
 
 ### code-typescript.xml
+
 - No `any` or `unknown` casts
 - Interfaces over types
 - Named exports only (no default)
@@ -62,6 +76,7 @@ For full details, see `.claude/rules/*.xml`:
 - React best practices (minimal useEffect)
 
 ### code-cpp.xml
+
 - C++20 minimum with modern features
 - Smart pointers for all ownership
 - OpenSSL 3.6+ EVP APIs only (no deprecated)
@@ -70,6 +85,7 @@ For full details, see `.claude/rules/*.xml`:
 - Memory safety (no leaks, no raw ownership)
 
 ### crypto-security.xml
+
 - Cryptographic correctness (match specs)
 - No timing attacks (CRYPTO_memcmp)
 - Secure RNG (RAND_bytes)
@@ -79,6 +95,7 @@ For full details, see `.claude/rules/*.xml`:
 - No key material in errors
 
 ### ci-caching.xml
+
 - iOS Pods/DerivedData cache consistency (exact-match Pods, no restore-keys)
 - Cache key design (no version suffixes, use hashFiles)
 - Android Maestro patterns (don't launch app before Maestro)
@@ -87,12 +104,14 @@ For full details, see `.claude/rules/*.xml`:
 ## When to Use Orchestration
 
 ### Use Orchestrator For:
+
 - ✅ Tasks touching 3+ files
 - ✅ Cross-language changes (TypeScript + C++)
 - ✅ New crypto features (API + implementation)
 - ✅ Complex refactoring
 
 ### Work Directly For:
+
 - ✅ Single file changes
 - ✅ Simple bug fixes
 - ✅ Type updates
@@ -111,14 +130,17 @@ For full details, see `.claude/rules/*.xml`:
 Use these instead of web searches:
 
 - **Node.js**: `$REPOS/node`
+
   - `deps/ncrypto` - Use as bible for crypto operations
   - May need updating to OpenSSL 3.6+ patterns
 
 - **ncrypto**: `$REPOS/ncrypto`
+
   - separate crypto lib broken out from Node.js
   - Patterns and tools to access OpenSSL
 
 - **Nitro**: `$REPOS/nitro`
+
   - iOS CI caching patterns (super-fast builds)
   - Nitro Modules bridging examples
 
@@ -128,7 +150,7 @@ Use these instead of web searches:
 
 ## Testing
 
-Tests run in the React Native example app environment, not standard Node.js test runners. 
+Tests run in the React Native example app environment, not standard Node.js test runners.
 
 Don't ask to run tests - they must be executed in the example React Native application.
 
@@ -139,6 +161,7 @@ Metro output is tee'd to `/tmp/rnqc-metro.log`. When debugging test failures, re
 ## Quality Checks
 
 Before committing:
+
 - [ ] Type safety (no `any`, proper interfaces)
 - [ ] Memory safety (smart pointers, RAII)
 - [ ] Cryptographic correctness (test vectors)

docs/data/coverage.ts

@@ -349,15 +349,15 @@ export const COVERAGE_DATA: CoverageCategory[] = [
       {
         name: 'crypto.subtle.digest',
         subItems: [
-          { name: 'cSHAKE128', status: 'missing' },
-          { name: 'cSHAKE256', status: 'missing' },
+          { name: 'cSHAKE128', status: 'implemented' },
+          { name: 'cSHAKE256', status: 'implemented' },
           { name: 'SHA-1', status: 'implemented' },
           { name: 'SHA-256', status: 'implemented' },
           { name: 'SHA-384', status: 'implemented' },
           { name: 'SHA-512', status: 'implemented' },
-          { name: 'SHA3-256', status: 'missing' },
-          { name: 'SHA3-384', status: 'missing' },
-          { name: 'SHA3-512', status: 'missing' },
+          { name: 'SHA3-256', status: 'implemented' },
+          { name: 'SHA3-384', status: 'implemented' },
+          { name: 'SHA3-512', status: 'implemented' },
         ],
       },
       {

example/src/tests/subtle/digest.ts

@@ -21,6 +21,9 @@ const kTests: Test[] = [
   ['SHA-256', 'sha256', 256],
   ['SHA-384', 'sha384', 384],
   ['SHA-512', 'sha512', 512],
+  ['SHA3-256', 'sha3-256', 256],
+  ['SHA3-384', 'sha3-384', 384],
+  ['SHA3-512', 'sha3-512', 512],
 ];
 
 const kData = toArrayBuffer(Buffer.from('hello'));
@@ -46,3 +49,32 @@ kTests.forEach(([algorithm, legacyName, bitLength]) => {
     });
   });
 });
+
+// cSHAKE tests (XOF - extendable output functions)
+test(SUITE, 'hash: cSHAKE128', async () => {
+  const outputLength = 32;
+  const checkValue = createHash('shake128', { outputLength })
+    .update(kData)
+    .digest()
+    .toString('hex');
+
+  const result = await subtle.digest(
+    { name: 'cSHAKE128', length: outputLength },
+    kData,
+  );
+  expect(ab2str(result)).to.equal(checkValue);
+});
+
+test(SUITE, 'hash: cSHAKE256', async () => {
+  const outputLength = 64;
+  const checkValue = createHash('shake256', { outputLength })
+    .update(kData)
+    .digest()
+    .toString('hex');
+
+  const result = await subtle.digest(
+    { name: 'cSHAKE256', length: outputLength },
+    kData,
+  );
+  expect(ab2str(result)).to.equal(checkValue);
+});