docs: update README to reflect current codebase

[Copilot]

README was significantly out of date — entire subsystems were undocumented and several details were incorrect.

Corrections

• Go requirement: 1.21+ → 1.26+
• AdminMiddleware second argument type: UserStore → AdminChecker interface

Missing packages

• maintenance — added to packages table and given a full section documenting StartCleanup

Missing auth package APIs

• Sentinel errors: ErrEmailNotVerified, ErrSessionRevoked, ErrTOTPNotFound, ErrInvalidTOTPCode, ErrOIDCSubjectAlreadyLinked
• Crypto: GenerateRandomBase64
• Context helpers: ContextWithUserID, ContextWithRoles, RolesFromContext
• Middleware: RequireRole, RequirePermission
• RBAC: built-in roles/permissions table, StoreRoleChecker, NewCachingRoleChecker, NewAdminCheckerFromRoleChecker, RegisterRolePermissions
• TOTP: GenerateTOTPSecret, TOTPProvisioningURI, ValidateTOTP, TOTPUsedCodeCache (replay protection)
• Store interfaces: MagicLinkStore, EmailVerificationStore, TOTPStore, PasswordResetStore, RBACUserStore

Missing handler package APIs

• AuthHandler.RequireVerification / AuthHandler.Verifications fields
• TOTPHandler — full enrollment/verify/disable flow
• MagicLinkHandler — passwordless login with auto-provisioning
• EmailVerificationHandler — token issuance and consumption
• PasswordResetHandler — request/confirm flow with OIDC-account guard
• Cookie helpers: SetRefreshCookie, ClearRefreshCookie

Security notes

Added notes for TOTP replay protection, password reset scope limited to password-auth accounts, and email enumeration resistance across magic link / password reset / email verification endpoints.

[Copilot]

Pull request overview

Updates README.md to align public documentation with the current goauth codebase, covering newly added subsystems/APIs and correcting outdated details (toolchain + middleware signature expectations).

Changes:

• Updates documented Go version requirement to 1.26+ and refreshes the package overview/features list.
• Expands auth and handler documentation to include RBAC, magic links, TOTP/MFA, email verification, password reset, and related store interfaces/helpers.
• Adds documentation for the maintenance package and extends Security Notes for replay protection, reset scoping, and enumeration resistance.

Show a summary per file

File	Description
README.md	Refreshes and expands documentation to match current packages, APIs, and security characteristics.

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:557

• The README says SendVerification “always returns 200”, but the handler returns 400 when the email field is missing/empty (and may also return non-200 on malformed JSON). If the intent is to document enumeration resistance, consider wording it as “returns 200 for both existing and non-existing addresses / already-verified addresses” rather than an absolute “always 200”.

POST /verify-email/send   → h.SendVerification   // send verification email (always 200)
GET  /verify-email        → h.VerifyEmail         // ?token=<token> → marks email verified

SendVerification silently skips already-verified addresses and always returns 200 to avoid leaking whether an address is registered. Set RequireVerification: true on AuthHandler to gate login on email verification.

**README.md:574**
* `RequestReset` is documented as “always 200”, but the handler can return non-200 for invalid input (e.g., missing email → 400) and when rate limiting is enabled (→ 429). Consider clarifying that it returns 200 for both registered and unregistered emails (to avoid enumeration), while still returning appropriate status codes for validation/rate-limit errors.

POST /password-reset/request → h.RequestReset // send reset email (always 200)
POST /password-reset/confirm → h.ResetPassword // validate token and set new password

Only accounts with a password hash (not OIDC-only accounts) can use the reset flow. `RequestReset` always returns 200. Reset tokens are consumed (deleted) after successful use.

README.md:645

• This security note says these endpoints “always return 200”, but the implementations can return non-200 for invalid input (400) and rate limiting (429), etc. Consider rephrasing to the intended property: the response is the same (200) for “email exists” vs “email not found” cases to mitigate enumeration, while still allowing validation/abuse-protection errors to use other status codes.

- **Email enumeration** – `RequestMagicLink`, `RequestReset`, and `SendVerification` always return 200 to prevent username/email enumeration via timing or response differences.

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