diff --git a/.env.example b/.env.example index 4826da7..e4ee686 100644 --- a/.env.example +++ b/.env.example @@ -20,3 +20,8 @@ ADMIN_PASSWORD=change_me_strong_password_here # Set to true only for local development (exposes /api/docs, /api/redoc) DOCS_ENABLED=false + +# Ntfy push notifications for super admin alerts (optional) +# Use https://ntfy.sh/your-secret-topic or self-hosted URL +NTFY_URL= +NTFY_TOKEN= diff --git a/README.md b/README.md index 5382319..ac17701 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ A self-hosted web app for managing homeschool schedules, tracking daily learning - **Password Change** — Users can change their own account password from Admin → Settings → Reset Password. The form requires the current password before accepting a new one. - **Multi-Child Support** — Manage multiple students under one parent account, each with their own color, schedule, and history. - **JWT Authentication** — Secure parent login with access tokens and httpOnly refresh cookies. TV dashboard is public (no login required). Disabled accounts receive a clear error message explaining the account is disabled rather than a generic "invalid credentials" response. After **5 consecutive failed login attempts**, an account is locked for **15 minutes** — the error message includes the remaining wait time. Locks clear automatically after the cooldown, or immediately when a super admin resets the account's password. +- **Ntfy Push Notifications** — Optional push notifications delivered to the super admin via [Ntfy](https://ntfy.sh). Alerts are sent for: new user registration, account lockout after 5 failed login attempts, and login attempts on an already-locked account. Works with ntfy.sh (public or self-hosted). Configure via `NTFY_URL` and optionally `NTFY_TOKEN` in `.env`. - **Super Admin Panel** — A separate admin interface (at `/super-admin`) for site-wide management. Log in with a dedicated admin username and password (set in `.env`). Provides full control over all registered parent accounts: - **Impersonate** — Enter any user's session to view and manage their data. An impersonation banner is shown at the top of every page with a one-click "Exit to Admin Panel" button. - **Reset Password** — Set a new password for any user without needing the current password. Also clears any active login lockout on the account. @@ -168,6 +169,11 @@ ADMIN_PASSWORD=change_me_admin_password # Set to true only for local development (exposes /api/docs, /api/redoc) DOCS_ENABLED=false + +# Ntfy push notifications for super admin alerts (optional) +# Use https://ntfy.sh/your-secret-topic or a self-hosted Ntfy server +NTFY_URL= +NTFY_TOKEN= ``` ### 3. Build and start @@ -346,6 +352,8 @@ The TV dashboard connects to `ws://host/ws/{tv_token}` (using the child's 6-digi | `ADMIN_USERNAME` | No | Super admin login username (default: `admin`) | | `ADMIN_PASSWORD` | No | Super admin login password (default: `change_me_admin_password`) | | `DOCS_ENABLED` | No | Set to `true` to enable `/api/docs` and `/api/redoc` (default: `false`). Recommended only for local development. | +| `NTFY_URL` | No | Full Ntfy topic URL (e.g. `https://ntfy.sh/your-secret-topic`). Leave blank to disable notifications. | +| `NTFY_TOKEN` | No | Bearer token for a protected Ntfy topic. Leave blank for public topics. | > **Note:** `ADMIN_USERNAME` and `ADMIN_PASSWORD` must be set in `.env` **and** listed in the `backend` service's `environment` block in `docker-compose.yml`. Changing them in `.env` alone is not sufficient — the backend container reads them as environment variables, not from the file directly. diff --git a/backend/app/config.py b/backend/app/config.py index 836505f..8a1f2a0 100644 --- a/backend/app/config.py +++ b/backend/app/config.py @@ -12,6 +12,8 @@ class Settings(BaseSettings): admin_username: str = "admin" admin_password: str # no default — must be explicitly set in .env docs_enabled: bool = False + ntfy_url: str = "" # e.g. https://ntfy.sh/your-secret-topic + ntfy_token: str = "" # optional Bearer token if topic is protected @property def cors_origins_list(self) -> list[str]: diff --git a/backend/app/routers/auth.py b/backend/app/routers/auth.py index b649f3f..412ce4a 100644 --- a/backend/app/routers/auth.py +++ b/backend/app/routers/auth.py @@ -18,6 +18,7 @@ from app.models.user import User from app.models.subject import Subject from app.schemas.auth import LoginRequest, RegisterRequest, TokenResponse from app.schemas.user import UserOut +from app.utils.ntfy import notify router = APIRouter(prefix="/api/auth", tags=["auth"]) @@ -57,6 +58,14 @@ async def register(body: RegisterRequest, response: Response, db: AsyncSession = access = create_access_token({"sub": str(user.id)}) refresh = create_refresh_token({"sub": str(user.id)}) response.set_cookie(REFRESH_COOKIE, refresh, **COOKIE_OPTS) + + await notify( + title="New User Registered", + message=f"{body.full_name} ({body.email})", + priority="default", + tags=["bust_in_silhouette"], + ) + return TokenResponse(access_token=access) @@ -76,6 +85,12 @@ async def login(body: LoginRequest, response: Response, db: AsyncSession = Depen if user.locked_until and user.locked_until > now: remaining = int((user.locked_until - now).total_seconds() / 60) + 1 logger.warning("Locked account login attempt for email=%s", body.email) + await notify( + title="Login Attempt on Locked Account", + message=f"{body.email} — locked for {remaining} more minute(s)", + priority="high", + tags=["lock"], + ) raise HTTPException(status_code=429, detail=f"Account locked. Try again in {remaining} minute(s).") if not user.is_active: @@ -87,6 +102,12 @@ async def login(body: LoginRequest, response: Response, db: AsyncSession = Depen if user.failed_login_attempts >= _LOGIN_MAX_ATTEMPTS: user.locked_until = now + timedelta(minutes=_LOGIN_LOCKOUT_MINUTES) logger.warning("Account locked for email=%s after %d failed attempts", body.email, user.failed_login_attempts) + await notify( + title="Account Locked", + message=f"{body.email} locked after {user.failed_login_attempts} failed attempts", + priority="urgent", + tags=["warning"], + ) else: logger.warning("Failed login attempt %d/%d for email=%s", user.failed_login_attempts, _LOGIN_MAX_ATTEMPTS, body.email) await db.commit() diff --git a/backend/app/utils/ntfy.py b/backend/app/utils/ntfy.py new file mode 100644 index 0000000..c8c3ff7 --- /dev/null +++ b/backend/app/utils/ntfy.py @@ -0,0 +1,25 @@ +import logging +import httpx +from app.config import get_settings + +logger = logging.getLogger("homeschool.ntfy") + + +async def notify(title: str, message: str, priority: str = "default", tags: list[str] | None = None) -> None: + """Fire-and-forget notification to Ntfy. Silently logs errors — never raises.""" + settings = get_settings() + if not settings.ntfy_url: + return + + headers = {"Title": title, "Priority": priority} + if tags: + headers["Tags"] = ",".join(tags) + if settings.ntfy_token: + headers["Authorization"] = f"Bearer {settings.ntfy_token}" + + try: + async with httpx.AsyncClient(timeout=5) as client: + resp = await client.post(settings.ntfy_url, content=message, headers=headers) + resp.raise_for_status() + except Exception as exc: + logger.warning("Ntfy notification failed: %s", exc) diff --git a/backend/requirements.txt b/backend/requirements.txt index 864272f..0ee5a93 100644 --- a/backend/requirements.txt +++ b/backend/requirements.txt @@ -10,3 +10,4 @@ pydantic-settings==2.5.2 alembic==1.13.3 python-multipart==0.0.22 email-validator==2.2.0 +httpx==0.27.2 diff --git a/docker-compose.yml b/docker-compose.yml index 22ab759..0084aae 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -33,6 +33,8 @@ services: CORS_ORIGINS: ${CORS_ORIGINS:-http://localhost:8057} ADMIN_USERNAME: ${ADMIN_USERNAME} ADMIN_PASSWORD: ${ADMIN_PASSWORD} + NTFY_URL: ${NTFY_URL:-} + NTFY_TOKEN: ${NTFY_TOKEN:-} depends_on: db: condition: service_healthy