Skip to content

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.py
new file mode 100644
index 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.py
index 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 annotations
import base64
-import importlib.util
import json
+import os
+import subprocess
+import sys
import time
from collections.abc import Iterator
from pathlib import Path
@@ -18,20 +20,13 @@ from fastapi import FastAPI, Request
from fastapi.testclient import TestClient
from openexecutive.api import caller as api_caller
+from openexecutive.api import caller_signing
from openexecutive.api.caller import AssertionRefused, Caller, JtiLedger
from openexecutive.api.routes import executive as executive_route
from openexecutive.memory import episodic
from openexecutive.people import registry as people_registry
from 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_S
def 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.Mo
assert chat.await_args.kwargs["person_id"] is None
await 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.py
index 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 annotations
import argparse
-import base64
-import re
-import secrets
+import pathlib
import 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: E402
def 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.py
index 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 annotations
import argparse
-import base64
-import json
import os
-import re
-import secrets
+import pathlib
import 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: E402
def main() -> int:
@@ -108,7 +44,7 @@ def main() -> int:
return 2
try:
print(
- mint(
+ mint_assertion(
setting,
kind="user" if args.email else "operator",
email=args.email,