Take auth/ whole from boilerplate 09e144d: the lockout claimed before the scrypt, APP_PASSWORD recovery closing every session, Starlette's cookie parser, the rightmost forwarded hop in the log, revoke_all on a password change, a 421 for a non-loopback Host on an open app, API tokens in auth_tokens behind Authorization: Bearer, and sockets closed with their credential

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
WolfandClaude Fable 5.1 committed 2026-10-27 11:51:21 +01:00
1 parent 83e965dfeb
commit 244e57ac29
19 files changed
+2288 -214

No files matched your search

+465
View File
@@ -0,0 +1,465 @@
"""API tokens: the third way in, for a script, and what it cannot do.
uv run pytest auth/tests/test_tokens.py -q
A token is minted with the password, carried as `Authorization: Bearer`, looked
up on every request like a session, and shut out of the account routes. The
same-site rule the middleware applies to every request is here too, because a
script's token is the one credential a browser never carries for it.
"""
from __future__ import annotations
import logging
import sqlite3
from collections.abc import Callable
from contextlib import closing
from datetime import UTC, datetime, timedelta
import pytest
from fastapi.testclient import TestClient
from starlette.websockets import WebSocketDisconnect
from auth import AuthStore
from auth.middleware import ACCOUNT, _rebound, cross_site
from auth.store import HINT
from auth.tests import PASSWORD, sign_in
CONFIRM = {"current": PASSWORD}
def mint(client: TestClient, label: str = "cron", **body: object) -> dict:
answer = client.post("/api/account/tokens", json={**CONFIRM, "label": label, **body})
assert answer.status_code == 200, answer.text
return answer.json()
def bearer(token: str) -> dict[str, str]:
return {"authorization": f"Bearer {token}"}
# ------------------------------------------------------------------ the store
def test_the_token_is_not_in_the_file(store: AuthStore):
"""Hashed like a session token, and for the same reason: the file lets
nobody in."""
token_id, token = store.create_token("cron", None)
assert token.encode() not in store.path.read_bytes()
assert store.touch_token(token) is not None
assert store.touch_token(token).id == token_id
def test_the_list_shows_the_opening_and_nothing_else(store: AuthStore):
_, token = store.create_token("cron", None)
(listed,) = store.tokens()
assert listed.hint == token[:HINT] and len(listed.hint) == HINT
assert listed.label == "cron" and listed.expires_at == "" and listed.last_used_at == ""
assert "token" not in listed.model_dump()
def test_a_dated_token_runs_out(store: AuthStore):
_, token = store.create_token("short", 30)
(listed,) = store.tokens()
expires = datetime.fromisoformat(listed.expires_at)
assert timedelta(days=29) < expires - datetime.now(UTC) <= timedelta(days=30)
with closing(sqlite3.connect(store.path)) as conn, conn:
conn.execute("UPDATE auth_tokens SET expires_at='2000-01-01T00:00:00+00:00'")
assert store.touch_token(token) is None
# Still listed, so the owner sees the row that ran out and removes it.
assert len(store.tokens()) == 1
def test_using_a_token_stamps_it_once_in_a_while(store: AuthStore):
_, token = store.create_token("cron", None)
first = store.touch_token(token)
assert first is not None and first.last_used_at
with closing(sqlite3.connect(store.path)) as conn, conn:
conn.execute("UPDATE auth_tokens SET last_used_at='2000-01-01T00:00:00+00:00'")
again = store.touch_token(token)
assert again is not None and again.last_used_at > "2000-01-02"
def test_a_token_is_renamed_and_revoked_by_its_row(store: AuthStore):
token_id, token = store.create_token("cron", None)
assert store.rename_token(token_id, "the laptop") is True
assert store.tokens()[0].label == "the laptop"
assert store.delete_token(token_id) is True
assert store.touch_token(token) is None
assert store.delete_token(token_id) is False
def test_a_token_is_not_a_session(store: AuthStore):
"""Two tables, two lookups: a token in the cookie opens nothing, and a
session token in the header opens nothing."""
_, token = store.create_token("cron", None)
session = store.open_session("browser", 30)
assert store.touch(token) is None
assert store.touch_token(session) is None
# ----------------------------------------------------------------- minting
def test_minting_needs_a_session(locked: TestClient):
assert locked.post("/api/account/tokens", json=CONFIRM).status_code == 401
def test_minting_needs_the_password_too(signed_in: TestClient, caplog):
"""A token outlives every session and a password change, so a borrowed
signed-in browser must not be able to mint one."""
with caplog.at_level(logging.WARNING):
wrong = signed_in.post("/api/account/tokens", json={"current": "nope"})
assert wrong.status_code == 403
assert "wrong current password" in caplog.text
assert signed_in.get("/api/account").json()["tokens"] == []
def test_minting_is_behind_the_same_lockout(signed_in: TestClient):
for _ in range(5):
signed_in.post("/api/account/tokens", json={"current": "nope"})
refused = signed_in.post("/api/account/tokens", json=CONFIRM)
assert refused.status_code == 429
assert sign_in(signed_in).status_code == 429
def test_an_app_with_no_password_mints_without_one(open_app: TestClient):
"""The laptop before it is deployed, as with a passkey."""
made = open_app.post("/api/account/tokens", json={"current": "", "label": "here"})
assert made.status_code == 200 and made.json()["token"]
def test_the_token_is_shown_once_and_listed_by_its_opening(signed_in: TestClient):
made = mint(signed_in, "cron", days=90)
assert made["hint"] == made["token"][:HINT] and made["label"] == "cron"
assert made["expires_at"]
(listed,) = signed_in.get("/api/account").json()["tokens"]
assert listed["id"] == made["id"] and listed["hint"] == made["hint"]
assert "token" not in listed
def test_the_label_and_the_days_are_bounded(signed_in: TestClient):
assert signed_in.post("/api/account/tokens",
json={**CONFIRM, "days": 0}).status_code == 422
assert signed_in.post("/api/account/tokens",
json={**CONFIRM, "days": 4000}).status_code == 422
assert signed_in.post("/api/account/tokens",
json={**CONFIRM, "label": "x" * 101}).status_code == 422
# ------------------------------------------------------------- the bearer
def test_a_token_opens_the_api_and_the_socket(signed_in: TestClient):
token = mint(signed_in)["token"]
script = TestClient(signed_in.app, follow_redirects=False)
assert script.get("/api/thing").status_code == 401
assert script.get("/api/thing", headers=bearer(token)).status_code == 200
with script.websocket_connect("/ws/jobs", headers=bearer(token)) as socket:
assert socket.receive_json()["type"] == "jobs"
def test_a_token_cannot_reach_the_account(signed_in: TestClient):
"""A leaked token must not be able to mint another, revoke the owner's
sessions, or read the list of ways in; and `/logout` is a session's."""
token = mint(signed_in)["token"]
script = TestClient(signed_in.app, follow_redirects=False)
for method, path in (("GET", "/api/account"),
("POST", "/api/account/tokens"),
("POST", "/api/account/sessions/close"),
("DELETE", "/api/account/sessions/1"),
("POST", "/api/account/password"),
("POST", "/logout")):
refused = script.request(method, path, headers=bearer(token), json=CONFIRM)
assert refused.status_code == 403, f"{method} {path}: {refused.status_code}"
assert "not the account" in refused.json()["detail"]
# And the names are matched whole: `/api/accounts` is not the account.
assert script.get("/api/accountx", headers=bearer(token)).status_code == 404
assert ACCOUNT == ("/api/account", "/api/account/", "/logout")
def test_a_cookie_session_wins_over_a_bad_header(signed_in: TestClient):
"""A browser extension that adds a stale header must not sign a browser out."""
assert signed_in.get("/api/account", headers=bearer("stale")).status_code == 200
def test_a_bad_token_is_a_401_and_a_line_in_the_log(locked: TestClient, caplog):
with caplog.at_level(logging.WARNING):
refused = locked.get("/api/thing", headers=bearer("not-a-token"))
assert refused.status_code == 401
assert refused.json()["detail"] == "That token is not valid here."
assert "bad token from testclient" in caplog.text
# JSON whatever was asked for: a script, not a browser, sent this header.
assert locked.get("/deep/page", headers=bearer("not-a-token")).status_code == 401
# And nothing is counted against the password: the right one still opens.
assert sign_in(locked).status_code == 200
def test_only_the_bearer_scheme_is_read(locked: TestClient):
assert locked.get("/api/thing",
headers={"authorization": "Basic dXNlcjpwYXNz"}).status_code == 401
assert locked.get("/api/thing?token=x").status_code == 401
def test_a_revoked_token_is_refused_on_the_next_request(signed_in: TestClient):
made = mint(signed_in)
script = TestClient(signed_in.app, follow_redirects=False)
assert script.get("/api/thing", headers=bearer(made["token"])).status_code == 200
assert signed_in.delete(f"/api/account/tokens/{made['id']}").status_code == 200
assert script.get("/api/thing", headers=bearer(made["token"])).status_code == 401
assert signed_in.delete(f"/api/account/tokens/{made['id']}").status_code == 404
def test_a_token_survives_a_password_change(signed_in: TestClient):
"""Like a passkey: the cron job holding it is not what the password was
changed against. The account screen is where to revoke it, and the answer
says how many remain so the screen can say so."""
token = mint(signed_in)["token"]
changed = signed_in.post("/api/account/password",
json={"current": PASSWORD, "new": "a-much-longer-one"})
assert changed.status_code == 200
assert changed.json() == {"signed_out": 0, "tokens_revoked": 0, "passkeys_revoked": 0,
"tokens_left": 1, "passkeys_left": 0}
script = TestClient(signed_in.app, follow_redirects=False)
assert script.get("/api/thing", headers=bearer(token)).status_code == 200
def test_a_password_change_can_revoke_every_token_and_passkey(signed_in: TestClient):
"""The case the route exists for: whoever had the password may have
minted a token that never expires or registered a passkey, and either
outlives the change. `revoke_all` deletes them with it."""
token = mint(signed_in)["token"]
mint(signed_in, "another")
signed_in.app.state.auth.add_passkey(b"cred", b"key", 0, "", "someone's key")
other = TestClient(signed_in.app, follow_redirects=False)
sign_in(other)
changed = signed_in.post("/api/account/password", json={
"current": PASSWORD, "new": "a-much-longer-one", "revoke_all": True})
assert changed.status_code == 200
assert changed.json() == {"signed_out": 1, "tokens_revoked": 2, "passkeys_revoked": 1,
"tokens_left": 0, "passkeys_left": 0}
script = TestClient(signed_in.app, follow_redirects=False)
assert script.get("/api/thing", headers=bearer(token)).status_code == 401
account = signed_in.get("/api/account").json()
assert account["tokens"] == [] and account["passkeys"] == []
assert other.get("/api/thing").status_code == 401
assert signed_in.get("/api/thing").status_code == 200
def test_a_wrong_password_revokes_nothing(signed_in: TestClient):
token = mint(signed_in)["token"]
refused = signed_in.post("/api/account/password", json={
"current": "nope", "new": "a-much-longer-one", "revoke_all": True})
assert refused.status_code == 403
script = TestClient(signed_in.app, follow_redirects=False)
assert script.get("/api/thing", headers=bearer(token)).status_code == 200
def test_a_token_is_renamed_from_the_account(signed_in: TestClient):
made = mint(signed_in)
renamed = signed_in.post(f"/api/account/tokens/{made['id']}/label",
json={"label": "the pi"})
assert renamed.status_code == 200
assert signed_in.get("/api/account").json()["tokens"][0]["label"] == "the pi"
assert signed_in.post("/api/account/tokens/999/label",
json={"label": "x"}).status_code == 404
def test_an_open_app_ignores_the_header(open_app: TestClient):
"""Unlocked, there is no door for a token to open; a stale one is not an error."""
assert open_app.get("/api/thing", headers=bearer("whatever")).status_code == 200
# ------------------------------------------------------------ another site
EVIL = "http://evil.example"
def test_another_sites_page_cannot_post_to_an_unlocked_app(open_app: TestClient):
"""No session cookie to withhold on loopback, so `SameSite` protected
nothing: a `text/plain` POST needs no preflight and reached every route
that takes no body."""
assert open_app.post("/api/account/sessions/close").status_code == 200
assert open_app.post("/api/account/sessions/close",
headers={"origin": "http://127.0.0.1"}).status_code == 200
assert open_app.post("/api/account/sessions/close",
headers={"sec-fetch-site": "same-origin"}).status_code == 200
for headers in ({"origin": EVIL}, {"origin": "null"},
{"sec-fetch-site": "cross-site"}, {"sec-fetch-site": "same-site"},
{"origin": "http://127.0.0.1", "sec-fetch-site": "cross-site"}):
refused = open_app.post("/api/account/sessions/close", headers=headers)
assert refused.status_code == 403, headers
assert "another site" in refused.json()["detail"]
plain = open_app.post("/api/account/sessions/close", content=b"x",
headers={"content-type": "text/plain"})
assert plain.status_code == 415 and "application/json" in plain.json()["detail"]
form = open_app.post("/api/account/sessions/close", content=b"a=1",
headers={"content-type": "application/x-www-form-urlencoded"})
assert form.status_code == 415
# A read is never refused, wherever it came from.
assert open_app.get("/api/thing", headers={"origin": EVIL}).status_code == 200
def test_a_transfer_encoding_header_is_a_body_whatever_its_value():
"""Its presence says a body follows; an empty value is malformed and is
not given the benefit of the doubt."""
for value in (b"chunked", b""):
scope = {"type": "http", "method": "POST",
"headers": [(b"content-type", b"text/plain"),
(b"transfer-encoding", value)]}
refused = cross_site(scope)
assert refused is not None and refused[0] == 415, value
scope["headers"] = [(b"content-type", b"text/plain")]
assert cross_site(scope) is None
def test_another_sites_page_cannot_open_the_socket(open_app: TestClient):
"""A WebSocket handshake is not subject to CORS, so any page could open
`/ws/jobs` on a loopback app and read every job and notice."""
with pytest.raises(WebSocketDisconnect), \
open_app.websocket_connect("/ws/jobs", headers={"origin": EVIL}):
pass
# The test client's handshake names `testserver` whatever the base URL,
# so the app's own page is spelt out: a loopback host, and its origin.
with open_app.websocket_connect("/ws/jobs", headers={
"host": "127.0.0.1", "origin": "http://127.0.0.1"}) as ws:
assert ws.receive_json()["type"] == "jobs"
def test_the_configured_origin_is_accepted_behind_a_proxy_that_rewrites_host(
make_client: Callable[..., TestClient]):
client = make_client(enabled="auto", host="127.0.0.1", password=None,
origin="https://app.example.com", base_url="http://127.0.0.1")
assert client.post("/api/account/sessions/close",
headers={"origin": "https://app.example.com"}).status_code == 200
assert client.post("/api/account/sessions/close",
headers={"origin": EVIL}).status_code == 403
def test_the_rule_holds_on_a_locked_app_too(signed_in: TestClient):
"""A locked app with `secure_cookie: never` on a LAN is a real deployment,
and the two header reads cost nothing."""
assert signed_in.post("/api/account/sessions/close",
headers={"origin": EVIL}).status_code == 403
assert signed_in.post("/api/account/sessions/close").status_code == 200
# ------------------------------------------------- what a token must not reach
def test_an_app_names_what_a_token_may_not_reach(tmp_path):
"""A route that hands out or replaces the database as a file holds the
password hash and the token rows, so `connect(session_only=...)` shuts it
to a token the way the account is shut."""
from fastapi import FastAPI
from fastapi.responses import PlainTextResponse
from auth import AuthConfig, AuthStore, connect
app = FastAPI()
db = tmp_path / "s.db"
store = AuthStore(db)
store.set_password(PASSWORD)
connect(app, store, AuthConfig(enabled="always"), host="0.0.0.0",
session_only=("/api/backups", "/api/backups/", "/api/restore"))
@app.get("/api/backups/{name}", response_class=PlainTextResponse)
def download(name: str) -> str:
return "the whole database"
@app.post("/api/restore", response_class=PlainTextResponse)
def restore() -> str:
return "swapped"
@app.get("/api/thing")
def thing() -> dict[str, bool]:
return {"ok": True}
_, token = store.create_token("cron", None)
with TestClient(app, follow_redirects=False) as client:
assert client.get("/api/thing", headers=bearer(token)).status_code == 200
assert client.get("/api/backups/x.db.gz", headers=bearer(token)).status_code == 403
assert client.post("/api/restore", headers=bearer(token)).status_code == 403
sign_in(client)
assert client.get("/api/backups/x.db.gz").status_code == 200
# ---------------------------------------------------------- a rebound name
def test_a_rebinding_page_is_refused_on_an_unlocked_app(open_app: TestClient):
"""A page on `rebind.example`, pointed at 127.0.0.1, sends a `Host` and
an `Origin` that agree, and `Sec-Fetch-Site: same-origin`, so the
same-site rule cannot tell it from the app's own page. The name can:
a loopback app is reached as localhost, and a script naming anything
else for it is refused with the proxy's 421."""
page = {"host": "rebind.example:8787", "origin": "http://rebind.example:8787",
"sec-fetch-site": "same-origin"}
refused = open_app.post("/api/account/tokens", json={"current": ""}, headers=page)
assert refused.status_code == 421
assert "localhost" in refused.json()["detail"]
assert open_app.get("/api/thing", headers=page).status_code == 421
with pytest.raises(WebSocketDisconnect), \
open_app.websocket_connect("/ws/jobs", headers=page):
pass
# The app's own page, at any loopback name, is untouched, and so is a
# client that is not a page when it names one.
for host in ("localhost:8787", "127.0.0.1", "[::1]:8787", "app.localhost"):
own = {"host": host, "origin": f"http://{host}", "sec-fetch-site": "same-origin"}
assert open_app.get("/api/thing", headers=own).status_code == 200, host
assert open_app.get("/api/thing", headers={"host": host}).status_code == 200, host
assert open_app.post("/api/account/sessions/close",
headers={"host": "localhost"}).status_code == 200
def test_a_rebound_request_without_page_headers_is_refused_too(open_app: TestClient):
"""A browser that sends no `Sec-Fetch-Site`, and no `Origin` on a read, is
still a rebound page reading the API. The `Host` is judged whatever else
the request carries, so a name that is not loopback is refused, and so is
a `Host` that names nothing."""
for host in ("rebind.example", "rebind.example:8787", "testserver", "["):
refused = open_app.get("/api/thing", headers={"host": host})
assert refused.status_code == 421, host
assert open_app.post("/api/account/sessions/close",
headers={"host": "rebind.example"}).status_code == 421
with pytest.raises(WebSocketDisconnect), \
open_app.websocket_connect("/ws/jobs", headers={"host": "rebind.example"}):
pass
assert _rebound({"type": "http", "headers": []}, "") is True
def test_the_configured_origin_is_a_name_the_unlocked_app_answers_to(
make_client: Callable[..., TestClient]):
client = make_client(enabled="auto", host="127.0.0.1", password=None,
origin="https://app.example.com")
page = {"host": "app.example.com", "origin": "https://app.example.com",
"sec-fetch-site": "same-origin"}
assert client.get("/api/thing", headers=page).status_code == 200
page["host"] = page["origin"] = "other.example.com"
assert client.get("/api/thing", headers=page).status_code == 421
# -------------------------------------------------------- a cookie that is not one
def test_a_cookie_header_that_is_not_one_is_read_as_no_cookie(locked: TestClient):
"""The middleware is in front of every request, so a header it cannot
read must be no cookie and not a 500 on every call that carried it."""
for header in ("a@b=1", ";;;", "=", '"', "app_session=", "app_session"):
refused = locked.get("/api/thing", headers={"cookie": header})
assert refused.status_code == 401, header
def test_a_malformed_neighbour_cookie_does_not_sign_the_owner_out(signed_in: TestClient):
"""`SimpleCookie.load` returned an empty jar for the whole header when any
cookie in it had a space or JSON in its value, so a sibling app on the
parent domain setting `theme=dark mode` locked the owner into a login
loop. Read per pair, the session beside it still opens the door."""
from http.cookies import SimpleCookie
session = signed_in.cookies["app_session"]
jar = SimpleCookie()
jar.load(f"theme=dark mode; app_session={session}")
assert "app_session" not in jar, "the stdlib parser was the bug"
browser = TestClient(signed_in.app, follow_redirects=False)
for neighbour in ("theme=dark mode", 'x={"a":1}'):
for header in (f"{neighbour}; app_session={session}",
f"app_session={session}; {neighbour}"):
answer = browser.get("/api/thing", headers={"cookie": header})
assert answer.status_code == 200, header