tethr-engine 0.1.0__py3-none-any.whl

tethr_engine/__init__.py

@@ -0,0 +1 @@
+"""tethr_engine — Standalone Familiar identity engine package."""

tethr_engine/api_keys.py

@@ -0,0 +1,86 @@
+"""
+api_keys.py — External API key management for network access mode.
+
+Keys are prefixed 'fam_' and stored as SHA-256 hashes in the api_keys table.
+The plaintext key is returned only once at creation time — store it immediately.
+"""
+import hashlib
+import secrets
+from datetime import datetime, timezone
+
+from tethr_engine.database import get_connection
+
+
+def _hash_key(key: str) -> str:
+    return hashlib.sha256(key.encode()).hexdigest()
+
+
+def create_api_key(name: str) -> dict:
+    """
+    Generate a new API key, store hash in DB.
+    Returns {"id": int, "key": str, "name": str} — key is plaintext, shown once.
+    """
+    key = "fam_" + secrets.token_urlsafe(32)
+    key_hash = _hash_key(key)
+    conn = get_connection()
+    try:
+        cursor = conn.execute(
+            "INSERT INTO api_keys (key_hash, name, created_at, active) VALUES (?, ?, ?, 1)",
+            (key_hash, name, datetime.now(timezone.utc).isoformat()),
+        )
+        conn.commit()
+        key_id = cursor.lastrowid
+    finally:
+        conn.close()
+    return {"id": key_id, "key": key, "name": name}
+
+
+def verify_api_key(key: str) -> int | None:
+    """
+    Validate a raw API key. Returns the api_key id if active, None otherwise.
+    Updates last_used on success.
+    """
+    key_hash = _hash_key(key)
+    conn = get_connection()
+    try:
+        row = conn.execute(
+            "SELECT id FROM api_keys WHERE key_hash = ? AND active = 1",
+            (key_hash,),
+        ).fetchone()
+        if row:
+            conn.execute(
+                "UPDATE api_keys SET last_used = ? WHERE id = ?",
+                (datetime.now(timezone.utc).isoformat(), row["id"]),
+            )
+            conn.commit()
+            return row["id"]
+    finally:
+        conn.close()
+    return None
+
+
+def revoke_api_key(key_id: int) -> bool:
+    """Deactivate an API key by id. Returns True if found and deactivated."""
+    conn = get_connection()
+    try:
+        cursor = conn.execute(
+            "UPDATE api_keys SET active = 0 WHERE id = ? AND active = 1",
+            (key_id,),
+        )
+        conn.commit()
+        return cursor.rowcount > 0
+    finally:
+        conn.close()
+
+
+def list_api_keys() -> list:
+    """Return all active API keys (key_hash excluded)."""
+    conn = get_connection()
+    try:
+        rows = conn.execute(
+            "SELECT id, name, created_at, last_used "
+            "FROM api_keys WHERE active = 1 ORDER BY created_at DESC"
+        ).fetchall()
+        return [dict(r) for r in rows]
+    finally:
+        conn.close()

tethr_engine/audit.py

@@ -0,0 +1,245 @@
+"""
+audit.py — Audit logging, input sanitization middleware, and injection detection.
+
+Audit log: immutable record of security events.
+Sanitization middleware: strips null bytes and control characters, then scans
+  all string fields for prompt injection patterns before routing.
+detect_injection(): flags instruction override, role hijack, system prompt
+  extraction, jailbreak, and identity replacement attempts.
+"""
+import logging
+import re
+import sqlite3
+
+from tethr_engine.database import get_connection
+
+logger = logging.getLogger(__name__)
+
+
+# ── audit log ─────────────────────────────────────────────
+
+def log_audit(
+    action: str,
+    user_id: str = None,
+    details: str = None,
+    ip_address: str = None,
+):
+    """Write a security event to the audit_log table."""
+    conn = get_connection()
+    try:
+        conn.execute(
+            "INSERT INTO audit_log (user_id, action, details, ip_address) VALUES (?, ?, ?, ?)",
+            (user_id, action, details, ip_address)
+        )
+        conn.commit()
+    except Exception as e:
+        print(f"[audit] WARN — failed to write audit event '{action}': {e}")
+    finally:
+        conn.close()
+
+
+# ── prompt injection detection ────────────────────────────
+# Patterns are ordered within each category by specificity.
+# confidence: 3 = high certainty (exact known phrase), 2 = likely, 1 = possible.
+
+_INJECTION_PATTERNS: list[tuple[str, int, re.Pattern]] = []
+
+def _build_injection_patterns():
+    """Compile injection detection patterns once at import time."""
+    raw = [
+        # (threat_type, confidence, pattern_string)
+        # Instruction override
+        ("instruction_override", 3, r"ignore\s+previous\s+instructions?"),
+        ("instruction_override", 3, r"ignore\s+all\s+(previous\s+)?instructions?"),
+        ("instruction_override", 3, r"forget\s+your\s+instructions?"),
+        ("instruction_override", 3, r"new\s+instructions?[\s:]+"),
+        ("instruction_override", 2, r"\bdisregard\b"),
+        # Role hijack
+        ("role_hijack", 3, r"you\s+are\s+now\s+\w"),
+        ("role_hijack", 3, r"you\s+have\s+been\s+reprogrammed"),
+        ("role_hijack", 3, r"your\s+new\s+name\s+is\b"),
+        ("role_hijack", 2, r"\bpretend\s+you\s+are\b"),
+        ("role_hijack", 2, r"\bact\s+as\s+(an?\s+)?\w"),
+        # System prompt extraction
+        ("system_prompt_extraction", 3, r"repeat\s+your\s+instructions?"),
+        ("system_prompt_extraction", 3, r"show\s+(me\s+)?your\s+system\s+prompt"),
+        ("system_prompt_extraction", 3, r"print\s+your\s+(system\s+)?prompt"),
+        ("system_prompt_extraction", 2, r"what\s+are\s+your\s+instructions?"),
+        ("system_prompt_extraction", 2, r"reveal\s+your\s+(system\s+)?prompt"),
+        # Jailbreak
+        ("jailbreak", 3, r"\bDAN\b"),
+        ("jailbreak", 3, r"\bdeveloper\s+mode\b"),
+        ("jailbreak", 3, r"\bunrestricted\s+mode\b"),
+        ("jailbreak", 2, r"\bno\s+restrictions?\b"),
+        ("jailbreak", 2, r"\bwithout\s+filters?\b"),
+        # Identity replacement
+        ("identity_replacement", 3, r"your\s+real\s+name\s+is\b"),
+        ("identity_replacement", 3, r"your\s+true\s+identity\b"),
+        ("identity_replacement", 3, r"you\s+were\s+actually\b"),
+    ]
+    for threat_type, confidence, pattern in raw:
+        _INJECTION_PATTERNS.append(
+            (threat_type, confidence, re.compile(pattern, re.IGNORECASE))
+        )
+
+_build_injection_patterns()
+
+
+def detect_injection(text: str) -> dict:
+    """
+    Scan a string for prompt injection patterns.
+
+    Returns:
+        {
+            "detected":        bool,
+            "threat_type":     str | None,   # first match wins
+            "confidence":      int | None,   # 1–3
+            "matched_pattern": str | None,   # the matched substring
+        }
+    """
+    for threat_type, confidence, pattern in _INJECTION_PATTERNS:
+        m = pattern.search(text)
+        if m:
+            return {
+                "detected":        True,
+                "threat_type":     threat_type,
+                "confidence":      confidence,
+                "matched_pattern": m.group(0),
+            }
+    return {"detected": False, "threat_type": None, "confidence": None, "matched_pattern": None}
+
+
+def _collect_strings(value) -> list[str]:
+    """Recursively collect all string values from a JSON-decoded structure."""
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, dict):
+        out = []
+        for v in value.values():
+            out.extend(_collect_strings(v))
+        return out
+    if isinstance(value, list):
+        out = []
+        for item in value:
+            out.extend(_collect_strings(item))
+        return out
+    return []
+
+
+# ── input sanitization ────────────────────────────────────
+# Strips: null bytes (\x00), ASCII control chars (0x01–0x1F except \t \n \r),
+# DEL (0x7F), and Unicode zero-width / specials.
+
+_STRIP_PATTERN = re.compile(
+    r"[\x00\x01-\x08\x0b\x0c\x0e-\x1f\x7f]"
+    r"|\u200b|\u200c|\u200d|\u200e|\u200f"
+    r"|[\ufff0-\uffff]"
+)
+
+
+def _sanitize_str(value: str) -> tuple[str, bool]:
+    cleaned = _STRIP_PATTERN.sub("", value)
+    return cleaned, cleaned != value
+
+
+def _sanitize_value(value):
+    """Recursively sanitize strings within dicts, lists, and scalars."""
+    if isinstance(value, str):
+        return _sanitize_str(value)
+    if isinstance(value, dict):
+        result  = {}
+        changed = False
+        for k, v in value.items():
+            new_v, c = _sanitize_value(v)
+            result[k] = new_v
+            changed = changed or c
+        return result, changed
+    if isinstance(value, list):
+        result  = []
+        changed = False
+        for item in value:
+            new_item, c = _sanitize_value(item)
+            result.append(new_item)
+            changed = changed or c
+        return result, changed
+    return value, False
+
+
+# ── FastAPI middleware ─────────────────────────────────────
+
+from fastapi import Request
+from starlette.middleware.base import BaseHTTPMiddleware
+import json
+
+
+class SanitizationMiddleware(BaseHTTPMiddleware):
+    """
+    For every JSON request:
+    1. Strip control characters from all string values.
+    2. Scan all string values for prompt injection patterns.
+    3. Log both events to security_log (flag only — never block).
+    """
+
+    async def dispatch(self, request: Request, call_next):
+        content_type = request.headers.get("content-type", "")
+
+        if "application/json" in content_type:
+            try:
+                body_bytes = await request.body()
+                if body_bytes:
+                    data = json.loads(body_bytes)
+
+                    # 1. Sanitize control characters
+                    cleaned, changed = _sanitize_value(data)
+                    if changed:
+                        self._log_security(request, "control_chars_stripped", None, None)
+                        request._body = json.dumps(cleaned).encode()
+                        data = cleaned   # scan the cleaned version for injections
+
+                    # 2. Injection detection — scan every string field
+                    for text in _collect_strings(data):
+                        result = detect_injection(text)
+                        if result["detected"]:
+                            self._log_security(
+                                request,
+                                "injection_detected",
+                                result["threat_type"],
+                                result["confidence"],
+                            )
+                            break   # one log entry per request is enough
+
+            except (json.JSONDecodeError, Exception):
+                pass   # malformed JSON — FastAPI validation handles it
+
+        return await call_next(request)
+
+    def _log_security(
+        self,
+        request: Request,
+        detail: str,
+        threat_type: str | None,
+        confidence: int | None,
+    ):
+        ip = None
+        if request.client:
+            ip = request.client.host
+        forwarded = request.headers.get("X-Forwarded-For")
+        if forwarded:
+            ip = forwarded.split(",")[0].strip()
+
+        detail_str = detail
+        if threat_type:
+            detail_str += f" threat={threat_type} confidence={confidence}"
+
+        conn = get_connection()
+        try:
+            conn.execute(
+                "INSERT INTO security_log (ip_address, endpoint, detail, threat_type) "
+                "VALUES (?, ?, ?, ?)",
+                (ip, str(request.url.path), detail_str, threat_type)
+            )
+            conn.commit()
+        except sqlite3.Error as e:
+            logger.warning(f"DB error: {e}")
+        finally:
+            conn.close()

tethr_engine/auth.py

@@ -0,0 +1,180 @@
+"""
+auth.py — JWT creation/validation, password hashing, token management.
+
+Access tokens:  30-day JWT stored in httpOnly cookie.
+Refresh tokens: 7-day opaque token, SHA-256 hashed in `tokens` table.
+Passwords:      bcrypt-hashed, never logged.
+"""
+import hashlib
+import logging
+import re
+import secrets
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+import bcrypt
+from fastapi import Cookie, Depends, HTTPException, Request
+from jose import JWTError, jwt
+
+from tethr_engine.database import get_connection
+
+logger = logging.getLogger(__name__)
+
+# ── constants ─────────────────────────────────────────────
+ALGORITHM                    = "HS256"
+ACCESS_TOKEN_EXPIRE_MINUTES  = 30 * 24 * 60   # 30 days
+REFRESH_TOKEN_EXPIRE_DAYS    = 7
+
+# Lazy-loaded from config to avoid circular import at module load time
+_SECRET_KEY: Optional[str] = None
+
+
+def _get_secret() -> str:
+    global _SECRET_KEY
+    if _SECRET_KEY is None:
+        from tethr_engine.config import get_config
+        _SECRET_KEY = get_config().get("server_secret", "")
+        if not _SECRET_KEY:
+            raise RuntimeError(
+                "server_secret missing from config.yaml — "
+                "restart the server to auto-generate one"
+            )
+    return _SECRET_KEY
+
+
+# ── password utilities ────────────────────────────────────
+
+def hash_password(password: str) -> str:
+    return bcrypt.hashpw(password.encode(), bcrypt.gensalt(rounds=12)).decode()
+
+
+def verify_password(password: str, hashed: str) -> bool:
+    try:
+        return bcrypt.checkpw(password.encode(), hashed.encode())
+    except Exception as e:
+        logger.warning(f"Password verification error: {e}")
+        return False
+
+
+def validate_password_strength(password: str):
+    """Raises ValueError if password doesn't meet requirements."""
+    if len(password) < 8:
+        raise ValueError("Password must be at least 8 characters")
+    if not re.search(r"[A-Za-z]", password):
+        raise ValueError("Password must contain at least one letter")
+    if not re.search(r"\d", password):
+        raise ValueError("Password must contain at least one number")
+
+
+# ── token creation ────────────────────────────────────────
+
+def create_access_token(user_id: str) -> str:
+    expire  = datetime.now(timezone.utc) + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
+    payload = {"sub": user_id, "exp": expire, "type": "access"}
+    return jwt.encode(payload, _get_secret(), algorithm=ALGORITHM)
+
+
+def create_refresh_token(user_id: str) -> str:
+    """Creates opaque refresh token, stores SHA-256 hash in DB. Returns raw token."""
+    token      = secrets.token_urlsafe(32)
+    token_hash = hashlib.sha256(token.encode()).hexdigest()
+    expires_at = (datetime.now(timezone.utc) + timedelta(days=REFRESH_TOKEN_EXPIRE_DAYS)).isoformat()
+
+    conn = get_connection()
+    try:
+        conn.execute(
+            "INSERT INTO tokens (user_id, token_hash, expires_at) VALUES (?, ?, ?)",
+            (user_id, token_hash, expires_at)
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+    return token
+
+
+# ── token verification ────────────────────────────────────
+
+def verify_access_token(token: str) -> str:
+    """Returns user_id or raises 401."""
+    try:
+        payload = jwt.decode(token, _get_secret(), algorithms=[ALGORITHM])
+        if payload.get("type") != "access":
+            raise JWTError("wrong token type")
+        user_id = payload.get("sub")
+        if not user_id:
+            raise JWTError("missing sub")
+        return user_id
+    except JWTError:
+        raise HTTPException(status_code=401, detail="Invalid or expired token")
+
+
+def verify_refresh_token(token: str) -> str:
+    """Returns user_id or raises 401."""
+    token_hash = hashlib.sha256(token.encode()).hexdigest()
+    conn = get_connection()
+    try:
+        row = conn.execute(
+            "SELECT user_id, expires_at, revoked FROM tokens WHERE token_hash = ?",
+            (token_hash,)
+        ).fetchone()
+    finally:
+        conn.close()
+
+    if not row:
+        raise HTTPException(status_code=401, detail="Invalid refresh token")
+    if row["revoked"]:
+        raise HTTPException(status_code=401, detail="Refresh token has been revoked")
+
+    expires = datetime.fromisoformat(row["expires_at"]).replace(tzinfo=timezone.utc)
+    if datetime.now(timezone.utc) > expires:
+        raise HTTPException(status_code=401, detail="Refresh token expired")
+
+    return row["user_id"]
+
+
+def revoke_refresh_token(token: str):
+    token_hash = hashlib.sha256(token.encode()).hexdigest()
+    conn = get_connection()
+    try:
+        conn.execute("UPDATE tokens SET revoked = 1 WHERE token_hash = ?", (token_hash,))
+        conn.commit()
+    finally:
+        conn.close()
+
+
+# ── FastAPI dependency ─────────────────────────────────────
+
+def get_current_user(request: Request) -> str:
+    """
+    Dependency — accepts JWT from either:
+      1. Authorization: Bearer <token>  (desktop / device clients)
+      2. httpOnly access_token cookie   (web clients)
+    Raises 401 if missing or invalid.
+    """
+    auth_header = request.headers.get("Authorization", "")
+    if auth_header.startswith("Bearer "):
+        return verify_access_token(auth_header[7:])
+    token = request.cookies.get("access_token")
+    if not token:
+        raise HTTPException(status_code=401, detail="Not authenticated")
+    return verify_access_token(token)
+
+
+def get_current_admin(request: Request) -> str:
+    """
+    Dependency — same as get_current_user but also checks admin flag.
+    Raises 403 if user is not an admin.
+    """
+    user_id = get_current_user(request)
+    conn = get_connection()
+    try:
+        row = conn.execute(
+            "SELECT is_admin FROM users WHERE id = ?", (user_id,)
+        ).fetchone()
+    finally:
+        conn.close()
+
+    if not row or not row["is_admin"]:
+        raise HTTPException(status_code=403, detail="Admin access required")
+    return user_id

tethr_engine/cli.py

@@ -0,0 +1,78 @@
+"""cli.py — tethr command-line interface."""
+import argparse
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="tethr",
+        description="Tethr Engine — identity and memory server",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # tethr start
+    start_p = sub.add_parser("start", help="Start the tethr engine server")
+    start_p.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Bind host (default: 127.0.0.1; use 0.0.0.0 for network access)",
+    )
+    start_p.add_argument(
+        "--port", type=int, default=8001, help="Port (default: 8001)"
+    )
+    start_p.add_argument(
+        "--reload", action="store_true", help="Enable auto-reload for development"
+    )
+
+    # tethr status
+    sub.add_parser("status", help="Check server health")
+
+    # tethr version
+    sub.add_parser("version", help="Print version and exit")
+
+    args = parser.parse_args()
+
+    if args.command == "start":
+        _cmd_start(args)
+    elif args.command == "status":
+        _cmd_status()
+    elif args.command == "version":
+        _cmd_version()
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+def _cmd_start(args):
+    import uvicorn
+
+    uvicorn.run(
+        "tethr_engine.server:app",
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+    )
+
+
+def _cmd_status():
+    import requests
+
+    url = "http://127.0.0.1:8001/health"
+    try:
+        resp = requests.get(url, timeout=5)
+        resp.raise_for_status()
+        print(resp.json())
+    except requests.ConnectionError:
+        print(f"ERROR: Could not connect to {url} — is the server running?")
+        sys.exit(1)
+    except Exception as exc:
+        print(f"ERROR: {exc}")
+        sys.exit(1)
+
+
+def _cmd_version():
+    try:
+        from importlib.metadata import version
+        print(f"tethr-engine {version('tethr-engine')}")
+    except Exception:
+        print("tethr-engine 0.1.0")