Skip to content

Epic: User accounts, authentication, session management, and RBAC #23

@sugan0tech

Description

@sugan0tech

Summary

  • 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.

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.
  • Admin/user mgmt:
    • 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

  • 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

Metadata

Metadata

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions