docs: add authentication section to README #295
Conversation
Adds documentation explaining the built-in authentication system: - First-time setup process - Single-user system design - JWT-based auth with bcrypt - Security recommendations for VPS/remote deployment - HTTPS and firewall guidance Fixes siteboon#291 Co-Authored-By: Claude Opus 4.5 <[email protected]>
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughAdded Authentication and Tool Permissions documentation to README.md: describes built-in single-user JWT authentication with bcrypt, first-time admin setup, session persistence, cautions for VPS/remote deployment, and revised guidance and illustrations for enabling tools via the Settings modal. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation about the built-in authentication system to the README, addressing user concerns about security when deploying Claude Code UI on VPS or remote servers.
Changes:
- Added new "Authentication" subsection under "Security & Tools Configuration" explaining the authentication system
- Documented first-time setup process, single-user design, JWT-based implementation, and security recommendations
- Provided specific guidance for remote/VPS deployments including strong passwords, HTTPS, and firewall recommendations
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Hey @viper151 @blackmammoth 👋 This PR addresses issue #291 by adding documentation about the built-in authentication system. Key additions:
Would appreciate a review when you have time. Thanks! 🙏 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
README.md (1)
207-214: Fix the numbered list sequence.The numbered steps skip from 1 directly to 3, missing step 2. This creates confusion in the enablement instructions.
📝 Proposed fix for the step numbering
To use Claude Code's full functionality, you'll need to manually enable tools: 1. **Open Tools Settings** - Click the gear icon in the sidebar +2. **Review Available Tools** - See the list of Claude Code tools 3. **Enable Selectively** - Turn on only the tools you need 4. **Apply Settings** - Your preferences are saved locallyOr if step 2 should be removed and steps renumbered:
To use Claude Code's full functionality, you'll need to manually enable tools: 1. **Open Tools Settings** - Click the gear icon in the sidebar -3. **Enable Selectively** - Turn on only the tools you need -4. **Apply Settings** - Your preferences are saved locally +2. **Enable Selectively** - Turn on only the tools you need +3. **Apply Settings** - Your preferences are saved locally
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md
🔇 Additional comments (2)
README.md (2)
215-222: Good use of visual documentation and progressive enablement guidance.The screenshot reference and recommended approach effectively communicate:
- Visual confirmation of the Tools Settings interface
- Progressive enablement strategy (start basic, add as needed)
- Flexibility to adjust settings later
This helps users understand both the UI and best practices for tool configuration.
187-202: Excellent documentation of authentication system with clear security guidance.The Authentication section effectively documents the implementation:
- Built-in authentication requirement and first-time admin setup
- Single-user system design rationale
- Technical implementation details (JWT + bcrypt) are accurate per the codebase
- Actionable security recommendations for VPS deployments
The security warning is appropriately prominent and the guidance is practical for production deployments.
Changes step numbers from 1, 3, 4 to 1, 2, 3 for proper sequential ordering. Co-Authored-By: Claude Opus 4.5 <[email protected]>
|
Fixed the numbered list sequence issue in the Enabling Tools section (1, 3, 4 → 1, 2, 3) as flagged by CodeRabbit. Thanks for the catch! 👍 |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @README.md:
- Around line 189-194: Update the README text: replace "admin account" with
"initial user account" and change "Session persistence" to "Client-side JWT
persistence" clarifying tokens are stored in localStorage and are stateless;
explicitly state "JWT-based auth" tokens have no expiration by default and there
is no token revocation mechanism; add a short security notes subsection calling
out missing features for VPS/remote deployments (no password reset/recovery, no
brute-force rate limiting on the /login endpoint, weak minimum password
requirement—currently 6 chars—and no token expiration/revocation) and recommend
mitigation steps (enforce stronger password policy, use a reverse proxy/firewall
for rate limiting, consider rotating or revoking tokens via server-side scheme).
🧹 Nitpick comments (2)
README.md (2)
196-199: Enhance password strength guidance with specific requirements.The recommendation to "Set a strong password" is vague. Consider documenting specific password requirements or best practices.
📝 Suggested enhancement for password guidance
> ⚠️ **Important for Remote/VPS Deployment**: If you're running Claude Code UI on a remote server or VPS, authentication is **essential** to prevent unauthorized access to your projects and Claude sessions. Make sure to: -> 1. Set a strong password during initial setup +> 1. Set a strong password during initial setup (minimum 12 characters, mix of uppercase, lowercase, numbers, and symbols) > 2. Use HTTPS (via reverse proxy like nginx/caddy) for production deployments > 3. Consider firewall rules to restrict access to trusted IPs
187-202: Consider adding password recovery and session management documentation.The authentication section would benefit from additional details about operational aspects that users will encounter:
- Password recovery: How to reset the admin password if forgotten
- Credential storage: Where authentication data is stored (for backup/migration purposes)
- Session expiry: Whether sessions timeout and if so, after how long
- Security hardening: Whether rate limiting or brute force protection is implemented
These details help users understand the complete authentication workflow and prepare for common scenarios.
Would you like me to draft additional subsections covering password recovery and session management that could be added to this section?
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md
🔇 Additional comments (2)
README.md (2)
203-205: LGTM! Clear security-conscious default.The "Tool Permissions" section clearly communicates the secure-by-default approach. The emphasis on disabled-by-default tools is appropriate for security awareness.
208-222: Excellent improvements to tool enablement guidance.The revised "Enabling Tools" section effectively:
- Emphasizes selective enablement for better security posture
- Clarifies that preferences are saved locally (helpful for users to understand persistence)
- Adds visual guidance with the modal screenshot
- Provides best practice recommendation for progressive enablement
These changes align well with the security-conscious approach introduced in the Authentication section.
- Add specific password requirements (12+ chars recommended) - Add rate limiting recommendation for VPS deployments - Document JWT token storage (localStorage) and expiry behavior - Add password recovery instructions (database reset) - Note that reset clears saved settings and GitHub tokens Addresses CodeRabbit review feedback. Co-Authored-By: Claude Opus 4.5 <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@README.md`:
- Line 197: The README says a 12-char minimum but the code enforces 6; change
the enforcement to match the docs by updating the password length checks from 6
to 12 where validation occurs: update the client-side check in SetupForm.jsx
(the password.length < 6 condition and any validation messages shown to the
user) and the server-side check in auth.js (the password.length < 6 condition
and error message returned), ensuring both use 12 as the minimum and keep
messages consistent; alternatively, if you prefer documenting 6 as the enforced
minimum, update the README line to state 6 is enforced and 12 is recommended
instead.
♻️ Duplicate comments (3)
README.md (3)
191-191: Replace "admin account" with "user account".Based on the authentication implementation (confirmed by previous code review), the system creates a single user account with no admin privileges or role-based access control. The term "admin account" is misleading.
📝 Suggested change
-- **First-time setup**: When you first access the UI, you'll be prompted to create an admin account +- **First-time setup**: When you first access the UI, you'll be prompted to create a user account
194-194: Replace "Session persistence" with more accurate terminology.The system uses stateless JWT tokens stored in localStorage, not server-side sessions. "Session persistence" is misleading terminology for this implementation.
📝 Suggested change
-- **Session persistence**: Stay logged in across browser sessions +- **Client-side token persistence**: JWT tokens stored in browser localStorage keep you logged in across browser sessions
217-217: Replace "admin account" with "user account" (second occurrence).Same issue as line 191—use "user account" instead of "admin account" for consistency and accuracy.
📝 Suggested change
-4. Create a new admin account on first access +4. Create a new user account on first access
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md
🔇 Additional comments (2)
README.md (2)
221-241: LGTM! Clear documentation for tool permissions.The Tool Permissions and Enabling Tools sections provide clear guidance:
- Explicitly states tools are disabled by default for security
- Provides step-by-step instructions with corrected numbering
- Includes helpful screenshot and recommends selective enablement
The numbered list fix (lines 230-231) addresses the sequencing issue mentioned in the PR comments.
193-193: All claims in the README have been verified as accurate:✓ JWT tokens are properly generated using
jwt.sign()in server/middleware/auth.js (line 65)
✓ Bcrypt is used for password hashing with 12 salt rounds in server/routes/auth.js (line 48)
✓ Token expiration is not configured — thejwt.sign()call contains noexpiresInoption, with explicit code comments stating "No expiration - token lasts forever"The documentation accurately reflects the implementation.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
|
Addressed CodeRabbit's feedback:
Thanks for the suggestions! 👍 |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - **Session persistence**: Stay logged in across browser sessions | ||
|
|
||
| > ⚠️ **Important for Remote/VPS Deployment**: If you're running Claude Code UI on a remote server or VPS, authentication is **essential** to prevent unauthorized access to your projects and Claude sessions. Make sure to: | ||
| > 1. Set a strong password during initial setup (minimum 12 characters recommended, with a mix of uppercase, lowercase, numbers, and symbols) |
There was a problem hiding this comment.
The recommendation to set a "minimum 12 characters" password is not enforced by the application. Based on the authentication implementation in server/routes/auth.js, there is no minimum password length validation. Consider either adding password validation to the backend or adjusting this documentation to note that this is a recommendation rather than an enforced requirement.
| > 1. Set a strong password during initial setup (minimum 12 characters recommended, with a mix of uppercase, lowercase, numbers, and symbols) | |
| > 1. Set a strong password during initial setup (use at least 12 characters with a mix of uppercase, lowercase, numbers, and symbols — this is a recommendation and is not enforced by the application) |
| #### Session Management | ||
|
|
||
| - **Token storage**: JWT tokens are stored in your browser's localStorage | ||
| - **Token expiry**: Tokens do not expire by default - you stay logged in until you manually log out |
There was a problem hiding this comment.
The statement "Tokens do not expire by default - you stay logged in until you manually log out" is accurate based on the JWT implementation (no expiry set in generateToken function). However, this is a security concern that should be documented differently. Consider rephrasing to acknowledge this as a potential security trade-off, for example: "Tokens do not expire by default for convenience, but this means you should log out when using shared or public computers."
| - **Token expiry**: Tokens do not expire by default - you stay logged in until you manually log out | |
| - **Token expiry**: Tokens do not expire by default for convenience; always log out when using shared or public computers to protect your account |
| 3. Restart the server | ||
| 4. Create a new admin account on first access | ||
|
|
||
| > **Note**: This will also clear any saved settings and GitHub tokens. |
There was a problem hiding this comment.
The password recovery instructions state "This will also clear any saved settings and GitHub tokens." However, based on the codebase, tools settings, themes, and other preferences are stored in localStorage (browser-side), not in the SQLite database. Only the user account and potentially database-stored settings would be cleared. Consider clarifying that this only clears server-side data (user account) and that browser-stored settings (tools, preferences) will remain unless the browser cache is cleared separately.
| > **Note**: This will also clear any saved settings and GitHub tokens. | |
| > **Note**: Resetting the database clears all **server-side** data (your user account and any database-stored settings or GitHub tokens). **Client-side** settings stored in your browser (such as tool configuration, themes, and other preferences saved in localStorage) are not removed; clear your browser data separately if you want to reset those as well. |
|
@copilot open a new pull request to apply changes based on the comments in this thread |
blackmammoth
requested review from
viper151
and removed request for
blackmammoth
1 participant
Summary
Adds documentation explaining the built-in authentication system to address user concerns about data security when running on VPS/remote servers.
Changes
Added new "Authentication" subsection under "Security & Tools Configuration" that covers:
Why this matters
Users deploying Claude Code UI on remote servers need to understand that:
Fixes #291
🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.