docs: add missing struct definitions to store-interfaces and document TOTPEncoding

[github-actions]

Summary

Two documentation gaps identified and fixed:

1. docs/auth/store-interfaces.md — missing struct definitions

The store-interfaces reference documented every interface but only showed the User struct layout. Implementors and consumers of the other stores had no canonical place to look up field names and types for the structs returned by those interfaces.

Added ### <Type> struct subsections (matching the existing ### User struct pattern) for:

Struct	Under section
APIKey	APIKeyStore
Session	SessionStore
PasskeyCredential	PasskeyStore
PasskeyChallenge	PasskeyStore
MagicLink	MagicLinkStore
EmailVerificationToken	EmailVerificationStore
TOTPSecret	TOTPStore
PasswordResetToken	PasswordResetStore

All struct definitions are taken verbatim from auth/types.go, with brief inline comments where the source code already had them (e.g. PasswordHash, OIDCSubject, TOTPSecret.Secret).

2. docs/auth/totp.md — TOTPEncoding() undocumented

auth.TOTPEncoding() is an exported function that returns the specific base32 encoding (standard RFC 4648, no padding) used by every TOTP function in the library. Without documentation, callers who need to encode or decode raw secret bytes outside the built-in helpers have no way to know which encoding to use, risking subtle incompatibilities.

Added a Base32 encoding section showing EncodeToString and DecodeString usage.

Files changed

• docs/auth/store-interfaces.md
• docs/auth/totp.md

Generated by Update Docs · ● 1.3M · ◷

To install this agentic workflow, run

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

Greptile Summary

This PR fills two documentation gaps: it backfills ### <Type> struct subsections for all 8 store-interface types previously missing from docs/auth/store-interfaces.md, and adds a EncodeToString usage example to the TOTP secret-encoding section in docs/auth/totp.md. All struct field layouts match auth/types.go; the only notable issue is that the PasskeyChallenge.SessionData inline comment references the unexported internal type passkeyChallengeData from handler/passkey.go, which is an implementation detail that store implementors don't need and that could drift if the handler changes.

Confidence Score: 5/5

Documentation-only PR with accurate struct definitions; safe to merge.

All changes are documentation. Struct definitions match the source. The single finding is a P2 style issue (referencing an unexported type in a field comment), which does not affect correctness or safety.

docs/auth/store-interfaces.md — PasskeyChallenge.SessionData comment references internal unexported type

Important Files Changed

Filename	Overview
docs/auth/store-interfaces.md	Added 8 struct definitions (APIKey, Session, PasskeyCredential, PasskeyChallenge, MagicLink, EmailVerificationToken, TOTPSecret, PasswordResetToken) matching source; one field comment on PasskeyChallenge.SessionData references an unexported internal type.
docs/auth/totp.md	Added EncodeToString usage example in the Secret encoding section and a trailing blank line before the HTTP handler section.

Entity Relationship Diagram

%%{init: {'theme': 'neutral'}}%%
erDiagram
    User {
        string ID
        string Name
        string Email
        string PasswordHash
        string OIDCSubject
        bool IsAdmin
        bool EmailVerified
        time CreatedAt
    }
    APIKey {
        string ID
        string UserID
        string Name
        string KeyHash
        string KeyPrefix
        time LastUsedAt
        time CreatedAt
    }
    Session {
        string ID
        string UserID
        string RefreshTokenHash
        string UserAgent
        string IPAddress
        time ExpiresAt
        time CreatedAt
    }
    PasskeyCredential {
        string ID
        string UserID
        string Name
        string CredentialID
        string CredentialData
        string AAGUID
        time CreatedAt
    }
    PasskeyChallenge {
        string ID
        string UserID
        string SessionData
        time ExpiresAt
        time CreatedAt
    }
    TOTPSecret {
        string ID
        string UserID
        string Secret
        time CreatedAt
    }
    PasswordResetToken {
        string ID
        string UserID
        string TokenHash
        time ExpiresAt
        time CreatedAt
    }
    User ||--o{ APIKey : "has"
    User ||--o{ Session : "has"
    User ||--o{ PasskeyCredential : "has"
    User ||--o| PasskeyChallenge : "initiates"
    User ||--o| TOTPSecret : "has"
    User ||--o{ PasswordResetToken : "has"

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
docs/auth/store-interfaces.md:142
**`SessionData` comment exposes an unexported internal type**

The comment references `passkeyChallengeData`, which is a private struct in `handler/passkey.go` (unexported). Implementors of `PasskeyStore` don't need to know the internal serialization format — and if `PasskeyHandler`'s encoding ever changes, this doc comment will silently become stale. Consider describing the field as opaque to the store:

```suggestion
    SessionData string    // opaque JSON blob written and read exclusively by PasskeyHandler; store implementations must not interpret or modify this value
```

_{Reviews (2): Last reviewed commit: "docs: address review comments on store-i..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR fills documentation gaps in the auth docs by adding missing struct layouts to the store interface reference and documenting the canonical base32 encoding used for TOTP secrets.

Changes:

• Added a “Base32 encoding” section to docs/auth/totp.md describing auth.TOTPEncoding() usage.
• Added struct definitions for store-returned types (e.g., APIKey, Session, PasskeyCredential, MagicLink, etc.) in docs/auth/store-interfaces.md.

Show a summary per file

File	Description
docs/auth/totp.md	Documents the exact base32 encoding used by TOTP helpers via auth.TOTPEncoding().
docs/auth/store-interfaces.md	Adds struct layouts for store-returned types to make field names/types discoverable for implementors.

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