scrubbr 0.2.0__py3-none-any.whl

scrubbr/__init__.py

@@ -0,0 +1,6 @@
+from scrubbr.alias import AliasBook
+from scrubbr.identity import LocalIdentity
+from scrubbr.kinds import Finding, Kind
+from scrubbr.scrub import ScrubResult, scrub
+
+__all__ = ["AliasBook", "Finding", "Kind", "LocalIdentity", "ScrubResult", "scrub"]

scrubbr/alias.py

@@ -0,0 +1,38 @@
+import random
+
+from scrubbr.kinds import Kind
+from scrubbr.shapes import mint, normalize, render
+
+
+class AliasBook:
+    """The only thing that may mint an alias.
+
+    Callers ask for the alias of a value and cannot obtain an inconsistent answer, which
+    is what makes "one value, one replacement" a structural guarantee rather than a
+    convention every call site has to remember.
+    """
+
+    def __init__(self, rng: random.Random | None = None) -> None:
+        # SystemRandom is the CSPRNG secrets is built on; a seeded Random makes the
+        # output reproducible, which tests and correlated multi-document runs need.
+        self._rng = rng if rng is not None else random.SystemRandom()
+        self._canonical: dict[tuple[Kind, str], str] = {}
+        self._issued: dict[Kind, int] = {}
+
+    def alias_for(self, kind: Kind, text: str) -> str:
+        canonical = self.canonical_alias(kind, normalize(kind, text))
+        return render(kind, canonical, text)
+
+    def canonical_alias(self, kind: Kind, normalized: str) -> str:
+        key = (kind, normalized)
+        existing = self._canonical.get(key)
+        if existing is not None:
+            return existing
+        minted = mint(kind, normalized, self._rng, self._next(kind))
+        self._canonical[key] = minted
+        return minted
+
+    def _next(self, kind: Kind) -> int:
+        index = self._issued.get(kind, 0)
+        self._issued[kind] = index + 1
+        return index

scrubbr/cli.py

@@ -0,0 +1,168 @@
+import argparse
+import io
+import os
+import shutil
+import sys
+from collections import Counter
+from collections.abc import Callable
+from dataclasses import replace
+from importlib.metadata import version
+from pathlib import Path
+
+import structlog
+
+from scrubbr.identity import LocalIdentity
+from scrubbr.report import clip, render_report
+from scrubbr.review import NoTerminal, Terminal, confirm, open_terminal
+from scrubbr.scrub import ScrubResult, scrub
+
+
+def _configure_logging() -> None:
+    renderer = (
+        structlog.dev.ConsoleRenderer(colors=sys.stderr.isatty())
+        if sys.stderr.isatty()
+        else structlog.processors.JSONRenderer()
+    )
+    structlog.configure(
+        processors=[structlog.processors.add_log_level, renderer],
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stderr),
+    )
+
+
+def _parse(argv: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="scrubbr",
+        description="Sanitize Linux diagnostics before pasting them into an LLM.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {version('scrubbr')}",
+    )
+    parser.add_argument(
+        "infile",
+        nargs="?",
+        # Kernel and firmware strings in dmesg are not always valid UTF-8, and crashing on
+        # a decode error would lose whatever the caller piped in.
+        type=lambda path: argparse.FileType("r", encoding="utf-8", errors="replace")(path),
+        default=None,
+        help="file to read; defaults to stdin",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        metavar="FILE",
+        help="write the scrubbed text to FILE instead of stdout",
+    )
+    parser.add_argument(
+        "-y",
+        "--no-review",
+        action="store_true",
+        help="skip the interactive review",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="also report each replaced value with its count and alias"
+        " (prints the original values to stderr)",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="refuse to emit anything while unscrubbed suspicious strings remain",
+    )
+    parser.add_argument(
+        "--no-identity",
+        action="store_true",
+        help="do not seed the scanner with this machine's hostname, user and machine-id",
+    )
+    parser.add_argument(
+        "--also",
+        action="append",
+        default=[],
+        metavar="TEXT",
+        help="scrub this value too; repeatable. IPs are always replaced (even private or"
+        " loopback), long hex, UUIDs and emails keep their shape; anything else becomes"
+        " [REDACTED]",
+    )
+    return parser.parse_args(argv)
+
+
+def _report(log: structlog.stdlib.BoundLogger, result: ScrubResult, verbose: bool) -> None:
+    if sys.stderr.isatty():
+        sys.stderr.write("\n".join(render_report(result, verbose, _stderr_width())) + "\n")
+        return
+    log.info(
+        "scrubbed",
+        **{kind.value: count for kind, count in sorted(result.counts.items())},
+        replacements=len(result.findings),
+    )
+    if verbose:
+        occurrences = Counter((f.kind, f.text, f.alias) for f in result.findings)
+        for (kind, text, alias), count in sorted(occurrences.items()):
+            log.info("replaced", kind=kind.value, text=clip(text), count=count, alias=clip(alias))
+    for residual in result.residuals:
+        log.warning("unscrubbed", line=residual.line, reason=residual.reason, text=residual.text)
+
+
+def _stderr_width() -> int:
+    try:
+        return os.get_terminal_size(sys.stderr.fileno()).columns
+    except (OSError, ValueError):
+        # shutil probes stdout, which is routinely a pipe here (`scrubbr | wl-copy`), so
+        # stderr's own fd is tried first; shutil still honours $COLUMNS before its 80.
+        return shutil.get_terminal_size().columns
+
+
+def main(argv: list[str] | None = None, open_tty: Callable[[], Terminal] = open_terminal) -> int:
+    args = _parse(argv)
+    _configure_logging()
+    log = structlog.get_logger()
+
+    if args.infile is None:
+        if isinstance(sys.stdin, io.TextIOWrapper):
+            sys.stdin.reconfigure(errors="replace")
+        args.infile = sys.stdin
+    text = args.infile.read()
+    base = LocalIdentity() if args.no_identity else LocalIdentity.local()
+    identity = replace(base, extra=base.extra + tuple(args.also))
+    result = scrub(text, identity)
+    _report(log, result, args.verbose)
+
+    if args.strict and result.residuals:
+        log.error("refusing to emit", reason="strict mode with unscrubbed strings")
+        return 2
+
+    if not args.no_review:
+        try:
+            tty = open_tty()
+        except NoTerminal:
+            # Failing open here would emit unreviewed text precisely when the safety gate
+            # could not run. Skipping review has to be a decision the caller makes.
+            log.error("refusing to emit", reason="no terminal for review; pass -y to skip it")
+            return 3
+        try:
+            confirmed = confirm(text, result.text, result.residuals, tty)
+        finally:
+            tty.close()
+        if not confirmed:
+            log.error("discarded", reason="not confirmed at review")
+            return 1
+
+    if args.output is not None:
+        try:
+            # Opened only after the review passes: opening at parse time would leave an
+            # empty or truncated file behind on every refused run.
+            Path(args.output).write_text(result.text, encoding="utf-8")
+        except OSError as error:
+            log.error("could not write", path=args.output, error=str(error))
+            return 4
+        log.info("written", path=args.output)
+    else:
+        sys.stdout.write(result.text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scrubbr/detect.py

@@ -0,0 +1,230 @@
+import re
+from dataclasses import dataclass
+from functools import lru_cache
+
+from scrubbr.identity import LocalIdentity
+from scrubbr.kinds import Kind
+from scrubbr.shapes import EMAIL_PATTERN, HEX_PATTERN, UUID_PATTERN, classify_literal
+
+# An RSA-8192 key is around 12 KB of base64, so this fits any real key while keeping an
+# unterminated BEGIN marker from backtracking across the whole file.
+PEM_MAX_BODY = 20_000
+
+NO_IDENTITY = LocalIdentity()
+
+SECRET_KEYWORDS = (
+    "psk",
+    "password",
+    "passwd",
+    "secret",
+    "api_key",
+    "apikey",
+    "access_token",
+    "auth_token",
+    "client_secret",
+    "private_key",
+)
+
+
+@dataclass(frozen=True)
+class Rule:
+    name: str
+    kind: Kind
+    pattern: str
+    value_group: str | None = None
+    forced: bool = False
+
+
+@dataclass(frozen=True)
+class Match:
+    kind: Kind
+    start: int
+    end: int
+    text: str
+    forced: bool = False
+
+
+# Ordered most-specific first. Alternation resolves precedence: at any position the
+# earliest alternative that matches wins, which is what makes the colon-hex family
+# (fingerprint / MAC / IPv6) disambiguate correctly.
+STRUCTURAL_RULES: tuple[Rule, ...] = (
+    Rule(
+        "pem",
+        Kind.PEM,
+        # The body stays a wildcard on purpose. Narrowing it to the base64 alphabet would
+        # make one stray character anywhere in the block fail the whole alternative and
+        # pass the key through verbatim; the length bound alone removes the backtracking.
+        r"-----BEGIN [A-Z0-9 ._-]{0,100}-----"
+        rf"(?P<pem_body>[\s\S]{{0,{PEM_MAX_BODY}}}?)"
+        r"-----END [A-Z0-9 ._-]{0,100}-----",
+        value_group="pem_body",
+    ),
+    # A log cut off mid-key has a BEGIN marker and no END. The complete rule above is
+    # tried first, so this only ever fires on a truncated block -- without it the key body
+    # matches nothing at all and survives verbatim, which truncated diagnostics make common.
+    Rule(
+        "pem_truncated",
+        Kind.PEM,
+        r"-----BEGIN [A-Z0-9 ._-]{0,100}-----"
+        rf"(?P<pem_open>(?:\r?\n[A-Za-z0-9+/=]{{16,80}}){{1,{PEM_MAX_BODY // 16}}})",
+        value_group="pem_open",
+    ),
+    Rule(
+        "crypt_hash",
+        Kind.CRYPT_HASH,
+        r"\$(?:1|5|6|2[aby]|apr1)\$(?:rounds=\d+\$)?[./A-Za-z0-9]{1,16}\$[./A-Za-z0-9]{20,90}",
+    ),
+    Rule("jwt", Kind.JWT, r"eyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]*"),
+    Rule("disk_id", Kind.DISK_ID, r"/dev/disk/by-id/(?P<disk_id_val>[A-Za-z0-9._:+-]+)",
+         value_group="disk_id_val"),
+    # 8+ colon-hex groups: a digest fingerprint, never a MAC.
+    Rule(
+        "fingerprint",
+        Kind.FINGERPRINT,
+        r"(?<![0-9A-Fa-f:])(?:[0-9A-Fa-f]{2}:){7,}[0-9A-Fa-f]{2}(?![0-9A-Fa-f:])",
+    ),
+    Rule("uuid", Kind.UUID, rf"(?<![0-9A-Fa-f-]){UUID_PATTERN}(?![0-9A-Fa-f-])"),
+    # Exactly six 2-digit groups with a consistent separator, fenced by lookarounds so it
+    # cannot bite a slice out of a longer colon-hex chain.
+    # One rule per separator rather than one rule with a backreferenced separator: each
+    # fence then excludes only its OWN separator, so a colon-separated address is still
+    # found in "aa:bb:cc:dd:ee:ff-eth0" and "wlan0-aa:bb:cc:dd:ee:ff", while a
+    # hyphen-separated one is still fenced off from a longer hyphenated run.
+    Rule(
+        "mac_colon",
+        Kind.MAC,
+        r"(?<![0-9A-Fa-f:])(?:[0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}(?![0-9A-Fa-f:])",
+    ),
+    Rule(
+        "mac_hyphen",
+        Kind.MAC,
+        r"(?<![0-9A-Fa-f-])(?:[0-9A-Fa-f]{2}-){5}[0-9A-Fa-f]{2}(?![0-9A-Fa-f-])",
+    ),
+    # A trailing dot only disqualifies the dotted form when more hex follows it.
+    Rule(
+        "mac_cisco",
+        Kind.MAC,
+        r"(?<![0-9A-Fa-f])(?<![0-9A-Fa-f]\.)"
+        r"[0-9A-Fa-f]{4}\.[0-9A-Fa-f]{4}\.[0-9A-Fa-f]{4}"
+        r"(?![0-9A-Fa-f])(?!\.[0-9A-Fa-f])",
+    ),
+    # Bare 12-hex is only a MAC when something says so; on its own it is indistinguishable
+    # from a truncated hash, and scrubbing every 12-hex run would wreck ordinary logs.
+    Rule(
+        "mac_bare",
+        Kind.MAC,
+        r"(?i:mac|hwaddr|hw_addr|bssid|ether|lladdr|hw)(?:\s+address)?\s*[=:]?\s*"
+        r"(?P<mac_bare_val>[0-9A-Fa-f]{12})(?![0-9A-Za-z])",
+        value_group="mac_bare_val",
+    ),
+    # Ahead of the identity literals: a username is usually the local part of its owner's
+    # address, and letting the literal win would rewrite "dev@example.com" to
+    # "user-a@example.com", keeping the domain — normally the more identifying half.
+    Rule("email", Kind.EMAIL, EMAIL_PATTERN),
+)
+
+CONTEXTUAL_RULES: tuple[Rule, ...] = (
+    Rule(
+        "ssid",
+        Kind.SSID,
+        r"(?i:ssid)\s*[=:]\s*(?P<ssid_q>[\"'])(?P<ssid_val>[^\"']*)(?P=ssid_q)",
+        value_group="ssid_val",
+    ),
+    Rule(
+        "secret_kv",
+        Kind.SECRET_VALUE,
+        r"(?i:" + "|".join(SECRET_KEYWORDS) + r")\s*[=:]\s*"
+        r"(?P<secret_q>[\"']?)(?P<secret_val>[^\s\"',;]+)(?P=secret_q)",
+        value_group="secret_val",
+    ),
+    Rule(
+        "home_path",
+        Kind.USERNAME,
+        r"/home/(?P<home_user>[a-z_][a-z0-9_-]{0,31})",
+        value_group="home_user",
+    ),
+    Rule(
+        "ipv6",
+        Kind.IPV6,
+        r"(?<![0-9A-Fa-f:.])[0-9A-Fa-f]{0,4}(?::[0-9A-Fa-f]{0,4}){2,7}(?![0-9A-Fa-f:])",
+    ),
+    Rule("ipv4", Kind.IPV4, r"(?<![0-9.])(?:[0-9]{1,3}\.){3}[0-9]{1,3}(?![0-9.])"),
+    Rule(
+        "hex",
+        Kind.HEX,
+        rf"(?<![0-9A-Za-z])(?:0[xX])?(?P<hex_val>{HEX_PATTERN})(?![0-9A-Za-z])",
+        value_group="hex_val",
+    ),
+)
+
+
+def _literal_rules(
+    identity: LocalIdentity, promoted: tuple[tuple[str, Kind], ...]
+) -> tuple[Rule, ...]:
+    literals: list[tuple[str, Kind, bool]] = []
+    if identity.hostname:
+        literals.append((identity.hostname, Kind.HOSTNAME, False))
+        short = identity.hostname.split(".")[0]
+        if short != identity.hostname:
+            literals.append((short, Kind.HOSTNAME, False))
+    # An extra value is explicitly declared, so it is scrubbed unconditionally -- forced
+    # past the keep-allowlists that judge only incidental matches.
+    literals.extend((value, classify_literal(value), True) for value in identity.extra)
+    if identity.username:
+        literals.append((identity.username, Kind.USERNAME, False))
+    literals.extend((value, kind, False) for value, kind in promoted)
+    # Longest first: a username is frequently a substring of the hostname ("dev" inside
+    # "dev-thinkpad"), and the longer match has to win at that position.
+    literals.sort(key=lambda entry: len(entry[0]), reverse=True)
+    return tuple(
+        Rule(f"literal_{index}", kind, _literal_pattern(value, kind), forced=forced)
+        for index, (value, kind, forced) in enumerate(literals)
+    )
+
+
+def _literal_pattern(value: str, kind: Kind) -> str:
+    escaped = re.escape(value)
+    if kind is Kind.IPV6:
+        # Forcing must survive the log spelling FE80::1 as fe80::1.
+        escaped = f"(?i:{escaped})"
+    return rf"(?<![A-Za-z0-9_]){escaped}(?![A-Za-z0-9_])"
+
+
+@lru_cache(maxsize=64)
+def _compiled(
+    identity: LocalIdentity, promoted: tuple[tuple[str, Kind], ...]
+) -> tuple[re.Pattern[str], dict[str, Rule]]:
+    rules = STRUCTURAL_RULES + _literal_rules(identity, promoted) + CONTEXTUAL_RULES
+    combined = "|".join(f"(?P<{rule.name}>{rule.pattern})" for rule in rules)
+    return re.compile(combined), {rule.name: rule for rule in rules}
+
+
+def detect(
+    text: str,
+    identity: LocalIdentity = NO_IDENTITY,
+    promoted: tuple[tuple[str, Kind], ...] = (),
+) -> list[Match]:
+    """Locate everything worth replacing.
+
+    `promoted` carries values a first pass discovered behind a keyword — `psk=secret` —
+    so that a second pass also catches them where they appear bare and unlabelled.
+    """
+    pattern, by_name = _compiled(identity, promoted)
+    matches: list[Match] = []
+    for found in pattern.finditer(text):
+        rule = by_name[_which(found, by_name)]
+        group = rule.value_group or rule.name
+        start, end = found.span(group)
+        if start < 0 or start == end:
+            continue
+        matches.append(
+            Match(kind=rule.kind, start=start, end=end, text=text[start:end], forced=rule.forced)
+        )
+    return matches
+
+
+def _which(found: re.Match[str], by_name: dict[str, Rule]) -> str:
+    for name in by_name:
+        if found.group(name) is not None:
+            return name
+    raise AssertionError("a match must belong to exactly one rule")

scrubbr/identity.py

@@ -0,0 +1,59 @@
+import getpass
+import socket
+from dataclasses import dataclass, field
+from pathlib import Path
+
+SYSTEM_USERNAMES = frozenset(
+    {
+        "root",
+        "daemon",
+        "bin",
+        "sys",
+        "sync",
+        "man",
+        "nobody",
+        "messagebus",
+        "dbus",
+        "polkitd",
+        "sshd",
+        "www-data",
+        "systemd-network",
+        "systemd-resolve",
+        "systemd-timesync",
+        "systemd-journal",
+        "user",
+    }
+)
+
+
+@dataclass(frozen=True)
+class LocalIdentity:
+    """Literal strings naming *this* machine and *this* person.
+
+    Seeding the scanner with these is the highest-precision rule available: the surest
+    way to know a hostname is yours is to ask the system for it, rather than to guess at
+    which token in a syslog line is a hostname.
+    """
+
+    hostname: str | None = None
+    username: str | None = None
+    extra: tuple[str, ...] = field(default_factory=tuple)
+
+    @classmethod
+    def local(cls) -> "LocalIdentity":
+        extra: list[str] = []
+        try:
+            machine_id = Path("/etc/machine-id").read_text(encoding="utf-8").strip()
+        except OSError:
+            machine_id = ""
+        if machine_id:
+            extra.append(machine_id)
+        try:
+            username: str | None = getpass.getuser()
+        except (OSError, KeyError):
+            username = None
+        try:
+            hostname: str | None = socket.gethostname()
+        except OSError:
+            hostname = None
+        return cls(hostname=hostname, username=username, extra=tuple(extra))

scrubbr/kinds.py

@@ -0,0 +1,41 @@
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Kind(StrEnum):
+    PEM = "pem"
+    CRYPT_HASH = "crypt_hash"
+    JWT = "jwt"
+    FINGERPRINT = "fingerprint"
+    DISK_ID = "disk_id"
+    UUID = "uuid"
+    MAC = "mac"
+    IPV6 = "ipv6"
+    LINK_LOCAL_ID = "link_local_id"
+    IPV4 = "ipv4"
+    HEX = "hex"
+    EMAIL = "email"
+    SECRET_VALUE = "secret_value"
+    REDACTED = "redacted"
+    SSID = "ssid"
+    HOSTNAME = "hostname"
+    USERNAME = "username"
+
+
+class Finding(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    kind: Kind
+    start: int
+    end: int
+    text: str
+    alias: str
+
+
+class Residual(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    line: int
+    text: str
+    reason: str

scrubbr/report.py

@@ -0,0 +1,108 @@
+import textwrap
+from collections import Counter
+
+from scrubbr.kinds import Finding, Kind, Residual
+from scrubbr.scrub import ScrubResult
+
+# The report names values, it does not reproduce them: a PEM body is kilobytes across
+# many lines, and no terminal width justifies showing more of a secret.
+CLIP = 60
+# Below this the columns stop being readable anyway; render as if the terminal were this
+# wide and let it wrap.
+MIN_WIDTH = 40
+_GUTTER = "  "
+# StrEnum sorts alphabetically; declaration order is the sensitivity order, which is what
+# a security report should lead with.
+_KIND_ORDER = {kind: index for index, kind in enumerate(Kind)}
+
+
+def render_report(result: ScrubResult, verbose: bool, width: int) -> list[str]:
+    width = max(width, MIN_WIDTH)
+    lines = _summary(result, width)
+    if verbose and result.findings:
+        lines += ["", *_findings_table(result.findings, width)]
+    if result.residuals:
+        lines += ["", *_residuals_table(result.residuals, width)]
+    return lines
+
+
+def _summary(result: ScrubResult, width: int) -> list[str]:
+    distinct = sum(result.counts.values())
+    lines = [f"scrubbed {distinct} distinct values, {len(result.findings)} replacements"]
+    if result.counts:
+        by_kind = ", ".join(
+            f"{kind.value} {result.counts[kind]}" for kind in Kind if kind in result.counts
+        )
+        lines += textwrap.wrap(
+            by_kind, width=width, initial_indent=_GUTTER, subsequent_indent=_GUTTER
+        )
+    return lines
+
+
+def _findings_table(findings: list[Finding], width: int) -> list[str]:
+    occurrences = Counter((f.kind, f.text, f.alias) for f in findings)
+    rows = sorted(
+        (
+            (kind, _flatten(text), count, _flatten(alias))
+            for (kind, text, alias), count in occurrences.items()
+        ),
+        key=lambda row: (_KIND_ORDER[row[0]], -row[2], row[1]),
+    )
+    kind_w = max(len("kind"), *(len(kind.value) for kind, _, _, _ in rows))
+    count_w = max(len("count"), *(len(str(count)) for _, _, count, _ in rows))
+    text_w, alias_w = _apportion(
+        width - kind_w - count_w - 3 * len(_GUTTER),
+        min(CLIP, max(len("text"), *(len(text) for _, text, _, _ in rows))),
+        min(CLIP, max(len("alias"), *(len(alias) for _, _, _, alias in rows))),
+    )
+    template = f"{{:<{kind_w}}}{_GUTTER}{{:>{count_w}}}{_GUTTER}{{:<{text_w}}}{_GUTTER}{{}}"
+    header = template.format("kind", "count", _fit("text", text_w), _fit("alias", alias_w))
+    lines = [header.rstrip()]
+    lines += [
+        template.format(kind.value, count, _fit(text, text_w), _fit(alias, alias_w)).rstrip()
+        for kind, text, count, alias in rows
+    ]
+    return lines
+
+
+def _residuals_table(residuals: list[Residual], width: int) -> list[str]:
+    line_w = max(len("line"), *(len(str(residual.line)) for residual in residuals))
+    reason_w = max(len("reason"), *(len(residual.reason) for residual in residuals))
+    text_w = min(CLIP, width - line_w - reason_w - 3 * len(_GUTTER))
+    template = f"{_GUTTER}{{:>{line_w}}}{_GUTTER}{{:<{reason_w}}}{_GUTTER}{{}}"
+    lines = [f"{len(residuals)} unscrubbed strings look sensitive:"]
+    lines.append(template.format("line", "reason", "text").rstrip())
+    lines += [
+        template.format(residual.line, residual.reason, _fit(_flatten(residual.text), text_w))
+        for residual in residuals
+    ]
+    return lines
+
+
+def _apportion(avail: int, text_nat: int, alias_nat: int) -> tuple[int, int]:
+    if text_nat + alias_nat <= avail:
+        return text_nat, alias_nat
+    half = avail // 2
+    if text_nat <= half:
+        return text_nat, avail - text_nat
+    if alias_nat <= half:
+        return avail - alias_nat, alias_nat
+    return max(avail - half, 0), max(half, 0)
+
+
+def _fit(value: str, width: int) -> str:
+    if len(value) <= width:
+        return value
+    if width <= 0:
+        return ""
+    keep = width - 1
+    tail = keep // 2
+    return value[: keep - tail] + "…" + value[len(value) - tail :]
+
+
+def _flatten(value: str) -> str:
+    return " ".join(value.split())
+
+
+def clip(value: str) -> str:
+    return _flatten(value)[:CLIP]