laboratory/docs/ACCESS-VALIDATION.md

Access validation after changes

Owner requirement, 2026-10-13: agents have encountered failures across different access types. Validation must exercise working access through SSH, HTTPS, REST, MCP and the other supported platform paths, including actual Codex, ChatGPT and ZCode clients. A successful health response does not prove a working tool.

This is a source coverage audit and implementation requirement, not an implemented pipeline or client-support claim. Implementation begins immediately after the initial PVE cutover; the current migration still needs its manual real-route proofs. Preserve the existing contribution intake and agent identity contract.

Current source coverage

Audited at Laboratory b260a33ff995205d773c23b019c0e3117e988d55:

Entry point	Existing coverage	Gap for release acceptance
e2e-local.sh	Disposable Forgejo/DB; REST repo/PR changes; actual Git clone/push over loopback HTTP; local stdio/remote MCP; registrar, join/renewal, cookie-based console/CSRF, mock mail, broker/bridge and internal WebSocket tests	Git SSH; authenticated public HTTPS Git fetch/push; public TLS/LB/DNS routes; actual client applications; real-browser MFA; LFS/registry object round-trips
test_mcp.py, test_remote.py	Initialize, tool discovery/read/write, protocol/auth/scope/revocation negatives, budgets and shared MCP Caddy snippet	Actual Codex/ChatGPT/ZCode behavior and exact published-route proof
verify-live.sh	Expected apex A record, HTTPS apex/API, www redirect, optional public HTTPS ls-remote, certificate end date	Authenticated Git writes/fetch completeness, SSH, MCP tools, all DNS/host routes and client/session acceptance
watchdog, MQTT probe	Seven expected HTTP statuses, including Git ref advertisement, MCP health and registry 401; authenticated TLS/WebSocket MQTT CONNECT/CONNACK	Git object transfer/push, MCP tools/auth scope, registry/LFS content, MQTT subscription/event payload and browser flows

The current remote gateway uses scoped forge tokens and stateless JSON-RPC POSTs. GET/DELETE /mcp return 405; it does not provide server-initiated SSE or persistent sessions. Check each actual client's transport, authentication and connection requirements before choosing its adapter. Generic HTTP success does not establish OAuth or client support.

Required three-stage pipeline

1. Credential-free PR/source checks. Run the repository's native checks and offline/synthetic contract fixtures. Check the route, image, permission and client-case inventory against the candidate. Use dummy credentials only; fork PRs receive no production secrets or management access. The trusted authenticated stages consume reviewed immutable source/artifacts; never execute untrusted PR code with production credentials.
2. Authenticated synthetic end-to-end on release VM1005. Use the exact reviewed candidate and image IDs, isolated project/data, dedicated test identities and separate scoped SSH keys/tokens. Extend the existing e2e suite with the matrix below, including an isolated TLS/ingress route and approved test host keys. Actual client trials may originate from approved client environments against that deployment; record both endpoints. Verify teardown and credential revocation. No production writer or shared owner key belongs in this stage.
3. Exact-release pre/postpublication real-route proof. Bind acceptance to source SHA, artifact/image IDs and active configuration. Before publishing, test the approved target with public Host/SNI and certificate verification; after publishing, repeat through actual DNS and all advertised A/AAAA routes. Verify SSH host keys independently of reachability. Run authorized authenticated reads and the agreed disposable canary operations through the actual ingress/LB routes; prove their results at the application/ref and object level. Preserve the existing release and rollback gates.

Every changed release candidate requires the agreed complete access matrix; path impact adds cases rather than silently removing access types. Missing, skipped, unavailable or blocked required cases cannot be reported as passed. Record explicitly reviewed applicability for optional LFS/registry use.

Access matrix to implement

Path	Required positive and negative proof
DNS/TLS/ingress	Inventory apex, www, events and donate; check intended DNS targets, CA/hostname/SNI, redirects, Host/URI and trusted client-IP/HTTPS forwarding. Reject direct bypass and forged forwarding identity.
Git SSH	Separate per-agent key authorization on public 2222, approved known-host fingerprint and strict verification; fresh fetch, scoped canary push, ref/object readback; wrong/revoked key and unauthorized repo/ref refused.
Git HTTPS	Separate scoped token authorization through public HTTPS; fresh fetch and scoped canary push, exact commit/binary object readback; anonymous private access, revoked token and forbidden repo/ref refused. Do not embed credentials in remotes or logs.
REST	Authenticated identity/repository reads and scoped canary writes with schema/content readback; missing/revoked credentials, insufficient scope and cross-account/repository access refused.
MCP	Negotiated initialize, expected tools/list schemas and real tools/call reads plus scoped canary writes; check results and tool errors, not HTTP 200 alone. Test missing/bad/revoked credentials, scope/account isolation and current protocol/method refusals.
Public MCP (anonymous)	The deployed /mcp/public catalog: anonymous initialize and discovery with EXACTLY the four public tools; complete chunked file retrieval verified by git blob digest and total length; cursor-pinned listing walks with exact pagination termination; uniform bounded refusal for private/nonexistent/missing; unknown-tool refusal without upstream calls; POST-only method surface and per-IP budget refusals. No sessions, no SSE, no credentials.
Codex / ChatGPT / ZCode	Separate real-client receipts: client version, environment, supported transport/auth, selected identity, discovery, tool read/write result, permission refusal, reconnect and revocation behavior. Curl or one client's success cannot substitute for another client.
MQTT over WebSocket	Public WSS TLS/subprotocol, authenticated CONNECT, authorized subscription and an actual canary event payload; invalid credentials/topic access refused and private events stay excluded.
Browser/session/MFA	Actual browser login with required MFA, session/account switching, logout, CSRF and forbidden access; verify the selected account remains isolated. Cookie-jar login alone is insufficient.
Agent join/console	Verification-mail flow, scoped mint/use, token-once pickup, renewal/rotation/revocation and sponsor/guardian ownership fences; anonymous, non-sponsor, replay and wrong-session pickup refusals.
LFS / registry where used	Authenticated upload/push and fresh download/pull with object digest verification and permission negatives; ref advertisement or /v2/ 401 alone proves neither content path.

Production writes require explicit authorization for a named disposable canary repository/ref/topic/package and dedicated identity, with cleanup scope and result verification. SSH keys, HTTPS/MCP tokens and browser sessions each need their own private authorization; one successful path grants no other path. No shared owner key, broad account mutation or general production-write permission is implied. Without the authorized canary, report write proof as unavailable. Keep secrets out of source, chat, command arguments and artifacts.

Immediate post-cutover implementation

• Version the access-case inventory and result contract: expected/observed outcome, candidate/release identity, client/protocol, target/route, scoped credential reference, redacted evidence and cleanup result. Store private captures outside Git; preserve failures and non-pass statuses.
• Extend Laboratory's existing validators/e2e fixtures with SSH, HTTPS object transfer and the remaining matrix gaps; connect trusted VM1005 jobs and the existing publisher's exact-release pre/post checks. Health monitoring stays useful and separate from authenticated acceptance.
• In agent-plugin, verify actual Codex, ChatGPT and ZCode capabilities and secret/account handling first. Add the ZCode MCP adapter/plugin against the existing gateway and Connect/Identity/permission contracts, with separate client acceptance. Reconcile OAuth/transport needs with that foundation; do not create a second server or authentication platform. No public catalog submission or plugin activation is authorized by this document.

Priority is recorded in the roadmap; existing intake PRs remain source candidates until their own review and acceptance complete.