voidaccess 1.3.0__py3-none-any.whl

analysis/temporal.py

@@ -0,0 +1,201 @@
+"""
+analysis/temporal.py — Time-series analysis of forum and actor behavior.
+
+Detects anomalies that historically precede significant events (exit scams,
+law enforcement actions, major releases).
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from collections import defaultdict
+from datetime import date, datetime, timedelta, timezone
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def build_activity_timeline(
+    entity_value: str,
+    entity_type: str,
+    since: Optional[datetime] = None,
+) -> list[dict]:
+    """
+    Query DB for all pages where this entity appeared, grouped by day.
+
+    Returns list of {"date": date, "count": int, "page_ids": list[str]}.
+    Returns [] if no data or DB unavailable. Never raises.
+    """
+    try:
+        from db.models import Entity, Page
+        from db.session import get_session
+
+        with get_session() as session:
+            entities = (
+                session.query(Entity)
+                .filter(
+                    Entity.entity_type == entity_type,
+                    Entity.value == entity_value,
+                )
+                .all()
+            )
+
+            if not entities:
+                return []
+
+            page_ids = list({e.page_id for e in entities if e.page_id is not None})
+            if not page_ids:
+                return []
+
+            q = session.query(Page).filter(Page.id.in_(page_ids))
+            if since is not None:
+                q = q.filter(Page.scrape_timestamp >= since)
+            pages = q.all()
+
+            if not pages:
+                return []
+
+            by_date: dict[date, list[str]] = defaultdict(list)
+            skipped_count = 0
+            for page in pages:
+                ts = page.posted_at
+                if ts is None:
+                    skipped_count += 1
+                    continue
+                day = ts.date() if hasattr(ts, "date") else ts
+                by_date[day].append(str(page.id))
+            if skipped_count > 0:
+                logger.debug(
+                    "build_activity_timeline: skipped %d pages due to missing posted_at",
+                    skipped_count,
+                )
+
+            return [
+                {"date": d, "count": len(ids), "page_ids": ids}
+                for d, ids in sorted(by_date.items())
+            ]
+
+    except Exception as exc:
+        logger.debug("build_activity_timeline: DB unavailable (%s)", exc)
+        return []
+
+
+def compute_activity_stats(timeline: list[dict]) -> dict:
+    """
+    Compute summary statistics for an activity timeline.
+
+    Returns a dict with mean_daily, std_daily, peak_day, peak_count,
+    total_appearances, active_days, first_seen, last_seen.
+    """
+    if not timeline:
+        return {
+            "mean_daily": 0.0,
+            "std_daily": 0.0,
+            "peak_day": None,
+            "peak_count": 0,
+            "total_appearances": 0,
+            "active_days": 0,
+            "first_seen": None,
+            "last_seen": None,
+        }
+
+    counts = [entry["count"] for entry in timeline]
+    dates = [entry["date"] for entry in timeline]
+
+    n = len(counts)
+    total = sum(counts)
+    mean_daily = total / n
+
+    variance = sum((c - mean_daily) ** 2 for c in counts) / n
+    std_daily = math.sqrt(variance)
+
+    peak_idx = counts.index(max(counts))
+
+    return {
+        "mean_daily": float(mean_daily),
+        "std_daily": float(std_daily),
+        "peak_day": dates[peak_idx],
+        "peak_count": int(counts[peak_idx]),
+        "total_appearances": int(total),
+        "active_days": n,
+        "first_seen": dates[0] if dates else None,
+        "last_seen": dates[-1] if dates else None,
+    }
+
+
+Z_SCORE_THRESHOLD = 2.5
+MIN_DATA_POINTS = 10
+MIN_ABSOLUTE_SPIKE = 5
+
+
+def detect_anomalies(
+    timeline: list[dict],
+    z_threshold: float = Z_SCORE_THRESHOLD,
+) -> list[dict]:
+    """
+    Flag days where activity deviates > z_threshold standard deviations.
+
+    Returns list of {"date": date, "count": int, "z_score": float, "type": str}.
+    Returns [] for timelines with fewer than 10 data points OR fewer than 5 posts.
+    """
+    if len(timeline) < MIN_DATA_POINTS:
+        return []
+
+    stats = compute_activity_stats(timeline)
+    mean = stats["mean_daily"]
+    std = stats["std_daily"]
+
+    if std == 0.0:
+        return []
+
+    anomalies: list[dict] = []
+    for entry in timeline:
+        count = entry["count"]
+        z = (count - mean) / std
+        if abs(z) > z_threshold:
+            if z > 0 and count < MIN_ABSOLUTE_SPIKE:
+                continue
+            anomalies.append(
+                {
+                    "date": entry["date"],
+                    "count": count,
+                    "z_score": float(z),
+                    "type": "spike" if z > 0 else "drop",
+                }
+            )
+
+    return anomalies
+
+
+def detect_silence_breaks(
+    timeline: list[dict],
+    silence_days: int = 14,
+) -> list[dict]:
+    """
+    Find cases where the entity was inactive for silence_days or more,
+    then reappeared.
+
+    Returns list of {"silent_from": date, "silent_to": date, "gap_days": int}.
+    Significant for tracking actor reappearances under new names.
+    """
+    if len(timeline) < 2:
+        return []
+
+    sorted_entries = sorted(timeline, key=lambda x: x["date"])
+    breaks: list[dict] = []
+
+    for i in range(1, len(sorted_entries)):
+        prev_date = sorted_entries[i - 1]["date"]
+        curr_date = sorted_entries[i]["date"]
+        gap = (curr_date - prev_date).days
+        if gap >= silence_days:
+            breaks.append(
+                {
+                    "silent_from": prev_date,
+                    "silent_to": curr_date,
+                    "gap_days": gap,
+                }
+            )
+
+    return breaks

api/__init__.py

@@ -0,0 +1 @@
+# api package — Phase 5 FastAPI REST API

api/auth.py

@@ -0,0 +1,163 @@
+"""
+JWT authentication for VoidAccess API.
+
+Flow:
+1. POST /auth/login → returns access_token (JWT, 8hr expiry)
+2. All protected routes require: Authorization: Bearer {token}
+3. First login with default password → returns {must_reset: true}
+4. POST /auth/reset-password → sets new password, clears must_reset flag
+"""
+
+import secrets
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
+
+from config import JWT_SECRET
+from db.models import User
+from db.session import get_session, get_db
+from auth.token_blacklist import is_token_revoked
+
+# Config — single canonical source from config.py
+SECRET = JWT_SECRET
+JWT_ALGORITHM = "HS256"
+JWT_EXPIRY_HOURS = 8
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+bearer_scheme = HTTPBearer()
+
+
+# ─── Pydantic schemas ──────────────────────────────────────────────────────
+
+class LoginRequest(BaseModel):
+    email: str
+    password: str
+
+class LoginResponse(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+    must_reset_password: bool
+
+class ResetPasswordRequest(BaseModel):
+    current_password: str
+    new_password: str
+    confirm_password: str
+
+class TokenData(BaseModel):
+    user_id: int
+    email: str
+    jti: Optional[str] = None
+
+
+# ─── Core functions ────────────────────────────────────────────────────────
+
+def verify_password(plain: str, hashed: str) -> bool:
+    return pwd_context.verify(plain, hashed)
+
+def hash_password(plain: str) -> str:
+    return pwd_context.hash(plain)
+
+def create_access_token(user_id: int, email: str) -> tuple[str, str]:
+    jti = secrets.token_hex(16)
+    now = datetime.now(timezone.utc)
+    payload = {
+        "sub": str(user_id),
+        "email": email,
+        "jti": jti,
+        "exp": now + timedelta(hours=JWT_EXPIRY_HOURS),
+        "iat": now,
+    }
+    token = jwt.encode(payload, SECRET, algorithm=JWT_ALGORITHM)
+    return token, jti
+
+class TokenPayload(BaseModel):
+    user_id: int
+    email: str
+    jti: str
+    exp: datetime
+
+
+def decode_token(token: str) -> TokenPayload:
+    payload = jwt.decode(token, SECRET, algorithms=[JWT_ALGORITHM])
+    user_id = int(payload["sub"])
+    email = payload["email"]
+    jti = payload.get("jti", "")
+    exp = payload["exp"]
+    return TokenPayload(user_id=user_id, email=email, jti=jti, exp=exp)
+
+
+from pydantic import BaseModel, ConfigDict
+
+
+# ─── FastAPI dependency ────────────────────────────────────────────────────
+
+class CurrentUser(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    
+    user: User
+    jti: str
+    exp: Optional[datetime] = None
+
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(bearer_scheme),
+    db: Session = Depends(get_db),
+) -> CurrentUser:
+    """
+    Dependency for protected routes.
+    Usage: current: CurrentUser = Depends(get_current_user)
+    Now uses request-scoped 'db' session to ensure user is not detached.
+    """
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Invalid or expired token",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    revoked_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Token has been revoked",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        token_payload = decode_token(credentials.credentials)
+    except JWTError:
+        raise credentials_exception
+
+    if token_payload.jti:
+        if await is_token_revoked(token_payload.jti):
+            raise revoked_exception
+
+    user = db.query(User).filter(
+        User.id == token_payload.user_id,
+        User.is_active == True,
+    ).first()
+
+    if not user:
+        raise credentials_exception
+
+    return CurrentUser(user=user, jti=token_payload.jti, exp=token_payload.exp)
+
+
+async def require_password_not_reset_pending(
+    current_user: CurrentUser = Depends(get_current_user),
+) -> CurrentUser:
+    """Dependency for resource-creating endpoints — blocks access when a password reset is required."""
+    if getattr(current_user.user, "must_reset_password", False):
+        raise HTTPException(
+            status_code=403,
+            detail={
+                "error": "password_reset_required",
+                "message": (
+                    "You must change your password before continuing. "
+                    "Use POST /auth/reset-password"
+                ),
+                "code": "PASSWORD_RESET_REQUIRED",
+            },
+        )
+    return current_user