fix(miner): add optional token verification to init

[taillred]

Summary

Add an opt-in --verify-token flag to gittensory-miner init that makes one authenticated GitHub API call, reports the returned scopes on success, and fails fast on invalid or under-scoped tokens. Default init behavior is unchanged when the flag is omitted.

Closes #5171.

Supersedes #5419.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves (Closes #5171).

Validation

• git diff --check
• npm run build --workspace @jsonbored/gittensory-engine
• npm run typecheck
• npm run test -- test/unit/miner-init-verify-token.test.ts test/unit/miner-laptop-init.test.ts
• Added a regression test for an explicitly empty x-oauth-scopes header
• npm run actionlint
• npm run test:coverage
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate

If any required check was skipped, explain why:

• The repo’s full coverage command is dominated by the global suite threshold when run on a tiny slice, so I validated the affected files directly with the repo typecheck and targeted tests, and fixed the review-blocked empty-header edge case that Codecov/patch was still flagging.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.

Notes

• doctor remains untouched and still makes no network calls.
• init only performs a GitHub request when --verify-token is passed.
• The x-oauth-scopes handling now distinguishes an omitted header from an explicitly empty one and rejects the latter.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.41%. Comparing base (aeb2244) to head (ba029ab).
⚠️ Report is 31 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5422   +/-   ##
=======================================
  Coverage   94.40%   94.41%           
=======================================
  Files         550      550           
  Lines       44119    44166   +47     
  Branches    14632    14632           
=======================================
+ Hits        41652    41699   +47     
  Misses       1792     1792           
  Partials      675      675           

Flag	Coverage Δ
shard-1	43.71% <0.00%> (-0.30%)	⬇️
shard-2	34.02% <20.40%> (-0.63%)	⬇️
shard-3	32.24% <100.00%> (+0.63%)	⬆️
shard-4	31.36% <6.12%> (-0.06%)	⬇️
shard-5	33.01% <6.12%> (-0.14%)	⬇️
shard-6	43.58% <0.00%> (+0.23%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/gittensory-miner/lib/cli.js	100.00% <ø> (ø)
packages/gittensory-miner/lib/laptop-init.js	98.26% <100.00%> (+1.20%)	⬆️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-12 18:23:30 UTC}

8 files · 2 AI reviewers · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
Adds an opt-in --verify-token flag to init that makes one authenticated GitHub /user call, checks classic OAuth scopes when GitHub reports them, and fails fast with a clear message on invalid/under-scoped tokens; default init behavior is unchanged and remains offline (verified by the 'makes no network calls' test still passing). The implementation is careful: timeout via AbortController, blank-token handling, empty-scopes-header edge case, and JSON/human output both covered. `runInit` and its one caller in bin/gittensory-miner.js are correctly converted to async/await, and console.error goes to stderr on failure so exit code 1 is meaningful.

Nits — 5 non-blocking

• packages/gittensory-miner/lib/laptop-init.js:158 — the 5000ms timeout is a magic number; consider naming it e.g. `const defaultTimeoutMs = 5000;` alongside the other module constants.
• packages/gittensory-miner/lib/laptop-init.js:151-247 — `verifyGithubToken` is a fairly large, branchy function (external analysis flags ~19 branches); consider extracting the response-classification logic (scope/empty-header/error checks) into a small helper for readability.
• The classic-scope allowlist (`repo`, `public_repo`) will never match fine-grained PATs, which don't emit `x-oauth-scopes` at all — that's handled gracefully (treated as valid with 'did not report classic OAuth scopes'), but it does mean a fine-grained PAT missing actual repo write access won't be caught by this check; worth a one-line doc caveat since the flag's promise is 'fail fast on invalid or under-scoped tokens'.
• No test covers a non-JSON (parse-failure) GitHub response body, though the code path (`payload = null`, falls back to HTTP status) is simple enough that this is low risk.
• Consider extracting the four post-response classification branches (scopesHeaderPresent-empty, missing-repo-scope, error, success) into a small pure function `classifyTokenResponse(response, payload)` to shrink verifyGithubToken and make each branch independently testable.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#5171
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 53 registered-repo PR(s), 34 merged, 1 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	luckydicer; Gittensor profile; 53 PR(s), 1 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence. LLM value judgment: moderate — The PR closes an open, maintainer-linked issue (#5171) with a narrow, well-tested, opt-in CLI feature that doesn't touch the default offline init path, matching the repo's preference for narrow operator-facing work over speculative feature surface.

Linked issue satisfaction

Addressed
The PR adds an opt-in --verify-token flag to init that makes a single GET /user call, reports scopes/login on success and a clear error on failure, leaves default init behavior and doctor's no-network contract untouched, and ships comprehensive unit tests covering success, failure, empty-header, timeout, and no-flag/no-network-call paths.

Review context

• Author: luckydicer
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 53 PR(s), 1 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.