DEV Community: Akanksha Trehun

Week 11: Welcome to my Midterm evaluation

Akanksha Trehun — Sun, 16 Aug 2026 06:06:06 +0000

Midterm evaluations ran from the 10th to the 14th. Deep linking and roster sync both
shipped, two more pull requests merged, and then I sat down to write an honest account of
where the project stands — which is how I found out that the plan I have been working
from for a month builds a machine nobody can switch on.

Deep linking, end to end

Two pull requests, two days apart.

#7772 handles the request
side: a launch arrives with LtiDeepLinkingRequest as its message type instead of
LtiResourceLinkRequest, and everything downstream has to route differently. The
platform sends along deep_linking_settings — where to return the response, whether
multiple items are allowed, whether the platform wants a title back — and that has to be
stashed for the response, which happens on a completely separate request.

#7777 is what the instructor
actually sees: a picker listing their circuits and assignments, with the selection posted
back to the LMS as a signed JWT.

The satisfying part is that neither pull request needed anything new from the protocol
layer. The JWT signing is the key manager from week 4. The validation on the way in is
the validator from week 9. Deep linking is a different conversation with the platform,
but it is the same handshake underneath, and by this point the handshake is just there.

The roster

#7779 reads a course roster
over the Names and Roles service — pagination via Link headers, roles parsed out of the
IMS role URIs. #7781 turns
that into group members.

The interesting decision in the second one is how users get matched. Not on email — that
was week 5's lesson, and the reason for it holds here too: a platform's privacy settings
may mean no email arrives at all, and even when one does, it might belong to a different
CircuitVerse account than the person clicking. The match is on sub plus issuer, the
same identity pair the launch signs the user in with. A roster import that mapped on
email could silently add a stranger to a course.

Members created this way get marked as LTI-synced, which matters for the drop-handling
pull request that follows: when someone disappears from the LMS roster, only synced
members get deactivated. Somebody who joined the CircuitVerse group directly should not
be removed because they were never in Canvas to begin with.

Two merges

#7715, the JWT validator,
merged on the 11th. #7763,
the resource link model, merged on the 12th. Both had been sitting approved for a while —
the validator since the end of July.

Five merged now: the 1.1 passback fix, the deployment model, the JWKS and tool
configuration endpoints, the validator, and the resource link. Eight more open and
waiting.

The evaluation

What the evaluation actually asked me to do was describe the state of the project, which
sounds trivial and was not. Writing "here is what works" forces a different question than
"here is what I built this week," and the two answers were not the same shape.

So I went back to the three issues this project exists to close and read them line by
line against what is in the repository. Not the proposal — the issues, as filed.

A pipeline nobody could feed

The autograding phase of my plan had six pull requests: a test case model, a headless
runner wrapper, a grading result, a job that runs on submission, a results page, and a
push to the LMS gradebook. Student submits, autograder runs, grade lands in Canvas.

Every one of those is about executing test cases. Not one of them is about creating
test cases.

The issue says it plainly — "a test case editor in the assignment settings UI where
instructors can add, edit and delete test cases" — and I had somehow read that as
satisfied by a database table. It is not. A model with no UI means the only way to define
a test suite is the Rails console, which is not a feature an instructor can use. I had
planned six pull requests that would ship a grading pipeline with no way to put anything
into it.

Reading further with that lens, four more gaps fell out. There was no visible/hidden flag
on test cases, which both issues ask for. There was nothing for the autograde
configuration — partial credit, allowed attempts, whether students see the cases before
submitting. "Versioned with the assignment" had no plan behind it at all, and my model
actively worked against it: one row per assignment, edited in place, so changing a suite
would quietly invalidate every grade already produced from it.

And the least visible one, which I only found by reading the Grade model rather than
remembering it: nothing in the plan mapped a score onto an assignment's grading scale.
The autograder produces a fraction. Grade validates against letter, percent, or
custom, and rejects no_scale outright. Autograding an assignment with no grading
scale would have failed at the last step, after the run, with the student watching.

Twenty-four becomes twenty-seven

Week 7's post was called "Twenty-Four Pull Requests." That plan is now twenty-seven, all
three additions in the autograding phase: the test case editor, the autograde settings,
and the grading-scale mapping — plus reworking the grading result to carry an attempt
number and a snapshot, and folding hidden-case redaction into the results page.

The snapshot is how "versioned with the assignment" gets solved, and it is the change I
am happiest with. Rather than a version table with all the machinery that implies, each
grading result stores a copy of the suite it ran against. Edit the suite afterwards and
old results stay reproducible, because the thing that produced them is still sitting
right there next to them.

Three of the nine are written. The model and the runner are pushed; the editor is done
and waiting locally, because it needs the model's table to exist and I would rather open
one clean pull request after the first merges than one showing two commits.

Reusing a format instead of inventing one

The nicest thing I wrote this week is four words long.

A test case needs a name, input pin values, expected output pin values, and a hidden
flag. The simulator's testbench format already has groups — a named collection of cases
with input and output signals. My first instinct was to add fields: a name array, a
hidden array, indices lining up across them.

Then: a test case is just a group with n: 1.

One case, one name, one hidden boolean. It validates against the model I had already
written without changing a line of it, it invents no schema, and when the suite reaches
the simulator it is a format the simulator already knows how to run. The editor
serialises its table into exactly that on submit.

I have written the other version of this before — the one with parallel arrays and a
comment explaining how the indices correspond. It works right up until someone deletes a
row from one array and not the others.

Not reimplementing the simulator

The runner wrapper was the piece I was most nervous about, and the design question was
where the simulation actually happens.

The tempting answer was Ruby: run the circuit server-side, in the language the rest of
the grading code is written in. I talked myself out of it in about ten minutes. It means
reimplementing thousands of lines of simulation logic, and then maintaining two engines
that will drift — and the failure mode of that drift is a student's circuit passing in
the browser and failing at grading. For a grading tool there is no worse bug.

Driving a real browser was the next candidate, and capybara-playwright-driver is
already in the Gemfile, so it looked nearly free. A browser process per submission is not
nearly free.

Shelling out to Node was the closest call, because there is precedent: the Yosys
integration in this repository does exactly that. I went with an HTTP call to a sidecar
service instead, mirroring the other half of that same integration — a URL from the
environment, the same timeout-and-post shape the simulator controller already uses. It
keeps the engine on the frontend repository's release cadence, where that code and the
people who know it live.

Every failure collapses into one error class: bad circuit data, a non-2xx, a timeout, a
non-JSON body, an empty result. That is deliberate. The only caller is a background job,
and there is exactly one right answer to all of them — mark the run failed, leave the
student's grade alone.

Where the project stands

Five merged, eight open, three written and waiting. The protocol layer is done and
merged. Grade passback, deep linking, and roster sync are all in the queue. Autograding is
started.

The plan grew by three pull requests this week, which on a burndown chart is a bad week.
It is the most useful thing I did. I have spent eleven weeks getting good at making
mechanisms work, and the evaluation caught me having built most of a system that no
instructor could have used, because I kept reading a feature request as a description of
a machine instead of a description of a person trying to get something done.

Next week: the editor lands, and then the settings and the grading result behind it.

Week 10: The Handshake Begins

Akanksha Trehun — Sat, 08 Aug 2026 02:21:38 +0000

This week the first leg of the LTI 1.3 handshake shipped as
#7746, a static analyser and I
disagreed about CSRF, and I spent an afternoon cleaning up a database mess I had made
for myself weeks earlier.

OIDC login initiation

The endpoint is /lti/login, and it is the URL that the tool configuration from
#7659 has been advertising as
oidc_initiation_url for three weeks while returning 404.

An LMS calls it with iss, login_hint, and optionally client_id and
lti_deployment_id. CircuitVerse resolves those to a registered deployment, mints a
one-time nonce and a signed state, and redirects the browser to the platform's
authorization endpoint:

302 Found
location: http://canvas.docker/api/lti/authorize_redirect?scope=openid
  &response_type=id_token&response_mode=form_post&prompt=none
  &client_id=...&redirect_uri=.../lti/launch&login_hint=demo-student
  &nonce=ddbf28cc...&state=eyJfcmFpbHMi...--e3a4d84925a8df11c8dc6a...

response_mode=form_post and prompt=none are what make the platform POST the token
straight back rather than showing a login screen. The -- in the state is the HMAC
separator — that is the signed-state design from week 6 finally in production form.

64 lines of controller code, about 150 lines of tests.

Arguing with CodeQL

CI came back with CodeQL failing: CSRF protection weakened or disabled.

It was pointing at this line, which I had edited to add the new action:

skip_before_action :verify_authenticity_token, only: %i[launch oidc_login]

My first reaction was that this is a false positive. Of course there is no CSRF token —
the request originates from Canvas. There is no way for an LMS to hold a token minted by
our forms.

My second reaction, which took longer, was that the scanner was pointing at something
real even if its conclusion did not fit. skip_before_action is a blunt instrument: it
turns the check off for the entire action, for every request shape, forever. What I
actually wanted to say is narrower — this particular kind of request does not need a
token, and everything else still does.

So instead of skipping, I overrode the predicate the check uses:

def verified_request?
  super || (action_name == "oidc_login" && params[:iss].present? && params[:login_hint].present?)
end

Token verification stays fully active for every other action and every other request
shape. Only a well-formed LTI initiation is treated as verified. And the justification
holds up: the action reads no session, writes nothing, and the signed state it returns is
what actually protects the launch that follows.

I checked this was real rather than incidental by removing the override and running the
tests — the cross-site POST spec fails with InvalidAuthenticityToken. Worth doing,
because a test that passes for the wrong reason is worse than no test. The test
environment disables forgery protection by default, so that spec has to switch it back
on explicitly or it proves nothing at all.

CodeQL went green, and the code is genuinely narrower than what I started with. The
scanner was more right than I initially gave it credit for.

What review caught

Three findings on the pull request, all worth having:

Ambiguous deployment matches. My lookup ended with scope.order(:id).first. Since
client_id is optional in an initiation, a platform with several registrations under
one issuer would silently resolve to whichever row happened to have the lowest ID — and
the launch would be sent to a different registration's client ID and authorization
endpoint. Now an ambiguous match is refused with a 404 rather than guessed at.

Non-HTTPS authorization endpoints. The LtiDeployment model only validates that
auth_login_url is present, not that it is a sane URL. Since the redirect uses
allow_other_host: true, a malformed or hostile value in that column goes straight to
the browser. A javascript: URL is now rejected before it can reach redirect_to, and
TLS is required in production while plain http still works locally.

Registered query parameters being discarded. Some platforms register an
authorization endpoint that already carries query parameters. I was replacing the query
string wholesale. The suggested fix merged instead of replaced — and introduced a subtle
bug of its own by merging symbol keys into a hash with string keys, so a platform's own
scope= would have survived alongside ours as a duplicate parameter. String keys
throughout fixed it.

That last one is a good reminder that a suggested patch is a suggestion. Both PRs this
week had a fix applied through the GitHub web UI that did not splice cleanly — one
duplicated the tail of a method, leaving four unreachable statements and a duplicate
rescue clause that failed lint. Convenient, but it still needs reading.

The database mess

Somewhere in this week I tried to run the new endpoint against my development database
and got a NOT NULL violation on a column that does not exist in the merged schema.

The cause was archaeology. My abandoned POC branch from week 2 had a migration creating
lti_deployments with a platform_id column. I ran it against my dev database in June.
The branch was closed; the migration was never rolled back. The merged version of that
table, from a completely different pull request, has no platform_id — so my dev
database had a table that matched no branch anyone was working on.

Tracing it was more interesting than expected. The physical column order gave it away:
platform_public_key sat after the timestamps, which meant it had been added by a
later add_column rather than declared inline — which pinned it to the March POC
migration rather than the June one. Twenty-six migration versions were recorded in my
dev database with no corresponding file on any branch, along with an orphaned
lti_platforms table whose migration no longer exists anywhere.

I cleaned it surgically rather than dropping the database: exported the two Canvas
registrations my demo depends on, dropped the drifted columns and tables, cleared the
stale migration stamps, ran the real migration, and re-imported the registrations
against the new schema.

The lesson is cheap to state and I had to learn it the expensive way: migrations you
run from a branch that never merges do not clean themselves up. A dev database is
long-lived state that accumulates the residue of every experiment.

Where the project stands

Merged: the 1.1 grade passback fix, and the deployment model. Approved and waiting: the
JWKS and tool configuration endpoints, the JWT validator, and now the OIDC login.

That is four of the twenty-four, with the whole of phase 1's protocol layer either
merged or in the queue.

Next is the launch itself — verify the state, validate the token through the validator
from week 9, bind the token's deployment to the one the state was issued for, and sign
the user in on their sub. It is the piece where all the separate bricks finally do
something a user can see: a Canvas click landing a signed-in user inside CircuitVerse.

It is also the one I need to be most careful with, and I have a list of open questions
to settle before writing it — what happens when a platform's privacy settings mean it
sends no email address at all, what happens when that email already belongs to a
CircuitVerse account, and where the nonce gets recorded so a state cannot be replayed
inside its five-minute window.

Ten weeks ago I would have just written it and found out.

Week 9: Verifying the Token

Akanksha Trehun — Sat, 08 Aug 2026 02:19:37 +0000

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.

Week 8: The First Merge, and Learning to Wait

Akanksha Trehun — Sat, 08 Aug 2026 02:18:20 +0000

On 26 July, #7647 merged. It
was the first piece of my project to land in CircuitVerse's master branch, fourteen
days after I opened it and about seven weeks into the project.

It is a small change. It makes sure an LTI 1.1 grade is written to CircuitVerse's
database before it is pushed to the LMS gradebook, so the two cannot silently disagree
when a local save fails. Plus the fix from last week's review — clearing stale grading
context only after a launch has been verified, so a forged request cannot wipe a
teacher's session on its way to being rejected.

Most of this week was spent not writing code, which is a thing I want to write about
honestly rather than skip over.

What actually shipped

The merged change has two halves, and the second only exists because of review.

The first is ordering: persist the grade, then push it to the LMS. Previously the
passback ran first, so a local save that failed validation left the gradebook holding a
score CircuitVerse had no record of. The LMS is the more visible system, which makes
this the worse direction to be wrong in — a student and an instructor both see a grade
that does not exist anywhere in our database.

The second is the fix from anxkhn's review: stale grading context is now cleared only
after a launch has been verified, not before. An unauthenticated request that gets
rejected can no longer wipe a teacher's in-progress grading session on its way out.

Both are small. Neither is glamorous. Together they mean the gradebook and CircuitVerse
cannot silently disagree, in an integration that schools are using today, which is worth
more than another thousand lines of the 1.3 work sitting unmerged on a branch.

The shape of the week

My commit graph for 16–25 July is empty. Two pull requests were open and waiting
(#7654 and
#7659), one was awaiting the
final look before merge, and the next thing in the plan — the JWT validator — depended
on decisions inside them.

Early in the project, a week like this would have gone one of two ways. Either I would
have sat refreshing the PR page, or I would have started building three PRs ahead and
piled up work that might need reworking depending on how the review went.

I had done the second thing already, in weeks 2 and 3, and it is how I ended up with a
2,000 line branch nobody could review.

What review latency actually is

The reframe that helped: maintainer response time is not an obstacle in the process. It
is the process.

CircuitVerse's maintainers review contributions alongside their own jobs. A day or two
of latency on a pull request is not neglect, it is the normal operating speed of a
volunteer-maintained project. Every plan I make has to be built for that speed rather
than in spite of it.

Concretely, that changes what "being blocked" means. If PR N is in review and PR N+1
depends on it, I am not blocked from working — I am blocked from committing to a
particular implementation of N+1. Those are different, and the gap between them is
where the useful work of a waiting week lives.

What I did with it

Read the review comments properly. Not just applying them, but working out the
general rule behind each. anxkhn's note about clearing grading context before
verification was specifically about one method, but the rule it implies — nothing that
mutates state may happen before the security check, including deletes — is one I could
then apply to code they had not looked at. A review comment is a sample from a
distribution of mistakes I am prone to. Fixing the sample is the minimum; finding the
distribution is the value.

Wrote the next PR's tests before its code. The JWT validator was next, and while I
did not want to commit to its implementation before the deployment model merged, the
attacks it must survive did not depend on any of that. A token signed with the wrong
key. A token with alg: none. An HS256 token where the validator expects RS256 —
algorithm confusion, where an attacker signs with the public key as an HMAC secret and a
naive validator accepts it. Expired tokens, wrong issuer, wrong audience, missing
subject, replayed nonce.

Writing those first meant that when the validator got written, its shape was determined
by what it had to refuse rather than by what I found convenient to implement.

Read other people's LTI implementations. Specifically for how they handle key
rotation — a platform can publish a new signing key at any time, and a tool that caches
the key set has to notice. The pattern I settled on: cache the key set, but if a token
arrives with a kid that is not in the cache, refetch immediately rather than waiting
for the cache to expire. Rotation is exactly the case where the cache is stale, so
treating a cache miss as a rotation signal is the right default.

Kept the queue moving. The point of the twenty-four PR plan is a steady stream of
small reviewable things. That only works if the queue is never empty from my side, and
never so full that it becomes a burden. Two open at a time, both small, both green,
turned out to be about right.

On the size of the win

Fourteen days from open to merge, for a change of about 150 lines that fixes a real bug
in a feature real users have today.

Measured in lines of code per day it is not much. But the previous seven weeks produced
zero merged lines, and the thing that changed was not that I started working harder — it
was that I started sending work in a form somebody could say yes to.

That is the actual lesson of the first half of this project, and I could not have
learned it by reading about it. I had to spend three weeks building something good that
could not merge.

There is a version of this project where I never write the POC, go straight to small
PRs, and have six things merged by now. I do not think I would have understood why
they had to be small. The POC being closed is what made the constraint make sense rather
than feel like bureaucracy.

Where things stand

Merged: the 1.1 grade passback fix.
Approved and waiting: the deployment model, and the JWKS and tool configuration endpoints.
Next: the JWT validator — the security-critical brick, reviewed on its own.

Next week: the token validator, and finding out my key-resolution code had two failure
modes I had not handled.

Week 7: Creating phases for the tasks

Akanksha Trehun — Sat, 08 Aug 2026 02:16:10 +0000

This was the week the project got a plan it could actually execute, and the week a
reviewer found a security bug in a fix I had already convinced myself was correct.

The review

I had opened #7647 at the end
of last week — the small fix ensuring an LTI 1.1 grade is saved locally before being
pushed to the LMS.

On 14 July, anxkhn reviewed it. The first comment was housekeeping: rebase and look
at failing CI. I rebased, tests went green, and I said so.

The second comment is the one worth writing about:

storing the context is fixed, but it is still cleared before valid_request?. for
example, a fake launch could clear a teacher's valid grading session and prevent the
next grade passback. please clear it only after a valid launch too.

Let me unpack what that means, because it is genuinely subtle.

An LTI 1.1 launch stores some grading context in the session — the outcome service URL
the LMS wants scores posted to, and which assignment is being graded. My change made
sure that context is written after the launch signature is verified. Good.

But the clearing of stale context happened in a before_action, which runs before
valid_request? — before we know whether the launch is genuine at all.

So: a teacher launches from Canvas, gets a valid grading session, starts grading.
Meanwhile anyone can POST garbage at /lti/launch with no valid signature. That request
gets rejected — 401, correct — but on its way to being rejected it has already wiped
the teacher's grading context. Their next grade passback silently fails.

An unauthenticated request cannot sign in, cannot read anything, cannot write
anything — and can still degrade a legitimate user's session as a side effect of being
rejected.

I had read that code many times. I had written the fix for the adjacent bug in the same
method. I did not see it, because I was asking "is the write ordered correctly?" and the
bug was in the delete.

What I take from it: when you fix ordering around a security check, audit every
operation on that path, not just the one you came for. The invariant is not "the write
happens after verification." It is "nothing that affects state happens before
verification." I had fixed one instance of a general rule while leaving another in
place.

I also want to record that this is the value of review that no amount of care
substitutes for. Not because the reviewer knew something I did not, but because they
came to the code without my assumption about which line was interesting.

The other review comment

The same day, anxkhn reviewed
#7654, the LtiDeployment
model, and approved it — with a nitpick:

could you change Fixes #7405 to Part of #7405? this PR is the first foundation
step, so merging it should not close the larger issue.

Small, and it corrected a real misunderstanding. I had been writing Fixes #7405 on
every LTI pull request out of habit. GitHub's auto-close keywords mean the first one to
merge would have closed the umbrella issue tracking the entire LTI 1.3 upgrade — with
about 90% of it unbuilt.

Part of #7405 links without closing. I have used that phrasing on every LTI PR since.

Twenty-four pull requests

The bigger piece of the week was planning. On 14 July I wrote out the remaining work as
a sequence of pull requests, and the constraint I set was that no single one should
exceed roughly 200 hand-written lines. Generated files like Gemfile.lock and
db/schema.rb do not count, but get flagged for reviewers.

It came to twenty-four.

The number was startling and also clarifying. What used to be "implement LTI 1.3" became
a dependency-ordered queue, with phases:

Phase 0 — the credibility work: fix the 1.1 bug that already affects real users.
Phase 1 — the launch core, five PRs: gems and the deployment model; key manager and public endpoints; the JWT validator alone; OIDC login initiation; the launch itself; then the resource link model.
Phase 2 — Assignment and Grade Services, so grades flow to the LMS gradebook.
Phase 3 — Deep Linking, so an instructor can embed specific CircuitVerse content.
Phase 4 — Names and Roles, so the roster syncs.
Phase 5 — autograding.

The thing that surprised me is how much the constraint improved the design, not just
the delivery. Forced to make Lti::JwtValidator a standalone pull request, it has to be
a class that takes a token and a deployment and returns a payload — no controller, no
session, no Rails request. That is a better boundary than I would have drawn if I were
free to let it reach into whatever it wanted.

The same happened to the OIDC login. Made to stand alone, it has to hand back a state
that the launch can verify later with no shared memory between them — which is exactly
the signed-state design from last week. The constraint and the correct architecture
pointed the same way.

Two rules I wrote down alongside the plan:

If a PR crosses ~200 lines, split the spec edge cases into a follow-up — never thin out security validation to fit the budget.
Every PR description names which future PR depends on it, so a maintainer can see why a change with no user-visible behaviour deserves to merge.

That second rule is doing a lot of work. The hardest thing about this approach is that
most of the PRs do nothing on their own. A deployments table nothing reads. A validator
nothing calls. Without the dependency note, each looks like dead code, and "we don't
merge unused code" is a reasonable instinct for a maintainer to have.

Shipping against the plan

Two PRs went out under the new scheme:

#7654 — the LtiDeployment
model: issuer, client ID, deployment ID, and the platform's endpoint URLs, unique per
issuer + client + deployment. 97 lines. Storage only, nothing reads it yet. Approved
the day it was reviewed.

#7659 — the JWKS and tool
configuration endpoints, plus a key manager that owns CircuitVerse's own RSA keypair.
This is what makes CircuitVerse registerable: an LMS admin fetches the tool
configuration, and the platform can fetch our public key to verify anything we sign.
193 lines, behind the flag.

Both were reviewable in a sitting. Which, compared to a 2,000 line POC closed the next
day, is the whole difference.

Next week: waiting, and what I did with it.

Week 6: Signing the State, and Closing My Own Pull Requests

Akanksha Trehun — Sat, 08 Aug 2026 02:13:42 +0000

Three things happened this week: I undid the cookie change from week 5 with something
better, I put the entire LTI 1.3 feature behind a flag that defaults to off, and I
closed two of my own pull requests.

Undoing the cookie

Last week I set SameSite=None on the session cookie so it would survive the
cross-site POST that carries the id_token back from the platform. It worked, and it
weakened a CSRF defence across the whole application to serve one endpoint.

This week's commit is
fix(lti): sign the OIDC state instead of weakening the session cookie.

The reframe that unlocked it: I had been treating "the state must survive the round
trip" as "the state must be stored somewhere that survives the round trip." Those are
not the same requirement. The state does not need to be stored at all. It needs to be
recognisable when it comes back.

So instead of keeping a value in the session and comparing, the state becomes a signed,
self-contained token carrying its own payload:

LTI_STATE_PURPOSE = "lti.launch.state"
LTI_STATE_TTL = 5.minutes

state = lti_state_verifier.generate(
  { "nonce" => nonce, "deployment_id" => deployment.id },
  purpose: LTI_STATE_PURPOSE,
  expires_in: LTI_STATE_TTL
)

Rails.application.message_verifier signs it with the application's secret. When the
launch returns, we verify the signature, and if it checks out we know the contents came
from us and have not been altered. The nonce and the deployment ID ride inside the
token itself.

What this buys:

No session, so no cookie problem. Nothing needs to survive the cross-site POST except the parameter the platform is already sending back to us.
No cookie policy change. SameSite=Lax stays as it is for every other page on the site.
No server-side state. No table, no cleanup job, no expiry sweeper.
The signature is the CSRF defence. Only CircuitVerse can mint a valid state, so a launch carrying one is answering an initiation we started.
It expires. Five minutes, enforced by the verifier.

The purpose argument is a detail worth calling out. It scopes the signature to this
one use, so a token signed elsewhere in the application with the same secret will not
verify here. Same secret, different purposes, no cross-use.

The general lesson: when a constraint blocks you, check whether you are solving the
constraint or the requirement behind it. "Survive a cross-site POST" sounded like a
cookie problem. It was a state-management problem, and moving the state out of the
session dissolved the cookie question entirely.

The flag

The commit feat(lti): gate LTI 1.3 behind a default-off lti_advantage flag does what
it says: every 1.3 endpoint returns 404 unless an operator turns the flag on.

The reason is specific. The 1.3 launch auto-provisions user accounts. A launch from
a registered platform creates a CircuitVerse user, confirmed, ready to sign in. That is
correct behaviour for the feature and it is also a significant thing to have live in
production the moment a branch merges.

A default-off flag means the code can land, be reviewed, be tested, and sit there inert
until somebody deliberately switches it on. It decouples "this code is merged" from
"this code is running", which for an auth path is exactly the separation you want.

There was also a small commit removing some stale comments about CSRF token handling —
notes I had written to myself that had stopped being true after the state change.
Comments that describe an older version of the code are worse than no comments.

Closing two pull requests

On 12 July I closed #7510,
the lti-advantage gem addition, and
#7632, the subgroups feature.

The gem one was straightforward: I had already reversed that decision in week 4 and
gone direct to ruby-jwt. Leaving the PR open was just noise in the queue. Closing your
own obsolete pull requests is a small courtesy — every open PR is something a maintainer
has to look at at least once to decide it is not for them.

Subgroups was harder, because that one was finished. Data layer, UI, controller, API
endpoints, scoping, tests. Earlier in the week I had added the REST API v1 endpoints and
fixed a bug where a synced user who was also a subgroup mentor got a duplicate
membership row inserted.

But it had the same problem as my original POC: it was a large change to a core model,
arriving as one piece, at a moment when the maintainers' attention on my work was
pointed at LTI. It was not going to get the review it needed, and holding it open would
not change that.

The work is not lost — the branch is intact and the design still holds up. It just is
not the thing I should be spending review capital on right now.

That framing — review capacity as a budget you spend — was new to me this week.
Maintainer attention is the scarcest resource on the project. Every PR I open spends
some, and if I spend it on something that is not on the critical path, the thing that
is on the critical path waits longer.

Opening the first small one

Right at the end of the week I opened
#7647, and it is deliberately
tiny.

It fixes a bug in the existing LTI 1.1 code: when a teacher grades a project in an LTI
session, the score was pushed to the LMS before the grade was saved locally. If the
local save then failed validation, the LMS would show a grade that CircuitVerse had
never stored. The gradebook and the source of truth silently disagree.

It has nothing to do with 1.3. I picked it as the first thing to send precisely because
it is small, self-contained, and improves the integration that already has real users —
and because it demonstrates I can send something a maintainer can review in ten minutes.

Which, after week 3, felt like the point.

Next week: a reviewer finds a bug in it that I had looked straight past, and I cut the
remaining work into twenty-four pull requests.

Community Bonding: Before the First Line of Project Code

Akanksha Trehun — Sat, 08 Aug 2026 02:01:18 +0000

Coding starts on 1 June. This post is about the three weeks before that — what I did
with them, and what I thought the project was going to be, which turned out to be only
partly right.

How I got here

By the time the accepted projects were announced, I had already sent CircuitVerse about
forty pull requests.

That number sounds more impressive than it is. A lot of them were typo fixes in
documentation and specs — genuinely trivial changes, the kind you send while you are
still working out where anything lives. Some were closed. Some are still open.

But they did their job, which was less about the changes themselves than about learning
the shape of the project: how the app is laid out, what the review process feels like,
which parts of the codebase are load-bearing and which are quiet corners nobody has
touched in three years.

The ones I am actually pleased with came later and were small bug fixes rather than
typos — scoping an assignments index to the current user's groups, removing a duplicate
update! call, adding includes(:user) to some notification callbacks that were firing
N+1 queries.

One of them turned out to be a signpost: a partial unique index on
assignments.lti_consumer_key, because LTI 1.1 launches look assignments up by that
column and there was nothing enforcing uniqueness. That was the first time I read
CircuitVerse's LMS integration properly, months before I proposed to rewrite it.

Turning a proposal into issues

The most useful thing I did during bonding was on 25 May, and it produced no code at
all. I broke the project down into four separate feature issues and filed them:

#7405 — upgrade the LMS integration from LTI 1.1 to LTI 1.3
#7406 — roster sync, so a class list flows from the LMS into a CircuitVerse group
#7407 — grade passback via Assignment and Grade Services
#7408 — deep linking, so an instructor can embed specific CircuitVerse content in a course page

A proposal is a document you write for a small audience during a selection process, and
then it mostly sits still. Issues are different. They live in the repository where the
work happens, anyone can comment on them, and they force you to state what you are
actually going to build in terms a maintainer can disagree with before you have built
anything.

Writing them also clarified something for me. In the proposal, "LTI 1.3 support" was one
line item. Split into four issues, the dependency structure became obvious: the launch
has to exist before grades can flow back, because grade passback needs the deployment
and resource-link context that a launch establishes. Roster sync and deep linking both
need the same. #7405 is not one of four features, it is the foundation the other three
stand on.

That ordering shaped everything since.

Reading the code I was proposing to replace

The other substantial piece of bonding was reading CircuitVerse's existing LTI 1.1
integration line by line — the controller, the score submission service, the launch
views, the specs.

I went in expecting to find it neglected, because 1.1 is the old standard and my project
is the new one. That is not what I found. It is compact and it works, and it is used by
real courses today.

I did find things I noted for later. Grades were being pushed to the LMS before being
saved locally, so a failed local save could leave the gradebook holding a score
CircuitVerse never stored. A NameError in a code path that only triggers under
specific conditions. Small gaps, mostly in error handling rather than in the happy path.

Two of them became my first pull requests of the coding period.

Reading it also settled a design question I had been vague about in the proposal.
Nothing about my project requires removing 1.1, and plenty of institutions are still on
it. So the plan became strictly additive: 1.3 arrives alongside 1.1, both work, and
nobody's existing setup breaks. "Backward compatible" stopped being a nice phrase in a
proposal and became a constraint I could check every change against.

The Mergathon

On 26 May, CircuitVerse ran a Mergathon — a coordinated push across all the org's
repositories to deal with the pull request backlog. I spent the day on triage.

I have permissions to label, close and comment, not to merge, so the work was: read
every open PR, work out whether it was still alive, and close the ones that were not
with an explanation.

The numbers were bracing. On the Interactive-Book repository I closed around forty-six
stale pull requests, some open since 2019. Thirteen more on the Vue frontend, five on
the blog. On the mobile app there were ten Dependabot PRs all failing for the same
reason — a dependency requiring a newer Flutter SDK than CI was running — so I traced
the root cause once and commented it on all ten. A handful of others were genuinely
green and just needed someone to say so, which I labelled for a maintainer to merge.

Reading dozens of dead pull requests in one sitting is an unusual way to spend a day and
I learned more from it than from anything else in bonding. Almost none of them died
because the code was wrong. They died from going quiet — the author moved on, the branch
drifted behind master, a maintainer asked a question that was never answered, and then
too much time passed for anyone to want to pick it up.

The pattern I noticed and did not fully absorb: the bigger a pull request was, the more
likely it was to be in that pile. Small ones either merged or got closed quickly. Large
ones lingered until they were unmergeable.

I understood that as an observation about other people's pull requests. It took until
week 3 of the coding period, and having my own large one closed, to understand it was
about mine too.

Setting up something to test against

The last piece was practical: getting an LMS I could actually launch from. Reading the
LTI specification tells you what the protocol says. Watching a real Canvas instance
refuse your launch for reasons the spec does not mention teaches you a different set of
things.

This took longer than expected, which I gather is normal. LTI is a protocol where two
servers have to agree about URLs, keys and identifiers before anything works at all, and
every mismatch surfaces as the same unhelpful failure.

What I expected to be hard

Going into 1 June, I thought the difficulty of this project was the protocol —
signatures, key rotation, the security model, getting the cryptography right.

Some of that has been hard. But the protocol is a written specification with a right
answer; if you read it carefully you converge on it.

The part I did not budget for is the one this whole first stretch has actually turned
on: getting the work into a shape somebody else can be confident about. That is not in
any specification, and it is not something I understood until I had done it wrong.

Next: week 1, and actually writing some code.

Week 5: Identity Is Not an Email Address

Akanksha Trehun — Fri, 07 Aug 2026 14:15:14 +0000

This week produced the single most important line of the project so far, and a decision
I would reverse four days later. It also took a detour into a completely different
feature, which turned out to be a better use of time than it sounds.

The claim you must not trust

The commit is
fix(lti): key 1.3 identity on validated sub, not the email claim.

Here is the problem. When a launch arrives, the id_token contains claims about the
user — a subject identifier (sub), usually a name, and often an email address. The
natural way to sign somebody in is to take that email and look them up:

user = User.find_by(email: payload["email"])

That is what my POC did, and it is wrong in a way that took me a while to see, because
it works perfectly in every test you would think to write.

The token's signature proves the platform sent it. It does not prove the platform
verified anything inside it. The email claim is whatever the LMS has in its user record
— self-asserted, frequently unverified, sometimes editable by the user in their own
profile settings.

So if a CircuitVerse account exists with the email maintainer@circuitverse.org, and
somebody can get an LMS to emit a launch with that email claim, matching on email hands
them that account. The token is valid. The signature checks out. And they are signed in
as somebody else.

The fix is to identify people by the sub claim, which is the platform's own stable
identifier for that user and is not user-editable, scoped to the deployment it came
from:

User.find_or_create_by!(provider: "lti", uid: "#{deployment.id}:#{payload['sub']}")

The scoping matters as much as the choice of claim. Two different institutions can both
have a user with sub of 12345. Without the deployment prefix, those two people
collide into one CircuitVerse account.

Email still gets used — when provisioning a brand new account, we have to put something
in the email column. But it is used as an attribute of a user we have already
identified, never as the thing that identifies them. That distinction is the whole
lesson: authentication data and profile data are different, even when they arrive in
the same signed envelope.

The companion commit, fix(lti): return 401 for tokens missing required claims, comes
from the same place. If sub is missing, there is no identity to key on, and the right
answer is to reject the launch rather than fall back to something more convenient.

The cookie I weakened

The other commit from this week is
Add Canvas placements to tool config and SameSite=None session cookie, and I want to
write about it honestly because I undid half of it the following week.

The problem is real. When the platform POSTs the id_token back to CircuitVerse, that
is a cross-site POST — the request originates from Canvas's domain and lands on
ours. Browsers do not send SameSite=Lax cookies on cross-site POSTs. That is the
entire point of SameSite.

I had stored the login state in the session. So when the launch came back, the session
cookie was not sent, the session was empty, and the launch failed with no state to
check against.

The fix I reached for was to set SameSite=None on the session cookie, which makes the
browser send it on cross-site requests. It worked immediately.

It is also a change to how every cookie in the application behaves, made to serve one
endpoint. Every page on CircuitVerse would have a session cookie that browsers are
willing to attach to cross-site requests, weakening a default that exists specifically
to blunt CSRF — for a feature that is off by default and used by a small fraction of
users.

I did not see it that way when I wrote it. I saw a blocked feature and a config flag
that unblocked it. Seeing it required asking a different question: not "does this make
the launch work" but "what else does this change, for people not using this feature at
all?" More on how I fixed it next week.

The other half of the commit has aged better: Canvas placements in the tool
configuration document. Placements are how a tool declares where it wants to appear in
the LMS — course navigation, assignment selection. It is the difference between a tool
an admin can register and a tool an instructor can actually find.

The detour: subgroups

Midweek I switched to something unrelated: subgroups within a group, so an instructor
can split a class into smaller teams. Commits
feat(groups): add self-referential subgroups data layer and
feat(groups): subgroup management UI, controller and API scoping.

The design decision worth recording: a subgroup is just a Group with a
parent_group_id. That is it. No new model, no parallel hierarchy.

The alternative was a dedicated Subgroup model. It looks cleaner on a diagram and it
is much worse in practice, because assignments, membership, grades, notifications and
authorization policies are all written against Group. A new model means every one of
those systems needs to learn about a second kind of container, and every one of them is
a place to forget. A self-referential association means all of that machinery works
unchanged, and the entire feature is a nullable foreign key plus scoping.

Why work on this at all mid-project? Partly because it had been asked for. But the
honest reason is that I was waiting on review for the LTI work, and I had learned the
week before that pushing on a branch nobody has agreed to review does not move anything
forward. Having a second track meant review latency stopped being dead time.

What I would tell myself

Two things.

The signature does not vouch for the contents. A signed token proves who sent it,
not that what it says is true. Everything inside still needs to be evaluated on whether
the sender had any business asserting it.

"It works" is where you start asking questions, not where you stop. The
SameSite=None change worked on the first try. Working was exactly what stopped me
looking at it.

Next week: undoing the cookie change properly, and two pull requests getting closed on
the same day.

Week 4: Rebuilding From the Spec (and Dropping the Gem)

Akanksha Trehun — Fri, 07 Aug 2026 14:11:20 +0000

After a week with nothing to show, this one produced a lot: the LTI 1.3 infrastructure
rebuilt from the specification rather than from other people's example code, a
dependency added and then removed again, and the three security checks that make a 1.3
launch trustworthy written as three separate, named things instead of one blob.

Starting with the gem

I had opened #7510 the
previous week to add lti-advantage 0.1.0, and I had a separate issue
(#7509) tracking it. My
assumption was the ordinary one: this is a well-specified protocol, somebody has
written the gem, I should use the gem rather than hand-rolling security code.

That assumption is usually right. It was not right here, and the version number was the
clue I ignored. 0.1.0 is not a version that has been through much contact with
production.

When I started wiring the rebuilt launch against it, the shape of the problem became
clear. The gem gave me some convenience wrappers around things ruby-jwt already does
well, and did not give me the parts that are actually hard: resolving a platform's
public key by kid from its JWKS endpoint, handling key rotation, binding a token to a
specific deployment. Those I was going to write regardless.

So I was adding a dependency, in the authentication path, that I would still have to
write the security-critical code around. That is the worst of both: a supply-chain
surface without the benefit.

By the end of the week I had reversed it. Two commits tell that story —
build(deps): restore ims-lti for the LTI 1.1 launch path and
build(deps): drop unused lti-advantage gem. CircuitVerse keeps ims-lti for the
existing 1.1 path, which still has real users, and 1.3 gets built directly on
ruby-jwt, which is mature and which I understand.

The lesson I want to keep: "there's a gem for it" is a hypothesis, not a conclusion.
Check what it actually does before you build on it, especially in an auth path. The
cost of finding out late is that you have already designed around it.

The three checks

The main work of the week was the commit
fix(lti): enforce state, nonce, and deployment binding on 1.3 launch. In the POC, all
of this had been one function that either returned a user or didn't. Pulling the three
defences apart and naming them individually changed how I thought about each.

State. The state parameter is a value the tool generates when it starts the login
and checks when the launch comes back. Without it, anyone can POST a token at your
launch endpoint and you have no idea whether you ever asked for that login. It is the
CSRF defence for the handshake.

Nonce. The tool generates a nonce, sends it in the authorization request, and the
platform copies it into the id_token it returns. When the token comes back, the nonce
must match the one issued. This ties the token to this login attempt. Without it a
token captured once could be presented again later.

Deployment binding. This is the one I had missed entirely in the POC, and the one
reading the spec properly surfaced. A platform is identified by an issuer, a client ID,
and a deployment ID. Every one of those platforms signs its own valid tokens. So a
token can be perfectly valid — correct signature, unexpired, well-formed — and still be
from a completely different institution's Canvas than the one that started this login.
The token has to be bound to the deployment the login was initiated against, or a valid
token from platform B can be presented in a session opened for platform A.

It is the kind of hole you do not find by testing, because every test you write by hand
uses one platform. You find it by reading the spec and asking what each field is for.

Identity, and a bug I created for myself

Two smaller commits this week were about actually signing the user in, and both came
from things breaking.

fix(lti): confirm LTI 1.3 provisioned users so sign_in succeeds — CircuitVerse uses
Devise with the :confirmable module, so a newly created user has to have a
confirmation timestamp before they can be signed in. When CircuitVerse provisions an
account from a launch, the platform has already authenticated that person; there is no
email round-trip to wait for. So provisioning sets confirmed_at at creation. Obvious
in hindsight, and it took a while to see, because the failure looked like the sign-in
silently doing nothing.

fix(spec): stub JWKS HTTP request in LTI 1.3 launch tests — the launch fetches the
platform's public keys over HTTP. My tests were really trying to make that request.
Stubbing it made the suite fast and deterministic, and it forced me to be explicit
about what the JWKS response actually looks like, which paid off later when I came to
handle key rotation.

There was also a housekeeping commit,
fix(lti): add missing schema migration and resolve all rubocop offenses. Not
interesting, except as a reminder that "it works" and "it is ready for someone else to
look at" are different states.

Writing tests against forgeries

The other shift this week was in how I write tests for this. My instinct had been to
test the happy path thoroughly and add a couple of failure cases.

For authentication code that is the wrong ratio. The happy path is the case an attacker
does not care about. What matters is every way a token can be wrong: signed with the
wrong key, signed with no key at all, signed with a symmetric algorithm when we expect
an asymmetric one, expired, wrong issuer, wrong audience, right issuer but wrong
deployment, missing the subject claim, replayed nonce.

Each of those is a test that fails loudly if I ever weaken the validator. That framing —
the test suite as a set of attacks the code has to survive, not a set of features it has
to have — is the thing I have found most useful to internalise, and it is what made the
validator work later in the project reviewable in isolation.

Where this leaves the week

The protocol layer exists again, built from the spec, with the three defences separated
and named, no unnecessary dependency in the auth path, and a test suite that mostly
consists of things going wrong.

What it does not have yet is a shape a reviewer can accept. It is still one branch with
everything on it. That problem is still ahead of me, and it is the one that closed my
POC.

Next week: the email address a platform sends you is not proof of anything, and I
weaken a cookie in a way I will have to undo.

Week 3: The Week Nothing Merged

Akanksha Trehun — Fri, 07 Aug 2026 14:10:25 +0000

What I had built

The project is upgrading CircuitVerse's LMS integration from LTI 1.1 to LTI 1.3
(issue #7405). LTI is the
standard that lets a tool like CircuitVerse live inside Canvas or Moodle: a student
clicks an assignment in their course, and they land inside CircuitVerse already signed
in, with their grade flowing back to the gradebook.

CircuitVerse currently speaks LTI 1.1, which authenticates a launch with an OAuth 1.0
signature over a shared secret. Canvas has deprecated that for new installations. LTI
1.3 replaces it with OpenID Connect and signed JWTs.

At the start of week 2 I opened #7488,
titled [POC] Feat/lti 1 3 upgrade. It was the whole thing. Migrations for a new
deployments table, a JWT validator, an OIDC login endpoint, a rewritten launch, key
management, a JWKS endpoint, tool configuration, user provisioning, and a rewritten
test suite. It worked. I had a real Canvas container talking to a local CircuitVerse
and a real user landing signed in.

It was closed the next day.

Sitting with that

My first instinct was that this was a communication failure — that if I had explained
the design better, or written a longer description, it would have gone differently. I
spent a chunk of this week drafting exactly that: a better writeup of the same pull
request.

Somewhere in the middle of writing it I opened the diff and tried to review it as if
someone else had sent it to me. That was the moment it clicked.

The change touched authentication. It auto-provisioned user accounts. It added a code
path that signs somebody in based on a token that arrived from an external server. To
approve it, a maintainer would have to hold all of that in their head at once and be
confident that no part of it was wrong. Not "probably fine" — confident, because the
failure mode is somebody signing in as somebody else.

I could not have reviewed it myself, and I wrote it.

That is not a communication problem. No description makes a change like that
reviewable. The size is the problem, and a better cover letter would only have made
it more persuasive without making it more correct.

The thing I had actually gotten wrong

I had been treating the pull request as a delivery mechanism — a box you put finished
work in. Get the feature working, put it in the box, hand it over.

For a project where a maintainer has to put their name on the merge, that is backwards.
The pull request is the unit of review, and review is the thing that has to be possible.
Which means the size and shape of a change is not a packaging decision made at the end.
It is a design decision made at the start, and it constrains how you build.

A 2,000 line change that works is worth less than a 150 line change that a reviewer can
be confident about, because only one of them can actually land. Code that cannot merge
is not really finished, no matter how well it runs on my machine.

What I did with the rest of the week

Two smaller pull requests were sitting in the queue and I left them there rather than
poking at them:
#7502, a NameError fix in
the existing 1.1 code, and
#7510, which swapped in an
lti-advantage gem. Both had been open since the previous week.

Instead I went back to the specification. Not skimming for the parts I needed to make
Canvas work — reading it properly, in order, including the parts I had implemented by
copying from other people's tools.

That turned out to matter. There is a real difference between "I made the handshake
succeed" and "I understand what each step of the handshake is defending against." I had
the first. Writing the OIDC login by pattern-matching against blog posts, I could tell
you the state parameter is required. I could not have told you crisply what an
attacker does if you get it wrong.

Going through it deliberately, the shape of the protocol became much clearer. The
handshake has two legs, and each carries a specific defence:

The platform asks the tool to begin a login. The tool generates a nonce and a state, and redirects back to the platform's authorization endpoint.
The platform authenticates the user and POSTs an id_token back to the tool. The tool verifies the token's signature against the platform's published keys, checks the nonce it issued, and only then signs anyone in.

The state proves the launch answers an initiation we started. The nonce ties the
token to that one initiation, so a captured token cannot be replayed. The signature
proves the platform, and only the platform, minted the token. Three separate defences,
and I had implemented all three as one undifferentiated blob of code.

Once I saw them as separate defences, they started to look like separate pieces of
work. Which is, I suspect, the point I was supposed to reach.

What I am carrying into next week

Rebuilding, and rebuilding differently. Not the same code re-uploaded in smaller
chunks, but actually reconsidered — because reading the spec properly turned up things
my POC had glossed over, particularly around binding a token to the specific deployment
that issued it.

The plan is to start from the pieces that stand alone and can be judged on their own
terms. A storage model for platform registrations does not need the launch to exist to
be reviewable. A JWT validator can be unit tested against forged tokens without any
controller at all.

I will be honest that the week felt bad while I was in it. There is a particular
discomfort in having working code and no way to ship it, and in reporting a week with
an empty commit graph. But I would rather find out in week 3 that my approach to
shipping was wrong than in week 10.

Next week: rebuilding the protocol layer, and discovering that the gem I had been
counting on does less than its name suggests.

Week 2: Pull Requests, Rejected Code, and the Art of Not Breaking Things

Akanksha Trehun — Sat, 13 Jun 2026 15:53:27 +0000

GSoC 2026 | CircuitVerse × Canvas LMS LTI 1.3 Integration

If Week 1 was about getting familiar with the codebase and understanding what needed to be built, Week 2 was about learning the hard way that writing code is only half the job. The other half — the messier, more humbling half — is getting that code accepted by the people who actually maintain the project.

This week was full of detours, rejected pull requests, reviewer feedback that stung a little, and a surprisingly frustrating fight with a two-letter word in Ruby. But by the end of it, I had something real to show: a clean, reviewed, and submitted change to CircuitVerse that lays the foundation for the entire LTI 1.3 integration. Let me walk you through it.

A Quick Refresher: What Are We Building?

CircuitVerse is an open-source platform where students can build and simulate digital circuits right in their browser. The project I'm working on aims to connect CircuitVerse with Canvas, one of the most widely used Learning Management Systems (LMS) in universities around the world.

The technology that makes this connection possible is called LTI — Learning Tools Interoperability. Think of it as a universal plug that lets any educational tool (like CircuitVerse) slot into any LMS (like Canvas) so that students can log in once, get assignments, submit work, and have their grades flow back automatically — all without leaving their course page.

There are two versions of this plug: LTI 1.1, which is old and uses a simpler (but outdated) security mechanism, and LTI 1.3, which is newer, more secure, and what Canvas actually recommends today. My job is to bring CircuitVerse fully up to LTI 1.3 standards.

Monday–Tuesday: A Pull Request That Taught Me to Read Diffs

I started the week with what I thought was a solid pull request (PR) — a fix for a bug in CircuitVerse's existing LTI 1.1 grade passback feature. "Grade passback" is the process where CircuitVerse sends a student's score back to Canvas after they complete an assignment.

My PR got reviewed, and the reviewer left two comments that immediately made me wince:

Comment 1: "It seems that the whole schema is sorted. This issue has been fixed upstream."

Translation: I had accidentally included a massive, unrelated change to a file called schema.rb — a file that describes the structure of CircuitVerse's database. When I ran a command to regenerate this file on my laptop, a newer version of the Rails framework (the toolkit CircuitVerse is built on) quietly reordered every single database column alphabetically. This produced a diff with hundreds of changed lines — none of which were related to my actual fix. The reviewer spotted it immediately.

Comment 2: "You are downgrading gem version here."

Translation: I had accidentally rolled back a security upgrade. CircuitVerse uses a library called jwt (JSON Web Tokens — a way to securely verify identity online) that had recently been upgraded from version 2.x to 3.x. My branch had unknowingly reverted it to the older version because of a chain reaction: another library I'd updated (webpush, used for browser notifications) happened to be incompatible with jwt 3.x, pulling the version back down without me realising.

The Fix: I had to undo the schema changes by restoring the file to exactly what the main CircuitVerse codebase had, restore jwt to version 3.2.0, and also downgrade webpush back to the version that didn't cause the conflict. Three files. Careful surgery with git commands. Then push the corrected version, re-commit, and update the PR.

This taught me something I'll carry for the rest of the summer: always check your diff before opening a pull request. A diff is the list of everything your code changes compared to the original. If anything looks unfamiliar or unexpected, it probably shouldn't be there.

Wednesday: The PR I Had to Close

After fixing those issues and updating the pull request, I got some harder news: the PR had to be closed. The grade passback code I'd written depended on an old library (ims-lti) that used LTI 1.1's way of doing things — OAuth 1.0, an older form of authentication. The problem was that several other files in the project also depended on that same library, and changing it was causing things to break in places I hadn't touched.

It felt frustrating. But my mentor pointed me in the right direction: before fixing the grade passback flow, I needed to first upgrade the underlying library itself. That meant replacing ims-lti with something modern that could handle LTI 1.3 properly.

Wednesday–Thursday: Reviewing Someone Else's Pull Request

While I regrouped, I was asked to review another PR that had been submitted — a Dependabot update (an automated tool that suggests library upgrades) proposing to bump ims-lti from version 1.2.9 to 2.3.7.

This was a useful exercise. Looking at what changed between the two versions, I spotted that:

The 2.x version had removed support for the OAuth library entirely — the same one that LtiScoreSubmission (the grade passback code) depended on
A class called IMS::LTI::ToolProvider, which is what the controller uses to verify a student's identity when they launch CircuitVerse from Canvas, simply doesn't exist in 2.x

Merging this PR would have silently broken every LTI launch and every grade submission. I wrote up a review explaining this and recommended the PR be held until the LTI code was properly migrated to 1.3. The PR was not merged.

Reviewing other people's code with a critical eye is a skill in itself, and this was good practice.

Thursday: Syncing With the Main Codebase (A Surprisingly Tricky Task)

Before writing any new code, I needed to make sure my local copy of CircuitVerse was up to date with the changes the main team had been making. This process is called "fetching upstream" — pulling in changes from the official CircuitVerse repository.

It should have been simple. It wasn't.

Git (the tool developers use to track code changes) threw an error about corrupted branch references — essentially, some branch names in the CircuitVerse repository contained spaces in their names, which git wasn't expecting. These bad references were blocking the entire fetch operation.

The fix involved tracking down these broken references, deleting them, and then fetching again. Once that worked, I had a new problem: a merge conflict. The main codebase had changed the jwt library version (to 3.2.0), while my local copy still had the older pin (2.10.3). Git didn't know which one to keep, so it stopped and asked me to decide.

I chose the upstream version (3.2.0) — the right call, since that's the one the maintainers had intentionally upgraded to. I also removed a manually-added entry for a library called faraday (used for making HTTP requests) since it was already included indirectly through other libraries and didn't need to be declared explicitly.

There was also a leftover reference to a submodule (a separate mini-repository embedded inside CircuitVerse) that I'd already removed in an earlier session. The merge picked it back up; I removed it again. After all of that, the sync was complete.

Friday: Finding the Right Gem — A Detective Story

With the codebase up to date, it was time to research the actual replacement for ims-lti. The library I'd been asked to migrate to is called lti_advantage.

Here's where it got interesting. There are two different things with very similar names:

lti_advantage (version 0.0.3) — published on RubyGems (the standard place Ruby libraries are shared), authored by an individual developer, with no publicly accessible source code and almost no documentation.
lti-advantage (version 0.1.0) — embedded directly inside Canvas LMS's own codebase, maintained by Instructure (the company that builds Canvas), with full source code, tests, and comments linking to the official LTI standards.

Since the entire point of this integration is to work with Canvas, using the library that Canvas itself uses was clearly the right call. The Canvas version is battle-tested, actively maintained, and built to the exact same LTI 1.3 specification we're implementing.

I updated the Gemfile (the file that lists all libraries a Ruby application depends on) to point to Canvas's version of the gem, directly from the Canvas GitHub repository.

Friday Evening: The Two-Letter Word That Cost Me an Hour

After setting up the Gemfile, I ran a quick test to verify the library had loaded correctly. Instead of a confirmation, I got a wall of red error text.

The culprit? The word it.

In Ruby 3.4 (released late 2023), it was introduced as a new shorthand inside code blocks — a way to refer to the current item being processed without naming it explicitly. The Canvas team had adopted this syntax in their codebase.

But CircuitVerse runs on Ruby 3.2.2. In that version, it isn't a special keyword — it's just an undefined method name. So when the library tried to load, Ruby 3.2.2 hit the word it and said: "I have no idea what this is."

The solution was to find the specific point in Canvas's git history just before this syntax was introduced — a commit from March 2025, before the Canvas team upgraded their Rubocop linting tool to support Ruby 3.4 style. By pinning our Gemfile to that specific historical commit, we get the full functionality of the library without the Ruby version incompatibility.

After making that change, the verification check finally printed what I needed to see:

0.1.0
LtiAdvantage::Messages::ResourceLinkRequest

The library was in, working, and ready.

Wrapping Up: 793 Tests, 0 Failures

With the new library loaded, the last step was making sure I hadn't accidentally broken anything else in the process. I ran CircuitVerse's full test suite — 793 individual automated tests covering models, controllers, API endpoints, background jobs, and more.

793 examples, 0 failures.

Every part of the existing application still worked exactly as before. The only test excluded from this run was the one specifically for LTI — which I already knew would fail, because it still references the old library. Rewriting that test is part of next week's work.

I created a clean pull request with a single, focused commit describing exactly what changed and why, linked it to the issue (#7509) I'd opened for the work, and submitted it.

What I Learned This Week

Read your diffs. Every line in a pull request should be there intentionally. Unexpected changes are usually a sign something went wrong.
Library upgrades are never just library upgrades. Every dependency has dependencies of its own, and changing one can quietly shift others.
Reviewing code is as valuable as writing it. Catching a breaking change before it merges is just as important as shipping a feature.
Version numbers matter — down to the commit. Pinning a library to a specific historical commit felt overly cautious at first, but it was the only correct solution given the Ruby version gap.
A clean pull request with one clear purpose is worth far more than a large one with many. My first PR of the week was rejected partly because it accidentally carried in unrelated changes. The PR at the end of the week had exactly one commit, one purpose, and zero noise.

Next week: I start the actual code migration — replacing the old LTI 1.1 authentication logic with the new lti-advantage library's APIs, rewriting the tests, and wiring up the full OIDC launch flow that Canvas LTI 1.3 requires.

The foundation is set. Time to build.

GSoC 2026 · Week 1 — What Happens When a Student Clicks "Open Assignment"?

Akanksha Trehun — Sat, 06 Jun 2026 17:46:44 +0000

Testing the LMS–LTI integration in CircuitVerse

A behind-the-scenes look at debugging a silent integration — and what it taught me about the gap between code that exists and code that works.

Project: CircuitVerse · Week: 1 · Focus: Testing & fixing the LMS–LTI assignment workflow

TL;DR

In my first week, I tested the full LMS–LTI flow end to end — a student opening an assignment from Canvas, building a circuit in CircuitVerse, and a teacher grading it back in Canvas. On the surface the feature looked complete. In reality, four interconnected bugs were silently breaking the handoff. Here's how I found and fixed each one.

#	Symptom	Root cause	Fix
1	Student hit a login page	Session was never established after launch	Add `sign_in(@user)`
2	Student landed on the wrong page	Redirect pointed at the group home, not the project	Redirect to `user_project_path`
3	Teacher couldn't grade	Grading form hidden until deadline passes	Allow past deadlines for testing
4	Grade showed `0` in Canvas	Feature flag off, missing LTI session, `maxPoints = 0`	Enable flag, launch via Canvas, set max points

First, some context: what is LMS–LTI?

LMS stands for Learning Management System — the software your university uses to manage courses, post assignments, and track grades. Canvas, Moodle, Google Classroom, and Blackboard are all examples.

LTI stands for Learning Tools Interoperability — an industry standard that lets an LMS talk to an external tool like CircuitVerse, so students don't need separate accounts or a second login. In theory:

A student clicks a link inside Canvas and is transported directly into CircuitVerse, identity already known.
The teacher grades the work from Canvas.
The score flows back automatically.

In practice, making that seamless handoff actually work is where things get interesting.

Setting up the test

Before any real testing could happen, I needed two systems running side by side and talking to each other. So I set up:

A local Canvas instance and a local CircuitVerse instance.
A test course in Canvas, with a test student and a test teacher enrolled.
An LTI assignment configured to point at CircuitVerse.

With everything in place, I logged in as the student and clicked the assignment link.

Bug 1: the student ended up on the login page

The first screenshot told the whole story. Instead of landing in CircuitVerse on the assignment, the student was redirected to /users/sign_in — CircuitVerse's standard login page.

The LTI handoff itself had worked. Canvas had sent all the right information to CircuitVerse:

Who the student was
Which course they were in
Which assignment they were opening

CircuitVerse read that information, found the matching user, and even created a blank project for the student to fill in. But it never told CircuitVerse's authentication system that the student was now logged in.

Think of it like a hotel. The front desk checked your reservation, confirmed your identity, and handed you a room key — but forgot to actually activate the key. Every door you try still says "access denied."

The fix was a single line in the code that handles student LTI launches:

sign_in(@user)

Adding this before showing the student their assignment established the session properly. After this fix, the student landed authenticated and ready.

Bug 2: the student landed on the wrong page

With authentication fixed, the student was now signed in — but being sent to a course overview page with no obvious path to their actual assignment. The intermediate "please wait" page CircuitVerse shows during the handoff was opening a new browser tab pointing at the group's home page, not the student's specific work.

The fix was conceptually simple: redirect the student straight to the project that was auto-created for them during the launch.

# Before: took the student to the course home page
group_path(@group)

# After: takes the student straight to their project
user_project_path(@user, @project)

Now when the student's browser opens the new tab, they land on their own project page with a clear "Launch Simulator" button waiting for them.

Bug 3: the teacher could not grade

With the student flow working, I switched to the teacher's perspective. The teacher launches the same LTI assignment from Canvas, lands on the assignment management page, and can see the student's submission — the circuit they built — in a preview panel.

But there was no grading form. Nowhere to enter a score.

This one required reading the code rather than guessing. The grading form is deliberately hidden until the assignment's deadline has passed:

def can_be_graded?
  mentor_access? && assignment.graded? && (assignment.deadline - Time.current).negative?
end

The last condition — negative? — means the deadline must be in the past. My test assignment had a deadline set a week in the future.

The logic makes sense for real classrooms: you don't want teachers accidentally grading before students have finished submitting.

There was also a secondary problem: the date picker on the assignment edit form had a minDate restriction that prevented selecting any past date — so even if you knew the workaround, the UI would reset your choice.

Both restrictions were removed for the editing flow, allowing a past deadline for testing. Once the deadline was in the past, the grading form appeared immediately.

Bug 4: the grade did not appear in Canvas

This was the most layered problem of the four, and the most instructive.

After the teacher submitted a grade of 68 in CircuitVerse, I went to the Canvas gradebook expecting to see 68. Instead, it showed 0.

A grade of zero when you entered 68 is never a simple problem.

I pulled the Rails server logs to see exactly what happened on submission:

POST "/grades"
Parameters: {"grade"=>{"project_id"=>"15", "assignment_id"=>"19",
             "grade"=>"68", "remarks"=>"average"}}
...
Completed 200 OK

The grade was saved successfully in CircuitVerse — but there was no outgoing HTTP request to Canvas anywhere in the log. The code that should have sent the grade back was never reached.

Three conditions had to be true simultaneously for the grade passback to fire:

A feature flag called lms_integration had to be enabled. CircuitVerse uses feature flags to toggle capabilities without deploying new code. This one was off by default. Running Flipper.enable(:lms_integration) in the server console switched it on.
The teacher had to have launched via Canvas LTI before grading. The passback code checks session[:is_lti] — a marker that says "this session started from an LTI launch." Logging into CircuitVerse directly never set it. The fix: always initiate grading from Canvas by clicking "Load LTI test in a new window."
The Canvas assignment had zero maximum points. LTI sends scores as a decimal between 0 and 1 — so 68 out of 100 becomes 0.68. Canvas multiplies that by the assignment's max points:

With max points 0 → 0.68 × 0 = 0
With max points 100 → 0.68 × 100 = 68 ✅

After resolving all three, the Canvas gradebook finally showed 68 out of 100 for the test student.

What made this hard

None of these bugs announced themselves loudly:

The server returned success codes.
Pages loaded.
No errors appeared on screen.

The student reached CircuitVerse — just not authenticated. The grade was saved — just not forwarded. The grading form existed in the code — just not rendered.

This is the particular difficulty of integration testing: two systems each behaving correctly on their own, but the handoff between them silently failing. The only way to catch it is to walk through the entire experience from beginning to end, as an actual user would.

The lesson is simple but easy to forget:

A feature is not done when the code is written. It is done when a real person can use it from start to finish without needing to know what is happening underneath.

The moment it worked

After all of the above, I went back to Canvas, clicked the LTI assignment as the teacher, entered a grade of 68, and reloaded the gradebook.

It showed 68 out of 100.

That number, small and unremarkable on its own, represented a complete round trip:

A student identity handed from Canvas to CircuitVerse
A circuit built and saved
A grade entered by a teacher
A score carried back to where the course lives

What's next

The workflow works. Now the real work begins — upgrading it from LTI 1.1 to the more secure and capable LTI 1.3.

Thanks for reading my Week 1 update. More to come as the LTI 1.3 migration gets underway. 🌸