Week 9: Verifying the Token

Two pull requests merged this week and the most security-critical piece of the whole project went out for review on its own. This was the week the plan from week 7 started visibly paying off. Two merges On 28 July, #7654 merged — the LtiDeployment model. CircuitVerse can now store which LMS platforms it trusts: the issuer, the client ID, the deployment ID, and the platform's endpoint URLs, unique per issuer + client + deployment because that triple is how LTI 1.3 identifies a deployment. Nothing reads the table yet. That is the point of building this way, and it is the thing that needs explaining in every PR description. The validator The main work was #7715: Lti::JwtValidator, a class with one public method. Lti::JwtValidator.validate!(token, deployment:, nonce:) Give it an id_token, the deployment it should belong to, and the nonce we issued. It either returns the verified payload or raises. No controller, no session, no Rails request object. That isolation was forced by the constraint that it had to be its own pull request, and it is a much better boundary than I would have drawn otherwise. What it has to refuse The tests are mostly attacks: A token signed by the wrong key. The baseline. A token with alg: none. Early JWT libraries would accept an unsigned token if it declared its algorithm as none. Any validator that reads the algorithm out of the token and trusts it is exploitable. An HS256 token where RS256 is expected. This is algorithm confusion, and it is the subtle one. RS256 is asymmetric: the platform signs with a private key, we verify with their public key, which is published. HS256 is symmetric: the same secret signs and verifies. If a validator takes the algorithm from the token header and passes the platform's public key as the key, an attacker can sign a token using that public key as an HMAC secret — and the validator verifies it, because it is doing exactly what it was told. The public key is public, so anyone can do this. The defence is to never read the algorithm from the token. Pass an explicit allow-list: encoded_token.verify_signature!(algorithm: "RS256", key: key) Expired, wrong issuer, wrong audience, missing subject, replayed nonce, and the multi-audience case: when aud is an array with more than one entry, the azp claim must name our client ID. Resolving the platform's key The other half is fetching the right public key. A platform publishes a JWKS endpoint; the token header carries a kid identifying which key signed it. Two things made this more interesting than expected: Key rotation. Platforms rotate keys. A cached key set will not contain a newly rotated key. So a kid that is missing from the cache is treated as a signal that rotation may have happened, and triggers a refetch rather than a wait for expiry. Caching. Without it, every single launch makes an outbound HTTP request to the platform before anyone can sign in. If the platform's JWKS endpoint is slow, every login is slow; if it is down, every login is down. A short-lived cache keyed on the JWKS URL fixes that, with the rotation behaviour above as the escape hatch. What review found The bot review flagged two failure modes I had not handled, and both were correct: A blank jwks_url. A deployment configured with only a stored public key and no JWKS URL would still make an HTTP request, because a blank URL parses as a relative path rather than failing. So every launch for that deployment took a pointless network trip before falling back. One guard clause. Malformed stored key data. OpenSSL::PKey::RSA.new raises OpenSSL::PKey::RSAError on bad PEM data, and I was only rescuing JWT::DecodeError. So a misconfigured deployment record would propagate an OpenSSL exception out of a method whose entire contract is "raises ValidationError". Callers written against that contract would not catch it. That second one is a good example of a bug that is invisible while you are writing the code and obvious once named. My mental model was "this method validates tokens, so it raises validation errors." The actual behaviour was "this method raises validation errors unless the database row is malformed, in which case it raises something else entirely." I fixed both in fix(lti): harden JwtValidator key resolution per review. The refactor request Late in the week, a maintainer asked something more interesting than a bug report: could you suggest refactoring this class using JWT::Token or JWT::EncodedToken My implementation called JWT.decode twice — once with verification disabled to read the header and pick a key by kid, then again with verification on. That works, and it has a smell: there is a window where the code holds an unverified, parsed token, and nothing but my own discipline stops me from reading a claim out of it. JWT::EncodedToken closes that window at the library level. #payload refuses to decode until both the signature and the claims have been verified: def payload raise JWT::DecodeError, '...' unless @signature_verified raise JWT::DecodeError, '...' unless @claims_verified decoded_payload end The header is still read unverified, which is unavoidable — you cannot pick a key without knowing which key was used — but it is only ever used to select a candidate key, and the ordering the class used to depend on by convention is now enforced by the library. That is a strictly better property: the difference between "the code is correct" and "the code cannot easily be made incorrect by the next person to edit it." What I am taking from the week The isolation was the win. Because the validator was its own pull request, with no controller and no session attached, both the review comments were about the validator — its error contract, its failure modes — rather than about whether the launch flow around it made sense. Compare that to my POC, where the same class was buried in 2,000 lines and nobody looked at it at all. Next week: the first half of the handshake ships, and a scanner disagrees with me about CSRF.