docs: document ErrSessionRevoked handling in FindSessionByRefreshTokenHash and RefreshToken

[github-actions]

What changed

PR #186 wired ErrSessionRevoked into two additional code paths:

1. auth.Middleware — FindSessionByID returning ErrSessionRevoked now yields HTTP 401 "session expired or revoked" (same as ErrNotFound).
2. handler.AuthHandler.RefreshToken — FindSessionByRefreshTokenHash returning ErrSessionRevoked now yields HTTP 401 "invalid or expired refresh token" (same as ErrNotFound).

The middleware docs already covered case 1. Case 2 was not documented.

Documentation updates

docs/auth/store-interfaces.md

The SessionStore contract note previously only mentioned that FindSessionByID may return ErrSessionRevoked. It now also clarifies that FindSessionByRefreshTokenHash implementations may return ErrSessionRevoked, and that RefreshToken treats it identically to ErrNotFound (HTTP 401).

docs/handler/auth.md

The RefreshToken HTTP 401 row in the status-code table now reads "Invalid, expired, or revoked refresh token" instead of "Invalid or expired refresh token", accurately reflecting that a revoked session surfaces through this endpoint.

Testing

No code changes — documentation only. Verified against handler/auth.go:250 and auth/middleware.go:292.

Generated by Update Docs · ● 760.1K · ◷

To install this agentic workflow, run

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

Greptile Summary

Documentation-only PR that backfills the ErrSessionRevoked contract for FindSessionByRefreshTokenHash and the RefreshToken handler, following the same pattern already established for FindSessionByID and auth.Middleware. All three changes were verified against handler/auth.go:250 and auth/types.go — the documented behavior accurately reflects the implementation.

Confidence Score: 5/5

Safe to merge — documentation-only change with no code modifications.

All three files contain purely additive documentation updates. The documented behaviour was verified against the source code and is accurate. No logic, types, or tests are modified.

No files require special attention.

Important Files Changed

Filename	Overview
auth/types.go	Expands the GoDoc comment on FindSessionByRefreshTokenHash to document ErrSessionRevoked handling, consistent with the existing FindSessionByID comment pattern and confirmed accurate against handler/auth.go:250.
docs/auth/store-interfaces.md	Splits the ErrSessionRevoked contract note into two paragraphs, adding an accurate description of how RefreshToken handles ErrSessionRevoked from FindSessionByRefreshTokenHash.
docs/handler/auth.md	Updates the RefreshToken 401 status-code table entry to include "revoked" as a trigger condition, accurately reflecting the ErrSessionRevoked handling added in PR #186.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Handler as RefreshToken Handler
    participant Store as SessionStore

    Client->>Handler: POST /auth/refresh
    Handler->>Store: FindSessionByRefreshTokenHash(hash)
    Store-->>Handler: ErrNotFound OR ErrSessionRevoked
    Handler-->>Client: 401 Unauthorized

    Client->>Handler: POST /auth/refresh
    Handler->>Store: FindSessionByRefreshTokenHash(hash)
    Store-->>Handler: Session returned
    Handler->>Store: DeleteSession (consume)
    Handler-->>Client: 200 OK with new tokens

Loading

_{Reviews (2): Last reviewed commit: "docs: add ErrSessionRevoked to FindSessi..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR updates the authentication documentation to reflect the ErrSessionRevoked behavior added in PR #186, specifically for refresh-token session lookups and the RefreshToken endpoint. It fits into the codebase by keeping the public auth/store contracts and handler docs aligned with the runtime behavior already implemented in handler/auth.go.

Changes:

• Clarifies in docs/auth/store-interfaces.md that FindSessionByRefreshTokenHash may return auth.ErrSessionRevoked.
• Updates the AuthHandler.RefreshToken status table entry to mention revoked refresh tokens as a 401 case.

Show a summary per file

File	Description
docs/handler/auth.md	Updates the RefreshToken HTTP 401 condition text in the handler docs.
docs/auth/store-interfaces.md	Expands the SessionStore contract notes to document revoked-session handling for refresh-token lookups.

Copilot's findings

Tip

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

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