simple-module-site-lock 0.0.30__tar.gz

simple_module_site_lock-0.0.30/.gitignore

@@ -0,0 +1,65 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# UV
+uv.lock
+
+# Node
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# Database
+*.db
+*.sqlite3
+
+# Module-managed runtime state (e.g. uploaded dataset files,
+# default storage_dir for SM_DATASETS_STORAGE_DIR).
+var/
+
+# file_storage filesystem backend default root (override via SM_FILE_STORAGE_FS_ROOT_PATH).
+uploads/
+
+# Vite
+host/static/dist/
+
+# VitePress (docs)
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+
+# Auto-generated frontend module manifest (regenerated by the host at boot
+# or via `make gen-pages`).
+host/client_app/modules.manifest.json
+host/client_app/modules.generated.ts
+host/client_app/modules.generated.css
+host/client_app/modules.assets.json
+
+# Worktrees
+.worktrees/
+
+# Performance profiles
+.memray/
+.benchmarks/
+
+# OS
+.DS_Store
+Thumbs.db
+
+.playwright-cli/*
+.playwright-mcp/*
+host/client_app/.playwright-cli/*
+.superpowers/
+.qa/

simple_module_site_lock-0.0.30/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: simple_module_site_lock
+Version: 0.0.30
+Summary: Optional site-wide password gate (staging / pre-launch) for simple_module apps
+Project-URL: Homepage, https://github.com/antosubash/simple_module_python
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+Keywords: gate,password,simple-module,staging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: simple-module-auth==0.0.30
+Requires-Dist: simple-module-core==0.0.30
+Requires-Dist: simple-module-hosting==0.0.30
+Requires-Dist: simple-module-settings==0.0.30
+Description-Content-Type: text/markdown
+
+# simple_module_site_lock
+
+Optional site-wide password gate for `simple_module` apps — a staging /
+pre-launch door. When enabled, every visitor must enter one shared password
+before they can see anything: not the landing page, not the API, not even
+that a login form exists.
+
+**Off by default.** Installing this module changes nothing until an operator
+turns it on.
+
+## Install
+
+Add the package to your host and re-sync — discovery picks it up from the
+`simple_module` entry point, no host code changes:
+
+```toml
+# host/pyproject.toml
+dependencies = ["simple_module_site_lock"]
+```
+
+```bash
+uv sync --all-packages
+```
+
+Or scaffold a new app with it selected: `smpy new --modules site_lock`.
+
+## Usage
+
+1. Sign in as an admin and open **Settings → Modules → SiteLock**.
+2. Set `password` (and optionally `message`), tick `enabled`, and **Save**.
+   Saving with a blank password is refused — the error appears on the
+   `enabled` field and nothing is persisted.
+3. Anyone without the password now gets the gate page at `/__unlock` on every
+   URL. They enter the password once and are returned to where they were
+   heading.
+4. To lift the gate, untick `enabled` and save. To rotate the password, set a
+   new one — every already-unlocked visitor is logged back out of the gate.
+
+Keep your own session alive while you do this: an admin with a live session
+skips the gate, which is what lets you undo a mistake (see
+[Admin bypass](#admin-bypass-and-the-lockout-you-can-still-cause) below).
+
+## How it works
+
+The module installs a single middleware that runs *before* `AuthMiddleware`.
+That ordering is the whole point — an anonymous visitor gets the gate rather
+than a redirect to the login page, so a locked site never reveals that it has
+one.
+
+It achieves that ordering by declaring `depends_on=["Settings", "Auth"]`:
+modules are installed in topological order and Starlette's `add_middleware`
+is LIFO, so sorting after `Auth` makes this middleware wrap outermost.
+
+Unlock state lives in the signed session cookie. The stored marker is a
+fingerprint of the current password, so **rotating the password immediately
+invalidates every unlocked session**.
+
+## Enabling it
+
+Settings → Site Lock:
+
+| Field | Default | Meaning |
+|---|---|---|
+| `enabled` | `false` | Master switch |
+| `password` | `""` | The shared password. Masked in the admin UI |
+| `message` | `""` | Optional line shown on the gate page |
+
+Changes apply immediately — no restart. Enabling with a blank password is
+rejected by a validator, so you cannot accidentally gate the site behind the
+empty string.
+
+## What stays reachable when locked
+
+- `/health` — always. Gating it would fail Kubernetes liveness/readiness
+  probes and get the pod killed.
+- `/__unlock` — the gate page itself.
+
+Everything else is gated. Requests under `/api/`, and any request carrying an
+`Authorization` header, get `403 {"detail": "Site is locked"}` rather than a
+redirect — a `401` would invite an auth flow that cannot succeed while the
+site is locked. Browser requests get a `302` to the gate.
+
+That includes the login API itself, so while the gate is on there is no
+programmatic way in: CI smoke tests, uptime monitors, mobile clients and
+webhook senders all get `403` no matter what credentials they hold. Only a
+browser that has passed the gate (or an admin holding a live session) can
+reach anything. Pause those integrations before enabling the gate, or point
+uptime checks at `/health`, which stays open.
+
+## Admin bypass, and the lockout you can still cause
+
+A user who already holds a session with the `admin` role skips the gate.
+This is the intended escape hatch: if you enable the gate and mistype the
+password, you are still holding the session that lets you go straight back to
+Settings and fix it.
+
+**It only rescues a live session.** If no admin is currently signed in and the
+password has been forgotten, there is no in-app recovery. Clear the override
+directly in the database:
+
+```sql
+DELETE FROM settings_setting
+ WHERE scope = 'system' AND key = 'site_lock.enabled';
+```
+
+Then restart the app (or save any setting) so the module re-hydrates.
+
+## Brute-force protection
+
+The unlock endpoint tracks failures per client IP in memory: 10 failures
+within 5 minutes trigger a 15-minute cooldown returning `429`. These
+thresholds are module constants, not settings — they are the only defence on
+a single shared secret, so they are not an operator-tunable surface.
+
+The limiter is process-local, which is adequate for the single-process
+staging deployments this module targets.
+
+## What this is not
+
+This is not user authentication or authorisation — that is what the `auth`,
+`users`, and `permissions` modules are for. The site lock is one shared
+secret in front of everything, with no notion of identity.

simple_module_site_lock-0.0.30/README.md

@@ -0,0 +1,122 @@
+# simple_module_site_lock
+
+Optional site-wide password gate for `simple_module` apps — a staging /
+pre-launch door. When enabled, every visitor must enter one shared password
+before they can see anything: not the landing page, not the API, not even
+that a login form exists.
+
+**Off by default.** Installing this module changes nothing until an operator
+turns it on.
+
+## Install
+
+Add the package to your host and re-sync — discovery picks it up from the
+`simple_module` entry point, no host code changes:
+
+```toml
+# host/pyproject.toml
+dependencies = ["simple_module_site_lock"]
+```
+
+```bash
+uv sync --all-packages
+```
+
+Or scaffold a new app with it selected: `smpy new --modules site_lock`.
+
+## Usage
+
+1. Sign in as an admin and open **Settings → Modules → SiteLock**.
+2. Set `password` (and optionally `message`), tick `enabled`, and **Save**.
+   Saving with a blank password is refused — the error appears on the
+   `enabled` field and nothing is persisted.
+3. Anyone without the password now gets the gate page at `/__unlock` on every
+   URL. They enter the password once and are returned to where they were
+   heading.
+4. To lift the gate, untick `enabled` and save. To rotate the password, set a
+   new one — every already-unlocked visitor is logged back out of the gate.
+
+Keep your own session alive while you do this: an admin with a live session
+skips the gate, which is what lets you undo a mistake (see
+[Admin bypass](#admin-bypass-and-the-lockout-you-can-still-cause) below).
+
+## How it works
+
+The module installs a single middleware that runs *before* `AuthMiddleware`.
+That ordering is the whole point — an anonymous visitor gets the gate rather
+than a redirect to the login page, so a locked site never reveals that it has
+one.
+
+It achieves that ordering by declaring `depends_on=["Settings", "Auth"]`:
+modules are installed in topological order and Starlette's `add_middleware`
+is LIFO, so sorting after `Auth` makes this middleware wrap outermost.
+
+Unlock state lives in the signed session cookie. The stored marker is a
+fingerprint of the current password, so **rotating the password immediately
+invalidates every unlocked session**.
+
+## Enabling it
+
+Settings → Site Lock:
+
+| Field | Default | Meaning |
+|---|---|---|
+| `enabled` | `false` | Master switch |
+| `password` | `""` | The shared password. Masked in the admin UI |
+| `message` | `""` | Optional line shown on the gate page |
+
+Changes apply immediately — no restart. Enabling with a blank password is
+rejected by a validator, so you cannot accidentally gate the site behind the
+empty string.
+
+## What stays reachable when locked
+
+- `/health` — always. Gating it would fail Kubernetes liveness/readiness
+  probes and get the pod killed.
+- `/__unlock` — the gate page itself.
+
+Everything else is gated. Requests under `/api/`, and any request carrying an
+`Authorization` header, get `403 {"detail": "Site is locked"}` rather than a
+redirect — a `401` would invite an auth flow that cannot succeed while the
+site is locked. Browser requests get a `302` to the gate.
+
+That includes the login API itself, so while the gate is on there is no
+programmatic way in: CI smoke tests, uptime monitors, mobile clients and
+webhook senders all get `403` no matter what credentials they hold. Only a
+browser that has passed the gate (or an admin holding a live session) can
+reach anything. Pause those integrations before enabling the gate, or point
+uptime checks at `/health`, which stays open.
+
+## Admin bypass, and the lockout you can still cause
+
+A user who already holds a session with the `admin` role skips the gate.
+This is the intended escape hatch: if you enable the gate and mistype the
+password, you are still holding the session that lets you go straight back to
+Settings and fix it.
+
+**It only rescues a live session.** If no admin is currently signed in and the
+password has been forgotten, there is no in-app recovery. Clear the override
+directly in the database:
+
+```sql
+DELETE FROM settings_setting
+ WHERE scope = 'system' AND key = 'site_lock.enabled';
+```
+
+Then restart the app (or save any setting) so the module re-hydrates.
+
+## Brute-force protection
+
+The unlock endpoint tracks failures per client IP in memory: 10 failures
+within 5 minutes trigger a 15-minute cooldown returning `429`. These
+thresholds are module constants, not settings — they are the only defence on
+a single shared secret, so they are not an operator-tunable surface.
+
+The limiter is process-local, which is adequate for the single-process
+staging deployments this module targets.
+
+## What this is not
+
+This is not user authentication or authorisation — that is what the `auth`,
+`users`, and `permissions` modules are for. The site lock is one shared
+secret in front of everything, with no notion of identity.

simple_module_site_lock-0.0.30/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "simple_module_site_lock"
+version = "0.0.30"
+description = "Optional site-wide password gate (staging / pre-launch) for simple_module apps"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{ name = "Anto Subash", email = "antosubash@live.com" }]
+keywords = ["simple-module", "password", "staging", "gate"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+dependencies = [
+    "simple_module_core==0.0.30",
+    "simple_module_hosting==0.0.30",
+    "simple_module_settings==0.0.30",
+    "simple_module_auth==0.0.30",
+]
+
+[project.entry-points.simple_module]
+site_lock = "site_lock.module:SiteLockModule"
+
+[project.urls]
+Homepage = "https://github.com/antosubash/simple_module_python"
+Repository = "https://github.com/antosubash/simple_module_python"
+Issues = "https://github.com/antosubash/simple_module_python/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["site_lock"]
+
+[tool.uv.sources]
+simple_module_core = { workspace = true }
+simple_module_hosting = { workspace = true }
+simple_module_settings = { workspace = true }
+simple_module_auth = { workspace = true }

simple_module_site_lock-0.0.30/site_lock/constants.py

@@ -0,0 +1,28 @@
+"""Every literal the site_lock module depends on."""
+
+from __future__ import annotations
+
+MODULE_NAME = "SiteLock"
+MODULE_PACKAGE = "site_lock"
+
+# Dependencies — names must match the other modules' ``ModuleMeta.name``.
+MODULE_SETTINGS = "Settings"
+MODULE_AUTH = "Auth"
+
+# The gate endpoint. Double-underscore prefix keeps it clear of app routes.
+UNLOCK_PATH = "/__unlock"
+SESSION_KEY = "site_lock"
+
+# Never gated: Kubernetes liveness/readiness probes must always succeed.
+HEALTH_PREFIX = "/health"
+API_PREFIX = "/api/"
+
+# Duplicated rather than imported from ``users`` — site_lock must also work
+# under the ``keycloak`` provider, which has no dependency on ``users``.
+ADMIN_ROLE = "admin"
+
+# Brute-force limits. Deliberately NOT settings fields: they are the only
+# defence on a single shared secret and are not an operator-tunable surface.
+MAX_FAILURES = 10
+WINDOW_SECONDS = 300
+COOLDOWN_SECONDS = 900

simple_module_site_lock-0.0.30/site_lock/middleware.py

@@ -0,0 +1,177 @@
+"""Site-wide password gate.
+
+Runs outermost among module middleware — the module sorts after ``Auth``, and
+Starlette's ``add_middleware`` is LIFO — so this executes *before*
+``AuthMiddleware``. That ordering is the whole point: an anonymous visitor
+sees the gate instead of being redirected to the login page, so a locked site
+never reveals that a login form exists.
+
+``SessionMiddleware`` sits outside this one, so ``scope["session"]`` is
+readable here and writes are persisted on the way out.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import secrets
+from urllib.parse import quote
+
+from starlette.requests import Request
+from starlette.responses import (
+    HTMLResponse,
+    JSONResponse,
+    RedirectResponse,
+    Response,
+)
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from site_lock import constants as c
+from site_lock.page import render_unlock_page, safe_next
+
+logger = logging.getLogger(__name__)
+
+_NO_STORE = {"Cache-Control": "no-store"}
+_ERR_WRONG = "Incorrect password."
+_ERR_THROTTLED = "Too many attempts. Try again later."
+
+
+def password_fingerprint(password: str) -> str:
+    """Short digest of the active password, stored in the session.
+
+    Comparing this on each request is what makes a password rotation
+    invalidate every previously-unlocked session.
+    """
+    return hashlib.sha256(password.encode("utf-8")).hexdigest()[:16]
+
+
+class SiteLockMiddleware:
+    """Gate every request behind a single shared password."""
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        state = scope["app"].state.site_lock
+        settings = state.settings
+
+        # Default-off fast path: one attribute read, no Request construction.
+        if not settings.enabled:
+            await self.app(scope, receive, send)
+            return
+
+        path: str = scope["path"]
+
+        # Kubernetes probes must never be gated, or the pod gets killed.
+        if path.startswith(c.HEALTH_PREFIX):
+            await self.app(scope, receive, send)
+            return
+
+        fingerprint = password_fingerprint(settings.password)
+        session = scope.get("session")
+
+        if path == c.UNLOCK_PATH:
+            response = await self._unlock(scope, receive, state, fingerprint, session)
+            await response(scope, receive, send)
+            return
+
+        if session is not None and session.get(c.SESSION_KEY) == fingerprint:
+            await self.app(scope, receive, send)
+            return
+
+        if await self._is_admin(scope):
+            # Stamp the marker so the provider lookup costs once per session
+            # rather than once per request.
+            if session is not None:
+                session[c.SESSION_KEY] = fingerprint
+            await self.app(scope, receive, send)
+            return
+
+        await self._gate(scope, receive, send, path)
+
+    async def _gate(self, scope: Scope, receive: Receive, send: Send, path: str) -> None:
+        has_auth_header = any(k == b"authorization" for k, _ in scope.get("headers", ()))
+        if path.startswith(c.API_PREFIX) or has_auth_header:
+            # 403 rather than 401: a 401 would invite an auth flow that cannot
+            # succeed while the site is locked.
+            response: Response = JSONResponse(
+                {"detail": "Site is locked"}, status_code=403, headers=_NO_STORE
+            )
+        else:
+            target = f"{c.UNLOCK_PATH}?next={quote(safe_next(path), safe='/')}"
+            response = RedirectResponse(target, status_code=302, headers=_NO_STORE)
+        await response(scope, receive, send)
+
+    async def _unlock(
+        self,
+        scope: Scope,
+        receive: Receive,
+        state,
+        fingerprint: str,
+        session,
+    ) -> Response:
+        method: str = scope.get("method", "GET")
+        settings = state.settings
+        request = Request(scope, receive)
+
+        if method == "GET":
+            return HTMLResponse(
+                render_unlock_page(
+                    message=settings.message,
+                    next_url=request.query_params.get("next", "/"),
+                ),
+                headers=_NO_STORE,
+            )
+        if method != "POST":
+            return Response(status_code=405, headers=_NO_STORE)
+
+        client = scope.get("client")
+        key = client[0] if client else "unknown"
+        if state.limiter.is_blocked(key):
+            return self._page(settings, _ERR_THROTTLED, "/", status=429)
+
+        form = await request.form()
+        supplied = str(form.get("password", ""))
+        target = safe_next(str(form.get("next", "/")))
+
+        if secrets.compare_digest(supplied, settings.password):
+            state.limiter.reset(key)
+            if session is not None:
+                session[c.SESSION_KEY] = fingerprint
+            return RedirectResponse(target, status_code=303, headers=_NO_STORE)
+
+        state.limiter.record_failure(key)
+        return self._page(settings, _ERR_WRONG, target, status=401)
+
+    @staticmethod
+    def _page(settings, error: str, next_url: str, *, status: int) -> HTMLResponse:
+        return HTMLResponse(
+            render_unlock_page(message=settings.message, error=error, next_url=next_url),
+            status_code=status,
+            headers=_NO_STORE,
+        )
+
+    @staticmethod
+    async def _is_admin(scope: Scope) -> bool:
+        """True when the caller already holds a session for an admin user.
+
+        This is the documented lockout escape hatch: an admin who enables the
+        gate and mistypes the password keeps access to the settings screen.
+        """
+        auth_state = getattr(scope["app"].state, "auth", None)
+        provider = getattr(auth_state, "auth_provider", None)
+        if provider is None:
+            return False
+        try:
+            user = await provider.resolve_user(Request(scope))
+        except Exception:
+            logger.exception("Site lock admin bypass failed; treating as anonymous")
+            return False
+        return user is not None and c.ADMIN_ROLE in getattr(user, "roles", ())
+
+
+__all__ = ["SiteLockMiddleware", "password_fingerprint"]

simple_module_site_lock-0.0.30/site_lock/module.py

@@ -0,0 +1,47 @@
+"""Site Lock module — optional site-wide password gate."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from simple_module_core.module import ModuleBase, ModuleMeta
+
+from site_lock import constants as c
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+
+class SiteLockModule(ModuleBase):
+    meta = ModuleMeta(
+        name=c.MODULE_NAME,
+        # ``Settings`` so register_module_settings can reach the module
+        # registry; ``Auth`` so this module sorts *after* auth and its
+        # middleware therefore wraps outermost, executing before
+        # AuthMiddleware. Both are load-bearing — see the module README.
+        depends_on=[c.MODULE_SETTINGS, c.MODULE_AUTH],
+    )
+
+    def register_settings(self, app: FastAPI) -> None:
+        import importlib
+
+        from site_lock.settings import SiteLockSettings
+        from site_lock.state import SiteLockState
+
+        # SM009 is AST-based: resolving via importlib matches the convention
+        # used by the other settings-backed modules.
+        register_module_settings = importlib.import_module(
+            "settings.registration"
+        ).register_module_settings
+
+        register_module_settings(
+            app,
+            c.MODULE_PACKAGE,
+            SiteLockSettings,
+            lambda s: SiteLockState(settings=s),
+        )
+
+    def register_middleware(self, app: FastAPI) -> None:
+        from site_lock.middleware import SiteLockMiddleware
+
+        app.add_middleware(SiteLockMiddleware)

simple_module_site_lock-0.0.30/site_lock/page.py

@@ -0,0 +1,55 @@
+"""Render the standalone unlock page.
+
+Kept out of ``middleware.py`` so the escaping and ``next``-sanitisation rules
+can be unit-tested without an ASGI harness, and so both files stay well under
+the 300-line cap.
+"""
+
+from __future__ import annotations
+
+import html
+import importlib.resources
+from string import Template
+
+_TEMPLATE = Template(
+    (importlib.resources.files(__package__) / "templates" / "unlock.html").read_text(
+        encoding="utf-8"
+    )
+)
+
+_DEFAULT_MESSAGE = "This site is not public yet. Enter the password to continue."
+_ERROR_BLOCK = '<p class="error" role="alert">{message}</p>'
+
+
+def safe_next(raw: str | None) -> str:
+    """Return ``raw`` if it is a same-site absolute path, else ``/``.
+
+    Rejects protocol-relative (``//host``) and backslash-prefixed (``/\\host``)
+    targets — browsers resolve both off-site — plus anything carrying CR/LF,
+    which could otherwise be smuggled into the redirect header. Without this
+    the gate would be an open redirect.
+    """
+    if not raw or not raw.startswith("/"):
+        return "/"
+    if raw.startswith(("//", "/\\")):
+        return "/"
+    if "\r" in raw or "\n" in raw:
+        return "/"
+    return raw
+
+
+def render_unlock_page(
+    *,
+    message: str = "",
+    error: str = "",
+    next_url: str = "/",
+) -> str:
+    """Render the gate page. Every interpolated value is HTML-escaped."""
+    return _TEMPLATE.safe_substitute(
+        message=html.escape(message or _DEFAULT_MESSAGE),
+        error=_ERROR_BLOCK.format(message=html.escape(error)) if error else "",
+        next_url=html.escape(safe_next(next_url), quote=True),
+    )
+
+
+__all__ = ["render_unlock_page", "safe_next"]