glovebox-hosts 0.4.0__tar.gz

glovebox_hosts-0.4.0/.gitignore

@@ -0,0 +1,192 @@
+.worktrees
+.claude/worktrees/
+.agents/
+.codex/
+
+# vm agent-entrypoint boot trace — a runtime log appended into the workspace by
+# gb_boot_trace; a diagnostic artifact, never committed.
+.gb-agent-boot-trace
+
+# Dependencies
+# Tool-managed dirs use the BARE name (no trailing slash). A `foo/` pattern
+# matches only a *directory*, so a symlink named `foo` — e.g. one linked into a
+# git worktree to run tests — slips past it and `git add -A` stages it (how a
+# node_modules symlink twice reached CI this repo's history). The bare name
+# matches the dir AND a same-named symlink/file, so tool output can't be
+# committed by accident. Only applied to names that are never a legitimately
+# tracked file (dependency/venv/cache/report dirs); generic names like dist/ or
+# build/ keep the trailing slash so they don't over-ignore a real file.
+node_modules
+.pnpm-store
+
+# Build outputs
+dist/
+build/
+out/
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# Coverage
+coverage/
+coverage.json
+.c8-output
+.coverage
+.coverage.*
+.py-coverage.lock
+htmlcov
+
+# Mutation testing (Stryker): sandbox, HTML report, and the incremental cache
+.stryker-tmp
+reports/
+
+# Generated LaunchAgent (rendered from the .template by setup.bash at install time)
+launchagents/*.generated.plist
+
+# Python
+__pycache__
+*.pyc
+.venv
+.uv
+.pytest_cache
+
+# `uv run` inside inspect-glovebox/, glovebox-monitor/ or glovebox-driver/ writes a lock
+# beside that pyproject.toml. Each wheel is a library, so it pins nothing; committing one
+# adds a `uv.lock -merge` path that scripts/lib-regen-rules.mjs owns no rule for, which
+# reds the JS suite.
+/inspect-glovebox/uv.lock
+/glovebox-monitor/uv.lock
+/glovebox-driver/uv.lock
+# pytest scratch (repo-relative --basetemp): throwaway fixture files, including
+# fake executables the suite writes (keyprobe, docker stubs). Ignored so they never
+# surface as uncommitted changes or get captured onto a session-end review branch.
+.pytest-tmp
+
+# Fuzzer crash reproducers (jazzer.js / atheris drop these in the repo root, which
+# is their cwd). Anchored with a leading slash: an unanchored `crash-*` matches at
+# ANY depth, so it silently swallowed bin/checks/vm/crash-resilience-int.bash — a
+# `git add` of a legitimately-named source file that reports success and stages
+# nothing.
+/crash-*
+/timeout-*
+/oom-*
+/leak-*
+
+# History working files — each lives on the perf-history or ci-timings branch and is
+# seeded into the checkout by persist-perf-history.sh read or record-setup-timing.sh;
+# never committed to main or a feature branch. A glob, not a list: a tool that walks
+# "tracked plus untracked-not-ignored" takes a seeded file for a repository file, and
+# a per-metric list leaves the next metric's file out of the pattern.
+.github/*-history.json
+.github/*-history.jsonl
+
+# pytest --basetemp droppings (used where /tmp is noexec)
+.pytest-exec-tmp
+
+# Hypothesis property-testing example database (regenerated locally; never committed)
+.hypothesis/
+
+# CI timing maps that balance the shard fan-outs. They live in R2 (uploaded only by
+# main runs, fetched best-effort by CI — see .github/ci-durations.json) and are never
+# committed; ignored so a CI fetch or a local `uv run pytest --store-durations` /
+# vm-live run can't accidentally stage them.
+tests/.gb-test-durations.json
+tests/.gb-test-uninstrumented-durations.json
+tests/.gb-kcov-durations.json
+tests/.gb-drvfs-durations.json
+tests/.gb-macos-durations.json
+# The plan job's published shard assignment, one per leg (keyed by that leg's
+# duration-map name): derived from the fetched map, shipped to the shards in the
+# same artifact, never committed.
+tests/.gb-*-shard-assignment.json
+tests/.gb-select-maps.json
+.github/vm-live/durations.json
+.github/kata-live/durations.json
+
+# The pinned scanner binary that .github/scripts/python-deps-vuln-scan.sh downloads
+# into the repo root (~56 MB). Running that script locally to reproduce a red
+# osv-scanner check is the documented response to one, so the artifact lands in
+# every contributor's tree; ignored so it can't be staged by a `git add -A`.
+/osv-scanner
+
+# esbuild output — every artifact scripts/build-hook-bundles.mjs or
+# scripts/build-vm-dispatcher.mjs writes, wherever its home. Built once per tree by
+# `pnpm install`'s postinstall, by setup.bash at install time, in the nix buildPhase and
+# in the image's own bundler stage, so the reviewable surface is the sources plus
+# pnpm-lock.yaml. Suffix, not a directory or a member list: a bundle whose home the
+# pattern misses leaves every tree that builds it permanently dirty.
+*.bundle.mjs
+
+# Sharded mutation configs are deterministic build output. The planner and
+# `pnpm install` render them from config/mutation-sessions.json.
+/tools/mutation/*of*.toml
+
+# The pinned kcov binary that tests/install-kcov-local.sh builds into the repo
+# root — the same path .github/actions/install-kcov caches to, so tests/run-kcov.sh
+# finds a local build with no PATH edit. Reproducing a red "Bash coverage (kcov)"
+# check locally is the documented response to one, so the artifact lands in every
+# contributor's tree; ignored so it can't be staged by a `git add -A`.
+/kcov-bin/
+.claude/.hookpin-*/
+
+# synced-deps.test.mjs's untracked-file probe, mkdtemp'd under a synced path on
+# purpose. Ignored so a concurrent `git add -A` elsewhere in this checkout can't
+# stage it mid-test: staged, it would pass trackedUnder()'s check and leave an
+# AD entry in the shared index once the test deletes it from disk.
+.claude/consumer-probe-*/
+
+# `ct settings pull` writes this per-checkout pin cache into the repo root. The pin this
+# harness measures lives in evals/control_tower/ct-settings-pin.txt; a committed copy here
+# would be a second one that drifts.
+.settings.local.yml
+
+# `gh` writes its per-machine state here when it runs with the repo root as the
+# XDG state home — a device identifier, which no checkout should carry.
+/.local/
+
+# Generated doc pages, published to the CDN instead of committed
+# (scripts/render-doc-site.py, .github/workflows/docs-publish.yaml). A committed
+# page is re-derived by every branch that touches its generator's inputs, which
+# made these the busiest files in the history and conflicted branches on bytes
+# nobody typed. Their generators still run, and still refuse a bad input; only
+# the output stays out of the tree.
+/docs/architecture-callgraph.md
+/docs/ci-map.generated.md
+/docs/inspect-evals-coverage.generated.md
+/docs/tla/configs.md
+/docs/tla/reachable-subsets.md
+/docs/tla/diagrams/
+/docs/tla/modules/
+# TLC's own scratch metadir, written here by a run given no -metadir.
+/docs/tla/states/
+
+# The eval time series live on the `metrics-history` branch, which `main` never
+# merges (.github/scripts/eval-series.sh). A tracker or a local run materializes its
+# own working copy here; committing one would put the series back on the merge path.
+metrics/monitor-eval.jsonl
+metrics/sabotage-eval.jsonl
+metrics/breakout-ctf.jsonl
+
+# `nix build` links its output here.
+/result
+/result-*
+
+# go build output of the guest network daemon
+bin/lib/kata/netd/netd

glovebox_hosts-0.4.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.5
+Name: glovebox-hosts
+Version: 0.4.0
+Summary: The one hostname spelling and host-matching rules every glovebox component applies
+Project-URL: Homepage, https://github.com/AlexanderMattTurner/agent-glovebox
+Project-URL: Source, https://github.com/AlexanderMattTurner/agent-glovebox
+Author: AlexanderMattTurner
+License-Expression: Apache-2.0
+Keywords: egress,glovebox,hostname,sandbox
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Requires-Dist: tldextract==5.3.2
+Description-Content-Type: text/markdown
+
+# glovebox-hosts
+
+The one answer to "which host is this" that every part of glovebox uses: the egress proxy's verdict service, the launcher, the WebFetch hook, the session driver and the evals.
+
+A host is compared in one spelling: ASCII only, surrounding whitespace removed, lowercased, and an IP literal in its standard form. A name that is not ASCII, or that starts or ends with a dot, is refused with `HostError` rather than folded, so two readers can never disagree about it.
+
+```python
+>>> from glovebox_hosts import canonical_host, split_authority, granting_entries
+>>> split_authority("[2001:DB8::1]:443")
+('2001:db8::1', 443)
+>>> granting_entries("API.example.com", ["example.com"])
+['example.com']
+>>> granting_entries("a.b.example.com", ["example.com"])
+[]
+```
+
+A grant reaches the entry and one label below it, the depth one certificate wildcard covers. A bar (`constraining_entries`) reaches any depth. A grant may not name a `*.` wildcard over a public suffix, or over a name with one below it (`suffix_below`): `grant_name_refusal` says why, reading the Public Suffix List that `tldextract` bundles. A grant on a public suffix itself is allowed, and `grant_is_exact` tells the policy render to hold it to that one host. That is the package's one dependency, and it is imported only when a grant name is judged.
+
+`pod_grants` reads a Kata pod's `glovebox.dev/egress-grants` annotation as every node reads it, so an admission webhook can refuse a pod at submission for the same reason the node would refuse it later. It returns the granted hosts at their tiers and the address grants, and raises `GrantRefused` with the node's own message for the first entry the node refuses. How wide an address grant may be is each node's own setting, so it is not checked here.
+
+```python
+>>> from glovebox_hosts import GrantRefused, pod_grants
+>>> pod_grants('["httpbin.org", {"host": "203.0.113.5:8443", "rw": true}]').hosts
+{'httpbin.org': 'ro'}
+>>> pod_grants('["*.amazonaws.com"]')
+Traceback (most recent call last):
+...
+glovebox_hosts.GrantRefused: glovebox.dev/egress-grants: '*.amazonaws.com' is a wildcard over a name with the public suffix ...
+```

glovebox_hosts-0.4.0/README.md

@@ -0,0 +1,29 @@
+# glovebox-hosts
+
+The one answer to "which host is this" that every part of glovebox uses: the egress proxy's verdict service, the launcher, the WebFetch hook, the session driver and the evals.
+
+A host is compared in one spelling: ASCII only, surrounding whitespace removed, lowercased, and an IP literal in its standard form. A name that is not ASCII, or that starts or ends with a dot, is refused with `HostError` rather than folded, so two readers can never disagree about it.
+
+```python
+>>> from glovebox_hosts import canonical_host, split_authority, granting_entries
+>>> split_authority("[2001:DB8::1]:443")
+('2001:db8::1', 443)
+>>> granting_entries("API.example.com", ["example.com"])
+['example.com']
+>>> granting_entries("a.b.example.com", ["example.com"])
+[]
+```
+
+A grant reaches the entry and one label below it, the depth one certificate wildcard covers. A bar (`constraining_entries`) reaches any depth. A grant may not name a `*.` wildcard over a public suffix, or over a name with one below it (`suffix_below`): `grant_name_refusal` says why, reading the Public Suffix List that `tldextract` bundles. A grant on a public suffix itself is allowed, and `grant_is_exact` tells the policy render to hold it to that one host. That is the package's one dependency, and it is imported only when a grant name is judged.
+
+`pod_grants` reads a Kata pod's `glovebox.dev/egress-grants` annotation as every node reads it, so an admission webhook can refuse a pod at submission for the same reason the node would refuse it later. It returns the granted hosts at their tiers and the address grants, and raises `GrantRefused` with the node's own message for the first entry the node refuses. How wide an address grant may be is each node's own setting, so it is not checked here.
+
+```python
+>>> from glovebox_hosts import GrantRefused, pod_grants
+>>> pod_grants('["httpbin.org", {"host": "203.0.113.5:8443", "rw": true}]').hosts
+{'httpbin.org': 'ro'}
+>>> pod_grants('["*.amazonaws.com"]')
+Traceback (most recent call last):
+...
+glovebox_hosts.GrantRefused: glovebox.dev/egress-grants: '*.amazonaws.com' is a wildcard over a name with the public suffix ...
+```

glovebox_hosts-0.4.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "glovebox-hosts"
+version = "0.4.0"
+description = "The one hostname spelling and host-matching rules every glovebox component applies"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+authors = [{ name = "AlexanderMattTurner" }]
+keywords = ["glovebox", "sandbox", "egress", "hostname"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+]
+# Imported only when a grant name is judged, so the guest image and the Lima VM still
+# import this module from a bare PYTHONPATH. Pinned: the bundled list decides the verdict.
+dependencies = ["tldextract==5.3.2"]
+
+[project.urls]
+Homepage = "https://github.com/AlexanderMattTurner/agent-glovebox"
+Source = "https://github.com/AlexanderMattTurner/agent-glovebox"
+
+[build-system]
+# scripts/write-python-pins.mjs writes this version from the root pyproject's dev pin;
+# an edit here is overwritten by the next `pnpm install` or commit.
+requires = ["hatchling==1.32.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/glovebox_hosts"]

glovebox_hosts-0.4.0/src/glovebox_hosts/__init__.py

@@ -0,0 +1,635 @@
+"""The one spelling of a hostname, and the host rules every glovebox reader applies.
+
+PROBLEM CLASS — the launcher, the host proxy's verdict service, the WebFetch hook, the
+driver's evidence reader and the evals each ask "which host is this". Answered twice, a
+host one layer admits reads as another host to the next. Its import needs the standard
+library only, so the guest, the Lima VM and a published package all import this one file.
+Judging a grant name imports tldextract, which only a host that renders a policy carries.
+
+The WebFetch hook imports it under the host's own python3, which is 3.9 on a stock Mac,
+so every `X | None` annotation is quoted: evaluated at definition time, it raises there.
+"""
+
+import argparse
+import functools
+import ipaddress
+import json
+import re
+import string
+import sys
+from collections.abc import Callable, Iterable, Iterator
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, NamedTuple, overload
+
+if TYPE_CHECKING:
+    import tldextract
+
+
+class HostError(ValueError):
+    """A string that names no host this tree can rule on, or no readable authority."""
+
+
+def canonical_host(host: str) -> str:
+    """HOST as the one spelling every comparison uses: ASCII, stripped, lowercased.
+
+    INVARIANT: a name two readers could fold apart is refused, never folded. `str.lower`
+    turns U+212A KELVIN SIGN into `k`, and `str.strip` removes U+00A0, so the ASCII read
+    runs first. A trailing dot is refused because no allowlist entry carries one.
+    """
+    if not host.isascii():
+        raise HostError(f"{host!r} is not an ASCII hostname")
+    host = host.strip().lower()
+    if not host or host.startswith(".") or host.endswith("."):
+        raise HostError(f"{host!r} is empty or starts or ends with a dot")
+    try:
+        return str(ipaddress.ip_address(host))
+    except ValueError:
+        return host
+
+
+@overload
+def split_authority(authority: str, default_port: int) -> tuple[str, int]: ...
+@overload
+def split_authority(
+    authority: str, default_port: None = None
+) -> "tuple[str, int | None]": ...
+def split_authority(
+    authority: str, default_port: "int | None" = None
+) -> "tuple[str, int | None]":
+    """The canonical host and the port of `host`, `host:port` or `[v6]:port`.
+
+    Userinfo, a path, a query, a fragment, any whitespace, an unbalanced bracket and a
+    port outside 1-65535 are refused: each hands the host rule one name while a client
+    dials another (`user@gateway` reads as `gateway`).
+    """
+    if any(mark in authority for mark in "@?#/") or any(
+        character.isspace() for character in authority
+    ):
+        raise HostError(
+            f"invalid authority: {authority!r} carries userinfo, a path or whitespace"
+        )
+    if authority.startswith("["):
+        host, closer, rest = authority[1:].partition("]")
+        if not closer or (rest and not rest.startswith(":")):
+            raise HostError(
+                f"invalid authority: {authority!r} is not a bracketed address"
+            )
+        # INVARIANT: brackets hold only an IPv6 literal with no zone ID, so `[[]`,
+        # `[1.2.3.4]` or `[fe80::1%[]` never reaches the host rule as another name.
+        try:
+            zoned = ipaddress.IPv6Address(host).scope_id is not None
+        except ValueError as exc:
+            raise HostError(
+                f"invalid authority: {authority!r} is not a bracketed IPv6 literal"
+            ) from exc
+        if zoned:
+            raise HostError(f"invalid authority: {authority!r} names an IPv6 zone")
+        port = rest[1:]
+    elif "[" in authority or "]" in authority:
+        raise HostError(f"invalid authority: {authority!r} is not a bracketed address")
+    else:
+        host, _, port = authority.partition(":")
+    if not host:
+        raise HostError(f"invalid authority: {authority!r} names no host")
+    host = canonical_host(host)
+    if not port:
+        return host, default_port
+    # `isascii` before `isdigit`: `²` is a digit to str.isdigit() and not to int().
+    if not port.isascii() or not port.isdigit() or not 1 <= int(port) <= 65535:
+        raise HostError(f"invalid authority: {authority!r} names no port in 1-65535")
+    return host, int(port)
+
+
+def render_authority(host: str, port: "int | None") -> str:
+    """HOST as an authority, PORT appended when not None, an IPv6 literal bracketed.
+
+    `split_authority` strips the brackets, and `2001:db8::1:443` names neither the
+    address nor the port, so every authority this tree writes goes through here.
+    """
+    literal = f"[{host}]" if ":" in host else host
+    return literal if port is None else f"{literal}:{port}"
+
+
+def _without_port(authority: str) -> str:
+    """AUTHORITY less a trailing `:digits` port and the brackets round the host left."""
+    try:
+        ipaddress.ip_address(authority)
+    except ValueError:
+        head, colon, tail = authority.rpartition(":")
+        if colon and tail.isascii() and tail.isdigit():
+            return head[1:-1] if head.startswith("[") and head.endswith("]") else head
+    return authority
+
+
+def record_authority(authority: str) -> "tuple[str, int | None]":
+    """The canonical host and port a policy-log entry's AUTHORITY names.
+
+    A refused authority is what the agent typed. One `split_authority` rejects (a bare IPv6
+    literal, a port past 65535) keeps its host with the port dropped. Only an ASCII host is
+    lowercased, because `str.lower` folds U+212A KELVIN SIGN to `k`; ASCII space is stripped.
+    """
+    # ASCII whitespace only: a Unicode space stripped here would fold a name the
+    # verdict service refuses into the ASCII host it would have admitted.
+    authority = authority.strip(string.whitespace)
+    try:
+        return split_authority(authority)
+    except HostError:
+        pass
+    authority = _without_port(authority)
+    try:
+        return canonical_host(authority), None
+    except HostError:
+        return (authority.lower() if authority.isascii() else authority), None
+
+
+# Every matcher below re-canonicalises its whole entry table per host, and the failed
+# `ip_address` parse each hostname pays made a policy render quadratic. Only entries reach
+# this cache, never a request host, so no stream of request hosts can evict the table.
+# A call that raises is never cached, so a malformed entry raises on every call.
+_canonical_entry = functools.lru_cache(maxsize=4096)(canonical_host)
+
+
+def _canonical_entries(entries: Iterable[str]) -> Iterator[tuple[str, str]]:
+    """Each non-blank entry as spelled, beside its canonical form.
+
+    A blank entry is skipped because an empty suffix matches every host. A malformed
+    entry raises, because a matcher that quietly skipped it would miss a bar.
+    """
+    for entry in entries:
+        if entry.strip():
+            yield entry, _canonical_entry(entry)
+
+
+def is_wildcard(entry: str) -> bool:
+    """Whether ENTRY is spelled `*.S`, the marker of a grant over every name below S."""
+    return entry.startswith("*.")
+
+
+def _below_wildcard(host: str, canonical: str) -> bool:
+    """Whether CANONICAL is a `*.S` entry and HOST sits any depth below S, never at S."""
+    # allow-affix-match: `canonical[1:]` is `.S`, so the leading dot anchors a label boundary.
+    return is_wildcard(canonical) and host.endswith(canonical[1:])
+
+
+def granting_entries(host: str, entries: Iterable[str]) -> list[str]:
+    """Every entry whose GRANT reaches HOST — the entry itself, or one label below.
+
+    A named grant reaches as far as one certificate wildcard covers: `example.com`
+    names `api.example.com` and not `api.eu.example.com`. A `*.S` entry reaches every
+    depth below S and never S itself. A caller needing one entry takes the LONGEST.
+    A policy row marked exact narrows its entry to itself; the render marks a public
+    suffix's row so (`grant_is_exact`), and every row reader honours the mark.
+    """
+    host = canonical_host(host)
+    parent = host.partition(".")[2]
+    return [
+        entry
+        for entry, canonical in _canonical_entries(entries)
+        if canonical in (host, parent) or _below_wildcard(host, canonical)
+    ]
+
+
+def constraining_entries(host: str, entries: Iterable[str]) -> list[str]:
+    """Every entry whose BAR reaches HOST — the entry itself, or any depth below it.
+
+    A bar someone can step under bars nothing, so this rule runs the whole subtree.
+    """
+    host = canonical_host(host)
+    return [
+        entry
+        for entry, canonical in _canonical_entries(entries)
+        if host == canonical
+        # allow-affix-match: the leading dot anchors the match at a label boundary.
+        or host.endswith("." + canonical)
+        or _below_wildcard(host, canonical)
+    ]
+
+
+def governing_entry(
+    host: str,
+    entries: Iterable[str],
+    reach: Callable[[str, Iterable[str]], list[str]],
+) -> "str | None":
+    """The LONGEST entry whose REACH covers HOST, or None when none does.
+
+    REACH is required: `granting_entries` and `constraining_entries` reach differently.
+    Longest by the canonical spelling less a `*.` marker, a named entry winning a tie, so
+    neither padding nor entry order picks the answer. Every longest-match rule names it here.
+    """
+    matches = reach(host, entries)
+    if not matches:
+        return None
+    return max(matches, key=_entry_depth)
+
+
+def _entry_depth(entry: str) -> tuple[int, bool]:
+    canonical = _canonical_entry(entry)
+    return len(wildcard_suffix(canonical)), not is_wildcard(canonical)
+
+
+def family_tier(host: str, tiers: dict[str, str]) -> str:
+    """The tier of the entry in TIERS that governs HOST, or "".
+
+    TIERS naming one host under two spellings is refused, as the gateway refuses it: a
+    tier chosen by key order could grant what the host proxy denies.
+    """
+    spelled: dict[str, str] = {}
+    for entry, canonical in _canonical_entries(tiers):
+        if canonical in spelled:
+            raise HostError(f"{entry!r} and {spelled[canonical]!r} are one host")
+        spelled[canonical] = entry
+    governing = governing_entry(host, tiers, granting_entries)
+    return "" if governing is None else tiers[governing]
+
+
+_LABEL = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?")
+_PLAIN = re.compile(r"[A-Za-z0-9._-]*")
+
+
+def valid_domain_name(name: str) -> bool:
+    """Whether NAME is a bare DNS hostname a workspace or a grant may name.
+
+    Dot-separated labels of 1-63 letters, digits and hyphens, each edged with a letter
+    or digit, 253 characters at most, and at least one dot. The last label starts with
+    a letter, which refuses every IPv4 spelling inet_aton(3) dials, octal and hex
+    included (`0177.0.0.1` reaches 127.0.0.1). A URL, a port, a wildcard, whitespace
+    and a trailing dot all fail, so no such value seeds an allowlist entry.
+    """
+    if len(name) > 253 or not name.isascii():
+        return False
+    labels = name.split(".")
+    return (
+        len(labels) > 1
+        and labels[-1][:1].isalpha()
+        and all(len(label) <= 63 and _LABEL.fullmatch(label) for label in labels)
+    )
+
+
+def wildcard_suffix(name: str) -> str:
+    """NAME less a leading `*.`: the suffix S a `*.S` grant names, or NAME itself."""
+    return name.removeprefix("*.")
+
+
+# Names judged public suffixes whatever the bundled list says. Each value names what the
+# label below the suffix belongs to. The first is pinned so the refusal does not depend on
+# upstream list churn; the bundled snapshot carries it today. The other two the list lacks.
+_PUBLIC_SUFFIX_SUPPLEMENT = {
+    "blob.core.windows.net": "an Azure storage account",
+    "web.core.windows.net": "an Azure storage account's static site",
+    "modal.run": "a Modal workspace",
+}
+
+
+@functools.cache
+def _suffix_of() -> "Callable[[str], str]":
+    """The public suffix of a host, read from the Public Suffix List tldextract bundles.
+
+    Offline: `suffix_list_urls=()` and `cache_dir=None` read the snapshot and write
+    nothing. `include_psl_private_domains=True` admits the list's private section, where
+    `github.io` and `blob.core.windows.net` sit. ImportError where tldextract is absent.
+    """
+    extract = _extractor()
+    return lambda host: extract(host).suffix
+
+
+@functools.cache
+def _extractor() -> "tldextract.TLDExtract":
+    """The offline tldextract reader `_suffix_of` and `suffix_below` share."""
+    import tldextract  # pylint: disable=import-outside-toplevel
+
+    return tldextract.TLDExtract(
+        suffix_list_urls=(), include_psl_private_domains=True, cache_dir=None
+    )
+
+
+@functools.cache
+def _suffix_rules() -> tuple[str, ...]:
+    """Every public suffix rule, folded and sorted, a `*.S` rule kept as written. An
+    exception rule (`!host`) names a host that is NOT a suffix, so none is kept."""
+    rules = {rule.lower() for rule in _extractor().tlds if not rule.startswith("!")}
+    # The list spells an internationalized rule in Unicode, and a grant names it in
+    # punycode, so each rule is kept in both spellings.
+    spelled = rules | {_ascii_rule(rule) for rule in rules}
+    return tuple(sorted(spelled | set(_PUBLIC_SUFFIX_SUPPLEMENT)))
+
+
+def _ascii_rule(rule: str) -> str:
+    """RULE with each non-ASCII label in its punycode spelling, or RULE unchanged where
+    a label has none."""
+    try:
+        return ".".join(
+            label if label.isascii() else label.encode("idna").decode("ascii")
+            for label in rule.split(".")
+        )
+    except UnicodeError:
+        return rule
+
+
+def suffix_below(host: str) -> "str | None":
+    """A public suffix rule strictly below HOST, or None. A `*.S` grant reaches every
+    depth below S, so one over such a host also reaches the names strangers register
+    under that suffix: `*.amazonaws.com` reaches `bucket.s3.amazonaws.com`.
+    ImportError where tldextract is absent."""
+    dotted = "." + wildcard_suffix(host.strip().lower())
+    return next((rule for rule in _suffix_rules() if rule.endswith(dotted)), None)
+
+
+def is_public_suffix(host: str) -> bool:
+    """True when HOST's grant reaches a name a stranger registers a label below.
+
+    Folded, as every host rule folds, so `Modal.run` is judged as `modal.run`. The probe
+    label is what reads the list's WILDCARD rules: `*.compute.amazonaws.com` leaves
+    `compute.amazonaws.com` looking like an ordinary domain while the one label below it
+    is a different stranger's host each time. A `*.S` entry is read as S.
+    """
+    folded = wildcard_suffix(host.strip().lower())
+    if folded in _PUBLIC_SUFFIX_SUPPLEMENT:
+        return True
+    reached = f"a.{folded}"
+    return _suffix_of()(reached) in (folded, reached)
+
+
+def grant_name_refusal(name: str) -> "str | None":
+    """Why NAME is no host a grant may name, as a phrase that follows the name, or None.
+
+    A grant names a `valid_domain_name`, or `*.S` for one. `*.S` reaches every name
+    below S, so it is refused when S is a public suffix, or when one lies below S
+    (`suffix_below`): either way it hands the grant to strangers. A plain public suffix
+    such as `httpbin.org` may be granted, because `grant_is_exact` holds its grant to
+    that one host instead of one label below it.
+
+    INVARIANT: without tldextract every name is refused, because a name this python cannot
+    judge may be a public suffix, and a grant over one reaches strangers.
+    """
+    if not valid_domain_name(wildcard_suffix(name)):
+        return (
+            "is not a valid hostname (letters, digits, dots and hyphens, with at least"
+            " one dot) or a `*.` wildcard over one"
+        )
+    try:
+        public = is_public_suffix(name)
+        below = suffix_below(name) if is_wildcard(name) and not public else None
+    except ImportError:
+        return (
+            f"cannot be judged: {sys.executable} cannot import tldextract to tell"
+            " whether it is, or spans, a public suffix. Install tldextract==5.3.2 into"
+            " that python"
+        )
+    if public and is_wildcard(name):
+        return (
+            "is a wildcard over a public suffix, so it reaches every name a stranger"
+            " registers below it. Name the one host you meant"
+        )
+    if below is not None:
+        return (
+            f"is a wildcard over a name with the public suffix {below!r} below it, so"
+            " it reaches every name a stranger registers there. Name the one host you"
+            " meant"
+        )
+    return None
+
+
+def grant_is_exact(name: str) -> bool:
+    """Whether a grant on NAME reaches NAME alone, never the one label below it that a
+    plain grant reaches: NAME is a plain public suffix, whose labels strangers register.
+
+    ImportError where tldextract is absent: an answer of False there would let a public
+    suffix reach the strangers below it, so the caller must refuse rather than guess.
+    """
+    if is_wildcard(name):
+        return False
+    return is_public_suffix(name)
+
+
+def valid_grant_name(name: str) -> bool:
+    """Whether NAME is a host a grant may name: `grant_name_refusal` finds no fault.
+
+    `*.S` reaches every name below S and never S itself. S keeps the one-dot floor, so
+    `*`, `*.com`, `**.example.com` and `a.*.example.com` all fail, and so does `*.co.uk`.
+    `co.uk` itself passes, as a grant `grant_is_exact` holds to that one host.
+    """
+    return grant_name_refusal(name) is None
+
+
+def lookalike(name: str) -> bool:
+    """Whether NAME carries an `xn--` label or a character outside `[A-Za-z0-9._-]`.
+
+    Those are the shapes a homoglyph of an allowlisted host hides behind. The punycode
+    test ignores case, because DNS does: `XN--80AK6AA92E.com` is the same host. A
+    leading `*.` is a wildcard grant's marker, so the test reads the suffix below it.
+    """
+    name = wildcard_suffix(name)
+    return "xn--" in name.lower() or not _PLAIN.fullmatch(name)
+
+
+# The annotation a Kata pod names its own egress grants in, and the keys one grant object
+# may carry. A reader would ignore any other key, so a key meant to narrow a grant would
+# widen it unread: the grant is refused instead.
+ANNOTATION_GRANTS = "glovebox.dev/egress-grants"
+GRANT_KEYS = frozenset({"host", "rw"})
+DEFAULT_PORT = 443  # the port an address grant opens when it names none
+
+
+class GrantRefused(ValueError):
+    """A grant this tree will not open, with the sentence that says why."""
+
+
+@dataclass(frozen=True)
+class AddressGrant:
+    """One address grant as written: a network and the one port it opens."""
+
+    network: "ipaddress.IPv4Network | ipaddress.IPv6Network"
+    port: int
+
+
+def address_grant(entry: str) -> "AddressGrant | None":
+    """ENTRY as an address grant, None when it names a host, GrantRefused when malformed.
+
+    `ADDR`, `ADDR/PREFIX`, either with `:PORT`; IPv6 takes `[ADDR[/PREFIX]]:PORT` for a
+    port. The port defaults to DEFAULT_PORT. Host bits set under the prefix are refused.
+    How wide a network one grant may name is the caller's to judge.
+    """
+    text = entry.strip()
+    port_text: str | None = None
+    if text.startswith("["):
+        inner, closer, rest = text[1:].partition("]")
+        if not closer or (rest and not rest.startswith(":")):
+            raise GrantRefused(f"{entry!r} is not a bracketed IPv6 grant")
+        text, port_text = inner, rest[1:] if rest else None
+    elif text.count(":") == 1:
+        text, _, port_text = text.partition(":")
+    try:
+        network = ipaddress.ip_network(text, strict=True)
+    except ValueError as bad:
+        if "/" in text or ":" in text or entry.strip().startswith("["):
+            raise GrantRefused(f"{entry!r} is not an address grant: {bad}") from bad
+        return None
+    return AddressGrant(network=network, port=grant_port(port_text, entry))
+
+
+def grant_port(text: "str | None", entry: str) -> int:
+    """TEXT as a port; None, a port the entry never wrote, is DEFAULT_PORT. A port written
+    empty (`ADDR:`) is refused, never read as the default."""
+    if text is None:
+        return DEFAULT_PORT
+    if not (text.isascii() and text.isdigit() and 1 <= int(text) <= 65535):
+        raise GrantRefused(f"{entry!r} names no port in 1-65535")
+    return int(text)
+
+
+def grant_host_refusal(host: str) -> "str | None":
+    """Why HOST is no name a pod's grant may carry, as a whole phrase, or None: the grant
+    name rules plus `lookalike`. The forbidden-host bar applies at the render."""
+    fault = grant_name_refusal(host)
+    if fault is not None:
+        return f"{host!r} {fault}"
+    if lookalike(host):
+        return f"{host!r} carries punycode or non-ASCII characters"
+    return None
+
+
+class PodGrants(NamedTuple):
+    """What a pod's grants annotation names: each host at `ro` or `rw`, and each address."""
+
+    hosts: dict[str, str]
+    addresses: list[AddressGrant]
+
+
+def _as_text(value: object) -> str:
+    """A grant field as text. A non-string renders as JSON, so a boolean reads `true`."""
+    return value if isinstance(value, str) else json.dumps(value, ensure_ascii=False)
+
+
+def _grant_entries(text: str) -> list[tuple[str, str]]:
+    """Each `(entry, tier)` TEXT names: `"host"`, or `{"host": ..., "rw": ...}` where an
+    absent or false `rw` reads as read-only, the weaker."""
+    try:
+        listed = json.loads(text)
+    except (ValueError, RecursionError) as bad:
+        # RecursionError: an annotation nested deeper than the parser's stack.
+        raise GrantRefused(f"{ANNOTATION_GRANTS} is not JSON: {bad}") from bad
+    if not isinstance(listed, list):
+        raise GrantRefused(f"{ANNOTATION_GRANTS} is not a JSON list of hosts")
+    for raw in listed:
+        unknown = sorted(set(raw) - GRANT_KEYS) if isinstance(raw, dict) else []
+        if unknown:
+            raise GrantRefused(
+                f"{ANNOTATION_GRANTS}: a grant carries {unknown[0]!r}; "
+                f"a grant's keys are {' and '.join(sorted(GRANT_KEYS))}"
+            )
+    entries: list[tuple[str, str]] = []
+    for raw in listed:
+        grant = raw if isinstance(raw, dict) else {"host": raw}
+        rw_value = grant.get("rw")
+        rw = _as_text(False if rw_value is None or rw_value is False else rw_value)
+        host = _as_text(grant.get("host"))
+        if rw not in ("true", "false"):
+            raise GrantRefused(
+                f"{ANNOTATION_GRANTS}: {host}'s rw is {rw}, not a boolean"
+            )
+        entries.append((host, "rw" if rw == "true" else "ro"))
+    return entries
+
+
+def pod_grants(text: "str | None") -> PodGrants:
+    """What a Kata pod's `glovebox.dev/egress-grants` annotation TEXT grants, as every
+    node and admission webhook must read it. None, no annotation, grants nothing.
+
+    INVARIANT: the one reader of this annotation. GrantRefused names the first entry the
+    node would refuse the whole pod for. An address must carry `"rw": true`, since a
+    tunnel's bytes go unread. How wide an address may be is the node's own setting.
+    """
+    if text is None:
+        return PodGrants(hosts={}, addresses=[])
+    hosts: dict[str, str] = {}
+    addresses: list[AddressGrant] = []
+    for entry, tier in _grant_entries(text):
+        if entry != entry.strip():
+            # address_grant would strip it, and the name rules refuse it: judge one
+            # spelling, so a padded address is refused as a padded name is.
+            raise GrantRefused(
+                f"{ANNOTATION_GRANTS}: {entry!r} carries surrounding whitespace"
+            )
+        try:
+            grant = address_grant(entry)
+        except GrantRefused as bad:
+            raise GrantRefused(f"{ANNOTATION_GRANTS}: {bad}") from bad
+        if grant is not None:
+            if tier != "rw":
+                raise GrantRefused(
+                    f"{ANNOTATION_GRANTS}: {entry} is an address, which opens a raw "
+                    'tunnel; grant it with "rw": true'
+                )
+            addresses.append(grant)
+            continue
+        refusal = grant_host_refusal(entry)
+        if refusal is not None:
+            raise GrantRefused(f"{ANNOTATION_GRANTS}: {refusal}")
+        hosts[entry] = tier
+    return PodGrants(hosts=hosts, addresses=addresses)
+
+
+def _name_check(args: argparse.Namespace) -> None:
+    """Print `malformed`, `lookalike` or `ok` for NAME, the first fault found.
+
+    A shell caller maps the word to its own message and refuses on any other output,
+    so an interpreter that cannot run refuses too.
+    """
+    if not args.lookalike_only and not valid_domain_name(args.name):
+        print("malformed")
+    elif lookalike(args.name):
+        print("lookalike")
+    else:
+        print("ok")
+
+
+def _constraining(args: argparse.Namespace) -> None:
+    """Print each host on stdin that the denylist file bars, in one batch per launch."""
+    with open(args.entries, encoding="utf-8") as handle:
+        entries = handle.read().splitlines()
+    # A blank line is the batch's framing, as it is in the entry file; a host that is
+    # not blank and has no canonical spelling still raises.
+    for host in filter(str.strip, sys.stdin.read().splitlines()):
+        if constraining_entries(host, entries):
+            print(host)
+
+
+def _tier(args: argparse.Namespace) -> None:
+    """Print `{"tier": ..., "error": ...}` for HOST under the allowlist's `domains`,
+    plus the API hosts of the `--agent` the caller runs inside."""
+    with open(args.allowlist, encoding="utf-8") as handle:
+        document = json.load(handle)
+    domains = document["domains"]
+    if args.agent:
+        domains = {
+            **domains,
+            **document["agents"][args.agent]["api_host_allowlist_entries"],
+        }
+    try:
+        canonical_host(args.host)
+    except HostError as exc:
+        print(json.dumps({"tier": None, "error": str(exc)}))
+        return
+    # An entry that names no host is the allowlist's defect, so it raises past here.
+    print(json.dumps({"tier": family_tier(args.host, domains) or None, "error": None}))
+
+
+def main(argv: list[str]) -> None:
+    """`constraining ENTRIES`, `tier [--agent NAME] ALLOWLIST HOST` and `name-check [--lookalike-only]
+    NAME`, for callers outside Python."""
+    parser = argparse.ArgumentParser(prog="glovebox_hosts")
+    commands = parser.add_subparsers(required=True)
+    constraining = commands.add_parser("constraining")
+    constraining.add_argument("entries")
+    constraining.set_defaults(run=_constraining)
+    tier = commands.add_parser("tier")
+    tier.add_argument("--agent", default="")
+    tier.add_argument("allowlist")
+    tier.add_argument("host")
+    tier.set_defaults(run=_tier)
+    check = commands.add_parser("name-check")
+    check.add_argument("--lookalike-only", action="store_true")
+    check.add_argument("name")
+    check.set_defaults(run=_name_check)
+    args = parser.parse_args(argv)
+    args.run(args)

glovebox_hosts-0.4.0/src/glovebox_hosts/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m glovebox_hosts`: the host rule's command line, for callers outside Python."""
+
+import sys
+
+from glovebox_hosts import main
+
+main(sys.argv[1:])