flask-fenrir 0.1.0__tar.gz

flask_fenrir-0.1.0/.envrc

@@ -0,0 +1 @@
+export PYPI_TOKEN=pypi-AgEIcHlwaS5vcmcCJDg5MWY3OTBmLWYwNWEtNDU3OS05NDE4LTk1MDc1OWM4NDU2MAACKlszLCIzY2JiOTk5Ny0wMDg0LTQ3M2MtODE3Zi02YWZkZTRlMjllMmIiXQAABiBF2S2fNYfpL_9SrG9_YxQJ80z5yFYP161OOn1MS-IkSw

flask_fenrir-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+uv.lock

flask_fenrir-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fenrir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

flask_fenrir-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: flask-fenrir
+Version: 0.1.0
+Summary: Drop-in Flask API for LLM agent access to SQLModel web apps
+Project-URL: Repository, https://github.com/fenrir/fenrir-api
+Author: Fenrir
+License: MIT
+License-File: LICENSE
+Keywords: api,flask,llm,sqlalchemy,sqlmodel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Flask
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: flask>=3.0
+Requires-Dist: sqlalchemy>=2.0
+Description-Content-Type: text/markdown
+
+# flask-fenrir
+
+Drop-in Flask API for LLM agent access to SQLModel web apps. One install, two lines of code, one env var.
+
+## Install
+
+```bash
+uv add flask-fenrir
+```
+
+## Usage
+
+```python
+from flask_fenrir import create_fenrir_bp
+
+app.register_blueprint(create_fenrir_bp(engine))
+```
+
+```python
+from flask_fenrir import secure_app
+
+secure_app(app)  # optional — adds basic auth to the whole app
+```
+
+```bash
+dokku config:set myapp FENRIR_API_KEY=$(openssl rand -hex 32)
+```
+
+That's it. One env var for everything — bearer token for LLM agents, basic auth password for browser access.
+
+## What it does
+
+Registers a `/fenrir/` blueprint with four endpoints, all behind bearer token auth:
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/fenrir/` | GET | App info, FENRIR.md contents, table list with row counts |
+| `/fenrir/schema` | GET | Full schema introspection (columns, types, PKs, FKs, indexes) |
+| `/fenrir/query` | POST | Read-only SQL (`SELECT` / `WITH ... SELECT`), returns rows as JSON |
+
+### Authentication
+
+`FENRIR_API_KEY` is the single secret for your app.
+
+**Fenrir endpoints** (`/fenrir/*`) require `Authorization: Bearer <key>`.
+
+**`secure_app(app)`** (optional) adds basic auth to all other routes — any username, password must match `FENRIR_API_KEY`. This replaces Dokku's `http-auth` so everything is managed in one place.
+
+Both are skipped when `FLASK_DEBUG` is on. If the env var isn't set, everything returns 401/503 (fail closed).
+
+```python
+# Options:
+secure_app(app)                                        # basic auth on all routes
+secure_app(app, skip_paths=["/health", "/webhook"])     # skip specific paths
+secure_app(app, api_key_auth={                          # also accept a separate API key
+    "header": "X-API-Key",
+    "secret": os.getenv("API_KEY"),
+})
+```
+
+### FENRIR.md
+
+Write a `FENRIR.md` at your project root with domain context for the LLM:
+
+```markdown
+# My App
+
+A brief description of what this app does.
+
+## Domain concepts
+
+- **Widget** — the core thing users create. Has a `status` field: draft, active, archived.
+- **Team** — groups of users. The `owner_id` is always a user, not another team.
+
+## Useful queries
+
+- Active widgets by team: `SELECT t.name, COUNT(*) FROM widget w JOIN team t ON ...`
+```
+
+The `/fenrir/` endpoint serves this content so the LLM can understand your app before querying it.
+
+#### Generating FENRIR.md with an LLM
+
+If the app is running locally with flask-fenrir enabled, you can have an LLM generate the file. Run this prompt from the app's project root:
+
+```
+This app uses flask-fenrir — a small Flask blueprint that exposes the
+database to LLM agents via REST (schema introspection, read/write SQL).
+It serves a FENRIR.md file at GET /fenrir/ to give the LLM domain
+context it can't infer from the schema alone. That's the file you're
+writing now.
+
+The API is at /fenrir/.
+
+Read the codebase to understand the app's models, business logic, and
+domain. Then hit GET /fenrir/schema and POST /fenrir/query to see what
+the database actually looks like from Fenrir POV.
+
+Compare what you learned from the code with what the schema and data
+show. Write a FENRIR.md that bridges the gap — focus on things an LLM
+querying the database blind would NOT be able to figure out from the
+schema alone:
+- What the app actually does (one-liner)
+- What each table/field means in business terms
+- Non-obvious values: enums, flags, status codes, soft deletes, fields
+  whose names are misleading
+- How tables relate to each other (especially implicit relationships
+  not captured by foreign keys)
+- Common useful queries for an operator
+- Gotchas and edge cases
+
+Don't repeat what's already obvious from column names and types.
+An LLM can read a schema — FENRIR.md should add the context it can't
+infer.
+
+Ask me questions if anything in the code or data is unclear. Don't
+guess at business logic — it's better to ask than to document something
+wrong.
+
+This file will need to be maintained alongside the codebase. Keep it concise
+and structured so it's easy to update when models change. If a section
+would go stale quickly, leave it out or note what to watch for.
+```
+
+### Row limit
+
+By default, `/fenrir/query` caps results at 1000 rows. Override it:
+
+```python
+app.register_blueprint(create_fenrir_bp(engine, row_limit=500))
+```
+
+## Dependencies
+
+Just Flask (≥3.0) and SQLAlchemy (≥2.0). Works with any Flask + SQLAlchemy app — SQLModel not required at runtime.
+
+## License
+
+MIT

flask_fenrir-0.1.0/README.md

@@ -0,0 +1,139 @@
+# flask-fenrir
+
+Drop-in Flask API for LLM agent access to SQLModel web apps. One install, two lines of code, one env var.
+
+## Install
+
+```bash
+uv add flask-fenrir
+```
+
+## Usage
+
+```python
+from flask_fenrir import create_fenrir_bp
+
+app.register_blueprint(create_fenrir_bp(engine))
+```
+
+```python
+from flask_fenrir import secure_app
+
+secure_app(app)  # optional — adds basic auth to the whole app
+```
+
+```bash
+dokku config:set myapp FENRIR_API_KEY=$(openssl rand -hex 32)
+```
+
+That's it. One env var for everything — bearer token for LLM agents, basic auth password for browser access.
+
+## What it does
+
+Registers a `/fenrir/` blueprint with four endpoints, all behind bearer token auth:
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/fenrir/` | GET | App info, FENRIR.md contents, table list with row counts |
+| `/fenrir/schema` | GET | Full schema introspection (columns, types, PKs, FKs, indexes) |
+| `/fenrir/query` | POST | Read-only SQL (`SELECT` / `WITH ... SELECT`), returns rows as JSON |
+
+### Authentication
+
+`FENRIR_API_KEY` is the single secret for your app.
+
+**Fenrir endpoints** (`/fenrir/*`) require `Authorization: Bearer <key>`.
+
+**`secure_app(app)`** (optional) adds basic auth to all other routes — any username, password must match `FENRIR_API_KEY`. This replaces Dokku's `http-auth` so everything is managed in one place.
+
+Both are skipped when `FLASK_DEBUG` is on. If the env var isn't set, everything returns 401/503 (fail closed).
+
+```python
+# Options:
+secure_app(app)                                        # basic auth on all routes
+secure_app(app, skip_paths=["/health", "/webhook"])     # skip specific paths
+secure_app(app, api_key_auth={                          # also accept a separate API key
+    "header": "X-API-Key",
+    "secret": os.getenv("API_KEY"),
+})
+```
+
+### FENRIR.md
+
+Write a `FENRIR.md` at your project root with domain context for the LLM:
+
+```markdown
+# My App
+
+A brief description of what this app does.
+
+## Domain concepts
+
+- **Widget** — the core thing users create. Has a `status` field: draft, active, archived.
+- **Team** — groups of users. The `owner_id` is always a user, not another team.
+
+## Useful queries
+
+- Active widgets by team: `SELECT t.name, COUNT(*) FROM widget w JOIN team t ON ...`
+```
+
+The `/fenrir/` endpoint serves this content so the LLM can understand your app before querying it.
+
+#### Generating FENRIR.md with an LLM
+
+If the app is running locally with flask-fenrir enabled, you can have an LLM generate the file. Run this prompt from the app's project root:
+
+```
+This app uses flask-fenrir — a small Flask blueprint that exposes the
+database to LLM agents via REST (schema introspection, read/write SQL).
+It serves a FENRIR.md file at GET /fenrir/ to give the LLM domain
+context it can't infer from the schema alone. That's the file you're
+writing now.
+
+The API is at /fenrir/.
+
+Read the codebase to understand the app's models, business logic, and
+domain. Then hit GET /fenrir/schema and POST /fenrir/query to see what
+the database actually looks like from Fenrir POV.
+
+Compare what you learned from the code with what the schema and data
+show. Write a FENRIR.md that bridges the gap — focus on things an LLM
+querying the database blind would NOT be able to figure out from the
+schema alone:
+- What the app actually does (one-liner)
+- What each table/field means in business terms
+- Non-obvious values: enums, flags, status codes, soft deletes, fields
+  whose names are misleading
+- How tables relate to each other (especially implicit relationships
+  not captured by foreign keys)
+- Common useful queries for an operator
+- Gotchas and edge cases
+
+Don't repeat what's already obvious from column names and types.
+An LLM can read a schema — FENRIR.md should add the context it can't
+infer.
+
+Ask me questions if anything in the code or data is unclear. Don't
+guess at business logic — it's better to ask than to document something
+wrong.
+
+This file will need to be maintained alongside the codebase. Keep it concise
+and structured so it's easy to update when models change. If a section
+would go stale quickly, leave it out or note what to watch for.
+```
+
+### Row limit
+
+By default, `/fenrir/query` caps results at 1000 rows. Override it:
+
+```python
+app.register_blueprint(create_fenrir_bp(engine, row_limit=500))
+```
+
+## Dependencies
+
+Just Flask (≥3.0) and SQLAlchemy (≥2.0). Works with any Flask + SQLAlchemy app — SQLModel not required at runtime.
+
+## License
+
+MIT

flask_fenrir-0.1.0/flask_fenrir.py

@@ -0,0 +1,257 @@
+"""
+fenrir-api — Drop-in Flask API for LLM agent access to SQLModel web apps.
+
+Usage:
+    from flask_fenrir import create_fenrir_bp, secure_app
+
+    app.register_blueprint(create_fenrir_bp(engine))
+    secure_app(app)
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from functools import wraps
+from pathlib import Path
+
+from flask import Blueprint, Flask, Response, current_app, jsonify, request
+from sqlalchemy import inspect, text
+from sqlalchemy.engine import Engine
+
+__all__ = ["create_fenrir_bp", "secure_app"]
+
+DEFAULT_ROW_LIMIT = 1000
+
+# Matches SELECT or WITH ... SELECT (the only read-only shapes we allow)
+_READ_ONLY_RE = re.compile(
+    r"^\s*(SELECT|WITH\s)", re.IGNORECASE | re.DOTALL
+)
+
+
+def _require_auth(f):
+    """Reject requests unless Authorization header matches FENRIR_API_KEY.
+
+    Auth is skipped entirely when the Flask app has DEBUG enabled.
+    """
+
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        if current_app.debug:
+            return f(*args, **kwargs)
+
+        api_key = os.environ.get("FENRIR_API_KEY")
+        if not api_key:
+            return jsonify({"error": "FENRIR_API_KEY not configured"}), 401
+
+        auth = request.headers.get("Authorization", "")
+        if not auth.startswith("Bearer ") or auth[7:] != api_key:
+            return jsonify({"error": "unauthorized"}), 401
+
+        return f(*args, **kwargs)
+
+    return wrapper
+
+
+def secure_app(
+    app: Flask,
+    *,
+    skip_paths: list[str] | None = None,
+    api_key_auth: dict[str, str | None] | None = None,
+) -> None:
+    """Add basic auth to all routes except /fenrir/ and static files.
+
+    Uses FENRIR_API_KEY as the password (any username accepted).
+    Skipped entirely when app.debug is True.
+
+    Args:
+        app: Flask application.
+        skip_paths: Additional path prefixes to skip auth for (e.g. ["/health"]).
+        api_key_auth: Optional dict with "header" and "secret" keys for API key
+            auth (e.g. {"header": "X-API-Key", "secret": os.getenv("API_KEY")}).
+            Allows programmatic access (MCP, etc.) with a separate secret.
+    """
+    _skip = ["/fenrir/", "/static/"]
+    if skip_paths:
+        _skip.extend(skip_paths)
+
+    @app.before_request
+    def _basic_auth_check():
+        if app.debug:
+            return
+
+        # Skip excluded paths
+        path = request.path
+        if path == "/" or any(path.startswith(p) for p in _skip):
+            return
+        if request.endpoint == "static":
+            return
+
+        api_key = os.environ.get("FENRIR_API_KEY")
+        if not api_key:
+            return Response("Not configured", 503)
+
+        # Check API key header if configured (for MCP / programmatic access)
+        if api_key_auth and api_key_auth.get("secret"):
+            header_val = request.headers.get(api_key_auth.get("header", ""))
+            if header_val and header_val == api_key_auth["secret"]:
+                return
+
+        # Check basic auth — any username, password must match FENRIR_API_KEY
+        auth = request.authorization
+        if auth and auth.password == api_key:
+            return
+
+        return Response(
+            "Authentication required",
+            401,
+            {"WWW-Authenticate": 'Basic realm="Login"'},
+        )
+
+
+def _read_fenrir_md() -> str | None:
+    """Read FENRIR.md from the app's root directory."""
+    root = Path(current_app.root_path)
+    # Walk up at most two levels — root_path is often the package dir,
+    # FENRIR.md lives at the project root (next to pyproject.toml).
+    for base in [root, root.parent, root.parent.parent]:
+        candidate = base / "FENRIR.md"
+        if candidate.is_file():
+            return candidate.read_text(encoding="utf-8")
+    return None
+
+
+def _extract_app_name(md: str | None, app_name: str) -> str:
+    """Pull the first heading from FENRIR.md, or fall back to Flask app name."""
+    if md:
+        for line in md.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("#"):
+                return stripped.lstrip("#").strip()
+    return app_name
+
+
+def create_fenrir_bp(engine: Engine, *, row_limit: int = DEFAULT_ROW_LIMIT) -> Blueprint:
+    """Create and return the Fenrir API blueprint.
+
+    Args:
+        engine: SQLAlchemy engine to introspect and query.
+        row_limit: Max rows returned by /fenrir/query (default 1000).
+    """
+    bp = Blueprint("fenrir", __name__, url_prefix="/fenrir")
+
+    # -- GET /fenrir/ ----------------------------------------------------------
+
+    @bp.route("/")
+    @_require_auth
+    def index():
+        md = _read_fenrir_md()
+        app_name = _extract_app_name(md, current_app.name)
+
+        # Table list with row counts
+        insp = inspect(engine)
+        tables = []
+        with engine.connect() as conn:
+            for table_name in sorted(insp.get_table_names()):
+                count = conn.execute(
+                    text(f'SELECT COUNT(*) FROM "{table_name}"')
+                ).scalar()
+                tables.append({"name": table_name, "row_count": count})
+
+        return jsonify({
+            "app": app_name,
+            "fenrir_md": md,
+            "tables": tables,
+        })
+
+    # -- GET /fenrir/schema ----------------------------------------------------
+
+    @bp.route("/schema")
+    @_require_auth
+    def schema():
+        insp = inspect(engine)
+        tables = {}
+
+        for table_name in sorted(insp.get_table_names()):
+            columns = []
+            for col in insp.get_columns(table_name):
+                columns.append({
+                    "name": col["name"],
+                    "type": str(col["type"]),
+                    "nullable": col.get("nullable", True),
+                    "default": str(col["default"]) if col.get("default") is not None else None,
+                })
+
+            pk = insp.get_pk_constraint(table_name)
+            fks = [
+                {
+                    "columns": fk["constrained_columns"],
+                    "referred_table": fk["referred_table"],
+                    "referred_columns": fk["referred_columns"],
+                }
+                for fk in insp.get_foreign_keys(table_name)
+            ]
+            indexes = [
+                {
+                    "name": idx["name"],
+                    "columns": idx["column_names"],
+                    "unique": idx["unique"],
+                }
+                for idx in insp.get_indexes(table_name)
+            ]
+
+            tables[table_name] = {
+                "columns": columns,
+                "primary_key": pk.get("constrained_columns", []) if pk else [],
+                "foreign_keys": fks,
+                "indexes": indexes,
+            }
+
+        return jsonify({"tables": tables})
+
+    # -- POST /fenrir/query ----------------------------------------------------
+
+    @bp.route("/query", methods=["POST"])
+    @_require_auth
+    def query():
+        body = request.get_json(silent=True) or {}
+        sql = body.get("sql", "").strip()
+
+        if not sql:
+            return jsonify({"error": "missing 'sql' field"}), 400
+
+        if not _READ_ONLY_RE.match(sql):
+            return jsonify({"error": "only SELECT (or WITH ... SELECT) allowed"}), 400
+
+        try:
+            with engine.connect().execution_options(
+                postgresql_readonly=True,      # PostgreSQL
+                sqlite_raw_colnames=True,      # harmless on SQLite
+            ) as conn:
+                conn.begin()
+                # SET TRANSACTION READ ONLY works on PostgreSQL.
+                # SQLite doesn't support it, so we skip errors silently.
+                try:
+                    conn.execute(text("SET TRANSACTION READ ONLY"))
+                except Exception:
+                    pass
+                result = conn.execute(text(sql))
+                columns = list(result.keys())
+                rows = [list(r) for r in result.fetchmany(row_limit)]
+                total = len(rows)
+                # Check if there were more rows we didn't fetch
+                extra = result.fetchone()
+                truncated = extra is not None
+                conn.rollback()
+        except Exception as exc:
+            return jsonify({"error": str(exc)}), 422
+
+        return jsonify({
+            "columns": columns,
+            "rows": rows,
+            "row_count": total,
+            "truncated": truncated,
+            "row_limit": row_limit,
+        })
+
+    return bp

flask_fenrir-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "flask-fenrir"
+version = "0.1.0"
+description = "Drop-in Flask API for LLM agent access to SQLModel web apps"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.12"
+authors = [{name = "Fenrir"}]
+keywords = ["flask", "llm", "api", "sqlmodel", "sqlalchemy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Flask",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "flask>=3.0",
+    "sqlalchemy>=2.0",
+]
+
+[project.urls]
+Repository = "https://github.com/fenrir/fenrir-api"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["flask_fenrir.py"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "sqlmodel>=0.0.22",
+]

flask_fenrir-0.1.0/tests/test_fenrir_api.py

@@ -0,0 +1,415 @@
+"""Tests for fenrir-api using a minimal Flask + SQLModel app with SQLite."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+import pytest
+from flask import Flask
+from sqlalchemy import create_engine
+from sqlmodel import Field, Session, SQLModel
+
+from flask_fenrir import create_fenrir_bp, secure_app
+
+# ---------------------------------------------------------------------------
+# Models
+# ---------------------------------------------------------------------------
+
+
+class Author(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str
+    email: str | None = None
+
+
+class Book(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    title: str
+    author_id: int = Field(foreign_key="author.id")
+    pages: int | None = None
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+API_KEY = "test-secret-key"
+
+
+@pytest.fixture()
+def app(tmp_path: Path):
+    """Create a minimal Flask app with an in-memory SQLite DB."""
+    # Write a FENRIR.md next to the app
+    fenrir_md = tmp_path / "FENRIR.md"
+    fenrir_md.write_text("# Bookstore\n\nA tiny bookstore app.\n")
+
+    engine = create_engine("sqlite://", echo=False)
+    SQLModel.metadata.create_all(engine)
+
+    # Seed data
+    with Session(engine) as session:
+        a = Author(name="Tolkien", email="jrr@shire.nz")
+        session.add(a)
+        session.commit()
+        session.refresh(a)
+        session.add(Book(title="The Hobbit", author_id=a.id, pages=310))
+        session.commit()
+
+    app = Flask(__name__, root_path=str(tmp_path))
+    app.config["TESTING"] = True
+    app.register_blueprint(create_fenrir_bp(engine))
+
+    os.environ["FENRIR_API_KEY"] = API_KEY
+    yield app
+    os.environ.pop("FENRIR_API_KEY", None)
+
+
+@pytest.fixture()
+def client(app):
+    return app.test_client()
+
+
+def auth_headers():
+    return {"Authorization": f"Bearer {API_KEY}"}
+
+
+# ---------------------------------------------------------------------------
+# Auth tests
+# ---------------------------------------------------------------------------
+
+
+class TestAuth:
+    def test_missing_header(self, client):
+        r = client.get("/fenrir/")
+        assert r.status_code == 401
+
+    def test_wrong_key(self, client):
+        r = client.get("/fenrir/", headers={"Authorization": "Bearer wrong"})
+        assert r.status_code == 401
+
+    def test_correct_key(self, client):
+        r = client.get("/fenrir/", headers=auth_headers())
+        assert r.status_code == 200
+
+    def test_no_env_var(self, client):
+        os.environ.pop("FENRIR_API_KEY", None)
+        r = client.get("/fenrir/", headers={"Authorization": "Bearer anything"})
+        assert r.status_code == 401
+
+    def test_debug_mode_skips_auth(self, app):
+        app.debug = True
+        with app.test_client() as c:
+            r = c.get("/fenrir/")
+            assert r.status_code == 200
+
+    def test_debug_mode_skips_auth_even_without_env_var(self, app):
+        os.environ.pop("FENRIR_API_KEY", None)
+        app.debug = True
+        with app.test_client() as c:
+            r = c.get("/fenrir/")
+            assert r.status_code == 200
+
+
+# ---------------------------------------------------------------------------
+# GET /fenrir/
+# ---------------------------------------------------------------------------
+
+
+class TestIndex:
+    def test_returns_app_info(self, client):
+        r = client.get("/fenrir/", headers=auth_headers())
+        data = r.get_json()
+        assert data["app"] == "Bookstore"
+        assert "Bookstore" in data["fenrir_md"]
+        assert any(t["name"] == "author" for t in data["tables"])
+        assert any(t["name"] == "book" for t in data["tables"])
+
+    def test_row_counts(self, client):
+        r = client.get("/fenrir/", headers=auth_headers())
+        data = r.get_json()
+        authors = next(t for t in data["tables"] if t["name"] == "author")
+        books = next(t for t in data["tables"] if t["name"] == "book")
+        assert authors["row_count"] == 1
+        assert books["row_count"] == 1
+
+    def test_no_fenrir_md(self, tmp_path):
+        """When FENRIR.md doesn't exist, fenrir_md should be null."""
+        empty_dir = tmp_path / "empty"
+        empty_dir.mkdir()
+        engine = create_engine("sqlite://")
+        SQLModel.metadata.create_all(engine)
+
+        app = Flask(__name__, root_path=str(empty_dir))
+        app.config["TESTING"] = True
+        app.register_blueprint(create_fenrir_bp(engine))
+
+        os.environ["FENRIR_API_KEY"] = API_KEY
+        with app.test_client() as c:
+            r = c.get("/fenrir/", headers=auth_headers())
+            data = r.get_json()
+            assert data["fenrir_md"] is None
+            # Falls back to Flask app name
+            assert data["app"] is not None
+        os.environ.pop("FENRIR_API_KEY", None)
+
+
+# ---------------------------------------------------------------------------
+# GET /fenrir/schema
+# ---------------------------------------------------------------------------
+
+
+class TestSchema:
+    def test_returns_tables(self, client):
+        r = client.get("/fenrir/schema", headers=auth_headers())
+        data = r.get_json()
+        assert "author" in data["tables"]
+        assert "book" in data["tables"]
+
+    def test_column_info(self, client):
+        r = client.get("/fenrir/schema", headers=auth_headers())
+        author = r.get_json()["tables"]["author"]
+        col_names = [c["name"] for c in author["columns"]]
+        assert "id" in col_names
+        assert "name" in col_names
+        assert "email" in col_names
+
+    def test_primary_key(self, client):
+        r = client.get("/fenrir/schema", headers=auth_headers())
+        author = r.get_json()["tables"]["author"]
+        assert "id" in author["primary_key"]
+
+    def test_foreign_keys(self, client):
+        r = client.get("/fenrir/schema", headers=auth_headers())
+        book = r.get_json()["tables"]["book"]
+        assert len(book["foreign_keys"]) == 1
+        fk = book["foreign_keys"][0]
+        assert fk["referred_table"] == "author"
+
+
+# ---------------------------------------------------------------------------
+# POST /fenrir/query
+# ---------------------------------------------------------------------------
+
+
+class TestQuery:
+    def test_select(self, client):
+        r = client.post(
+            "/fenrir/query",
+            json={"sql": "SELECT name FROM author"},
+            headers=auth_headers(),
+        )
+        data = r.get_json()
+        assert data["columns"] == ["name"]
+        assert data["rows"] == [["Tolkien"]]
+        assert data["row_count"] == 1
+        assert data["truncated"] is False
+
+    def test_with_select(self, client):
+        r = client.post(
+            "/fenrir/query",
+            json={"sql": "WITH a AS (SELECT * FROM author) SELECT name FROM a"},
+            headers=auth_headers(),
+        )
+        assert r.status_code == 200
+        assert r.get_json()["row_count"] == 1
+
+    def test_rejects_insert(self, client):
+        r = client.post(
+            "/fenrir/query",
+            json={"sql": "INSERT INTO author (name) VALUES ('nope')"},
+            headers=auth_headers(),
+        )
+        assert r.status_code == 400
+
+    def test_rejects_delete(self, client):
+        r = client.post(
+            "/fenrir/query",
+            json={"sql": "DELETE FROM author"},
+            headers=auth_headers(),
+        )
+        assert r.status_code == 400
+
+    def test_missing_sql(self, client):
+        r = client.post("/fenrir/query", json={}, headers=auth_headers())
+        assert r.status_code == 400
+
+    def test_row_limit(self, tmp_path):
+        """Row limit caps the number of returned rows."""
+        engine = create_engine("sqlite://")
+        SQLModel.metadata.create_all(engine)
+
+        with Session(engine) as session:
+            for i in range(10):
+                session.add(Author(name=f"Author {i}"))
+            session.commit()
+
+        app = Flask(__name__, root_path=str(tmp_path))
+        app.config["TESTING"] = True
+        app.register_blueprint(create_fenrir_bp(engine, row_limit=3))
+
+        os.environ["FENRIR_API_KEY"] = API_KEY
+        with app.test_client() as c:
+            r = c.post(
+                "/fenrir/query",
+                json={"sql": "SELECT * FROM author"},
+                headers=auth_headers(),
+            )
+            data = r.get_json()
+            assert data["row_count"] == 3
+            assert data["truncated"] is True
+            assert data["row_limit"] == 3
+        os.environ.pop("FENRIR_API_KEY", None)
+
+    def test_bad_sql(self, client):
+        r = client.post(
+            "/fenrir/query",
+            json={"sql": "SELECT * FROM nonexistent"},
+            headers=auth_headers(),
+        )
+        assert r.status_code == 422
+
+
+# ---------------------------------------------------------------------------
+# secure_app
+# ---------------------------------------------------------------------------
+
+
+class TestSecureApp:
+    """Tests for the secure_app() basic auth middleware."""
+
+    @pytest.fixture()
+    def secured_app(self, tmp_path):
+        engine = create_engine("sqlite://")
+        SQLModel.metadata.create_all(engine)
+
+        app = Flask(__name__, root_path=str(tmp_path))
+        app.config["TESTING"] = True
+        app.register_blueprint(create_fenrir_bp(engine))
+        secure_app(app)
+
+        @app.route("/dashboard")
+        def dashboard():
+            return "ok"
+
+        @app.route("/api/data")
+        def api_data():
+            return "ok"
+
+        os.environ["FENRIR_API_KEY"] = API_KEY
+        yield app
+        os.environ.pop("FENRIR_API_KEY", None)
+
+    @pytest.fixture()
+    def secured_client(self, secured_app):
+        return secured_app.test_client()
+
+    def _basic_auth_headers(self, password=API_KEY, username="anything"):
+        import base64
+        creds = base64.b64encode(f"{username}:{password}".encode()).decode()
+        return {"Authorization": f"Basic {creds}"}
+
+    # -- Basic auth on app routes --
+
+    def test_app_route_blocked_without_auth(self, secured_client):
+        r = secured_client.get("/dashboard")
+        assert r.status_code == 401
+        assert "WWW-Authenticate" in r.headers
+
+    def test_app_route_allowed_with_basic_auth(self, secured_client):
+        r = secured_client.get("/dashboard", headers=self._basic_auth_headers())
+        assert r.status_code == 200
+
+    def test_app_route_wrong_password(self, secured_client):
+        r = secured_client.get("/dashboard", headers=self._basic_auth_headers(password="wrong"))
+        assert r.status_code == 401
+
+    def test_any_username_accepted(self, secured_client):
+        r = secured_client.get("/dashboard", headers=self._basic_auth_headers(username="bob"))
+        assert r.status_code == 200
+
+    # -- Fenrir paths skip basic auth (use their own bearer auth) --
+
+    def test_fenrir_not_blocked_by_basic_auth(self, secured_client):
+        """Fenrir endpoints should not get a basic auth challenge — they use bearer."""
+        r = secured_client.get("/fenrir/", headers=auth_headers())
+        assert r.status_code == 200
+
+    def test_fenrir_without_any_auth_gets_bearer_401(self, secured_client):
+        """Fenrir without bearer token should return JSON 401, not basic auth challenge."""
+        r = secured_client.get("/fenrir/")
+        assert r.status_code == 401
+        data = r.get_json()
+        assert data is not None  # JSON response, not basic auth HTML
+
+    # -- Debug mode --
+
+    def test_debug_skips_basic_auth(self, secured_app):
+        secured_app.debug = True
+        with secured_app.test_client() as c:
+            r = c.get("/dashboard")
+            assert r.status_code == 200
+
+    # -- No env var --
+
+    def test_no_env_var_returns_503(self, secured_client):
+        os.environ.pop("FENRIR_API_KEY", None)
+        r = secured_client.get("/dashboard")
+        assert r.status_code == 503
+
+    # -- skip_paths --
+
+    def test_skip_paths(self, tmp_path):
+        engine = create_engine("sqlite://")
+        SQLModel.metadata.create_all(engine)
+
+        app = Flask(__name__, root_path=str(tmp_path))
+        app.config["TESTING"] = True
+        app.register_blueprint(create_fenrir_bp(engine))
+        secure_app(app, skip_paths=["/health"])
+
+        @app.route("/health")
+        def health():
+            return "ok"
+
+        os.environ["FENRIR_API_KEY"] = API_KEY
+        with app.test_client() as c:
+            r = c.get("/health")
+            assert r.status_code == 200
+        os.environ.pop("FENRIR_API_KEY", None)
+
+    # -- api_key_auth --
+
+    def test_api_key_auth(self, tmp_path):
+        engine = create_engine("sqlite://")
+        SQLModel.metadata.create_all(engine)
+
+        MCP_SECRET = "mcp-secret-123"
+
+        app = Flask(__name__, root_path=str(tmp_path))
+        app.config["TESTING"] = True
+        app.register_blueprint(create_fenrir_bp(engine))
+        secure_app(app, api_key_auth={"header": "X-API-Key", "secret": MCP_SECRET})
+
+        @app.route("/api/stuff")
+        def stuff():
+            return "ok"
+
+        os.environ["FENRIR_API_KEY"] = API_KEY
+        with app.test_client() as c:
+            # Basic auth still works
+            r = c.get("/api/stuff", headers=self._basic_auth_headers())
+            assert r.status_code == 200
+            # API key header works with its own secret
+            r = c.get("/api/stuff", headers={"X-API-Key": MCP_SECRET})
+            assert r.status_code == 200
+            # FENRIR_API_KEY doesn't work as API key header
+            r = c.get("/api/stuff", headers={"X-API-Key": API_KEY})
+            assert r.status_code == 401
+            # Wrong secret rejected
+            r = c.get("/api/stuff", headers={"X-API-Key": "wrong"})
+            assert r.status_code == 401
+        os.environ.pop("FENRIR_API_KEY", None)
+