mathtrail-standalone

Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

Every change lands as an ordinary commit on main through a pull request, and the whole history is public — the repository is the work in progress, not a drop of
finished releases. Releases are cut from that history rather than the other way round: https://github.com/MathTrail/mathtrail-standalone/commits/main

Repository on GitHub, which uses git. git is distributed.

Each release carries a unique semantic version, worked out by the release workflow and stamped into the binary at link time, so a running instance reports exactly which release it is: https://github.com/MathTrail/mathtrail-standalone/releases

Every release is a git tag of the form vMAJOR.MINOR.PATCH, created by the release workflow at the commit the checks passed on: https://github.com/MathTrail/mathtrail-standalone/tags

No release notes fileThis is a single service, not a library reused elsewhere, and it is delivered continuously: a merge to main is deployed within minutes, and nobody chooses which version to run. Releases exist as a record of provenance — signed binaries whose certificate records the workflow and commit that produced them — rather than as something users upgrade between: https://github.com/MathTrail/mathtrail-standalone/releases found.

No publicly known vulnerability has ever been fixed in this project's own code, and release notes are N/A for the reason above.

Bug reports go to the issue tracker: https://github.com/MathTrail/mathtrail-standalone/issues — how to report is described in https://github.com/MathTrail/mathtrail-standalone/blob/main/CONTRIBUTING.md. Security faults go privately instead, through https://github.com/MathTrail/mathtrail-standalone/security/advisories/new

GitHub issues: https://github.com/MathTrail/mathtrail-standalone/issues

The repository is new and no bug report has been submitted yet, so there is none left unacknowledged; every report that arrives gets an answer, as CONTRIBUTING.md and SECURITY.md both state.

No enhancement request has been submitted yet. CONTRIBUTING.md says plainly what will be declined and why, so a request gets a straight answer rather than silence.

Every report and every answer stays public and searchable: https://github.com/MathTrail/mathtrail-standalone/issues?q=is%3Aissue

Published in SECURITY.md, which GitHub also surfaces in the repository's Security tab: https://github.com/MathTrail/mathtrail-standalone/blob/main/SECURITY.md

Private reporting is the only channel offered: https://github.com/MathTrail/mathtrail-standalone/security/advisories/new — the thread stays private until the finding is resolved, and an advisory can be published from it. SECURITY.md asks reporters not to open a public issue for anything exploitable.

No vulnerability report has been received yet, so there is no response time to measure. SECURITY.md states what a reporter can expect: an acknowledgement and a fix as time allows, with no SLA promised that one maintainer cannot keep.

One command rebuilds everything from source: just build, and just docker-build for the image that ships. The recipes are in https://github.com/MathTrail/mathtrail-standalone/blob/main/justfile and the checks run the same ones on every pull request.

The Go toolchain, just as the task runner, and Docker — nothing else, and every version is pinned exactly: https://github.com/MathTrail/mathtrail-standalone/blob/main/justfile

Go, just and Docker are all FLOSS, and so is every dependency: the licence list is generated from the dependency graph and the checks fail on anything outside MIT, BSD-2, BSD-3, Apache-2.0 and ISC — https://github.com/MathTrail/mathtrail-standalone/blob/main/THIRD_PARTY_LICENSES

Go's standard testing package, with the whole suite run by one command — just test, or just ci-test with the race detector and coverage, which is what the pull request checks run. How to run it is in https://github.com/MathTrail/mathtrail-standalone/blob/main/CONTRIBUTING.md#setting-up

go test ./... — the standard way for Go, wrapped in just test only to add the flags the checks use: https://github.com/MathTrail/mathtrail-standalone/blob/main/justfile

87.5% of statements overall and 95.6% in the package that carries the content, measured on every run and reported to Codecov. Beyond line coverage: property tests state the invariants and let the library hunt for the input that breaks them, fuzz tests cover everything that parses input from outside, and a change that drops below 90% coverage of the lines it touches cannot be merged.

Every pull request runs the whole set before it can be merged: tests with the race detector, golangci-lint with gosec, CodeQL, govulncheck, a secret scan of the entire history, a licence check and a vulnerability scan of the runtime image — https://github.com/MathTrail/mathtrail-standalone/blob/main/.github/workflows/ci.yml

The policy is written down and enforced by the checks: tests come with the change, and a pull request that drops below 90% coverage of the lines it touches cannot be merged. A new check is not considered covered until its test has been seen to fail with the check switched off — https://github.com/MathTrail/mathtrail-standalone/blob/main/CLAUDE.md#tests

The most recent substantial change — the content of the binary, with its catalogs, reference tasks and loader — arrived with 95.6% coverage of that package, including property tests for the invariants and table-driven tests for every way the content can be broken: https://github.com/MathTrail/mathtrail-standalone/tree/main/content

Stated in the contribution instructions under "What a change has to satisfy": https://github.com/MathTrail/mathtrail-standalone/blob/main/CONTRIBUTING.md#what-a-change-has-to-satisfy

golangci-lint with a committed configuration, well past its defaults: gosec, errorlint, gocritic, gocognit, revive, depguard and more, plus go vet with every analyser enabled — https://github.com/MathTrail/mathtrail-standalone/blob/main/.golangci.yml

A single finding fails the checks and blocks the merge, so there is no backlog of warnings to live with. The standing rule is that a finding is answered by changing the code; accepting one is a last resort and carries a written reason in the decision log — https://github.com/MathTrail/mathtrail-standalone/blob/main/docs/decisions.md

Deliberately strict: the linter denies whole packages where they do not belong, caps cognitive complexity at the same ceiling the static analysis uses, and forbids the two logging calls through which a whole structure could reach a log line — a service for children may log aggregates and nothing else. Exactly one finding in the repository is marked as accepted, and it is marked in place with its reason.

The design is written down before it is built, and it applies the principles the criterion lists. Least privilege: the service asks Google only for openid and drive.file, the per-file scope that reaches nothing it did not create. Minimal attack surface and no stored secrets: the service is stateless, keeps no database and no disk, and the child's profile lives in the parent's own Drive. Defence in depth: tokens are sealed with per-purpose subkeys so one kind can never be presented as another, and the answer to a task stays encrypted until the child has answered. Trusted inputs are named as such: the one field a person writes and a model reads is carried as data inside a delimited block, never as instructions, and the rule that decides the task never reads it — https://github.com/MathTrail/mathtrail-standalone/blob/main/docs/architecture/02-auth.md

The threat model and the countermeasures are listed per risk in the same document: a leaked sealing key answered by rotation with two live keys, a replayed or swapped token answered by purpose-bound additional data, prompt injection through the one human-written field answered by making it structurally powerless, and every input that arrives from a chat model treated as untrusted and fuzz-tested. Injection into a database and unsafe memory are absent by construction: there is no database, and Go is memory-safe.

Only published, reviewed primitives: SHA-256 for the identifier of the embedded instructions, TLS for every connection, and — specified and about to be implemented — XChaCha20-Poly1305 with HKDF-SHA256 for everything the service seals. Nothing is invented here: https://github.com/MathTrail/mathtrail-standalone/blob/main/docs/architecture/02-auth.md

This is a maths coach, not a cryptography project: it calls Go's standard library and golang.org/x/crypto, and implements no primitive of its own. Sign-in is delegated to Google entirely, so no password is ever handled.

Everything cryptographic comes from Go's standard library and golang.org/x/crypto, both FLOSS under a BSD licence, and the licence check fails the build on anything outside the permissive list: https://github.com/MathTrail/mathtrail-standalone/blob/main/THIRD_PARTY_LICENSES

256-bit keys with 192-bit nonces, fixed in the design rather than configurable, so a weaker length cannot be selected at all — a stronger guarantee than being able to disable one. TLS is terminated by Google's frontend with its own modern defaults.

No broken algorithm anywhere: SHA-256 for the identifier of the embedded instructions, AEAD for everything sealed, and no interoperable protocol forcing an old primitive on us. MD5, SHA-1, DES and RC4 appear nowhere in the code or in its dependencies' code paths.

SHA-256 and AEAD only. The sealing design deliberately avoids the family of mistakes around nonces: XChaCha20-Poly1305 takes a 192-bit random nonce, which is large enough that several instances with no shared state can pick one at random without coordination — https://github.com/MathTrail/mathtrail-standalone/blob/main/docs/architecture/02-auth.md

Every connection is TLS with forward secrecy, terminated by Google's frontend in front of Cloud Run. The project negotiates no key agreement of its own: what it seals is sealed at rest with a key ring it holds, not with a session key.

No password is ever stored, or even seen: the parent signs in with Google, and the service keeps only what it needs to call Drive on their behalf — sealed, never on disk, and never between requests.

crypto/rand for everything that must be unpredictable: key material, nonces and the random identifiers in the sealed tokens. math/rand appears only where randomness is not a security property — shuffling generated input inside a test — and the linter's gosec checks would fail the build on the confusion between the two.

Distribution channels use HTTPS exclusively. [osps_br_03_02]

Everything travels over HTTPS: the repository and the releases from GitHub, the service on mcp.mathtrail.app and the site on mathtrail.app. Release artifacts also carry a Sigstore bundle, so a download can be checked against the certificate that records which workflow and which commit produced it, not only against the transport.

Nothing is fetched over plain http anywhere: every download in the build refuses a protocol downgrade, on itself and on redirects. Checksums are not trusted on their own — SHA256SUMS ships with its own signature, and every dependency is pinned: Go modules by version and the checksum database, container images by digest, GitHub Actions by commit SHA.

There is none: govulncheck runs on every pull request and fails on a known vulnerability in code the service actually reaches, and Trivy scans the runtime image at high and critical severity. Dependabot proposes updates weekly, and a bump is a pull request that changes a pinned version and nothing else.

None has been reported yet. The machinery to act fast is already in place: a merge to main is deployed within minutes, so a fix reaches production the moment it is merged, and the checks above stop a vulnerable dependency from getting there in the first place.

No credential has ever been committed, and nothing relies on remembering that: gitleaks scans the entire history on every pull request, shallow clones are refused so a key removed later is still seen, and secrets live in Secret Manager and reach the service through its environment. The one deployment value kept out of the files is the billing account id, and it arrives from the environment for the same reason.

Three tools on every pull request, and a release comes from a commit that passed them: golangci-lint with about twenty analysers, CodeQL with the security-extended queries, and SonarCloud — https://github.com/MathTrail/mathtrail-standalone/blob/main/.github/workflows/ci.yml

gosec inside the linter looks for the usual Go faults — insecure randomness, hardcoded credentials, unsafe file paths — and CodeQL follows values across functions and files, which is the part a single-file linter cannot do.

The standing rule is that a finding is answered by changing the code; accepting one is a last resort and carries a written reason. The first full sweep changed real things rather than being marked away: every download now refuses a protocol downgrade, the development image no longer runs as root, and the deployment identity holds a role of five permissions instead of a ready-made one of sixty — https://github.com/MathTrail/mathtrail-standalone/blob/main/docs/decisions.md

On every pull request and every push to main, plus a weekly CodeQL run so that a query set which grows between commits is still applied to code nobody happened to touch.

Two kinds of it run before anything is released: go test -race on every run, which is dynamic instrumentation for data races, and Go's built-in fuzzing over everything that parses input arriving from outside. Property tests add a third kind — the test states an invariant and the library generates inputs looking for one that breaks it.

Go is memory-safe, and the binary is built with CGO disabled, so no C is linked into it.

The tests run with the race detector on, which is the assertion mechanism that matters here, and it is a test-only build flag — the shipped binary is built without it. On top of that, the content of the binary is verified at startup in the production build itself: a catalog or a reference task that could not be used stops the process rather than reaching a child.

Nothing found so far, and nothing can be left unfixed: a failing test or a race blocks the merge, so a fault of this kind never reaches main in the first place.