You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Introduce user accounts with secure authentication, session management, and role-based access control (RBAC) to protect administrative APIs (e.g., app grouping) and UI.
Goals
Users can log in and have a session (or JWT) to access protected endpoints.
Roles (e.g., admin, editor, viewer) restrict access to sensitive operations.
Minimal friction to run locally (SQLite-backed), secure-by-default for production.
Scope
User model, password hashing, login/logout, session middleware, role checks, protected routes, and basic admin user management endpoints.
Documentation and examples for using auth and roles.
Out of Scope (initially)
SSO providers (OAuth/OIDC), MFA, email flows; can be follow-ups.
Architecture Overview
Data model:
users: id (uuid), email (unique), password_hash, display_name, role (enum/string), timestamps.
Optional: sessions if server-side sessions stored in DB.
Authentication options:
Session cookies (recommended for built-in UI): server-side session store, httpOnly, secure, SameSite=Lax/Strict.
JWT (stateless) for API-only use; consider refresh tokens if added.
Pick one to start; session cookies + DB-backed store is simplest with SQLite.
Security:
Use bcrypt or argon2id for password hashing; enforce minimal password policy.
CSRF protection for state-changing UI actions if form-based login is added.
PATCH /api/users/{id} — update role or details (admin-only).
DELETE /api/users/{id} — delete user (admin-only).
Middleware
AuthMiddleware to attach the authenticated user to context or reject with 401.
RBACMiddleware (or inline checks) to enforce route-level role permissions; e.g., only admin can manage apps or users, editor can modify app membership, viewer read-only access to servers/apps.
Integration
Protect new app management endpoints from the app-grouping feature with appropriate roles.
Public endpoints remain accessible (e.g., /api/discover may be guarded later if needed).
Acceptance Criteria
Can create at least one bootstrap admin user (env var or CLI) without UI.
Can log in and receive a secure session (httpOnly cookie) or token.
Protected endpoints return 401/403 when unauthenticated/unauthorized.
Role checks enforced for user and app management endpoints.
Basic docs on setup and curl examples to test flows.
Tasks
Add models.User and migrations; password hashing (bcrypt or argon2id).
Implement session store (DB-backed) and secure cookie settings; or JWT issuance/validation.
Add auth middleware and helpers to inject user into request context.
Implement auth endpoints (login, logout, me).
Implement basic user management endpoints (admin-only).
Integrate RBAC checks into routers/handlers.
Update README and API docs (see API docs issue) with auth notes.
Add minimal tests for auth flows and RBAC.
Open Questions
Preference: session cookies vs JWT for initial implementation?
Do we need a signup flow or only admin-created users?
Summary
Goals
admin,editor,viewer) restrict access to sensitive operations.Scope
Out of Scope (initially)
Architecture Overview
users:id(uuid),email(unique),password_hash,display_name,role(enum/string), timestamps.sessionsif server-side sessions stored in DB.bcryptorargon2idfor password hashing; enforce minimal password policy.API Endpoints
POST /api/auth/login—{ email, password }→ starts session / returns token.POST /api/auth/logout— ends session.GET /api/auth/me— returns current user info.POST /api/users— create user (admin-only).GET /api/users— list users (admin-only).PATCH /api/users/{id}— update role or details (admin-only).DELETE /api/users/{id}— delete user (admin-only).Middleware
AuthMiddlewareto attach the authenticated user to context or reject with 401.RBACMiddleware(or inline checks) to enforce route-level role permissions; e.g., onlyadmincan manage apps or users,editorcan modify app membership,viewerread-only access to servers/apps.Integration
/api/discovermay be guarded later if needed).Acceptance Criteria
401/403when unauthenticated/unauthorized.Tasks
models.Userand migrations; password hashing (bcrypt or argon2id).login,logout,me).Open Questions
/api/discoverrequire auth or a shared secret?)\n\nSub-issues (ordered):\n- [ ] Auth: Add basic user entity and storage (Auth: Add basic user entity and storage #24)\n- [ ] Auth: Implement basic authentication (JWT + cookies + middleware + endpoints) (Auth: Implement basic authentication (JWT + cookies + middleware + endpoints) #25)\n- [ ] Auth: Add RBAC and protect routes (Auth: Add RBAC and protect routes #26)\n- [ ] Docs: Update API docs for auth and RBAC (Docs: Update API docs for auth and RBAC #27)\n- [ ] Tests: Add coverage for user, auth, RBAC (Tests: Add coverage for user, auth, RBAC #28)\n\n\nSub-issues (GitHub-tracked):\n- [ ] Auth: Add basic user entity and storage #24 — Auth: Add basic user entity and storage\n- [ ] Auth: Implement basic authentication (JWT + cookies + middleware + endpoints) #25 — Auth: Implement basic authentication (JWT + cookies + middleware + endpoints)\n- [ ] Auth: Add RBAC and protect routes #26 — Auth: Add RBAC and protect routes\n- [ ] Docs: Update API docs for auth and RBAC #27 — Docs: Update API docs for auth and RBAC\n- [ ] Tests: Add coverage for user, auth, RBAC #28 — Tests: Add coverage for user, auth, RBAC\n