refactor: migrate admin auth from HTTP Basic to Flask-Login sessions

Replaces browser-cached Basic Auth credentials with proper server-side
session management. Logout now fully invalidates the session. Adds an
HTML login form at /admin/login, SECRET_KEY env var support, and updates
README with key generation instructions and role table.

.github/workflows/docker-image.yml

@@ -30,3 +30,15 @@ jobs:
         run: |
           docker tag $IMAGE_TAG snachodog/kiosk-guestbook:latest
           docker push snachodog/kiosk-guestbook:latest
+      - name: Notify via ntfy
+        if: github.event_name == 'push'
+        env:
+          NTFY_URL: ${{ secrets.NTFY_URL }}
+          NTFY_TOKEN: ${{ secrets.NTFY_TOKEN }}
+        run: |
+          curl -s -o /dev/null \
+            -H "Title: kiosk-guestbook image pushed to Docker Hub" \
+            -H "Tags: white_check_mark" \
+            -H "Authorization: Bearer $NTFY_TOKEN" \
+            -d "The kiosk-guestbook container has been pushed to Docker Hub and is ready to pull. Commit: ${{ github.sha }} — ${{ github.event.head_commit.message }}" \
+            "$NTFY_URL"

Dockerfile

@@ -4,8 +4,8 @@ FROM python:3.9-slim
 # Set the working directory
 WORKDIR /app
 
-# Install system dependencies (including gettext for envsubst)
-RUN apt-get update && apt-get install -y gettext && rm -rf /var/lib/apt/lists/*
+# Install system dependencies (including gettext for envsubst and gosu for privilege dropping)
+RUN apt-get update && apt-get install -y gettext gosu && rm -rf /var/lib/apt/lists/*
 
 # Install Python dependencies
 COPY requirements.txt .
@@ -30,7 +30,7 @@ ARG UID=1000
 ARG GID=1000
 RUN groupadd -g ${GID} appuser && useradd -u ${UID} -g ${GID} -s /bin/sh -M appuser
 RUN chown -R appuser:appuser /app /entrypoint.sh
-USER appuser
+# Entrypoint runs as root, fixes volume permissions, then drops to appuser via gosu
 
 # Use the entrypoint script as the container's command
 CMD ["/entrypoint.sh"]

README.md

@@ -96,13 +96,64 @@ Once deployed, open your browser and navigate to http://<your-server-ip>:8000 (o
 
 `docker-compose logs -f`
 
+## Admin Interface
+
+A password-protected admin panel is available at `/admin`. It displays all guest entries in a paginated table and allows individual entries to be deleted. Authentication uses session cookies with an HTML login form — logging out fully invalidates the session so credentials are never cached by the browser.
+
+Access requires `ADMIN_USER`, `ADMIN_PASSWORD`, and `SECRET_KEY` to be set in your `.env`. If either of the admin credentials are missing the interface returns 503. If `SECRET_KEY` is not set a default development key is used, which is insecure in production — always set your own.
+
+### Generating a `SECRET_KEY`
+
+Use Python to generate a cryptographically random key:
+
+```bash
+python3 -c "import secrets; print(secrets.token_hex(32))"
+```
+
+Paste the output as the value for `SECRET_KEY` in your `.env`.
+
+### User Roles
+
+The bootstrap superadmin (set via `ADMIN_USER` / `ADMIN_PASSWORD`) can manage additional users at `/admin/users`:
+
+| Role       | View entries | Delete entries | Manage users |
+| ---------- | :----------: | :------------: | :----------: |
+| superadmin | ✓            | ✓              | ✓            |
+| admin      | ✓            | ✓              | —            |
+| viewer     | ✓            | —              | —            |
+
 ## API Access
 
 Access the API endpoint to export guest entries by navigating to:
 
-`http://your-server-ip:8000/guests/api`
+`http://your-server-ip:8000/api/guests`
 
-This endpoint can be integrated with on-prem automation tools like n8n.
+Set the `API_KEY` variable in your `.env` and pass it in requests as the `X-API-Key` header. This endpoint can be integrated with on-prem automation tools like n8n.
+
+## Upgrading
+
+When upgrading from a previous version, compare your `.env` against `example.env` to check for newly required variables.
+
+As of **v2.1.0**, the following variables are required for the admin interface:
+
+```env
+ADMIN_USER=admin
+ADMIN_PASSWORD=changeme
+```
+
+As of **v2.3.0**, a `SECRET_KEY` is also required for session-based authentication:
+
+```env
+SECRET_KEY=your-random-secret-key-here
+```
+
+Generate one with:
+
+```bash
+python3 -c "import secrets; print(secrets.token_hex(32))"
+```
+
+Replace all placeholder values with your own before deploying.
 
 ## Additional Notes
 

app.py

@@ -1,11 +1,16 @@
-from flask import Flask, render_template, request, redirect, url_for, jsonify, abort
-from flask_limiter import Limiter
-from flask_limiter.util import get_remote_address
-from email_validator import validate_email, EmailNotValidError
-import sqlite3
 import logging
 import os
 import re
+import sqlite3
+
+from email_validator import validate_email, EmailNotValidError
+from flask import Flask, render_template, request, redirect, url_for, jsonify, abort
+from flask_limiter import Limiter
+from flask_limiter.util import get_remote_address
+from flask_login import (
+    LoginManager, UserMixin, login_user, logout_user, login_required, current_user
+)
+from werkzeug.security import generate_password_hash, check_password_hash
 
 # Set up logging
 logging.basicConfig(level=logging.INFO)
@@ -13,8 +18,53 @@ logger = logging.getLogger(__name__)
 
 app = Flask(__name__)
 DATABASE = os.environ.get('DATABASE_PATH', 'guestbook.db')
+app.secret_key = os.environ.get('SECRET_KEY', 'dev-secret-key-change-in-production')
+
 limiter = Limiter(get_remote_address, app=app, default_limits=[])
 
+login_manager = LoginManager(app)
+login_manager.login_view = 'admin_login'
+
+# ---------------------------------------------------------------------------
+# User model
+# ---------------------------------------------------------------------------
+
+class User(UserMixin):
+    """Lightweight user object stored in the session."""
+    def __init__(self, user_id, username, role):
+        # user_id format: 's:<username>' for superadmin, 'u:<db_id>' for DB users
+        self.id = user_id
+        self.username = username
+        self.role = role
+
+
+@login_manager.user_loader
+def load_user(user_id):
+    if user_id.startswith('s:'):
+        username = user_id[2:]
+        admin_user = os.environ.get('ADMIN_USER')
+        if admin_user and username == admin_user:
+            return User(user_id, username, 'superadmin')
+        return None
+    if user_id.startswith('u:'):
+        db_id = user_id[2:]
+        try:
+            conn = sqlite3.connect(DATABASE)
+            c = conn.cursor()
+            row = c.execute(
+                'SELECT id, username, role FROM users WHERE id = ?', (db_id,)
+            ).fetchone()
+            conn.close()
+            if row:
+                return User(f'u:{row[0]}', row[1], row[2])
+        except sqlite3.Error as e:
+            logger.error("Database error in user_loader: %s", e)
+    return None
+
+# ---------------------------------------------------------------------------
+# Profanity filter
+# ---------------------------------------------------------------------------
+
 def load_banned_words():
     banned_words = set()
     file_path = os.path.join(os.path.dirname(__file__), 'en.txt')
@@ -51,6 +101,10 @@ def contains_banned_words(text):
             return True
     return False
 
+# ---------------------------------------------------------------------------
+# Database migrations
+# ---------------------------------------------------------------------------
+
 # Each entry is a list of SQL statements for that schema version.
 # To add a column or index in the future, append a new list — never modify existing entries.
 MIGRATIONS = [
@@ -69,6 +123,15 @@ MIGRATIONS = [
         'CREATE INDEX IF NOT EXISTS idx_guests_id ON guests (id DESC)',
         'CREATE INDEX IF NOT EXISTS idx_guests_email ON guests (email)',
     ],
+    # v2 — user accounts for admin interface (role: 'admin' or 'viewer')
+    [
+        '''CREATE TABLE IF NOT EXISTS users (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            username TEXT NOT NULL UNIQUE,
+            password_hash TEXT NOT NULL,
+            role TEXT NOT NULL CHECK(role IN ('admin', 'viewer'))
+        )''',
+    ],
 ]
 
 def migrate_db():
@@ -110,6 +173,10 @@ def is_valid_email(email):
 with app.app_context():
     migrate_db()
 
+# ---------------------------------------------------------------------------
+# Public routes
+# ---------------------------------------------------------------------------
+
 @app.route('/', methods=['GET', 'POST'])
 @limiter.limit("5 per minute", methods=["POST"])
 def index():
@@ -177,6 +244,168 @@ def index():
     logger.info("Rendering index with %d guests.", len(guests))
     return render_template('index.html', error=error, guests=guests)
 
+# ---------------------------------------------------------------------------
+# Admin auth routes
+# ---------------------------------------------------------------------------
+
+def _admin_configured():
+    return bool(os.environ.get('ADMIN_USER') and os.environ.get('ADMIN_PASSWORD'))
+
+@app.route('/admin/login', methods=['GET', 'POST'])
+def admin_login():
+    if not _admin_configured():
+        abort(503)
+    if current_user.is_authenticated:
+        return redirect(url_for('admin'))
+    error = None
+    if request.method == 'POST':
+        username = request.form.get('username', '').strip()
+        password = request.form.get('password', '').strip()
+        admin_user = os.environ.get('ADMIN_USER')
+        admin_password = os.environ.get('ADMIN_PASSWORD')
+        # Check superadmin first
+        if admin_user and username == admin_user and password == admin_password:
+            login_user(User(f's:{username}', username, 'superadmin'))
+            logger.info("Superadmin '%s' logged in.", username)
+            return redirect(request.args.get('next') or url_for('admin'))
+        # Check DB users
+        try:
+            conn = sqlite3.connect(DATABASE)
+            c = conn.cursor()
+            row = c.execute(
+                'SELECT id, password_hash, role FROM users WHERE username = ?', (username,)
+            ).fetchone()
+            conn.close()
+            if row and check_password_hash(row[1], password):
+                login_user(User(f'u:{row[0]}', username, row[2]))
+                logger.info("User '%s' (role=%s) logged in.", username, row[2])
+                return redirect(request.args.get('next') or url_for('admin'))
+        except sqlite3.Error as e:
+            logger.error("Database error during login: %s", e)
+        error = 'Invalid username or password.'
+        logger.warning("Failed login attempt for username '%s'.", username)
+    return render_template('admin_login.html', error=error)
+
+@app.route('/admin/logout')
+def admin_logout():
+    logout_user()
+    return redirect(url_for('admin_login'))
+
+# ---------------------------------------------------------------------------
+# Admin routes
+# ---------------------------------------------------------------------------
+
+@app.route('/admin')
+@login_required
+def admin():
+    if not _admin_configured():
+        abort(503)
+    page = request.args.get('page', 1, type=int)
+    per_page = 25
+    offset = (page - 1) * per_page
+    try:
+        conn = sqlite3.connect(DATABASE)
+        c = conn.cursor()
+        total = c.execute('SELECT COUNT(*) FROM guests').fetchone()[0]
+        c.execute('''
+            SELECT id, first_name, last_name, email, location, comment, newsletter_opt_in, timestamp
+            FROM guests ORDER BY id DESC LIMIT ? OFFSET ?
+        ''', (per_page, offset))
+        guests = c.fetchall()
+        conn.close()
+    except sqlite3.Error as e:
+        logger.error("Database error in admin: %s", e)
+        guests = []
+        total = 0
+    total_pages = (total + per_page - 1) // per_page
+    return render_template('admin.html', guests=guests, page=page, total_pages=total_pages,
+                           total=total)
+
+@app.route('/admin/delete/<int:entry_id>', methods=['POST'])
+@login_required
+def admin_delete(entry_id):
+    if not _admin_configured():
+        abort(503)
+    if current_user.role == 'viewer':
+        abort(403)
+    try:
+        conn = sqlite3.connect(DATABASE)
+        c = conn.cursor()
+        c.execute('DELETE FROM guests WHERE id = ?', (entry_id,))
+        conn.commit()
+        conn.close()
+        logger.info("Admin deleted guest entry id=%d", entry_id)
+    except sqlite3.Error as e:
+        logger.error("Database error deleting guest %d: %s", entry_id, e)
+    return redirect(url_for('admin', page=request.args.get('page', 1)))
+
+@app.route('/admin/users')
+@login_required
+def admin_users():
+    if not _admin_configured():
+        abort(503)
+    if current_user.role != 'superadmin':
+        abort(403)
+    try:
+        conn = sqlite3.connect(DATABASE)
+        c = conn.cursor()
+        users = c.execute('SELECT id, username, role FROM users ORDER BY username').fetchall()
+        conn.close()
+    except sqlite3.Error as e:
+        logger.error("Database error in admin_users: %s", e)
+        users = []
+    return render_template('admin_users.html', users=users)
+
+@app.route('/admin/users/add', methods=['POST'])
+@login_required
+def admin_users_add():
+    if not _admin_configured():
+        abort(503)
+    if current_user.role != 'superadmin':
+        abort(403)
+    username = request.form.get('username', '').strip()
+    password = request.form.get('password', '').strip()
+    role = request.form.get('role', '').strip()
+    if not username or not password or role not in ('admin', 'viewer'):
+        return redirect(url_for('admin_users'))
+    try:
+        conn = sqlite3.connect(DATABASE)
+        c = conn.cursor()
+        c.execute(
+            'INSERT INTO users (username, password_hash, role) VALUES (?, ?, ?)',
+            (username, generate_password_hash(password), role)
+        )
+        conn.commit()
+        conn.close()
+        logger.info("Superadmin added user '%s' with role '%s'", username, role)
+    except sqlite3.IntegrityError:
+        logger.warning("Attempted to add duplicate username '%s'", username)
+    except sqlite3.Error as e:
+        logger.error("Database error adding user: %s", e)
+    return redirect(url_for('admin_users'))
+
+@app.route('/admin/users/delete/<int:user_id>', methods=['POST'])
+@login_required
+def admin_users_delete(user_id):
+    if not _admin_configured():
+        abort(503)
+    if current_user.role != 'superadmin':
+        abort(403)
+    try:
+        conn = sqlite3.connect(DATABASE)
+        c = conn.cursor()
+        c.execute('DELETE FROM users WHERE id = ?', (user_id,))
+        conn.commit()
+        conn.close()
+        logger.info("Superadmin deleted user id=%d", user_id)
+    except sqlite3.Error as e:
+        logger.error("Database error deleting user %d: %s", user_id, e)
+    return redirect(url_for('admin_users'))
+
+# ---------------------------------------------------------------------------
+# API
+# ---------------------------------------------------------------------------
+
 @app.route('/api/guests', methods=['GET'])
 def api_guests():
     api_key = request.headers.get('X-API-Key')

entrypoint.sh

@@ -1,7 +1,12 @@
 #!/bin/sh
+# Fix ownership of the data directory so appuser can write the database.
+# This runs as root (no USER directive in Dockerfile) and is safe because
+# we immediately drop privileges via gosu before starting the app.
+DATA_DIR=$(dirname "${DATABASE_PATH:-/data/guestbook.db}")
+chown -R appuser:appuser "$DATA_DIR"
+
 # Process index.html.template to create index.html
-# Adjust the path if your template is located somewhere else
 envsubst < /app/templates/index.html.template > /app/templates/index.html
 
-# Start Gunicorn; using an environment variable for workers (default is 3)
-exec gunicorn --bind 0.0.0.0:8000 app:app --workers ${GUNICORN_WORKERS:-3}
+# Drop to appuser and start Gunicorn
+exec gosu appuser gunicorn --bind 0.0.0.0:8000 app:app --workers ${GUNICORN_WORKERS:-3}

example.env

@@ -10,3 +10,6 @@ PID=1000
 GID=1000
 SITE_TITLE="The Montana Dinosaur Center Visitor Log"
 LOGO_URL="/static/images/logo.png"
+ADMIN_USER=admin
+ADMIN_PASSWORD=changeme
+SECRET_KEY=change-this-to-a-random-secret-key

requirements.txt

@@ -1,5 +1,6 @@
 Flask>=3.1.3
 Werkzeug>=3.0.6
 Flask-Limiter>=3.0
+Flask-Login>=0.6
 email-validator>=2.0
 gunicorn

templates/admin.html

@@ -0,0 +1,83 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Guestbook Admin</title>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" />
+</head>
+<body class="bg-light">
+    <div class="container py-4">
+        <div class="d-flex justify-content-between align-items-center mb-4">
+            <h1 class="h3 mb-0">Guestbook Admin</h1>
+            <div class="d-flex align-items-center gap-3">
+                <span class="text-muted">{{ current_user.username }} &middot; {{ total }} entries</span>
+                {% if current_user.role == 'superadmin' %}
+                <a href="{{ url_for('admin_users') }}" class="btn btn-outline-secondary btn-sm">Manage Users</a>
+                {% endif %}
+                <a href="{{ url_for('admin_logout') }}" class="btn btn-outline-danger btn-sm">Logout</a>
+            </div>
+        </div>
+
+        <div class="table-responsive">
+            <table class="table table-bordered table-hover bg-white">
+                <thead class="table-dark">
+                    <tr>
+                        <th>ID</th>
+                        <th>Name</th>
+                        <th>Email</th>
+                        <th>Location</th>
+                        <th>Comment</th>
+                        <th>Newsletter</th>
+                        <th>Timestamp</th>
+                        <th></th>
+                    </tr>
+                </thead>
+                <tbody>
+                    {% for g in guests %}
+                    <tr>
+                        <td class="text-muted">{{ g[0] }}</td>
+                        <td>{{ g[1] }} {{ g[2] }}</td>
+                        <td>{{ g[3] or '—' }}</td>
+                        <td>{{ g[4] }}</td>
+                        <td>{{ g[5] or '—' }}</td>
+                        <td>{{ 'Yes' if g[6] else 'No' }}</td>
+                        <td class="text-nowrap">{{ g[7] }}</td>
+                        <td>
+                            {% if current_user.role != 'viewer' %}
+                            <form method="POST" action="{{ url_for('admin_delete', entry_id=g[0]) }}?page={{ page }}"
+                                  onsubmit="return confirm('Delete entry for {{ g[1] }} {{ g[2] }}?')">
+                                <button type="submit" class="btn btn-danger btn-sm">Delete</button>
+                            </form>
+                            {% endif %}
+                        </td>
+                    </tr>
+                    {% else %}
+                    <tr>
+                        <td colspan="8" class="text-center text-muted">No entries found.</td>
+                    </tr>
+                    {% endfor %}
+                </tbody>
+            </table>
+        </div>
+
+        {% if total_pages > 1 %}
+        <nav>
+            <ul class="pagination">
+                <li class="page-item {% if page == 1 %}disabled{% endif %}">
+                    <a class="page-link" href="{{ url_for('admin', page=page-1) }}">Previous</a>
+                </li>
+                {% for p in range(1, total_pages + 1) %}
+                <li class="page-item {% if p == page %}active{% endif %}">
+                    <a class="page-link" href="{{ url_for('admin', page=p) }}">{{ p }}</a>
+                </li>
+                {% endfor %}
+                <li class="page-item {% if page == total_pages %}disabled{% endif %}">
+                    <a class="page-link" href="{{ url_for('admin', page=page+1) }}">Next</a>
+                </li>
+            </ul>
+        </nav>
+        {% endif %}
+    </div>
+</body>
+</html>

templates/admin_login.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Guestbook Admin — Login</title>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" />
+</head>
+<body class="bg-light">
+    <div class="container py-5" style="max-width: 400px;">
+        <h1 class="h4 mb-4 text-center">Admin Login</h1>
+        <div class="card">
+            <div class="card-body">
+                {% if error %}
+                <div class="alert alert-danger py-2">{{ error }}</div>
+                {% endif %}
+                <form method="POST" action="{{ url_for('admin_login', next=request.args.get('next', '')) }}">
+                    <div class="mb-3">
+                        <label for="username" class="form-label">Username</label>
+                        <input type="text" id="username" name="username" class="form-control"
+                               autocomplete="username" required autofocus />
+                    </div>
+                    <div class="mb-3">
+                        <label for="password" class="form-label">Password</label>
+                        <input type="password" id="password" name="password" class="form-control"
+                               autocomplete="current-password" required />
+                    </div>
+                    <button type="submit" class="btn btn-primary w-100">Log In</button>
+                </form>
+            </div>
+        </div>
+    </div>
+</body>
+</html>

templates/admin_users.html

@@ -0,0 +1,78 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Guestbook Admin — Users</title>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" />
+</head>
+<body class="bg-light">
+    <div class="container py-4" style="max-width: 700px;">
+        <div class="d-flex justify-content-between align-items-center mb-4">
+            <h1 class="h3 mb-0">User Management</h1>
+            <div class="d-flex gap-2">
+                <a href="{{ url_for('admin') }}" class="btn btn-outline-secondary btn-sm">Back to Entries</a>
+                <a href="{{ url_for('admin_logout') }}" class="btn btn-outline-danger btn-sm">Logout</a>
+            </div>
+        </div>
+
+        <div class="card mb-4">
+            <div class="card-header">Add User</div>
+            <div class="card-body">
+                <form method="POST" action="{{ url_for('admin_users_add') }}">
+                    <div class="row g-2">
+                        <div class="col-sm-4">
+                            <input type="text" name="username" class="form-control" placeholder="Username" required />
+                        </div>
+                        <div class="col-sm-4">
+                            <input type="password" name="password" class="form-control" placeholder="Password" required />
+                        </div>
+                        <div class="col-sm-2">
+                            <select name="role" class="form-select">
+                                <option value="viewer">Viewer</option>
+                                <option value="admin">Admin</option>
+                            </select>
+                        </div>
+                        <div class="col-sm-2">
+                            <button type="submit" class="btn btn-primary w-100">Add</button>
+                        </div>
+                    </div>
+                </form>
+            </div>
+        </div>
+
+        <table class="table table-bordered bg-white">
+            <thead class="table-dark">
+                <tr>
+                    <th>Username</th>
+                    <th>Role</th>
+                    <th></th>
+                </tr>
+            </thead>
+            <tbody>
+                {% for u in users %}
+                <tr>
+                    <td>{{ u[1] }}</td>
+                    <td><span class="badge bg-{{ 'danger' if u[2] == 'admin' else 'secondary' }}">{{ u[2] }}</span></td>
+                    <td>
+                        <form method="POST" action="{{ url_for('admin_users_delete', user_id=u[0]) }}"
+                              onsubmit="return confirm('Remove user {{ u[1] }}?')">
+                            <button type="submit" class="btn btn-danger btn-sm">Remove</button>
+                        </form>
+                    </td>
+                </tr>
+                {% else %}
+                <tr>
+                    <td colspan="3" class="text-center text-muted">No users added yet.</td>
+                </tr>
+                {% endfor %}
+            </tbody>
+        </table>
+
+        <p class="text-muted small">
+            These accounts are in addition to the bootstrap superadmin configured in <code>.env</code>.
+            Admins can view and delete entries. Viewers can only view.
+        </p>
+    </div>
+</body>
+</html>