unifi-api-server 0.1.0__py3-none-any.whl

unifi_api/__init__.py

@@ -0,0 +1 @@
+"""UniFi rich HTTP API service."""

unifi_api/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for `python -m unifi_api`."""
+
+from unifi_api.cli import app
+
+
+if __name__ == "__main__":
+    app()

unifi_api/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

unifi_api/alembic/env.py

@@ -0,0 +1,64 @@
+"""Alembic env for unifi-api.
+
+The DB file is unencrypted at the engine layer (sensitive columns use
+AES-GCM at the application layer per unifi_api.db.crypto). The DB path is
+resolvable from config or via -x db_path=... on the alembic command line.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+from alembic import context
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+# Make unifi_api importable when alembic runs standalone
+_HERE = Path(__file__).resolve().parent
+_SRC = _HERE.parent / "src"
+if _SRC.exists() and str(_SRC) not in sys.path:
+    sys.path.insert(0, str(_SRC))
+
+from unifi_api.db.engine import create_engine  # noqa: E402
+from unifi_api.db.models import Base  # noqa: E402
+
+
+target_metadata = Base.metadata
+
+
+def _resolve_db_path() -> Path:
+    cli_args = context.get_x_argument(as_dictionary=True)
+    if "db_path" in cli_args:
+        return Path(cli_args["db_path"])
+    env_path = os.environ.get("UNIFI_API_DB_PATH")
+    if env_path:
+        return Path(env_path)
+    return Path("./state.db")
+
+
+def run_migrations_offline() -> None:
+    raise RuntimeError(
+        "Offline migration mode is not supported; the async engine requires "
+        "a live connection."
+    )
+
+
+async def run_migrations_online() -> None:
+    engine: AsyncEngine = create_engine(_resolve_db_path())
+    async with engine.connect() as conn:
+        await conn.run_sync(_run_sync_migrations)
+    await engine.dispose()
+
+
+def _run_sync_migrations(connection):
+    context.configure(connection=connection, target_metadata=target_metadata)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    asyncio.run(run_migrations_online())

unifi_api/alembic/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

unifi_api/alembic/versions/0001_initial_schema.py

@@ -0,0 +1,73 @@
+"""initial schema
+
+Revision ID: 0001
+Revises:
+Create Date: 2026-04-28
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision: str = "0001"
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "schema_version",
+        sa.Column("version", sa.Integer, primary_key=True),
+        sa.Column("applied_at", sa.DateTime(timezone=True), nullable=False),
+    )
+    op.create_table(
+        "api_keys",
+        sa.Column("id", sa.String(36), primary_key=True),
+        sa.Column("prefix", sa.String(64), nullable=False, unique=True),
+        sa.Column("hash", sa.String(255), nullable=False),
+        sa.Column("scopes", sa.String(64), nullable=False),
+        sa.Column("name", sa.String(128), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.create_table(
+        "controllers",
+        sa.Column("id", sa.String(36), primary_key=True),
+        sa.Column("name", sa.String(128), nullable=False),
+        sa.Column("base_url", sa.String(255), nullable=False),
+        sa.Column("product_kinds", sa.String(64), nullable=False),
+        sa.Column("credentials_blob", sa.LargeBinary, nullable=False),
+        sa.Column("verify_tls", sa.Boolean, nullable=False, server_default=sa.text("1")),
+        sa.Column("is_default", sa.Boolean, nullable=False, server_default=sa.text("0")),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+    )
+    op.create_table(
+        "sessions",
+        sa.Column("id", sa.String(36), primary_key=True),
+        sa.Column("api_key_id", sa.String(36), sa.ForeignKey("api_keys.id"), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+    )
+    op.create_table(
+        "audit_log",
+        sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+        sa.Column("ts", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("key_id_prefix", sa.String(64), nullable=False),
+        sa.Column("controller", sa.String(36), nullable=True),
+        sa.Column("target", sa.String(128), nullable=False),
+        sa.Column("outcome", sa.String(32), nullable=False),
+        sa.Column("error_kind", sa.String(64), nullable=True),
+        sa.Column("detail", sa.Text, nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("audit_log")
+    op.drop_table("sessions")
+    op.drop_table("controllers")
+    op.drop_table("api_keys")
+    op.drop_table("schema_version")

unifi_api/alembic/versions/0002_add_app_settings.py

@@ -0,0 +1,52 @@
+"""add app_settings table
+
+Revision ID: 0002
+Revises: 0001
+Create Date: 2026-04-30
+"""
+
+from datetime import datetime, timezone
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision: str = "0002"
+down_revision: Union[str, None] = "0001"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "app_settings",
+        sa.Column("key", sa.String(128), primary_key=True),
+        sa.Column("value", sa.Text, nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+    )
+    defaults = [
+        ("audit.retention.max_age_days", "90"),
+        ("audit.retention.max_rows", "1000000"),
+        ("audit.retention.enabled", "true"),
+        ("audit.retention.prune_interval_hours", "6"),
+        ("logs.file.enabled", "true"),
+        ("logs.file.path", "state/api.log"),
+        ("logs.file.max_bytes", "10485760"),
+        ("logs.file.backup_count", "5"),
+        ("logs.file.level", "INFO"),
+        ("theme.default", "auto"),
+    ]
+    op.bulk_insert(
+        sa.table(
+            "app_settings",
+            sa.column("key", sa.String),
+            sa.column("value", sa.Text),
+            sa.column("updated_at", sa.DateTime(timezone=True)),
+        ),
+        [{"key": k, "value": v, "updated_at": datetime.now(timezone.utc)} for k, v in defaults],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("app_settings")

unifi_api/alembic.ini

@@ -0,0 +1,39 @@
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+version_path_separator = os
+sqlalchemy.url = sqlite+aiosqlite:///./state.db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

unifi_api/auth/__init__.py

@@ -0,0 +1 @@
+"""Authentication module."""

unifi_api/auth/api_key.py

@@ -0,0 +1,55 @@
+"""API key generation, format validation, and argon2id hashing.
+
+Format: unifi_<env>_<22-char-base32>
+Env is "live" or "test". The 22-char body is base32-encoded random bytes.
+The "prefix" exposed in audit logs is the first 15 chars (env + first 4 random).
+"""
+
+from __future__ import annotations
+
+import re
+import secrets
+from base64 import b32encode
+from dataclasses import dataclass
+from enum import Enum
+
+from argon2 import PasswordHasher
+from argon2.exceptions import VerifyMismatchError
+
+
+KEY_PATTERN = re.compile(r"^unifi_(live|test)_[A-Z2-7]{22}$")
+KEY_PREFIX_LEN = 15
+_HASHER = PasswordHasher()
+
+
+class ApiKeyEnv(str, Enum):
+    LIVE = "live"
+    TEST = "test"
+
+
+@dataclass(frozen=True)
+class ApiKeyMaterial:
+    plaintext: str
+    prefix: str
+
+
+def generate_key(env: ApiKeyEnv = ApiKeyEnv.LIVE) -> ApiKeyMaterial:
+    body = b32encode(secrets.token_bytes(14)).decode("ascii").rstrip("=")[:22]
+    plaintext = f"unifi_{env.value}_{body}"
+    prefix = plaintext[:KEY_PREFIX_LEN]
+    return ApiKeyMaterial(plaintext=plaintext, prefix=prefix)
+
+
+def hash_key(plaintext: str) -> str:
+    if not KEY_PATTERN.fullmatch(plaintext):
+        raise ValueError("invalid key format")
+    return _HASHER.hash(plaintext)
+
+
+def verify_key(plaintext: str, digest: str) -> bool:
+    if not KEY_PATTERN.fullmatch(plaintext):
+        raise ValueError("invalid key format")
+    try:
+        return _HASHER.verify(digest, plaintext)
+    except VerifyMismatchError:
+        return False

unifi_api/auth/cache.py

@@ -0,0 +1,60 @@
+"""Argon2 verify cache.
+
+Bounded LRU keyed by SHA-256(plaintext_token), value = (api_key_id, scopes,
+fetched_at). Cache hit lets the auth path skip ~50-100ms argon2id verify.
+
+Process-global singleton initialized in server.create_app and wired into
+app.state. NOT an asyncio.Lock-guarded structure - Python dict + collections.OrderedDict
+gives us O(1) LRU and our access pattern is single-process, lock-free safe under CPython
+GIL for these atomic operations. If we move to a multi-process deployment later, this
+becomes a Redis cache with the same interface.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from collections import OrderedDict
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CachedKey:
+    api_key_id: str
+    scopes: str
+    fetched_at: float
+
+
+def _hash_plaintext(plaintext: str) -> str:
+    return hashlib.sha256(plaintext.encode("utf-8")).hexdigest()
+
+
+class ArgonVerifyCache:
+    def __init__(self, max_size: int = 1024, ttl_seconds: int = 60) -> None:
+        self._max_size = max_size
+        self._ttl = ttl_seconds
+        self._data: OrderedDict[str, CachedKey] = OrderedDict()
+
+    def get(self, plaintext: str) -> CachedKey | None:
+        h = _hash_plaintext(plaintext)
+        entry = self._data.get(h)
+        if entry is None:
+            return None
+        if time.time() - entry.fetched_at > self._ttl:
+            del self._data[h]
+            return None
+        self._data.move_to_end(h)
+        return entry
+
+    def put(self, plaintext: str, value: CachedKey) -> None:
+        h = _hash_plaintext(plaintext)
+        self._data[h] = value
+        self._data.move_to_end(h)
+        while len(self._data) > self._max_size:
+            self._data.popitem(last=False)
+
+    def invalidate(self, api_key_id: str) -> None:
+        """Drop all entries whose api_key_id matches."""
+        to_remove = [h for h, v in self._data.items() if v.api_key_id == api_key_id]
+        for h in to_remove:
+            del self._data[h]

unifi_api/auth/middleware.py

@@ -0,0 +1,98 @@
+"""Bearer token auth middleware as a FastAPI dependency factory.
+
+`_authenticate` resolves a bearer token to an ApiKey row (or raises 401).
+`require_scope(scope)` returns a FastAPI dependency that authenticates and
+then enforces the requested scope (raises 403 on insufficient scope).
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Callable
+
+from fastapi import HTTPException, Request, status
+from sqlalchemy import select
+
+from unifi_api.auth.api_key import KEY_PATTERN, KEY_PREFIX_LEN, verify_key
+from unifi_api.auth.cache import ArgonVerifyCache, CachedKey
+from unifi_api.auth.scopes import Scope, parse_scopes, scope_allows
+from unifi_api.db.models import ApiKey
+from unifi_api.logging import key_id_prefix_ctx
+from unifi_api.services.audit import write_audit
+
+
+async def _audit_denial(app, *, key_id_prefix: str, target: str, error_kind: str) -> None:
+    """Best-effort denial audit. Uses a fresh session so middleware doesn't depend on caller transaction state."""
+    sm = app.state.sessionmaker
+    async with sm() as session:
+        await write_audit(
+            session, key_id_prefix=key_id_prefix,
+            controller=None, target=target,
+            outcome="denied", error_kind=error_kind,
+        )
+        await session.commit()
+
+
+async def _authenticate(request: Request) -> ApiKey:
+    target = f"{request.method} {request.url.path}"
+    auth_header = request.headers.get("authorization", "")
+    if not auth_header.lower().startswith("bearer "):
+        await _audit_denial(request.app, key_id_prefix="(none)", target=target, error_kind="missing_bearer")
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="missing bearer token")
+    plaintext = auth_header[len("Bearer "):].strip()
+
+    if not KEY_PATTERN.fullmatch(plaintext):
+        await _audit_denial(request.app, key_id_prefix=plaintext[:KEY_PREFIX_LEN] or "(short)",
+                            target=target, error_kind="malformed_token")
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="malformed token")
+
+    cache: ArgonVerifyCache = request.app.state.argon_cache
+    cached = cache.get(plaintext)
+    sm = request.app.state.sessionmaker
+
+    if cached is not None:
+        # Cache hit — confirm not revoked
+        async with sm() as session:
+            row = (await session.execute(
+                select(ApiKey).where(ApiKey.id == cached.api_key_id)
+            )).scalar_one_or_none()
+            if row is None or row.revoked_at is not None:
+                cache.invalidate(cached.api_key_id)
+                await _audit_denial(request.app, key_id_prefix=plaintext[:KEY_PREFIX_LEN],
+                                    target=target, error_kind="unknown_token")
+                raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="unknown token")
+            key_id_prefix_ctx.set(row.prefix)
+            request.state.api_key_prefix = row.prefix
+            return row
+
+    # Cache miss — full argon2 verify path
+    prefix = plaintext[:KEY_PREFIX_LEN]
+    async with sm() as session:
+        row = (await session.execute(select(ApiKey).where(ApiKey.prefix == prefix))).scalar_one_or_none()
+        if row is None or row.revoked_at is not None:
+            await _audit_denial(request.app, key_id_prefix=prefix, target=target, error_kind="unknown_token")
+            raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="unknown token")
+        if not verify_key(plaintext, row.hash):
+            await _audit_denial(request.app, key_id_prefix=prefix, target=target, error_kind="invalid_token")
+            raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="invalid token")
+
+    cache.put(plaintext, CachedKey(api_key_id=row.id, scopes=row.scopes, fetched_at=time.time()))
+    key_id_prefix_ctx.set(row.prefix)
+    request.state.api_key_prefix = row.prefix
+    return row
+
+
+def require_scope(required: Scope) -> Callable:
+    async def _dep(request: Request) -> ApiKey:
+        api_key = await _authenticate(request)
+        held = parse_scopes(api_key.scopes)
+        if not scope_allows(held, required):
+            await _audit_denial(
+                request.app, key_id_prefix=api_key.prefix,
+                target=f"{request.method} {request.url.path}",
+                error_kind="insufficient_scope",
+            )
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="insufficient scope")
+        return api_key
+
+    return _dep

unifi_api/auth/scopes.py

@@ -0,0 +1,28 @@
+"""Scope definitions and check helpers."""
+
+from __future__ import annotations
+
+import enum
+
+
+class Scope(str, enum.Enum):
+    READ = "read"
+    WRITE = "write"
+    ADMIN = "admin"
+
+
+def parse_scopes(s: str) -> frozenset[Scope]:
+    parts = [p.strip() for p in s.split(",") if p.strip()]
+    out: set[Scope] = set()
+    for p in parts:
+        try:
+            out.add(Scope(p))
+        except ValueError as e:
+            raise ValueError(f"unknown scope: {p}") from e
+    return frozenset(out)
+
+
+def scope_allows(held: frozenset[Scope], required: Scope) -> bool:
+    if Scope.ADMIN in held:
+        return True
+    return required in held