@url-sanitize/core 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Antonio Orionus
+
+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.
+
+Note: this MIT license applies to the @url-sanitize/core, @url-sanitize/cli,
+@url-sanitize/fetch, and @url-sanitize/action packages. The
+@url-sanitize/clearurls package ships a catalog derived from the ClearURLs
+ruleset and is licensed under LGPL-3.0-only for that bundled data. See
+packages/clearurls/LICENSE and docs/license-model.md for details.

package/README.md

@@ -0,0 +1,47 @@
+# @url-sanitize/core
+
+Pure TypeScript URL sanitization engine with explainable results and pluggable catalogs.
+
+## Install
+
+```sh
+npm install @url-sanitize/core @url-sanitize/clearurls
+```
+
+## Usage
+
+```ts
+import { compileSanitizer } from '@url-sanitize/core';
+import { clearurlsCatalog } from '@url-sanitize/clearurls';
+
+const sanitize = compileSanitizer(clearurlsCatalog, {
+  stripReferralMarketing: false,
+  unwrapRedirects: true,
+  domainBlocking: false
+});
+
+const result = sanitize('https://example.com/?utm_source=x&id=123');
+```
+
+## Result shape
+
+```ts
+type SanitizeResult =
+  | { kind: 'unchanged'; url: string }
+  | { kind: 'cleaned'; original: string; url: string;
+      strippedParams: string[]; matchedRules: MatchedRule[] }
+  | { kind: 'redirected'; original: string; url: string; via: MatchedRule }
+  | { kind: 'blocked'; original: string; via: MatchedRule };
+```
+
+## Design
+
+- Zero runtime dependencies.
+- Pure function; no I/O.
+- Catalog-agnostic: any source (ClearURLs, AdGuard, custom) that produces a `SanitizerCatalog` works.
+- Factory pattern (`compileSanitizer(catalog)`) — no module-level cache, no singletons.
+- Discriminated union return type — exhaustive `switch (result.kind)`.
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+type RuleSource = 'clearurls' | 'adguard' | 'brave' | 'firefox' | 'custom';
+type SanitizerRule = {
+    kind: 'strip-param';
+    source: RuleSource;
+    provider: string;
+    urlPattern?: string;
+    paramPattern: string;
+    exceptions?: string[];
+    isReferralMarketing?: boolean;
+} | {
+    kind: 'raw-replace';
+    source: RuleSource;
+    provider: string;
+    urlPattern?: string;
+    pattern: string;
+    replacement: string;
+    exceptions?: string[];
+} | {
+    kind: 'unwrap-redirect';
+    source: RuleSource;
+    provider: string;
+    urlPattern?: string;
+    pattern: string;
+    captureGroup: number;
+    exceptions?: string[];
+} | {
+    kind: 'block-domain';
+    source: RuleSource;
+    provider: string;
+    urlPattern: string;
+    exceptions?: string[];
+};
+interface SanitizerCatalog {
+    version: string;
+    generatedAt: string;
+    sources: Array<{
+        name: RuleSource;
+        version?: string;
+        hash?: string;
+        license?: string;
+        upstream?: string;
+    }>;
+    rules: SanitizerRule[];
+}
+interface MatchedRule {
+    source: RuleSource;
+    provider: string;
+    kind: SanitizerRule['kind'];
+    detail?: string;
+}
+type SanitizeResult = {
+    kind: 'unchanged';
+    url: string;
+} | {
+    kind: 'cleaned';
+    original: string;
+    url: string;
+    strippedParams: string[];
+    matchedRules: MatchedRule[];
+} | {
+    kind: 'redirected';
+    original: string;
+    url: string;
+    via: MatchedRule;
+} | {
+    kind: 'blocked';
+    original: string;
+    via: MatchedRule;
+};
+interface SanitizerOptions {
+    stripReferralMarketing?: boolean;
+    unwrapRedirects?: boolean;
+    domainBlocking?: boolean;
+}
+
+type Sanitizer = (input: string) => SanitizeResult;
+declare function compileSanitizer(catalog: SanitizerCatalog, options?: SanitizerOptions): Sanitizer;
+
+export { type MatchedRule, type RuleSource, type SanitizeResult, type Sanitizer, type SanitizerCatalog, type SanitizerOptions, type SanitizerRule, compileSanitizer };

package/dist/index.js

@@ -0,0 +1,219 @@
+// src/sanitize.ts
+function safeRegex(pattern, flags = "") {
+  try {
+    return new RegExp(pattern, flags);
+  } catch {
+    return null;
+  }
+}
+function compileExceptions(patterns) {
+  if (!patterns) return [];
+  const out = [];
+  for (const p of patterns) {
+    const re = safeRegex(p, "");
+    if (re) out.push(re);
+  }
+  return out;
+}
+function compileRule(rule) {
+  switch (rule.kind) {
+    case "strip-param": {
+      const paramPattern = safeRegex(`^(?:${rule.paramPattern})$`, "i");
+      if (!paramPattern) return null;
+      const urlPattern = rule.urlPattern ? safeRegex(rule.urlPattern, "i") : null;
+      if (rule.urlPattern && !urlPattern) return null;
+      return {
+        kind: "strip-param",
+        source: rule.source,
+        provider: rule.provider,
+        urlPattern,
+        paramPattern,
+        exceptions: compileExceptions(rule.exceptions),
+        isReferralMarketing: rule.isReferralMarketing ?? false
+      };
+    }
+    case "raw-replace": {
+      const pattern = safeRegex(rule.pattern, "gi");
+      if (!pattern) return null;
+      const urlPattern = rule.urlPattern ? safeRegex(rule.urlPattern, "i") : null;
+      if (rule.urlPattern && !urlPattern) return null;
+      return {
+        kind: "raw-replace",
+        source: rule.source,
+        provider: rule.provider,
+        urlPattern,
+        pattern,
+        replacement: rule.replacement,
+        exceptions: compileExceptions(rule.exceptions)
+      };
+    }
+    case "unwrap-redirect": {
+      const pattern = safeRegex(rule.pattern, "i");
+      if (!pattern) return null;
+      const urlPattern = rule.urlPattern ? safeRegex(rule.urlPattern, "i") : null;
+      if (rule.urlPattern && !urlPattern) return null;
+      return {
+        kind: "unwrap-redirect",
+        source: rule.source,
+        provider: rule.provider,
+        urlPattern,
+        pattern,
+        captureGroup: rule.captureGroup,
+        exceptions: compileExceptions(rule.exceptions)
+      };
+    }
+    case "block-domain": {
+      const urlPattern = safeRegex(rule.urlPattern, "i");
+      if (!urlPattern) return null;
+      return {
+        kind: "block-domain",
+        source: rule.source,
+        provider: rule.provider,
+        urlPattern,
+        exceptions: compileExceptions(rule.exceptions)
+      };
+    }
+  }
+}
+function safeDecode(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+function matchesAny(url, patterns) {
+  return patterns.some((re) => re.test(url));
+}
+function appliesTo(rule, url) {
+  if (rule.kind !== "block-domain" && rule.urlPattern && !rule.urlPattern.test(url)) {
+    return false;
+  }
+  if (rule.kind === "block-domain" && !rule.urlPattern.test(url)) return false;
+  if (matchesAny(url, rule.exceptions)) return false;
+  return true;
+}
+function compileSanitizer(catalog, options = {}) {
+  const {
+    stripReferralMarketing = false,
+    unwrapRedirects = true,
+    domainBlocking = false
+  } = options;
+  const compiled = [];
+  for (const rule of catalog.rules) {
+    const c = compileRule(rule);
+    if (c) compiled.push(c);
+  }
+  return function sanitize(input) {
+    let parsed;
+    try {
+      parsed = new URL(input);
+    } catch {
+      return { kind: "unchanged", url: input };
+    }
+    let current = parsed.toString();
+    const original = input;
+    const strippedParams = [];
+    const matchedRules = [];
+    for (const rule of compiled) {
+      if (!appliesTo(rule, current)) continue;
+      switch (rule.kind) {
+        case "block-domain": {
+          if (!domainBlocking) continue;
+          return {
+            kind: "blocked",
+            original,
+            via: { source: rule.source, provider: rule.provider, kind: rule.kind }
+          };
+        }
+        case "unwrap-redirect": {
+          if (!unwrapRedirects) continue;
+          const m = rule.pattern.exec(current);
+          const captured = m?.[rule.captureGroup];
+          if (typeof captured === "string" && captured.length > 0) {
+            const target = safeDecode(captured);
+            try {
+              const targetUrl = new URL(target);
+              return {
+                kind: "redirected",
+                original,
+                url: targetUrl.toString(),
+                via: { source: rule.source, provider: rule.provider, kind: rule.kind }
+              };
+            } catch {
+            }
+          }
+          continue;
+        }
+        case "raw-replace": {
+          const next = current.replace(rule.pattern, rule.replacement);
+          if (next !== current) {
+            current = next;
+            matchedRules.push({
+              source: rule.source,
+              provider: rule.provider,
+              kind: rule.kind
+            });
+          }
+          continue;
+        }
+        case "strip-param": {
+          if (rule.isReferralMarketing && !stripReferralMarketing) continue;
+          let urlObj;
+          try {
+            urlObj = new URL(current);
+          } catch {
+            continue;
+          }
+          const search = stripFromQueryString(urlObj.search, rule.paramPattern);
+          const hash = stripFromQueryString(urlObj.hash, rule.paramPattern);
+          const removed = [...search.removed, ...hash.removed];
+          if (removed.length === 0) continue;
+          urlObj.search = search.result;
+          urlObj.hash = hash.result;
+          current = urlObj.toString();
+          strippedParams.push(...removed);
+          matchedRules.push({
+            source: rule.source,
+            provider: rule.provider,
+            kind: rule.kind,
+            detail: removed.join(",")
+          });
+          continue;
+        }
+      }
+    }
+    if (current === original) return { kind: "unchanged", url: original };
+    return {
+      kind: "cleaned",
+      original,
+      url: current,
+      strippedParams,
+      matchedRules
+    };
+  };
+}
+function stripFromQueryString(searchOrHash, paramPattern) {
+  if (!searchOrHash) return { result: searchOrHash, removed: [] };
+  const prefix = searchOrHash.charAt(0);
+  const body = prefix === "?" || prefix === "#" ? searchOrHash.slice(1) : searchOrHash;
+  if (!body) return { result: searchOrHash, removed: [] };
+  const pairs = body.split("&").filter(Boolean);
+  const kept = [];
+  const removed = [];
+  for (const pair of pairs) {
+    const eqIdx = pair.indexOf("=");
+    const name = eqIdx === -1 ? pair : pair.slice(0, eqIdx);
+    if (paramPattern.test(name)) {
+      removed.push(name);
+    } else {
+      kept.push(pair);
+    }
+  }
+  if (removed.length === 0) return { result: searchOrHash, removed: [] };
+  if (kept.length === 0) return { result: "", removed };
+  return { result: prefix + kept.join("&"), removed };
+}
+export {
+  compileSanitizer
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@url-sanitize/core",
+  "version": "0.1.0",
+  "description": "Pure TypeScript URL sanitization engine with explainable results and pluggable catalogs.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "url",
+    "sanitize",
+    "tracking",
+    "clearurls",
+    "privacy"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/antonio-orionus/url-sanitize.git",
+    "directory": "packages/core"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch"
+  }
+}