flshbd 0.0.9__tar.gz

flshbd-0.0.9/.gitignore

@@ -0,0 +1,52 @@
+# ---> Python
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# data for development
+flshbd-data/
+
+# dotenv files with local settings/secrets (the bundled copy shipped with the
+# package is committed on purpose)
+.env
+!src/flshbd/core/.env
+
+# Opencode & AI
+.opencode/
+
+# Distribution / packaging
+build/
+dist/
+.hatch/
+sdist/
+.temp/
+.vscode/
+wheels/
+.zed/
+
+# Jupyter
+jupyter/
+*.ipynb
+.ipynb_checkpoints/
+
+# MkDocs documentation
+pages/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/

flshbd-0.0.9/AGENTS.md

@@ -0,0 +1,232 @@
+# AGENTS.md
+
+This document provides guidance for AI agents and assistants working with the **flshbd** (FlashBoard) project.
+
+_v0.0.8_ Last updated: November 2026
+
+## 📋 Project Overview
+
+**FlashBoard (flshbd)** is a Flask-based dashboard application that provides centralized access to various tools and services through a clean, role-based interface with user authentication. Users are organized in groups, and sites are collected in site groups. The sidebar dynamically displays only accessible site groups based on user group memberships.
+
+The project supports both iframe-based external services and Jinja2-based template content. Session management uses client-side cookies with configurable inactivity timeout. Data is stored in SQLite3 databases.
+
+## 🏗️ Project Structure
+
+```
+/home/robert/Python/flshbd/
+├── src/flshbd/
+│   ├── __init__.py           # Package initialization
+│   ├── __main__.py           # CLI entry point
+│   ├── __about__.py          # Version information
+│   ├── core/                 # Core utilities
+│   │   ├── __init__.py
+│   │   ├── .env              # Bundled env file (docs for all FLSHBD_* vars; copied to DATA_DIR on first start)
+│   │   ├── config.py         # Configuration management
+│   │   ├── env.py            # .env bootstrap: loaded from __init__.py before config is imported
+│   │   └── security.py       # Security utilities
+│   ├── data/                 # Data layer
+│   │   ├── __init__.py
+│   │   ├── database.py       # Database operations
+│   │   └── models.py         # Data models
+│   ├── web/                  # Web application
+│   │   ├── __init__.py
+│   │   ├── app.py            # Flask application factory
+│   │   ├── auth.py           # Authentication (standard)
+│   │   ├── auth_pam.py       # PAM authentication
+│   │   ├── routes.py         # Route definitions
+│   │   ├── static/           # Static files (CSS, JS, images) — bundled defaults, copied to DATA_DIR on first start
+│   │   └── templates/        # Jinja2 templates — bundled defaults, copied to DATA_DIR on first start
+│   └── cli/                  # CLI commands
+│       ├── __init__.py       # Main CLI entry point (fld)
+│       ├── access.py         # Access control commands
+│       ├── dash.py           # Server management commands
+│       ├── db.py             # Database management commands
+│       ├── groups.py         # User group management
+│       ├── process.py        # Process manager (PID files, Flask/Gunicorn start)
+│       ├── site_groups.py    # Site group management
+│       ├── sites.py          # Site management
+│       ├── users.py          # User management
+│       └── utils.py          # CLI utilities
+├── tests/                   # Test suite
+│   ├── conftest.py          # Pytest fixtures
+│   └── test_dash/           # Dashboard tests
+│       ├── test_auth.py
+│       ├── test_auth_pam.py
+│       ├── test_cli_process.py
+│       ├── test_models.py
+│       ├── test_routes.py
+│       ├── test_secret_key.py
+│       └── test_security.py
+├── docs/                    # Documentation
+│   ├── index.html           # Self-contained demo site (to be iframed)
+│   ├── nginx_auth.md        # Nginx auth_request setup for protected subdomains
+│   ├── pamconfig.md         # PAM configuration notes
+│   └── validation.md        # Validation notes
+├── pyproject.toml           # Project configuration (Hatch)
+├── README.md                # User documentation
+├── CHANGELOG.md             # Project changelog
+└── AGENTS.md                # This file
+```
+
+## 🔧 Development Setup
+
+### Prerequisites
+- Python 3.13+
+- [Hatch](https://hatch.pypa.io/) (recommended)
+
+### Installation
+```bash
+# Install in development mode
+hatch run pip install -e .
+
+# Or install from PyPI (not published yet)
+pip install flshbd
+```
+
+### Verify installation
+```bash
+fld --help
+```
+
+### Running Tests
+```bash
+# Run all tests
+hatch run pytest
+
+# Run specific test file
+hatch run pytest tests/test_dash/test_auth.py -v
+
+# Run with coverage
+hatch run pytest --cov=flshbd --cov=tests
+```
+
+## 🚀 CLI Commands
+
+The project uses the `fld` CLI (installed via `project.scripts` in pyproject.toml).
+
+**Structure:** `fld [--env|-e <production|development|testing|default>] <command> [options]` (`default` resolves to production; short flags `-e`/`-h` available)
+
+**Main commands:**
+- `fld dash <start/stop/status/generate-secret-key>` - Manage Flask server
+- `fld db <init/migrate/backup/restore>` - Database management
+- `fld db config <get/set/list>` - Key/value `config` table (e.g. `title`, `info`, `important`)
+- `fld user <list/add/modify/delete>` - User management (usernames are always lowercase)
+- `fld group <list/add/modify/delete>` - User group management
+- `fld site <list/add/modify/delete>` - Site management (`-v` shows URLs, `--sort-order` for ordering)
+- `fld site-group <list/add/modify/delete>` - Site group management
+- `fld access <list/grant/revoke>` - Access control management
+
+Use `-h`/`--help` at any level for detailed options.
+
+## 📚 Key Modules
+
+### Core Modules
+- **`core/config.py`** - Configuration classes for different environments
+- **`core/env.py`** - `.env` bootstrap (`get_data_dir`, `ensure_env_file`, `load_env_file`, `bootstrap`); must not import `core/config.py`
+- **`core/security.py`** - Security utilities and password hashing
+
+### Data Layer
+- **`data/database.py`** - Database initialization, connection, and operations
+- **`data/models.py`** - SQLAlchemy models (User, UserGroup, Site, SiteGroup, Access, ConfigEntry) plus the `user_can_access_site()` helper
+
+### Web Application
+- **`web/app.py`** - Flask application factory with CSP and session configuration
+- **`web/auth.py`** - Session-based authentication with login/logout
+- **`web/auth_pam.py`** - Optional PAM authentication integration
+- **`web/routes.py`** - All web routes (login, dashboard, site access, logout, `/auth/verify[/<site_id>]` for Nginx `auth_request`)
+
+### CLI Modules
+- **`cli/__init__.py`** - Main CLI group (`fld`) with environment handling (`--env`/`-e`)
+- **`cli/dash.py`** - Server start/stop/status plus `generate-secret-key`
+- **`cli/process.py`** - ProcessManager: PID-file handling, Flask dev server / Gunicorn (`--preload`, shared secret key) start
+- **`cli/db.py`** - Database init/migrate/backup/restore and the `db config` key/value commands
+- **`cli/users.py`**, **`cli/groups.py`**, **`cli/sites.py`**, **`cli/site_groups.py`** - Entity management
+- **`cli/access.py`** - Access control between user groups and site groups
+
+## 🎯 Important Considerations
+
+### Security
+- Passwords are **hashed** (bcrypt); usernames are always lowercase
+- Session cookies are HTTP-only, `SameSite=Lax`, and `Secure` in production. Signing uses an ephemeral secret key per server start unless `FLSHBD_SECRET_KEY` is set (see `fld dash generate-secret-key`); Gunicorn runs with `--preload` so all workers share the key
+- Response delay on unsuccessful DB login attempts
+- CSP headers configured per environment (more permissive in development)
+- PAM authentication available as optional dependency (`FLSHBD_PAM_ENABLED`, `FLSHBD_PAM_SERVICE`; see `docs/pamconfig.md`)
+
+### Configuration
+- **Environments:** production (default; `default` maps to production), development, testing — selected via `fld --env/-e ...`
+- Env-enabled config vars start with `FLSHBD_`: `FLSHBD_SECRET_KEY`, `FLSHBD_COOKIE_DOMAIN`, `FLSHBD_SESSION_LIFETIME`, `FLSHBD_PAM_ENABLED`, `FLSHBD_PAM_SERVICE`, `FLSHBD_TEMPLATE_FOLDER`, `FLSHBD_STATIC_FOLDER`
+- **`.env` file:** all `FLSHBD_*` vars can also be set in `<DATA_DIR>/.env` (`flshbd-data/.env` in development/testing, `~/.config/flshbd/.env` in production); on first start a documented copy of the bundled `src/flshbd/core/.env` is placed there by `ensure_env_file()` (never overwritten, mode 0600, since it may hold `FLSHBD_SECRET_KEY`). It is loaded by `flshbd.core.env.bootstrap()`, called from `flshbd/__init__.py` — before any submodule, in particular before `flshbd.core.config` is imported (whose `FLSHBD_*` reads happen at import time) — via `python-dotenv`'s `load_dotenv(..., override=False)` (optional extra `flshbd[dotenv]`). Precedence: exported env var > `.env` value > built-in default. The env for locating the data dir is detected from `sys.argv` (`--env/-e`, or `create_app('...')` in server command lines; `default` → production data dir); server subprocesses spawned by the CLI inherit the loaded values via `os.environ`. No-op under pytest. Without `python-dotenv`, the file is ignored (stderr hint if it contains active assignments). `core/env.py` must not import `core/config.py` (chicken-and-egg). The long per-variable explanations live in the bundled `.env`; `config.py` only keeps one-liners pointing to `<DATA_DIR>/.env`
+- **Templates & static files:** served from `<DATA_DIR>/templates` and `<DATA_DIR>/static` (`flshbd-data/` in development/testing, `~/.config/flshbd/` in production); on first server start (`create_app()` → `ensure_web_folders()`) they are auto-populated with the bundled copies from `src/flshbd/web/`, and can then be adapted per environment. `FLSHBD_TEMPLATE_FOLDER` / `FLSHBD_STATIC_FOLDER` override both locations (used as-is, never copied into); without them, the bundled folders are the fallback if the `DATA_DIR` folders don't exist. `fld site add/modify --type template` validates against the resolved template folder. Templates under `DATA_DIR` are Jinja2-rendered with the privileges of the server process
+- **Reload semantics of the web folders** (verified against Flask/Jinja2 behavior):
+  - *Which folder is used* is resolved once per process — the config class attributes at import time plus `ensure_web_folders()` in `create_app()` — so changing `FLSHBD_TEMPLATE_FOLDER`/`FLSHBD_STATIC_FOLDER` or the existence of the `DATA_DIR` folders requires a **server restart**. This applies to the Flask development server and to Gunicorn alike; with `--preload` (enforced by the CLI), `create_app()` runs once in the Gunicorn master and all workers inherit the same folders via fork, so a full Gunicorn restart is needed to pick up folder changes
+  - *Template content*: in development `DEBUG=True` makes Jinja2's `auto_reload=True`, so edits to template files are picked up **live, without restart**. In production (and the testing config) `auto_reload=False`: templates are cached in the app's Jinja environment, so content changes require a **restart** (same for Gunicorn workers, which share the preloaded master's environment)
+  - *Static content*: `send_static_file` reads from disk on every request, so edits are **live immediately** in all environments and servers. Responses carry `Cache-Control: no-cache` by default (`SEND_FILE_MAX_AGE_DEFAULT` unset), so browsers revalidate instead of serving stale files (see also the "Caching/Lifetime" item under *Cleanups* in CHANGELOG.md)
+- **Development:** Debug mode, data in `flshbd-data/`, server on `localhost:5000`
+- **Production:** Gunicorn (or Flask) server, data in `~/.config/flshbd/` (XDG compliant), secure cookies
+- **Session timeout:** `FLSHBD_SESSION_LIFETIME` env var in seconds (default 1800 = 30 min, sliding inactivity timeout), mapped to Flask's `PERMANENT_SESSION_LIFETIME` and read once at process start like the other env-backed `FLSHBD_*` vars; unset or invalid values fall back to 1800 s. Via the `.env` file (see above) it is loaded automatically at package import, before `flshbd.core.config`
+- **Config table:** key/value pairs in the DB (`fld db config ...`), e.g. `title` (dashboard title) and `info`/`important` (admin messages above the login area; plain text only, `important` overwrites `info`)
+- **Reverse proxy:** `/auth/verify[/<site_id>]` returns plain status codes (204/401/403, never redirects) for Nginx `auth_request` on subdomains; set `FLSHBD_COOKIE_DOMAIN` (e.g. `.example.com`) to share the session cookie across subdomains. See `docs/nginx_auth.md` for prerequisites and Nginx config examples
+
+### Database
+- SQLite3 databases per environment
+- Schema auto-initialization at first server start (`create_app()` → `ensure_database_initialized()` in `data/database.py`), if not there — parallel to `ensure_web_folders()` for the web folders; idempotent, so safe on every start (Flask debug reloader, Gunicorn `--preload`). The lazy init in `get_database()` remains as a safety net for CLI-only usage (`fld user add` etc. on a fresh data dir)
+- Static demo data is NOT auto-populated anymore (the `FLSHBD_MIGRATE_DATA` env var is removed); seed explicitly with `fld db migrate` (`seed_static_data()` in `data/models.py`, only if the DB has no users yet); backups via `fld db backup` / `fld db restore`
+- Key/value `config` table for the dashboard title and admin messages (`fld db config ...`; run `fld db init --force` after schema changes)
+- **Warning:** Default static users (admin/admin123, user1/user123, user2/user223) must be deleted or have passwords changed in production!
+
+### Current State
+- Database-backed user, group, site, site-group and access management (active/inactive flags; `name`/`username` plus ids for the CLI, `description`/`full-name` for display)
+- Dynamic sidebar based on user permissions; site groups sorted alphabetically, sites sorted within groups (overridable via `--sort-order`)
+- Sidebar is collapsible via a hamburger button in the header, implemented with pure HTML/CSS (checkbox hack in `dash.html` + `partials/header.html`, rules in `style.css`) -- no JavaScript; hidden by default on screens up to 768px (`@media (max-width: 768px)`)
+- Both iframe-based and Jinja2-template-based sites supported; tooltips on the dashboard
+- Configurable dashboard title and admin messages (`info`/`important`) via the `config` table; `[DEV]`/`[TEST]` markers in titles
+- Subdomain services can be protected via Nginx `auth_request` against `/auth/verify[/<site_id>]` (per-site access check via `user_can_access_site()`, read-only session check — the inactivity timeout does not slide on subdomain requests)
+
+## 🤖 AI Assistant Guidelines
+
+### Working with the Codebase
+1. **Update documentation first** - Check AGENTS.md, README.md, and CHANGELOG.md for current state
+2. **Test your changes** - Keep test suite up to date, run tests after changes
+3. **Follow existing patterns** - Maintain code style, structure, and naming conventions
+4. **If in doubt, ask** - Clarify requirements before making significant changes
+
+### Development Workflow
+```bash
+# Lint code
+hatch run lint
+
+# Format code
+hatch run format
+
+# Run tests
+hatch run pytest
+
+# Build package
+hatch build
+```
+
+## 📖 Additional Resources
+
+- **README.md** - User documentation, installation, and usage
+- **CHANGELOG.md** - Recent changes and TODO items
+- **docs/** - `nginx_auth.md` (subdomain protection via Nginx), `pamconfig.md`, `validation.md`, demo `index.html`
+- **pyproject.toml** - Project configuration, dependencies, and Hatch scripts
+- **Tests** - Comprehensive test suite in `tests/`
+- **Source** - https://codeberg.org/rokor/flshbd
+- **Issues** - https://codeberg.org/rokor/flshbd/issues
+
+## 🙏 Contribution Guidelines
+
+When contributing to this project:
+
+1. Follow existing code style (ruff configuration in pyproject.toml)
+2. Update tests for any new functionality
+3. Add documentation for new features
+4. Maintain backward compatibility where possible
+5. Run lint, format, and test suite before submitting changes
+
+---
+
+**Project Status**: ✅ Active development (v0.0.8)
+**Last Updated**: November 2026
+**Maintainer**: Robert Kormann, assisted by [Opencode](https://opencode.ai) and [Mistral](https://mistral.ai)

flshbd-0.0.9/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+## Cleanups
+
+- Check CSP definitions
+
+## TODO
+
+- Implementation of MD-based static sites within a Jinja2 template
+- Implement better logging
+- Enter password always via corresponding field, not CLI, esp. for `modify`
+- Howto empty values like email for users?
+- The CLI command `fld db migrate` might hit the wrong environment. It might be useful to trigger a DB backup before changes are made there.
+
+## v0.0.9
+
+- New optional dependency `python-dotenv` (`pip install flshbd[dotenv]`): all `FLSHBD_*` env vars can also be set in `<DATA_DIR>/.env` (`flshbd-data/.env` in development/testing, `~/.config/flshbd/.env` in production).
+- New `FLSHBD_SESSION_LIFETIME` env var to adjust the session inactivity timeout in seconds (default 1800 = 30 min, sliding); it is mapped to Flask's `PERMANENT_SESSION_LIFETIME`.
+- Database schema is now auto-initialized at first server start (`create_app()` → `ensure_database_initialized()`), if not there. The lazy init in `get_database()` remains as a safety net for CLI-only usage
+- Removed the `FLSHBD_MIGRATE_DATA` env var
+- Update of `AGENTS.md`, adaption of the sites Info & Help to describe _FlashBoard_, style tweaks
+- Collapsible sidebar via hamburger button in the header, pure HTML/CSS (checkbox hack, no JS); hidden by default on small screens (max. 768px)
+- New `FLSHBD_TEMPLATE_FOLDER` / `FLSHBD_STATIC_FOLDER` env vars. For details see `Readme.md` and `Agents.md`.
+- Fixed stale coverage omit paths in `pyproject.toml`
+
+## v0.0.8
+
+- New `/auth/verify[/<site_id>]` route for Nginx `ngx_http_auth_request_module`. It returns  plain status codes (204/401/403).
+- Per-site authorization via the existing group-based access control
+- Important: Session check for type iframe is read-only (no sliding on subdomain requests). Adapt the inactivity timeout via `FLSHBD_SESSION_LIFETIME`, if necessary
+- New `FLSHBD_COOKIE_DOMAIN` env var / `SESSION_COOKIE_DOMAIN` config to share the session cookie across subdomains (e.g. `.example.com`)
+- New `user_can_access_site()` helper in `flshbd.data.models`
+- Update of README.md and AGENTS.md
+- Explanation of the method in `docs/nginx_auth.md`, incl. "Prerequisites" (cookie domain, HTTPS, stable secret key, SameSite) and "Testing with curl" sections, and self-contained demo site `index.html` to be iframed in _FlashBoard_
+- Removed unused `GUNICORN_BIND` config
+
+## v0.0.7 "Bond"
+
+- Replace `0.0.0.0` by `localhost`
+- Replace `main_view.html` by `main.html` (readability)
+- Smaller footer & header
+- URL added to `fld site list -v`
+- Users are always lowercase
+- Formatting & linting
+- Short 1-letter flags for important options
+
+## v0.0.6
+
+- Improvement of the DB structure (ids for machine, name for humans, breaking change)
+- New `sites` and `site-groups` now possible
+- Tooltips for the dashboard page
+
+## v0.0.5
+
+- `[DEV]` / `[TEST]` mark near the titles for clarity
+- FlashBoard's `title` (login, header) adjustable in the db's config table
+- FlashBoard Admin Messages implemented
+- Copyleft remarks, improvement of docs
+- Switch default env to `production`
+- Env-enabled config vars start with `FLSHBD_`
+- Response delay for unsuccessful db login attempts for security
+
+## v0.0.4
+
+- Hatch version corrected
+- Extend the auth logic with `use_dba`.
+- Incomplete isolation of environments fixed
+- Consistent tests with PAM active or inactive
+- Ephemeral or env-driven `FLSHBD_SECRET_KEY`.
+
+## v0.0.3
+
+- Adding a "What is this?" dropdown below the login form.
+- Improving CSS for screen and print
+- `fld --env production db migrate` now working
+- `fld dash status`/`fld dash stop` are aware of the enviroment
+- Config `USE_DB` and deprecated env variable `FLASK_ENV` removed
+
+## v0.0.2
+
+- Refactoring of the data model
+- Code reorganisation and cleanup, recheck of consistent imports
+- New database table `config` with CLI commands (`fld db init --force` necessary!)
+- Reorganisation of data directories
+- CLI: `None` values resented as `---`
+- Updated `README.md` and `AGENTS.md`
+
+## v0.0.1
+
+- Initial release, based on unpublished `aimd`

flshbd-0.0.9/LICENSE.txt

@@ -0,0 +1,10 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.
+
+In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

flshbd-0.0.9/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: flshbd
+Version: 0.0.9
+Summary: FlashBoard
+Project-URL: Documentation, https://codeberg.org/rokor/flshbd#readme
+Project-URL: Issues, https://codeberg.org/rokor/flshbd/issues
+Project-URL: Source, https://codeberg.org/rokor/flshbd
+Author-email: Robert Kormann <rokor@kormann.info>
+License-Expression: Unlicense
+License-File: LICENSE.txt
+Keywords: dashboard,flask
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.13
+Requires-Dist: click>=8.0.0
+Requires-Dist: flask>=3.0.0
+Requires-Dist: werkzeug>=3.0.0
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv>=1.0.0; extra == 'dotenv'
+Provides-Extra: gunicorn
+Requires-Dist: gunicorn>=21.0.0; extra == 'gunicorn'
+Provides-Extra: pam
+Requires-Dist: python-pam>=2.0.0; extra == 'pam'
+Description-Content-Type: text/markdown
+
+# flshbd
+
+**A simple, Flask-based dashboard**
+
+[![PyPI - Version](https://img.shields.io/pypi/v/flshbd.svg)](https://pypi.org/project/flshbd)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flshbd.svg)](https://pypi.org/project/flshbd)
+
+-----
+
+## Table of Contents
+
+- [Installation](#installation)
+- [FlashBoard](#flashboard)
+- [Administration](#administration)
+- [Protecting services on subdomains](#protecting-services-on-subdomains)
+- [License](#license)
+
+## Installation
+
+_**Remark**_ _FlashBoard_ is not published yet on PyPI.
+
+```console
+pip install flshbd
+```
+
+Optional installs are `pam` for Linux's [Pluggable Authentication Module](https://github.com/linux-pam/linux-pam) and `gunicorn` ([Gunicorn](https://gunicorn.org/)) as [WSGI server](https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface).
+
+---
+
+_**Alpha** Software_
+
+This software is in **Alpha** State. Check the [changelog](CHANGELOG.md) for information on potential changes in the upcoming versions. Furthermore, as long as we are in *Alpha* (micro versions), there might be breaking changes.
+
+---
+
+## FlashBoard
+
+_FlashBoard_ is a small Flask-based web application that provides an interface to organize and access -- mainly local -- tools or services. The dashboard features a clean header/sidebar/main/footer layout with user authentication, and access control based on user groups.
+
+Users are organized in (user) groups, and sites are collected in site groups. The sidebar dynamically displays only these site groups a user has access to, based on her or his (user) group memberships. This allows for a personalized dashboard experience. The information about users and sites, their groups and the access table are stored in a SQLite3 database. The user and site groups can be changed on-the-fly during normal operation of _FlashBoard_, and is backed by a static model for testing and development.
+
+The sidebar can be hidden and shown via the hamburger button in the header. On small screens (max. 768px width) the sidebar is hidden by default, and can be toggled open the same way.
+
+_FlashBoard_ supports for its sites both, iframe-based content (_FlashBoard_-external services, typically on the same machine, or within the same LAN, and shown as site) in the main (view), and Jinja2-based template content (_FlashBoard_-internal sites). Session management is handled through client-side cookies with a configurable inactivity timeout.
+
+## Administration
+
+The dashboard includes a CLI for managing it, `fld dash <start/stop/status>`, and can operate in the environments _development_ (Flask-internal server in debug mode), or _production_ (Gunicorn- or Flask server-based, default).
+The SQLite3 databases, one for _development_ within the current (typ. project) folder `flshbd-data`, and a user-based folder `~/.config/flshbd` (XDG compliant) for _production_, are administered also via the same command `fld` on CLI. The structure of `fld` is `fld [--env <production/development>] command [command options] subcommand [subcommand options] [parameter]`. Most commands should be obvious, e.g., the command for _production_ user management reads `fld user <list/add/modify/delete>`. Use `--help` (short `-h`) at each command level for the available options.
+
+On the first server start, the database is auto-initialized with an empty schema, if not there (parallel to the templates and static files, see below). It can be populated by hand (e.g., `fld user add ...`), or from the static model running `fld db migrate`. The latter copies the static three `user/password` pairs, `admin/admin123`, `user1/user123`, and `user2/user223` (of course, salted and hashed in the databases), and contents for user groups, site and site groups. Check it, using the CLI commands, e.g., `fld user list -v`. Of course, now you can login using the static user credentials, and inspect the default sites and site groups, which are accessible for the user groups.
+
+**Warning** These static users MUST be deleted (or at least their password changed) in a _production_ environment for obvious reasons!
+
+Users and sites can be active or inactive. Site goups are sorted alphabetically within the sidebar, as well as sites within site groups. This can be overruled, e.g., for sites via `fld site modify <site> --sort-order <integer>` (defaults to 0, smaller is earlier in the list). Misaligned sites or site groups might lead to non-existing links within _FlashBoard_. In this case, the top-most site is shown. It is therefore useful to place an informative site there. All objects have a `name` (`username` for users) used internally and for the CLI, and a `description` (`full-name` for users) used for the dashboards.
+
+The title of _FlashBoard_ can be set, e.g., to "My Dashboard" via `fld db config set title "My Dashboard"`, or reset by `fld db config set title ""`. The title keyword and its value is stored within the database in a (string-based) key/value table `config`. Using the same key/value scheme, the keys `info` and `important` create messages above the login area. Important messages overwrite info messages. Values of these keys can only be text messages, HTML is not allowed.
+
+Templates and static files are taken from the environment's data directory (`flshbd-data/` in _development_, `~/.config/flshbd/` in _production_): on the first start they are populated automatically with the bundled copies shipped with _FlashBoard_, and can then be customized per environment (e.g., additional partials for template sites, which `fld site add --type template` validates against the resolved template folder). Set the environment variables `FLSHBD_TEMPLATE_FOLDER` and `FLSHBD_STATIC_FOLDER` to use custom locations instead. Note that template sites are Jinja2-rendered with the privileges of the _FlashBoard_ process.
+
+The folders are resolved once when the server process starts, so changing them requires a restart (Flask and Gunicorn alike); edits to template files are picked up live only in _development_, while static files are always read from disk per request. Details in `AGENTS.md`.
+
+All `FLSHBD_*` environment variables can alternatively be set in a `.env` file within the environment's data directory (`flshbd-data/.env` in _development_, `~/.config/flshbd/.env` in _production_): on the first start, a documented copy of the bundled defaults is placed there (never overwritten), and can then be edited per environment. Loading the file requires the optional dependency `python-dotenv` (`pip install flshbd[dotenv]`). The precedence is: exported environment variable first, `.env` value second, built-in default third. The values are read once at process start, so changes require a restart.
+
+The signing of the session cookie is performed by an ephemeral secret key, which is created when starting a _FlashBoard_ session via `fld dash start`. As a consequence, all existing sessions become invalid, when _FlashBoard_ is (re)started. To avoid this, create an environment variable `FLSHBD_SECRET_KEY` (`fld dash generate-secret-key` might help).
+
+The session inactivity timeout (a sliding timeout, default 1800 s = 30 min) can be adjusted via the `FLSHBD_SESSION_LIFETIME` environment variable, whose value is the timeout in seconds (e.g. `FLSHBD_SESSION_LIFETIME=3600`). Unset or invalid values fall back to the default.
+
+## Protecting services on subdomains
+
+_FlashBoard_ can also guard iframe-type services running on subdomains (e.g. `service.example.com`) while _FlashBoard_ itself runs behind a reverse proxy at `example.com`. This uses Nginx's [`ngx_http_auth_request_module`](https://nginx.org/en/docs/http/ngx_http_auth_request_module.html): for every request to the subdomain, Nginx first makes an internal subrequest to _FlashBoard_'s `/auth/verify` endpoint, which checks the session cookie and — if a site is given — whether the user has access to that site.
+
+Please see [Nginx auth](docs/nginx_auth.md) for more details on this functionality.
+
+## License
+
+`flshbd` is distributed under the terms of the [Unlicense](https://unlicense.org) license.

flshbd-0.0.9/README.md

@@ -0,0 +1,77 @@
+# flshbd
+
+**A simple, Flask-based dashboard**
+
+[![PyPI - Version](https://img.shields.io/pypi/v/flshbd.svg)](https://pypi.org/project/flshbd)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flshbd.svg)](https://pypi.org/project/flshbd)
+
+-----
+
+## Table of Contents
+
+- [Installation](#installation)
+- [FlashBoard](#flashboard)
+- [Administration](#administration)
+- [Protecting services on subdomains](#protecting-services-on-subdomains)
+- [License](#license)
+
+## Installation
+
+_**Remark**_ _FlashBoard_ is not published yet on PyPI.
+
+```console
+pip install flshbd
+```
+
+Optional installs are `pam` for Linux's [Pluggable Authentication Module](https://github.com/linux-pam/linux-pam) and `gunicorn` ([Gunicorn](https://gunicorn.org/)) as [WSGI server](https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface).
+
+---
+
+_**Alpha** Software_
+
+This software is in **Alpha** State. Check the [changelog](CHANGELOG.md) for information on potential changes in the upcoming versions. Furthermore, as long as we are in *Alpha* (micro versions), there might be breaking changes.
+
+---
+
+## FlashBoard
+
+_FlashBoard_ is a small Flask-based web application that provides an interface to organize and access -- mainly local -- tools or services. The dashboard features a clean header/sidebar/main/footer layout with user authentication, and access control based on user groups.
+
+Users are organized in (user) groups, and sites are collected in site groups. The sidebar dynamically displays only these site groups a user has access to, based on her or his (user) group memberships. This allows for a personalized dashboard experience. The information about users and sites, their groups and the access table are stored in a SQLite3 database. The user and site groups can be changed on-the-fly during normal operation of _FlashBoard_, and is backed by a static model for testing and development.
+
+The sidebar can be hidden and shown via the hamburger button in the header. On small screens (max. 768px width) the sidebar is hidden by default, and can be toggled open the same way.
+
+_FlashBoard_ supports for its sites both, iframe-based content (_FlashBoard_-external services, typically on the same machine, or within the same LAN, and shown as site) in the main (view), and Jinja2-based template content (_FlashBoard_-internal sites). Session management is handled through client-side cookies with a configurable inactivity timeout.
+
+## Administration
+
+The dashboard includes a CLI for managing it, `fld dash <start/stop/status>`, and can operate in the environments _development_ (Flask-internal server in debug mode), or _production_ (Gunicorn- or Flask server-based, default).
+The SQLite3 databases, one for _development_ within the current (typ. project) folder `flshbd-data`, and a user-based folder `~/.config/flshbd` (XDG compliant) for _production_, are administered also via the same command `fld` on CLI. The structure of `fld` is `fld [--env <production/development>] command [command options] subcommand [subcommand options] [parameter]`. Most commands should be obvious, e.g., the command for _production_ user management reads `fld user <list/add/modify/delete>`. Use `--help` (short `-h`) at each command level for the available options.
+
+On the first server start, the database is auto-initialized with an empty schema, if not there (parallel to the templates and static files, see below). It can be populated by hand (e.g., `fld user add ...`), or from the static model running `fld db migrate`. The latter copies the static three `user/password` pairs, `admin/admin123`, `user1/user123`, and `user2/user223` (of course, salted and hashed in the databases), and contents for user groups, site and site groups. Check it, using the CLI commands, e.g., `fld user list -v`. Of course, now you can login using the static user credentials, and inspect the default sites and site groups, which are accessible for the user groups.
+
+**Warning** These static users MUST be deleted (or at least their password changed) in a _production_ environment for obvious reasons!
+
+Users and sites can be active or inactive. Site goups are sorted alphabetically within the sidebar, as well as sites within site groups. This can be overruled, e.g., for sites via `fld site modify <site> --sort-order <integer>` (defaults to 0, smaller is earlier in the list). Misaligned sites or site groups might lead to non-existing links within _FlashBoard_. In this case, the top-most site is shown. It is therefore useful to place an informative site there. All objects have a `name` (`username` for users) used internally and for the CLI, and a `description` (`full-name` for users) used for the dashboards.
+
+The title of _FlashBoard_ can be set, e.g., to "My Dashboard" via `fld db config set title "My Dashboard"`, or reset by `fld db config set title ""`. The title keyword and its value is stored within the database in a (string-based) key/value table `config`. Using the same key/value scheme, the keys `info` and `important` create messages above the login area. Important messages overwrite info messages. Values of these keys can only be text messages, HTML is not allowed.
+
+Templates and static files are taken from the environment's data directory (`flshbd-data/` in _development_, `~/.config/flshbd/` in _production_): on the first start they are populated automatically with the bundled copies shipped with _FlashBoard_, and can then be customized per environment (e.g., additional partials for template sites, which `fld site add --type template` validates against the resolved template folder). Set the environment variables `FLSHBD_TEMPLATE_FOLDER` and `FLSHBD_STATIC_FOLDER` to use custom locations instead. Note that template sites are Jinja2-rendered with the privileges of the _FlashBoard_ process.
+
+The folders are resolved once when the server process starts, so changing them requires a restart (Flask and Gunicorn alike); edits to template files are picked up live only in _development_, while static files are always read from disk per request. Details in `AGENTS.md`.
+
+All `FLSHBD_*` environment variables can alternatively be set in a `.env` file within the environment's data directory (`flshbd-data/.env` in _development_, `~/.config/flshbd/.env` in _production_): on the first start, a documented copy of the bundled defaults is placed there (never overwritten), and can then be edited per environment. Loading the file requires the optional dependency `python-dotenv` (`pip install flshbd[dotenv]`). The precedence is: exported environment variable first, `.env` value second, built-in default third. The values are read once at process start, so changes require a restart.
+
+The signing of the session cookie is performed by an ephemeral secret key, which is created when starting a _FlashBoard_ session via `fld dash start`. As a consequence, all existing sessions become invalid, when _FlashBoard_ is (re)started. To avoid this, create an environment variable `FLSHBD_SECRET_KEY` (`fld dash generate-secret-key` might help).
+
+The session inactivity timeout (a sliding timeout, default 1800 s = 30 min) can be adjusted via the `FLSHBD_SESSION_LIFETIME` environment variable, whose value is the timeout in seconds (e.g. `FLSHBD_SESSION_LIFETIME=3600`). Unset or invalid values fall back to the default.
+
+## Protecting services on subdomains
+
+_FlashBoard_ can also guard iframe-type services running on subdomains (e.g. `service.example.com`) while _FlashBoard_ itself runs behind a reverse proxy at `example.com`. This uses Nginx's [`ngx_http_auth_request_module`](https://nginx.org/en/docs/http/ngx_http_auth_request_module.html): for every request to the subdomain, Nginx first makes an internal subrequest to _FlashBoard_'s `/auth/verify` endpoint, which checks the session cookie and — if a site is given — whether the user has access to that site.
+
+Please see [Nginx auth](docs/nginx_auth.md) for more details on this functionality.
+
+## License
+
+`flshbd` is distributed under the terms of the [Unlicense](https://unlicense.org) license.