docs: document shared token issuance flow and fix magic-links warning callout

[github-actions]

Follows PR #330 ("Extract shared session/refresh-cookie validation for auth handlers").

Changes

docs/handler/magic-links.md

Adds the !!! warning "Sessions requires RefreshCookieName" admonition callout that was present in every other session-supporting handler's docs (auth.md, oauth2.md, oidc.md, passkeys.md) but missing from magic-links.md. The previous inline sentence is replaced with a styled callout for visual consistency.

docs/handler/cookies.md

Adds a Token issuance flow section that explains the five-step centralized flow introduced by PR #330. Developers customizing or debugging token issuance now have a single place to understand:

• How refresh tokens are generated and hashed before storage
• How session records are created and linked to the JWT jti claim
• When SetRefreshCookie / SetAuthCookie are called
• How RefreshTokenTTL / DefaultRefreshTokenTTL control cookie Max-Age and session expiry
• The sessionless code path (no jti, no refresh cookie)

Checklist

• No behaviour changes — documentation only
• Consistent admonition style across all handler docs
• Progressive disclosure: high-level flow steps, no implementation internals exposed

Generated by Update Docs · ● 1.8M · ◷

Add this agentic workflows to your repo

To install this agentic workflow, run

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

Greptile Summary

This documentation-only PR adds a "Token issuance flow" section to docs/handler/cookies.md and adds the missing !!! warning "Sessions requires RefreshCookieName" admonition to docs/handler/magic-links.md. Both changes accurately reflect the implementation in handler/helpers.go.

• cookies.md: The five-step token issuance flow description matches the issueTokens function exactly — random hex generation via auth.GenerateRandomHex(32), SHA-256 hashing, session creation, CreateTokenWithSession with jti, cookie writes, and the DefaultRefreshTokenTTL fallback.
• magic-links.md: The inline RefreshCookieName requirement sentence is replaced with a styled warning admonition, bringing it visually in line with auth.md, oauth2.md, oidc.md, and passkeys.md.

Confidence Score: 5/5

Documentation-only change with no behaviour modifications; safe to merge.

Both new documentation sections were verified against the actual implementation in handler/helpers.go and auth/crypto.go. Every step in the token issuance flow description matches the code exactly, the sessionless path description is correct, and the RefreshCookieName warning admonition preserves all information from the removed inline sentence.

No files require special attention.

Important Files Changed

Filename	Overview
docs/handler/cookies.md	Adds a Token issuance flow section; all five steps and the sessionless path accurately match the issueTokens implementation in handler/helpers.go.
docs/handler/magic-links.md	Replaces inline RefreshCookieName requirement sentence with a warning admonition, consistent with other handler docs; no content is lost.

Sequence Diagram

sequenceDiagram
    participant H as Handler
    participant IT as issueTokens()
    participant S as SessionStore
    participant J as JWTManager
    participant W as http.ResponseWriter

    H->>IT: issueTokens(w, r, userID, sessions, ...)

    alt Sessions is non-nil
        IT->>IT: GenerateRandomHex(32) → rawRefresh
        IT->>IT: HashHighEntropyToken(rawRefresh) → hash
        IT->>S: CreateSession(ctx, userID, hash, userAgent, ip, now+TTL)
        S-->>IT: sess (with sess.ID)
        IT->>J: CreateTokenWithSession(userID, sess.ID)
        J-->>IT: "accessToken (jti = sess.ID)"
        IT->>W: "SetRefreshCookie(rawRefresh, refreshCookieName, maxAge=TTL)"
        IT->>W: SetAuthCookie(accessToken, cookieName)
        IT-->>H: "accessToken, rawRefresh, ok=true"
    else Sessions is nil
        IT->>J: CreateToken(userID)
        J-->>IT: accessToken (no jti)
        IT->>W: SetAuthCookie(accessToken, cookieName)
        IT-->>H: "accessToken, empty, ok=true"
    end

Loading

_{Reviews (2): Last reviewed commit: "Update docs/handler/cookies.md" | Re-trigger Greptile}

[Copilot]

Pull request overview

Updates handler documentation to reflect the shared, centralized token issuance behavior introduced in PR #330 and to make session/refresh-cookie configuration warnings consistent across handler docs.

Changes:

• Adds a standardized !!! warning "Sessions requires RefreshCookieName" admonition to MagicLinkHandler docs (matching other session-capable handlers).
• Documents the shared 5-step token issuance flow (session-enabled vs sessionless) in docs/handler/cookies.md.

Show a summary per file

File	Description
docs/handler/magic-links.md	Replaces an inline configuration warning with a consistent admonition callout for Sessions + RefreshCookieName validation.
docs/handler/cookies.md	Adds a centralized “Token issuance flow” section describing shared issuance steps and how RefreshTokenTTL/DefaultRefreshTokenTTL affect sessions/cookies.

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