primarypath-server 1.0.0__py3-none-any.whl

app/netguard.py

@@ -0,0 +1,73 @@
+"""SSRF guard for outbound callback_url (webhook) targets.
+
+The service POSTs the decision to a caller-supplied callback_url. Without a
+check, a caller could point it at an internal address (cloud metadata,
+loopback, private ranges) and have the service fetch it — SSRF. This
+validates the URL at create time.
+
+Self-hosted buyers legitimately POST to internal webhooks (an internal
+PagerDuty, a private queue), so private/loopback targets are allowed only
+when webhook_allow_private is set — but the cloud metadata range
+(169.254.0.0/16, including 169.254.169.254) is refused always, because
+nothing legitimate lives there.
+
+Note the residual risk: this validates the literal host at create time; a
+hostname that resolves to a public IP now but a private one later (DNS
+rebinding) is not caught here. Bind egress with a NetworkPolicy / firewall
+for defense in depth (documented in OPERATIONS).
+"""
+from __future__ import annotations
+
+import ipaddress
+from urllib.parse import urlparse
+
+
+class UnsafeCallbackURL(ValueError):
+    pass
+
+
+def _addresses(host: str) -> list[ipaddress._BaseAddress]:
+    # literal IP?
+    try:
+        return [ipaddress.ip_address(host)]
+    except ValueError:
+        pass
+    # hostname: resolve best-effort (may be empty if resolution fails)
+    import socket
+
+    out: list[ipaddress._BaseAddress] = []
+    try:
+        for info in socket.getaddrinfo(host, None):
+            try:
+                out.append(ipaddress.ip_address(info[4][0]))
+            except ValueError:
+                continue
+    except OSError:
+        pass
+    return out
+
+
+def validate_callback_url(url: str, allow_private: bool) -> None:
+    """Raise UnsafeCallbackURL if the target is unsafe for the posture."""
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        raise UnsafeCallbackURL("callback_url must be http(s)")
+    host = parsed.hostname
+    if not host:
+        raise UnsafeCallbackURL("callback_url has no host")
+
+    if host.lower() == "localhost" and not allow_private:
+        raise UnsafeCallbackURL("callback_url may not target localhost")
+
+    addrs = _addresses(host)
+    for ip in addrs:
+        assert isinstance(ip, (ipaddress.IPv4Address, ipaddress.IPv6Address))
+        # the cloud metadata / link-local range is refused ALWAYS
+        if ip.is_link_local:
+            raise UnsafeCallbackURL(
+                "callback_url may not target the link-local/metadata range")
+        if not allow_private and (ip.is_private or ip.is_loopback
+                                  or ip.is_reserved or ip.is_multicast):
+            raise UnsafeCallbackURL(
+                "callback_url may not target a private/loopback address "
+                "(set webhook_allow_private to allow internal webhooks)")

app/obslog.py

@@ -0,0 +1,105 @@
+"""Structured JSON logging with correlation ids and secret redaction.
+
+One JSON object per line on stdout. A redaction filter scrubs every
+configured secret (tokens, session secret, Slack/Teams credentials, PINs)
+from every record on every logger it is attached to — a leaked secret in
+a log line is an incident; this makes the safe path the default path.
+"""
+from __future__ import annotations
+
+import contextvars
+import datetime as dt
+import json
+import logging
+import re
+import uuid
+
+request_id_var: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "primarypath_request_id", default=None)
+
+
+def new_request_id() -> str:
+    return uuid.uuid4().hex[:12]
+
+
+def gather_secrets(settings) -> list[str]:
+    values = [
+        settings.service_token, settings.admin_token, settings.session_secret,
+        settings.oidc_client_secret, settings.slack_bot_token,
+        settings.slack_signing_secret, settings.teams_app_password,
+        settings.pkcs11_pin, settings.siem_token,
+    ]
+    return [v for v in values if v and len(v) >= 4]
+
+
+# Issued tokens (F22) are dynamic, so they can't be pre-registered like env
+# secrets; scrub them by their minted shape instead. Storage is hash-only —
+# this covers the plaintext-in-flight window (e.g. a response body logged in
+# an exception).
+_ISSUED_TOKEN_RE = re.compile(r"pp_(?:service|admin)_[A-Za-z0-9_-]{16,}")
+
+
+class RedactingFilter(logging.Filter):
+    def __init__(self, secrets: list[str]):
+        super().__init__()
+        self.secrets = secrets
+
+    def _scrub(self, text: str) -> str:
+        for s in self.secrets:
+            if s in text:
+                text = text.replace(s, "[REDACTED]")
+        return _ISSUED_TOKEN_RE.sub("[REDACTED]", text)
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        try:
+            message = record.getMessage()
+        except Exception:
+            return True
+        scrubbed = self._scrub(message)
+        if scrubbed != message:
+            record.msg = scrubbed
+            record.args = ()
+        return True
+
+
+class JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        out = {
+            "ts": dt.datetime.now(dt.UTC).isoformat(timespec="milliseconds"),
+            "level": record.levelname.lower(),
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+        rid = request_id_var.get()
+        if rid:
+            out["request_id"] = rid
+        if record.exc_info and record.exc_info[0] is not None:
+            out["exc"] = self.formatException(record.exc_info)
+        return json.dumps(out, ensure_ascii=False)
+
+
+_configured = False
+
+
+def setup_logging(settings) -> None:
+    """Idempotent: JSON handler + redaction on the root logger."""
+    global _configured
+    root = logging.getLogger()
+    redactor = RedactingFilter(gather_secrets(settings))
+    if _configured:
+        # refresh secrets on the existing handlers (new app, new settings)
+        for h in root.handlers:
+            h.filters = [f for f in h.filters
+                         if not isinstance(f, RedactingFilter)]
+            h.addFilter(redactor)
+        return
+    if settings.log_json:
+        handler = logging.StreamHandler()
+        handler.setFormatter(JsonFormatter())
+        handler.addFilter(redactor)
+        root.addHandler(handler)
+        root.setLevel(settings.log_level.upper())
+    else:
+        for h in root.handlers:
+            h.addFilter(redactor)
+    _configured = True

app/policy.py

@@ -0,0 +1,390 @@
+"""Event-sourced approval policy + the shadow -> assisted -> autonomous
+rollout, per tenant.
+
+The current policy is a fold of `policy_set` events (last-write-wins per
+action), materialized into the `policy_view` projection — same discipline
+as approvals_view: the log is truth, the table is a rebuildable cache.
+Changing policy appends a `policy_set` carrying `by`/`reason`, so weakening
+a control leaves a chained, signed, per-tenant record. The governance of
+the governance is audited.
+
+Modes:
+- assisted   -> requires a human decision (the default, fail-safe).
+- autonomous -> runs without approval; the service auto-grants by
+                `system:policy` so the loop resolves immediately.
+- sampled    -> earned autonomy with teeth: most proposals auto-grant,
+                but a DETERMINISTIC 1-in-N (HMAC-SHA256 of the approval_id,
+                keyed by a per-tenant server-side salt) is routed to a
+                human before execution. The middle rung between assisted
+                and autonomous: agents keep their speed, humans keep a
+                real, unpredictable-to-the-agent check. The salt is
+                disclosed in the admin-gated export, so an auditor can
+                recompute every pick; the agent plane cannot read it, so
+                an agent cannot grind call ids that are never sampled.
+- shadow     -> observe without gating: auto-grants, tagged shadow, while a
+                track record accrues. A rollout stage, not a trust level.
+
+IMPORTANT — shadow EXECUTES in this approval-gateway model. Unlike drangue's
+in-process Autonomy (where shadow means "propose, do not run"), the service
+only speaks approved/denied over HTTP; it cannot stop a framework-agnostic
+agent from running a granted action. Shadow here is the F13 "record-only"
+stage: the tool runs and the proposal is logged for the track record. Do NOT
+use shadow to observe a dangerous action without side effects — use assisted
+(a human gates it) or leave the action ungoverned but ingest run_events. The
+auto-grant reason always names the mode so the decision is never silent.
+
+`requires_approval` is the master gate; `mode` drives the track record and
+graduation. Setting a rule derives `requires_approval` from the mode when
+the caller does not pin it explicitly.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+import time
+
+from .ledger.store import DEFAULT_TENANT, Ledger
+
+MODES = ("shadow", "assisted", "sampled", "autonomous")
+POLICY_REVIEWER = "system:policy"
+DEFAULT_SAMPLE_N = 10
+
+VIEW_COLUMNS = (
+    "action, requires_approval, reversible, mode, allow, deny, "
+    "approver_groups, require_second_approval, sample_n, updated_by, "
+    "reason, updated_ts_ms, risk, blast_radius, version"
+)
+RISKS = ("low", "medium", "high", "critical")
+
+
+def default_risk(reversible: bool, require_second: bool) -> str:
+    """Server-authored risk when the admin did not state one: an
+    irreversible action is high, irreversible under dual control critical."""
+    if not reversible:
+        return "critical" if require_second else "high"
+    return "medium"
+
+
+def default_requires_approval(mode: str) -> bool:
+    """assisted gates; shadow/autonomous do not; sampled gates per
+    approval (the 1-in-N pick, decided at create time)."""
+    return mode == "assisted"
+
+
+def sampled_for_review(approval_id: str, sample_n: int, salt: str) -> bool:
+    """The deterministic 1-in-N pick: HMAC-SHA256 over the approval_id,
+    keyed by a per-tenant server-side salt. Deterministic, so retrying the
+    same id gets the same answer — and KEYED, because the agent chooses
+    run_id:call_id: an unkeyed hash would let it grind call ids offline
+    until none of its proposals are ever sampled. The salt lives on the
+    operator plane (the agent token cannot read it) and is disclosed in
+    the admin-gated audit export, so an auditor can still recompute from
+    the export why any proposal was (or was not) routed to a human."""
+    if sample_n <= 1:
+        return True
+    digest = hmac.new(salt.encode("utf-8"), approval_id.encode("utf-8"),
+                      hashlib.sha256).digest()
+    return int.from_bytes(digest[:8], "big") % sample_n == 0
+
+
+class NotAnApprover(Exception):
+    """The reviewer is not in the action's approver_groups (F21)."""
+
+
+def check_approver_groups(rule: dict | None, identity: dict | None) -> None:
+    """Enforce 'who may approve': if the action pins approver_groups, a human
+    approver's IdP groups must intersect them. Admins bypass (the operator
+    can always decide). In dev/token mode (identity is None) there are no
+    groups to check — the deployment is single-trust."""
+    if not rule:
+        return
+    required = set(rule.get("approver_groups") or [])
+    if not required or identity is None:
+        return
+    if "admin" in (identity.get("roles") or []):
+        return
+    if not (set(identity.get("groups") or []) & required):
+        raise NotAnApprover(
+            "your groups do not include an approver group for this action")
+
+
+def case_controls(stored: dict | None, live: dict | None,
+                  identity: dict | None) -> bool:
+    """The controls a decision on an existing case must satisfy: the
+    stricter of the policy snapshotted when the case was created and the
+    rule as it stands now (B6). A relaxation applies to new proposals only;
+    a tightening applies to pending cases too. The reviewer must pass the
+    approver_groups of both, and dual control binds if either demands it.
+    Raises NotAnApprover; returns whether a second approver is required."""
+    for rule in (stored, live):
+        check_approver_groups(rule, identity)
+    return any(bool(r and r.get("require_second_approval"))
+               for r in (stored, live))
+
+
+def _row_to_rule(row: tuple) -> dict:
+    keys = [k.strip() for k in VIEW_COLUMNS.split(",")]
+    return dict(zip(keys, row))
+
+
+class PolicyStore:
+    def __init__(self, pool, ledger: Ledger, settings):
+        self.pool = pool
+        self.ledger = ledger
+        self.settings = settings
+        self._salts: dict[str, str] = {}
+
+    async def sampling_salt(self, tenant: str = DEFAULT_TENANT) -> str:
+        """The per-tenant key of the 1-in-N pick. Operational, not chained
+        (it is a secret against the agent, like a session key, not a fact
+        about the work); created on first use, immutable thereafter so
+        every historical pick stays recomputable."""
+        cached = self._salts.get(tenant)
+        if cached is not None:
+            return cached
+        async with self.pool.connection() as conn:
+            await conn.execute(
+                "INSERT INTO sampling_salt (tenant_id, salt) "
+                "VALUES (%s, %s) ON CONFLICT (tenant_id) DO NOTHING",
+                (tenant, secrets.token_hex(32)))
+            cur = await conn.execute(
+                "SELECT salt FROM sampling_salt WHERE tenant_id = %s",
+                (tenant,))
+            salt = (await cur.fetchone())[0]
+        self._salts[tenant] = salt
+        return salt
+
+    # -- read (fold via the projection) --------------------------------------
+
+    async def current_policy(self, tenant: str = DEFAULT_TENANT) -> list[dict]:
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                f"SELECT {VIEW_COLUMNS} FROM policy_view WHERE tenant_id = %s "
+                f"ORDER BY action", (tenant,))
+            rows = await cur.fetchall()
+        return [_row_to_rule(r) for r in rows]
+
+    async def policy_for(self, action: str,
+                         tenant: str = DEFAULT_TENANT) -> dict | None:
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                f"SELECT {VIEW_COLUMNS} FROM policy_view "
+                f"WHERE tenant_id = %s AND action = %s", (tenant, action))
+            row = await cur.fetchone()
+        return _row_to_rule(row) if row else None
+
+    async def effective(self, action: str,
+                        tenant: str = DEFAULT_TENANT) -> dict:
+        """The gating decision for an action: the rule if one exists, else
+        the configured fail-safe default (require approval)."""
+        rule = await self.policy_for(action, tenant)
+        if rule is not None:
+            # dual control implies a human gate: an action that demands two
+            # approvers can never be auto-granted, whatever the mode says
+            require_second = bool(rule.get("require_second_approval"))
+            out = {"requires_approval": (rule["requires_approval"]
+                                         or require_second),
+                   "mode": rule["mode"],
+                   "require_second_approval": require_second,
+                   "approver_groups": list(rule.get("approver_groups") or []),
+                   "reversible": bool(rule.get("reversible")),
+                   "risk": rule.get("risk") or default_risk(
+                       bool(rule.get("reversible")), require_second),
+                   "blast_radius": rule.get("blast_radius"),
+                   "version": rule.get("version"),
+                   "source": "policy"}
+            if rule["mode"] == "sampled":
+                out["sample_n"] = rule.get("sample_n") or DEFAULT_SAMPLE_N
+            return out
+        return {
+            "requires_approval": self.settings.policy_default_requires_approval,
+            "mode": "assisted" if self.settings.policy_default_requires_approval
+                    else "autonomous",
+            "require_second_approval": False,
+            "approver_groups": [],
+            # no rule: nothing vouches for reversibility, so it is treated
+            # as irreversible and high risk until an admin says otherwise
+            "reversible": False, "risk": "high", "blast_radius": None,
+            "version": None,
+            "source": "default",
+        }
+
+    @staticmethod
+    def snapshot(effective: dict) -> dict:
+        """The request-time policy snapshot stamped into approval_requested:
+        exactly what the console shows and the server enforces bulk
+        constraints on, versioned so a later rule change is visible."""
+        return {k: effective.get(k) for k in (
+            "version", "mode", "requires_approval", "reversible", "risk",
+            "blast_radius", "require_second_approval", "approver_groups",
+            "source")}
+
+    # -- write (append policy_set) -------------------------------------------
+
+    async def set_policy(self, action: str, *, mode: str, by: str,
+                         reason: str = "", reversible: bool = False,
+                         requires_approval: bool | None = None,
+                         allow: list | None = None, deny: list | None = None,
+                         approver_groups: list | None = None,
+                         require_second_approval: bool = False,
+                         sample_n: int | None = None,
+                         risk: str | None = None,
+                         blast_radius: str | None = None,
+                         tenant: str = DEFAULT_TENANT) -> dict:
+        if mode not in MODES:
+            raise ValueError(f"mode must be one of {MODES}")
+        if risk is not None and risk not in RISKS:
+            raise ValueError(f"risk must be one of {RISKS}")
+        risk = risk or default_risk(bool(reversible),
+                                    bool(require_second_approval))
+        if requires_approval is None:
+            requires_approval = default_requires_approval(mode)
+        if mode == "sampled":
+            sample_n = sample_n or DEFAULT_SAMPLE_N
+            if sample_n < 2:
+                raise ValueError("sample_n must be >= 2 (1 would gate all)")
+        else:
+            # inert outside sampled mode, but PRESERVED so a demote/promote
+            # round trip does not silently reset the rate
+            sample_n = sample_n or 0
+        payload = {
+            "action": action, "mode": mode,
+            "requires_approval": bool(requires_approval),
+            "reversible": bool(reversible),
+            "allow": allow or [], "deny": deny or [],
+            "approver_groups": approver_groups or [],
+            "require_second_approval": bool(require_second_approval),
+            "sample_n": sample_n,
+            "risk": risk, "blast_radius": blast_radius or None,
+            "by": by, "reason": reason,
+        }
+        await self.ledger.append("policy_set", payload, tenant=tenant)
+        rule = await self.policy_for(action, tenant)
+        assert rule is not None  # just appended
+        return rule
+
+    # -- rollout track record + graduation -----------------------------------
+
+    async def rollout(self, tenant: str = DEFAULT_TENANT,
+                      now: float | None = None) -> list[dict]:
+        """Per-action track record plus a graduation recommendation.
+
+        The record is a SQL aggregate over approvals_view (indexed on
+        tenant, tool, requested time) within an EXPLICIT lookback window —
+        policy_rollout_lookback_days, reported on every row as
+        `window_days` — never a silently truncated slice of history.
+        Incidents are counted from structured `incident_reported` events
+        (POST /api/approvals/{id}/incident), not from words in notes.
+        Actions come from both the policy and the approvals seen, so an
+        ungoverned-but-active action still surfaces."""
+        days = self.settings.policy_rollout_lookback_days
+        now_ms = int((now if now is not None else time.time()) * 1000)
+        since = now_ms - days * 86_400_000 if days > 0 else 0
+        rules = {r["action"]: r for r in await self.current_policy(tenant)}
+        auto = POLICY_REVIEWER + "%"
+
+        rec: dict[str, dict] = {}
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                """
+                SELECT tool,
+                       count(*),
+                       count(*) FILTER (WHERE status = 'pending'),
+                       count(*) FILTER (WHERE status = 'granted'
+                                        AND reviewer LIKE %s),
+                       count(*) FILTER (WHERE status = 'granted'
+                                        AND reviewer NOT LIKE %s),
+                       count(*) FILTER (WHERE status = 'denied')
+                FROM approvals_view
+                WHERE tenant_id = %s AND requested_ts_ms >= %s
+                GROUP BY tool
+                """, (auto, auto, tenant, since))
+            for tool, n, pending, auto_n, human_ok, human_no in \
+                    await cur.fetchall():
+                rec[tool] = {
+                    "proposals": n, "human_approvals": human_ok,
+                    "human_rejections": human_no, "auto_executed": auto_n,
+                    "pending": pending, "incidents": 0}
+            cur = await conn.execute(
+                """
+                SELECT payload_json->>'tool', count(*)
+                FROM events
+                WHERE tenant_id = %s AND type = 'incident_reported'
+                      AND ts_ms >= %s
+                GROUP BY 1
+                """, (tenant, since))
+            for tool, n in await cur.fetchall():
+                rec.setdefault(tool, {
+                    "proposals": 0, "human_approvals": 0,
+                    "human_rejections": 0, "auto_executed": 0,
+                    "pending": 0, "incidents": 0})["incidents"] = n
+
+        actions = sorted(set(rec) | set(rules))
+        out = []
+        for action in actions:
+            record = dict(rec.get(action, {
+                "proposals": 0, "human_approvals": 0, "human_rejections": 0,
+                "auto_executed": 0, "pending": 0, "incidents": 0}))
+            rule = rules.get(action)
+            mode = rule["mode"] if rule else "assisted"
+            reversible = bool(rule["reversible"]) if rule else False
+            decisions = record["human_approvals"] + record["human_rejections"]
+            record["decisions"] = decisions
+            record["approval_rate"] = (
+                record["human_approvals"] / decisions if decisions else None)
+            record["window_days"] = days
+            out.append({
+                "action": action, "mode": mode, "reversible": reversible,
+                "requires_approval": (rule["requires_approval"] if rule
+                                      else self.settings
+                                      .policy_default_requires_approval),
+                "record": record,
+                "recommendation": self._recommend(mode, reversible, record),
+            })
+        return out
+
+    def _recommend(self, mode: str, reversible: bool, record: dict) -> dict:
+        s = self.settings
+        decisions = record["decisions"]
+        rate = record["approval_rate"]
+        rejections = record["human_rejections"]
+        reject_rate = (rejections / decisions) if decisions else 0.0
+
+        # demote first: an incident or a rejection spike tightens the control
+        if record["incidents"] > 0 or (
+                decisions >= s.policy_graduation_min_decisions
+                and reject_rate >= s.policy_demotion_rejection_rate):
+            if mode in ("autonomous", "sampled"):
+                return {"action": "demote", "to_mode": "assisted",
+                        "why": (f"{record['incidents']} incident(s) reported "
+                                f"in the last {record.get('window_days')} days"
+                                if record["incidents"]
+                                else f"rejection rate {reject_rate:.0%} "
+                                f"over {decisions} decisions")}
+            if mode == "shadow":
+                return {"action": "demote", "to_mode": "assisted",
+                        "why": "tighten to human approval while risk is present"}
+            return {"action": "hold", "to_mode": mode,
+                    "why": "already gated by a human (assisted)"}
+
+        # promote: strong track record on a reversible action. assisted
+        # graduates to SAMPLED first (autonomy with a live 1-in-N check),
+        # sampled to autonomous once the sampled decisions also hold up.
+        if (mode in ("assisted", "shadow", "sampled") and reversible
+                and decisions >= s.policy_graduation_min_decisions
+                and rate is not None
+                and rate >= s.policy_graduation_approval_rate):
+            to_mode = "autonomous" if mode == "sampled" else "sampled"
+            return {"action": "promote", "to_mode": to_mode,
+                    "why": f"{rate:.0%} approval over {decisions} decisions, "
+                           f"reversible action"}
+
+        if mode in ("assisted", "shadow") and not reversible and rate == 1.0 \
+                and decisions >= s.policy_graduation_min_decisions:
+            return {"action": "hold", "to_mode": mode,
+                    "why": "strong record but action is irreversible — "
+                           "keep a human in the loop"}
+        return {"action": "hold", "to_mode": mode,
+                "why": f"{decisions} decisions "
+                       f"(need {s.policy_graduation_min_decisions} to graduate)"}

app/ratelimit.py

@@ -0,0 +1,78 @@
+"""A minimal in-memory rate limiter for abuse-sensitive endpoints.
+
+Fixed 1-minute window per (client IP, path-class). Guards auth, decisions,
+and chat interactions — brute-force / spam surfaces — and deliberately does
+NOT touch reads or agent polling (wait_for_decision polls GET faster than a
+limiter should allow). In-memory and per-replica; production should also
+rate-limit at the ingress. Dependency-free.
+"""
+from __future__ import annotations
+
+import hashlib
+import math
+
+# path prefixes that are guarded; everything else is unlimited
+GUARDED_PREFIXES = (
+    "/auth/login", "/auth/callback",
+    "/slack/interactions", "/teams/activities",
+)
+
+
+def is_guarded(method: str, path: str) -> bool:
+    if path.startswith(GUARDED_PREFIXES):
+        return True
+    # approval decisions: POST /api/approvals/{id}/decision
+    return (method == "POST" and path.startswith("/api/approvals/")
+            and path.endswith("/decision"))
+
+
+def _class(path: str) -> str:
+    for p in GUARDED_PREFIXES:
+        if path.startswith(p):
+            return p
+    return "decision"
+
+
+# authenticated agent WRITES: bounded per credential so a buggy or
+# compromised agent cannot turn its token into unbounded storage/CPU.
+# Reads and polling (wait_for_decision) are never limited.
+def is_agent_write(method: str, path: str) -> bool:
+    if method != "POST":
+        return False
+    if path in ("/api/approvals", "/api/evals", "/api/gate"):
+        return True
+    return path.startswith("/api/runs/") and path.endswith("/events")
+
+
+def agent_key(authorization: str | None, ip: str) -> str:
+    """The credential, not the address: replicas of one agent share a
+    token, and one NAT can front many agents."""
+    if authorization:
+        return "tok:" + hashlib.sha256(authorization.encode()).hexdigest()[:16]
+    return "ip:" + ip
+
+
+class RateLimiter:
+    def __init__(self, per_minute: int, agent_per_minute: int = 0):
+        self.per_minute = per_minute
+        self.agent_per_minute = agent_per_minute
+        self._buckets: dict[tuple[str, str, int], int] = {}
+
+    def _hit(self, subject: str, cls: str, now: float, limit: int) -> bool:
+        if limit <= 0:
+            return True
+        window = math.floor(now / 60)
+        key = (subject, cls, window)
+        count = self._buckets.get(key, 0) + 1
+        self._buckets[key] = count
+        # opportunistic cleanup of stale windows
+        if len(self._buckets) > 4096:
+            self._buckets = {k: v for k, v in self._buckets.items()
+                             if k[2] >= window}
+        return count <= limit
+
+    def allow(self, ip: str, path: str, now: float) -> bool:
+        return self._hit(ip, _class(path), now, self.per_minute)
+
+    def allow_agent_write(self, subject: str, now: float) -> bool:
+        return self._hit(subject, "agent_write", now, self.agent_per_minute)