toolgovern-cli 0.1.1__py3-none-any.whl

toolgovern/policy/load_policy.py

@@ -0,0 +1,41 @@
+"""Loads and validates a ``toolgovern.policy.yml`` file from disk.
+
+Ported from ``packages/toolgovern/src/policy/loadPolicy.ts``::
+
+    policy = load_policy("./toolgovern.policy.yml")
+    gated_shell_tool = govern_tool(shell_tool, policy)
+
+``load_policy`` is synchronous by design -- it is meant to run once at process startup, the same
+way a framework loads any other config file.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+import yaml
+
+from ..types import Policy
+from .validate_policy import as_policy, validate_policy
+
+
+class PolicyValidationError(Exception):
+    def __init__(self, file_path: str, errors: List[str]) -> None:
+        self.errors = errors
+        message = f'Invalid policy file "{file_path}":\n' + "\n".join(f"  - {e}" for e in errors)
+        super().__init__(message)
+
+
+def load_policy(file_path: str) -> Policy:
+    """Parses and validates a policy file, raising ``PolicyValidationError`` if it is invalid."""
+    with open(file_path, "r", encoding="utf-8") as f:
+        raw_text = f.read()
+    try:
+        parsed = yaml.safe_load(raw_text)
+    except yaml.YAMLError as cause:
+        raise ValueError(f'Failed to parse policy file "{file_path}" as YAML.') from cause
+
+    result = validate_policy(parsed)
+    if not result.valid:
+        raise PolicyValidationError(file_path, list(result.errors))
+    return as_policy(parsed)

toolgovern/policy/validate_policy.py

@@ -0,0 +1,106 @@
+"""Structural and rule-reference validation for a policy file.
+
+Ported from ``packages/toolgovern/src/policy/validatePolicy.ts``. Used both by ``load_policy()``
+(raises on failure -- a program should not start with a broken policy) and by
+``toolgovern-cli validate`` (reports every error found, without raising, so a developer gets one
+full list instead of fixing errors one at a time).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, List, Optional, Sequence
+
+from ..classifier import rule_registry
+from ..scoping import is_valid_scope_declaration
+from ..types import Policy, RuleOverrides, ScopeDeclaration
+
+_VALID_RULE_IDS = {r.id for r in rule_registry}
+_VALID_DECISIONS = {"allow", "deny", "require-approval"}
+
+
+@dataclass(frozen=True)
+class PolicyValidationResult:
+    valid: bool
+    errors: Sequence[str] = field(default_factory=tuple)
+
+
+def validate_policy(raw: Any) -> PolicyValidationResult:
+    """Validates a parsed (but untyped) policy object. Returns every error found, not just the
+    first."""
+    errors: List[str] = []
+
+    if not isinstance(raw, dict):
+        return PolicyValidationResult(
+            valid=False, errors=["Policy file must define a single YAML mapping (object)."]
+        )
+    candidate = raw
+
+    if "name" in candidate and candidate["name"] is not None and not isinstance(candidate["name"], str):
+        errors.append('"name" must be a string if present.')
+    if (
+        "policy" in candidate
+        and candidate["policy"] is not None
+        and not isinstance(candidate["policy"], str)
+    ):
+        errors.append('"policy" must be a string if present.')
+
+    if not is_valid_scope_declaration(candidate.get("scope")):
+        errors.append(
+            '"scope" is required and must have network (boolean or string[]), filesystem '
+            "(string[]), and credentials (string[])."
+        )
+
+    if "defaultDecision" in candidate or "default_decision" in candidate:
+        default_decision = candidate.get("defaultDecision", candidate.get("default_decision"))
+        if not isinstance(default_decision, str) or default_decision not in _VALID_DECISIONS:
+            errors.append('"defaultDecision" must be one of: allow, deny, require-approval.')
+
+    rules = candidate.get("rules")
+    if rules is not None:
+        if not isinstance(rules, dict):
+            errors.append('"rules" must be an object with optional "disable" and "requireApproval" arrays.')
+        else:
+            for field_name in ("disable", "requireApproval"):
+                value = rules.get(field_name)
+                if value is None:
+                    continue
+                if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+                    errors.append(f'"rules.{field_name}" must be an array of rule ID strings.')
+                    continue
+                for rule_id in value:
+                    if rule_id not in _VALID_RULE_IDS:
+                        errors.append(
+                            f'"rules.{field_name}" references unknown rule ID "{rule_id}". '
+                            f'Valid rule IDs: {", ".join(sorted(_VALID_RULE_IDS))}.'
+                        )
+
+    return PolicyValidationResult(valid=len(errors) == 0, errors=errors)
+
+
+def as_policy(raw: dict) -> Policy:
+    """Narrows ``raw`` to a ``Policy`` after ``validate_policy`` has confirmed it is
+    structurally valid."""
+    scope_raw = raw.get("scope", {})
+    scope = ScopeDeclaration(
+        network=scope_raw.get("network", False),
+        filesystem=tuple(scope_raw.get("filesystem", ())),
+        credentials=tuple(scope_raw.get("credentials", ())),
+    )
+    rules_raw = raw.get("rules")
+    rules: Optional[RuleOverrides] = None
+    if rules_raw is not None:
+        rules = RuleOverrides(
+            disable=tuple(rules_raw.get("disable", ())),
+            require_approval=tuple(rules_raw.get("requireApproval", ())),
+        )
+    return Policy(
+        scope=scope,
+        policy=raw.get("policy"),
+        name=raw.get("name"),
+        rules=rules,
+        default_decision=raw.get("defaultDecision", raw.get("default_decision", "allow")),
+        agent_id=raw.get("agentId", raw.get("agent_id")),
+        session_id=raw.get("sessionId", raw.get("session_id")),
+        coordinator_id=raw.get("coordinatorId", raw.get("coordinator_id")),
+    )

toolgovern/scoping/__init__.py

@@ -0,0 +1,13 @@
+from .inheritance_enforcer import ScopeRegistry, SpawnSubAgentParams, compute_inherited_scope, has_zero_capability
+from .scope_declaration import EMPTY_SCOPE, is_valid_agent_id, is_valid_scope_declaration, normalize_scope
+
+__all__ = [
+    "EMPTY_SCOPE",
+    "ScopeRegistry",
+    "SpawnSubAgentParams",
+    "compute_inherited_scope",
+    "has_zero_capability",
+    "is_valid_agent_id",
+    "is_valid_scope_declaration",
+    "normalize_scope",
+]

toolgovern/scoping/inheritance_enforcer.py

@@ -0,0 +1,145 @@
+"""Default-deny scope inheritance.
+
+Ported from ``packages/toolgovern/src/scoping/inheritance-enforcer.ts``.
+
+When a coordinator agent spawns a sub-agent, the sub-agent does NOT inherit the coordinator's
+full access by default. Its scope is the intersection of what it requests and what the
+coordinator itself actually has -- anything requested but not covered by the coordinator's own
+scope is silently dropped, never silently granted. ``ScopeRegistry`` is the runtime home for
+this: it records every agent's effective (granted) scope and re-checks it on every call a rule
+evaluates, not just once at spawn time.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+from ..shared.paths import credential_matches_granted, host_matches_allowed, is_path_within
+from ..types import AgentScopeRecord, ScopeDeclaration
+from .scope_declaration import EMPTY_SCOPE
+
+
+def _intersect_network(coordinator, requested):
+    if coordinator is False or requested is False:
+        return False
+    if coordinator is True and requested is True:
+        return True
+    coordinator_list = None if coordinator is True else coordinator
+    requested_list = None if requested is True else requested
+    if coordinator_list is None:
+        return list(requested_list) if requested_list is not None else []
+    if requested_list is None:
+        return list(coordinator_list)
+    # For each (coordinator, requested) pair that are the same host or one is a subdomain of
+    # the other, grant the NARROWER of the two -- not unconditionally whichever list's entry
+    # matched. Filtering only the coordinator list (the original bug) grants a sub-agent that
+    # asked for a narrow host (api.example.com) the coordinator's much broader entry
+    # (example.com) whenever the broader entry's domain happens to cover the narrow request.
+    # Filtering only the requested list would fix that case but breaks the opposite one: a
+    # sub-agent that broadly requests example.com while the coordinator holds both
+    # example.com and a narrower api.example.com should still receive the narrower
+    # api.example.com grant intact (it's covered by the broad request, not widened by it).
+    granted: "dict[str, None]" = {}
+    for coord_host in coordinator_list:
+        for req_host in requested_list:
+            if coord_host == req_host:
+                granted[coord_host] = None
+            elif host_matches_allowed(coord_host, req_host):
+                granted[coord_host] = None  # coordinator's entry is the narrower (subdomain) value
+            elif host_matches_allowed(req_host, coord_host):
+                granted[req_host] = None  # requested entry is the narrower (subdomain) value
+    return list(granted.keys())
+
+
+def _intersect_filesystem(coordinator, requested):
+    return [
+        req_path for req_path in requested if any(is_path_within(req_path, coord_path) for coord_path in coordinator)
+    ]
+
+
+def _intersect_credentials(coordinator, requested):
+    return [
+        req_cred
+        for req_cred in requested
+        if any(credential_matches_granted(req_cred, coord_cred) for coord_cred in coordinator)
+    ]
+
+
+def has_zero_capability(scope: ScopeDeclaration) -> bool:
+    """True if ``scope`` carries no capability at all -- no network access (False, or an
+    allowlist with zero entries -- both mean "cannot reach any host"), no filesystem prefix,
+    and no credential. An agent whose *granted* scope is this empty cannot legitimately make
+    any tool call, regardless of what the call's arguments happen to look like."""
+    has_network = scope.network is True or (isinstance(scope.network, (list, tuple)) and len(scope.network) > 0)
+    return not has_network and len(scope.filesystem) == 0 and len(scope.credentials) == 0
+
+
+def compute_inherited_scope(
+    coordinator_scope: ScopeDeclaration, requested_scope: ScopeDeclaration
+) -> ScopeDeclaration:
+    """Pure function: given a coordinator's own effective scope and a sub-agent's requested
+    scope, returns the scope actually granted. Never returns anything the coordinator itself
+    does not have, and never grants anything the sub-agent did not explicitly request."""
+    return ScopeDeclaration(
+        network=_intersect_network(coordinator_scope.network, requested_scope.network),
+        filesystem=_intersect_filesystem(coordinator_scope.filesystem, requested_scope.filesystem),
+        credentials=_intersect_credentials(coordinator_scope.credentials, requested_scope.credentials),
+    )
+
+
+@dataclass(frozen=True)
+class SpawnSubAgentParams:
+    coordinator_id: str
+    sub_agent_id: str
+    session_id: str
+    requested_scope: ScopeDeclaration
+
+
+class ScopeRegistry:
+    """Tracks every agent's effective (granted) scope for a governed run. Root agents register
+    their own declared scope directly; sub-agents are spawned against a coordinator and receive
+    the intersection of what they request and what their coordinator actually has."""
+
+    def __init__(self) -> None:
+        self._records: Dict[str, AgentScopeRecord] = {}
+
+    def register_root_agent(self, agent_id: str, session_id: str, scope: ScopeDeclaration) -> AgentScopeRecord:
+        record = AgentScopeRecord(agent_id=agent_id, session_id=session_id, granted_scope=scope)
+        self._records[agent_id] = record
+        return record
+
+    def spawn_sub_agent(self, params: SpawnSubAgentParams) -> AgentScopeRecord:
+        """Spawns a sub-agent under ``params.coordinator_id``. If the coordinator has never
+        been registered, the sub-agent is granted the empty scope -- default-deny applies even
+        when the caller forgot to register the coordinator first, rather than falling back to
+        "unrestricted."."""
+        coordinator_record = self._records.get(params.coordinator_id)
+        coordinator_scope = coordinator_record.granted_scope if coordinator_record else EMPTY_SCOPE
+        granted_scope = compute_inherited_scope(coordinator_scope, params.requested_scope)
+        record = AgentScopeRecord(
+            agent_id=params.sub_agent_id,
+            session_id=params.session_id,
+            coordinator_id=params.coordinator_id,
+            requested_scope=params.requested_scope,
+            granted_scope=granted_scope,
+        )
+        self._records[params.sub_agent_id] = record
+        return record
+
+    def get_record(self, agent_id: str) -> Optional[AgentScopeRecord]:
+        return self._records.get(agent_id)
+
+    def get_effective_scope(self, agent_id: str) -> Optional[ScopeDeclaration]:
+        record = self._records.get(agent_id)
+        return record.granted_scope if record else None
+
+    def has(self, agent_id: str) -> bool:
+        return agent_id in self._records
+
+    def is_zero_capability(self, agent_id: str) -> bool:
+        """True if ``agent_id`` is registered and its granted scope has zero capability. An
+        unregistered agent is not "zero capability" here -- that case is covered separately by
+        TG05-unregistered-sub-agent."""
+        record = self._records.get(agent_id)
+        return record is not None and has_zero_capability(record.granted_scope)

toolgovern/scoping/scope_declaration.py

@@ -0,0 +1,84 @@
+"""Helpers for validating and comparing ``ScopeDeclaration`` values.
+
+Ported from ``packages/toolgovern/src/scoping/scope-declaration.ts``.
+
+A ``ScopeDeclaration`` is intentionally simple: an agent gets access to what it declares, and
+nothing else. There is no implicit "and everything under this is fine too" beyond the explicit
+path-prefix / hostname-suffix / credential-identifier matching implemented here.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from ..types import ScopeDeclaration
+
+# The empty scope: no network, no filesystem, no credentials. This is the default-deny floor.
+EMPTY_SCOPE = ScopeDeclaration(network=False, filesystem=(), credentials=())
+
+
+def is_valid_scope_declaration(value: Any) -> bool:
+    if not isinstance(value, dict):
+        return False
+
+    network = value.get("network")
+    network_ok = isinstance(network, bool) or (
+        isinstance(network, list) and all(isinstance(h, str) for h in network)
+    )
+    filesystem = value.get("filesystem")
+    filesystem_ok = isinstance(filesystem, list) and all(isinstance(p, str) for p in filesystem)
+    credentials = value.get("credentials")
+    credentials_ok = isinstance(credentials, list) and all(isinstance(c, str) for c in credentials)
+
+    return network_ok and filesystem_ok and credentials_ok
+
+
+def normalize_scope(partial: Optional[dict]) -> ScopeDeclaration:
+    """Normalizes a partial/loosely-typed scope object into a fully-formed ScopeDeclaration,
+    defaulting any missing field to the most restrictive value (default-deny)."""
+    partial = partial or {}
+    return ScopeDeclaration(
+        network=partial.get("network", False),
+        filesystem=tuple(partial.get("filesystem", ())),
+        credentials=tuple(partial.get("credentials", ())),
+    )
+
+
+# Generous ceiling on agent_id length. Not a protocol limit -- just large enough that no
+# realistic identity scheme (UUID, DNS name, URN, JWT sub claim) trips it, while still
+# rejecting unbounded strings that look like a buffer-abuse or log-flooding attempt.
+_MAX_AGENT_ID_LENGTH = 256
+
+
+def _is_disallowed_control_code_point(code_point: int) -> bool:
+    """Code points with no legitimate reason to appear in an agent identity string: ASCII
+    control characters (0x00-0x1F, 0x7F) and the Unicode line/paragraph separators (0x2028,
+    0x2029). Letting them through invites log-injection, null-byte truncation tricks, or
+    terminal/ANSI escape abuse."""
+    return (0x00 <= code_point <= 0x1F) or code_point == 0x7F or code_point in (0x2028, 0x2029)
+
+
+def is_valid_agent_id(value: Any) -> bool:
+    """Format-only validation for an agent_id string.
+
+    IMPORTANT -- what this is NOT: this does not verify that a caller actually is the agent it
+    claims to be. toolgovern has no cryptographic identity verification mechanism in v0.1; any
+    caller can still supply any well-formed agent_id and have it accepted as-is (see
+    docs/security-model.md). A string that passes is merely *well-formed* -- it remains just as
+    much a bare, unverified claim as any other string that passes.
+
+    What this DOES do: reject a narrow, concrete class of malformed/malicious inputs -- an
+    empty string, a string past a sane length ceiling, or a string containing control
+    characters/embedded null bytes that could be used for log injection or to confuse
+    downstream string handling. This is a hygiene filter, not an authentication mechanism.
+    """
+    if not isinstance(value, str):
+        return False
+    if len(value) == 0:
+        return False
+    if len(value) > _MAX_AGENT_ID_LENGTH:
+        return False
+    for ch in value:
+        if _is_disallowed_control_code_point(ord(ch)):
+            return False
+    return True

toolgovern/shared/paths.py

@@ -0,0 +1,266 @@
+"""Low-level path/host normalization helpers shared by the classifier and the scoping registry.
+
+Ported from ``packages/toolgovern/src/shared/paths.ts``. Kept dependency-free and
+side-effect-free so both modules can import from here without a classifier <-> scoping cycle.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List, Optional, Tuple
+from urllib.parse import urlparse
+
+_SCHEME_PATTERN = re.compile(r"^[a-z][a-z0-9+.-]*://", re.IGNORECASE)
+_BRACKETED_HOST_PATTERN = re.compile(r"^\[([^\]]+)\]")
+
+
+def normalize_path(raw_path: str) -> str:
+    """Collapses ``./``, trailing slashes, and duplicate slashes for stable prefix comparison."""
+    path = raw_path.strip()
+    if path.startswith("./"):
+        path = path[2:]
+    path = re.sub(r"/+", "/", path)
+    if len(path) > 1 and path.endswith("/"):
+        path = path[:-1]
+    return path
+
+
+def is_path_within(candidate: str, prefix: str) -> bool:
+    """True if ``candidate`` is equal to, or a path-segment child of, ``prefix``."""
+    normalized_candidate = normalize_path(candidate)
+    normalized_prefix = normalize_path(prefix)
+    if normalized_prefix in ("", "."):
+        return True
+    return normalized_candidate == normalized_prefix or normalized_candidate.startswith(
+        f"{normalized_prefix}/"
+    )
+
+
+def contains_path_traversal(raw_path: str) -> bool:
+    """True if the path contains a ``..`` segment that could escape a scoped prefix via traversal."""
+    return ".." in raw_path.split("/")
+
+
+def normalize_host(host_like: str) -> str:
+    """Best-effort hostname extraction from a bare host string or a full URL."""
+    trimmed = host_like.strip()
+    if _SCHEME_PATTERN.match(trimmed):
+        try:
+            hostname = urlparse(trimmed).hostname
+            if hostname:
+                return hostname.lower()
+        except ValueError:
+            pass  # fall through to the raw-string heuristics below
+
+    without_path = trimmed.split("/", 1)[0] if trimmed else trimmed
+    # A bracketed IPv6 literal ([::1] or [::1]:8080) -- unwrap the brackets and drop any
+    # trailing port, but keep the address itself intact.
+    bracketed = _BRACKETED_HOST_PATTERN.match(without_path)
+    if bracketed:
+        return (bracketed.group(1) or "").lower()
+    # A bare host containing more than one colon is an IPv6 literal, not a host:port pair --
+    # splitting on the first colon (as below) would truncate the address.
+    if without_path.count(":") >= 2:
+        return without_path.lower()
+    without_port = without_path.split(":", 1)[0] if without_path else without_path
+    return without_port.lower()
+
+
+def _is_dotted_ipv4_literal(host: str) -> bool:
+    """True if ``host`` is a dotted-decimal IPv4 literal (``a.b.c.d``), and only that form --
+    used where a bare decimal integer must NOT be treated as an IP (parsing an IPv6 literal's
+    hextets, where a plain numeric group like ``1234`` in ``fe80::1234`` is ordinary hex, not
+    a packed IPv4 address). ``_parse_ipv4_octets`` below is the looser, general-purpose check."""
+    return bool(re.match(r"^(\d{1,3}\.){3}\d{1,3}$", host))
+
+
+def _parse_ipv4_octets(host: str) -> Optional[Tuple[int, int, int, int]]:
+    """Parses ``host`` as an IPv4 address in either dotted-decimal (``a.b.c.d``) or bare
+    single-integer decimal form (the same address packed into one 32-bit unsigned integer,
+    e.g. ``2852039166`` for ``169.254.169.254``) -- the latter is accepted as a valid IP
+    literal by curl, browsers, and most OS resolvers, and is a well-known technique for
+    slipping a private/metadata target past a dotted-decimal-only IP-literal check. Returns
+    the four octets, or ``None`` if ``host`` is neither form."""
+    if _is_dotted_ipv4_literal(host):
+        octets_str = host.split(".")
+        if len(octets_str) != 4:
+            return None
+        try:
+            octets = [int(o) for o in octets_str]
+        except ValueError:
+            return None
+        if any(o > 255 for o in octets):
+            return None
+        return (octets[0], octets[1], octets[2], octets[3])
+    if re.match(r"^\d{1,10}$", host):
+        value = int(host)
+        if value < 0 or value > 0xFFFFFFFF:
+            return None
+        return (
+            (value >> 24) & 0xFF,
+            (value >> 16) & 0xFF,
+            (value >> 8) & 0xFF,
+            value & 0xFF,
+        )
+    return None
+
+
+def _is_ipv4_literal(host: str) -> bool:
+    """True if ``host`` is a raw IPv4 literal (not a domain name), dotted-decimal or bare
+    single-integer decimal form (see ``_parse_ipv4_octets``)."""
+    return _parse_ipv4_octets(host) is not None
+
+
+def _strip_ipv6_decoration(host: str) -> str:
+    """Strips an optional surrounding ``[...]`` bracket pair and a trailing ``%zone`` scope id
+    from an IPv6 literal, e.g. ``[fe80::1%eth0]`` -> ``fe80::1``."""
+    h = host.strip()
+    bracketed = re.match(r"^\[([^\]]+)\]$", h)
+    if bracketed:
+        h = bracketed.group(1) or ""
+    zone_index = h.find("%")
+    if zone_index != -1:
+        h = h[:zone_index]
+    return h
+
+
+_HEXTET_PATTERN = re.compile(r"^[0-9a-f]{1,4}$", re.IGNORECASE)
+
+
+def _parse_ipv6_groups(host: str) -> Optional[List[int]]:
+    """Parses a bare (undecorated) IPv6 literal into its eight 16-bit groups, expanding a
+    single ``::`` run and an embedded IPv4 tail. Returns ``None`` if not syntactically valid."""
+    if ":" not in host:
+        return None
+    has_double_colon = "::" in host
+    if host.count("::") > 1:
+        return None
+
+    head, tail = host, ""
+    if has_double_colon:
+        parts = host.split("::")
+        if len(parts) != 2:
+            return None
+        head, tail = parts[0], parts[1]
+
+    def split_hextets(segment: str) -> List[str]:
+        return segment.split(":") if segment else []
+
+    head_parts = split_hextets(head)
+    tail_parts = split_hextets(tail)
+
+    # An embedded IPv4 tail (::ffff:169.254.169.254) contributes two hextets worth of bits.
+    embedded_ipv4: Optional[List[int]] = None
+    if tail_parts:
+        last_tail_part = tail_parts[-1]
+        if last_tail_part and _is_dotted_ipv4_literal(last_tail_part):
+            octets_str = last_tail_part.split(".")
+            if len(octets_str) != 4:
+                return None
+            try:
+                octets = [int(o) for o in octets_str]
+            except ValueError:
+                return None
+            if any(o > 255 for o in octets):
+                return None
+            o0, o1, o2, o3 = octets
+            embedded_ipv4 = [(o0 << 8) | o1, (o2 << 8) | o3]
+            tail_parts.pop()
+
+    if any(not _HEXTET_PATTERN.match(p) for p in head_parts):
+        return None
+    if any(not _HEXTET_PATTERN.match(p) for p in tail_parts):
+        return None
+
+    head_groups = [int(p, 16) for p in head_parts]
+    tail_groups = [int(p, 16) for p in tail_parts]
+    embedded_length = 2 if embedded_ipv4 else 0
+    total = len(head_groups) + len(tail_groups) + embedded_length
+
+    if has_double_colon:
+        zeros = 8 - total
+        if zeros < 0:
+            return None
+        groups = head_groups + [0] * zeros + tail_groups + (embedded_ipv4 or [])
+    else:
+        if total != 8:
+            return None
+        groups = head_groups + tail_groups + (embedded_ipv4 or [])
+
+    return groups if len(groups) == 8 else None
+
+
+def _is_ipv6_literal(host: str) -> bool:
+    """True if ``host`` is a raw IPv6 literal -- bracketed or bare, with or without a
+    ``%zone`` id or an embedded IPv4 tail."""
+    return _parse_ipv6_groups(_strip_ipv6_decoration(host)) is not None
+
+
+def is_ip_literal(host: str) -> bool:
+    """True if ``host`` is a raw IP literal, IPv4 or IPv6 (not a domain name)."""
+    return _is_ipv4_literal(host) or _is_ipv6_literal(host)
+
+
+def _is_private_ipv4_octets(octets: Tuple[int, int, int, int]) -> bool:
+    """True if IPv4 ``octets`` fall in a loopback, RFC1918-private, or link-local range --
+    link-local (169.254.0.0/16) includes the 169.254.169.254 cloud-metadata endpoint used by
+    AWS, GCP, Azure, and most other cloud providers."""
+    a, b = octets[0], octets[1]
+    if a == 127:
+        return True  # loopback 127.0.0.0/8
+    if a == 10:
+        return True  # RFC1918 10.0.0.0/8
+    if a == 172 and 16 <= b <= 31:
+        return True  # RFC1918 172.16.0.0/12
+    if a == 192 and b == 168:
+        return True  # RFC1918 192.168.0.0/16
+    if a == 169 and b == 254:
+        return True  # link-local, incl. cloud metadata 169.254.169.254
+    return False
+
+
+def is_private_or_metadata_target(host: str) -> bool:
+    """True if ``host`` is a raw IP literal (v4 or v6) that targets loopback, an
+    RFC1918/unique-local private range, link-local space, or a cloud-metadata endpoint
+    (169.254.169.254 and its IPv6 equivalents: ::1, fe80::/10, fc00::/7, and IPv4-mapped
+    ::ffff:a.b.c.d addresses that resolve into one of the above IPv4 ranges) -- the set of
+    destinations a rubber-stamped human approval should never be able to wave through."""
+    ipv4_octets = _parse_ipv4_octets(host)
+    if ipv4_octets is not None:
+        return _is_private_ipv4_octets(ipv4_octets)
+
+    groups = _parse_ipv6_groups(_strip_ipv6_decoration(host))
+    if not groups:
+        return False
+    g0, g1, g2, g3, g4, g5, g6, g7 = groups
+
+    # ::1 loopback
+    if g0 == 0 and g1 == 0 and g2 == 0 and g3 == 0 and g4 == 0 and g5 == 0 and g6 == 0 and g7 == 1:
+        return True
+    # fe80::/10 link-local
+    if (g0 & 0xFFC0) == 0xFE80:
+        return True
+    # fc00::/7 unique-local
+    if (g0 & 0xFE00) == 0xFC00:
+        return True
+    # IPv4-mapped (::ffff:a.b.c.d) -- check the embedded IPv4 address
+    if g0 == 0 and g1 == 0 and g2 == 0 and g3 == 0 and g4 == 0 and g5 == 0xFFFF:
+        octets = (g6 >> 8, g6 & 0xFF, g7 >> 8, g7 & 0xFF)
+        return _is_private_ipv4_octets(octets)
+    return False
+
+
+def host_matches_allowed(host: str, allowed: str) -> bool:
+    """True if ``host`` matches ``allowed`` exactly or is a subdomain of it."""
+    h = host.lower()
+    a = allowed.lower()
+    return h == a or h.endswith(f".{a}")
+
+
+def credential_matches_granted(identifier: str, granted: str) -> bool:
+    """True if ``identifier`` matches ``granted`` exactly, as a path suffix, or as a
+    substring -- used for credential-identifier comparisons where declared scopes are often
+    coarse-grained (e.g. granting "aws" should cover ".aws/credentials")."""
+    i = identifier.lower()
+    g = granted.lower()
+    return i == g or i.endswith(f"/{g}") or g in i