superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/server/routes/compliance.py

@@ -1,533 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-"""SuperLocalMemory V3 - Compliance Routes
- - AGPL-3.0-or-later
-
-Routes: /api/compliance/status, /api/compliance/audit,
-        /api/compliance/retention-policy
-Uses V3 compliance modules: ABACEngine, AuditChain, RetentionEngine.
-"""
-import logging
-from typing import Optional
-
-from fastapi import APIRouter, Query, Request
-from fastapi.responses import JSONResponse
-
-from superlocalmemory.server.route_mutations import authorize_route_mutation
-from superlocalmemory.storage.memory_write import memory_write
-
-from .helpers import DB_PATH, MEMORY_DIR, get_active_profile, get_engine_lazy
-
-logger = logging.getLogger("superlocalmemory.routes.compliance")
-router = APIRouter()
-
-# The engine's audit post-hooks write to <data_root>/audit_chain.db
-# (core/engine_wiring.py). The route MUST read that same file — an earlier
-# "audit.db" path pointed at a file nothing ever wrote, so the Compliance tab
-# always showed zero events.
-AUDIT_DB = MEMORY_DIR / "audit_chain.db"
-
-# Feature detection
-COMPLIANCE_AVAILABLE = False
-try:
-    from superlocalmemory.compliance.abac import ABACEngine
-    from superlocalmemory.compliance.audit import AuditChain
-    from superlocalmemory.compliance.gdpr import GDPRCompliance
-    from superlocalmemory.compliance.retention import RetentionEngine
-    COMPLIANCE_AVAILABLE = True
-except ImportError:
-    logger.info("V3 compliance engine not available")
-
-
-def _require_manage(request) -> None:
-    """Require MANAGE on the active workspace, where the workspace has roles.
-
-    A store with no roles configured has nobody to check against, and refusing
-    there would break every personal install; the loopback boundary is the
-    control in that case.
-    """
-    try:
-        from superlocalmemory.access.rbac import Permission
-        from superlocalmemory.server.rbac_enforce import require_permission
-
-        require_permission(request, Permission.MANAGE, profile=get_active_profile())
-    except ImportError:  # pragma: no cover -- roles are always present in-tree
-        return
-
-
-@router.get("/api/compliance/status")
-async def compliance_status(request: Request):
-    """Get compliance engine status for active profile."""
-    # This returns which operations ran and what categories of memory exist.
-    # That is operational metadata about someone's store; it had no gate at all.
-    from superlocalmemory.server.write_identity import require_http_mutation_actor
-
-    require_http_mutation_actor(
-        request, getattr(request.app.state, "daemon_descriptor", None),
-        actor_kind="compliance-read",
-    )
-    if not COMPLIANCE_AVAILABLE:
-        return {"available": False, "message": "Compliance engine not available"}
-
-    try:
-        profile = get_active_profile()
-
-        # Audit events (hash-chained, from the engine's live audit_chain.db).
-        # Scope the count + recent list to the active profile.
-        audit_events_count = 0
-        recent_audit_events = []
-        try:
-            audit = AuditChain(str(AUDIT_DB))
-            recent_audit_events = audit.query(profile_id=profile, limit=30)
-            # get_stats() is global; count this profile's rows for the header.
-            audit_events_count = len(audit.query(profile_id=profile, limit=100000))
-        except Exception as exc:
-            logger.debug("audit chain: %s", exc)
-
-        # Retention policies (scoped to the active profile).
-        # RetentionEngine.__init__ runs DDL (CREATE TABLE IF NOT EXISTS) so even
-        # list_rules() is a write at the constructor level — use memory_write().
-        retention_policies = []
-        try:
-            with memory_write(DB_PATH) as conn:
-                engine = RetentionEngine(conn)
-                retention_policies = engine.list_rules(profile)
-        except Exception as exc:
-            logger.debug("retention engine: %s", exc)
-
-        # ABAC policies
-        abac_policies_count = 0
-        try:
-            abac = ABACEngine()
-            abac_policies_count = len(abac._policies)
-        except Exception:
-            pass
-
-        return {
-            "available": True,
-            "active_profile": profile,
-            "audit_events_count": audit_events_count,
-            "recent_audit_events": recent_audit_events,
-            "retention_policies": retention_policies,
-            "abac_policies_count": abac_policies_count,
-        }
-    except Exception:
-        logger.exception("compliance_status error")
-        return {"available": False, "error": "Internal server error"}
-
-
-@router.get("/api/compliance/audit")
-async def query_audit_trail(
-    request: Request,
-    limit: int = Query(default=50, ge=1, le=500),
-    event_type: Optional[str] = Query(default=None),
-    since: Optional[str] = Query(default=None),
-):
-    """Query audit trail events with optional filters."""
-    if not COMPLIANCE_AVAILABLE:
-        return {"available": False, "error": "Compliance engine not available"}
-    # The audit trail reveals operations, actors, and fact_ids. This GET is not
-    # covered by the mutation middleware; the same-origin dashboard reads it via
-    # a plain GET (no token header), so gate on the loopback-trusted mutation
-    # boundary — local owner allowed, remote uncredentialed caller fails closed.
-    from superlocalmemory.server.write_identity import require_http_mutation_actor
-    require_http_mutation_actor(request, getattr(request.app.state, "daemon_descriptor", None),
-                                actor_kind="audit-read")
-    try:
-        profile = get_active_profile()
-        audit = AuditChain(str(AUDIT_DB))
-        events = audit.query(
-            profile_id=profile, operation=event_type, start_date=since,
-            limit=limit,
-        )
-        chain_ok = True
-        try:
-            chain_ok = audit.verify_integrity()
-        except Exception:
-            pass
-        return {
-            "available": True, "events": events, "total": len(events),
-            "chain_verified": chain_ok, "active_profile": profile,
-            "filters": {"event_type": event_type, "since": since, "limit": limit},
-        }
-    except Exception:
-        logger.exception("query_audit_trail error")
-        return {"available": False, "error": "Internal server error"}
-
-
-def _erasure_succeeded(result: dict) -> bool:
-    """One place that decides, so the surfaces cannot disagree.
-
-    The erasure reports two things, because they are two questions: whether the
-    data is gone, and whether that can be shown afterwards. This route used to
-    inline its own list of failure markers and the CLI used a different one, so
-    the API could say failure while the command line printed COMPLETE for the
-    same erasure.
-
-    Anything that leaves either question unanswered is a failure here. A caller
-    that wants the finer distinction reads ``erasure_complete`` and
-    ``erasure_provable`` from the body, which are both in it.
-    """
-    markers = (
-        "vector_store_failures",
-        "audit_completion_failed",
-        "audit_request_failed",
-        "receipt_persist_failed",
-        "table_delete_failures",
-        "code_graph_failed",
-        "fact_expansion_fts_failed",
-        "working_sets_failed",
-        "residue_recount_failed",
-        "backup_scan_failed",
-    )
-    if any(result.get(marker) for marker in markers):
-        return False
-    # Present on the profile path; absent on the entity path, where its absence
-    # must not be read as a failure.
-    for verdict in ("erasure_complete", "erasure_provable"):
-        if verdict in result and not result.get(verdict):
-            return False
-    return True
-
-
-@router.post("/api/compliance/retention-policy")
-async def create_retention_policy(request: Request, data: dict):
-    """Create a compliance retention policy.
-
-    Body: {
-        name: str,
-        retention_days: int,
-        category: str (maps to framework),
-        action: "archive" | "tombstone" | "notify",
-        applies_to: dict (optional)
-    }
-    """
-    # A retention rule decides what is kept and for how long, so changing one
-    # is a persistent configuration change on someone else's data. It is gated
-    # on the same loopback-trusted boundary the audit read uses, and on MANAGE
-    # in a workspace that has roles -- it had neither.
-    from superlocalmemory.server.write_identity import require_http_mutation_actor
-
-    require_http_mutation_actor(
-        request, getattr(request.app.state, "daemon_descriptor", None),
-        actor_kind="retention-policy",
-    )
-    _require_manage(request)
-    if not COMPLIANCE_AVAILABLE:
-        return {"success": False, "error": "Compliance engine not available"}
-
-    name = data.get('name')
-    retention_days = data.get('retention_days')
-    framework = data.get('category', 'custom')
-    action = data.get('action')
-    applies_to = data.get('applies_to', {})
-
-    if not name or not isinstance(name, str):
-        return {"success": False, "error": "name is required (string)"}
-    if not isinstance(retention_days, int) or retention_days < 1:
-        return {"success": False, "error": "retention_days must be a positive integer"}
-
-    valid_actions = ("archive", "tombstone", "notify")
-    if action not in valid_actions:
-        return {"success": False, "error": f"action must be one of: {valid_actions}"}
-
-    try:
-        profile = get_active_profile()
-        with memory_write(DB_PATH) as conn:
-            engine = RetentionEngine(conn)
-            rule_id = engine.create_rule(
-                name=name, framework=framework,
-                retention_days=retention_days, action=action,
-                applies_to=applies_to, profile_id=profile,
-            )
-
-        return {
-            "success": True, "rule_id": rule_id,
-            "active_profile": profile,
-            "message": f"Retention policy '{name}' created ({retention_days}d, {action})",
-        }
-    except Exception:
-        logger.exception("create_retention_policy error")
-        return {"success": False, "error": "Internal server error"}
-
-
-@router.delete("/api/compliance/retention-policy")
-async def delete_retention_policy(request: Request, name: str = Query(...)):
-    """Delete a retention policy by name for the active profile."""
-    # A retention rule decides what is kept and for how long, so changing one
-    # is a persistent configuration change on someone else's data. It is gated
-    # on the same loopback-trusted boundary the audit read uses, and on MANAGE
-    # in a workspace that has roles -- it had neither.
-    from superlocalmemory.server.write_identity import require_http_mutation_actor
-
-    require_http_mutation_actor(
-        request, getattr(request.app.state, "daemon_descriptor", None),
-        actor_kind="retention-policy",
-    )
-    _require_manage(request)
-    if not COMPLIANCE_AVAILABLE:
-        return {"success": False, "error": "Compliance engine not available"}
-    try:
-        profile = get_active_profile()
-        with memory_write(DB_PATH) as conn:
-            engine = RetentionEngine(conn)
-            removed = engine.delete_rule(profile, name)
-        if not removed:
-            return {"success": False, "error": f"Policy '{name}' not found"}
-        return {"success": True, "active_profile": profile,
-                "message": f"Retention policy '{name}' deleted"}
-    except Exception:
-        logger.exception("delete_retention_policy error")
-        return {"success": False, "error": "Internal server error"}
-
-
-@router.post("/api/compliance/retention/enforce")
-async def enforce_retention(request: Request):
-    """Run all retention policies for the active profile now.
-
-    Moves expired facts to their rule's terminal lifecycle zone (archive/
-    tombstone) or counts them (notify). Soft-state only — never a raw delete.
-    """
-    # A retention rule decides what is kept and for how long, so changing one
-    # is a persistent configuration change on someone else's data. It is gated
-    # on the same loopback-trusted boundary the audit read uses, and on MANAGE
-    # in a workspace that has roles -- it had neither.
-    from superlocalmemory.server.write_identity import require_http_mutation_actor
-
-    require_http_mutation_actor(
-        request, getattr(request.app.state, "daemon_descriptor", None),
-        actor_kind="retention-policy",
-    )
-    _require_manage(request)
-    if not COMPLIANCE_AVAILABLE:
-        return {"success": False, "error": "Compliance engine not available"}
-    try:
-        profile = get_active_profile()
-        with memory_write(DB_PATH) as conn:
-            engine = RetentionEngine(conn)
-            result = engine.enforce(profile)
-        return {"success": True, **result}
-    except Exception:
-        logger.exception("enforce_retention error")
-        return {"success": False, "error": "Internal server error"}
-
-
-# ── GDPR Art. 15/20 — Right to Access / Portability ─────────────────────────
-
-@router.get("/api/compliance/gdpr/export")
-async def gdpr_export(request: Request):
-    """Export ALL data for the active profile (GDPR Art. 20 portability).
-
-    Comprehensive 14-table export (memories, facts, entities, edges, trust,
-    feedback, behavioral patterns, provenance, audit, …) as a downloadable
-    JSON attachment. Read-only.
-    """
-    if not COMPLIANCE_AVAILABLE:
-        return {"available": False, "error": "Compliance engine not available"}
-    # A full-workspace data dump is an administrative action. Triggered by a
-    # top-level navigation (a.href) that cannot carry a credential header, so
-    # gate on the loopback-trusted mutation boundary (local owner allowed,
-    # remote uncredentialed fails closed) AND require MANAGE — in company mode
-    # a session cookie flows on navigation, so a non-admin user is still denied;
-    # the machine owner keeps MANAGE.
-    from superlocalmemory.server.rbac_enforce import require_manage
-    from superlocalmemory.server.write_identity import require_http_mutation_actor
-    require_http_mutation_actor(request, getattr(request.app.state, "daemon_descriptor", None),
-                                actor_kind="gdpr-export")
-    require_manage(request)
-    try:
-        engine = get_engine_lazy(request.app.state)
-        if engine is None:
-            return {"available": False, "error": "Engine not initialized"}
-        profile = get_active_profile()
-        data = GDPRCompliance(engine._db).export_profile_data(profile)
-        filename = f"slm-export-{profile}.json"
-        return JSONResponse(
-            content=data,
-            headers={"Content-Disposition": f'attachment; filename="{filename}"'},
-        )
-    except Exception:
-        logger.exception("gdpr_export error")
-        return {"available": False, "error": "Internal server error"}
-
-
-# ── GDPR Art. 17 — Right to Erasure ─────────────────────────────────────────
-
-@router.post("/api/compliance/gdpr/erase")
-async def gdpr_erase(request: Request, data: dict = {}):
-    """Permanently erase ALL data for the active profile (GDPR Art. 17).
-
-    IRREVERSIBLE. Requires an explicit ``confirm`` field in the body that
-    exactly matches the active profile name — this is the guard against an
-    accidental one-click wipe. The 'default' profile can never be erased
-    (enforced in GDPRCompliance.forget_profile). Mutation-authorized.
-    """
-    if not COMPLIANCE_AVAILABLE:
-        return {"success": False, "error": "Compliance engine not available"}
-    try:
-        engine = get_engine_lazy(request.app.state)
-        if engine is None:
-            return {"success": False, "error": "Engine not initialized"}
-        profile = get_active_profile()
-        confirm = (data or {}).get("confirm", "")
-        if confirm != profile:
-            return {
-                "success": False,
-                "error": (
-                    "Confirmation required: send {\"confirm\": \"" + profile +
-                    "\"} to erase this profile. This is irreversible."
-                ),
-            }
-        if profile == "default":
-            return {"success": False,
-                    "error": "The 'default' profile cannot be erased."}
-        # Irreversible erasure is admin-only (beyond mutation auth).
-        from superlocalmemory.server.rbac_enforce import require_manage
-        require_manage(request, profile=profile)
-        authorization = authorize_route_mutation(
-            request,
-            operation="delete",
-            source_agent_id="http-gdpr-erase",
-            profile_id=profile,
-        )
-        result = GDPRCompliance(engine._db, engine=engine).forget_profile(profile)
-        authorization.complete()
-        result = result or {}
-        success = _erasure_succeeded(result)
-        return {"success": success, "active_profile": profile, **result}
-    except Exception:
-        logger.exception("gdpr_erase error")
-        return {"success": False, "error": "Internal server error"}
-
-
-# ── GDPR Art. 17 — Entity-level Erasure ──────────────────────────────────────
-
-@router.post("/api/compliance/gdpr/erase-entity")
-async def gdpr_erase_entity(request: Request, data: dict = {}):
-    """Erase all facts mentioning a named entity for the active profile.
-
-    IRREVERSIBLE. Body must contain an ``entity_name`` and a ``confirm``
-    field that exactly matches ``entity_name`` — same confirm-guard pattern
-    as profile erasure. Mutation-authorized; requires MANAGE permission.
-    """
-    if not COMPLIANCE_AVAILABLE:
-        return {"success": False, "error": "Compliance engine not available"}
-    try:
-        engine = get_engine_lazy(request.app.state)
-        if engine is None:
-            return {"success": False, "error": "Engine not initialized"}
-        profile = get_active_profile()
-        entity_name = ((data or {}).get("entity_name") or "").strip()
-        confirm = (data or {}).get("confirm", "")
-        if not entity_name:
-            return {"success": False, "error": "entity_name is required"}
-        if confirm != entity_name:
-            return {
-                "success": False,
-                "error": (
-                    "Confirmation required: send {\"confirm\": \"" + entity_name +
-                    "\"} to erase this entity. This is irreversible."
-                ),
-            }
-        from superlocalmemory.server.rbac_enforce import require_manage
-        from superlocalmemory.server.write_identity import require_http_mutation_actor
-        require_http_mutation_actor(
-            request,
-            getattr(request.app.state, "daemon_descriptor", None),
-            actor_kind="gdpr-erase-entity",
-        )
-        require_manage(request, profile=profile)
-        authorization = authorize_route_mutation(
-            request,
-            operation="delete",
-            source_agent_id="http-gdpr-erase-entity",
-            profile_id=profile,
-        )
-        result = GDPRCompliance(engine._db, engine=engine).forget_entity(entity_name, profile)
-        authorization.complete()
-        result = result or {}
-        success = _erasure_succeeded(result)
-        return {
-            "success": success, "active_profile": profile,
-            "entity_name": entity_name, **result,
-        }
-    except Exception:
-        logger.exception("gdpr_erase_entity error")
-        return {"success": False, "error": "Internal server error"}
-
-
-# ── Erasure Receipts — list + cryptographic verify ───────────────────────────
-
-@router.get("/api/compliance/receipts")
-async def list_erasure_receipts(
-    request: Request,
-    limit: int = Query(default=50, ge=1, le=200),
-):
-    """List recent erasure receipts for the active profile.
-
-    Returns summary rows from ``erasure_receipts`` (migration M035):
-    erasure_id, subject_type, subject_id, state, all_erased, fact_count,
-    requested_at, completed_at. Read-only; loopback-gated.
-    """
-    if not COMPLIANCE_AVAILABLE:
-        return {"available": False, "error": "Compliance engine not available"}
-    from superlocalmemory.server.write_identity import require_http_mutation_actor
-    require_http_mutation_actor(
-        request,
-        getattr(request.app.state, "daemon_descriptor", None),
-        actor_kind="erasure-receipts-read",
-    )
-    try:
-        engine = get_engine_lazy(request.app.state)
-        if engine is None:
-            return {"available": False, "error": "Engine not initialized"}
-        profile = get_active_profile()
-        try:
-            rows = engine._db.execute(
-                "SELECT erasure_id, subject_type, subject_id, state, all_erased, "
-                "fact_count, requested_at, completed_at "
-                "FROM erasure_receipts WHERE profile_id = ? "
-                "ORDER BY requested_at DESC LIMIT ?",
-                (profile, limit),
-            )
-            receipts = [dict(r) for r in rows]
-        except Exception:
-            receipts = []
-        return {
-            "available": True, "active_profile": profile,
-            "receipts": receipts, "total": len(receipts),
-        }
-    except Exception:
-        logger.exception("list_erasure_receipts error")
-        return {"available": False, "error": "Internal server error"}
-
-
-@router.get("/api/compliance/receipts/{erasure_id}/verify")
-async def verify_erasure_receipt(request: Request, erasure_id: str):
-    """Cryptographically verify an erasure receipt's audit hash.
-
-    Returns ``{verified: bool}`` — True means the stored hash matches a
-    recompute from the receipt fields (tamper-evident). Read-only;
-    loopback-gated.
-    """
-    if not COMPLIANCE_AVAILABLE:
-        return {"available": False, "error": "Compliance engine not available"}
-    from superlocalmemory.server.write_identity import require_http_mutation_actor
-    require_http_mutation_actor(
-        request,
-        getattr(request.app.state, "daemon_descriptor", None),
-        actor_kind="erasure-receipt-verify",
-    )
-    try:
-        engine = get_engine_lazy(request.app.state)
-        if engine is None:
-            return {"available": False, "error": "Engine not initialized"}
-        profile = get_active_profile()
-        from superlocalmemory.core.transactions.erasure import verify_receipt
-        with engine._db.raw_connection() as conn:
-            verified = verify_receipt(conn, erasure_id, profile_id=profile)
-        return {"available": True, "erasure_id": erasure_id, "verified": verified}
-    except Exception:
-        logger.exception("verify_erasure_receipt error")
-        return {"available": False, "error": "Internal server error"}