firebird-admin 1.0.1__py3-none-any.whl

fbadmin/__init__.py

@@ -0,0 +1,7 @@
+"""fbadmin - a pgAdmin-style administration tool for Firebird SQL."""
+
+__version__ = "1.0.1"
+
+from . import driver_patches as _driver_patches  # noqa: E402
+
+_driver_patches.apply()

fbadmin/__main__.py

@@ -0,0 +1,54 @@
+"""Command line entry point: ``fbadmin`` or ``python -m fbadmin``."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import threading
+import webbrowser
+
+import uvicorn
+
+from .config import settings
+from .logsetup import LEVELS, configure_logging
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(prog="fbadmin", description="Web administration tool for Firebird SQL")
+    p.add_argument("--host", default=settings.host, help="bind address (default %(default)s)")
+    p.add_argument("--port", type=int, default=settings.port, help="port (default %(default)s)")
+    p.add_argument("--no-browser", action="store_true", help="do not open a browser window")
+    p.add_argument("--reload", action="store_true", help="auto-reload on code changes (development)")
+    p.add_argument("--log-level", choices=LEVELS, default=None,
+                   help="log level (default $FBADMIN_LOG_LEVEL or info)")
+    p.add_argument("--log-format", choices=("text", "json"), default=None,
+                   help="log output format; json writes one object per line (default $FBADMIN_LOG_FORMAT or text)")
+    # --- security / server mode (docs/SECURITY.md)
+    p.add_argument("--server-mode", action="store_true",
+                   help="multi-user server mode with logins (same as FBADMIN_SERVER_MODE=1)")
+    p.add_argument("--ssl-certfile", help="serve HTTPS with this certificate (PEM)")
+    p.add_argument("--ssl-keyfile", help="private key for --ssl-certfile")
+    p.add_argument("--proxy-headers", action="store_true",
+                   help="trust X-Forwarded-Proto/For from --forwarded-allow-ips (behind a reverse proxy)")
+    p.add_argument("--forwarded-allow-ips", default=os.environ.get("FORWARDED_ALLOW_IPS", "127.0.0.1"),
+                   help="proxy addresses trusted for X-Forwarded-* headers (default %(default)s)")
+    args = p.parse_args()
+    log_config = configure_logging(args.log_level, args.log_format)
+    if args.server_mode:
+        os.environ["FBADMIN_SERVER_MODE"] = "1"
+    https = bool(args.ssl_certfile)
+    if not args.no_browser:
+        host = "localhost" if args.host in ("0.0.0.0", "127.0.0.1") else args.host
+        url = f"{'https' if https else 'http'}://{host}:{args.port}/"
+        threading.Timer(1.5, lambda: webbrowser.open(url)).start()
+    extra = {}
+    if https:
+        extra.update(ssl_certfile=args.ssl_certfile, ssl_keyfile=args.ssl_keyfile)
+    if args.proxy_headers:
+        extra.update(proxy_headers=True, forwarded_allow_ips=args.forwarded_allow_ips)
+    uvicorn.run("fbadmin.app:app", host=args.host, port=args.port, reload=args.reload,
+                log_config=log_config, access_log=False, **extra)
+
+
+if __name__ == "__main__":
+    main()

fbadmin/ai/__init__.py

@@ -0,0 +1,41 @@
+"""Opt-in AI assistant: explain plans, suggest indices, convert SQL from other dialects.
+
+Disabled unless ``FBADMIN_AI_PROVIDER`` is set. Only SQL text, plans and table DDL are
+sent to the provider — never table data. Providers are pluggable: register a class with
+``register_provider`` or via the ``fbadmin.ai_providers`` entry point group.
+"""
+
+from __future__ import annotations
+
+import os
+from importlib.metadata import entry_points
+
+from .providers import AIProvider, AnthropicProvider, AIUnavailable
+
+_PROVIDERS: dict[str, type[AIProvider]] = {"anthropic": AnthropicProvider}
+
+
+def register_provider(name: str, cls: type[AIProvider]) -> None:
+    _PROVIDERS[name] = cls
+
+
+def _load_entry_points() -> None:
+    try:
+        for ep in entry_points(group="fbadmin.ai_providers"):
+            _PROVIDERS.setdefault(ep.name, ep.load())
+    except Exception:  # noqa: BLE001 - a broken plugin must not break the app
+        pass
+
+
+def get_provider() -> AIProvider | None:
+    name = os.environ.get("FBADMIN_AI_PROVIDER", "").strip().lower()
+    if not name or name == "none":
+        return None
+    _load_entry_points()
+    cls = _PROVIDERS.get(name)
+    if cls is None:
+        raise AIUnavailable(f"Unknown AI provider {name!r}; available: {', '.join(sorted(_PROVIDERS))}")
+    return cls()
+
+
+__all__ = ["AIProvider", "AIUnavailable", "AnthropicProvider", "get_provider", "register_provider"]

fbadmin/ai/providers.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import os
+
+
+class AIUnavailable(Exception):
+    """The assistant is not configured or the provider failed."""
+
+
+class AIProvider:
+    """Interface for assistant backends."""
+
+    name = "base"
+
+    def complete(self, system: str, prompt: str) -> str:  # pragma: no cover - interface
+        raise NotImplementedError
+
+    def describe(self) -> dict:
+        return {"provider": self.name}
+
+
+class AnthropicProvider(AIProvider):
+    """Claude via the official Anthropic SDK (``pip install firebird-admin[ai]``).
+
+    Credentials come from the SDK's normal resolution (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN,
+    an ``ant auth login`` profile, ...). Model: FBADMIN_AI_MODEL (default claude-opus-5-5).
+    """
+
+    name = "anthropic"
+
+    def __init__(self) -> None:
+        try:
+            import anthropic
+        except ImportError as exc:
+            raise AIUnavailable("The 'anthropic' package is not installed: pip install 'firebird-admin[ai]'") from exc
+        self._anthropic = anthropic
+        self.model = os.environ.get("FBADMIN_AI_MODEL", "claude-opus-5-5")
+        self.effort = os.environ.get("FBADMIN_AI_EFFORT", "high")
+        self.client = anthropic.Anthropic()
+
+    def describe(self) -> dict:
+        return {"provider": self.name, "model": self.model}
+
+    def complete(self, system: str, prompt: str) -> str:
+        a = self._anthropic
+        try:
+            # Server-side fallback: if a safety classifier declines, the API re-runs the
+            # request on a fallback model inside the same call.
+            with self.client.beta.messages.stream(
+                model=self.model,
+                max_tokens=16000,
+                system=system,
+                output_config={"effort": self.effort},
+                betas=["server-side-fallback-2026-07-01"],
+                fallbacks="default",
+                messages=[{"role": "user", "content": prompt}],
+            ) as stream:
+                msg = stream.get_final_message()
+        except a.AuthenticationError as exc:
+            raise AIUnavailable("Anthropic credentials are missing or invalid (set ANTHROPIC_API_KEY)") from exc
+        except a.RateLimitError as exc:
+            raise AIUnavailable("Rate limited by the Anthropic API; try again shortly") from exc
+        except a.APIStatusError as exc:
+            raise AIUnavailable(f"Anthropic API error {exc.status_code}: {exc.message}") from exc
+        except a.APIConnectionError as exc:
+            raise AIUnavailable("Cannot reach the Anthropic API (network)") from exc
+        if msg.stop_reason == "refusal":
+            raise AIUnavailable("The model declined this request")
+        text = "".join(b.text for b in msg.content if b.type == "text").strip()
+        if msg.stop_reason == "max_tokens":
+            text += "\n\n(answer truncated)"
+        return text

fbadmin/api/__init__.py

@@ -0,0 +1,43 @@
+"""API routers. Feature modules add themselves to ROUTERS (one line each, to merge cleanly)."""
+
+from fastapi import APIRouter
+
+from . import ai  # noqa: I001 - one import per line keeps parallel branches mergeable
+from . import databases
+from . import jobs
+from . import maintenance
+from . import query
+from . import schedules
+from . import servers
+from . import trace
+from . import metrics
+from . import monitoring
+from . import replication
+from . import version as version_api
+from . import object_dialogs
+from . import schema
+from . import admin
+from . import auth
+from . import fbsecurity
+
+ROUTERS: list[APIRouter] = [
+    servers.router,
+    databases.router,
+    query.router,
+    jobs.router,
+    ai.router,
+    maintenance.router,
+    trace.router,
+    schedules.router,
+    monitoring.router,
+    monitoring.settings_router,
+    metrics.router,
+    replication.router,
+    replication.conf_router,
+    version_api.router,
+    object_dialogs.router,
+    schema.router,
+    auth.router,
+    admin.router,
+    fbsecurity.router,
+]

fbadmin/api/admin.py

@@ -0,0 +1,84 @@
+"""fbadmin user administration and the audit log viewer (administrators only)."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Query
+from pydantic import BaseModel
+
+from ..security.core import require_admin
+from ..security.errors import SecurityError
+from .deps import get_state
+
+router = APIRouter(prefix="/api/admin", tags=["admin"])
+
+
+class UserIn(BaseModel):
+    username: str
+    email: str | None = None
+    password: str | None = None
+    role: str = "user"
+    active: bool = True
+    auth_source: str = "internal"
+
+
+class UserUpdate(BaseModel):
+    email: str | None = None
+    password: str | None = None
+    role: str | None = None
+    active: bool | None = None
+
+
+def _server_mode_admin():
+    p = require_admin()
+    if p is None:
+        raise SecurityError(400, "User accounts exist only in server mode", "desktop_mode")
+    return p
+
+
+@router.get("/users")
+def list_users():
+    _server_mode_admin()
+    return get_state().security.db.list_users()
+
+
+@router.post("/users", status_code=201)
+def create_user(body: UserIn):
+    _server_mode_admin()
+    sec = get_state().security
+    if body.auth_source not in ("internal", "ldap", "proxy") and not body.auth_source.startswith("oidc:"):
+        raise SecurityError(400, f"Unknown authentication source {body.auth_source!r}", "bad_source")
+    user = sec.create_user(body.username, email=body.email, password=body.password, role=body.role,
+                           auth_source=body.auth_source, active=body.active)
+    return {k: v for k, v in user.items() if k not in ("password_hash", "vault")}
+
+
+@router.put("/users/{user_id}")
+def update_user(user_id: int, body: UserUpdate):
+    p = _server_mode_admin()
+    user = get_state().security.update_user(user_id, body.model_dump(exclude_unset=True), p)
+    return {k: v for k, v in user.items() if k not in ("password_hash", "vault")}
+
+
+@router.delete("/users/{user_id}", status_code=204)
+def delete_user(user_id: int):
+    p = _server_mode_admin()
+    get_state().security.delete_user(user_id, p)
+
+
+@router.get("/audit")
+def audit(
+    limit: int = Query(100, ge=1, le=1000),
+    offset: int = Query(0, ge=0),
+    username: str | None = None,
+    server: str | None = None,
+    q: str | None = None,
+    success: bool | None = None,
+    since: float | None = None,
+    until: float | None = None,
+    category: str | None = None,
+):
+    require_admin()
+    sec = get_state().security
+    out = sec.db.query_audit(limit=limit, offset=offset, username=username, server=server, text=q,
+                             success=success, since=since, until=until, category=category) if sec.db.exists else {"total": 0, "rows": []}
+    return {**out, "enabled": sec.audit.enabled}

fbadmin/api/ai.py

@@ -0,0 +1,117 @@
+"""AI assistant endpoints (opt-in, see fbadmin/ai)."""
+
+from __future__ import annotations
+
+import re
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from ..ai import AIUnavailable, get_provider
+from ..metadata import Catalog
+from ..query import explain
+from ..sqlsplit import bind_params
+from .deps import get_state
+
+router = APIRouter(prefix="/api/ai", tags=["ai"])
+
+SYSTEM = (
+    "You are a Firebird SQL expert embedded in fbadmin, a database administration tool. "
+    "Answer for Firebird {version} specifically (its SQL dialect, PSQL, plans and index behaviour). "
+    "Be concise and practical: short explanation, then concrete SQL in ```sql blocks when relevant. "
+    "Never invent tables or columns that are not in the provided DDL; say what is missing instead."
+)
+
+TASKS = {
+    "explain_plan": "Explain this query's execution plan in plain language. Point out full table scans "
+                    "(NATURAL / Full Scan), sorts and joins that could be slow, and why the optimizer chose them.",
+    "suggest_indexes": "Suggest indices (CREATE INDEX statements) that would make this query faster, given the plan "
+                       "and the table definitions. Mention selectivity concerns and existing indices that already cover it. "
+                       "If no index would help, say so.",
+    "convert_sql": "Convert the following SQL from {dialect} to Firebird SQL. Output the converted SQL in one ```sql block, "
+                   "then list the changes you made (e.g. LIMIT -> FETCH FIRST/ROWS, AUTO_INCREMENT -> IDENTITY, "
+                   "string concatenation, date functions, data types).",
+    "explain_error": "Explain this Firebird error for the given SQL and show the corrected SQL.",
+    "ask": "Answer the user's question about this SQL / database.",
+}
+
+
+class AskIn(BaseModel):
+    task: str
+    sql: str = ""
+    question: str = ""
+    error: str = ""
+    dialect: str = "MySQL"
+    server_id: str | None = None
+    database_id: str | None = None
+
+
+@router.get("/status")
+def status():
+    try:
+        p = get_provider()
+    except AIUnavailable as exc:
+        return {"enabled": False, "reason": str(exc)}
+    if p is None:
+        return {"enabled": False, "reason": "Set FBADMIN_AI_PROVIDER=anthropic to enable the assistant"}
+    return {"enabled": True, **p.describe()}
+
+
+def _context(server_id: str, db_id: str, sql: str, with_plan: bool) -> tuple[str, str]:
+    """Plan + DDL of the tables the statement touches; and the engine version."""
+    parts: list[str] = []
+    with get_state().manager.meta(server_id, db_id) as conn:
+        cat = Catalog(conn)
+        version = cat.engine_version
+        names: list[str] = []
+        if with_plan and sql.strip():
+            bound, _ = bind_params(sql.strip().rstrip(";"), [0])
+            try:
+                plan = explain(conn, bound)
+                detailed = explain(conn, bound, detailed=True)
+                parts.append(f"Plan:\n{plan}\n\nDetailed plan:\n{detailed}")
+                names += re.findall(r'Table (?:"[^"]+"\.)?"([^"]+)"', detailed or "")  # FB6: "SCHEMA"."T"
+            except Exception as exc:  # noqa: BLE001
+                parts.append(f"(could not prepare the statement: {exc})")
+        tables = {r["name"] for r in cat.list_objects("tables")} | {r["name"] for r in cat.list_objects("views")}
+        names += [w for w in re.findall(r'[A-Za-z_][A-Za-z0-9_$]*|"[^"]+"', sql) if w.strip('"').upper() in tables or w.strip('"') in tables]
+        seen = []
+        for n in names:
+            n = n.strip('"')
+            n = n if n in tables else n.upper()
+            if n in tables and n not in seen:
+                seen.append(n)
+        for n in seen[:12]:
+            otype = "tables" if n in {r["name"] for r in cat.list_objects("tables")} else "views"
+            try:
+                parts.append(cat.get_object(otype, n)["ddl"])
+            except Exception:  # noqa: BLE001
+                pass
+    return "\n\n".join(parts), version
+
+
+@router.post("/ask")
+def ask(body: AskIn):
+    try:
+        provider = get_provider()
+        if provider is None:
+            return JSONResponse(status_code=400, content={"detail": "AI assistant is disabled (FBADMIN_AI_PROVIDER not set)"})
+        if body.task not in TASKS:
+            return JSONResponse(status_code=400, content={"detail": f"Unknown task {body.task!r}"})
+        ctx, version = "", "3.0+"
+        if body.server_id and body.database_id and body.task != "convert_sql":
+            ctx, version = _context(body.server_id, body.database_id, body.sql,
+                                    with_plan=body.task in ("explain_plan", "suggest_indexes"))
+        prompt = TASKS[body.task].format(dialect=body.dialect)
+        if body.question:
+            prompt += f"\n\nQuestion: {body.question}"
+        if body.error:
+            prompt += f"\n\nError:\n{body.error}"
+        prompt += f"\n\nSQL:\n```sql\n{body.sql}\n```"
+        if ctx:
+            prompt += f"\n\nContext from the database:\n{ctx}"
+        answer = provider.complete(SYSTEM.format(version=version or "3.0+"), prompt)
+        return {"answer": answer, **provider.describe()}
+    except AIUnavailable as exc:
+        return JSONResponse(status_code=503, content={"detail": str(exc)})

fbadmin/api/auth.py

@@ -0,0 +1,215 @@
+"""Login, logout, first-run setup, OAuth2/OIDC and the master password (vault)."""
+
+from __future__ import annotations
+
+import urllib.parse
+
+from fastapi import APIRouter, Request, Response
+from fastapi.responses import RedirectResponse
+from pydantic import BaseModel
+
+from ..security.errors import LoginRequired, SecurityError
+from ..security.middleware import SESSION_COOKIE, clear_cookies, is_secure, session_cookies
+from ..security.oidc import identity
+from ..security.sessions import current_principal
+from .deps import get_state
+
+router = APIRouter(prefix="/api/auth", tags=["auth"])
+
+
+class LoginIn(BaseModel):
+    username: str
+    password: str
+
+
+class SetupIn(BaseModel):
+    username: str
+    email: str | None = None
+    password: str
+
+
+class PasswordChangeIn(BaseModel):
+    old_password: str
+    new_password: str
+
+
+class VaultIn(BaseModel):
+    password: str
+
+
+class VaultChangeIn(BaseModel):
+    old_password: str
+    new_password: str
+
+
+def _set_cookies(response: Response, headers: list[tuple[bytes, bytes]]) -> None:
+    for k, v in headers:
+        response.headers.append(k.decode(), v.decode())
+
+
+def _status(request: Request) -> dict:
+    sec = get_state().security
+    p = current_principal.get()
+    out: dict = {
+        "server_mode": sec.server_mode,
+        "authenticated": (p is not None) or not sec.server_mode,
+        "needs_setup": sec.needs_setup(),
+        "auth_sources": [],
+        "user": None,
+        "audit": sec.audit.enabled,
+    }
+    if sec.server_mode:
+        srcs = sec.settings.auth_sources
+        out["auth_sources"] = [{"type": "password", "name": s} for s in srcs if s in ("internal", "ldap")]
+        if "oidc" in srcs:
+            out["auth_sources"] += [{"type": "oidc", "name": o.name, "title": o.title} for o in sec.settings.oidc]
+        if "proxy" in srcs:
+            out["auth_sources"].append({"type": "proxy", "name": "proxy"})
+    if p is not None:
+        user = sec.db.get_user(p.user_id) or {}
+        out["user"] = {"id": p.user_id, "username": p.username, "role": p.role, "email": user.get("email"),
+                       "auth_source": p.auth_source}
+    elif not sec.server_mode:
+        out["user"] = {"id": 0, "username": "desktop", "role": "admin", "email": None, "auth_source": "desktop"}
+    if out["authenticated"]:
+        try:
+            out["vault"] = sec.vault_status()
+        except SecurityError:
+            out["vault"] = None
+    return out
+
+
+@router.get("/status")
+def status(request: Request):
+    return _status(request)
+
+
+def _login_response(request: Request, response: Response, principal) -> dict:
+    sec = get_state().security
+    old = request.cookies.get(SESSION_COOKIE)
+    if old:
+        sec.end_session(old)
+    session = sec.start_session(principal)
+    _set_cookies(response, session_cookies(sec, session, is_secure(sec, request.url.scheme)))
+    token = current_principal.set(principal)
+    try:
+        return {**_status(request), "csrf_token": session.csrf}
+    finally:
+        current_principal.reset(token)
+
+
+@router.post("/login")
+def login(body: LoginIn, request: Request, response: Response):
+    sec = get_state().security
+    if not sec.server_mode:
+        raise SecurityError(400, "fbadmin runs in desktop mode (no login)", "desktop_mode")
+    if sec.needs_setup():
+        raise SecurityError(409, "Create the first administrator first", "needs_setup")
+    srcs = sec.settings.auth_sources
+    if "internal" not in srcs and "ldap" not in srcs:
+        raise SecurityError(400, "Password login is disabled", "password_login_disabled")
+    p = sec.login_password(body.username, body.password, request.client.host if request.client else None)
+    return _login_response(request, response, p)
+
+
+@router.post("/setup")
+def setup(body: SetupIn, request: Request, response: Response):
+    """First run in server mode: create the initial administrator."""
+    sec = get_state().security
+    if not sec.needs_setup():
+        raise SecurityError(409, "Setup has already been completed", "setup_done")
+    sec.create_user(body.username, email=body.email, password=body.password, role="admin")
+    p = sec.login_password(body.username, body.password, request.client.host if request.client else None)
+    return _login_response(request, response, p)
+
+
+@router.post("/logout")
+def logout(request: Request, response: Response):
+    sec = get_state().security
+    sec.end_session(request.cookies.get(SESSION_COOKIE))
+    _set_cookies(response, clear_cookies(is_secure(sec, request.url.scheme)))
+    return {"ok": True}
+
+
+@router.post("/password")
+def change_password(body: PasswordChangeIn):
+    sec = get_state().security
+    p = current_principal.get()
+    if p is None:
+        raise LoginRequired()
+    sec.change_password(p, body.old_password, body.new_password)
+    return {"ok": True}
+
+
+# ------------------------------------------------------------- OAuth2 / OIDC
+def _redirect_uri(request: Request, provider: str) -> str:
+    sec = get_state().security
+    base = sec.settings.public_url or str(request.base_url).rstrip("/")
+    return f"{base}/api/auth/oidc/{urllib.parse.quote(provider)}/callback"
+
+
+@router.get("/oidc/{provider}/login")
+def oidc_login(provider: str, request: Request):
+    sec = get_state().security
+    if not sec.server_mode or "oidc" not in sec.settings.auth_sources:
+        raise SecurityError(400, "OAuth2/OIDC login is not enabled", "oidc_disabled")
+    p = sec.settings.oidc_provider(provider)
+    return RedirectResponse(sec.oidc.start(p, _redirect_uri(request, provider)), status_code=302)
+
+
+@router.get("/oidc/{provider}/callback")
+def oidc_callback(provider: str, request: Request, code: str = "", state: str = "", error: str = ""):
+    sec = get_state().security
+    if not sec.server_mode or "oidc" not in sec.settings.auth_sources:
+        raise SecurityError(400, "OAuth2/OIDC login is not enabled", "oidc_disabled")
+    if error or not code:
+        return RedirectResponse("/?login_error=" + urllib.parse.quote(error or "no code"), status_code=302)
+    p = sec.settings.oidc_provider(provider)
+    try:
+        info = identity(p, sec.oidc.finish(p, code, state))
+        principal = sec.login_external(info, f"oidc:{provider}")
+    except SecurityError as exc:
+        return RedirectResponse("/?login_error=" + urllib.parse.quote(exc.detail), status_code=302)
+    resp = RedirectResponse("/", status_code=302)
+    old = request.cookies.get(SESSION_COOKIE)
+    if old:
+        sec.end_session(old)
+    session = sec.start_session(principal)
+    _set_cookies(resp, session_cookies(sec, session, is_secure(sec, request.url.scheme)))
+    return resp
+
+
+# ------------------------------------------------------------- master password
+@router.get("/vault")
+def vault_status():
+    return get_state().security.vault_status()
+
+
+@router.post("/vault/setup")
+def vault_setup(body: VaultIn):
+    return get_state().security.vault_setup(body.password)
+
+
+@router.post("/vault/unlock")
+def vault_unlock(body: VaultIn):
+    return get_state().security.vault_unlock(body.password)
+
+
+@router.post("/vault/lock")
+def vault_lock():
+    return get_state().security.vault_lock()
+
+
+@router.post("/vault/change")
+def vault_change(body: VaultChangeIn):
+    return get_state().security.vault_change(body.old_password, body.new_password)
+
+
+@router.post("/vault/disable")
+def vault_disable(body: VaultIn):
+    return get_state().security.vault_disable(body.password)
+
+
+@router.post("/vault/reset")
+def vault_reset():
+    return get_state().security.vault_reset()