Skip to content

docs: neutralise vendor comparisons in comments - #737

Merged
lakhansamani merged 1 commit into
mainfrom
chore/neutral-wording-in-comments
Aug 1, 2026
Merged

docs: neutralise vendor comparisons in comments#737
lakhansamani merged 1 commit into
mainfrom
chore/neutral-wording-in-comments

Conversation

@lakhansamani

Copy link
Copy Markdown
Contributor

Why

Several comments named other IdP vendors as a benchmark rather than as an
illustration — "what Auth0's required audience parameter and Keycloak's
audience mappers provide", "same as Keycloak default", "competing on lighter
than Keycloak". That framing dates badly (it is wrong the moment another vendor
changes behaviour), and it puts positioning language into source comments where
an engineer wants the reason, not the scoreboard.

Named products are kept — they are genuinely useful for orientation — but only
in example form.

Changes

File Before After
internal/token/auth_token.go "…and what Auth0's required audience parameter and Keycloak's audience mappers provide" explains the consequence directly: one shared audience means a token minted for service A is valid at service B
token_grant_hardening_test.go "Auth0 makes audience mandatory…; this is the equivalent" describes the established shape for the grant, with resource as the standards-track spelling
internal/storage/schemas/trusted_issuer.go "same as Keycloak default" justified by its actual cost — an API round-trip per authentication
MIGRATION.md "Keycloak-inspired four-pillar authorization engine" described by its own role/group/permission shape, noting the model is conventional in enterprise IAM
perf/README.md "competing on 'lighter than Keycloak'" argues from reproducibility: published numbers get benchmarked back at you

Also normalised bare slash-lists to explicit example form so they cannot be read
as claims — (Okta/Entra/ADFS) becomes (e.g. Okta, Entra, ADFS) in
saml_sp.go, oauth_sso.go, scim_endpoint.go, authorize.go and token.go.

Left alone deliberately

  • Interop facts, where the vendor name is the information: the Okta and
    Auth0 doc links in authorize.go, and the CHANGELOG's "(Auth0 compatibility)"
    note on base64url padding tolerance — that is literally why the code exists.
  • CHANGELOG history — a record of what shipped, not something to rewrite.
  • Test fixtures using Okta/Entra as sample IdP names.
  • .claude/research/machine-client-authz-landscape.md — an explicitly headed
    competitive-landscape brief, doing exactly its job.

Verification

Comment- and docs-only. Mechanically confirmed that every changed Go line is a
comment:

git diff -U0 -- '*.go' | grep '^[+-]' | grep -v '^[+-]\s*//'
→ (empty)

go build, make lint-go (0 issues), and the touched packages
(internal/token, internal/storage/schemas, internal/http_handlers) all pass.

Named products now appear only as illustrative examples of a pattern,
never as a benchmark Authorizer is measured against. Comparative
framing dates badly the moment another vendor changes behaviour, and
it belongs in positioning material rather than in source comments.

- Audience-binding comments explain why binding a machine token to its
  target API matters, instead of citing which vendors mandate it.
- Trusted-issuer default is justified by its cost (an API round-trip
  per authentication), not by matching another server's default.
- FGA model described by its own role/group/permission shape.
- Perf checklist argues from reproducibility rather than a footprint
  claim.
- IdP references normalised to "e.g. ..." so they read as examples.

Comment- and docs-only: every changed Go line is a comment.
@lakhansamani
lakhansamani merged commit 89428cb into main Aug 1, 2026
4 checks passed
@lakhansamani
lakhansamani deleted the chore/neutral-wording-in-comments branch August 1, 2026 06:05
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.

1 participant