Repository navigation
docs: stop claiming the generated config reference covers policy keys - #71
Merged
Merged
Conversation
The go-trust page told readers the generated reference lists "every YAML key ... generated directly from the Go config structs, so it can't drift". It does not cover `policies`: the generator does not descend into PolicyConfig, so the entire policy key space renders as one opaque row, `policies.policies · map[string]*PolicyConfig (object)`. That is the subtree where the hand-written page carries the most detail — service_types, entity_types, allowed_domains, issuer_allowlist, allowed_aaguids and the rest — so pointing readers at the reference for it sent them somewhere those keys do not appear. Scope the claim to server/logging/security/registries, say plainly what is missing, and name the two places that do document policy keys: this page and example/config.yaml in the go-trust repo. Surfaced by sirosfoundation/go-trust#177, which notes the same generator limitation. Teaching the generator to expand PolicyConfig would let this qualification be dropped again. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Sep 28, 2026
leifj
added a commit
that referenced
this pull request
Sep 29, 2026
Independent revalidation of the config-audit fixes from PRs #69/#71 found several remaining bugs the original passes missed, mostly in sections the diffs never touched: go-trust: - Resolution strategy: first_match queries registries in PARALLEL and the first positive decision wins (a race), not a scan in registration order (pkg/registry/strategies.go evaluateFirstMatchFiltered). - X5C enrichment wiring: go-trust PR #177 (merged today) wired all five enrichment keys through config.yaml and closed a client-context bypass. The doc's "silently dropped, must be set via request context" caution was accurate against v0.21.1 but is now stale against current main. vc (SUNET/vc): - issuer.md / api-integration.md: /offers/{scope}/{wallet_id} does not exist (real route is single-segment /offers/:scope; the two-segment form is explicitly tested as gone). - api-integration.md: three leftover POST/GET .../datastore/ calls with a trailing slash (fixed everywhere else in the endpoint table, missed in the request-body examples and a sequence diagram); an orphan code-fence that silently swallowed two headings ("## gRPC Integration" and "### Service Definition") into a fake code block. - issuer.md / deployment.md: a leftover ${OIDC_CLIENT_SECRET} env-var interpolation and a stale github.com/sirosfoundation/vc metadata link (both patterns already fixed elsewhere in the same docs, missed here). - keycloak_issuer.md: an entire "Advanced Configuration" section untouched by either PR, built entirely on the pre-fix issuer.authentication / credential_constructor-era shape: fabricated issuer.credential_policies (role/group-gated issuance, not implemented anywhere), a fabricated multi-provider issuer.authentication.providers list (apigw supports exactly one OIDC provider), a stale SAML example, a stale POST /offers pre-auth call, and an unused KEYCLOAK_CLIENT_SECRET container env var (vc reads only VC_CONFIG_YAML and SSL_CERT_FILE). - token-status-lists.md: the registry's real endpoints are GET /statuslists and GET /statuslists/{id}, not GET /status/{id}; the registry has no /.well-known/jwt-vc-issuer endpoint (that belongs to the credential issuer/APIGW, for a different purpose). - digital-credentials-api.md: a leftover `enabled` (vs. `enable`) table row, and wrong defaults for response_mode, preferred_formats and deep_link_scheme, left inconsistent with the rest of the same file. registry-cli: `serve`'s --base-url has its own empty default (falls back to http://addr:port), not build's https://registry.siros.org default; its JWKS endpoint is /.well-known/jwks.json, not nested under /api/v1/. Independently re-verified (no changes needed): go-trust registry inventory/policy wiring/metrics/endpoints (17/18 checklist items), vc apigw/issuer/verifier config surface against a freshly regenerated CONFIGURATION.md, go-wallet-backend WIA config, and all anchor links on the 17 touched pages (none break Docusaurus's default-warn broken-anchor check). Verified via `make fetch-api-specs && make fetch-config-docs && make fetch-release-notes && pnpm build` (clean build; the release-notes fetch was also needed since a stock `pnpm build` failed on an unrelated, pre-existing broken link into the gitignored release-notes category). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
leifj
added a commit
that referenced
this pull request
Sep 29, 2026
Independent revalidation of the config-audit fixes from PRs #69/#71 found several remaining bugs the original passes missed, mostly in sections the diffs never touched: go-trust: - Resolution strategy: first_match queries registries in PARALLEL and the first positive decision wins (a race), not a scan in registration order (pkg/registry/strategies.go evaluateFirstMatchFiltered). - X5C enrichment wiring: go-trust PR #177 (merged today) wired all five enrichment keys through config.yaml and closed a client-context bypass. The doc's "silently dropped, must be set via request context" caution was accurate against v0.21.1 but is now stale against current main. vc (SUNET/vc): - issuer.md / api-integration.md: /offers/{scope}/{wallet_id} does not exist (real route is single-segment /offers/:scope; the two-segment form is explicitly tested as gone). - api-integration.md: three leftover POST/GET .../datastore/ calls with a trailing slash (fixed everywhere else in the endpoint table, missed in the request-body examples and a sequence diagram); an orphan code-fence that silently swallowed two headings ("## gRPC Integration" and "### Service Definition") into a fake code block. - issuer.md / deployment.md: a leftover ${OIDC_CLIENT_SECRET} env-var interpolation and a stale github.com/sirosfoundation/vc metadata link (both patterns already fixed elsewhere in the same docs, missed here). - keycloak_issuer.md: an entire "Advanced Configuration" section untouched by either PR, built entirely on the pre-fix issuer.authentication / credential_constructor-era shape: fabricated issuer.credential_policies (role/group-gated issuance, not implemented anywhere), a fabricated multi-provider issuer.authentication.providers list (apigw supports exactly one OIDC provider), a stale SAML example, a stale POST /offers pre-auth call, and an unused KEYCLOAK_CLIENT_SECRET container env var (vc reads only VC_CONFIG_YAML and SSL_CERT_FILE). - token-status-lists.md: the registry's real endpoints are GET /statuslists and GET /statuslists/{id}, not GET /status/{id}; the registry has no /.well-known/jwt-vc-issuer endpoint (that belongs to the credential issuer/APIGW, for a different purpose). - digital-credentials-api.md: a leftover `enabled` (vs. `enable`) table row, and wrong defaults for response_mode, preferred_formats and deep_link_scheme, left inconsistent with the rest of the same file. registry-cli: `serve`'s --base-url has its own empty default (falls back to http://addr:port), not build's https://registry.siros.org default; its JWKS endpoint is /.well-known/jwks.json, not nested under /api/v1/. Independently re-verified (no changes needed): go-trust registry inventory/policy wiring/metrics/endpoints (17/18 checklist items), vc apigw/issuer/verifier config surface against a freshly regenerated CONFIGURATION.md, go-wallet-backend WIA config, and all anchor links on the 17 touched pages (none break Docusaurus's default-warn broken-anchor check). Verified via `make fetch-api-specs && make fetch-config-docs && make fetch-release-notes && pnpm build` (clean build; the release-notes fetch was also needed since a stock `pnpm build` failed on an unrelated, pre-existing broken link into the gitignored release-notes category). Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
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
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.
The go-trust page told readers the generated reference lists
It does not cover
policies. The generator does not descend intoPolicyConfig, so the whole policy key space renders as a single opaque row:That is precisely the subtree where the hand-written page carries the most detail —
service_types,service_statuses,entity_types,required_trust_marks,allowed_domains,issuer_allowlist,allowed_aaguidsand the rest — so a reader chasing one of those keys was sent to a page where none of them appear.This scopes the claim to
server/logging/security/registries, states plainly what is missing, and names the two places that do document policy keys: the go-trust page itself, andexample/config.yamlin the go-trust repo. The same edit is applied to the shorter cross-reference intrust/index.md.Surfaced by sirosfoundation/go-trust#177, which independently notes the same generator limitation while wiring the policy enrichment keys through. If that generator is later taught to expand
PolicyConfig, this qualification can be dropped again — worth folding into the item 3/4 tidying tracked in go-trust#176.Verified with the full deploy sequence (
make fetch-api-specs && make fetch-config-docs && make fetch-release-notes && pnpm build) — clean.🤖 Generated with Claude Code