docs(miner): AMS auth/identity research — hosted login-layer options

[lourincedaging0-commits]

Closes #5217. (Clean resubmit of the closed #5763 — that branch was cut from a stale base and accidentally bundled the already-merged #5216 storage doc; this PR touches exactly one file, the #5217 deliverable.)

A research-spike comparison doc (packages/loopover-miner/docs/ams-auth-identity-research.md) surveying hosted-AMS auth/identity options, grounded in ORB's existing GitHub-App token-broker precedent (src/orb/broker.ts das-github-mirror model, src/orb/oauth.ts self-enrollment) vs the miner's GITHUB_TOKEN-env no-auth baseline.

Compares 3 approaches — (1) GitHub OAuth reusing the self-enrollment + broker (recommended), (2) managed IdP alongside, (3) custom JWT/OIDC — each with security/integration tradeoffs and explicit reuse/replace/alongside notes for the broker's token exchange. Docs-only, non-binding, no code changed (per the issue boundaries).

[superagent-security]

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

[loopover-orb]

Tip

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

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-14 13:02:12 UTC}

1 file · 1 AI reviewer · no blockers · readiness 95/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
Docs-only research spike comparing three hosted-AMS auth/identity approaches against ORB's existing GitHub-App token-broker precedent, correctly scoped to a single new file with no code changes. It explicitly closes #5217 and states it is a clean resubmit avoiding the prior bundling mistake from #5763. The technical claims about `src/orb/broker.ts` and `src/orb/oauth.ts` are consistent with the referenced sibling storage-research doc's conventions and citation style, and the doc is appropriately non-binding/advisory throughout.

Nits — 5 non-blocking

• The doc cites specific line numbers (`broker.ts:8`, `:30`) for the installation_id binding claim but I can't verify those against the actual broker.ts source since it isn't in the diff — worth double-checking they're accurate before merge.
• No explicit pointer to how/where the follow-up maintainer-owned auth design issue will be filed or tracked, unlike the sibling storage doc which at least references Scope local ledger keys by forge host, not bare repoFullName #5563 for the tenant-scoping seam.
• Consider adding a short 'Open questions for the design issue' section (mirroring how the storage-abstraction doc closes with a clear handoff) to make the non-binding handoff to the maintainer-owned issue more concrete.
• If `src/orb/oauth.ts` line references are available, cite them the same way `broker.ts:8`/`:30` are cited for consistency.
• Diff looks like trivial or whitespace-only churn — Reduce whitespace-only or formatting-only churn and keep the diff focused on substantive changes.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#5217, #5763
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 (2 linked issues).
Validation posture	⚠️ 20/25	Preflight is ready, but the PR body does not name the validation run.
Contributor workload	✅ 10/10	Author activity: 0 registered-repo PR(s), 0 merged, 0 issue(s).
Contributor context	❌ No public Gittensor match	lourincedaging0-commits; not a blocker.
Gate result	✅ Passing	No configured blocker found.
Improvement	⚠️ ℹ️ Insufficient signal	risk: low · value: insufficient-signal — Nothing measurable for the structural-improvement analyzers on this PR (e.g. no code files changed). LLM value judgment: moderate — A well-scoped, single-file research doc that directly closes an open issue and grounds its recommendation in concrete existing precedent (ORB's broker/oauth code) rather than speculative design, making it a useful non-binding input to a future auth design decision.

Review context

• Author: lourincedaging0-commits
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Contributor context: Public profile only; not a blocker.
• PR-specific overlap: none found.

Contributor next steps

• Add validation command/output.

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 LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

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