docs: package-wide comment sweep

[paskal]

Package-wide comment sweep. Two scopes in one commit:

1. Drift fixes — pre-existing comments that don't match the code, surfaced by
   running the same audit prompt over the v1 package that originally turned up
   the issues post-fix(avatar): prevent stored XSS via content-type spoofing #290.
2. Trims — the verbose, rationale-heavy docstrings I added in fix(avatar): prevent stored XSS via content-type spoofing #290 cut down to
   API-contract size. Several of those were factually loose; tighter prose has
   less surface to be wrong.

Net 28 files (v1 + v2 mirror). Line count drops by ~30. Doc-only — no symbol
changes, no test changes. Build green, lint clean, go fix ./... clean on both
modules.

Note on overlap with #291: #291 fixed a subset of the security-adjacent
docstrings touched here. This PR covers everything #291 covers plus the wider
package. If this lands first, #291 can be closed; otherwise we rebase.

Drift fixes

avatar/:

• gridfs.go — ID doc claimed it returns MD5 sourced from GridFS; metadata is
  the SHA-1 written at Put time.
• bolt.go, gridfs.go — Put docs and the BoltDB type doc claimed these
  store layers "resize" the image; they copy bytes verbatim. Resize happens
  upstream in Proxy.resize.
• store.go — Migrate doc didn't mention per-avatar Get/Put/Close errors
  are logged-and-skipped, and the returned count is "ids attempted", not "ids
  stored".

provider/:

• oauth1.go — initOauth1Handler godoc and its [DEBUG] log both said
  "oauth2"; function and protocol are OAuth 1.
• service.go — Service.Handler doc said it "returns auth routes"; it
  dispatches login/callback/logout.
• telegram.go — processUpdates claimed to return an offset (no return value);
  checkToken doc described an "address or empty string" return shape but the
  signature is (*token.User, error).
• verify.go — Sender interface doc locked the contract to "send emails",
  contradicting the broader "email, IM, or anything else" comment on
  VerifyHandler upstream. AuthHandler comment was copy-pasted from
  provider/direct.go.
• dev_provider.go — NewDev doc said "for admin user"; it makes the dev
  oauth2 provider, admin role is set separately.

middleware/ and logger/:

• user_updater.go — UserUpdFunc adapter doc said the result "is a
  Handler"; it implements UserUpdater.
• interface.go — Func adapter doc said "Logf calls f(id)"; it calls
  f(format, args...).

token/:

• jwt.go — SendJWTHeader option doc said "instead of cookie"; Set sends
  header and cookie (header path explicitly falls through). Set doc
  referenced a "permanent flag" that doesn't exist in the signature (controlled
  by claims.SessionOnly/Handshake). Get doc oversimplified the XSRF gate
  (skipped when DisableXSRF, method in XSRFIgnoreMethods, or claims carry no
  user). Update/Validate adapter docs said "calls f(id)"; actually
  f(claims) and f(token, claims).
• user.go — HashID inline "or empty" was wrong; an empty val never matches
  reValidSha.

auth.go:

• BasicAuthChecker doc grammar was broken and understated behavior — when a
  checker is set, AdminPasswd is bypassed entirely, not "ignored".
• // peak dev provider typo for "peek".
• AvatarProxy doc was a sentence fragment.

Trims (rationale prose from #290 → API contract)

avatar/avatar.go:

• maxAvatarFetchSize, maxAvatarPixels — dropped the "Telegram caps at 5 MiB"
  / "100 KB declaring 65535x65535 px" rationale, kept the contract.
• Proxy.Put — now describes the identicon fallback (which the old doc didn't
  mention at all).
• Proxy.Handler godoc — replaced the stale "returns token routes" with what
  the function does today.
• Handler inline sniff comment — was claiming "validate the bytes really are an
  image"; it's content-type sniffing against an allowlist on the first
  sniffLen bytes, not a full decode.
• Proxy.resize — split the doc cleanly between metadata-only check
  (DecodeConfig path) and full decode (resize path). Dropped the inline
  example.
• safeImgContentType — kept the allowlist and SVG-excluded note, dropped the
  "future scriptable image/*" defensive rationale.

auth.go:

• withSecurityHeaders — dropped the bullet-list explanation of standard HTTP
  headers. Kept the CONSUMER NOTE (real footgun) but tightened it.

All changes mirrored across v1 and v2.

[coveralls]

Coverage Report for CI Build 26202899073

Coverage increased (+0.03%) to 85.425%

Details

• Coverage increased (+0.03%) from the base build.
• Patch coverage: 3 of 3 lines across 3 files are fully covered (100%).
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	3561
Covered Lines:	3042
Line Coverage:	85.43%
Coverage Strength:	8.31 hits per line

---

💛 - Coveralls