loopable / api /aios_session.py
fsanyoto's picture
Deploy AIOS web (React glide grid + FastAPI slice)
868b75a verified
Raw History Blame Contribute Delete
8.35 kB
"""aios_session.py — X3: the signed, STATELESS session cookie (EXIT-3a, 2026-07-30).
aios_session = base64url(json {t,u,e,i,x}) . base64url(HMAC-SHA256)
`t` tenant slug · `u` username · `e` the user's revocation epoch · `i` idle deadline ·
`x` absolute expiry. Signed with `AIOS_SESSION_SECRET` using stdlib `hmac` — no new dependency,
and nothing to store server-side, which is the whole point: EXIT-4 requires a process that holds
no per-tenant state, and a session TABLE is per-tenant state. D2's Postgres sessions-MIRROR (an
audit view, not the source of truth) arrives with C-2 and is deliberately deferred.
WHY STATELESS STILL REVOKES. A cookie nobody can delete sounds like a cookie nobody can revoke.
The answer is the `epoch` integer on the user record (`core.users.epoch` / `bump_epoch`): the
cookie carries the epoch it was minted under, every verification re-reads the account's current
epoch, and a password change, a deactivation, or (wave 40, R2) any LOGIN bumps it — so every outstanding cookie for that
user dies at once, without a session table.
⚠ NO FALLBACK SECRET, EVER. With `AIOS_SESSION_SECRET` unset this module mints a RANDOM
per-process key: sessions then die on restart, which is an inconvenience. A hardcoded default
would instead let anyone who has read this repo forge a cookie for any user of any tenant — an
inconvenience is the correct trade against a forgery key. `EPHEMERAL_SECRET` records which
happened so the app can say so at startup and a gate can assert it.
"""
import base64
import hmac
import json
import os
import secrets
import time
from hashlib import sha256
COOKIE_NAME = "aios_session"
IDLE_SECONDS = 8 * 60 * 60 # D2: reissued on every authenticated request
ABSOLUTE_SECONDS = 30 * 24 * 60 * 60 # D2: a hard ceiling no amount of activity extends
TRUST_COOKIE_NAME = "aios_trusted_browser"
TRUST_SECONDS = 7 * 24 * 60 * 60
_TRUST_PURPOSE = "aios-trusted-browser-v1"
_env_secret = os.environ.get("AIOS_SESSION_SECRET") or ""
EPHEMERAL_SECRET = not _env_secret
_SECRET = _env_secret.encode("utf-8") if _env_secret else secrets.token_bytes(32)
def _b64(raw: bytes) -> str:
return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
def _unb64(txt: str) -> bytes:
return base64.urlsafe_b64decode(txt + "=" * (-len(txt) % 4))
def _sign(payload: bytes) -> str:
return _b64(hmac.new(_SECRET, payload, sha256).digest())
def mint(tenant, username, epoch, now=None, absolute_expiry=None):
"""A fresh cookie value. `absolute_expiry` carries over on reissue so refreshing the idle
window can never extend the 30-day ceiling — that would make the ceiling unreachable."""
now = int(now if now is not None else time.time())
claims = {"t": str(tenant), "u": str(username), "e": int(epoch),
"i": now + IDLE_SECONDS,
"x": int(absolute_expiry if absolute_expiry is not None
else now + ABSOLUTE_SECONDS)}
payload = json.dumps(claims, separators=(",", ":"), sort_keys=True).encode("utf-8")
return f"{_b64(payload)}.{_sign(payload)}", claims
def read(value, now=None):
"""Parse + verify a cookie value → claims dict, or None.
None for EVERY failure mode — bad shape, bad signature, expired, unparseable. The caller
answers 401 and must not learn which: an error that distinguishes "signature wrong" from
"expired" tells a forger whether their key is right.
"""
if not value or not isinstance(value, str) or value.count(".") != 1:
return None
body, sig = value.split(".", 1)
try:
payload = _unb64(body)
except Exception:
return None
# compare_digest on the SIGNATURE, always — a byte-wise early exit is a timing oracle.
if not hmac.compare_digest(sig, _sign(payload)):
return None
try:
claims = json.loads(payload.decode("utf-8"))
except Exception:
return None
if not isinstance(claims, dict):
return None
if not isinstance(claims.get("u"), str) or not isinstance(claims.get("t"), str):
return None
if not claims["u"] or not claims["t"]:
return None
try:
idle, absolute, epoch = int(claims["i"]), int(claims["x"]), int(claims["e"])
except (KeyError, TypeError, ValueError):
return None
now = int(now if now is not None else time.time())
if now >= idle or now >= absolute:
return None
claims["e"], claims["i"], claims["x"] = epoch, idle, absolute
return claims
def is_secure_request(request):
"""Secure flag ON unless this is plain-HTTP localhost. Set unconditionally in production;
unset on a local http:// dev origin, where a Secure cookie is simply never sent back and
login would appear to succeed and then not work."""
host = (request.headers.get("host") or "").split(":")[0].lower()
proto = (request.headers.get("x-forwarded-proto")
or request.url.scheme or "http").split(",")[0].strip().lower()
if proto == "https":
return True
return host not in ("localhost", "127.0.0.1", "[::1]", "::1")
def set_cookie(response, request, value):
response.set_cookie(
COOKIE_NAME, value, httponly=True, samesite="lax",
secure=is_secure_request(request), max_age=ABSOLUTE_SECONDS, path="/")
def clear_cookie(response, request):
# Same attributes as when it was set: a browser matches on path/secure/samesite when
# deleting, and a mismatched delete silently leaves the cookie in place.
response.delete_cookie(COOKIE_NAME, path="/", httponly=True, samesite="lax",
secure=is_secure_request(request))
def _trust_sign(payload):
key = hmac.new(_SECRET, _TRUST_PURPOSE.encode("ascii"), sha256).digest()
return _b64(hmac.new(key, payload, sha256).digest())
def mint_trusted_browser(tenant, username, epoch, generation, *, now=None, original=None):
"""Carry the original proof window when a password login rotates its session epoch."""
now = int(time.time() if now is None else now)
issued = original["a"] if original is not None else now
expiry = original["x"] if original is not None else now + TRUST_SECONDS
claims = {"p": _TRUST_PURPOSE, "t": tenant, "u": username, "e": epoch,
"g": generation, "a": issued, "x": expiry}
payload = json.dumps(claims, separators=(",", ":"), sort_keys=True).encode("utf-8")
return f"{_b64(payload)}.{_trust_sign(payload)}", claims
def read_trusted_browser(value, tenant, username, epoch, generation, *, now=None):
"""Refuse every malformed or mismatched claim without admitting a session."""
if not isinstance(value, str) or len(value) > 2048 or value.count(".") != 1:
return None
try:
body, signature = value.split(".")
payload = _unb64(body)
if _b64(payload) != body or not hmac.compare_digest(signature, _trust_sign(payload)):
return None
claims = json.loads(payload)
if not isinstance(claims, dict) or set(claims) != {"p", "t", "u", "e", "g", "a", "x"}:
return None
if any(type(claims[k]) is not int for k in ("e", "a", "x")):
return None
if any(type(claims[k]) is not str or not claims[k] for k in ("p", "t", "u", "g")):
return None
if (claims["p"] != _TRUST_PURPOSE or claims["t"] != tenant
or claims["u"] != username or claims["e"] != epoch
or claims["e"] < 0 or claims["g"] != generation):
return None
now = int(time.time() if now is None else now)
if not (0 <= claims["a"] <= now < claims["x"]
and claims["x"] - claims["a"] == TRUST_SECONDS):
return None
return claims
except (ValueError, TypeError, OverflowError, UnicodeError):
return None
def set_trusted_browser_cookie(response, request, value, claims):
remaining = max(0, min(TRUST_SECONDS, claims["x"] - int(time.time())))
response.set_cookie(TRUST_COOKIE_NAME, value, httponly=True, samesite="lax",
secure=is_secure_request(request), max_age=remaining, path="/")
def clear_trusted_browser_cookie(response, request):
response.delete_cookie(TRUST_COOKIE_NAME, path="/", httponly=True, samesite="lax",
secure=is_secure_request(request))