File size: 8,351 Bytes
9411b94 868b75a 9411b94 868b75a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 | """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))
|