AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
"""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"]
# Where the request came from, when it isn't the web app's own pages: "host",
# a host origin's page (OE_HOST_ORIGINS, docs/auth.md). Signed so the API can
# hold such a request to what a host may do.
SURFACES = ("host",)
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,
surface: str = "",
) -> 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). ``surface`` is
``host`` for a call a host origin's page made, else empty (and left out of
the claims, so an assertion without one is byte for byte as before)."""
if kind not in ("user", "operator"):
raise ValueError("kind is user or operator")
if surface and surface not in SURFACES:
raise ValueError("surface is host or empty")
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,
}
if surface:
claims["surface"] = surface
# 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')))}"