docs(auth): harden pkg/auth Deprecated marker with explicit removal date

[lml2468]

Summary

PR-D1 (server-side Stage D cleanup) of Stage A epic (#428). The PR-A1 shim's Deprecated marker said "six months after this shim was introduced" without giving the actual date — ambiguous when reviewers grep for upcoming removals. This PR pins:

• An explicit removal date (2026-12-22 = 6 months from the alias introduction in PR-A1 refactor(auth): extract modules/auth submodule and deprecate pkg/auth #429).
• A pointer to the migration tracker ([Epic] Refactor authentication subsystem: extract modules/auth and align with unified Octo auth contract (Stage A + D server-side cleanup) #428) so anyone touching pkg/auth in the interim can see who owns the migration.
• A concrete one-line migration recipe in the package doc, so a contributor reading the deprecation warning can act immediately.

Stacked on top of #432 (PR-A4). Base = `refactor/auth-verify-api-key`.

Changes

Comments only — single file (`pkg/auth/aliases.go`). No executable code touched.

Effect on callers

The per-symbol Deprecated lines now show the removal date alongside the redirect, so godoc and the golangci-lint `deprecated` check produce a more actionable warning at every call site. Visible in the diagnostics on the six existing pkg/auth importers (main.go, modules/{group,message,user,qrcode}/api.go, modules/user/api_manager.go).

Testing

• `go build ./pkg/auth/...` — clean
• `go test ./pkg/auth/...` — PASS
• `golangci-lint run ./pkg/auth/...` — 0 issues
• (Docs-only PR; full repo gates from PR-A1 / A2 / A3 / A4 unchanged.)

Checklist

• PR in English
• No code change, only docs
• Conventional Commits

[yujiawei]

Code Review — PR #433 (octo-server)

Scope reviewed: head SHA 9467c018c9bb3942d64fcfdd28cbb426049ae60c, base refactor/auth-verify-api-key.
Change: comments-only edit to a single file, pkg/auth/aliases.go (+33 / −3). No executable code touched.

Verdict: APPROVE

This is a documentation hardening of the pkg/auth deprecation shim: it replaces the vague "six months after this shim was introduced" wording with an explicit removal date, a migration-tracker pointer, and a concrete migration recipe. The change is accurate and improves the actionability of the godoc / deprecated linter output at every call site.

Verification

I checked every factual claim the new comments make against the code at this SHA:

• The six listed callers are correct. main.go, modules/group/api.go, modules/message/api.go, modules/qrcode/api.go, modules/user/api.go, and modules/user/api_manager.go all import .../pkg/auth; no other non-test importer exists. ✅
• aliases_test.go exists, so the "delete aliases.go and aliases_test.go" instruction in the removal-entails block is accurate. ✅
• "The exported surface is identical." Verified 1:1 against modules/auth: the type aliases (TokenInfo, LanguageResolver, RoleResolver, CacheTokenParser, ParserOption), the by-value sentinel re-exports (ErrEmptyToken, ErrInvalidToken), and the wrapper funcs (Encode, Decode, WithLanguageResolver, WithRoleResolver, NewCacheTokenParser) all map to existing canonical symbols with matching signatures. ✅
• The errors.Is claim is correct. The sentinels are re-exported as var ErrEmptyToken = modulesauth.ErrEmptyToken, which copies the same *errorString pointer, so errors.Is(err, auth.ErrEmptyToken) still matches errors produced by the canonical package. ✅
• Removal-date math is correct. The alias was introduced in #429 (dated 2026-06-22); 2026-06-22 + 6 months = 2026-12-22, matching the date pinned in the doc. ✅
• Gates pass: gofmt -l clean, go build ./pkg/auth/... clean, go test ./pkg/auth/... PASS. ✅

Security review

This PR was flagged for extra scrutiny because it touches the auth package. It is comments-only — there is no change to the token codec, parser, sentinel-error identity, or any control-flow path. No security-relevant behavior is altered, and nothing here requires manual security sign-off beyond the routine docs check above.

Notes (non-blocking)

• The migration recipe says gofmt -r "or a one-shot goimports" is enough. goimports alone will rewrite the import path only if the symbols actually resolve under the new package; since the surface is identical that holds here, so the guidance is accurate. No action needed — just noting it relies on the surface staying identical, which the same comment already asserts.

No P0/P1/P2 issues. Approving.

[OctoBoooot]

Review: docs(auth): harden pkg/auth Deprecated marker with explicit removal date (#433)

Verdict: Request changes — the PR body promises something the diff doesn't deliver. Otherwise the docs update is well-aimed.

Major

• pkg/auth/aliases.go:40-43 — package-level Deprecated: marker now carries the date, but the 12 per-symbol Deprecated: use [modulesauth.X]. lines (54, 59, 64, 69, 74, 81, 87, 95, 103, 110, 117, 127) are untouched. staticcheck SA1019 / golangci-lint deprecated reports the per-symbol marker at each call site, so the actual lint diagnostic at the six importers still has no date — which is exactly the diagnostic the PR body says is being hardened. Either extend the date to each per-symbol line or scope the PR body's claim to the package doc. (See inline.)

Minor

• pkg/auth/aliases.go:15 — [octo-server#428] uses godoc reference syntax with no matching [octo-server#428]: <url> link target, so pkg.go.dev won't hyperlink it. Same for the reuse on line 42. (See inline.)
• pkg/auth/aliases.go:14 — “six months after the alias was introduced in PR-A1 / #429” — #429 is still OPEN (mergedAt: null at 2026-06-22), so the alias isn't in main yet; 2026-12-22 is computed from today's PR-creation date, not from #429's eventual merge. If the stack slips, the parenthetical drifts. (See inline.)

Praise

• The concrete migration recipe (gofmt -r / goimports over the importing file) is correct for type-aliased + value-re-exported + wrapper-func re-exports, and immediately actionable for the six in-tree callers.
• "What removal entails" enumeration — naming aliases_test.go explicitly alongside aliases.go, and stating the out-of-tree-fork outcome (clean compile error, no silent breakage) — is the level of detail a contributor reading the warning actually needs.

Out of scope (informational)

• The PR is stacked on #429/#430/#431/#432, all of which are still OPEN. Nothing for this PR to do about it, but the entire Stage A chain has to land in order before the 2026-12-22 clock is even meaningful — worth keeping an eye on as the deadline approaches.

[OctoBoooot]

[major] The PR description says “per-symbol Deprecated lines now show the removal date alongside the redirect, so godoc and the golangci-lint deprecated check produce a more actionable warning at every call site.” The diff only updates the package-level Deprecated: marker (this block, lines 40–43). The 12 per-symbol // Deprecated: use [modulesauth.X]. lines — TokenInfo (54), LanguageResolver (59), RoleResolver (64), CacheTokenParser (69), ParserOption (74), ErrEmptyToken (81), ErrInvalidToken (87), Encode (95), Decode (103), WithLanguageResolver (110), WithRoleResolver (117), NewCacheTokenParser (127) — are untouched.

staticcheck SA1019 / golangci-lint deprecated reports the per-symbol marker at each call site, not the package one. So at the six importers, the lint diagnostic still says “use [modulesauth.X]” with no date — which is the exact diagnostic this PR claims to harden.

Fix either way (suggest the first): (a) append To be removed on or after 2026-12-22. to each of the 12 per-symbol Deprecated lines, or (b) correct the PR body to scope the claim to the package doc only.

[OctoBoooot]

[minor] [octo-server#428] is godoc reference syntax, but no [octo-server#428]: <url> link target is defined anywhere in the package doc — so pkg.go.dev renders it as literal bracketed text, not a hyperlink. Same applies to the reuse on line 42.

Fix: add a link-definition block at the end of the package doc, e.g.

//
// [octo-server#428]: https://github.com/Mininglamp-OSS/octo-server/issues/428

or inline the URL where the reference appears.

[OctoBoooot]

nit: “six months after the alias was introduced in PR-A1 / #429” — #429 is still OPEN (mergedAt: null) as of 2026-06-22, so the alias hasn’t actually been introduced into main yet; 2026-12-22 is six months from today’s PR-creation date, not from #429’s eventual merge. If the stack slips by a few weeks, this parenthetical drifts out of sync with the absolute date. Either reword to “six months after #429 merges” or drop the parenthetical and let the absolute date stand on its own.

[mochashanyao]

[Octo-Q · automated review]

Verdict: Approve — no blocking findings; notes below (data-flow traced).

---

octo-server PR#433 Review Report

PR: #433
Title: docs(auth): harden pkg/auth Deprecated marker with explicit removal date
Head SHA: 9467c018c9bb3942d64fcfdd28cbb426049ae60c
Reviewer: Octo-Q (automated review)
Scope: 1 file (pkg/auth/aliases.go), +33/-3, comments only — no executable code changed

1. Verification Summary

Check	Result	Evidence
Six call sites claim	✅ Verified	grep confirms exactly 6 importers: main.go:24, modules/{group,message,user,qrcode}/api.go, modules/user/api_manager.go:16, modules/user/api.go:45
Removal date (2026-12-22)	✅ Consistent	PR-A1 #429 authored 2026-06-22 → +6 months = 2026-12-22
Referenced issues exist	✅ Verified	#428 (OPEN, epic), #429 (OPEN, PR-A1), #432 (OPEN, PR-A4 stacked base)
"Exported surface is identical"	✅ Verified	All 12 symbols in pkg/auth (5 types, 2 sentinel vars, 5 funcs) have matching exports in modules/auth
go build ./pkg/auth/...	✅ Clean	Exit 0, no output
go test ./pkg/auth/...	✅ PASS	ok ... 0.018s
go vet ./pkg/auth/...	✅ Clean	Exit 0, no output
Deprecated marker format	✅ Correct	Package-level // Deprecated: and per-symbol // Deprecated: follow Go convention for golangci-lint depguard/staticcheck

2. Findings

No P0/P1/P2 findings. The diff is purely documentation — it replaces an ambiguous relative date ("six months after this shim was introduced") with a concrete removal date (2026-12-22), adds a removal-schedule section with migration recipe, and updates the Deprecated: marker to include the date and tracker reference. All factual claims in the documentation were verified against the codebase.

3. Suggestions (non-blocking)

• Nit: The [octo-server#428] reference in Go doc comments renders as plain text, not a clickable link (Go doc only auto-links bare URLs and [pkg.Symbol] syntax). Consider using a bare URL https://github.com/Mininglamp-OSS/octo-server/issues/428 for the migration tracker reference if clickable links in rendered godoc are desired. This is purely cosmetic.

4. Additional Observations

None — the PR is tightly scoped to its stated purpose.

5. Data Flow Traceback

N/A — no data flow changes. The diff modifies only Go doc comments; no runtime behavior is affected. The alias shim's type aliases (type = ), sentinel re-exports (var X = modulesauth.X), and wrapper functions remain unchanged.

6. Blind-spot Checklist (R5 — security_sensitive routing)

• C1 Dual-path parity: N/A — no symmetric paths (add/remove, subscribe/unsubscribe) touched. Comments only.
• C2 Control-flow ordering / nested reuse: N/A — no control flow exists in comment-only changes.
• C3 Authorization boundary ≠ capability boundary: N/A — no endpoints, tools, or capabilities exposed.
• C4 Authorization lifecycle / container-member state cascade: N/A — no auth logic touched.
• C5 Build ≠ runtime path correctness: N/A — no build artifacts, extensions, CLI, or relative URL changes. Build/test/vet all pass.
• C6 Governance/policy/security document self-consistency: N/A — this is a code-level deprecation marker, not a governance/policy document. No conflict with existing SECURITY.md or disclosure policies.

7. Cross-round Blocker Recheck (R6)

N/A — first review of this PR.

---

[Octo-Q] verdict: APPROVE — Documentation-only change with verified factual claims, no executable code impact, all checks green. One cosmetic nit on Go doc link format (non-blocking).

[Jerry-Xin]

APPROVE.

Docs-only change (1 file, +33/-3) hardening the pkg/auth deprecation marker. Verified for accuracy and self-consistency:

• Removal date is correct: 2026-12-22 = six months after PR-A1/#429 introduced the alias shim. Concrete date replaces the previous vague "six months after".
• Tracker reference (#428, the Stage A epic) is consistent with the same public issue referenced across #429–#432. No internal/private leakage — public issue only.
• The "exported surface is identical" description matches the actual shim: types via type = aliases, sentinel errors re-exported by value (so errors.Is keeps matching), functions as wrapper funcs preserving variadic signatures — exactly what landed in #429. Accurate, not aspirational.
• Migration instructions (swap import path, gofmt -r/goimports) are correct given the identical surface.
• No code change, no behavior impact, no removal performed yet (the six callers still import pkg/auth — consistent with the shim still existing).

No blocking items. No nits worth holding.

Merge gate note: stacked on refactor/auth-verify-api-key (top of the Stage A stack), so it can't reach main until the lower PRs (#431 in particular, which has an open blocking CR) land. mergeStateStatus currently UNSTABLE pending CI.

[Jerry-Xin]

Updating my earlier APPROVE to REQUEST_CHANGES — I missed a description-vs-implementation mismatch that Octo-PR correctly flagged. Owning that: my first pass verified the package-level doc change in isolation and was accurate about that, but I failed to cross-check the PR's own stated deliverable against the diff.

🔴 (should-fix) PR claim not delivered:
The PR description ("Effect on callers") states: "The per-symbol Deprecated lines now show the removal date alongside the redirect, so godoc and the golangci-lint deprecated check produce a more actionable warning at every call site."

But the diff only added 2026-12-22 to the package-level marker (aliases.go:40-42). The 12 per-symbol // Deprecated: use [modulesauth.X]. lines (54,59,64,69,74,81,87,95,103,110,117,127) are unchanged — none carry the date.

Why it matters (not cosmetic): staticcheck SA1019 / golangci-lint deprecated emit their diagnostic from the per-symbol Deprecated: line at each call site — exactly the lines that still have no date. So the stated benefit ("more actionable warning at every call site") is not actually produced. The package-doc date only shows in godoc's package header, not in the per-call-site lint output the PR promises.

Fix — pick one:

1. Add — removed on or after 2026-12-22 (see #428) to each of the 12 per-symbol Deprecated lines (delivers the promised per-call-site lint visibility), or
2. Scope the PR description down to "package-level marker only" so the claim matches the code.

🟡 godoc link: the [octo-server#428] doc-link reference may not resolve to a clickable link on pkg.go.dev (bare URL would be more reliable) — as mochashanyao/OctoBoooot noted. Non-blocking.

Everything I verified before still holds (date math correct, surface-identical description accurate, no code change). The block is purely the description/code mismatch above — trivial to fix.

[mochashanyao]

[Octo-Q · automated review]

Verdict: Approve — no blocking findings; notes below (data-flow traced).

---

octo-server PR#433 Review Report

Reviewer: Octo-Q (automated review)
PR: #433
Title: docs(auth): harden pkg/auth Deprecated marker with explicit removal date
Head SHA reviewed: faf9541f283b0e25956a5e94572279ce3dc1be1b (current head — note: differs from dispatch SHA fda2caecbad5edbe629ebe3476b7eeaaef60e98e, branch was updated)
Base: refactor/auth-verify-api-key
Files changed: 1 (pkg/auth/aliases.go) — +45 / -15
Scope: Comments/docs only — zero executable code changes

---

1. Verification Summary

Check	Result	Evidence
No executable code changed	✅	All diff hunks modify only // doc comments. Function bodies, type aliases, var assignments, imports are untouched.
Deprecated markers consistent	✅	All 11 deprecated symbols (5 types, 2 vars, 4 funcs) carry identical suffix: To be removed on or after 2026-12-22 — see [octo-server#428].
Package doc well-formed	✅	New # Removal schedule section uses correct Go 1.19+ godoc heading syntax. Indented code examples render as preformatted blocks.
Removal date arithmetic	✅	2026-12-22 = 6 months from ~2026-06-22 (PR-A1 introduction). Consistent with PR body claim.
Migration recipe correct	✅	Import path swap pkg/auth → modules/auth matches the canonical package established by PR-A1 (#429). Exported surface parity confirmed by the type = aliases and wrapper funcs still present in the file.
Build/test claims	✅ (per PR body)	go build ./pkg/auth/... clean, go test ./pkg/auth/... PASS, golangci-lint run ./pkg/auth/... 0 issues. Docs-only change makes these credible.

2. Findings

No P0/P1/P2 findings.

This is a pure documentation PR. Every change is additive hardening of existing Deprecated: markers. No behavioral, API, or type changes.

Diff-scope three-question (R2):

1. New/amplified/pre-existing? N/A — no defects found.
2. Does the diff alter any path's behavioral contract? No — zero code changes.
3. Pre-existing issues touched by this PR? None identified.

3. Suggestions (non-blocking)

• Nit: The [octo-server#428] reference in godoc link syntax won't resolve to a clickable link in standard godoc/pkgsite output (it's not a Go symbol). It renders as literal text. Consider using a plain URL like https://github.com/Mininglamp-OSS/octo-server/issues/428 if clickability matters, or accept the current form as human-readable shorthand that works fine in source.

4. Additional Observations

• The package doc now serves as a self-contained migration guide — a contributor hitting a Deprecated warning from golangci-lint can read the package doc, see the removal date, understand what removal entails, and execute the migration in one step. This is good documentation hygiene.
• The explicit enumeration of the six call sites in the removal section creates a useful checklist for the eventual deletion PR.

5. Data Flow Traceback

N/A — This PR contains no data flow. All changes are in Go doc comments. No variables, props, getters, SQL results, struct fields, or runtime values are consumed or produced. The executable code (type aliases, var re-exports, wrapper functions) is byte-identical to the base.

6. Blind-spot Checklist (R5)

This PR is routed as security_sensitive (touches pkg/auth), so all C-items are addressed:

• C1 — Dual-path parity: N/A. No symmetric paths (add/remove, subscribe/unsubscribe, etc.) are touched. All 11 deprecated symbols receive identical treatment — no symbol was accidentally skipped.
• C2 — Control-flow ordering / nested reuse: N/A. No control flow exists in comment-only changes.
• C3 — Authorization boundary ≠ capability boundary: N/A. No authorization, permission, or capability changes.
• C4 — Authorization lifecycle / container-member state cascade: N/A. No auth logic changes.
• C5 — Build/note ≠ runtime correctness: N/A. No build artifacts, extensions, CLI packaging, or relative-path changes. The PR is pure comments; go build passing is sufficient and expected.
• C6 — Governance/policy/security document self-consistency: N/A. This is code-level deprecation documentation, not organizational governance/policy. The deprecation timeline (6 months) is consistent with the project's stated deprecation window from the original PR-A1.

7. Cross-round Blocker Re-check (R6)

N/A — first review of this PR.

---

[Octo-Q] verdict: APPROVE

Rationale: Pure documentation hardening with zero code changes. All 11 deprecated symbols receive consistent, actionable removal metadata. No P0/P1/P2 findings. The single nit (godoc link resolvability) is cosmetic and non-blocking.

[yujiawei]

Code Review — PR #433 (octo-server)

Scope reviewed: current head faf9541f283b0e25956a5e94572279ce3dc1be1b, base refactor/auth-verify-api-key.
Note on head SHA: This review targets the current head faf9541, not the earlier fda2cae. The author pushed a follow-up commit ("propagate removal date to per-symbol Deprecated markers") that directly resolves the prior blocking finding. Per re-review hygiene, the verdict is given against the live head.

Change: comments-only edit to a single file, pkg/auth/aliases.go (+45 / −15). No executable code touched (verified: every changed line is a // comment; non-comment diff is empty).

Verdict: APPROVE

The earlier round flagged one legitimate blocker — the PR description promised per-call-site removal dates, but only the package-level marker carried the date. The 12 per-symbol Deprecated: lines (the ones staticcheck SA1019 / golangci-lint deprecated actually surface at each importer) had no date. That gap is now closed in faf9541.

What I verified

✅ Blocking finding resolved — All 12 per-symbol Deprecated: markers now read To be removed on or after 2026-12-22 — see [octo-server#428].:

• types: TokenInfo (l.54), LanguageResolver (l.59), RoleResolver (l.64), CacheTokenParser (l.69), ParserOption (l.74)
• sentinels: ErrEmptyToken (l.81), ErrInvalidToken (l.87)
• functions: Encode (l.95), Decode (l.103), WithLanguageResolver (l.110), WithRoleResolver (l.117), NewCacheTokenParser (l.127)

The diagnostic the PR body promises ("more actionable warning at every call site") is now actually produced, so description and code are consistent.

✅ Date math correct — 2026-12-22 = six months after the alias was introduced in PR-A1 / #429.

✅ Comments-only — diff contains no non-comment code change; the exported surface (type aliases, by-value sentinel re-exports, variadic wrapper funcs) is untouched.

✅ Migration recipe accurate — gofmt -r / goimports over the importing file is sufficient for type-aliased + value-re-exported + wrapper-func re-exports.

✅ Gates (local, Go 1.26.3):

• go build ./pkg/auth/... — clean
• go vet ./pkg/auth/... — clean
• go test ./pkg/auth/... — PASS

Non-blocking nits (suggestions, do not block merge)

• pkg/auth/aliases.go:15,42 — godoc link won't resolve. [octo-server#428] uses doc-link reference syntax but there is no matching [octo-server#428]: <url> link target in the package doc, so pkg.go.dev / godoc renders it as literal text, not a hyperlink. A bare URL (https://github.com/Mininglamp-OSS/octo-server/issues/428) or an added link-target line would render reliably. Cosmetic.
• pkg/auth/aliases.go:13-14 — date anchored to PR-creation, not merge. #429 (which introduces the alias) is still OPEN/unmerged on main, so 2026-12-22 is computed from the alias's authoring date rather than its eventual landing date. If the Stage A stack (#429–#432, all still open) slips, the "six months after" parenthetical drifts slightly. Informational — the explicit absolute date is still the right call vs. the previous vague wording.

Security note (PR classified security_sensitive)

The security_sensitive classification is a keyword hit on the pkg/auth path; the actual change is pure documentation/comments with zero executable-code or behavioral impact on the auth token codec. Nothing here alters authentication, token parsing, sentinel-error identity, or call-site behavior. No additional human security verification is warranted beyond confirming it's comments-only, which I have.

[lml2468]

Thanks @Jerry-Xin @OctoBoooot — fixed in faf9541: every per-symbol Deprecated marker now carries the removal date (2026-12-22) and the migration tracker (#428). Verified by 'grep -c "2026-12-22" pkg/auth/aliases.go' = 14 (1 in package doc, 1 in import doc, 12 per-symbol). golangci-lint deprecated check at importers now produces the actionable warning the PR claimed.

[OctoBoooot]

Review: docs(auth): harden pkg/auth Deprecated marker with explicit removal date (#433) — delta review

Verdict: Approve. Major from the prior CR (review 4543694546) is fixed: all 12 per-symbol Deprecated: lines now carry the 2026-12-22 removal date + [octo-server#428] tracker reference. staticcheck SA1019 / golangci-lint deprecated at each call site now matches the PR description's claim.

Delta scope (9467c01 → faf9541): only pkg/auth/aliases.go per-symbol Deprecated comments were updated; package-level marker unchanged from the prior SHA.

Out of scope (informational — author's discretion, not re-findings)

• Two minors from the prior review remain unactioned: (1) [octo-server#428] is godoc reference syntax without a matching [octo-server#428]: <url> link target, so pkg.go.dev won't hyperlink it; (2) the parenthetical "six months after the alias was introduced in PR-A1 / #429" still anchors to a future event — #429 / #430 / #431 are all still OPEN at this writing, so the alias hasn't been introduced into main yet, and the 2026-12-22 date is computed from PR-creation time rather than #429's eventual merge. Both are low-stakes; calling them out once more so the author can choose, not re-raising as blockers.

[OctoBoooot]

praise: all 12 per-symbol Deprecated: lines (TokenInfo at 54, LanguageResolver at 59, RoleResolver at 64, CacheTokenParser at 69, ParserOption at 74, ErrEmptyToken at 81, ErrInvalidToken at 87, Encode at 95, Decode at 103, WithLanguageResolver at 110, WithRoleResolver at 117, NewCacheTokenParser at 127) now carry the To be removed on or after 2026-12-22 — see [octo-server#428] suffix. staticcheck SA1019 / golangci-lint deprecated at the six call sites will now show the date alongside the redirect — which is the exact diagnostic the PR description promised. Major from the prior CR is fully resolved.

[Jerry-Xin]

Re-review at faf9541 — CHANGES_REQUESTED cleared. APPROVE.

My prior CR (review #4543718525) flagged a description/implementation mismatch: the body's "Effect on callers" promised the removal date "at every call site," but only the package-level marker carried the date — the 12 per-symbol // Deprecated: lines did not, which is where staticcheck SA1019 / golangci deprecated diagnostics actually fire.

This commit takes fix option (1) and resolves it completely:

🟢 Per-symbol audit — all 12 dated, none missed. Every per-symbol Deprecated: line now carries To be removed on or after 2026-12-22 — see [octo-server#428].:

• Types: TokenInfo (L54), LanguageResolver (L59), RoleResolver (L64), CacheTokenParser (L69), ParserOption (L74)
• Sentinels: ErrEmptyToken (L81), ErrInvalidToken (L87)
• Funcs: Encode (L95), Decode (L103), WithLanguageResolver (L110), WithRoleResolver (L117), NewCacheTokenParser (L127)
• Package-level marker (L40-43) also carries the date + tracker.

Verified: grep -c "Deprecated:" = 13, of which 12 per-symbol all contain 2026-12-22; the 13th (package-level L40) carries the date on its wrapped continuation line (L42). No undated per-symbol line remains.

🟢 Description now matches code. The "at every call site" claim is now true — the per-call-site deprecated diagnostic will surface the removal date and #428 tracker for each importer. Core defect fixed.

🟢 Still docs-only. Single file pkg/auth/aliases.go (+45/-15); all changes confined to // comment lines, no executable code touched. go build/go test/golangci-lint gates unaffected.

🟢 Date math + tracker consistent. 2026-12-22 = 6mo after #429 (PR-A1); [octo-server#428] ref consistent across package-level + all per-symbol lines.

🟡 (non-blocking, unchanged) The [octo-server#428] godoc reference uses bracket form rather than a bare URL; whether it renders clickable on pkg.go.dev depends on the godoc issue-link heuristic. Not a blocker — purely cosmetic for rendered docs.

LGTM. Clearing my CHANGES_REQUESTED.

[yujiawei]

Code Review — PR #433 (octo-server)

Verdict: APPROVED — docs-only change, all factual claims verified, no runtime impact.

Scope

This PR touches a single file, pkg/auth/aliases.go, and changes comments only (+45/-15). It hardens the existing Deprecated: markers on the pkg/auth shim with:

• An explicit removal date (on or after 2026-12-22).
• A # Removal schedule section documenting what removal entails and how to migrate a caller.
• A tracker reference ([octo-server#428]) appended to every per-symbol Deprecated: line.

No identifiers, signatures, control flow, or exported surface are modified.

Verification

Claim in the new docs	Result
Six call sites import pkg/auth (main.go, modules/{group,message,user,qrcode}/api.go, modules/user/api_manager.go)	✅ Confirmed — exactly these 6 non-test importers exist
Canonical package modules/auth exists and re-exports all named symbols	✅ Confirmed — TokenInfo, LanguageResolver, RoleResolver, CacheTokenParser, ParserOption, ErrEmptyToken, ErrInvalidToken, Encode, Decode, WithLanguageResolver, WithRoleResolver, NewCacheTokenParser all present
Sentinel errors re-exported by value so errors.Is keeps matching	✅ Confirmed — var ErrEmptyToken/ErrInvalidToken = modulesauth.…
Removal date = 6 months after introduction (#429)	✅ Consistent (shim introduced ~2026-06-22 → +6mo = 2026-12-22)
Tracker references resolve	✅ #428 (OPEN epic), #429 (OPEN introducing PR) both exist
gofmt clean	✅ gofmt -l reports nothing
go vet ./pkg/auth/	✅ Passes, exit 0

Security note (PR flagged security-sensitive)

The security_sensitive classification is a path/keyword match on pkg/auth. The actual diff carries no security surface: it is comment text only, with no change to token encode/decode, parsing, sentinel-error identity, or any auth logic. Nothing here warrants manual security verification beyond confirming the diff is comment-only — which it is.

Findings

No P0/P1/P2 blocking issues.

Nits (non-blocking, optional)

• The doc instructs migrating callers via "gofmt -r or a one-shot goimports pass." goimports will rewrite the import path only if the local package name resolves identically; since both packages are named auth, a plain import-path swap is indeed sufficient and the guidance is accurate. Minor: a bare goimports won't find the new path automatically unless the old import is removed first — but this is a doc convenience note, not a correctness claim, so no change required.

Conclusion

Accurate, well-scoped documentation hardening that improves the deprecation lifecycle's discoverability without any behavioral risk. Approving.

[OctoBoooot]

Review: docs(auth): harden pkg/auth Deprecated marker with explicit removal date (#433) — delta review

Verdict: Approve. The new head ae116809 is a pure rebase of the prior head faf9541f; the sole PR file pkg/auth/aliases.go is byte-identical (blob 7721b99e unchanged).

No new logical changes. My prior delta review (4543881407) — APPROVE; all 12 per-symbol Deprecated lines carry the 2026-12-22 removal date; two unactioned minors (godoc link target, date-anchor parenthetical) noted as author's discretion — applies verbatim at this SHA.

[mochashanyao]

[Octo-Q · automated review]

Verdict: Approve — no blocking findings; notes below (data-flow traced).

---

octo-server PR#433 Review Report

Reviewer: Octo-Q (automated review)
PR: #433
Title: docs(auth): harden pkg/auth Deprecated marker with explicit removal date
Head SHA reviewed: ae1168099fde1192f5134ea9fd38977b72edf8a6
Base: refactor/auth-verify-api-key
Files changed: 1 (pkg/auth/aliases.go) — +45 / -15
Scope: Comments/docs only — zero executable code changes

---

1. Verification Summary

Check	Result	Evidence
No executable code changed	✅	Filtered diff (non-comment, non-blank lines) is empty. All hunks modify only // doc comments.
Deprecated markers complete	✅	grep -c "Deprecated:" = 13 (1 package-level + 12 per-symbol). All 12 per-symbol carry 2026-12-22.
Removal date count	✅	grep -c "2026-12-22" = 14 (1 in removal-schedule section + 1 in package-level Deprecated + 12 per-symbol).
Removal date arithmetic	✅	2026-12-22 = 6 months from ~2026-06-22 (PR-A1/#429 introduction date).
Migration recipe correct	✅	Import path swap pkg/auth → modules/auth matches canonical package. Exported surface parity confirmed by type = aliases, by-value sentinel re-exports, and wrapper funcs — all untouched in diff.
Six importers consistent	✅	grep -rn "pkg/auth" --include="*.go" confirms: main.go, modules/{group,message,user,qrcode}/api.go, modules/user/api_manager.go — all still import pkg/auth, consistent with shim still existing.
Package doc well-formed	✅	# Removal schedule uses Go 1.19+ godoc heading syntax. Indented import examples render as preformatted blocks.
Prior blocker resolved	✅	Jerry-Xin's CHANGES_REQUESTED (per-symbol Deprecated lines missing date) is fully addressed — all 12 per-symbol lines now carry the date + tracker reference.

2. Findings

No P0/P1/P2 findings.

This is a pure documentation PR. Every change is additive hardening of existing Deprecated: markers. No behavioral, API, or type changes.

Diff-scope three-question (R2):

1. New/amplified/pre-existing? N/A — no defects found.
2. Does the diff alter any path's behavioral contract? No — zero code changes.
3. Pre-existing issues touched by this PR? None identified.

3. Suggestions (non-blocking)

• Nit (godoc link resolvability): [octo-server#428] uses Go doc reference syntax but is not a valid [pkg.Symbol] form, so pkg.go.dev / godoc renders it as literal text, not a hyperlink. A bare URL (https://github.com/Mininglamp-OSS/octo-server/issues/428) would render as a clickable link. Cosmetic — the reference is still human-readable and greppable.
• Nit (date anchoring): The removal date 2026-12-22 is computed from PR-A1/#429's authoring date (~2026-06-22), but #429 is still OPEN/unmerged on main. If the Stage A stack slips, the "six months after" parenthetical drifts slightly. Informational — the explicit absolute date is still the right call vs. the previous vague wording.

4. Additional Observations

• The package doc now serves as a self-contained migration guide: removal date, what removal entails, migration recipe, and tracker reference — all in one place. Good documentation hygiene.
• The explicit enumeration of the six call sites in the removal section creates a useful checklist for the eventual deletion PR.

5. Data Flow Traceback

N/A — This PR contains no data flow. All changes are in Go doc comments. No variables, props, getters, SQL results, struct fields, or runtime values are consumed or produced. The executable code (type aliases, var re-exports, wrapper functions) is byte-identical to the base.

6. Blind-spot Checklist (R5 — security_sensitive routing)

This PR is routed as security_sensitive (touches pkg/auth), so all C-items are addressed:

• C1 — Dual-path parity (incl. guard/lint tool equivalence coverage): N/A. No symmetric paths (add/remove, subscribe/unsubscribe, etc.) are touched. All 12 deprecated symbols receive identical treatment — no symbol was accidentally skipped. No guard/lint tool is involved.
• C2 — Control-flow ordering / nested reuse + security control non-canonical probing: N/A. No control flow exists in comment-only changes.
• C3 — Authorization boundary ≠ capability boundary: N/A. No authorization, permission, or capability changes. No endpoints or tools exposed.
• C4 — Authorization lifecycle / container-member state cascade: N/A. No auth logic changes. No container/member state involved.
• C5 — Build/note ≠ runtime correctness: N/A. No build artifacts, extensions, CLI packaging, or relative-path changes. The PR is pure comments; go build passing is sufficient and expected for a docs-only change.
• C6 — Governance/policy/security document self-consistency: N/A. This is code-level deprecation documentation, not organizational governance/policy. The deprecation timeline (6 months) is consistent with the project's stated deprecation window from the original PR-A1. No conflict with SECURITY.md or disclosure policies.

7. Cross-round Blocker Recheck (R6)

Prior round blocker (Jerry-Xin CHANGES_REQUESTED at SHA 9467c01):

• Blocker: PR description promised per-call-site removal dates in lint diagnostics, but only the package-level marker carried the date. The 12 per-symbol Deprecated: lines had no date.
• Status: ✅ Fixed at current head ae11680. All 12 per-symbol Deprecated: markers now carry To be removed on or after 2026-12-22 — see [octo-server#428]. Verified by grep: lines 54, 59, 64, 69, 74, 81, 87, 95, 103, 110, 117, 127. Jerry-Xin's own re-review at faf9541 (same logical content as current head) also confirmed and cleared the CR.

No other prior blockers exist.

---

[Octo-Q] verdict: APPROVE

Rationale: Pure documentation hardening with zero code changes. All 12 per-symbol deprecated markers receive consistent, actionable removal metadata. The sole prior blocker (description/code mismatch on per-symbol dates) is fully resolved. No P0/P1/P2 findings. Two cosmetic nits (godoc link resolvability, date anchoring to unmerged PR) are non-blocking.

[Jerry-Xin]

Re-review at head ae1168099fde (re-cast — my prior APPROVE on faf9541f was superseded by this rebase + review-fix commit).

✅ APPROVE — docs/comment-only, core deliverable intact.

This commit is a rebase of #433 onto the new base (post-#432) carrying the review-fix docs(auth): propagate removal date to per-symbol Deprecated markers. The clean parent→child delta is exactly pkg/auth/aliases.go +12 -12 — the 12 per-symbol date propagation. No executable code touched.

Per-symbol removal-date re-audit (all 12 still dated 2026-12-22, ref [octo-server#428]):

• TokenInfo (L54), LanguageResolver (L59), RoleResolver (L64), CacheTokenParser (L69), ParserOption (L74), ErrEmptyToken (L81), ErrInvalidToken (L87), Encode (L95), Decode (L103), WithLanguageResolver (L110), WithRoleResolver (L117), NewCacheTokenParser (L127). Plus the package-level Deprecated: marker dated. ✅ none regressed.

Verified:

• ✅ Description now matches code — the lint diagnostic at every pkg/auth call site reads use [modulesauth.X]. To be removed on or after 2026-12-22 — see [octo-server#428]. (the original blocking mismatch stays resolved).
• ✅ Date math correct: shim introduced PR-A1 / #429, removal 2026-12-22 = ~6 months later.
• ✅ #428 tracker reference consistent throughout (14 occurrences, all [octo-server#428]).
• ✅ Docs/comment-only, single file, no code/test logic change.

💬 Non-blocking (unchanged): the [octo-server#428] tracker reference is in godoc bracket-doclink form rather than a bare URL — may not render as a clickable link on pkg.go.dev. Cosmetic only; not worth another round.

LGTM.