"""Passkeys, driven by a real authenticator that happens to be in software. `softkey.py` says why this is possible and what it does not cover. The short version: the signatures here are real, so every check the server makes is exercised for real -- a wrong origin fails because the origin is signed over, a replay fails because the challenge is spent, a clone is caught because the counter went backwards. uv run pytest auth/tests/test_passkeys.py -q Skipped wholesale without the `passkeys` extra. What the app does when the extra is *missing* is `test_without_passkeys.py`, which always runs -- it has to be, or the case is covered by nothing. """ from __future__ import annotations from base64 import urlsafe_b64decode from collections.abc import Callable import pytest from fastapi.testclient import TestClient from auth.tests import PASSWORD, sign_in pytest.importorskip("webauthn", reason="the `passkeys` extra is not installed") from auth.tests.softkey import SoftKey, b64 # noqa: E402 after the skip #: The tests talk to the app as `localhost`, which is the one host a browser #: lets WebAuthn run on without HTTPS -- so it is also the one that exercises #: the real `blocked()` path rather than a configured override. RP_ID = "localhost" ORIGIN = "http://localhost" def unb64(text: str) -> bytes: return urlsafe_b64decode(text + "=" * (-len(text) % 4)) @pytest.fixture def client(make_client: Callable[..., TestClient]) -> TestClient: """A locked app the browser reaches as `localhost`.""" signed = make_client(enabled="always", base_url=ORIGIN) assert sign_in(signed).status_code == 200 return signed def register(client: TestClient, key: SoftKey, label: str = "Test key"): """The whole registration ceremony, both round trips.""" options = client.post("/api/account/passkeys/options").json() made = key.register(unb64(options["challenge"]), RP_ID, ORIGIN) return client.post("/api/account/passkeys", json={"credential": made, "label": label}) def login(client: TestClient, key: SoftKey, origin: str = ORIGIN): """The whole sign-in ceremony, both round trips.""" options = client.post("/login/passkey/options").json() signed = key.sign(unb64(options["challenge"]), RP_ID, origin) return client.post("/login/passkey", json={"credential": signed}) # --------------------------------------------------------------- registering def test_registering_needs_a_session(client: TestClient): """A passkey is a new way in, so adding one is gated on already being in.""" client.post("/logout") assert client.post("/api/account/passkeys/options").status_code == 401 def test_a_passkey_registers_and_is_listed(client: TestClient): assert register(client, SoftKey(), label="YubiKey 5C").status_code == 200 account = client.get("/api/account").json() assert [p["label"] for p in account["passkeys"]] == ["YubiKey 5C"] assert account["passkeys"][0]["transports"] == ["internal"] # No key material reaches the screen -- not even the public half. assert "public_key" not in account["passkeys"][0] def test_the_public_key_is_stored_and_the_private_one_is_not(client: TestClient): key = SoftKey() register(client, key) # The private key never left the authenticator, so nothing derived from it # can be in the file. Its public point, necessarily, is. private = key.key.private_numbers().private_value.to_bytes(32, "big") blob = client.app.state.auth.path.read_bytes() assert private not in blob assert key.credential_id in blob def test_a_second_registration_is_excluded_not_duplicated(client: TestClient): """The browser is told what is already registered, so an authenticator can say "you have one of these" rather than making a second.""" key = SoftKey() register(client, key) options = client.post("/api/account/passkeys/options").json() assert [c["id"] for c in options["excludeCredentials"]] == [b64(key.credential_id)] def test_a_stale_challenge_is_refused(client: TestClient): """A challenge is single-use, so the same response cannot be sent twice.""" key = SoftKey() options = client.post("/api/account/passkeys/options").json() made = key.register(unb64(options["challenge"]), RP_ID, ORIGIN) assert client.post("/api/account/passkeys", json={"credential": made}).status_code == 200 replay = client.post("/api/account/passkeys", json={"credential": made}) assert replay.status_code == 400 assert "already used" in replay.json()["detail"] def test_a_challenge_this_server_never_issued_is_refused(client: TestClient): """The response is well-formed and correctly signed. It is still not ours.""" made = SoftKey().register(b"a challenge from nowhere", RP_ID, ORIGIN) assert client.post("/api/account/passkeys", json={"credential": made}).status_code == 400 # ---------------------------------------------------------------- signing in def test_a_registered_passkey_signs_in(client: TestClient): key = SoftKey() register(client, key) client.post("/logout") assert client.get("/api/thing").status_code == 401 assert login(client, key).status_code == 200 assert client.get("/api/thing").status_code == 200 def test_a_passkey_session_is_an_ordinary_session(client: TestClient): """One kind of session whichever door it came through, so revoking and expiry have one implementation rather than two.""" key = SoftKey() register(client, key) client.post("/logout") login(client, key) sessions = client.get("/api/account").json()["sessions"] assert sum(s["current"] for s in sessions) == 1 client.post("/logout") assert client.get("/api/thing").status_code == 401 def test_an_unregistered_key_is_refused(client: TestClient): register(client, SoftKey()) client.post("/logout") assert login(client, SoftKey()).status_code == 401 def test_a_signature_for_another_origin_is_refused(client: TestClient): """The heart of why a passkey cannot be phished: the origin is inside what gets signed, so a signature made for one site is void at another.""" key = SoftKey() register(client, key) client.post("/logout") assert login(client, key, origin="https://app.example.evil").status_code == 401 assert client.get("/api/thing").status_code == 401 def test_a_replayed_signature_is_refused(client: TestClient): """Captured off the wire and sent again -- the challenge is already spent.""" key = SoftKey() register(client, key) client.post("/logout") options = client.post("/login/passkey/options").json() signed = key.sign(unb64(options["challenge"]), RP_ID, ORIGIN) assert client.post("/login/passkey", json={"credential": signed}).status_code == 200 client.post("/logout") assert client.post("/login/passkey", json={"credential": signed}).status_code == 401 def test_a_cloned_key_is_caught(client: TestClient): """A counter that goes backwards means two authenticators are answering for one credential. Only detectable when the authenticator uses the counter.""" key = SoftKey(counts=True) register(client, key) client.post("/logout") assert login(client, key).status_code == 200 client.post("/logout") key.sign_count = 0 # the clone, which started its own count key.counts = False refused = login(client, key) assert refused.status_code == 401 assert "cloned" in refused.json()["detail"] def test_a_platform_passkey_that_never_counts_still_works(client: TestClient): """Most phones report a constant 0. Treating that as a regression would reject every real sign-in from one, so it must not.""" key = SoftKey(counts=False) register(client, key) client.post("/logout") for _ in range(3): assert login(client, key).status_code == 200 client.post("/logout") def test_a_malformed_body_is_a_400_and_not_a_traceback(client: TestClient): """`webauthn` raises a whole family of exceptions and only one of them is `InvalidAuthenticationResponse`. Catching that one and nothing else leaves a body with a field missing to come out of an endpoint that needs no session as a 500 with a stack trace in the log -- from anyone on the internet, as often as they like. """ key = SoftKey() register(client, key) client.post("/logout") options = client.post("/login/passkey/options").json() signed = key.sign(unb64(options["challenge"]), RP_ID, ORIGIN) del signed["response"]["authenticatorData"] refused = client.post("/login/passkey", json={"credential": signed}) assert refused.status_code == 400 assert "not a passkey" in refused.json()["detail"] # 400 and not 401: nothing here was a credential, so nothing was refused. assert client.get("/api/thing").status_code == 401 assert client.post("/login/passkey", json={"credential": {}}).status_code == 400 def test_no_passkeys_registered_says_so(client: TestClient): client.post("/logout") assert client.post("/login/passkey/options").status_code == 404 # -------------------------------------------------- one purpose per challenge def test_a_registration_challenge_cannot_be_answered_at_the_login_door( client: TestClient): """A challenge is issued for one ceremony and is good for that one only. Without the purpose check the two doors share one pool of random numbers, and the door that needs no session can spend a challenge that was handed out behind one. Everything else about the response is real here -- a registered key, a live challenge, a signature this server would accept -- so the purpose is the only thing standing between the two. """ key = SoftKey() register(client, key) theirs = client.post("/api/account/passkeys/options").json() client.post("/logout") signed = key.sign(unb64(theirs["challenge"]), RP_ID, ORIGIN) assert client.post("/login/passkey", json={"credential": signed}).status_code == 401 assert client.get("/api/thing").status_code == 401 def test_a_login_challenge_cannot_be_answered_at_the_registration_door( client: TestClient): """The same rule the other way round, which is the half that is easy to forget: `/login/passkey/options` needs no session, so its challenges are the ones a stranger can have as many of as they like.""" key = SoftKey() register(client, key) theirs = client.post("/login/passkey/options").json() made = key.register(unb64(theirs["challenge"]), RP_ID, ORIGIN) assert client.post("/api/account/passkeys", json={"credential": made}).status_code == 400 def test_an_expired_challenge_is_refused(client: TestClient): """The bound on how long a captured `options` response is worth anything.""" key = SoftKey() register(client, key) client.post("/logout") options = client.post("/login/passkey/options").json() assert expire(client) == 1 signed = key.sign(unb64(options["challenge"]), RP_ID, ORIGIN) refused = client.post("/login/passkey", json={"credential": signed}) assert refused.status_code == 401 assert "too long" in refused.json()["detail"] assert client.get("/api/thing").status_code == 401 def expire(client: TestClient) -> int: """Backdate every outstanding challenge, as five minutes of doing nothing would. Written rather than waited for: the alternative is a test that sleeps for the ceremony timeout.""" import sqlite3 from contextlib import closing with closing(sqlite3.connect(client.app.state.auth.path)) as conn, conn: return conn.execute("UPDATE auth_challenges SET expires_at=?", ("2000-01-01T00:00:00+00:00",)).rowcount # ------------------------------------------------------------------ managing def test_a_passkey_can_be_renamed_and_revoked(client: TestClient): key = SoftKey() passkey_id = register(client, key).json()["id"] assert client.post(f"/api/account/passkeys/{passkey_id}/label", json={"label": "The one on my keyring"}).status_code == 200 assert client.get("/api/account").json()["passkeys"][0]["label"] \ == "The one on my keyring" assert client.delete(f"/api/account/passkeys/{passkey_id}").status_code == 200 assert client.get("/api/account").json()["passkeys"] == [] # Revoked means revoked. With none left there is nothing to sign with, so # the ceremony stops at the first round trip rather than the second. client.post("/logout") assert client.post("/login/passkey/options").status_code == 404 def test_revoking_a_passkey_cannot_lock_you_out(client: TestClient): """The password stays, which is the whole reason revoking is safe.""" passkey_id = register(client, SoftKey()).json()["id"] client.delete(f"/api/account/passkeys/{passkey_id}") client.post("/logout") assert sign_in(client).status_code == 200 def test_registering_does_not_disable_the_password(client: TestClient): register(client, SoftKey()) client.post("/logout") assert sign_in(client, PASSWORD).status_code == 200 # ------------------------------------------------------------- the settings def test_localhost_is_a_secure_context(client: TestClient): """The one host a browser lets WebAuthn run on without HTTPS, so the account screen must not claim otherwise.""" account = client.get("/api/account").json() assert account["passkeys_available"] is True assert account["passkeys_blocked"] == "" def test_plain_http_off_localhost_is_refused_with_a_reason( make_client: Callable[..., TestClient]): """The case that will actually happen: served over HTTP on a LAN address, where the browser would refuse and surface nothing useful.""" client = make_client(enabled="always", base_url="http://192.168.1.10:8787") sign_in(client) said = client.get("/api/account").json()["passkeys_blocked"] assert "HTTPS" in said assert "192.168.1.10" in said def test_a_configured_rp_id_and_origin_win(make_client: Callable[..., TestClient]): """What a deployment behind a TLS-terminating proxy needs: the app sees plain HTTP and must still bind credentials to the real origin.""" client = make_client(enabled="always", rp_id="app.example.com", origin="https://app.example.com") sign_in(client) options = client.post("/api/account/passkeys/options").json() assert options["rp"]["id"] == "app.example.com" assert client.get("/api/account").json()["passkeys_blocked"] == "" key = SoftKey() made = key.register(unb64(options["challenge"]), "app.example.com", "https://app.example.com") assert client.post("/api/account/passkeys", json={"credential": made}).status_code == 200 def test_a_passkey_login_on_an_unlocked_app_is_a_400(open_app: TestClient): """There is no session to open when there is no door, and this must not quietly hand one out anyway: that would be a second, unauthenticated way to mint the very thing the middleware checks.""" refused = open_app.post("/login/passkey", json={"credential": {}}) assert refused.status_code == 400 assert "not password-protected" in refused.json()["detail"] assert open_app.app.state.auth.sessions() == []