diff --git a/crates/mod-string/src/lib.rs b/crates/mod-string/src/lib.rs index 2d2f48fa0..21566b9d7 100644 --- a/crates/mod-string/src/lib.rs +++ b/crates/mod-string/src/lib.rs @@ -111,6 +111,14 @@ pub fn register(lua: &Lua) -> anyhow::Result<()> { })?, )?; + string_mod.set( + "psl_domain_is_known", + lua.create_function(move |_, s: String| { + let n = psl_utils::normalize_domain(&s); + Ok(psl_utils::domain_is_known(&n)) + })?, + )?; + string_mod.set( "psl_suffix", lua.create_function(move |_, s: String| { @@ -119,6 +127,14 @@ pub fn register(lua: &Lua) -> anyhow::Result<()> { })?, )?; + string_mod.set( + "psl_suffix_is_known", + lua.create_function(move |_, s: String| { + let n = psl_utils::normalize_domain(&s); + Ok(psl_utils::suffix_is_known(&n)) + })?, + )?; + string_mod.set( "eval_template", lua.create_function( diff --git a/crates/psl-utils/src/lib.rs b/crates/psl-utils/src/lib.rs index 665d1e682..4b826b345 100644 --- a/crates/psl-utils/src/lib.rs +++ b/crates/psl-utils/src/lib.rs @@ -27,6 +27,27 @@ pub fn suffix_str(s: &str) -> Option<&str> { psl::suffix_str(s) } +/// Check whether the public suffix is explicitly present in the public +/// suffix list (as opposed to being resolved via the fallback rule for an +/// unknown top-level domain). Returns `false` when the input has no public +/// suffix. The caller is expected to pass an already-normalized domain +/// (typically via [`normalize_domain`]). +pub fn suffix_is_known(s: &str) -> bool { + psl::suffix(s.as_bytes()) + .map(|suffix| suffix.is_known()) + .unwrap_or(false) +} + +/// Check whether the registrable domain's public suffix is explicitly +/// present in the public suffix list. Returns `false` when the input has no +/// registrable domain. The caller is expected to pass an already-normalized +/// domain (typically via [`normalize_domain`]). +pub fn domain_is_known(s: &str) -> bool { + psl::domain(s.as_bytes()) + .map(|domain| domain.suffix().is_known()) + .unwrap_or(false) +} + #[cfg(test)] mod tests { use super::*; @@ -69,4 +90,40 @@ mod tests { let n = normalize_domain("foo.Example.COM."); assert_eq!(domain_str(&n), Some("example.com")); } + + #[test] + fn suffix_is_known_known() { + let n = normalize_domain("www.example.com"); + assert_eq!(suffix_is_known(&n), true); + } + + #[test] + fn suffix_is_known_unknown_fallback() { + let n = normalize_domain("domain.invalid"); + assert_eq!(suffix_is_known(&n), false); + } + + #[test] + fn suffix_is_known_empty() { + let n = normalize_domain(""); + assert_eq!(suffix_is_known(&n), false); + } + + #[test] + fn domain_is_known_known() { + let n = normalize_domain("www.example.com"); + assert_eq!(domain_is_known(&n), true); + } + + #[test] + fn domain_is_known_unknown_fallback() { + let n = normalize_domain("domain.invalid"); + assert_eq!(domain_is_known(&n), false); + } + + #[test] + fn domain_is_known_empty() { + let n = normalize_domain(""); + assert_eq!(domain_is_known(&n), false); + } } diff --git a/docs/changelog/main.md b/docs/changelog/main.md index 2e842e0b1..83d8e0fe9 100644 --- a/docs/changelog/main.md +++ b/docs/changelog/main.md @@ -62,6 +62,11 @@ a [tls_mode](../reference/kumo/make_egress_path/tls_mode.md) parameter, each selecting `StartTls` (the default) or `ImplicitTls`. #199 #200 + * New [kumo.string.psl_suffix_is_known](../reference/string/psl_suffix_is_known.md) + and [kumo.string.psl_domain_is_known](../reference/string/psl_domain_is_known.md) + report whether the resolved public suffix is explicitly listed in the Public + Suffix List. Thanks to @umutondersu! #592 + * The SOCKS5 proxy listener now accepts a [max_connections](../reference/proxy/start_proxy_listener/max_connections.md) parameter (default `32768`) that bounds the number of concurrent client diff --git a/docs/reference/string/psl_domain_is_known.md b/docs/reference/string/psl_domain_is_known.md new file mode 100644 index 000000000..84b3904c4 --- /dev/null +++ b/docs/reference/string/psl_domain_is_known.md @@ -0,0 +1,21 @@ +# kumo.string.psl_domain_is_known + +```lua +kumo.string.psl_domain_is_known(STRING) +``` + +{{since('dev')}} + +Check whether the registrable domain's public suffix is explicitly listed in +Mozilla's [Public Suffix +List](https://publicsuffix.org/). + +Returns `true` when the input is a registrable domain whose public suffix is +explicitly listed, or `false` when the suffix was derived from an unlisted +label, or when the input has no registrable domain. + +```lua +assert(kumo.string.psl_domain_is_known 'www.example.com' == true) +assert(kumo.string.psl_domain_is_known 'domain.invalid' == false) +assert(kumo.string.psl_domain_is_known 'com' == false) +``` diff --git a/docs/reference/string/psl_suffix_is_known.md b/docs/reference/string/psl_suffix_is_known.md new file mode 100644 index 000000000..2a668862c --- /dev/null +++ b/docs/reference/string/psl_suffix_is_known.md @@ -0,0 +1,18 @@ +# kumo.string.psl_suffix_is_known + +```lua +kumo.string.psl_suffix_is_known(STRING) +``` + +{{since('dev')}} + +Check whether the public suffix is explicitly listed in Mozilla's [Public Suffix +List](https://publicsuffix.org/). + +Returns `true` when the suffix is explicitly listed, or `false` when the suffix +was derived from an unlisted label, or when the input has no public suffix. + +```lua +assert(kumo.string.psl_suffix_is_known 'www.example.com' == true) +assert(kumo.string.psl_suffix_is_known 'domain.invalid' == false) +```