docs: document missing features (RBAC, TOTP, magic links, email verification, password reset, maintenance)

[github-actions]

Summary

The README was missing documentation for several complete, implemented features. This PR fills all identified gaps.

Changes

Corrections

• Go version: 1.21+ → 1.26+ (matches go 1.26.1 in go.mod)

New sections

Area	What was added
Packages table	maintenance package entry
auth – Sentinel errors	Full reference table: ErrTOTPNotFound, ErrInvalidTOTPCode, ErrEmailNotVerified, ErrSessionRevoked, ErrOIDCSubjectAlreadyLinked
auth – RBAC	RegisterRolePermissions, StoreRoleChecker, NewCachingRoleChecker, built-in roles/permissions table, RBACUserStore interface
auth – Crypto	auth.GenerateRandomBase64 (used by magic links and password reset)
auth – Store interfaces	MagicLinkStore, EmailVerificationStore, TOTPStore, PasswordResetStore
handler	MagicLinkHandler, EmailVerificationHandler, PasswordResetHandler, TOTPHandler (full struct, routes, and behavior notes for each)
maintenance	Full StartCleanup section with example and behavioral notes
Security notes	TOTP replay protection, magic link / reset token security, email enumeration prevention

Testing

No code was changed — only documentation. The build is unaffected.

Warning

⚠️ Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by Update Docs · ● 2.3M · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/update-docs.md@96b9d4c39aa22359c0b38265927eadb31dcf4e2a

Greptile Summary

This PR documents several previously undocumented but fully-implemented features: RBAC, TOTP, magic links, email verification, password reset, and the maintenance package. Prior review feedback (incorrect ctx types in callback signatures and RBACUserStore) has been addressed.

• ErrSessionRevoked documentation is inaccurate: the table says it is returned by the middleware when a session is revoked, but this sentinel is never referenced anywhere in the library code. The middleware only handles ErrNotFound; returning ErrSessionRevoked from a SessionStore would produce HTTP 500 instead of 401.

Confidence Score: 4/5

Safe to merge after fixing the ErrSessionRevoked description, which would mislead SessionStore implementors.

One P1 documentation inaccuracy remains: ErrSessionRevoked is documented as returned by the middleware but is never used by the library; a store implementor relying on this table would write incorrect code. All other changes are accurate and prior P1 findings are resolved.

README.md line 108 — ErrSessionRevoked sentinel error description

Important Files Changed

Filename	Overview
README.md	Comprehensive documentation for previously undocumented features (RBAC, TOTP, magic links, email verification, password reset, maintenance); one P1 inaccuracy: ErrSessionRevoked is described as returned by the middleware but is in fact never used by the library.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Incoming Request] --> B{Has JWT?}
    B -- Yes --> C[Validate JWT signature & exp]
    C -- Invalid/Expired --> X1[401 Unauthorized]
    C -- Valid --> D{Sessions configured?}
    D -- No --> E[Inject UserID → handler]
    D -- Yes --> F[FindSessionByID jti]
    F -- ErrNotFound --> X2[401 session expired or revoked]
    F -- other error --> X3[500 Internal Server Error]
    F -- Found --> G{UserID match & not expired?}
    G -- No --> X2
    G -- Yes --> E
    B -- No API key --> H[ValidateAPIKey hash]
    H -- Not found --> X1
    H -- Found --> E

Loading

Comments Outside Diff (1)

1. README.md, line 588-624 (link)

   Incorrect ctx type in callback function literals

   Three newly-documented callback fields use Go's grouped-name shorthand where ctx is grouped with string parameters, making all parameters string. The actual field types require context.Context as the first argument, so these literals will not compile if copied verbatim.

   • Line 588 (MagicLinkHandler.Sender): func(ctx, email, token string) — actual type: func(ctx context.Context, email, token string) error
   • Line 608 (EmailVerificationHandler.SendEmail): func(ctx, to, token string) — actual type: func(ctx context.Context, to, token string) error
   • Line 624 (PasswordResetHandler.SendResetEmail): func(ctx, toEmail, rawToken string) — actual type: func(ctx context.Context, toEmail, rawToken string) error

   This is the same class of bug as the RBACUserStore snippet that was already fixed in this PR (the previous (ctx, userID string) → (ctx context.Context, userID string) correction).

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: README.md
   Line: 588-624
   
   Comment:
   **Incorrect `ctx` type in callback function literals**
   
   Three newly-documented callback fields use Go's grouped-name shorthand where `ctx` is grouped with `string` parameters, making all parameters `string`. The actual field types require `context.Context` as the first argument, so these literals will not compile if copied verbatim.
   
   - Line 588 (`MagicLinkHandler.Sender`): `func(ctx, email, token string)` — actual type: `func(ctx context.Context, email, token string) error`
   - Line 608 (`EmailVerificationHandler.SendEmail`): `func(ctx, to, token string)` — actual type: `func(ctx context.Context, to, token string) error`
   - Line 624 (`PasswordResetHandler.SendResetEmail`): `func(ctx, toEmail, rawToken string)` — actual type: `func(ctx context.Context, toEmail, rawToken string) error`
   
   This is the same class of bug as the `RBACUserStore` snippet that was already fixed in this PR (the previous `(ctx, userID string)` → `(ctx context.Context, userID string)` correction).
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

This is a comment left during a code review.
Path: README.md
Line: 108

Comment:
**`ErrSessionRevoked` is never returned by the middleware**

`ErrSessionRevoked` is defined in `auth/types.go` but is never referenced anywhere else in the library. The middleware (`auth/middleware.go`) only checks for `ErrNotFound` from the session store; any other error (including `ErrSessionRevoked`) falls to the `else` branch and produces an HTTP 500 response. A `SessionStore` implementor who reads this table and returns `ErrSessionRevoked` for revoked sessions based on this documentation would receive 500 errors instead of 401s.

The "When returned" description should either reflect the actual behaviour (this error is currently unused by the library, and store implementations should return `ErrNotFound` for missing/revoked sessions) or the middleware should be updated to explicitly handle `ErrSessionRevoked`.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (5): Last reviewed commit: "docs: fix ctx parameter type in callback..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[Copilot]

Pull request overview

Updates the README to document several previously implemented but undocumented authentication and maintenance features, and aligns the documented Go version requirement with go.mod.

Changes:

• Expands README coverage for RBAC, TOTP, magic links, email verification, password reset, and the maintenance package.
• Adds reference tables for sentinel errors, roles/permissions, and store interfaces.
• Updates the documented Go version requirement to 1.26+.

Show a summary per file

File	Description
README.md	Adds/updates documentation for implemented auth flows (RBAC, TOTP, magic links, email verification, password reset) and maintenance cleanup, plus corrects the stated Go version.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (3)

README.md:540

• The route comment for RequestReset says “always 200”, but the handler can return 429 when rate limited and 400 on missing/invalid email (and 500 on internal failures). Consider qualifying this as “returns 200 for well-formed requests regardless of whether the email is registered” and optionally calling out the 429 behavior when RateLimiter is set.

POST /password-reset/request  → h.RequestReset    // always 200; sends token if email is registered

README.md:525

• SendVerification is described as “always returns 200”, but the handler returns 400 for invalid input (e.g., missing email / invalid JSON). Consider qualifying this as “returns 200 for well-formed requests regardless of whether the email is registered” to keep the anti-enumeration guarantee accurate.

- `SendVerification` always returns 200 to avoid leaking account existence.

README.md:507

• RequestMagicLink is documented as “always returns 200”, but the handler returns non-200 responses for invalid input (e.g., missing email / invalid JSON) and for server misconfiguration or failures (e.g., Sender nil, store errors). Consider rephrasing to: it returns 200 for well-formed requests regardless of whether the email is registered (to prevent enumeration).

- `RequestMagicLink` always returns 200 to avoid leaking whether an address is registered.

• Files reviewed: 1/1 changed files
• Comments generated: 1

[greptile-apps]

ErrSessionRevoked is never returned by the middleware

ErrSessionRevoked is defined in auth/types.go but is never referenced anywhere else in the library. The middleware (auth/middleware.go) only checks for ErrNotFound from the session store; any other error (including ErrSessionRevoked) falls to the else branch and produces an HTTP 500 response. A SessionStore implementor who reads this table and returns ErrSessionRevoked for revoked sessions based on this documentation would receive 500 errors instead of 401s.

The "When returned" description should either reflect the actual behaviour (this error is currently unused by the library, and store implementations should return ErrNotFound for missing/revoked sessions) or the middleware should be updated to explicitly handle ErrSessionRevoked.

Prompt To Fix With AI

This is a comment left during a code review.
Path: README.md
Line: 108

Comment:
**`ErrSessionRevoked` is never returned by the middleware**

`ErrSessionRevoked` is defined in `auth/types.go` but is never referenced anywhere else in the library. The middleware (`auth/middleware.go`) only checks for `ErrNotFound` from the session store; any other error (including `ErrSessionRevoked`) falls to the `else` branch and produces an HTTP 500 response. A `SessionStore` implementor who reads this table and returns `ErrSessionRevoked` for revoked sessions based on this documentation would receive 500 errors instead of 401s.

The "When returned" description should either reflect the actual behaviour (this error is currently unused by the library, and store implementations should return `ErrNotFound` for missing/revoked sessions) or the middleware should be updated to explicitly handle `ErrSessionRevoked`.

How can I resolve this? If you propose a fix, please make it concise.