🏆Capstone project: Project: Tokens the Server Can Trust

signing.py can issue a token, read one, and replace a key. reading_server.py uses none of it yet: the write routes still accept two strings from sample_state(). This project connects the two and removes the strings. Here is what the finished server must do:

See where you stand:

python pl_sec.py forged-token

It logs in as ben, asks for a token, and then tries tokens that must not work. Today two lines tell the story:

ben asks for a token, with the cookie  POST /tokens  -> 404
a token that was once in the source code  POST /books -> 201  accepted

Where a token comes from now

A reader logs in, which gives them Chapter 4’s session, and then sends POST /tokens with the session cookie. The session proves who they are. The token is what a program sends afterward, with no cookie and no password.

current_session(request, state) finds the session. A visitor session has no user, so it gets the same 401 as no session at all. That 401 carries the Basic challenge of /login, because logging in is how a client gets the session it lacks.

can_write used to be written next to each fixed token. Now it comes from state["writers"], a set of names that sample_state() already has: the token says user in state["writers"]. A token carries that answer as it was when the token was made. A user who is removed from the set keeps writing until the token expires.

Milestones

1. Write the attack. test_attack_token_from_the_source_is_refused builds its state with steps.keyed_state(), which is sample_state() with the test key in state["keys"]. A test never runs main, so nothing else would put keys there. The precondition is a login that works; the attack is a POST /books with Bearer tok-ana-writes-7Qx2. Run python -m pytest -q: 1 failed, 14 passed, because the string still opens the route.

2. Issue tokens. Write token_response, add the tokens branch to handle, and add tokens to the no-store rule: a token is a credential, and no cache may keep one.

3. Check tokens. Write token_claims, and rewrite write_error so that it decides from the claims alone. Your test passes.

4. Remove the strings. Delete the "tokens" entry from sample_state(). Nothing reads it any more.

5. Two more attacks. Both start from steps.bearer_for(state, user, password), which logs in, asks POST /tokens, and returns the whole Authorization value, Bearer included. They are described below.

6. Watch it. Run python pl_sec.py forged-token again.

7. Write it down. Fill and close F6 in SECURITY.md, and add F14.

test_attack_changed_token_is_refused uses steps.keyed_state({"now": 1000000}), so the clock stands still at a moment when an exp of 2000000 is still ahead. Then only the tag can refuse the forged token. Get ben’s value with bearer_for and split it at the dots. Build the payload {"user": "ana", "can_write": True, "exp": 2000000}, turn it into text with signing.b64u_encode(json.dumps(payload).encode("utf-8")), and join the first part, that text, and the old third part with dots. First assert that ben’s honest token reads back as his: signing.read_token(state["keys"], bearer.split(" ")[1], now=1000000)["user"] is "ben". Then send POST /books with the forged value and assert 401.

test_attack_expired_token_is_refused keeps its clock: clock = {"now": 1000000}, then steps.keyed_state(clock). Get ana’s value, send POST /books, and assert 201. Add 16 * 60 to clock["now"], send the same request again, and assert 401.

After milestone 5, python -m pytest -q says 17 passed. The scenario of milestone 6 then shows what is inside ben’s token, and three refusals. Among its lines:

its payload, read without any key: {"user": "ben", "can_write": false, "exp": 1000900}
ben adds a book with his own token       POST /books -> 403  {"error": "this token may read the list but not change it"}
the changed payload with the old tag      POST /books -> 401  refused
a token that was once in the source code  POST /books -> 401  refused
ben's own token, 16 minutes old           POST /books -> 401  refused
3 of 3 bad tokens refused

One finding stays open

Closing F6 opens a smaller hole, and an honest list says so. Add row F14 below F7:

• Exposed: whatever a token allows, for up to 15 minutes.

• Attack: a token that leaks works until it expires. Logout does not end it, and the server keeps no list to cross it off.

• Fix: a short life, which is done, and in a real service a stored list of withdrawn tokens, which is not built.

• Test: none yet. Status: open.

Then press Check my work. It checks the routes with users, keys, and a clock of its own, calls main as Lesson 4’s check did, and runs your four tests of this chapter against servers of its own, where each test must fail on the mistake it is about.

The fixed strings are gone, and a token now proves who is asking. It does not yet say which books that person may touch: every writer’s token still opens every book. That is Chapter 6.