Skip to content

docs: refresh Cloud verification guides - #49

Open
hanakannzashi wants to merge 14 commits into
mainfrom
codex/refresh-verification-docs
Open

docs: refresh Cloud verification guides#49
hanakannzashi wants to merge 14 commits into
mainfrom
codex/refresh-verification-docs

Conversation

@hanakannzashi

Copy link
Copy Markdown

Summary

  • Reorganize Cloud verification around model, gateway, TLS, response signatures, and image provenance.
  • Document client nonces, signer matching for load-balanced endpoints, and same-connection TLS SPKI checks.
  • Add a fail-closed image-provenance guide, including clear handling for missing records and HTTP 404s.
  • Align related private-inference copy with the verification guides.

Validation

  • mint validate
  • mint broken-links

Closes #44

@thisisjoshford thisisjoshford left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tysm for the updates here @hanakannzashi ! Below is an agent review and agree we should resolve 1 & 2 ( having NVIDIA verification endpoint/example and including JS/Python snippets rather than just curl commands) - the rest are nice to haves IMO. I'm also working to update the verification example repo as mentioned in 3 but feel free to skip that part as we can do a follow-up PR.


  1. The NVIDIA verification endpoint is gone. The old model page had the full POST https://nras.attestation.nvidia.com/v3/attest/gpu example with a sample EAT response. The new pages only say "verify with the applicable NVIDIA verification service" — a reader can no longer discover where to send nvidia_payload. Suggest restoring the NRAS URL + minimal request/response example in reference/quote-nonce-signer.mdx (the "Verify GPU evidence" section is the natural home).

  2. All JS/Python examples were removed. The old pages had worked examples for attestation requests, request/response hashing (with a real fixture), and ethers/eth_account signature recovery. The new pages are curl-only, and signature verification is prose ("recover the Ethereum EIP-191 signer") with no code. Since #44 asked for stale examples to be updated, dropping them entirely feels like the wrong direction — even one JS + one Python snippet per flow would do.

  3. Link to the verification example repo was dropped. The old model/chat pages pointed to near-examples/nearai-cloud-verification-example (just updated for the current API, incl. signature_kind handling); only nearai-cloud-verifier survives, in one reference page. Please restore it alongside the verifier link — it's the easy on-ramp, the verifier is the complete implementation.

Non-blocking

  1. signature_kind inference guidance now contradicts the API reference. cloud-api's OpenAPI text says legacy signatures "can still be distinguished structurally" (3 parts = model TEE, 2 = gateway); cloud-api/response-signatures.mdx says "do not infer it from the shape of text". The stricter stance is defensible, but the two sources should agree — worth a follow-up to align the API reference.

  2. cloud/verification/provenance.mdx is orphaned — not in docs.json nav and nothing links to it, and since the path didn't exist before there are no external inbound links either. Wire it in or drop it.

  3. Consider docs.json redirects instead of stub pages for the old chat/model/gateway/tls URLs. The stubs work (hidden pages still resolve), but redirects would keep four near-empty pages out of search and llms.txt.

  4. The "why gateway signatures happen" explanation disappeared. The old chat page explained the gateway signs streamed responses because it rewrites chunks for usage accounting. Someone seeing signature_kind: "gateway" on a streamed completion now has no "why" anywhere — one sentence in cloud-api/response-signatures.mdx would cover it.

Couldn't verify live (plausible, just noting): the error_code/message 200-unavailable signature shape, and the E2EE "unsupported rather than re-routed" behavior.

@think-in-universe

Copy link
Copy Markdown
Contributor

@hanakannzashi I think we can hold on the merge of this PR until https://github.com/nearai/verifiable-ai-sdk/pull/1 is merged and the verifiable-ai-sdk is released.

We probably need to re-implement https://github.com/nearai/nearai-cloud-verifier after the verifiable-ai-sdk is published, and also update the NEAR AI docs accordingly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Refresh outdated Cloud verification docs

3 participants