utilvo-shield-filters 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 71031c7466f8d5138a1af2ef37fea9813ce81fbeccc486caf14bed9f7d0feb2b
+  data.tar.gz: db1c9d95bcb2e4bf7706e9deb50e26436b350b6c8e2ee3a1f03a3404c669d5d0
+SHA512:
+  metadata.gz: 708230a45be21f203f56a4b5de2cb80660ba1ed285c6079840113ffab5d4a7c8a8eaf037e350faf8bb2ab8d29fe047bf5498af0a9fef4b790e802496054e9a1b
+  data.tar.gz: 1ca32485daec47aecb3f7befae1aed6e729d16fb5ec85660a084884fe1ecb26c6dfadefe5198b7100b3278eb976fd39689d38141074a3f49265709e72bbe24b9

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Utilvo (https://utilvo.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,79 @@
+# utilvo-shield-filters
+
+Zero-dependency JavaScript, TypeScript, Python, and Go parser for Adblock Plus 2.0 (`[Adblock Plus 2.0]`) and uBlock Origin static network filter rules.
+
+## Features
+
+- Parse standard `||domain^$third-party,domain=~example.com` network rules
+- Extract target hostnames, `$third-party` modifiers, and excluded context domains
+- Fast parent-domain suffix matching (`Set`-backed lookup) for hostname verification
+- Built-in fetcher for the `utilvo-shield-filters.txt` blocklist
+
+## Installation
+
+### Node.js
+
+```bash
+npm install utilvo-shield-filters
+```
+
+```javascript
+const { parseAbpRule, isHostBlocked, fetchFilterHosts } = require("utilvo-shield-filters");
+
+// Parse a single rule
+const rule = parseAbpRule("||01counter.com^$third-party,domain=~youtube.com");
+// => { domain: '01counter.com', thirdParty: true, excludedDomains: ['youtube.com'] }
+
+// Match a hostname against a Set of rules
+const blocked = new Set(["01counter.com"]);
+console.log(isHostBlocked("tracker.01counter.com", blocked)); // true
+```
+
+### Python
+
+```bash
+pip install utilvo-shield-filters
+```
+
+```python
+from utilvo_shield_filters import parse_abp_rule, is_host_blocked
+
+rule = parse_abp_rule("||01counter.com^$third-party,domain=~youtube.com")
+print(rule)
+# {'domain': '01counter.com', 'third_party': True, 'excluded_domains': ['youtube.com']}
+
+blocked = {"01counter.com"}
+print(is_host_blocked("sub.01counter.com", blocked))  # True
+```
+
+### Go
+
+```bash
+go get github.com/utilvo/utilvo-shield-filters@latest
+```
+
+```go
+package main
+
+import (
+	"fmt"
+	shieldfilters "github.com/utilvo/utilvo-shield-filters"
+)
+
+func main() {
+	domain, ok := shieldfilters.ParseAbpDomain("||01counter.com^$third-party")
+	if ok {
+		fmt.Println(domain) // 01counter.com
+	}
+}
+```
+
+## API Reference
+
+- `parseAbpRule(line)` / `parse_abp_rule(line)` / `ParseAbpDomain(line)`: Parses a single ABP 2.0 rule line and returns the normalized lowercase domain and rule options. Returns `null` / `None` for comments (`!`), headers (`[Adblock Plus 2.0]`), or cosmetic filters.
+- `isHostBlocked(hostname, blockedSet)` / `is_host_blocked(hostname, blocked_set)`: Checks whether `hostname` or any of its parent registrable labels exist in `blockedSet`.
+- `fetchFilterHosts(url?)` / `fetch_filter_hosts(url?)`: Downloads and parses a remote ABP filter list into a `Set` of domain strings.
+
+## License
+
+Code is licensed under the [MIT License](./LICENSE). Filter list rules are licensed under CC BY-SA 4.0.

data/lib/utilvo_shield_filters.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "set"
+
+# Zero-dependency parser and domain matcher for Adblock Plus 2.0 network filter rules.
+module UtilvoShieldFilters
+  VERSION = "1.0.0"
+  FILTER_LIST_URL = "https://utilvo.com/filters/utilvo-shield-filters.txt"
+  MIRROR_FILTER_LIST_URL = "https://utilvo.com/shield/filters.txt"
+  SHIELD_HOMEPAGE = "https://utilvo.com/shield"
+
+  module_function
+
+  def parse_abp_rule(line)
+    return nil unless line.is_a?(String)
+
+    trimmed = line.strip
+    return nil if trimmed.empty? || trimmed.start_with?("!", "[")
+    return nil unless trimmed.start_with?("||")
+
+    caret_idx = trimmed.index("^")
+    return nil if caret_idx.nil? || caret_idx <= 2
+
+    domain = trimmed[2...caret_idx].downcase
+    options_str = trimmed[(caret_idx + 1)..] || ""
+    third_party = false
+    excluded_domains = []
+
+    if options_str.start_with?("$")
+      options_str[1..].split(",").each do |opt|
+        if opt == "third-party" || opt == "3p"
+          third_party = true
+        elsif opt.start_with?("domain=")
+          opt[7..].split("|").each do |dom|
+            excluded_domains << dom[1..].downcase if dom.start_with?("~") && dom.length > 1
+          end
+        end
+      end
+    end
+
+    {
+      domain: domain,
+      third_party: third_party,
+      excluded_domains: excluded_domains
+    }
+  end
+
+  def host_blocked?(hostname, blocked_set)
+    return false if hostname.nil? || blocked_set.nil?
+
+    clean = hostname.strip.chomp(".").downcase
+    return false if clean.empty?
+
+    parts = clean.split(".")
+    return false if parts.length < 2
+
+    (0...(parts.length - 1)).any? do |i|
+      candidate = parts[i..].join(".")
+      blocked_set.include?(candidate)
+    end
+  end
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: utilvo-shield-filters
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Utilvo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-19 00:00:00.000000000 Z
+dependencies: []
+description: Parses Adblock Plus 2.0 and uBlock Origin static network filter rules (||domain^$third-party) and matches hostnames against domain blocklists.
+email: utilvo.com@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/utilvo_shield_filters.rb
+- README.md
+- LICENSE
+homepage: https://utilvo.com/shield
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://utilvo.com/shield
+  source_code_uri: https://github.com/utilvo/utilvo-shield-filters
+  bug_tracker_uri: https://github.com/utilvo/utilvo-shield-filters/issues
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key: 
+specification_version: 4
+summary: Zero-dependency parser and domain matcher for Adblock Plus 2.0 network filter rules.
+test_files: []