Add secure username/password login portal

Gate the suite behind a self-contained login (no external IdP): - User model with bcrypt-hashed passwords; admin/user roles - /api/auth endpoints: login, logout, me, change-password, and admin-only user management (list/create/delete/reset/enable) - Stateless JWT session in an HttpOnly, SameSite=Lax, auto-Secure cookie; middleware refuses every /api data route without a session - login.html + auth-guard.js: login page and per-page guard with a top-right "name / Admin / Sign out" pill - Admin Console now gated on admin role (passphrase gate removed) with a User administration card - manage_users.py CLI to bootstrap the first admin - Rebuilt help.js into a searchable, multi-topic help center - Local-dev convenience: app serves html/ so the site + API share one origin under uvicorn (inactive in the prod container) - Docs/env: AUTH_SECRET_KEY, requirements (bcrypt, PyJWT), README Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-25 16:55:54 -05:00
parent a02f7ec511
commit 20afb0e565
18 changed files with 1470 additions and 99 deletions
--- a/server/.env.example
+++ b/server/.env.example
@@ -10,3 +10,13 @@ DATABASE_URL=postgresql+psycopg://wpsuite:CHANGE_ME@localhost:5432/wpsuite
 # Only needed for CROSS-ORIGIN local development (comma-separated). In
 # production the site is same-origin via NGINX, so leave this unset.
 # CORS_ORIGINS=http://localhost:5500
+
+# ── Authentication ────────────────────────────────────────────────────────────
+# Secret used to sign session cookies (JWTs). REQUIRED in production: if unset,
+# the API falls back to a random per-process key, so logins reset on every
+# restart and break across multiple gunicorn workers. Generate a strong one:
+#   python -c "import secrets; print(secrets.token_urlsafe(48))"
+AUTH_SECRET_KEY=CHANGE_ME_run_the_command_above
+
+# How long a login lasts before re-authentication (hours). Default 12.
+# AUTH_SESSION_HOURS=12
--- a/server/README.md
+++ b/server/README.md
@@ -13,7 +13,14 @@ browser → NGINX ──serves──> static site (index.html, …)

 | Method | Path | Purpose |
 |--------|------|---------|
-| GET  | `/api/health` | liveness check |
+| GET  | `/api/health` | liveness check (unauthenticated) |
+| POST | `/api/auth/login` | sign in (`{username, password}`) — sets the session cookie |
+| POST | `/api/auth/logout` | clear the session cookie |
+| GET  | `/api/auth/me` | the logged-in user |
+| POST | `/api/auth/password` | change your own password |
+| GET  | `/api/auth/users` | list accounts (**admin**) |
+| POST | `/api/auth/users` | create an account (**admin**) |
+| DELETE | `/api/auth/users/{id}` | delete an account (**admin**) |
 | POST | `/api/sops` | create/update a SOP (upsert by `id`) |
 | GET  | `/api/sops` | list SOP summaries |
 | GET  | `/api/sops/latest?complete=true` | most recent (complete) SOP |
@@ -33,6 +40,53 @@ fields (name, number, status, …) are promoted to columns for listing/filtering

 ---

+## Login portal (user accounts)
+
+The suite is gated by a username/password login. Sign-in issues a signed JWT
+that rides in an **HttpOnly, SameSite=Lax** cookie (`wp_session`); the cookie is
+marked **Secure** automatically whenever the request arrives over HTTPS (via
+NGINX's `X-Forwarded-Proto`). There is no server-side session store — each
+request is validated by checking the cookie's signature and expiry.
+
+**The real security boundary is the API:** every `/api/` data route is refused
+with `401` unless a valid session cookie is present (see `auth_gate` in
+`app.py`). The static pages additionally include `auth-guard.js`, which redirects
+to `login.html` when there's no session — that's for UX, not protection.
+
+Passwords are stored only as **bcrypt** hashes (`server/auth.py`). Roles are
+`admin` (may manage users) and `user`.
+
+### Set the signing secret
+
+Add `AUTH_SECRET_KEY` to `.env` (see `.env.example`). **Required in production** —
+without it the API uses a random per-process key, so logins reset on restart.
+
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(48))"
+```
+
+### Create the first admin
+
+The `/api/auth/users` endpoint needs an existing admin, so bootstrap one from a
+shell (run from the **project root**, like uvicorn):
+
+```bash
+python -m server.manage_users create-admin alice --name "Alice Smith"
+# prompts for a password (min 8 chars)
+```
+
+In Docker:
+
+```bash
+docker compose exec api python -m server.manage_users create-admin alice --name "Alice Smith"
+```
+
+Other commands: `create <user> --role user`, `list`, `reset-password <user>`,
+`disable <user>`, `enable <user>`. After that, admins can add users through the
+API (or you can keep using the CLI).
+
+---
+
 ## Local dev

 ```bash
@@ -237,14 +291,23 @@ docker compose down -v

 ## Quick test

-```bash
-curl -X POST http://127.0.0.1:8000/api/comments \
-  -H 'Content-Type: application/json' \
-  -d '{"type":"home_feedback","name":"Test","text":"hello"}'
+`/api/health` is open; data routes now require a session, so log in first and
+reuse the cookie jar:

-curl http://127.0.0.1:8000/api/comments
+```bash
+curl http://127.0.0.1:8000/api/health          # {"ok":true} — no auth needed
+
+# Sign in, saving the session cookie to a jar
+curl -c jar.txt -X POST http://127.0.0.1:8000/api/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"alice","password":"<password>"}'
+
+# Reuse the cookie on protected routes
+curl -b jar.txt http://127.0.0.1:8000/api/comments
 ```

+Without the cookie, protected routes return `401 {"detail":"Not authenticated"}`.
+
 Or via the nginx proxy (replace with your hostname):

 ```bash
--- a/server/app.py
+++ b/server/app.py
@@ -12,14 +12,16 @@ import os
 import uuid
 from typing import Any, Optional

-from fastapi import FastAPI, Depends, HTTPException, Query
+from fastapi import FastAPI, Depends, HTTPException, Query, Request, Response
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
 from pydantic import BaseModel, ConfigDict, Field
 from sqlalchemy import select, delete
 from sqlalchemy.orm import Session

 from .db import Base, engine, get_db
-from . import models
+from . import models, auth

 # Create tables on startup. (For schema changes later, switch to Alembic.)
 Base.metadata.create_all(bind=engine)
@@ -28,14 +30,28 @@ app = FastAPI(title="Work Package Suite API", docs_url="/api/docs", openapi_url=

 # Same-origin in production (NGINX), so CORS is normally unnecessary. For
 # cross-origin local dev, set CORS_ORIGINS="http://localhost:5500,..."
+# allow_credentials is required so the browser sends the session cookie.
 _origins = [o for o in os.getenv("CORS_ORIGINS", "").split(",") if o]
 if _origins:
    app.add_middleware(
-        CORSMiddleware, allow_origins=_origins,
+        CORSMiddleware, allow_origins=_origins, allow_credentials=True,
        allow_methods=["*"], allow_headers=["*"],
    )


+# ── Authentication gate ────────────────────────────────────────────────────────
+# Every /api/ data route requires a valid session cookie. Login, health, and the
+# docs are exempt (see auth._needs_auth). This is the real security boundary —
+# the static pages are only client-side guarded for UX. OPTIONS (CORS preflight)
+# is always allowed so the browser can negotiate before sending credentials.
+@app.middleware("http")
+async def auth_gate(request: Request, call_next):
+    if request.method != "OPTIONS" and auth._needs_auth(request.url.path):
+        if not auth.is_request_authenticated(request):
+            return JSONResponse(status_code=401, content={"detail": "Not authenticated"})
+    return await call_next(request)
+
+
 def gen_id(prefix: str) -> str:
    return f"{prefix}_{uuid.uuid4().hex[:12]}"

@@ -100,6 +116,139 @@ def health():
    return {"ok": True}


+# ── Authentication ─────────────────────────────────────────────────────────────
+class LoginIn(BaseModel):
+    username: str
+    password: str
+
+
+class NewUserIn(BaseModel):
+    username: str
+    password: str
+    full_name: str = ""
+    email: str = ""
+    role: str = "user"          # 'admin' | 'user'
+
+
+class PasswordChangeIn(BaseModel):
+    current_password: str
+    new_password: str
+
+
+class AdminPasswordIn(BaseModel):
+    new_password: str
+
+
+class ActiveIn(BaseModel):
+    is_active: bool
+
+
+@app.post("/api/auth/login")
+def login(body: LoginIn, request: Request, response: Response, db: Session = Depends(get_db)):
+    """Verify credentials and, on success, set the HttpOnly session cookie."""
+    user = auth.find_user(db, body.username)
+    # Always run a hash comparison to avoid leaking which usernames exist via
+    # response timing; verify_password tolerates an empty hash.
+    valid = auth.verify_password(body.password, user.password_hash if user else "")
+    if not user or not valid:
+        raise HTTPException(status_code=401, detail="Invalid username or password")
+    if not user.is_active:
+        raise HTTPException(status_code=403, detail="Account is disabled")
+    user.last_login_at = models.utcnow()
+    db.commit()
+    token = auth.create_token(user)
+    auth.set_session_cookie(response, request, token)
+    return {"user": user.to_dict()}
+
+
+@app.post("/api/auth/logout")
+def logout(response: Response):
+    auth.clear_session_cookie(response)
+    return {"ok": True}
+
+
+@app.get("/api/auth/me")
+def whoami(user: models.User = Depends(auth.get_current_user)):
+    """Who is logged in. The frontend guard calls this on every page load."""
+    return {"user": user.to_dict()}
+
+
+@app.post("/api/auth/password")
+def change_password(body: PasswordChangeIn, user: models.User = Depends(auth.get_current_user), db: Session = Depends(get_db)):
+    if not auth.verify_password(body.current_password, user.password_hash):
+        raise HTTPException(status_code=400, detail="Current password is incorrect")
+    if len(body.new_password) < 8:
+        raise HTTPException(status_code=400, detail="New password must be at least 8 characters")
+    user.password_hash = auth.hash_password(body.new_password)
+    db.commit()
+    return {"ok": True}
+
+
+# ── User administration (admin only) ────────────────────────────────────────────
+@app.get("/api/auth/users")
+def list_users(_admin: models.User = Depends(auth.require_admin), db: Session = Depends(get_db)):
+    rows = db.scalars(select(models.User).order_by(models.User.username)).all()
+    return [u.to_dict() for u in rows]
+
+
+@app.post("/api/auth/users")
+def create_user(body: NewUserIn, _admin: models.User = Depends(auth.require_admin), db: Session = Depends(get_db)):
+    if len(body.password) < 8:
+        raise HTTPException(status_code=400, detail="Password must be at least 8 characters")
+    if body.role not in ("admin", "user"):
+        raise HTTPException(status_code=400, detail="role must be 'admin' or 'user'")
+    if auth.find_user(db, body.username):
+        raise HTTPException(status_code=409, detail="A user with that username already exists")
+    u = models.User(
+        id=gen_id("user"),
+        username=body.username.strip(),
+        email=body.email.strip(),
+        full_name=body.full_name.strip(),
+        password_hash=auth.hash_password(body.password),
+        role=body.role,
+    )
+    db.add(u)
+    db.commit()
+    db.refresh(u)
+    return u.to_dict()
+
+
+@app.post("/api/auth/users/{user_id}/password")
+def admin_reset_password(user_id: str, body: AdminPasswordIn, _admin: models.User = Depends(auth.require_admin), db: Session = Depends(get_db)):
+    u = db.get(models.User, user_id)
+    if not u:
+        raise HTTPException(status_code=404, detail="User not found")
+    if len(body.new_password) < 8:
+        raise HTTPException(status_code=400, detail="Password must be at least 8 characters")
+    u.password_hash = auth.hash_password(body.new_password)
+    db.commit()
+    return {"ok": True}
+
+
+@app.post("/api/auth/users/{user_id}/active")
+def set_user_active(user_id: str, body: ActiveIn, admin: models.User = Depends(auth.require_admin), db: Session = Depends(get_db)):
+    u = db.get(models.User, user_id)
+    if not u:
+        raise HTTPException(status_code=404, detail="User not found")
+    if u.id == admin.id and not body.is_active:
+        raise HTTPException(status_code=400, detail="You cannot disable your own account")
+    u.is_active = body.is_active
+    db.commit()
+    return u.to_dict()
+
+
+@app.delete("/api/auth/users/{user_id}")
+def delete_user(user_id: str, admin: models.User = Depends(auth.require_admin), db: Session = Depends(get_db)):
+    u = db.get(models.User, user_id)
+    if not u:
+        raise HTTPException(status_code=404, detail="User not found")
+    if u.id == admin.id:
+        raise HTTPException(status_code=400, detail="You cannot delete your own account")
+    db.delete(u)
+    db.commit()
+    return {"deleted": user_id}
+
+
 # ── Projects ─────────────────────────────────────────────────────────────────
@app.post("/api/projects")
 def upsert_project(body: ProjectIn, db: Session = Depends(get_db)):
@@ -385,3 +534,16 @@ def list_comments(
        stmt = stmt.where(models.Comment.step == step)
    rows = db.scalars(stmt.order_by(models.Comment.created_at.desc())).all()
    return [c.to_dict() for c in rows]
+
+
+# ── Local dev convenience: serve the static site from this app ──────────────────
+# In production NGINX serves html/ and only proxies /api/ here, so this app never
+# receives "/" requests, and the api Docker image doesn't even include html/ — so
+# this mount stays inactive there. Locally (plain uvicorn, no NGINX) it lets you
+# open the whole suite at http://localhost:8000/ with the API on the SAME origin,
+# so the session cookie just works (no CORS, no Secure-cookie headache).
+#
+# Mounted LAST so the /api/* routes above always match first.
+_html_dir = os.path.join(os.path.dirname(__file__), "..", "html")
+if os.path.isdir(_html_dir):
+    app.mount("/", StaticFiles(directory=_html_dir, html=True), name="site")
--- a/server/auth.py
+++ b/server/auth.py
@@ -0,0 +1,186 @@
+"""Authentication for the Work Package Suite.
+
+A self-contained username/password login. Passwords are stored only as bcrypt
+hashes; a successful login issues a signed JWT that rides in an HttpOnly cookie
+(`wp_session`). Because the token is signed and self-validating, there is no
+server-side session store — every request is checked by verifying the cookie's
+signature and expiry (see `auth_gate` and `get_current_user`).
+
+Security model:
+  • The real boundary is `auth_gate` (middleware in app.py): every /api/ data
+    route is refused with 401 unless a valid session cookie is present.
+  • The cookie is HttpOnly (JS can't read it → XSS can't steal the session),
+    SameSite=Lax (blunts CSRF), and Secure whenever the request arrives over
+    HTTPS (detected via X-Forwarded-Proto behind NGINX).
+  • The signing secret comes from AUTH_SECRET_KEY. In production this MUST be
+    set; if it is missing we fall back to a random per-process key (which logs a
+    warning and invalidates every session on restart) so dev still works.
+
+Roles: 'admin' (may manage users) and 'user'.
+"""
+import os
+import secrets
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+import bcrypt
+import jwt
+from fastapi import Depends, HTTPException, Request, Response, status
+from sqlalchemy import select, func
+from sqlalchemy.orm import Session
+
+from .db import get_db
+from . import models
+
+log = logging.getLogger("wpsuite.auth")
+
+COOKIE_NAME = "wp_session"
+JWT_ALG = "HS256"
+# How long a login lasts before the user must sign in again.
+SESSION_HOURS = int(os.getenv("AUTH_SESSION_HOURS", "12"))
+
+# Paths under /api that do NOT require a session (login itself, health, docs).
+_EXEMPT_PREFIXES = ("/api/auth/",)
+_EXEMPT_EXACT = {
+    "/api/health",
+    "/api/docs",
+    "/api/openapi.json",
+    "/api/docs/oauth2-redirect",
+    "/api/redoc",
+}
+
+
+def _load_secret() -> str:
+    s = os.getenv("AUTH_SECRET_KEY")
+    if s:
+        return s
+    # No secret configured: generate an ephemeral one so the app still runs in
+    # dev. Sessions won't survive a restart, and this is unsafe across multiple
+    # workers — production must set AUTH_SECRET_KEY.
+    log.warning(
+        "AUTH_SECRET_KEY is not set — using a random ephemeral key. "
+        "Logins will reset on restart and break across multiple workers. "
+        "Set AUTH_SECRET_KEY in the environment for production."
+    )
+    return secrets.token_urlsafe(48)
+
+
+SECRET_KEY = _load_secret()
+
+
+# ── password hashing ──────────────────────────────────────────────────────────
+def hash_password(plain: str) -> str:
+    # bcrypt operates on at most 72 bytes; longer inputs are truncated by the
+    # algorithm. Encode explicitly so non-ASCII passwords hash consistently.
+    return bcrypt.hashpw(plain.encode("utf-8")[:72], bcrypt.gensalt()).decode("ascii")
+
+
+def verify_password(plain: str, hashed: str) -> bool:
+    if not hashed:
+        return False
+    try:
+        return bcrypt.checkpw(plain.encode("utf-8")[:72], hashed.encode("ascii"))
+    except (ValueError, TypeError):
+        return False
+
+
+# ── tokens ──────────────────────────────────────────────────────────────────
+def create_token(user: "models.User") -> str:
+    now = datetime.now(timezone.utc)
+    payload = {
+        "sub": user.id,
+        "username": user.username,
+        "role": user.role,
+        "iat": now,
+        "exp": now + timedelta(hours=SESSION_HOURS),
+    }
+    return jwt.encode(payload, SECRET_KEY, algorithm=JWT_ALG)
+
+
+def decode_token(token: str) -> Optional[dict]:
+    """Return the token claims if the signature and expiry are valid, else None."""
+    try:
+        return jwt.decode(token, SECRET_KEY, algorithms=[JWT_ALG])
+    except jwt.PyJWTError:
+        return None
+
+
+# ── cookie helpers ────────────────────────────────────────────────────────────
+def _is_https(request: Request) -> bool:
+    # Behind NGINX, TLS is terminated at the proxy and forwarded as plain HTTP,
+    # so trust X-Forwarded-Proto (set in nginx-wp-suite.conf) when present.
+    xfp = request.headers.get("x-forwarded-proto", "")
+    if xfp:
+        return xfp.split(",")[0].strip().lower() == "https"
+    return request.url.scheme == "https"
+
+
+def set_session_cookie(response: Response, request: Request, token: str) -> None:
+    response.set_cookie(
+        key=COOKIE_NAME,
+        value=token,
+        max_age=SESSION_HOURS * 3600,
+        httponly=True,
+        secure=_is_https(request),
+        samesite="lax",
+        path="/",
+    )
+
+
+def clear_session_cookie(response: Response) -> None:
+    response.delete_cookie(COOKIE_NAME, path="/")
+
+
+# ── request gate (used as middleware in app.py) ─────────────────────────────────
+def _needs_auth(path: str) -> bool:
+    if not path.startswith("/api/"):
+        return False  # static assets are served by NGINX, not this app
+    if path in _EXEMPT_EXACT:
+        return False
+    return not any(path.startswith(p) for p in _EXEMPT_PREFIXES)
+
+
+def is_request_authenticated(request: Request) -> Optional[dict]:
+    """Validate the session cookie on a raw request. Returns claims or None.
+    Used by the middleware gate, which has no dependency-injection context."""
+    token = request.cookies.get(COOKIE_NAME)
+    if not token:
+        return None
+    return decode_token(token)
+
+
+# ── dependencies (used inside route handlers) ───────────────────────────────────
+def get_current_user(request: Request, db: Session = Depends(get_db)) -> "models.User":
+    """Resolve the logged-in user from the session cookie, or raise 401.
+
+    Unlike the middleware gate (which only checks the token signature), this also
+    confirms the account still exists and is active — so disabling a user takes
+    effect on their next request."""
+    claims = is_request_authenticated(request)
+    if not claims:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Not authenticated")
+    user = db.get(models.User, claims.get("sub"))
+    if not user or not user.is_active:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Account is inactive")
+    return user
+
+
+def require_admin(user: "models.User" = Depends(get_current_user)) -> "models.User":
+    if user.role != "admin":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Admin access required")
+    return user
+
+
+# ── account helpers (shared by routes and the CLI) ──────────────────────────────
+def find_user(db: Session, username: str) -> Optional["models.User"]:
+    """Look up by username, case-insensitively (also matches on email)."""
+    uname = (username or "").strip().lower()
+    if not uname:
+        return None
+    return db.scalars(
+        select(models.User).where(
+            (func.lower(models.User.username) == uname)
+            | (func.lower(models.User.email) == uname)
+        )
+    ).first()
--- a/server/manage_users.py
+++ b/server/manage_users.py
@@ -0,0 +1,144 @@
+"""Command-line user management for the Work Package Suite.
+
+Use this to create the FIRST admin account (the /api/auth/users endpoint needs an
+existing admin, so you have to bootstrap one here), and for occasional account
+maintenance from a shell on the server.
+
+Run from the PROJECT ROOT (same place you run uvicorn), so the package imports
+and .env resolve the same way the API does:
+
+    python -m server.manage_users create-admin alice --name "Alice Smith"
+    python -m server.manage_users create bob --role user --name "Bob Jones"
+    python -m server.manage_users list
+    python -m server.manage_users reset-password alice
+    python -m server.manage_users disable bob
+    python -m server.manage_users enable bob
+
+If --password is omitted you'll be prompted (input is hidden). Passwords must be
+at least 8 characters.
+"""
+import argparse
+import getpass
+import sys
+import uuid
+
+from .db import SessionLocal, Base, engine
+from . import models, auth
+
+
+def _gen_id() -> str:
+    return f"user_{uuid.uuid4().hex[:12]}"
+
+
+def _prompt_password(provided: str | None) -> str:
+    pw = provided
+    if not pw:
+        pw = getpass.getpass("New password: ")
+        confirm = getpass.getpass("Confirm password: ")
+        if pw != confirm:
+            sys.exit("Passwords do not match.")
+    if len(pw) < 8:
+        sys.exit("Password must be at least 8 characters.")
+    return pw
+
+
+def cmd_create(args, role: str | None = None) -> None:
+    role = role or args.role
+    if role not in ("admin", "user"):
+        sys.exit("role must be 'admin' or 'user'")
+    pw = _prompt_password(getattr(args, "password", None))
+    with SessionLocal() as db:
+        if auth.find_user(db, args.username):
+            sys.exit(f"A user named '{args.username}' already exists.")
+        u = models.User(
+            id=_gen_id(),
+            username=args.username.strip(),
+            full_name=(args.name or "").strip(),
+            email=(args.email or "").strip(),
+            password_hash=auth.hash_password(pw),
+            role=role,
+        )
+        db.add(u)
+        db.commit()
+        print(f"Created {role}: {u.username}  (id={u.id})")
+
+
+def cmd_list(args) -> None:
+    with SessionLocal() as db:
+        rows = db.query(models.User).order_by(models.User.username).all()
+        if not rows:
+            print("No users yet. Create one with: create-admin <username>")
+            return
+        print(f"{'USERNAME':<24}{'ROLE':<8}{'ACTIVE':<8}{'NAME'}")
+        for u in rows:
+            print(f"{u.username:<24}{u.role:<8}{('yes' if u.is_active else 'no'):<8}{u.full_name}")
+
+
+def cmd_reset_password(args) -> None:
+    pw = _prompt_password(getattr(args, "password", None))
+    with SessionLocal() as db:
+        u = auth.find_user(db, args.username)
+        if not u:
+            sys.exit(f"No user named '{args.username}'.")
+        u.password_hash = auth.hash_password(pw)
+        db.commit()
+        print(f"Password reset for {u.username}.")
+
+
+def _set_active(username: str, active: bool) -> None:
+    with SessionLocal() as db:
+        u = auth.find_user(db, username)
+        if not u:
+            sys.exit(f"No user named '{username}'.")
+        u.is_active = active
+        db.commit()
+        print(f"{u.username} is now {'enabled' if active else 'disabled'}.")
+
+
+def main() -> None:
+    # Ensure the users table exists even on a fresh database.
+    Base.metadata.create_all(bind=engine)
+
+    p = argparse.ArgumentParser(prog="manage_users", description="Work Package Suite user management")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def add_create(name, help_):
+        sp = sub.add_parser(name, help=help_)
+        sp.add_argument("username")
+        sp.add_argument("--password", help="set non-interactively (otherwise prompted)")
+        sp.add_argument("--name", default="", help="full name")
+        sp.add_argument("--email", default="")
+        return sp
+
+    add_create("create-admin", "create an admin account")
+    c = add_create("create", "create an account")
+    c.add_argument("--role", choices=["admin", "user"], default="user")
+
+    sub.add_parser("list", help="list all accounts")
+
+    rp = sub.add_parser("reset-password", help="reset a user's password")
+    rp.add_argument("username")
+    rp.add_argument("--password", help="set non-interactively (otherwise prompted)")
+
+    dp = sub.add_parser("disable", help="disable an account (blocks login)")
+    dp.add_argument("username")
+    ep = sub.add_parser("enable", help="re-enable an account")
+    ep.add_argument("username")
+
+    args = p.parse_args()
+    if args.cmd == "create-admin":
+        cmd_create(args, role="admin")
+    elif args.cmd == "create":
+        cmd_create(args)
+    elif args.cmd == "list":
+        cmd_list(args)
+    elif args.cmd == "reset-password":
+        cmd_reset_password(args)
+    elif args.cmd == "disable":
+        _set_active(args.username, False)
+    elif args.cmd == "enable":
+        _set_active(args.username, True)
+
+
+if __name__ == "__main__":
+    main()
--- a/server/models.py
+++ b/server/models.py
@@ -111,6 +111,32 @@ class WorkPackage(Base):
        return {**self.summary(), "data": self.data or {}}


+class User(Base):
+    """A login account. Passwords are never stored in the clear — only a bcrypt
+    hash (see server/auth.py). `username` is what people sign in with; `role` is
+    either 'admin' (can manage users) or 'user'."""
+    __tablename__ = "users"
+
+    id: Mapped[str] = mapped_column(String(40), primary_key=True)
+    username: Mapped[str] = mapped_column(String(120), unique=True, index=True)
+    email: Mapped[str] = mapped_column(String(200), default="")
+    full_name: Mapped[str] = mapped_column(String(200), default="")
+    password_hash: Mapped[str] = mapped_column(String(200), default="")
+    role: Mapped[str] = mapped_column(String(20), default="user")  # 'admin' | 'user'
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow, onupdate=utcnow)
+    last_login_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    def to_dict(self) -> dict:
+        """Public view of a user — NEVER includes the password hash."""
+        return {
+            "id": self.id, "username": self.username, "email": self.email,
+            "full_name": self.full_name, "role": self.role, "is_active": self.is_active,
+            "created_at": _iso(self.created_at), "last_login_at": _iso(self.last_login_at),
+        }
+
+
 class Comment(Base):
    __tablename__ = "comments"

--- a/server/requirements.txt
+++ b/server/requirements.txt
@@ -5,3 +5,5 @@ sqlalchemy>=2.0
 psycopg[binary]>=3.1
 pydantic>=2.6
 python-dotenv>=1.0
+bcrypt>=4.1          # password hashing
+PyJWT>=2.8           # signed session tokens