docs: align audit/auth/oidc config reference with code#16
Open
jmasud wants to merge 1 commit into
Open
Conversation
jmasud
force-pushed
the
docs/config-reference-drift
branch
from
ae6dd44 to
75174a5
Compare
3 tasks
jmasud
force-pushed
the
docs/config-reference-drift
branch
from
75174a5 to
f125a1c
Compare
Audit reference page was missing capture_payloads, capture_headers, max_payload_bytes, and max_notifications; redact_keys default listed 7 of the 12 keys applyDefaults actually installs. The example YAML shipped the same 7-key list, so operators who copied it lost five defaults silently (setting redact_keys replaces, doesn't merge). A handful of bool defaults were documented as true but applyDefaults never touches them, so the Go zero-value default is actually false: audit.enabled, portal.cookie_secure, auth.require_for_mcp, auth.require_for_portal. Corrected with notes about what the shipped example/dev/live configs do. oidc.audience was flagged "required when oidc.enabled" but the validator only enforces it when non-empty. Demoted to optional in both reference.md and environment.md. auth.require_for_mcp and require_for_portal are declared but read by nothing in the binary; gating is governed by allow_anonymous and the auth chain. Documented honestly rather than papering over.
jmasud
force-pushed
the
docs/config-reference-drift
branch
from
f125a1c to
ab3b92b
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Sweep of
docs/configuration/reference.mdand friends againstpkg/config/config.goafter the v1.2 follow-ups. Four classes of drift fixed:Missing keys —
audit.capture_payloads,audit.capture_headers,audit.max_payload_bytes,audit.max_notificationswere inconfigs/mcp-test.example.yamlandpkg/config/config.go:152-174but never documented in the reference page.Wrong defaults — four boolean defaults said
truein the reference, butapplyDefaults()never touches them so the Go zero-value default is actuallyfalse:audit.enabledportal.cookie_secureauth.require_for_mcpauth.require_for_portalThe shipped example/dev/live configs all set these explicitly, so this never bites in shipped configs — but the reference was lying about the omit-this-key behavior. Corrected with notes about what each shipped config does.
Wrong required-ness —
oidc.audiencewas flagged "required when oidc.enabled" butpkg/auth/oidc.go:121only enforces it when non-empty (if v.cfg.Audience != ""). Demoted to optional in bothreference.mdandenvironment.md.Honest documentation —
auth.require_for_mcpandauth.require_for_portalare declared inAuthConfigbut read by nothing in the binary; gating is governed byauth.allow_anonymousand the composed auth chain. The reference previously claimed they "gated" endpoints. Now described as advisory with a pointer to what actually does the gating.Example YAML —
configs/mcp-test.example.yamlshipped a 7-keyredact_keyslist whileapplyDefaults()installs 12 keys. Operators copying the example would lose 5 defaults silently because settingredact_keysreplaces rather than merges. Updated to the full 12-key list with a comment about the no-merge behavior.Test plan
mkdocs build --strictsucceedsFollow-up worth a separate PR
auth.require_for_mcp/require_for_portalare dead fields inpkg/config/config.go:129-130. Either wire them up (the test fixtures + example configs imply that was the intent) or delete them. Out of scope here — flagging for triage.