dtxwiki 0.0.1__py3-none-any.whl

backend/__init__.py

@@ -0,0 +1 @@
+"""dtxWiki backend package."""

backend/alembic.ini

@@ -0,0 +1,38 @@
+[alembic]
+script_location = backend/migrations
+prepend_sys_path = .
+path_separator = os
+sqlalchemy.url = sqlite+pysqlite:///dtxwiki.sqlite
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+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

backend/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP API routers."""

backend/api/auth.py

@@ -0,0 +1,466 @@
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Path, Request, Response
+from fastapi.responses import JSONResponse
+
+from backend.api.deps import SessionFactoryDep
+from backend.app.errors import build_rest_error_response
+from backend.app.settings import Settings
+from backend.schemas.auth import (
+    ApiTokenCreateRequest,
+    ApiTokenDeleteResponse,
+    ApiTokenIssueResponse,
+    ApiTokenListResponse,
+    ApiTokenRevokeResponse,
+    ApiTokenUpdateRequest,
+    AuthLogoutResponse,
+    AuthMeResponse,
+    AuthSessionResponse,
+    LoginRequest,
+    PasswordChangeRequest,
+    SignupRequest,
+)
+from backend.schemas.common import RESTErrorBody
+from backend.services.api_token_service import (
+    ApiTokenNotFoundError,
+    ApiTokenRecord,
+    ApiTokenService,
+    ApiTokenServiceError,
+    InvalidApiTokenRequestError,
+)
+from backend.services.audit_service import AuditService
+from backend.services.credential_hashing import CredentialHasher
+from backend.services.session_service import (
+    AuthenticatedUser,
+    DuplicateEmailError,
+    InvalidCredentialsError,
+    InvalidSessionError,
+    PasswordPolicyError,
+    SessionResult,
+    SessionService,
+    SessionServiceError,
+    SessionTokenCodec,
+    SuspendedUserError,
+)
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+REST_ERROR_RESPONSES = {
+    401: {"model": RESTErrorBody},
+    403: {"model": RESTErrorBody},
+    404: {"model": RESTErrorBody},
+    409: {"model": RESTErrorBody},
+    422: {"model": RESTErrorBody},
+}
+
+
+def get_session_service(
+    request: Request,
+    session_factory: SessionFactoryDep,
+) -> SessionService:
+    if hasattr(request.app.state, "session_service"):
+        return request.app.state.session_service
+    settings = request.app.state.settings
+    service = SessionService(
+        session_factory=session_factory,
+        credential_hasher=CredentialHasher(),
+        token_codec=SessionTokenCodec(
+            secret=session_secret(settings),
+            ttl_seconds=settings.session_ttl_seconds,
+        ),
+        default_workspace_slug=settings.workspace_slug,
+        audit_service=AuditService(),
+    )
+    request.app.state.session_service = service
+    return service
+
+
+SessionServiceDep = Annotated[SessionService, Depends(get_session_service)]
+
+
+def get_api_token_service(
+    request: Request,
+    session_factory: SessionFactoryDep,
+) -> ApiTokenService:
+    if hasattr(request.app.state, "api_token_service"):
+        return request.app.state.api_token_service
+    service = ApiTokenService(
+        session_factory=session_factory,
+        credential_hasher=CredentialHasher(),
+    )
+    request.app.state.api_token_service = service
+    return service
+
+
+ApiTokenServiceDep = Annotated[ApiTokenService, Depends(get_api_token_service)]
+
+
+@router.post(
+    "/signup",
+    status_code=201,
+    response_model=AuthSessionResponse,
+    responses=REST_ERROR_RESPONSES,
+)
+def signup(
+    request_body: SignupRequest,
+    response: Response,
+    request: Request,
+    session_service: SessionServiceDep,
+):
+    try:
+        result = session_service.signup(
+            email=request_body.email,
+            password=request_body.password,
+            display_name=request_body.display_name,
+        )
+    except SessionServiceError as exc:
+        return auth_error_response(exc)
+    set_session_cookie(
+        response,
+        request.app.state.settings,
+        request,
+        result,
+        remember_me=request_body.remember_me,
+    )
+    return {"data": session_payload(result)}
+
+
+@router.post(
+    "/login",
+    response_model=AuthSessionResponse,
+    responses=REST_ERROR_RESPONSES,
+)
+def login(
+    request_body: LoginRequest,
+    response: Response,
+    request: Request,
+    session_service: SessionServiceDep,
+):
+    try:
+        result = session_service.login(
+            email=request_body.email,
+            password=request_body.password,
+        )
+    except SessionServiceError as exc:
+        return auth_error_response(exc)
+    set_session_cookie(
+        response,
+        request.app.state.settings,
+        request,
+        result,
+        remember_me=request_body.remember_me,
+    )
+    return {"data": session_payload(result)}
+
+
+@router.post(
+    "/logout",
+    response_model=AuthLogoutResponse,
+    responses=REST_ERROR_RESPONSES,
+)
+def logout(
+    request: Request,
+    response: Response,
+    session_service: SessionServiceDep,
+):
+    token = request.cookies.get(request.app.state.settings.session_cookie_name)
+    try:
+        session_service.logout(token)
+    except InvalidSessionError:
+        pass
+    clear_session_cookie(response, request.app.state.settings, request)
+    return {"data": {"logged_out": True}}
+
+
+@router.get(
+    "/me",
+    response_model=AuthMeResponse,
+    responses=REST_ERROR_RESPONSES,
+)
+def me(
+    request: Request,
+    session_service: SessionServiceDep,
+):
+    try:
+        user = current_session_user(request, session_service)
+    except SessionServiceError as exc:
+        return auth_error_response(exc)
+    return {"data": user_payload(user)}
+
+
+@router.post(
+    "/password",
+    response_model=AuthSessionResponse,
+    responses=REST_ERROR_RESPONSES,
+)
+def change_password(
+    request_body: PasswordChangeRequest,
+    response: Response,
+    request: Request,
+    session_service: SessionServiceDep,
+):
+    try:
+        user = current_session_user(request, session_service)
+        result = session_service.change_password(
+            user_id=user.user_id,
+            current_password=request_body.current_password,
+            new_password=request_body.new_password,
+        )
+    except SessionServiceError as exc:
+        return auth_error_response(exc)
+    set_session_cookie(response, request.app.state.settings, request, result)
+    return {"data": session_payload(result)}
+
+
+@router.get(
+    "/tokens",
+    response_model=ApiTokenListResponse,
+    responses=REST_ERROR_RESPONSES,
+)
+def list_api_tokens(
+    request: Request,
+    session_service: SessionServiceDep,
+    api_token_service: ApiTokenServiceDep,
+):
+    try:
+        user = current_session_user(request, session_service)
+        tokens = api_token_service.list_tokens(user.user_id)
+    except SessionServiceError as exc:
+        return auth_error_response(exc)
+    return {"data": [api_token_payload(token) for token in tokens]}
+
+
+@router.post(
+    "/tokens",
+    status_code=201,
+    response_model=ApiTokenIssueResponse,
+    responses=REST_ERROR_RESPONSES,
+)
+def create_api_token(
+    request_body: ApiTokenCreateRequest,
+    request: Request,
+    session_service: SessionServiceDep,
+    api_token_service: ApiTokenServiceDep,
+):
+    try:
+        user = current_session_user(request, session_service)
+        issued = api_token_service.create_token(
+            user_id=user.user_id,
+            name=request_body.name,
+            scopes=request_body.scopes,
+            expires_at=request_body.expires_at,
+            mcp_client_type=request_body.mcp_client_type,
+        )
+    except SessionServiceError as exc:
+        return auth_error_response(exc)
+    except ApiTokenServiceError as exc:
+        return api_token_error_response(exc)
+    return {
+        "data": {
+            "api_token": api_token_payload(issued.api_token),
+            "plain_token": issued.plain_token,
+        }
+    }
+
+
+@router.patch(
+    "/tokens/{token_id}",
+    response_model=ApiTokenRevokeResponse,
+    responses=REST_ERROR_RESPONSES,
+)
+def update_api_token(
+    token_id: Annotated[UUID, Path()],
+    request_body: ApiTokenUpdateRequest,
+    request: Request,
+    session_service: SessionServiceDep,
+    api_token_service: ApiTokenServiceDep,
+):
+    try:
+        user = current_session_user(request, session_service)
+        updated = api_token_service.update_token(
+            user_id=user.user_id,
+            token_id=token_id,
+            name=request_body.name,
+        )
+    except SessionServiceError as exc:
+        return auth_error_response(exc)
+    except ApiTokenServiceError as exc:
+        return api_token_error_response(exc)
+    return {"data": api_token_payload(updated)}
+
+
+@router.delete(
+    "/tokens/{token_id}/record",
+    response_model=ApiTokenDeleteResponse,
+    responses=REST_ERROR_RESPONSES,
+)
+def delete_revoked_api_token(
+    token_id: Annotated[UUID, Path()],
+    request: Request,
+    session_service: SessionServiceDep,
+    api_token_service: ApiTokenServiceDep,
+):
+    try:
+        user = current_session_user(request, session_service)
+        deleted_id = api_token_service.delete_revoked_token(
+            user_id=user.user_id,
+            token_id=token_id,
+        )
+    except SessionServiceError as exc:
+        return auth_error_response(exc)
+    except ApiTokenServiceError as exc:
+        return api_token_error_response(exc)
+    return {"data": {"id": deleted_id, "deleted": True}}
+
+
+@router.delete(
+    "/tokens/{token_id}",
+    response_model=ApiTokenRevokeResponse,
+    responses=REST_ERROR_RESPONSES,
+)
+def revoke_api_token(
+    token_id: Annotated[UUID, Path()],
+    request: Request,
+    session_service: SessionServiceDep,
+    api_token_service: ApiTokenServiceDep,
+):
+    try:
+        user = current_session_user(request, session_service)
+        revoked = api_token_service.revoke_token(
+            user_id=user.user_id,
+            token_id=token_id,
+        )
+    except SessionServiceError as exc:
+        return auth_error_response(exc)
+    except ApiTokenServiceError as exc:
+        return api_token_error_response(exc)
+    return {"data": api_token_payload(revoked)}
+
+
+def current_session_user(
+    request: Request,
+    session_service: SessionService,
+) -> AuthenticatedUser:
+    token = request.cookies.get(request.app.state.settings.session_cookie_name)
+    if token is None:
+        raise InvalidSessionError("session cookie is missing")
+    return session_service.authenticate_session(token)
+
+
+def session_secret(settings: Settings) -> str:
+    return settings.effective_session_secret
+
+
+def set_session_cookie(
+    response: Response,
+    settings: Settings,
+    request: Request,
+    result: SessionResult,
+    *,
+    remember_me: bool = True,
+) -> None:
+    cookie_options = {
+        "key": settings.session_cookie_name,
+        "value": result.session_token,
+        "httponly": True,
+        "secure": session_cookie_secure_for_request(settings, request),
+        "samesite": "lax",
+    }
+    if remember_me:
+        cookie_options["max_age"] = settings.session_ttl_seconds
+        cookie_options["expires"] = result.expires_at
+    response.set_cookie(**cookie_options)
+
+
+def clear_session_cookie(
+    response: Response,
+    settings: Settings,
+    request: Request,
+) -> None:
+    response.delete_cookie(
+        key=settings.session_cookie_name,
+        httponly=True,
+        secure=session_cookie_secure_for_request(settings, request),
+        samesite="lax",
+    )
+
+
+def session_cookie_secure_for_request(settings: Settings, request: Request) -> bool:
+    if settings.session_cookie_secure is not None:
+        return settings.session_cookie_secure
+    if settings.public_base_url is not None or settings.is_production:
+        return settings.effective_session_cookie_secure
+    if settings.behind_proxy:
+        forwarded_proto = request.headers.get("x-forwarded-proto", "")
+        first_proto = forwarded_proto.split(",", 1)[0].strip().lower()
+        if first_proto == "https":
+            return True
+    return settings.effective_session_cookie_secure
+
+
+def session_payload(result: SessionResult) -> dict:
+    return {
+        "user": user_payload(result.user),
+        "expires_at": result.expires_at,
+    }
+
+
+def user_payload(user: AuthenticatedUser) -> dict:
+    return {
+        "user_id": user.user_id,
+        "email": user.email,
+        "display_name": user.display_name,
+        "status": user.status,
+    }
+
+
+def api_token_payload(token: ApiTokenRecord) -> dict:
+    return {
+        "id": token.id,
+        "name": token.name,
+        "token_preview": token.token_preview,
+        "scopes": token.scopes,
+        "mcp_client_type": token.mcp_client_type,
+        "mcp_client_label": token.mcp_client_label,
+        "created_at": token.created_at,
+        "last_used_at": token.last_used_at,
+        "expires_at": token.expires_at,
+        "revoked_at": token.revoked_at,
+    }
+
+
+def auth_error_response(exc: SessionServiceError) -> JSONResponse:
+    return build_rest_error_response(
+        error_code=exc.error_code,
+        message=str(exc) or exc.error_code,
+        status_code=status_code_for_auth_error(exc),
+    )
+
+
+def api_token_error_response(exc: ApiTokenServiceError) -> JSONResponse:
+    return build_rest_error_response(
+        error_code=exc.error_code,
+        message=str(exc) or exc.error_code,
+        status_code=status_code_for_api_token_error(exc),
+    )
+
+
+def status_code_for_auth_error(exc: SessionServiceError) -> int:
+    if isinstance(exc, DuplicateEmailError):
+        return 409
+    if isinstance(exc, InvalidCredentialsError | InvalidSessionError):
+        return 401
+    if isinstance(exc, SuspendedUserError):
+        return 403
+    if isinstance(exc, PasswordPolicyError):
+        return 422
+    return 500
+
+
+def status_code_for_api_token_error(exc: ApiTokenServiceError) -> int:
+    if isinstance(exc, ApiTokenNotFoundError):
+        return 404
+    if isinstance(exc, InvalidApiTokenRequestError):
+        return 422
+    return 401

backend/api/deps.py

@@ -0,0 +1,61 @@
+from typing import Annotated
+
+from fastapi import Depends, Request
+from fastapi.responses import JSONResponse
+from sqlalchemy.orm import Session, sessionmaker
+
+from backend.app.errors import build_rest_error_response
+from backend.app.state import get_session_factory_from_app
+from backend.policy.auth import ActorContext
+from backend.policy.rest_scopes import require_token_scope
+from backend.services.read_errors import (
+    BundleExpiredError,
+    ChatOwnerUnresolvableError,
+    DuplicateSlugError,
+    ReadNotFoundError,
+    ReadServiceError,
+    ReadValidationError,
+    RejectedByPolicyError,
+    ReviewAlreadyClaimedError,
+    ScopeDeniedError,
+    StaleBaseVersionError,
+    UnsupportedRetrievalModeError,
+)
+
+
+def get_session_factory(request: Request) -> sessionmaker[Session]:
+    return get_session_factory_from_app(request)
+
+
+RestActorDep = Annotated[ActorContext, Depends(require_token_scope)]
+SessionFactoryDep = Annotated[sessionmaker[Session], Depends(get_session_factory)]
+
+
+def read_service_error_response(exc: ReadServiceError) -> JSONResponse:
+    return build_rest_error_response(
+        error_code=exc.error_code,
+        message=str(exc) or exc.error_code,
+        status_code=status_code_for_read_error(exc),
+    )
+
+
+def status_code_for_read_error(exc: ReadServiceError) -> int:
+    if isinstance(exc, ReadNotFoundError):
+        return 404
+    if isinstance(exc, ScopeDeniedError | RejectedByPolicyError):
+        return 403
+    if isinstance(exc, BundleExpiredError):
+        return 410
+    if isinstance(exc, DuplicateSlugError):
+        return 409
+    if isinstance(exc, ReadValidationError):
+        return 422
+    if isinstance(exc, StaleBaseVersionError):
+        return 409
+    if isinstance(exc, UnsupportedRetrievalModeError):
+        return 422
+    if isinstance(exc, ChatOwnerUnresolvableError):
+        return 422
+    if isinstance(exc, ReviewAlreadyClaimedError):
+        return 409
+    return 500

backend/api/health.py

@@ -0,0 +1,107 @@
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+
+from backend.app.db import database_health, database_ping
+from backend.app.settings import Settings
+from backend.schemas.health import (
+    HealthLiveResponse,
+    HealthReadyResponse,
+    HealthSmokeResponse,
+)
+from backend.services.oauth_service import _load_private_key
+
+router = APIRouter(tags=["health"])
+health_root_router = APIRouter(tags=["health"])
+root_router = health_root_router
+
+
+@router.get(
+    "/health",
+    response_model=HealthSmokeResponse,
+)
+def read_health(request: Request) -> HealthSmokeResponse:
+    settings: Settings = request.app.state.settings
+    return HealthSmokeResponse.model_validate({
+        "app": settings.app_name,
+        "version": settings.app_version,
+        "database": database_health(settings),
+    })
+
+
+@health_root_router.get("/health/live", response_model=HealthLiveResponse)
+def read_liveness(request: Request) -> HealthLiveResponse:
+    settings: Settings = request.app.state.settings
+    return HealthLiveResponse(
+        status="alive",
+        version=settings.app_version,
+    )
+
+
+@health_root_router.get(
+    "/health/ready",
+    response_model=HealthReadyResponse,
+    responses={503: {"model": HealthReadyResponse}},
+)
+def read_readiness(request: Request) -> JSONResponse:
+    return _ready_response(request)
+
+
+def _ready_response(request: Request) -> JSONResponse:
+    payload, status_code = _ready_payload(request)
+    return JSONResponse(payload.model_dump(), status_code=status_code)
+
+
+def _ready_payload(request: Request) -> tuple[HealthReadyResponse, int]:
+    components = {
+        "db": _check_db(request),
+        "app_version": _check_app_version(request),
+        "mcp": _check_mcp(request),
+        "oauth_jwk": _check_oauth_jwk(request),
+    }
+    ready = all(value in {"ok", "n/a"} for value in components.values())
+    return (
+        HealthReadyResponse.model_validate({
+            "status": "ready" if ready else "unhealthy",
+            "components": components,
+        }),
+        200 if ready else 503,
+    )
+
+
+def _check_db(request: Request) -> str:
+    settings: Settings = request.app.state.settings
+    ping = database_ping(settings)
+    return ping["status"]
+
+
+def _check_app_version(request: Request) -> str:
+    app_version_synced = getattr(request.app.state, "app_version_synced", None)
+    if app_version_synced is True:
+        return "ok"
+    if app_version_synced is False:
+        return "drift"
+    return "unsynced"
+
+
+def _check_mcp(request: Request) -> str:
+    settings: Settings = request.app.state.settings
+    mcp_mode = getattr(settings, "mcp_http_mode", "json_stateless")
+    if mcp_mode == "json_stateless":
+        return "n/a"
+    if getattr(request.app.state, "mcp_session_manager", None) is not None:
+        return "ok"
+    return "manager_missing"
+
+
+def _check_oauth_jwk(request: Request) -> str:
+    settings: Settings = request.app.state.settings
+    if not (
+        settings.oauth_jwt_private_key_pem
+        or settings.oauth_jwt_private_key_path
+    ):
+        return "ephemeral_unsafe"
+    try:
+        _load_private_key(settings)
+    except Exception:
+        return "invalid"
+    return "ok"