intentplane 0.5.0__py3-none-any.whl

intentplane/packs/accounts_payable.cedar

@@ -0,0 +1,53 @@
+// Accounts-payable pack. Default deny; forbid overrides permit at every approval level.
+// Amounts are integer cents. approval_level: 0 none, 1 step-up (the accountant), 2 four-eyes (e.g. the CFO).
+// The vendor master is itself a protected resource: changing it is an intent, and a freshly changed
+// IBAN is less trusted than a stable one. The ERP invoice is the source of truth for vendor and amount.
+
+// --- vendor.update_bank_details: only after a call-back on the phone number the ERP already knew,
+//     and always with a second human.
+@id("forbid-bank-change-without-callback")
+forbid (principal, action == Action::"vendor.update_bank_details", resource)
+unless { context.callback_verified };
+
+@id("permit-bank-change-four-eyes")
+permit (principal, action == Action::"vendor.update_bank_details", resource)
+when { context.approval_level >= 2 };
+
+// --- invoice.pay
+@id("forbid-invoice-not-open")
+forbid (principal, action == Action::"invoice.pay", resource)
+unless { context.invoice_open };
+
+@id("forbid-payee-not-invoice-vendor")
+forbid (principal, action == Action::"invoice.pay", resource)
+unless { context.payee_is_invoice_vendor };
+
+@id("forbid-amount-differs-from-invoice")
+forbid (principal, action == Action::"invoice.pay", resource)
+unless { context.amount_matches_invoice };
+
+@id("forbid-verification-of-payee-mismatch")
+forbid (principal, action == Action::"invoice.pay", resource)
+unless { context.vop_match };
+
+@id("forbid-sanctioned-payee")
+forbid (principal, action == Action::"invoice.pay", resource)
+when { context.payee_sanctioned };
+
+@id("forbid-hard-cap")
+forbid (principal, action == Action::"invoice.pay", resource)
+when { context.params.amount_cents > 5000000 };
+
+// stable IBAN (changed 7+ days ago): up to 5,000.00 automatic, above that the accountant confirms
+@id("permit-pay-stable-iban")
+permit (principal, action == Action::"invoice.pay", resource)
+when { context.iban_age_days >= 7 && context.params.amount_cents <= 500000 };
+
+@id("permit-pay-stable-iban-large-with-step-up")
+permit (principal, action == Action::"invoice.pay", resource)
+when { context.iban_age_days >= 7 && context.params.amount_cents > 500000 && context.approval_level >= 1 };
+
+// cooling-off: IBAN changed less than 7 days ago => four eyes, whatever the amount
+@id("permit-pay-fresh-iban-four-eyes")
+permit (principal, action == Action::"invoice.pay", resource)
+when { context.iban_age_days < 7 && context.approval_level >= 2 };

intentplane/packs/accounts_payable.py

@@ -0,0 +1,152 @@
+"""Accounts-payable pack: the "we changed banks" fraud, on an AP agent that reads vendor emails.
+
+Ported from an independent v2.2 design. Systems of record, all per tenant (the company named in the
+signed mandate), read by the gateway, never written by the agent:
+
+  vendors    : vendor id -> {name, iban, iban_changed_at, phone}        (ERP vendor master)
+  invoices   : invoice ref -> {vendor_id, amount_cents, currency, status} (ERP, after PO/receipt/invoice match)
+  callbacks  : (vendor id, new IBAN) -> phone number the finance team called
+  vop        : Verification of Payee: (vendor name, IBAN) -> holder name matches
+
+Actions:
+  vendor.update_bank_details  needs a call-back on the phone number already on file, then four eyes.
+  invoice.pay                 the invoice must exist and be open, the payee must be the CURRENT IBAN of the
+                              invoice's vendor, the amount must equal the invoice; a freshly changed IBAN
+                              (< 7 days) needs four eyes; large invoices need step-up; VoP and sanctions apply.
+
+Execution happens inside the gateway (under its lock): an invoice is marked paid in the same critical
+section that authorised it, so it cannot be paid twice, even by concurrent requests.
+"""
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Iterable, Mapping
+from pathlib import Path
+
+from intentplane.cedar_pdp import CedarPDP
+from intentplane.core import ActionContract, FromMandate, FromRegistry, Pack, Param
+from intentplane.packs.bank import is_iban, norm_iban
+
+DAY = 86_400.0
+POLICY_FILE = Path(__file__).with_name("accounts_payable.cedar")
+
+UPDATE_BANK = ActionContract(
+    name="vendor.update_bank_details", resource="vendor", version="ap-1",
+    params=(
+        Param("vendor_id", str, critical=True, sources=(FromRegistry("vendors"),)),
+        Param("new_iban", str, validate=is_iban),   # untrusted by nature: it comes from the request itself
+        Param("reason", str),
+    ),
+)
+
+PAY = ActionContract(
+    name="invoice.pay", resource="vendor", version="ap-1", budget_param="amount_cents",
+    params=(
+        Param("source_account", str, critical=True, sources=(FromMandate("source_account"),), normalize=norm_iban,
+              validate=is_iban),
+        Param("invoice_ref", str, critical=True, sources=(FromRegistry("invoices"),)),
+        Param("payee_iban", str, critical=True, sources=(FromRegistry("vendor_ibans"),), normalize=norm_iban,
+              validate=is_iban),
+        Param("amount_cents", int, validate=lambda a: a > 0),
+        Param("currency", str, critical=True, sources=(FromMandate("currency"),)),
+    ),
+)
+
+
+class ERP:
+    """Fictional ERP: tenant -> vendors, invoices, call-back log, plus a VoP service and a sanctions list."""
+
+    def __init__(self, tenants: Mapping[str, Mapping[str, dict]], vop: Mapping[tuple[str, str], bool] | None = None,
+                 sanctioned: Iterable[str] = (), now: Callable[[], float] = time.time) -> None:
+        self.t = {name: {"vendors": dict(d.get("vendors", {})), "invoices": dict(d.get("invoices", {})),
+                         "callbacks": dict(d.get("callbacks", {}))} for name, d in tenants.items()}
+        self.vop = {(n, norm_iban(i)): ok for (n, i), ok in (vop or {}).items()}
+        self.sanctioned = {norm_iban(i) for i in sanctioned}
+        self.now = now
+        self.payments: list[dict] = []
+
+    def of(self, tenant: str) -> dict:
+        return self.t.get(tenant, {"vendors": {}, "invoices": {}, "callbacks": {}})
+
+    def log_callback(self, tenant: str, vendor_id: str, new_iban: str, phone: str) -> None:
+        """Finance records that it called the vendor about `new_iban` on `phone` (trusted side only). The IBAN is
+        normalised here, so a connector cannot store a spelling the gateway would not recognise."""
+        self.t[tenant]["callbacks"][(vendor_id, norm_iban(new_iban))] = phone
+
+
+class _Ids:
+    """Registry view: ref == value, valid if the record exists for that tenant."""
+
+    def __init__(self, erp: ERP, table: str) -> None:
+        self.erp, self.table = erp, table
+
+    def get(self, owner, ref):
+        return ref if ref in self.erp.of(owner)[self.table] else None
+
+    def find(self, owner, value):
+        return value if isinstance(value, str) and value in self.erp.of(owner)[self.table] else None
+
+
+class _CurrentIbans:
+    """Registry view: the CURRENT IBAN of each vendor of the tenant (ref = vendor id)."""
+
+    def __init__(self, erp: ERP) -> None:
+        self.erp = erp
+
+    def get(self, owner, ref):
+        v = self.erp.of(owner)["vendors"].get(ref)
+        return v["iban"] if v else None
+
+    def find(self, owner, value):
+        try:
+            n = norm_iban(value)
+        except ValueError:
+            return None
+        return next((vid for vid, v in self.erp.of(owner)["vendors"].items() if norm_iban(v["iban"]) == n), None)
+
+
+def build(erp: ERP) -> Pack:
+    def invoice(values, m) -> dict:
+        return erp.of(m.owner)["invoices"][values["invoice_ref"]]
+
+    def invoice_vendor(values, m) -> dict:
+        return erp.of(m.owner)["vendors"][invoice(values, m)["vendor_id"]]
+
+    def callback_verified(a, v, m) -> bool:
+        if a != UPDATE_BANK.name:
+            return False
+        t = erp.of(m.owner)
+        phone = t["callbacks"].get((v["vendor_id"], norm_iban(v["new_iban"])))
+        return phone is not None and phone == t["vendors"][v["vendor_id"]]["phone"]
+
+    def pay_fact(fn):
+        return lambda a, v, m: fn(v, m) if a == PAY.name else False
+
+    context = {
+        "callback_verified": callback_verified,
+        "invoice_open": pay_fact(lambda v, m: invoice(v, m)["status"] == "open"),
+        "payee_is_invoice_vendor": pay_fact(lambda v, m: norm_iban(invoice_vendor(v, m)["iban"])
+                                            == norm_iban(v["payee_iban"])),
+        "amount_matches_invoice": pay_fact(lambda v, m: invoice(v, m)["amount_cents"] == v["amount_cents"]
+                                           and invoice(v, m)["currency"] == v["currency"]),
+        "vop_match": pay_fact(lambda v, m: erp.vop.get((invoice_vendor(v, m)["name"], norm_iban(v["payee_iban"])),
+                                                       False)),
+        "payee_sanctioned": pay_fact(lambda v, m: norm_iban(v["payee_iban"]) in erp.sanctioned),
+        "iban_age_days": lambda a, v, m: (int((erp.now() - invoice_vendor(v, m)["iban_changed_at"]) // DAY)
+                                          if a == PAY.name else 0),
+    }
+
+    def update_bank(values, m) -> str:   # writes only in the mandate's own tenant
+        vendor = erp.of(m.owner)["vendors"][values["vendor_id"]]
+        vendor["iban"], vendor["iban_changed_at"] = norm_iban(values["new_iban"]), erp.now()
+        return f"vendor {values['vendor_id']}: IBAN updated"
+
+    def pay(values, m) -> str:
+        erp.of(m.owner)["invoices"][values["invoice_ref"]]["status"] = "paid"
+        erp.payments.append({**values, "tenant": m.owner})
+        return f"paid {values['amount_cents'] / 100:.2f} {values['currency']} for {values['invoice_ref']}"
+
+    return Pack("accounts_payable", [UPDATE_BANK, PAY], CedarPDP.from_file("ap-policy-1", POLICY_FILE),
+                registries={"vendors": _Ids(erp, "vendors"), "invoices": _Ids(erp, "invoices"),
+                            "vendor_ibans": _CurrentIbans(erp)},
+                context=context, executors={UPDATE_BANK.name: update_bank, PAY.name: pay})

intentplane/packs/bank.cedar

@@ -0,0 +1,18 @@
+// Bank pack. Default deny; forbid overrides permit at every approval level.
+// Amounts are integer cents. approval_level: 0 none, 1 step-up (the principal), 2 four-eyes.
+
+@id("forbid-sanctioned-payee")
+forbid (principal, action == Action::"payment.transfer", resource)
+when { context.payee_sanctioned };
+
+@id("forbid-hard-cap")
+forbid (principal, action == Action::"payment.transfer", resource)
+when { context.params.amount_cents > 1000000 };
+
+@id("permit-transfer")
+permit (principal, action == Action::"payment.transfer", resource)
+when { context.params.amount_cents <= 100000 };
+
+@id("permit-large-transfer-with-step-up")
+permit (principal, action == Action::"payment.transfer", resource)
+when { context.params.amount_cents > 100000 && context.approval_level >= 1 };

intentplane/packs/bank.py

@@ -0,0 +1,73 @@
+"""Bank pack (the AgenticZeroTrust behaviour on the generic core).
+
+payee: the one the user named in the mandate, or one of HIS registered beneficiaries.
+source account and currency: bound in the mandate. Amount: chosen by the agent, but charged
+against the mandate's cumulative budget and checked by Cedar (step-up above 1,000.00, hard cap
+10,000.00, see bank.cedar). Sanctions come from the gateway's own list, never from the agent.
+Amounts are integer cents (Cedar has no float).
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+
+from intentplane.cedar_pdp import CedarPDP
+from intentplane.core import ActionContract, DictRegistry, FromMandate, FromRegistry, Pack, Param
+
+
+def norm_iban(v: object) -> str:
+    if not isinstance(v, str) or not v.isascii():   # look-alike characters are not folded: they stay different
+        raise ValueError("not an ASCII IBAN")
+    return re.sub(r"\s+", "", v).upper()
+
+
+_IBAN = re.compile(r"^[A-Z]{2}\d{2}[A-Z0-9]{10,30}$")
+
+
+def is_iban(v: object) -> bool:
+    """Structural IBAN check (country, check digits, BBAN). Applied to the RESOLVED value, so even a record
+    a human added by mistake ("Apple") is refused."""
+    try:
+        return bool(_IBAN.match(norm_iban(v)))
+    except ValueError:
+        return False
+
+
+TRANSFER = ActionContract(
+    name="payment.transfer", resource="account", version="bank-3", budget_param="amount_cents",
+    params=(
+        Param("source_account", str, critical=True, sources=(FromMandate("source_account"),), normalize=norm_iban,
+              validate=is_iban),
+        Param("payee_iban", str, critical=True, sources=(FromMandate("payee"), FromRegistry("beneficiaries")),
+              normalize=norm_iban, validate=is_iban),
+        Param("amount_cents", int, validate=lambda a: a > 0),
+        Param("currency", str, critical=True, sources=(FromMandate("currency"),)),
+        Param("reference", str),
+    ),
+)
+
+POLICY_FILE = Path(__file__).with_name("bank.cedar")
+
+
+def build(beneficiaries: Mapping[str, Mapping[str, str]], sanctioned: Iterable[str] = (),
+          sanctioned_countries: Iterable[str] = ("KP", "IR")) -> tuple[Pack, list]:
+    """beneficiaries: principal -> {ref: IBAN}. Returns the pack and the (mock) core-banking ledger."""
+    blocked = {norm_iban(i) for i in sanctioned}
+    countries = set(sanctioned_countries)
+    ledger: list[dict] = []
+
+    def is_sanctioned(action, values, mandate) -> bool:
+        iban = norm_iban(values["payee_iban"])
+        return iban in blocked or iban[:2] in countries
+
+    def execute(values, mandate) -> str:
+        ledger.append(dict(values))
+        return f"transfer-{len(ledger)}"
+
+    pack = Pack("bank", [TRANSFER], CedarPDP.from_file("bank-policy-3", POLICY_FILE),
+                registries={"beneficiaries": DictRegistry(beneficiaries, normalize=norm_iban)},
+                context={"payee_sanctioned": is_sanctioned},
+                executors={"payment.transfer": execute})
+    return pack, ledger
+

intentplane/packs/code.cedar

@@ -0,0 +1,18 @@
+// Code pack. Default deny; forbid overrides permit at every approval level.
+// approval_level: 0 none, 1 step-up (the developer), 2 four-eyes (a reviewer).
+
+@id("forbid-red-ci")
+forbid (principal, action == Action::"repo.merge", resource)
+when { context.ci_status != "success" };
+
+@id("permit-merge-unprotected-branch")
+permit (principal, action == Action::"repo.merge", resource)
+unless { ["main", "release"].contains(context.params.target_branch) };
+
+@id("permit-merge-protected-branch-reviewed")
+permit (principal, action == Action::"repo.merge", resource)
+when { ["main", "release"].contains(context.params.target_branch) && context.approved_review };
+
+@id("permit-merge-protected-branch-four-eyes")
+permit (principal, action == Action::"repo.merge", resource)
+when { ["main", "release"].contains(context.params.target_branch) && context.approval_level >= 2 };

intentplane/packs/code.py

@@ -0,0 +1,49 @@
+"""Code pack: the repository is bound in the developer's mandate, the commit must be one CI attested
+for that developer's repos (read by the gateway), CI status and review state are read by the gateway
+from the CI and code-review systems, protected branches without an approved review need a second
+human. No free shell exists in the catalog at all."""
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+
+from intentplane.cedar_pdp import CedarPDP
+from intentplane.core import (
+    ActionContract,
+    DictRegistry,
+    FromMandate,
+    FromRegistry,
+    Pack,
+    Param,
+)
+
+MERGE = ActionContract(
+    name="repo.merge", resource="repo", version="code-3",
+    params=(
+        Param("repo", str, critical=True, sources=(FromMandate("repo"),)),
+        Param("head_sha", str, critical=True, sources=(FromRegistry("ci_attested"),), validate=lambda s: len(s) == 40),
+        Param("target_branch", str, validate=lambda b: bool(b)),
+        Param("message", str),
+    ),
+)
+
+
+PDP = CedarPDP.from_file("code-policy-3", Path(__file__).with_name("code.cedar"))
+
+
+def build(ci_attested: Mapping[str, Mapping[str, str]], ci_status: Mapping[str, str],
+          approved_reviews: Iterable[str] = ()) -> tuple[Pack, list]:
+    """ci_attested: developer -> {CI run id: sha}; ci_status: sha -> status. Returns the pack and the merge log."""
+    approved = set(approved_reviews)
+    merges: list[dict] = []
+
+    def execute(values, mandate) -> str:
+        merges.append(dict(values))
+        return f"merged {values['head_sha'][:7]} into {values['target_branch']}"
+
+    pack = Pack("code", [MERGE], PDP,
+                registries={"ci_attested": DictRegistry(ci_attested)},
+                context={"ci_status": lambda a, v, m: ci_status.get(v["head_sha"], "unknown"),
+                         "approved_review": lambda a, v, m: v["head_sha"] in approved},
+                executors={"repo.merge": execute})
+    return pack, merges

intentplane/packs/health.cedar

@@ -0,0 +1,22 @@
+// Health pack. Default deny; forbid overrides permit at every approval level.
+// approval_level: 0 none, 1 step-up (the clinician justifies), 2 four-eyes (second reviewer).
+
+@id("forbid-research-without-consent")
+forbid (principal, action == Action::"ehr.read_record", resource)
+when { context.params.purpose == "research" && !context.consent_research };
+
+@id("permit-treatment-read")
+permit (principal, action == Action::"ehr.read_record", resource)
+when { context.params.purpose == "treatment" && context.params.section != "full" };
+
+@id("permit-full-record-with-step-up")
+permit (principal, action == Action::"ehr.read_record", resource)
+when { context.params.purpose == "treatment" && context.params.section == "full" && context.approval_level >= 1 };
+
+@id("permit-research-read")
+permit (principal, action == Action::"ehr.read_record", resource)
+when { context.params.purpose == "research" && context.params.section != "full" };
+
+@id("permit-break-the-glass-four-eyes")
+permit (principal, action == Action::"ehr.read_record", resource)
+when { context.params.purpose == "emergency" && context.approval_level >= 2 };

intentplane/packs/health.py

@@ -0,0 +1,49 @@
+"""Health pack: the patient must be one of the clinician's OPEN encounters (read by the gateway from
+the EHR), the purpose is bound in the clinician's mandate, research needs consent on file (read by the
+gateway from the consent registry), full records under treatment need step-up, emergency access is
+four-eyes ("break the glass")."""
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+
+from intentplane.cedar_pdp import CedarPDP
+from intentplane.core import (
+    ActionContract,
+    DictRegistry,
+    FromMandate,
+    FromRegistry,
+    Pack,
+    Param,
+)
+
+SECTIONS = {"summary", "labs", "meds", "notes", "full"}
+PURPOSES = {"treatment", "emergency", "research"}
+
+READ_RECORD = ActionContract(
+    name="ehr.read_record", resource="patient_record", version="health-3",
+    params=(
+        Param("patient_id", str, critical=True, sources=(FromRegistry("open_encounters"),)),
+        Param("section", str, validate=lambda s: s in SECTIONS),
+        Param("purpose", str, critical=True, sources=(FromMandate("purpose"),), validate=lambda p: p in PURPOSES),
+    ),
+)
+
+
+PDP = CedarPDP.from_file("health-policy-3", Path(__file__).with_name("health.cedar"))
+
+
+def build(open_encounters: Mapping[str, Mapping[str, str]], research_consent: Iterable[str] = ()) -> tuple[Pack, list]:
+    """open_encounters: clinician -> {encounter id: patient id}. Returns the pack and the access log."""
+    consent = set(research_consent)
+    reads: list[dict] = []
+
+    def execute(values, mandate) -> dict:
+        reads.append(dict(values))
+        return {"patient_id": values["patient_id"], "section": values["section"], "data": "<record>"}
+
+    pack = Pack("health", [READ_RECORD], PDP,
+                registries={"open_encounters": DictRegistry(open_encounters)},
+                context={"consent_research": lambda a, v, m: v["patient_id"] in consent},
+                executors={"ehr.read_record": execute})
+    return pack, reads

intentplane/proxy/__init__.py

@@ -0,0 +1,13 @@
+"""intentplane as an MCP proxy: put the gateway between any MCP client and the MCP servers it uses.
+
+    intentplane-mcp --config intentplane.toml
+
+The client (Claude Desktop, Claude Code, Cursor, ...) sees the downstream servers' tools. Every call to a
+configured tool becomes a proposal: its critical arguments are resolved against the mandate and the
+registries of the config, the Cedar policy decides, a step-up is confirmed by the user through MCP
+elicitation, and only then does the proxy call the downstream tool, with the resolved values.
+"""
+from .config import ProxyConfig, load_config
+from .gate import GateResult, ToolGate
+
+__all__ = ["GateResult", "ProxyConfig", "ToolGate", "load_config"]

intentplane/proxy/config.py

@@ -0,0 +1,147 @@
+"""Proxy configuration (TOML). Relative paths are resolved against the config file's directory.
+
+    [mandate]                      # the session mandate, issued by the trusted side when the proxy starts
+    principal = "emma"
+    budget = 250000                # in the units of each tool's `budget_param` (e.g. cents)
+    [mandate.claims]
+    payee = ["DE89370400440532013000"]
+
+    [registries.beneficiaries]     # a system of record: {ref: value}, read for the mandate's owner
+    file = "beneficiaries.json"
+    normalize = "iban"
+
+    [[servers]]                    # downstream MCP servers (stdio)
+    name = "bank"
+    command = "python"
+    args = ["bank_server.py"]
+
+    [[tools]]                      # a tool the gateway decides on
+    server = "bank"
+    tool = "send_money"
+    budget_param = "amount"
+    [tools.params.recipient]
+    critical = true
+    sources = ["mandate:payee", "registry:beneficiaries"]
+    normalize = "iban"
+    [tools.params.amount]
+    type = "number"
+    scale = 100                    # Cedar has no floats: the policy sees round(amount * 100)
+
+    [policy]
+    file = "policy.cedar"
+
+    [defaults]
+    passthrough = ["bank.get_balance"]   # read-only tools that need no decision; anything else unlisted is DENIED
+    receipts = "receipts.jsonl"
+"""
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+TYPES = {"string": str, "integer": int, "number": int, "boolean": bool}   # numbers are scaled to integers
+
+
+@dataclass(frozen=True)
+class ParamSpec:
+    name: str
+    type: str = "string"
+    critical: bool = False
+    sources: tuple[str, ...] = ()
+    normalize: str | None = None
+    scale: int = 1
+    each: bool = False   # a list of values, every item resolved (e.g. email recipients)
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    server: str
+    tool: str
+    action: str
+    params: tuple[ParamSpec, ...]
+    budget_param: str | None = None
+
+    @property
+    def key(self) -> str:
+        return f"{self.server}.{self.tool}"
+
+
+@dataclass(frozen=True)
+class ServerSpec:
+    name: str
+    command: str
+    args: tuple[str, ...] = ()
+    env: dict[str, str] | None = None
+
+
+@dataclass
+class ProxyConfig:
+    principal: str
+    claims: dict[str, Any]
+    budget: float | None
+    registries: dict[str, tuple[dict[str, Any], str | None]]   # name -> (records, normalizer)
+    servers: list[ServerSpec]
+    tools: dict[str, ToolSpec]
+    policy: str
+    passthrough: frozenset[str] = frozenset()
+    receipts: Path | None = None
+    base: Path = field(default_factory=Path.cwd)
+
+
+def _param(name: str, raw: dict) -> ParamSpec:
+    spec = ParamSpec(name, raw.get("type", "string"), bool(raw.get("critical", False)),
+                     tuple(raw.get("sources", ())), raw.get("normalize"), int(raw.get("scale", 1)),
+                     bool(raw.get("each", False)))
+    if spec.type not in TYPES:
+        raise ValueError(f"param {name!r}: unknown type {spec.type!r}")
+    if spec.critical and not spec.sources:
+        raise ValueError(f"param {name!r}: a critical parameter needs at least one trusted source")
+    for src in spec.sources:
+        kind, _, _ = src.partition(":")
+        if kind not in ("mandate", "registry"):
+            raise ValueError(f"param {name!r}: source {src!r} must be 'mandate:<claim>' or 'registry:<name>'")
+    return spec
+
+
+def load_config(path: str | Path) -> ProxyConfig:
+    path = Path(path).resolve()
+    base = path.parent
+    raw = tomllib.loads(path.read_text(encoding="utf-8"))
+    mandate = raw.get("mandate", {})
+    registries = {}
+    for name, reg in raw.get("registries", {}).items():
+        records = json.loads((base / reg["file"]).read_text(encoding="utf-8"))
+        if not isinstance(records, dict):
+            raise TypeError(f"registry {name!r}: the file must hold a JSON object {{ref: value}}")
+        registries[name] = (records, reg.get("normalize"))
+    # command "python" means the interpreter running the proxy, so the downstream server finds the same packages
+    servers = [ServerSpec(s["name"], sys.executable if s["command"] == "python" else s["command"],
+                          tuple(s.get("args", ())), s.get("env")) for s in raw.get("servers", ())]
+    names = {s.name for s in servers}
+    tools = {}
+    for t in raw.get("tools", ()):
+        if t["server"] not in names:
+            raise ValueError(f"tool {t['tool']!r}: unknown server {t['server']!r}")
+        spec = ToolSpec(t["server"], t["tool"], t.get("action", f"{t['server']}.{t['tool']}"),
+                        tuple(_param(n, p) for n, p in t.get("params", {}).items()), t.get("budget_param"))
+        if spec.budget_param and spec.budget_param not in {p.name for p in spec.params}:
+            raise ValueError(f"tool {spec.key}: budget_param {spec.budget_param!r} must be a declared param")
+        tools[spec.key] = spec
+    policy_file = raw.get("policy", {}).get("file")
+    if not policy_file:
+        raise ValueError("a [policy] file is required (Cedar, default deny)")
+    defaults = raw.get("defaults", {})
+    receipts = defaults.get("receipts")
+    return ProxyConfig(principal=mandate.get("principal", "user"), claims=dict(mandate.get("claims", {})),
+                       budget=mandate.get("budget"), registries=registries, servers=servers, tools=tools,
+                       policy=(base / policy_file).read_text(encoding="utf-8"),
+                       passthrough=frozenset(defaults.get("passthrough", ())),
+                       receipts=(base / receipts) if receipts else None, base=base)