api

A public git repository on GitHub: https://github.com/altnovatrail/api

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

Every pull request, its branch and its commits are public before they reach main and a release.

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

Every release has a unique version vX.Y.Z, tagged on its commit. The release workflow numbers it, and nobody tags by hand; releases are immutable, and a ruleset forbids moving or deleting a tag v*. https://github.com/altnovatrail/api/blob/main/.github/workflows/release.yml

Versions are MAJOR.MINOR.PATCH: each release is the next patch of the current line, 0.1 since the first release, v0.1.0, and a new line starts with the pull request that deserves it, one that breaks those who deploy api.

Each release is the git tag vX.Y.Z, which the release workflow creates together with the release.

A release follows every merge to main that changes what a release is built from, and its notes on GitHub list the pull requests it brings, linked to each pull request's description: an English summary of what changed and why. https://github.com/altnovatrail/api/releases

No publicly known vulnerability of api has been fixed in any release. If one is, its release notes will name it and link its GitHub security advisory. A fix of a dependency's vulnerability is named by the commit that raises the dependency, as the one that raised go-jose to v4.1.6, past three advisories of v4.1.4, before v0.1.4: https://github.com/altnovatrail/api/commit/e8a754a

Bugs are reported as GitHub issues, through the bug report form that GitHub shows for every repository of the organization: it asks what happened, what was expected, how to reproduce it on synthetic data and in which commit, release or tag. https://github.com/altnovatrail/api/issues/new/choose

GitHub issues track individual reports. The project's own planned work is in its work plan, RUN.md.

No bug report has been submitted yet; the maintainer answers each report in its issue.

No enhancement request has been submitted yet; the maintainer answers each request in its issue.

GitHub issues are public, permanent and searchable: https://github.com/altnovatrail/api/issues?q=is%3Aissue

The security policy, which every repository of the organization shares, says how to report a vulnerability: privately, through GitHub's private vulnerability reporting. https://github.com/altnovatrail/api/security/policy

Private vulnerability reporting is enabled: a report goes over HTTPS to the maintainers and opens a draft advisory that only they and the reporter see. https://github.com/altnovatrail/api/security/advisories/new

No vulnerability has been reported in the last six months.

just build builds the binary with the go command, static, without cgo and with -trimpath, and just release-files <version> builds a release's files: the binaries for linux/amd64 and linux/arm64, the Dockerfile a deployment builds the image by, the licenses the binaries come with and SHA256SUMS. The commit and its time come from a file that git archive writes, so that a build of the same commit gives the same bytes. The release builds them in the toolchain stage of .devcontainer/Dockerfile, from a base image pinned by digest and tools pinned by version and SHA-256. https://github.com/altnovatrail/api/blob/main/justfile

The go command builds, vets and tests the code, with govulncheck and go-licenses run by it, Docker builds the environment and the image, and just runs every recipe.

All FLOSS: Go (BSD-3-Clause), Docker Engine (Apache-2.0), just (CC0-1.0), govulncheck (BSD-3-Clause), go-licenses (Apache-2.0), embedded-postgres (MIT), which runs PostgreSQL (the PostgreSQL License) for the tests, and cosign (Apache-2.0), which signs the release's files.

An automated test suite in this repository, under Apache-2.0, run by the go command: 537 tests on 2026-11-12, the database's among them on a real PostgreSQL that embedded-postgres runs, with no Docker, and the tests over the test vectors of spec's parts. just ci-test runs them all; the README says so, and CI runs them on every pull request and on main, while its job Modules runs the test of the first app's path on the packages of the pinned release of modules: https://github.com/altnovatrail/api/blob/main/.github/workflows/ci.yml

just ci-test runs every test with the race detector, by go test ./..., the standard way for Go; the README names it.

On 2026-11-12 the tests covered 95.16% of the lines of the code on main (42e94be), as Codecov counts them: https://app.codecov.io/gh/altnovatrail/api

GitHub Actions runs every check and every test on each pull request and on each commit to main, and main takes a pull request only when they pass; the job Withdrawals checks the newest release of modules against the pinned one once a day. CI also builds the image as a deployment builds it from a release and as it builds from the source, and checks it on a PostgreSQL of its own.

RULES.md, the rules every NovaTrail repository shares, which this repository's CLAUDE.md imports: code comes with its tests, so a pull request that adds or changes what code does adds or changes the tests of its automated suite. A pull request merges only when at least 90% of its changed lines are covered (codecov/patch, a required check). https://github.com/altnovatrail/spec/blob/v0.16.3/RULES.md

The latest major changes came with their tests: an open lesson run kept from the engine while its next segment cannot begin (https://github.com/altnovatrail/api/pull/64); the modules that teach an anchor skill on the skill map (#63); the quota of platform AI (#59).

The rule on tests is in RULES.md, which the organization's CONTRIBUTING.md names as the rules every contribution follows, and the pull request template that GitHub shows for every repository of the organization asks for it: code comes with its tests. https://github.com/altnovatrail/.github/blob/main/.github/pull_request_template.md

gofmt and go vet check the Go code on every pull request, as just ci-lint runs them in the required check Go / lint, and the scripts of the recipes run with set -euo pipefail. SonarCloud analyses the code on every pull request, and its quality gate is a required check. https://sonarcloud.io/summary/new_code?id=altnovatrail_api

A finding of SonarCloud or CodeQL is fixed in code before the next task starts; marking one false is a last resort, with the reason written down. SonarCloud's current findings are public: https://sonarcloud.io/project/issues?id=altnovatrail_api

SonarCloud's quality gate, Sonar way, holds a merge when new code falls below rating A for reliability, security or maintainability, leaves a security hotspot unreviewed or duplicates more than 3% of its lines, and a finding below the gate is fixed in code too: the three findings shell:S7688 on the script of the image check, which came with the first release's pull request (#28), were fixed by the next one (#30). None is open.

The maintainer designs for least privilege, fail-safe defaults and a small attack surface. Every request with a token passes its checks before any learner's data: the sign-in service's ID token, its revocation, and the account's rights over the profile, kept by OpenFGA in api's own process. AI providers are reached only through tutor, whose requests have no field for the learner's or the account's identifiers; the picture sent for checking lives only in the request's memory, and a program, module-kit, decides every verdict. The log writes only the events and fields of a closed table: no identifier, IP address or content of the work. A secret comes from the environment or from a file outside any git working tree, and a deployment refuses a service account's key and takes the service's own account. A connection to the database must verify the server's certificate, a message over 11 MiB is refused, and every request has its time limit. The production image is the static binary on a distroless base, as nonroot, with no shell. Every workflow starts with a read-only token, a job gets only the write it needs, the workflows hold no secret, and main has no bypass. The decisions behind these, in Russian, are in https://github.com/altnovatrail/api/blob/main/docs/decisions.md

For this kind of software, a web service that keeps learners' data, children's among it, under an adult's account and sends their work to AI providers, the maintainer counters: broken access control (the checks of the token, its revocation and the account's rights over the profile come before any learner's data, and a deletion asks for a fresh sign-in); SQL injection (every value reaches the database as a parameter of pgx); guessing of secrets (the PIN of the section for adults is kept as argon2id, and five wrong PINs in 15 minutes close its input for 15 minutes; an invite code holds 80 random bits, and the database keeps its SHA-256 alone); cross-origin requests (CORS answers the exact origin of app alone, and a request is authorized by its bearer token, never a cookie); resource exhaustion (a message over 11 MiB is refused before it is decoded, and every request and connection has its time limit); learners' data in logs (a closed table of events and fields, with no identifier, IP address or content); instructions hidden in a learner's work for the model (a program decides every verdict, and the model's words reach the learner only after the leak check and the form check); path traversal and tampering in the packages of modules (an archive is unpacked in memory, files of the package alone and no links, and every file is held to the chain of SHA-256 digests from the pinned index, whose signature CI checks); and supply-chain tampering (actions pinned by commit, downloads checked against pinned SHA-256 sums, Go modules held by go.sum).

api implements no cryptography. It relies on published and reviewed algorithms and protocols: argon2id (RFC 9106) for the PIN of the section for adults and the fingerprints of the requests that carry a PIN or an age; SHA-256 (FIPS 180-4) for what the database keeps of an invite code, the fingerprints of other requests and the digests of the packages of modules; TLS, through Go's crypto/tls, for every connection to the database, the sign-in service and the AI providers; the RS256 signatures of the sign-in service's ID tokens, which the Firebase Admin SDK checks; and cosign, keyless, through Sigstore, whose certificates and signatures are ECDSA (FIPS 186-5), for the signatures of its release and of the index of modules it takes.

It calls Go's standard library — crypto/rand, crypto/sha256 and crypto/subtle, and crypto/tls through pgx and net/http — and golang.org/x/crypto/argon2; the Firebase Admin SDK checks the ID tokens, and the shared release workflow calls cosign to sign the release's files. It never implements cryptography itself.

Go's standard library and golang.org/x/crypto (BSD-3-Clause), the Firebase Admin SDK for Go (Apache-2.0) and cosign (Apache-2.0) are FLOSS.

api has no cryptographic keys of its own and sets no key length: its TLS connections take the defaults of Go's crypto/tls, and the keys that sign the ID tokens are the sign-in service's.

No broken algorithm is used: argon2id and SHA-256, and TLS as Go's crypto/tls negotiates it.

No algorithm with known serious weaknesses is used: argon2id and SHA-256, never SHA-1 or MD5, and TLS with the defaults of Go's crypto/tls.

api implements no key agreement; its TLS connections are Go's crypto/tls.

api stores no passwords: the adult signs in with Google through Firebase Auth. The one secret it checks itself, the PIN of the section for adults, is kept as an iterated hash with a salt of its own: argon2id with the minimum parameters of OWASP's Password Storage Cheat Sheet, m=19456 KiB, t=2, p=1, a salt of 16 bytes from crypto/rand for each PIN, and a comparison in constant time. https://github.com/altnovatrail/api/blob/main/internal/argon/argon.go

The salts of argon2id, the invite codes and the codes of the requests for a parent's consent come from crypto/rand, Go's cryptographically secure generator; api generates no keys or nonces otherwise.

api is delivered over HTTPS only: the repository, its releases and their files. Releases are immutable, GitHub attests each one with its files, and each file is signed with cosign, its bundle beside it in the release. spec's just release-verify checks a file against its bundle and Sigstore's trust root and against everything the certificate names: who signed, at whose call, on which branch and of which commit; whoever deploys builds the image around a binary only once that check has accepted it.

No hash is retrieved over HTTP: every SHA-256 sum is pinned in the file next to its version, the index of modules is held by the digest modules.json pins and each package by the chain of digests from it, and every download of the devcontainer is restricted to HTTPS, redirects included (curl --proto =https --proto-redir =https).

No vulnerability is open: Dependabot has no open alert, govulncheck finds none, and Scorecard's Vulnerabilities check scores 10. The three advisories of go-jose v4.1.4, one of them high, which the Firebase Admin SDK brought in, were fixed in two hours by v4.1.6, which v0.1.4 shipped (https://github.com/altnovatrail/api/pull/34), and GO-2026-5932 of golang.org/x/crypto, which Scorecard reported, in three days by v0.59.0 (#59).

Dependabot security updates are on, govulncheck is a required check (Go / vuln), and a finding of Scorecard, CodeQL or SonarCloud is fixed in code before the next task starts; one that no change can close stays open, with its reason written down.

gitleaks scans the whole history on every pull request and on main, and GitHub's secret scanning and push protection are on. The workflows hold no secret: coverage goes to Codecov with a short-lived OIDC token. The keys and connection strings of a run on the dev projects stay out of the repository, in a Docker volume, and the binary refuses a secret's file inside a git working tree.

CodeQL, with the security-extended queries, analyses the Go code and every workflow, and SonarCloud analyses the repository, on every pull request and on main. Both are required checks, CodeQL for each of its languages, and a release comes only after CI passes on main.

CodeQL's security-extended queries and SonarCloud's security rules look for common vulnerabilities, such as injection and path traversal, and govulncheck for the known vulnerabilities of the Go vulnerability database in the code and the standard library it reaches (Go / vuln, a required check).

The ruleset of main holds a merge on any CodeQL alert at error level or of high severity and above, and on SonarCloud's quality gate; every finding is fixed before the next task starts.

On every pull request and on every commit to main.

Go's native fuzzing varies the inputs of every reader of foreign input: the invite code a person types, the page token app gives back, the path and query of any request, the name of a package in the path of a file, the archive of a package from a release and modules.json, each with the invariants of what it accepts (func Fuzz… in internal/invite, internal/learning, internal/server and internal/packages). Their seeds and testdata/fuzz run on every pull request in the required check Go / test, which runs the whole suite with the race detector; just fuzz fuzzes each test in turn, and a task that changes a reader runs it. The first run, 2026-11-13, five minutes a test, found that a request for the root of a subtree was redirected with its path and query, that a page token of a time before 4713 BC reached the database, and that an archive of a sparse file unpacked a few KB to 500 MB; all three were fixed with the tests, and the sparse archive stays in the corpus. The README names the recipe: https://github.com/altnovatrail/api#build-and-run

api is Go, a memory-safe language, built without cgo, and its code imports no package unsafe.

Go has no assert statement. The code checks what it reads — its configuration, the deployment's facts, each package by its digests, each request by the contract — and refuses it with a named error, always on; the tests check every result with the testing package's t.Error and t.Fatal and run with the race detector.

A failing test fails a required check, and the pull request cannot merge until it passes. The first fuzzing, 2026-11-13, found three faults in released code, none of them a vulnerability: they were fixed, with their tests, in the pull request that brought the fuzz tests.