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))