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.

[gemini-code-assist]

The current ALPN character mapping logic replaces non-alphanumeric characters with '9'. However, according to the JA4 specification, if the first or last byte of the first ALPN is not an ASCII alphanumeric character, the first and last characters of the hex representation of the entire first ALPN value must be used instead. This ensures compliance with the JA4 spec for custom or non-standard ALPN protocols.

Suggested change

	let alpn_chars: String = match &alpn_first {
	None => "00".to_string(),
	Some(proto) if proto.is_empty() => "00".to_string(),
	Some(proto) => {
	let to_alnum = |b: u8| -> char {
	let c = b as char;
	if c.is_ascii_alphanumeric() { c.to_ascii_lowercase() } else { '9' }
	};
	format!("{}{}", to_alnum(proto[0]), to_alnum(proto[proto.len() - 1]))
	}
	};
	let alpn_chars: String = match &alpn_first {
	None => "00".to_string(),
	Some(proto) if proto.is_empty() => "00".to_string(),
	Some(proto) => {
	let first = proto[0];
	let last = proto[proto.len() - 1];
	let is_alnum = |b: u8| b.is_ascii_alphanumeric();
	if is_alnum(first) && is_alnum(last) {
	format!("{}{}", (first as char).to_ascii_lowercase(), (last as char).to_ascii_lowercase())
	} else {
	let hex = bytes_to_hex(proto);
	let hex_bytes = hex.as_bytes();
	format!("{}{}", hex_bytes[0] as char, hex_bytes[hex_bytes.len() - 1] as char)
	}
	}
	};

[gemini-code-assist]

According to the JA4 specification, if there are no signature algorithms in the ClientHello packet, the string ends without an underscore and is hashed. Checking has_sig_algs can result in a trailing underscore if the signature algorithms extension is present but empty (e.g., due to truncation or malformed data). Checking !sig_algs.is_empty() is more robust and fully compliant with the spec.

Suggested change

	let hash_input = if has_sig_algs {
	let sig_str = sig_algs.iter().map(|v| format!("{v:04x}")).collect::<Vec<_>>().join(",");
	format!("{ext_str}_{sig_str}")
	} else {
	ext_str
	};
	let hash_input = if !sig_algs.is_empty() {
	let sig_str = sig_algs.iter().map(|v| format!("{v:04x}")).collect::<Vec<_>>().join(",");
	format!("{ext_str}_{sig_str}")
	} else {
	ext_str
	};