Add JA4 TLS client fingerprinting (core, BSD-scoped) and fix GREASE filtering

[kriszyp]

Closes #12, closes #2.

What this does

Adds core JA4 TLS client fingerprinting (FoxIO spec) beside JA3 in the MSG_PEEK ClientHello parser, and accepts JA4 entries in the protection blocklist.

• PeekInfo gains ja4 (empty string on parse failure, like ja3). The parser now captures ALPN (ext 16), signature_algorithms (ext 13), and supported_versions (ext 43) payloads.
• ja4Blocklist?: string[] in ProtectionConfig, checked beside the JA3 check; entries normalized to lowercase on both sides.
• blocked events now carry ja3/ja4, so fingerprints can be collected from symphony's own logs for blocklisting.
• Licensing scope (deliberate): core JA4 for TLS only — it is BSD-licensed. JA4S/JA4H/JA4SSH and other JA4+ variants are under FoxIO's proprietary license and are not implemented; documented in the README.
• README also gains the one-paragraph MD5/JA3 rationale (JA3 is defined over MD5; not a security use) for dependency scanners and security questionnaires.

is_grease fix (root cause, in this path)

The GREASE predicate matched only 0x0A0A instead of all 16 RFC 8701 values. Fixed (lo == hi && (lo & 0x0F) == 0x0A) — this makes the red sni::tests::test_is_grease green and is required for correct JA4.

⚠️ Overlap note: #18 carries the identical is_grease fix — whichever merges second rebases trivially (same predicate).

⚠️ Behavior note for release notes: pre-fix JA3 hashes included non-0x0A0A GREASE values, so JA3 for GREASE-rotating clients (Chrome) was nonstandard and unstable per-connection. Post-fix values are spec-correct; JA3 blocklist entries collected from earlier symphony versions should be re-collected (README upgrade note included).

JA4 spec conformance

Part A (t + version-from-supported_versions + SNI d/i keyed on extension presence per spec + GREASE-excluded counts, with SNI/ALPN included in the extension count per spec + ALPN first/last chars with non-alphanumeric → 9), Part B (sha256/12 of sorted GREASE-excluded ciphers), Part C (sorted extensions minus SNI/ALPN + unsorted sigalgs, suffix omitted when ext 13 absent). Verified in review against the FoxIO spec field-by-field; the unit vector is synthetic (a captured-Chrome reference fixture would be a nice follow-up).

Review

Cross-model reviewed (Gemini diff-only leg + Opus domain pass). The domain pass specifically hunted for panic paths in the extended parser — this code runs pre-handshake on raw untrusted bytes in a napi cdylib where a panic aborts the Node process — and confirmed every slice is length-guarded (no remote-DoS path). Review fixes landed in b5add11.

Testing

• cargo test: 16/16 (including the previously-red test_is_grease, now covering all 16 GREASE values + near-misses).
• npm test: 33/34 — sole failure is the pre-existing hardcoded '0.4.0' version assertion, fixed in Fix CI: check out core submodule, drop retired macos-13 runner #18.
• 11 JA4 unit tests (version detection, d/i incl. present-but-rejected SNI, count rules, GREASE exclusion, hash inputs) + a Node spec that discovers the test client's real JA4 then asserts blocking via ja4Blocklist.

— Drafted and driven by KrAIs (Claude Opus 4.8 / Fable 5) on Kris's behalf; adversarially reviewed as described above.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request implements core JA4 TLS client fingerprinting and blocking support across the Rust and TypeScript layers, including configuration options, event emissions, comprehensive tests, and documentation. The review feedback highlights two important spec-compliance and robustness improvements in src/sni.rs: first, correcting the ALPN character mapping logic to use the hex representation of the ALPN value when non-alphanumeric characters are encountered; second, checking if sig_algs is not empty rather than relying on has_sig_algs to prevent a potential trailing underscore in the hash input.

[hdbjeff]

Medium — JA4 enforcement can be bypassed with a fragmented ClientHello

Inline on src/sni.rs, around line 145:

Medium — JA4 enforcement can be bypassed with a fragmented ClientHello

TcpStream::peek() returns whatever bytes are currently available, and this parser explicitly accepts a truncated extension list. A client can send enough of the ClientHello to expose its real SNI, pause before
later extensions, and cause Symphony to calculate a different or empty JA4. Rustls can subsequently read and accept the complete handshake, bypassing ja4Blocklist.

Please reassemble the complete declared ClientHello, including handshakes spanning TLS records, under a size bound and timeout. When fingerprint enforcement is configured, incomplete acquisition should have
explicit fail-closed behavior. Add a test that splits a valid ClientHello across multiple writes.

Medium — Invalid JA4 blocklist entries are silently accepted

Inline on src/proxy.rs, around line 642:

Medium — Invalid JA4 blocklist entries are silently accepted

This lowercases and installs arbitrary strings without validating the documented JA4 format. A typo starts successfully but can never match, silently leaving the intended client unblocked.

Please validate the complete JA4 structure during configuration parsing and return an error identifying the offending entry. Tests should cover invalid length, separators, and non-hex hash characters.

Low — GREASE signature algorithms produce noncanonical JA4 values

Inline on src/sni.rs, around line 352:

Low — GREASE signature algorithms produce noncanonical JA4 values

The JA4 specification requires GREASE values to be ignored wherever encountered, but signature algorithms are added to Part C without applying is_grease. A GREASE signature value will therefore change the
fingerprint and prevent it from matching standard JA4 tooling or external rule databases.

Please filter GREASE values from sig_algs and add a test proving that inserting a GREASE signature algorithm does not change the resulting JA4.

Review summary

Request changes. The JA4 implementation is generally well structured, but the new enforcement path currently trusts a partial ClientHello and can be bypassed through TCP fragmentation. The configuration
validation and GREASE handling should also be corrected for safe operation and interoperability.

[hdbjeff]

High Heap Allocation Churn on TLS Hot Path in compute_ja4

• Target File: src/sni.rs (inside compute_ja4 function)
• Suggested Position: Lines 356, 372, and 378 (where .map(|v| format!("{v:04x}")).collect::<Vec<_>>().join(",") is called)

1 ### ⚠️ Performance: Avoid High Heap Allocation Churn on TLS Hot Path
2
3 In compute_ja4, lists of ciphers, extensions, and signature algorithms are formatted using mapped strings, collected into intermediate vectors, and then joined:
let cipher_str = ciphers.iter().map(|v| format!("{v:04x}")).collect::<Vec<_>>().join(",");

1 Because compute_ja4 runs on the TLS "peek" hot path (executed on every new incoming connection), mapping and collecting these intermediate strings triggers up to 40+ heap allocations per
connection. Under high connection scales (e.g. 10k connections/sec), this results in over 400,000 avoidable allocations per second, leading to allocator churn and CPU pressure.
2
3 #### Suggested Fix
4 Format directly into a single pre-allocated string using Rust's write! macro, completely bypassing intermediate String and Vec allocations.
5
6 For cipher_str (apply similarly to ext_str and sig_str):
let mut cipher_str = String::with_capacity(ciphers.len() * 5); // 4 hex + 1 comma
for (i, &v) in ciphers.iter().enumerate() {
if i > 0 {
cipher_str.push(',');
}
use std::fmt::Write;
let _ = write!(cipher_str, "{v:04x}");
}

let part_b = if ciphers.is_empty() {
"000000000000".to_string()
} else {
sha256_hex12(cipher_str.as_bytes())
};

1 Applying this to the three string formats will make compute_ja4 practically allocation-free!

[kriszyp]

@hdbjeff your review here (the fragmented-ClientHello bypass, blocklist validation, GREASE sig-algs, and compute_ja4 allocation churn) landed as top-level comments and was missed when this PR merged — apologies. All four are addressed in the follow-up #28 on main:

• Fragmented-hello bypass → peek() reassembles the full ClientHello (bounded) and protection.rs fails closed (incomplete_handshake) under fingerprint enforcement.
• Invalid blocklist entries → validated at config parse (ja4 and ja3), construction error names the offender.
• GREASE sig-algs → now is_grease-filtered in JA4_c.
• Allocation churn → single write!-into-preallocated-String helper.

Re-review welcome on #28.

🤖 Claude Fable 5, on Kris's behalf

[hdbjeff]

Thanks for the follow-up. I reviewed #28 against the original findings.

The GREASE signature-algorithm fix and allocation cleanup are complete. JA3 validation is also correct. However, the fragmentation bypass and JA4 validation findings are not fully closed:

• Harden JA3/JA4 fingerprinting: fragmented-hello bypass, blocklist validation, GREASE sig-algs, hot-path allocs #28 reassembles TCP fragmentation within one TLS record, but does not correctly handle a ClientHello spanning multiple TLS records. It calculates the required wire length without accounting for continuation-record headers and can set
  complete=true before the full handshake payload is available. This can still produce a wrong JA3/JA4 while rustls later accepts the complete handshake.
• JA4 validation accepts QUIC/DTLS prefixes and versions Symphony cannot emit, so entries that can never match are still accepted. Validation also runs before lowercase normalization, conflicting with the case-insensitive behavior.

I’ve put the implementation details and missing test cases on #28. Therefore, I would leave the fragmented-ClientHello and JA4-validation findings open pending that follow-up.