AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
refactor(auth): make the signed-caller key maker and signer importable (#314)
Rufus0acb9f7be8a1
diff --git a/packages/core/openexecutive/api/caller_signing.py b/packages/core/openexecutive/api/caller_signing.pynew file mode 100644index 00000000..689107ee--- /dev/null+++ b/packages/core/openexecutive/api/caller_signing.py@@ -0,0 +1,110 @@+"""Making signed-caller keys and assertions: the signing half of+``api/caller.py`` (docs/auth.md, "Signed callers").++The API itself never signs: it holds only public keys. This is for the code+that does, besides the web app: ``scripts/make-caller-keys.py``,+``scripts/mint-caller-assertion.py``, and any program that provisions an API+or calls one as the operator. It needs only ``cryptography`` and the standard+library, so the scripts can import it without the rest of the package.++The wire format is the one ``packages/ui/src/lib/callerAssertion.ts`` signs;+``tests/unit/test_caller_assertion.py`` checks both against the same vectors.+"""+from __future__ import annotations++import base64+import json+import re+import secrets+import time+from typing import Literal++from cryptography.hazmat.primitives import serialization+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey++# Kept in step with api/caller.py and packages/ui/src/lib/callerAssertion.ts+# (the tests compare all three).+VERSION = "v1"+AUDIENCE = "openexecutive-api"+# Short, so a captured assertion is soon worthless, and well under the API's+# MAX_LIFETIME_S, so a slow clock on either side still leaves room.+LIFETIME_S = 30++KID_RE = re.compile(r"[A-Za-z0-9_-]{1,32}")+_SEED_RE = re.compile(r"[A-Za-z0-9_-]{43}=?")++SignerKind = Literal["user", "operator"]+++def _b64url(data: bytes) -> str:+ return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")+++def make_key_pair(kid: str | None = None) -> tuple[str, str]:+ """A fresh pair as ``(CALLER_ASSERTION_PRIVATE_KEY value,+ CALLER_ASSERTION_PUBLIC_KEYS entry)``, both ``kid:key``. ``kid`` names the+ key (letters, digits, ``_`` or ``-``, up to 32); random when omitted."""+ kid = kid if kid is not None else secrets.token_hex(4)+ if not KID_RE.fullmatch(kid):+ raise ValueError("a key id is 1-32 letters, digits, _ or -")+ key = Ed25519PrivateKey.generate()+ seed = key.private_bytes(+ serialization.Encoding.Raw,+ serialization.PrivateFormat.Raw,+ serialization.NoEncryption(),+ )+ public = key.public_key().public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)+ return f"{kid}:{_b64url(seed)}", f"{kid}:{_b64url(public)}"+++def load_private_key(setting: str) -> tuple[str, Ed25519PrivateKey]:+ """``kid:seed`` (CALLER_ASSERTION_PRIVATE_KEY) → the key id and key. The+ error never includes the key."""+ kid, sep, seed = (part.strip() for part in setting.strip().partition(":"))+ if not sep or not KID_RE.fullmatch(kid) or not _SEED_RE.fullmatch(seed):+ raise ValueError(+ "CALLER_ASSERTION_PRIVATE_KEY is <key id>:<private key>, as "+ "scripts/make-caller-keys.py prints it"+ )+ raw = base64.urlsafe_b64decode(seed.rstrip("=") + "=")+ return kid, Ed25519PrivateKey.from_private_bytes(raw)+++def mint_assertion(+ setting: str,+ *,+ kind: SignerKind,+ email: str,+ method: str,+ target: str,+ now_ms: int | None = None,+ jti: str | None = None,+) -> str:+ """One ``x-caller-assertion`` value, good for one request: ``method``,+ ``target`` (the path with its query, exactly as the request sends it), for+ ``LIFETIME_S``, once. ``kind`` is ``user`` (named by ``email``) or+ ``operator`` (the owner at the controls, naming no one)."""+ if kind not in ("user", "operator"):+ raise ValueError("kind is user or operator")+ sub = email.strip().lower() if kind == "user" else ""+ if kind == "user" and "@" not in sub:+ raise ValueError("a user is named by their email")+ if kind == "operator" and email.strip():+ raise ValueError("the operator names no one")+ kid, key = load_private_key(setting)+ iat = (int(time.time() * 1000) if now_ms is None else now_ms) // 1000+ claims = {+ "aud": AUDIENCE,+ "exp": iat + LIFETIME_S,+ "iat": iat,+ "jti": jti or secrets.token_urlsafe(18),+ "kid": kid,+ "kind": kind,+ "m": method.upper(),+ "p": target,+ "sub": sub,+ }+ # Sorted keys and no spaces: byte for byte what the web app signs.+ body = json.dumps(claims, sort_keys=True, separators=(",", ":"), ensure_ascii=False)+ signing_input = f"{VERSION}.{_b64url(body.encode('utf-8'))}"+ return f"{signing_input}.{_b64url(key.sign(signing_input.encode('ascii')))}"diff --git a/packages/core/tests/unit/test_caller_assertion.py b/packages/core/tests/unit/test_caller_assertion.pyindex 1ef5e84c..a47acf5b 100644--- a/packages/core/tests/unit/test_caller_assertion.py+++ b/packages/core/tests/unit/test_caller_assertion.py@@ -4,8 +4,10 @@ alone."""from __future__ import annotationsimport base64-import importlib.utilimport json+import os+import subprocess+import sysimport timefrom collections.abc import Iteratorfrom pathlib import Path@@ -18,20 +20,13 @@ from fastapi import FastAPI, Requestfrom fastapi.testclient import TestClientfrom openexecutive.api import caller as api_caller+from openexecutive.api import caller_signingfrom openexecutive.api.caller import AssertionRefused, Caller, JtiLedgerfrom openexecutive.api.routes import executive as executive_routefrom openexecutive.memory import episodicfrom openexecutive.people import registry as people_registryfrom openexecutive.people import store as people_store-_REPO = Path(__file__).resolve().parents[4]-_spec = importlib.util.spec_from_file_location(- "mint_caller_assertion", _REPO / "scripts" / "mint-caller-assertion.py"-)-assert _spec is not None and _spec.loader is not None-mint_script = importlib.util.module_from_spec(_spec)-_spec.loader.exec_module(mint_script)-VECTORS = json.loads((Path(__file__).parent / "caller_assertion_vectors.json").read_text())SIGNING_KEY = VECTORS["test_signing_key"]KEYS = api_caller.parse_public_keys(VECTORS["public_keys"])@@ -39,7 +34,7 @@ OWNER = "[email protected]"def _mint(kind: str = "user", email: str = OWNER, method: str = "GET", target: str = "/x", **kw: Any) -> str:- return str(mint_script.mint(SIGNING_KEY, kind=kind, email=email, method=method, target=target, **kw))+ return str(caller_signing.mint_assertion(SIGNING_KEY, kind=kind, email=email, method=method, target=target, **kw))def _b64(data: bytes) -> str:@@ -48,14 +43,14 @@ def _b64(data: bytes) -> str:def _signed(claims: dict[str, Any], version: str = "v1") -> str:"""A token over arbitrary claims, signed with the vectors' key."""- _kid, key = mint_script.load_private_key(SIGNING_KEY)+ _kid, key = caller_signing.load_private_key(SIGNING_KEY)signing_input = f"{version}.{_b64(json.dumps(claims).encode())}"return f"{signing_input}.{_b64(key.sign(signing_input.encode()))}"def _signed_raw(payload: bytes) -> str:"""A token over raw payload bytes, signed with the vectors' key."""- _kid, key = mint_script.load_private_key(SIGNING_KEY)+ _kid, key = caller_signing.load_private_key(SIGNING_KEY)signing_input = f"v1.{_b64(payload)}"return f"{signing_input}.{_b64(key.sign(signing_input.encode()))}"@@ -95,9 +90,9 @@ def test_the_shared_vectors_sign_and_verify(case: dict[str, Any]) -> None:def test_the_constants_match_the_script() -> None:- assert mint_script.AUDIENCE == api_caller.AUDIENCE- assert mint_script.VERSION == api_caller.ASSERTION_VERSION- assert mint_script.LIFETIME_S <= api_caller.MAX_LIFETIME_S+ assert caller_signing.AUDIENCE == api_caller.AUDIENCE+ assert caller_signing.VERSION == api_caller.ASSERTION_VERSION+ assert caller_signing.LIFETIME_S <= api_caller.MAX_LIFETIME_Sdef test_it_holds_for_one_request_once() -> None:@@ -216,7 +211,7 @@ def test_several_keys_while_rotating() -> None:keys = api_caller.parse_public_keys(f"{VECTORS['public_keys']}, {fresh_public}")assert set(keys) == {"rfc8032-test1", "k2"}for setting in (SIGNING_KEY, fresh_private):- token = mint_script.mint(setting, kind="operator", email="", method="GET", target="/x")+ token = caller_signing.mint_assertion(setting, kind="operator", email="", method="GET", target="/x")who = api_caller.verify_assertion(token, keys=keys, method="GET", target="/x", now=int(time.time()), ledger=JtiLedger())@@ -224,12 +219,7 @@ def test_several_keys_while_rotating() -> None:def _new_pair(kid: str) -> tuple[str, str]:- spec = importlib.util.spec_from_file_location("make_caller_keys", _REPO / "scripts" / "make-caller-keys.py")- assert spec is not None and spec.loader is not None- module = importlib.util.module_from_spec(spec)- spec.loader.exec_module(module)- private, public = module.make_pair(kid)- return str(private), str(public)+ return caller_signing.make_key_pair(kid)@pytest.mark.parametrize(@@ -425,3 +415,33 @@ async def test_mcp_asks_as_no_one_once_callers_are_signed(monkeypatch: pytest.Moassert chat.await_args.kwargs["person_id"] is Noneawait mcp_server.ask_executive("hi")assert chat.await_args.kwargs["person_id"] is None+++def test_make_key_pair_names_a_random_key_and_refuses_a_bad_id() -> None:+ private, public = caller_signing.make_key_pair()+ kid = private.partition(":")[0]+ assert public.startswith(f"{kid}:")+ assert set(api_caller.parse_public_keys(public)) == {kid}+ with pytest.raises(ValueError, match="key id"):+ caller_signing.make_key_pair("bad kid!")+++def test_the_scripts_make_a_pair_the_api_accepts_and_sign_with_it() -> None:+ """The two scripts run on their own (no package installed) and agree with+ the API."""+ scripts = Path(__file__).resolve().parents[4] / "scripts"+ made = subprocess.run(+ [sys.executable, str(scripts / "make-caller-keys.py"), "--kid", "k9"],+ capture_output=True, text=True, check=True, cwd="/",+ ).stdout+ settings = dict(line.split("=", 1) for line in made.splitlines() if not line.startswith("#"))+ keys = api_caller.parse_public_keys(settings["CALLER_ASSERTION_PUBLIC_KEYS"])+ env = {**os.environ, "CALLER_ASSERTION_PRIVATE_KEY": settings["CALLER_ASSERTION_PRIVATE_KEY"]}+ token = subprocess.run(+ [sys.executable, str(scripts / "mint-caller-assertion.py"), "GET", "/today"],+ capture_output=True, text=True, check=True, cwd="/", env=env,+ ).stdout.strip()+ who = api_caller.verify_assertion(+ token, keys=keys, method="GET", target="/today", now=int(time.time()), ledger=JtiLedger()+ )+ assert who == Caller("operator")diff --git a/scripts/make-caller-keys.py b/scripts/make-caller-keys.pyindex f3b14306..2136cb6a 100644--- a/scripts/make-caller-keys.py+++ b/scripts/make-caller-keys.py@@ -20,34 +20,12 @@ to the new private key, then drop the old public key.from __future__ import annotationsimport argparse-import base64-import re-import secrets+import pathlibimport sys-from cryptography.hazmat.primitives import serialization-from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1] / "packages" / "core"))-# The same rule as the API's (openexecutive/api/caller.py _KID_RE).-KID_RE = re.compile(r"[A-Za-z0-9_-]{1,32}")---def _b64url(data: bytes) -> str:- return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")---def make_pair(kid: str) -> tuple[str, str]:- """``(private setting, public setting)`` values for a fresh key."""- key = Ed25519PrivateKey.generate()- seed = key.private_bytes(- serialization.Encoding.Raw,- serialization.PrivateFormat.Raw,- serialization.NoEncryption(),- )- public = key.public_key().public_bytes(- serialization.Encoding.Raw, serialization.PublicFormat.Raw- )- return f"{kid}:{_b64url(seed)}", f"{kid}:{_b64url(public)}"+from openexecutive.api.caller_signing import KID_RE, make_key_pair # noqa: E402def main() -> int:@@ -57,11 +35,10 @@ def main() -> int:help="a name for this key: letters, digits, _ or -, up to 32 (default: random)",)args = parser.parse_args()- kid = args.kid or secrets.token_hex(4)- if not KID_RE.fullmatch(kid):+ if args.kid is not None and not KID_RE.fullmatch(args.kid):print("--kid must be 1-32 letters, digits, _ or -", file=sys.stderr)return 2- private, public = make_pair(kid)+ private, public = make_key_pair(args.kid)print("# The web app (packages/ui) only. Secret:")print(f"CALLER_ASSERTION_PRIVATE_KEY={private}")print("# The API only:")diff --git a/scripts/mint-caller-assertion.py b/scripts/mint-caller-assertion.pyindex c2047a14..296a9773 100644--- a/scripts/mint-caller-assertion.py+++ b/scripts/mint-caller-assertion.py@@ -20,77 +20,13 @@ seconds, once. Never print or store the private key.from __future__ import annotationsimport argparse-import base64-import jsonimport os-import re-import secrets+import pathlibimport sys-import time-from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1] / "packages" / "core"))-# Kept in step with openexecutive/api/caller.py and-# packages/ui/src/lib/callerAssertion.ts (the tests compare all three).-VERSION = "v1"-AUDIENCE = "openexecutive-api"-LIFETIME_S = 30-_KID_RE = re.compile(r"[A-Za-z0-9_-]{1,32}")-_SEED_RE = re.compile(r"[A-Za-z0-9_-]{43}=?")---def _b64url(data: bytes) -> str:- return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")---def load_private_key(setting: str) -> tuple[str, Ed25519PrivateKey]:- """``kid:seed`` (CALLER_ASSERTION_PRIVATE_KEY) → the key id and key."""- kid, sep, seed = (part.strip() for part in setting.strip().partition(":"))- if not sep or not _KID_RE.fullmatch(kid) or not _SEED_RE.fullmatch(seed):- raise ValueError(- "CALLER_ASSERTION_PRIVATE_KEY is <key id>:<private key>, as "- "scripts/make-caller-keys.py prints it"- )- raw = base64.urlsafe_b64decode(seed.rstrip("=") + "=")- return kid, Ed25519PrivateKey.from_private_bytes(raw)---def mint(- setting: str,- *,- kind: str,- email: str,- method: str,- target: str,- now_ms: int | None = None,- jti: str | None = None,-) -> str:- """One ``x-caller-assertion`` value. ``target`` is the path with its query,- exactly as the request will send it."""- if kind not in ("user", "operator"):- raise ValueError("kind is user or operator")- sub = email.strip().lower() if kind == "user" else ""- if kind == "user" and "@" not in sub:- raise ValueError("a user is named by their email")- if kind == "operator" and email.strip():- raise ValueError("the operator names no one")- kid, key = load_private_key(setting)- iat = (int(time.time() * 1000) if now_ms is None else now_ms) // 1000- claims = {- "aud": AUDIENCE,- "exp": iat + LIFETIME_S,- "iat": iat,- "jti": jti or secrets.token_urlsafe(18),- "kid": kid,- "kind": kind,- "m": method.upper(),- "p": target,- "sub": sub,- }- # Sorted keys and no spaces: byte for byte what the web app signs.- body = json.dumps(claims, sort_keys=True, separators=(",", ":"), ensure_ascii=False)- signing_input = f"{VERSION}.{_b64url(body.encode('utf-8'))}"- return f"{signing_input}.{_b64url(key.sign(signing_input.encode('ascii')))}"+from openexecutive.api.caller_signing import mint_assertion # noqa: E402def main() -> int:@@ -108,7 +44,7 @@ def main() -> int:return 2try:print(- mint(+ mint_assertion(setting,kind="user" if args.email else "operator",email=args.email,