docs: document auth.BcryptCost, DefaultRefreshTokenTTL, PasskeyCredentialDTO, GenerateTOTPCode

[github-actions]

Summary

This PR fills four small but meaningful documentation gaps in the README — exported symbols that were undocumented despite being part of the public API.

Changes

auth.BcryptCost (Crypto utilities section)
The constant was used internally and its value mentioned in prose ("Bcrypt cost 12"), but the exported name was never shown. Callers that hash passwords outside of AuthHandler (e.g. seeding a database) should use auth.BcryptCost to stay consistent with the rest of the library.

handler.DefaultRefreshTokenTTL (AuthHandler snippet)
The AuthHandler.RefreshTokenTTL godoc references DefaultRefreshTokenTTL by name but the README only showed the numeric literal 7 * 24 * time.Hour. Updated the comment to name the constant so readers know they can reference it directly.

handler.PasskeyCredentialDTO (PasskeyHandler section)
FinishRegistration (201) and ListCredentials (200) return this type, but it was never mentioned in the docs. Added the struct definition with JSON field names so integrators know the response shape without digging into source.

auth.GenerateTOTPCode (TOTP / MFA section)
This function is public and useful for integration tests and CLI tooling. Added a one-liner example with a note that ValidateTOTP should be used in production code.

Testing

Documentation-only change — no behaviour altered. Existing tests remain 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.4M · ◷

To install this agentic workflow, run

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

Greptile Summary

This documentation-only PR adds README coverage for four public API symbols — auth.BcryptCost, handler.DefaultRefreshTokenTTL, handler.PasskeyCredentialDTO, and auth.GenerateTOTPCode — all of which were verified accurate against the source. Two snippets (MagicLinkHandler and Quick start) still use the bare numeric literal 7 * 24 * time.Hour rather than the newly-referenced handler.DefaultRefreshTokenTTL constant, leaving minor inconsistencies in the documentation.

Confidence Score: 5/5

Safe to merge — documentation-only change with no behavioural impact.

All findings are P2 style suggestions. The documented content is accurate against the source code. No code correctness, security, or data-integrity issues are introduced.

No files require special attention beyond the two minor DefaultRefreshTokenTTL literal inconsistencies in README.md.

Important Files Changed

Filename	Overview
README.md	Documents four previously undocumented public symbols (auth.BcryptCost, handler.DefaultRefreshTokenTTL, handler.PasskeyCredentialDTO, auth.GenerateTOTPCode); all documented content verified accurate against source, but MagicLinkHandler and Quick start snippets still use the bare numeric literal instead of the new constant reference.

Sequence Diagram

sequenceDiagram
    participant Client
    participant AuthHandler
    participant PasskeyHandler
    participant TOTPHandler

    Note over Client,TOTPHandler: Flows newly documented in this PR

    Client->>AuthHandler: POST /auth/signup or /auth/login
    AuthHandler-->>Client: token + refresh_token (handler.DefaultRefreshTokenTTL)

    Client->>PasskeyHandler: POST /auth/passkey/register/finish
    PasskeyHandler-->>Client: PasskeyCredentialDTO {id, name, aaguid, created_at} (201)

    Client->>PasskeyHandler: GET /auth/passkey/credentials
    PasskeyHandler-->>Client: []PasskeyCredentialDTO (200)

    Note over Client,TOTPHandler: TOTP testing/tooling helper
    Client->>TOTPHandler: auth.GenerateTOTPCode(secret, time.Now())
    TOTPHandler-->>Client: 6-digit code (use ValidateTOTP in production)

Loading

Comments Outside Diff (1)

1. README.md, line 650 (link)

   Inconsistent DefaultRefreshTokenTTL reference in MagicLinkHandler snippet

   The AuthHandler snippet on line 472 was updated to add // defaults to handler.DefaultRefreshTokenTTL (7 days) when Sessions is set, making the constant discoverable. The MagicLinkHandler struct exposes the same RefreshTokenTTL field with the same default behaviour (as seen in handler/magiclink.go line 32), but this snippet still shows only the bare numeric literal with no mention of DefaultRefreshTokenTTL.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: README.md
   Line: 650
   
   Comment:
   **Inconsistent `DefaultRefreshTokenTTL` reference in `MagicLinkHandler` snippet**
   
   The `AuthHandler` snippet on line 472 was updated to add `// defaults to handler.DefaultRefreshTokenTTL (7 days) when Sessions is set`, making the constant discoverable. The `MagicLinkHandler` struct exposes the same `RefreshTokenTTL` field with the same default behaviour (as seen in `handler/magiclink.go` line 32), but this snippet still shows only the bare numeric literal with no mention of `DefaultRefreshTokenTTL`.
   
   
   
   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: 672

Comment:
**Inconsistent `DefaultRefreshTokenTTL` reference in `MagicLinkHandler` snippet**

The `AuthHandler` snippet (line 479) was updated to reference `handler.DefaultRefreshTokenTTL`, but the `MagicLinkHandler` snippet still uses the bare numeric literal. Both fields share the same default behaviour via `DefaultRefreshTokenTTL` (confirmed in `handler/magiclink.go` line 31 and `handler/helpers.go` line 50), so the same constant should be shown here for consistency.

```suggestion
    RefreshTokenTTL:   handler.DefaultRefreshTokenTTL, // defaults to 7 days when Sessions is set
```

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

---

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

Comment:
**Quick-start snippet not updated to use `handler.DefaultRefreshTokenTTL`**

The Quick start snippet at the top of the README still uses the bare numeric literal while the `AuthHandler` section below now references the named constant. Updating the quick-start example keeps all snippets consistent.

```suggestion
    RefreshTokenTTL:   handler.DefaultRefreshTokenTTL,
```

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

_{Reviews (2): Last reviewed commit: "docs: fix code variable collision in TOT..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR updates the README to document previously undocumented exported/public API symbols so integrators can rely on stable names and response shapes without digging into source.

Changes:

• Document auth.BcryptCost usage in the crypto utilities section.
• Add a README example for auth.GenerateTOTPCode (testing/tooling use).
• Document handler.PasskeyCredentialDTO response shape and reference handler.DefaultRefreshTokenTTL in the AuthHandler snippet.

Show a summary per file

File	Description
README.md	Adds missing documentation/examples for exported auth/handler symbols and passkey DTO response shape.

Copilot's findings

Tip

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

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