Passport System Architecture

The product is a local-first browser application backed by a public GitHub learning record and a private controller. The lab operates no permanent learner login service, analytics service, or database of student answers.

Content Ownership#

Optional practice is independent of frozen assessment meaning. New required evidence needs a reviewed contract/version/migration; a wording upgrade preserves existing draft and completion semantics.

Repository Boundaries#

IDEALLab/onboarding-IT                         handbook, curriculum, site, exporters
soheylm-passport-sandbox/passport-exercises    public fictional exercises and records
soheylm-passport-sandbox/gh-passport           public launcher releases
soheylm-passport-sandbox/onboarding-control    private authority and operations
username/passport-exercises                    learner-owned public fork

The active deployment profile is platform/deployment.json. Students are not members of either organization.

The source repository runs no GitHub Actions. A separate signed webhook routes same-repository source PR revisions to a bounded workflow in private onboarding-control; this keeps all billed Actions usage in the sandbox organization.

Three Separate Surfaces#

The launcher never mixes a learner's staged practice changes with a Passport submission. It copies only mission-declared synthetic artifacts into the managed transport clone and stages an exact allowlist.

First Contact And Consent#

public static first-contact page
  -> install Git and GitHub CLI
  -> inspect the active GitHub account
  -> sign in or switch only when needed
  -> install gh-passport
  -> gh passport start
  -> local pre-provisioning wizard
  -> choose platform and responsibilities
  -> read and accept the public-content boundary
  -> create/reuse fork, .transport clone, route, branch, and draft PR
  -> open first mission

No fork, branch, PR, or public answer exists before explicit consent. The browser wizard accepts only platform, known responsibility IDs, and the consent boolean.

Resume And Authority#

gh passport open works from any folder because the OS-specific registry stores only the absolute managed transport path. If local state disappears, the launcher reconstructs official progress from the central PR and Check Run. A completed closed, unmerged PR remains resumable.

Current Computer And Rechecks#

gh passport resume restores the existing assessment branch with fast-forward only recovery. It never creates a fork, route or PR, commits, or pushes. Published progress is recovered through the existing exact-SHA controller checks. Unsubmitted local answers and practice files are not synchronized.

The local context exposes computer.platform from the launcher runtime and an allowlist of assigned setup lessons. The protected passport.json platform remains registration metadata; neither it nor the private assignment changes. Instructions and generated practice commands use the current computer's OS. The existing curriculum supports all three operating systems for every mission.

The separate computer-check API runs only Git, Python-environment and SSH-config diagnostics for assigned lessons. It accepts no answers, runs no grading or submission, and writes no attempts, drafts, receipts or official state. SSH configuration checks do not attest a live login. The ordinary assessment API still enforces the current mission and all existing criteria. No data migration or controller-contract change is involved. See the learner recovery procedure.

Event And Assessment Path#

launcher pushes one generated mission submission
  -> public App sends signed pull_request webhook
  -> Cloudflare Worker checks signature, installation, repository, action,
     draft state, branch, base, body size, and SHA
  -> dispatch App starts private assess.yml with PR number + exact SHA
  -> private assignment freezes immutable GitHub IDs and route
  -> isolated container reads exact checkout with no token and no network
  -> controller revalidates the PR SHA
  -> trusted App writes one Check Run and upserts sanitized feedback

A sparse cron scans for dropped events four times daily. It is recovery, not the normal path. Duplicate dispatches are harmless because assignment state, attempt counts, and Check Runs are keyed by exact head SHA.

Trust Checks#

Registration and each assessment validate:

1. active private enrollment and immutable learner/reviewer IDs;
2. official central repository and base branch;
3. PR author, fork ID, direct parent ID, source branch, and draft/open state;
4. canonical route resolved from platform and responsibilities;
5. immutable protected-file hashes and exact submitted SHA;
6. secret scan before parsing or execution;
7. editable-path, size, suffix, and symlink boundaries;
8. exact remote Git-practice PR identity where that competency is assessed.

Untrusted code runs under resource limits in a network-disabled container. No App key, organization token, or learner token enters the checkout.

GitHub Apps#

Use separate least-privilege identities:

• Controller App: installed only on passport-exercises; reads contents and PRs, writes Checks, issues/comments, and PR state.
• Dispatch App: installed only on onboarding-control; writes Actions workflow dispatches and reads metadata.

The dispatch private key exists only as a Cloudflare Worker secret. The controller private key exists only in private onboarding-control. Neither App is installed on unrelated repositories or personal forks.

Completion And Human Work#

automatic and exception_only missions pass from deterministic criteria. exception_only creates attention only when the bounded verifier cannot decide. operational_approval can finish its training check while a real access, classification, or ownership decision remains assigned asynchronously.

On complete training, the controller writes the minimal private record and closes the transport PR without merging. Human review is not a routine Passport bottleneck.

Privacy#

The public record contains GitHub identity, structured choices, booleans, one-way challenge digests, scores, and declared synthetic artifacts. It excludes ETH identifiers, local/NAS paths, job IDs, logs, screenshots, AI transcripts, credentials, and research content. Private control stores identity and status metadata, not answer bodies.