scamgate 0.3.3__py3-none-any.whl

scamgate/paygate.py

@@ -0,0 +1,228 @@
+"""Payment gating for the hook: money-moving tool calls get the same check as `check_payment`.
+
+Without this, `check_payment` is voluntary: an injected agent can pay through a wallet, banking or
+payments MCP tool, or a payments API call in a shell, without ever asking scamgate. The hook now:
+
+1. Spots a payment in a tool call: a tool whose name says it moves money (pay, payout, transfer,
+   withdraw, send_crypto...), or any tool whose arguments carry an amount AND a destination
+   account (IBAN, wallet address, account number).
+2. Pulls out payee, account, amount, currency and method from the arguments, and runs the normal
+   payment rules with local payee history (the agent's claims about the payee are ignored).
+3. Spots payments in shell/code: crypto CLIs (`cast send`, `bitcoin-cli sendtoaddress`,
+   `solana transfer`...) and write calls to payment APIs (Stripe, PayPal, Wise, Revolut Business...).
+   Those can't be scored, so a human approves them.
+
+Like the rest of the hook it never says "allow": a low-risk payment passes silently.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+# ---------------------------------------------------------------- tool names
+
+_STRONG = re.compile(r"(?:^|_)(?:pay|pays|payment|payments|payout|payouts|send_?money|send_?payment|withdraw|"
+                     r"withdrawal|wire|remit|remittance|disburse|sepa|send_?(?:eth|btc|sol|crypto|coin|coins|token|"
+                     r"tokens|usdc|usdt|funds|transaction|tx|native)|transfer_?(?:funds|money|eth|btc|sol|token|tokens|"
+                     r"crypto|usdc|usdt|native)|sign_?(?:and_?send_?)?transaction|capture_?(?:order|payment)|"
+                     r"create_?charge|charge_?card|tip)(?:_|$)")
+_WEAK = re.compile(r"(?:^|_)(?:transfer|send|order|buy|purchase|checkout|charge|swap|bridge|deposit|"
+                   r"top_?up|refund|invoice)(?:_|$)")
+
+# ---------------------------------------------------------------- argument keys
+
+_AMOUNT_KEYS = ("amount", "amount_value", "value", "sum", "total", "total_amount", "price", "amount_cents",
+                "amount_minor", "amount_in_cents", "unit_amount", "quantity_usd")
+_MINOR_KEYS = {"amount_cents", "amount_minor", "amount_in_cents", "unit_amount"}
+_CURRENCY_KEYS = ("currency", "ccy", "currency_code", "asset", "token", "coin", "symbol", "denom")
+_ACCOUNT_KEYS = ("iban", "payee_account", "beneficiary_account", "creditor_account", "account_number",
+                 "account", "to_address", "recipient_address", "destination_address", "wallet_address",
+                 "receiver_address", "address", "destination", "to", "recipient", "receiver", "payee",
+                 "beneficiary", "wallet", "sort_code", "routing_number", "card_number", "merchant_id", "pay_to")
+_NAME_KEYS = ("payee_name", "beneficiary_name", "recipient_name", "creditor_name", "account_holder",
+              "account_name", "holder_name", "merchant_name", "to_name", "name", "payee", "beneficiary",
+              "recipient", "merchant", "counterparty")
+_CONTEXT_KEYS = ("reference", "memo", "description", "note", "message", "purpose", "remittance_information",
+                 "statement_descriptor", "narrative", "comment", "details", "reason")
+_ACCOUNT_RE = re.compile(r"""(?ix)^(?:
+    [A-Z]{2}\d{2}[A-Z0-9 ]{10,32}            # IBAN
+  | 0x[0-9a-f]{40}                          # EVM address
+  | (?:bc1|[13])[a-z0-9]{25,62}             # bitcoin
+  | [1-9A-HJ-NP-Za-km-z]{32,44}             # base58 (Solana etc.)
+  | \d{6,18}                                # account number
+  | (?:acct|ba|card|cus|pm|src)_[A-Za-z0-9]{6,}  # Stripe-style ids
+  | [\w.+-]+@[\w-]+(?:\.[\w-]+)+            # email (PayPal payouts)
+  | \$[A-Za-z][\w-]{1,30}                   # cashtag
+  )$""")
+_CRYPTO = {"btc", "eth", "usdt", "usdc", "sol", "bnb", "xrp", "doge", "ada", "trx", "matic", "pol", "dai",
+           "ltc", "avax", "ton", "xmr", "arb", "op", "wbtc", "weth", "shib", "link", "dot", "atom"}
+
+
+@dataclass
+class Payment:
+    payee_name: str = ""
+    payee_account: str = ""
+    amount: float = 0.0
+    amount_known: bool = False
+    currency: str = ""
+    method: str = "other"
+    context: str = ""
+    why: str = ""
+
+
+@dataclass
+class CodePayment:
+    detail: str
+    hosts: list[str] = field(default_factory=list)
+
+
+def _flat(value: Any, out: dict[str, Any], depth: int = 0) -> dict[str, Any]:
+    """First value seen for each lowercased key, anywhere in the arguments."""
+    if depth > 12:
+        return out
+    if isinstance(value, dict):
+        for k, v in value.items():
+            key = str(k).lower().replace("-", "_")
+            if not isinstance(v, (dict, list)) and key not in out and v not in (None, ""):
+                out[key] = v
+        for v in value.values():
+            if isinstance(v, (dict, list)):
+                _flat(v, out, depth + 1)
+    elif isinstance(value, list):
+        for v in value[:20]:
+            _flat(v, out, depth + 1)
+    return out
+
+
+def _first(flat: dict[str, Any], keys: tuple[str, ...]) -> tuple[str, Any]:
+    for k in keys:
+        if k in flat:
+            return k, flat[k]
+    return "", None
+
+
+def _num(v: Any) -> float | None:
+    if isinstance(v, bool):
+        return None
+    if isinstance(v, (int, float)):
+        return float(v) if math.isfinite(v) else None  # JSON "Infinity"/"NaN" isn't an amount scamgate can read
+    if isinstance(v, str):
+        s = re.sub(r"[^\d.,-]", "", v)
+        if s.count(",") and s.count("."):
+            s = s.replace(",", "")
+        elif s.count(",") == 1 and len(s.split(",")[1]) in (1, 2):
+            s = s.replace(",", ".")
+        else:
+            s = s.replace(",", "")
+        try:
+            n = float(s)
+        except ValueError:
+            return None
+        return n if math.isfinite(n) else None  # a 309-digit string is inf too
+    return None
+
+
+def _looks_like_account(v: Any) -> bool:
+    return isinstance(v, str) and bool(_ACCOUNT_RE.match(v.strip()))
+
+
+def _method(tool: str, account: str, currency: str) -> str:
+    t, a, c = tool.lower(), account.strip(), currency.lower()
+    if c in _CRYPTO or re.match(r"^(?:0x[0-9a-fA-F]{40}|bc1|[13][a-km-zA-HJ-NP-Z1-9]{25,34}$)", a) \
+            or re.search(r"crypto|wallet|eth|btc|sol|token|coin|swap|bridge|onchain|web3", t):
+        return "crypto"
+    if "gift" in t:
+        return "gift_card"
+    if re.match(r"^[A-Z]{2}\d{2}", a.replace(" ", "")) or re.search(r"transfer|wire|sepa|payout|iban|bank|remit", t):
+        return "bank_transfer"
+    if re.search(r"card|checkout|charge|purchase|buy|order", t) or a.startswith(("card_", "pm_")):
+        return "card"
+    return "other"
+
+
+def detect(tool: str, canon: str, tool_input: dict) -> Payment | None:
+    """A Payment if this tool call moves money, else None."""
+    flat = _flat(tool_input, {})
+    akey, amount = _first(flat, _AMOUNT_KEYS)
+    amt = _num(amount)
+    if amt is not None and akey in _MINOR_KEYS:
+        amt = amt / 100
+    acct_key, account = next(((k, flat[k]) for k in _ACCOUNT_KEYS if k in flat and _looks_like_account(flat[k])),
+                             ("", None))
+    strong = bool(_STRONG.search(canon))
+    weak = bool(_WEAK.search(canon))
+    money_args = amt is not None and account is not None
+    if not (strong or money_args or (weak and amt is not None and (account is not None or
+                                                                    _first(flat, _CURRENCY_KEYS)[1]))):
+        return None
+    _, name = _first(flat, _NAME_KEYS)
+    if name is not None and (not isinstance(name, str) or name == account):
+        name = None
+    _, cur = _first(flat, _CURRENCY_KEYS)
+    ctx = " ".join(str(flat[k]) for k in _CONTEXT_KEYS if k in flat and isinstance(flat[k], str))[:2000]
+    acct = str(account).strip() if account is not None else ""
+    return Payment(
+        payee_name=(str(name).strip() if name else acct)[:200],
+        payee_account=acct[:200],
+        amount=max(amt or 0.0, 0.0),
+        amount_known=amt is not None,
+        currency=(str(cur).upper()[:12] if cur else ""),
+        method=_method(canon + " " + tool, acct, str(cur or "")),
+        context=ctx,
+        why="the tool name" if strong else "an amount and a destination account in the arguments",
+    )
+
+
+# ---------------------------------------------------------------- shell / code
+
+_CRYPTO_CLI = re.compile(r"""(?ix)\b(?:
+    cast\s+(?:send|publish)\b | bitcoin-cli\b[^\n]*\b(?:sendtoaddress|sendmany|sendrawtransaction|send|walletcreatefundedpsbt)\b
+  | electrum\b[^\n]*\b(?:payto|paytomany|broadcast)\b | solana\s+transfer\b | spl-token\s+transfer\b
+  | near\s+(?:send|tokens)\b | aptos\s+account\s+transfer\b | sui\s+client\s+(?:transfer|pay|pay-sui|pay-all-sui)\b
+  | lncli\s+(?:sendpayment|payinvoice|sendcoins)\b | lightning-cli\s+(?:pay|withdraw|keysend)\b
+  | eth_sendTransaction | eth_sendRawTransaction | sendRawTransaction\( | sendTransaction\( | signAndSendTransaction
+  | web3\.eth\.send | \.functions\.transfer\( | wallet\.send_?(?:transaction|coins)\(
+  )""")
+_PAY_HOSTS = ("api.stripe.com", "api.paypal.com", "api-m.paypal.com", "api.wise.com", "api.transferwise.com",
+              "b2b.revolut.com", "api.revolut.com", "api.coinbase.com", "api.commerce.coinbase.com",
+              "api.gocardless.com", "adyenpayments.com", "api.adyen.com", "api.checkout.com", "api.mollie.com",
+              "connect.squareup.com", "api.squareup.com", "api.braintreegateway.com", "api.razorpay.com",
+              "api.paystack.co", "api.kraken.com", "api.binance.com", "api.circle.com", "api.moonpay.com",
+              "api.monzo.com", "api.starlingbank.com", "api.truelayer.com", "api.modulrfinance.com",
+              "api.currencycloud.com", "api.airwallex.com", "api.payoneer.com", "api.bitpay.com")
+_PAY_PATH = re.compile(r"(?i)/(?:[\w-]*/)*(?:pay|payments?|payouts?|transfers?|charges?|payment_intents|"
+                       r"checkout|orders?|withdraw\w*|send\w*|disburse\w*|refunds?|captures?|"
+                       r"capital/withdraw|quotes?|batch_payments)\b")
+_WRITE = re.compile(r"""(?ix)(?:\s-X\s*['"]?(?:POST|PUT|PATCH)\b|\s--request\s+['"]?(?:POST|PUT|PATCH)\b|\s-d[\s'"@]|
+                       \s--data\b|\s--data-\w+\b|\s--json\b|\s-F\s|\.post\(|\.put\(|\.patch\(|
+                       method\s*[:=]\s*['"](?:post|put|patch)['"]|request\(\s*['"](?:post|put|patch)['"]|
+                       Invoke-(?:RestMethod|WebRequest)\b[^\n]*-Method\s+(?:Post|Put|Patch))""")
+_HOST_IN = re.compile(r"(?i)https?://([a-z0-9.-]+)(/[^\s'\"`)]*)?")
+
+
+_SDK_PAY = re.compile(
+    r"(?i)\bstripe\.(?:Payout|PaymentIntent|Transfer|Charge|Refund|Subscription)\.create\b"
+    r"|\bpaypal\.Payout\b|\.payouts\(\)\.create\b"
+)
+
+
+def scan_code(code: str) -> CodePayment | None:
+    if m := _CRYPTO_CLI.search(code):
+        return CodePayment(f"a crypto transaction ('{m.group(0).strip()[:40]}')")
+    if m := _SDK_PAY.search(code):
+        return CodePayment(f"a payment SDK call ('{m.group(0).strip()[:40]}')")
+    if not _WRITE.search(code):
+        return None
+    hosts = []
+    for m in _HOST_IN.finditer(code):
+        host, path = m.group(1).lower(), m.group(2) or ""
+        if "sandbox" in host or ".test" in host or "-test" in host:
+            continue
+        if any(host == h or host.endswith("." + h) for h in _PAY_HOSTS) and _PAY_PATH.search(path):
+            hosts.append(host)
+    if hosts:
+        return CodePayment(f"a payment API call to {hosts[0]}", hosts)
+    return None

scamgate/plugin.py

@@ -0,0 +1,222 @@
+"""Hermes plugin: the same gate as the shell hook, in-process.
+
+Hermes calls `pre_tool_call` before every tool. This returns the hook's decision.
+Under `/yolo` or `approvals.mode: off`, Hermes would auto-approve an ask, so an ask
+becomes a block unless the user set `when_approvals_off: allow`.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+from typing import Any
+
+from pydantic import BaseModel, ValidationError
+
+from . import asklog, hook, refresh, tools
+
+_CTX: Any = None
+_log = logging.getLogger("scamgate")
+
+
+def approvals_bypassed(session_id: str = "") -> bool:
+    """True when this chat will not actually ask a human. Importing Hermes is optional."""
+    try:
+        from tools.approval import is_approval_bypass_active_for_session
+    except Exception:
+        return False
+    try:
+        return bool(is_approval_bypass_active_for_session(session_id or ""))
+    except Exception:
+        return False
+
+
+def when_approvals_off() -> str:
+    val = None
+    if _CTX is not None:
+        try:
+            val = _CTX.get_config("when_approvals_off", None)
+        except Exception:
+            val = None
+    if not val:
+        val = os.environ.get("SCAMGATE_WHEN_APPROVALS_OFF", "block")
+    return str(val).strip().lower()
+
+
+def on_pre_tool_call(tool_name: str = "", args: Any = None, session_id: str = "",
+                     tool_call_id: str = "", task_id: str = "", **_: Any) -> dict | None:
+    try:
+        decision = hook.handle({
+            "hook_event_name": "pre_tool_call",
+            "tool_name": tool_name,
+            "tool_input": args if isinstance(args, dict) else {},
+            "session_id": session_id or task_id or "",
+            "extra": {"tool_call_id": tool_call_id or "", "task_id": task_id or ""},
+        })
+    except Exception as exc:  # fail closed like the shell hook; don't rely on how Hermes treats a raising hook
+        return {"action": "block", "message": f"scamgate hook error, failing closed: {type(exc).__name__}: "
+                                              f"{str(exc)[:200]}"}
+    if not decision:
+        return None
+    if decision.get("action") == "approve" and approvals_bypassed(session_id) and when_approvals_off() != "allow":
+        message = decision.get("message") or "scamgate would have asked a human."
+        return {"action": "block", "message": message + " Approvals are off in this chat, so scamgate blocked it "
+                                              "instead of asking. Turn approvals back on, or set "
+                                              "plugins.entries.scamgate.settings.when_approvals_off to allow if you "
+                                              "accept that risk."}
+    return decision
+
+
+def on_post_tool_call(tool_name: str = "", session_id: str = "", tool_call_id: str = "",
+                      task_id: str = "", status: str | None = None, **_: Any) -> None:
+    try:
+        hook.handle({
+            "hook_event_name": "post_tool_call",
+            "tool_name": tool_name,
+            "tool_input": {},
+            "session_id": session_id or task_id or "",
+            "extra": {"tool_call_id": tool_call_id or "", "task_id": task_id or "", "status": status},
+        })
+    except Exception:
+        pass  # a post event only records whether you approved; it must never break the tool call
+    return None
+
+
+def _run_tool(fn: Any, model: type[BaseModel], args: Any) -> str:
+    """Same arguments and checks as the MCP tool. Bad arguments come back as an error, never a crash."""
+    try:
+        parsed = model.model_validate(args if isinstance(args, dict) else {})
+    except ValidationError as exc:
+        problems = "; ".join(f"{'.'.join(map(str, e['loc'])) or 'arguments'}: {e['msg']}" for e in exc.errors())
+        return json.dumps({"error": f"scamgate couldn't read these arguments ({problems})."})
+    return json.dumps(fn(parsed).model_dump(mode="json"))
+
+
+def check_url(args: dict, **_: Any) -> str:
+    return _run_tool(tools.check_url, tools.UrlArgs, args)
+
+
+def check_payment(args: dict, **_: Any) -> str:
+    return _run_tool(tools.check_payment, tools.PaymentArgs, args)
+
+
+def slash(raw_args: str = "") -> str:
+    """`/scamgate status | review | update`. Hermes runs this in a worker thread, so `update` can download."""
+    cmd = (raw_args or "").strip().lower()
+    if cmd in ("", "status"):
+        try:
+            from .feeds import LazyFeedIndex
+            feeds = LazyFeedIndex()
+            if not feeds:
+                return "scamgate: no phishing lists cached. Run `/scamgate update` to download them."
+            _, lines = refresh.status()
+            stale = sorted(feeds.stale_feeds(hours=24))
+            head = ("scamgate: lists are stale (" + ", ".join(stale) + "). Run `/scamgate update`." if stale
+                    else "scamgate: phishing lists are loaded.")
+            return head + "\n" + "\n".join(lines)
+        except Exception as exc:
+            return f"scamgate: could not read feed status ({type(exc).__name__})."
+    if cmd == "review":
+        rows = asklog.summarize(days=7)
+        if not rows:
+            return "scamgate: nothing in the ask log for the last 7 days."
+        lines = []
+        for r in rows[:8]:
+            top = next(iter(r.rules), "")
+            lines.append(f"{r.host}: {r.asks} asked ({r.ran} approved, {r.not_run} refused, {r.pending} pending), "
+                         f"{r.blocks} blocked" + (f"; top rule {top}" if top else ""))
+        return "scamgate, last 7 days:\n" + "\n".join(lines)
+    if cmd == "update":
+        return refresh.refresh().text()
+    return "Usage: /scamgate status | review | update"
+
+
+def update_feeds_tool(args: Any = None, **_: Any) -> str:
+    """The agent's refresh button. It takes no arguments: whatever the agent sends is ignored, the default
+    feeds are downloaded from their fixed sources into the configured cache, at most once an hour."""
+    try:
+        out = refresh.refresh(if_older_than_hours=refresh.TOOL_MIN_GAP_HOURS)
+    except Exception as exc:  # a full disk or a broken cache folder must not crash the chat
+        return json.dumps({"updated": [], "failed": {"all": f"{type(exc).__name__}: {str(exc)[:200]}"},
+                           "skipped": ""})
+    return json.dumps({**out.as_dict(), "summary": out.text()})
+
+
+# ---------------------------------------------------------------- background refresh
+
+AUTO_FIRST_DELAY = 120.0  # seconds; a short-lived `hermes ...` command exits before the first pass
+AUTO_EVERY = 30 * 60.0  # seconds between checks; a pass downloads only when the lists are 6 hours old
+
+
+def auto_update_enabled(ctx: Any = None) -> bool:
+    """On unless SCAMGATE_AUTO_UPDATE is off, or plugins.entries.scamgate.settings.auto_update_feeds is false."""
+    env = os.environ.get("SCAMGATE_AUTO_UPDATE")
+    if env is not None and env.strip().lower() in refresh.OFF_VALUES:
+        return False
+    val = None
+    if ctx is not None:
+        try:
+            val = ctx.get_config("auto_update_feeds", None)
+        except Exception:
+            val = None
+    if isinstance(val, str):
+        return val.strip().lower() not in refresh.OFF_VALUES
+    return val is None or bool(val)
+
+
+def start_auto_update(ctx: Any = None) -> threading.Thread | None:
+    """One daemon thread per process. Processes share the lock file, so only one downloads at a time."""
+    if not auto_update_enabled(ctx):
+        return None
+    return refresh.start_background(first_delay=AUTO_FIRST_DELAY, every=AUTO_EVERY,
+                                    on_unload=getattr(ctx, "on_unload", None))
+
+
+def _parameters(model: type[BaseModel]) -> dict:
+    """The tool's JSON schema for Hermes, from the same model the MCP tool uses (minus titles and null branches)."""
+    schema = model.model_json_schema()
+    props = {}
+    for name, prop in schema["properties"].items():
+        prop = {k: v for k, v in prop.items() if k not in ("title", "default")}
+        if "anyOf" in prop:
+            branches = [b for b in prop.pop("anyOf") if b.get("type") != "null"]
+            if len(branches) == 1:
+                prop.update(branches[0])
+            else:
+                prop["anyOf"] = branches
+        props[name] = prop
+    return {"type": "object", "properties": props, "required": schema.get("required", [])}
+
+
+_URL_SCHEMA = {"name": "scamgate_check_url", "description": tools.URL_DESCRIPTION,
+               "parameters": _parameters(tools.UrlArgs)}
+_PAY_SCHEMA = {"name": "scamgate_check_payment", "description": tools.PAYMENT_DESCRIPTION,
+               "parameters": _parameters(tools.PaymentArgs)}
+UPDATE_DESCRIPTION = tools.UPDATE_DESCRIPTION
+_UPDATE_SCHEMA = {"name": "scamgate_update_feeds", "description": UPDATE_DESCRIPTION,
+                  "parameters": {"type": "object", "properties": {}, "additionalProperties": False}}
+
+
+def register(ctx) -> None:
+    global _CTX
+    _CTX = ctx
+    ctx.register_hook("pre_tool_call", on_pre_tool_call)
+    ctx.register_hook("post_tool_call", on_post_tool_call)
+    ctx.register_tool(name="scamgate_check_url", toolset="scamgate", schema=_URL_SCHEMA, handler=check_url,
+                      description=_URL_SCHEMA["description"], emoji="🛡️")
+    ctx.register_tool(name="scamgate_check_payment", toolset="scamgate", schema=_PAY_SCHEMA, handler=check_payment,
+                      description=_PAY_SCHEMA["description"], emoji="🛡️")
+    ctx.register_tool(name="scamgate_update_feeds", toolset="scamgate", schema=_UPDATE_SCHEMA,
+                      handler=update_feeds_tool, description=UPDATE_DESCRIPTION, emoji="🛡️")
+    ctx.register_command("scamgate", slash, description="scamgate status, review, or update the phishing lists",
+                         args_hint="status|review|update")
+    if callable(getattr(ctx, "register_cli_command", None)):  # Hermes builds without it just skip the CLI
+        try:
+            ctx.register_cli_command("scamgate", help="scamgate phishing lists: update-feeds, feeds-status",
+                                     setup_fn=refresh.setup_cli, handler_fn=refresh.cli_main,
+                                     description="Refresh or inspect scamgate's cached phishing lists.")
+        except Exception:  # a CLI that can't be wired must never stop the gate from loading
+            _log.warning("scamgate: could not add `hermes scamgate`", exc_info=True)
+    start_auto_update(ctx)

scamgate/plugin.yaml

@@ -0,0 +1,24 @@
+name: scamgate
+version: "0.3.3"
+description: "Offline scam gate. Blocks known-bad links and payments before a tool runs, and asks a human when it cannot see the destination."
+author: Odai Ameera
+requires_hermes: ">=0.19.1"
+provides_hooks:
+  - pre_tool_call
+  - post_tool_call
+provides_tools:
+  - scamgate_check_url
+  - scamgate_check_payment
+  - scamgate_update_feeds
+python_dependencies:
+  - "pydantic>=2.7,<3"
+  - "pyyaml>=6.0,<7"
+config_schema:
+  when_approvals_off:
+    type: str
+    description: "When Hermes approvals are off, block asks (default) or allow them."
+    default: block
+  auto_update_feeds:
+    type: bool
+    description: "Refresh the phishing lists in the background every 6 hours (default on). Set false to refresh only with /scamgate update or hermes scamgate update-feeds."
+    default: true

scamgate/redact.py

@@ -0,0 +1,93 @@
+"""Strip secrets before anything is written to disk.
+
+Logs must be safe to read and share: no passwords, query-string values, card numbers,
+full IBANs, emails, API keys, tokens or seed phrases.
+"""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import parse_qsl, urlsplit, urlunsplit
+
+_LONG_TOKEN = re.compile(r"(?<![A-Za-z0-9])[A-Za-z0-9_\-]{24,}(?![A-Za-z0-9])")
+_CARD = re.compile(r"(?<!\d)(?:\d[ -]?){12,18}\d(?!\d)")
+_IBAN = re.compile(r"(?i)\b([A-Z]{2}\d{2})((?:[ ]?[A-Z0-9]){10,30})\b")
+_EMAIL = re.compile(r"\b[\w.+-]+@([\w-]+(?:\.[\w-]+)+)\b")
+_KV_SECRET = re.compile(r"(?i)\b(password|passwd|passphrase|passcode|pwd|secret|token|api[_-]?key|otp|pin|cvv|cvc)"
+                        r"(\s*[=:]\s*|\s+(?:is|was|=)\s+)(\S+)")
+_KEYLIKE = re.compile(r"\b(?:sk|pk|rk|ghp|gho|ghs|ghu|ghr|github_pat|glpat|xox[abprs]|AKIA|ASIA|AIza|hf|npm|pypi)"
+                      r"[-_][-_A-Za-z0-9]{10,}|\bAKIA[0-9A-Z]{16}\b|\bAIza[-_A-Za-z0-9]{20,}")
+_JWT = re.compile(r"\beyJ[\w-]{4,}\.[\w-]{4,}\.[\w-]{4,}")
+_HIGH_ENTROPY = re.compile(r"(?<![\w/+=-])(?=[\w/+=-]*[a-z])(?=[\w/+=-]*[A-Z])(?=[\w/+=-]*\d)[\w/+=-]{30,}(?![\w/+=-])")
+_SEED = re.compile(r"(?i)\b(seed(?:\s*phrase)?|mnemonic|recovery\s*(?:phrase|words)|secret\s*(?:phrase|words))"
+                   r"(\W{0,3})((?:[a-z]{3,8}[\s,]+){11,23}[a-z]{3,8})\b")
+
+
+def _luhn_ok(digits: str) -> bool:
+    total, alt = 0, False
+    for ch in reversed(digits):
+        n = int(ch)
+        if alt:
+            n *= 2
+            if n > 9:
+                n -= 9
+        total += n
+        alt = not alt
+    return total % 10 == 0
+
+
+def iban_ok(iban: str) -> bool:
+    s = re.sub(r"\s", "", iban).upper()
+    if not re.fullmatch(r"[A-Z]{2}\d{2}[A-Z0-9]{10,30}", s):
+        return False
+    digits = "".join(str(int(c, 36)) for c in s[4:] + s[:4])
+    return int(digits) % 97 == 1
+
+
+def _mask_cards(text: str) -> str:
+    def repl(m: re.Match) -> str:
+        digits = re.sub(r"\D", "", m.group(0))
+        return "<card>" if 13 <= len(digits) <= 19 and _luhn_ok(digits) else m.group(0)
+    return _CARD.sub(repl, text)
+
+
+def _mask_iban(text: str) -> str:
+    def repl(m: re.Match) -> str:
+        whole = m.group(0)
+        if whole.isupper() or iban_ok(whole):  # lowercase only when the checksum proves it's an IBAN
+            return f"{m.group(1).upper()}<iban>"
+        return whole
+    return _IBAN.sub(repl, text)
+
+
+def _mask_secrets(t: str) -> str:
+    t = _SEED.sub(lambda m: f"{m.group(1)}{m.group(2)}<seed>", t)
+    t = _KV_SECRET.sub(lambda m: f"{m.group(1)}{m.group(2)}<redacted>", t)
+    t = _JWT.sub("<jwt>", t)
+    t = _KEYLIKE.sub("<key>", t)
+    t = _HIGH_ENTROPY.sub("<secret>", t)
+    t = _mask_cards(t)
+    t = _mask_iban(t)
+    return _EMAIL.sub(lambda m: f"<email>@{m.group(1)}", t)
+
+
+def redact_text(text: str, limit: int = 300) -> str:
+    t = _mask_secrets(text or "")
+    t = re.sub(r"\s+", " ", t).strip()
+    return t if len(t) <= limit else t[:limit] + "…"
+
+
+def redact_url(url: str) -> str:
+    """Keep scheme, host, port and path shape; drop userinfo, query values, fragment and secrets in the path."""
+    raw = (url or "").strip()
+    try:
+        p = urlsplit(raw if "://" in raw else "http://" + raw)
+        host = p.hostname or ""
+        port = f":{p.port}" if p.port else ""
+    except ValueError:
+        return "<unparseable-url>"
+    user = "<user>@" if p.username else ""
+    path = _mask_secrets(p.path)
+    path = _LONG_TOKEN.sub("<token>", path)
+    query = "&".join(f"{k}=" for k, _ in parse_qsl(p.query, keep_blank_values=True))
+    return urlunsplit((p.scheme, f"{user}{host}{port}", path, query, ""))