docs(sdk): scope the evidence-options security rationale to the artifact

[mchmarny]

Summary

Corrects the security rationale on Config.EvidenceAttestationOptions(), added
in #2542, which asserted a blanket rule the same function contradicts four lines
later.

Motivation / Context

#2542's godoc justified keeping NoSign/Full un-derived with a general
principle: both "WEAKEN a run", and a checked-in file that weakens a run is a
supply-chain downgrade. The same function projects PlainHTTP and InsecureTLS
from that same committed document, and those weaken a run too. So the stated
boundary was not the boundary the code implements.

Found by running the five-lens review process retroactively on #2542 after it
merged. make qualify, golangci-lint, -race, coverage and mutation testing
all passed on that PR and none of them can catch a rationale that contradicts
its own function body.

Fixes: N/A
Related: #2542, #2245

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Build/CI/tooling

Component(s) Affected

• CLI (cmd/aicr, pkg/cli)
• API server (cmd/aicrd, pkg/server)
• Recipe engine / data (pkg/recipe)
• Bundlers (pkg/bundler, pkg/component/*)
• Collectors / snapshotter (pkg/collector, pkg/snapshotter)
• Validator (pkg/validator)
• Core libraries (pkg/errors, pkg/k8s)
• Docs/examples (docs/, examples/)
• Other: SDK facade godoc (pkg/client/v1)

Implementation Notes

No behavior change. Comments and markdown only. The config-settable
plainHTTP/insecureTLS capability is inherited unchanged from
EvidenceAttestationSpec and the CLI's existing mapping; this PR corrects what
the docs claim about it.

The distinction the rationale now draws is the artifact versus the hop.
NoSign/Full alter the artifact's own trust properties and stay
command-line-only. plainHTTP/insecureTLS configure transport to a registry
the same document already names in push, which is why EvidenceOptions carries
them while the bundler's options do not — MakeBundle never reaches a registry.
This connects to the rationale already stated for spec.bundle.registry
(go-library.md line ~921), which the #2542 section failed to reference.

Two claims are now stated as structural facts, and both were source-traced
rather than asserted:

1. PlainHTTP/InsecureTLS reach only the OCI transport — never
   SignStatement's Fulcio/Rekor call, never predicate or redaction
   construction.
2. Neither path reads the subject digest back from the weakened hop.
   Emit-and-push binds the digest computed locally during packaging, before any
   push begins (pkg/oci/push.go, pkg/oci/reference.go). Signing an
   already-pushed artifact resolves it at pull time instead
   (SignExistingOptions.Artifact, "resolved at pull time"), but the pull is
   content-addressed and cross-checked for equality at
   pkg/evidence/verifier/fetch.go:183-187, which fails closed.

The second point is deliberately split by path. An earlier draft of this PR
stated the local-packaging mechanism as covering both, which is false for the
aicr evidence sign leg — the end security property holds there, but via a
different mechanism.

Also states the residual risk rather than implying safety. A committed
plainHTTP/insecureTLS does weaken that hop, and it widens the threat model:
redirecting push needs a malicious document, whereas downgrading TLS on a
destination the operator believes is protected only needs someone on the network
path.

Declined, recorded here rather than silently: the text says
"EvidenceOptions and SignOptions carry these". No type named SignOptions
actually carries those fields — the real ones are EvidencePublishOptions (SDK)
and SignExistingOptions (CLI). But that shorthand is pre-existing at
go-library.md:921, bundle.go:83 and config.go:353; correcting it only in
the new sentence would leave three existing uses inconsistent. Worth a separate
cleanup.

One table row also moves: EvidenceAttestationOptions() now sits with the other
spec.validate.* derivation instead of after the spec.snapshot.* row, matching
the order of the "does and does not carry" subsections below it.

Testing

go build ./...
golangci-lint run -c .golangci.yaml ./pkg/client/v1/...
go test ./pkg/client/v1/...
make check-docs-mdx check-docs-mdx-parse

All pass. No test changes: the diff is comments and markdown, so there is no new
behavior to cover and coverage is unchanged.

Risk Assessment

• Low — Isolated change, well-tested, easy to revert
• Medium — Touches multiple components or has broader impact
• High — Breaking change, affects critical paths, or complex rollout

Rollout notes: Comments and markdown only; no code paths, signatures, or
generated artifacts change. N/A for migration.

Checklist

• Tests pass locally (make test with -race)
• Linter passes (make lint)
• I did not skip/disable tests to make CI green
• I added/updated tests for new functionality — N/A, comments and markdown only
• I updated docs if user-facing behavior changed
• Changes follow existing patterns in the codebase
• Commits are cryptographically signed (git commit -S) — GPG signing info

[github-actions]

🌿 Preview your docs: https://nvidia-preview-fix-2542-evidence-transport-rationale.docs.buildwithfern.com/aicr

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 2590382d-c373-451c-af5b-ee682333a320

📥 Commits

Reviewing files that changed from the base of the PR and between 949f672 and 740a678.

📒 Files selected for processing (2)

• docs/integrator/go-library.md
• pkg/client/v1/config.go

Included review availability: Your plan provides up to 12 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Updated EvidenceAttestationOptions() documentation in the Go client and integrator guide. The documentation distinguishes artifact-level NoSign and Full controls from transport-level plainHTTP and insecureTLS settings. It also describes local and pull-time digest pinning, mismatch handling, and the related transport threat model. The configuration derivation table order was updated.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Merge Risk: ⚪ Minimal · up to 740a6

This PR clarifies existing security documentation without changing code behavior, APIs, or generated artifacts. No actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: almaslennikov

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the documentation change and accurately scopes the security rationale to the artifact.
Description check	✅ Passed	The description is directly related to the documentation-only changes and explains the artifact-versus-transport distinction, scope, rationale, and validation.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/2542-evidence-transport-rationale

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Coverage Report ✅

Metric	Value
Coverage	84.2%
Threshold	80%
Status	Pass

Coverage Badge

![Coverage](https://img.shields.io/badge/coverage-84.2%25-brightgreen)

Coverage unchanged by this PR.