tokenbiryani 0.2.0__py3-none-any.whl

tokenbiryani/core/handoff.py

@@ -0,0 +1,87 @@
+"""Single-use tickets that hand an admin key from the terminal to the browser.
+
+The key itself must never travel in a URL — it lands in shell history, in the
+browser's own history, in a referrer, and in any proxy log on the way. That rule is
+what the console's sign-in copy promises, and it is not negotiable.
+
+A ticket can travel there, because it is worth nothing after one redemption:
+
+    tokenbiryani console   reads the admin key from the config file
+                           mints a ticket, authenticated with that key
+                           opens  /console?t=<ticket>
+    the page               redeems it once for the key, then rewrites the URL
+
+The properties that make that safe are all here rather than spread across the
+gateway: one redemption, a short life, and loopback only. The last one matters most
+— a ticket is a bearer credential with no second factor, so it is minted only for a
+gateway that nothing off-box can reach in the first place.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from typing import Dict, Optional, Tuple
+
+#: Long enough that guessing is hopeless inside the lifetime below.
+TICKET_BYTES = 24
+
+#: A ticket exists to survive the trip from an exec() to a page load. Sixty seconds
+#: is generous for that and short enough that a shell history full of stale tickets
+#: is a history full of nothing.
+TTL_SECONDS = 60.0
+
+#: Hosts a ticket may be minted for. A gateway reachable off-box needs a real login,
+#: not a bearer token in a query string.
+LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1", "0:0:0:0:0:0:0:1"})
+
+
+class HandoffError(RuntimeError):
+    """Raised when a ticket cannot be minted, or cannot be redeemed."""
+
+
+def is_loopback(host: str) -> bool:
+    return (host or "").strip().strip("[]").lower() in LOOPBACK_HOSTS
+
+
+class TicketBook:
+    """In-memory, process-local, and deliberately not persisted.
+
+    A ticket that survived a restart would be a credential in a file, which is the
+    thing this exists to avoid. Losing them on restart costs one re-run of the
+    command that mints them.
+    """
+
+    def __init__(self, ttl_seconds: float = TTL_SECONDS) -> None:
+        self.ttl_seconds = ttl_seconds
+        #: ticket -> (key, expires_at)
+        self._tickets: Dict[str, Tuple[str, float]] = {}
+
+    def _sweep(self, now: float) -> None:
+        expired = [t for t, (_, expires) in self._tickets.items() if expires <= now]
+        for ticket in expired:
+            self._tickets.pop(ticket, None)
+
+    def mint(self, key: str, now: Optional[float] = None) -> Tuple[str, float]:
+        """Return (ticket, ttl_seconds) for a key that has already been authenticated."""
+        if not key:
+            # An open gateway has no key to hand over; the console needs none either.
+            raise HandoffError("this gateway has no keys configured, so it needs no sign-in")
+        now = time.time() if now is None else now
+        self._sweep(now)
+        ticket = secrets.token_urlsafe(TICKET_BYTES)
+        self._tickets[ticket] = (key, now + self.ttl_seconds)
+        return ticket, self.ttl_seconds
+
+    def redeem(self, ticket: str, now: Optional[float] = None) -> str:
+        """Exchange a ticket for its key, exactly once."""
+        now = time.time() if now is None else now
+        self._sweep(now)
+        # pop, not get: a replayed ticket must fail even if the first use raced.
+        found = self._tickets.pop(str(ticket or ""), None)
+        if found is None:
+            raise HandoffError("that sign-in link has already been used, or has expired")
+        key, expires = found
+        if expires <= now:
+            raise HandoffError("that sign-in link has expired")
+        return key

tokenbiryani/core/keys.py

@@ -0,0 +1,199 @@
+"""Virtual keys.
+
+Clients present a gateway key, never an upstream credential. Real keys stay in the
+gateway process; a leaked virtual key costs you one revocation, not a rotation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, List, Mapping, Optional
+
+from ..config import KeyConfig
+
+PREFIX = "bir_"
+
+
+#: Below this length a key has too little entropy to reveal any of it and stay secret.
+MIN_MASKABLE = 16
+
+
+def generate_key() -> str:
+    return PREFIX + secrets.token_urlsafe(24)
+
+
+def mask_key(key: str) -> str:
+    """Show enough to tell two keys apart, never enough to use one.
+
+    Short keys are masked completely rather than partially: revealing the first
+    eight characters of an eight-character key reveals the key.
+    """
+    if not key:
+        return ""
+    if len(key) < MIN_MASKABLE:
+        return "\u2022" * 8
+    return key[: len(PREFIX) + 4] + "\u2026"
+
+
+@dataclass
+class AuthResult:
+    ok: bool
+    key: Optional[KeyConfig] = None
+    error: str = ""
+    status: int = 401
+
+
+def hash_key(key: str) -> str:
+    """Managed keys are stored hashed. A leaked store is not a leaked key."""
+    return hashlib.sha256(key.encode("utf-8")).hexdigest()
+
+
+def record_from_config(key: KeyConfig, plaintext: str) -> Dict[str, Any]:
+    return {
+        "name": key.name,
+        "key_hash": hash_key(plaintext),
+        "models": list(key.models),
+        "pool": list(key.pool),
+        "rpm": key.rpm,
+        "spend_cap_usd": key.spend_cap_usd,
+        "priority": key.priority,
+        "max_wait_seconds": key.max_wait_seconds,
+        "session_cap_usd": key.session_cap_usd,
+        "session_max_turns": key.session_max_turns,
+        "admin": key.admin,
+        "created_at": time.time(),
+    }
+
+
+def _string_list(value: Any, default: List[str]) -> List[str]:
+    """Records come back from a store as loose JSON; coerce rather than trust."""
+    if isinstance(value, (list, tuple)):
+        return [str(item) for item in value]
+    return list(default)
+
+
+def _optional_number(value: Any) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _optional_int(value: Any) -> Optional[int]:
+    number = _optional_number(value)
+    return None if number is None else int(number)
+
+
+def config_from_record(record: Mapping[str, Any]) -> KeyConfig:
+    rpm = _optional_number(record.get("rpm"))
+    return KeyConfig(
+        key="",
+        name=str(record.get("name") or ""),
+        models=_string_list(record.get("models"), ["*"]),
+        pool=_string_list(record.get("pool"), []),
+        rpm=None if rpm is None else int(rpm),
+        spend_cap_usd=_optional_number(record.get("spend_cap_usd")),
+        priority=str(record.get("priority") or "interactive"),
+        max_wait_seconds=_optional_number(record.get("max_wait_seconds")),
+        session_cap_usd=_optional_number(record.get("session_cap_usd")),
+        session_max_turns=_optional_int(record.get("session_max_turns")),
+        admin=bool(record.get("admin")),
+    )
+
+
+class KeyRegistry:
+    """Config keys are declared by the operator; managed keys are minted at runtime.
+
+    Config keys are compared in plaintext (they live in the operator's own file).
+    Managed keys are only ever stored as a hash, so the plaintext exists exactly once,
+    in the response that created it.
+    """
+
+    def __init__(self, keys: List[KeyConfig]) -> None:
+        self._keys = list(keys)
+        self._managed: List[Dict[str, Any]] = []
+
+    @property
+    def keys(self) -> List[KeyConfig]:
+        return list(self._keys)
+
+    def set_managed(self, records: List[Dict[str, Any]]) -> None:
+        self._managed = list(records)
+
+    @property
+    def open_access(self) -> bool:
+        """No keys at all means loopback-only, unauthenticated. Refused remotely."""
+        return not self._keys and not self._managed
+
+    def authenticate(self, presented: Optional[str]) -> AuthResult:
+        if self.open_access:
+            # Unauthenticated loopback development: full access, including admin.
+            return AuthResult(True, KeyConfig(key="", name="anonymous", admin=True))
+        if not presented:
+            return AuthResult(False, error="missing credentials")
+        for candidate in self._keys:
+            # Constant-time compare: key checking must not leak length or prefix.
+            if hmac.compare_digest(candidate.key, presented):
+                return AuthResult(True, candidate)
+        digest = hash_key(presented)
+        for record in self._managed:
+            stored = str(record.get("key_hash") or "")
+            if stored and hmac.compare_digest(stored, digest):
+                return AuthResult(True, config_from_record(record))
+        return AuthResult(False, error="invalid key")
+
+    def by_name(self, name: str) -> Optional[KeyConfig]:
+        for candidate in self._keys:
+            if candidate.name == name:
+                return candidate
+        for record in self._managed:
+            if record.get("name") == name:
+                return config_from_record(record)
+        return None
+
+    def is_config_key(self, name: str) -> bool:
+        return any(candidate.name == name for candidate in self._keys)
+
+    def redacted(self) -> List[Dict[str, Any]]:
+        out: List[Dict[str, Any]] = []
+        for key in self._keys:
+            out.append(
+                {
+                    "name": key.name,
+                    "key": mask_key(key.key),
+                    "source": "config",
+                    "models": key.models,
+                    "pool": key.pool or "all",
+                    "rpm": key.rpm,
+                    "spend_cap_usd": key.spend_cap_usd,
+                    "session_cap_usd": key.session_cap_usd,
+                    "session_max_turns": key.session_max_turns,
+                    "priority": key.priority,
+                    "admin": key.admin,
+                }
+            )
+        for record in self._managed:
+            key = config_from_record(record)
+            out.append(
+                {
+                    "name": key.name,
+                    "key": "(hashed)",
+                    "source": "managed",
+                    "models": key.models,
+                    "pool": key.pool or "all",
+                    "rpm": key.rpm,
+                    "spend_cap_usd": key.spend_cap_usd,
+                    "session_cap_usd": key.session_cap_usd,
+                    "session_max_turns": key.session_max_turns,
+                    "priority": key.priority,
+                    "admin": key.admin,
+                    "created_at": record.get("created_at"),
+                }
+            )
+        return out