contextsynapse 1.0.0__py3-none-any.whl

contextsynapse/security/rls.py

@@ -0,0 +1,205 @@
+"""RLS — Row-Level Security enforcement.
+
+Filters query results based on user's scoped_ids.
+Users only see resources they're authorized for.
+
+Global access roles (admin, compliance_officer) bypass RLS.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Set
+
+from fastapi import Depends
+
+logger = logging.getLogger(__name__)
+
+
+# Roles that bypass all row-level filtering
+GLOBAL_ACCESS_ROLES: Set[str] = {"admin", "compliance_officer"}
+
+# Roles that can see all clients (in addition to global)
+_CLIENT_GLOBAL_ROLES: Set[str] = {"admin", "compliance_officer", "operations"}
+
+
+class RLSFilter:
+    """Row-level security filter scoped to a single authenticated user.
+
+    Instantiate per-request from the JWT claims and use the filter_*
+    methods to strip unauthorised rows before returning API responses.
+    """
+
+    def __init__(
+        self,
+        user_id: str,
+        role: str,
+        scoped_ids: Optional[List[str]],
+        tenant_id: str,
+    ):
+        self.user_id = user_id
+        self.role = role
+        self.scoped_ids: List[str] = scoped_ids or []
+        self.tenant_id = tenant_id
+        self._scoped_set: Set[str] = set(self.scoped_ids)
+        self._is_global = role in GLOBAL_ACCESS_ROLES
+
+    # ------------------------------------------------------------------
+    # Generic helper
+    # ------------------------------------------------------------------
+
+    def apply_filter(
+        self,
+        items: List[dict],
+        id_field: str,
+        allowed_ids: Optional[Set[str]] = None,
+    ) -> List[dict]:
+        """Filter a list of dicts, keeping only those whose *id_field*
+        value is in *allowed_ids*.
+
+        If *allowed_ids* is None the user's scoped_ids are used.
+        """
+        ids = allowed_ids if allowed_ids is not None else self._scoped_set
+        return [item for item in items if item.get(id_field) in ids]
+
+    # ------------------------------------------------------------------
+    # Tenant guard (call first on every response)
+    # ------------------------------------------------------------------
+
+    def check_tenant(self, resource_tenant_id: str) -> bool:
+        """Ensure *resource_tenant_id* matches the authenticated user's tenant."""
+        return resource_tenant_id == self.tenant_id
+
+    # ------------------------------------------------------------------
+    # Resource-specific filters
+    # ------------------------------------------------------------------
+
+    def filter_portfolios(self, portfolios: List[dict]) -> List[dict]:
+        """Return only portfolios the user is authorised to see."""
+        if self._is_global:
+            return portfolios
+        return self.apply_filter(portfolios, "portfolio_id")
+
+    def filter_schemes(self, schemes: List[dict]) -> List[dict]:
+        """Return only MF schemes the user is authorised to see."""
+        if self._is_global:
+            return schemes
+        return self.apply_filter(schemes, "scheme_id")
+
+    def filter_trades(self, trades: List[dict]) -> List[dict]:
+        """Return only trades belonging to the user's authorised portfolios."""
+        if self._is_global:
+            return trades
+        return self.apply_filter(trades, "portfolio_id")
+
+    def filter_clients(self, clients: List[dict]) -> List[dict]:
+        """Return only clients the user is authorised to see.
+
+        Operations and admin/compliance roles can see all clients.
+        Other roles are filtered by client_id in scoped_ids.
+        """
+        if self.role in _CLIENT_GLOBAL_ROLES:
+            return clients
+        return self.apply_filter(clients, "client_id")
+
+    def filter_folios(self, folios: List[dict]) -> List[dict]:
+        """Return only MF folios for schemes the user can access."""
+        if self._is_global:
+            return folios
+        return self.apply_filter(folios, "scheme_id")
+
+    def filter_invoices(self, invoices: List[dict]) -> List[dict]:
+        """Return invoices matching the user's portfolio_id or client_id scope."""
+        if self._is_global:
+            return invoices
+        return [
+            inv for inv in invoices
+            if inv.get("portfolio_id") in self._scoped_set
+            or inv.get("client_id") in self._scoped_set
+        ]
+
+    def filter_settlements(self, settlements: List[dict]) -> List[dict]:
+        """Return settlements whose trade's portfolio is in scope."""
+        if self._is_global:
+            return settlements
+        return self.apply_filter(settlements, "portfolio_id")
+
+    def filter_notifications(self, notifications: List[dict]) -> List[dict]:
+        """Return only notifications addressed to the current user.
+
+        Admins can see all notifications.
+        """
+        if self.role == "admin":
+            return notifications
+        return [n for n in notifications if n.get("recipient_id") == self.user_id]
+
+    # ------------------------------------------------------------------
+    # Single-resource access check
+    # ------------------------------------------------------------------
+
+    def can_access(self, resource_type: str, resource_id: str) -> bool:
+        """Check whether the user can access a specific resource.
+
+        Global-access roles always return True.
+        """
+        if self._is_global:
+            return True
+        return resource_id in self._scoped_set
+
+
+# ======================================================================
+# FastAPI dependency
+# ======================================================================
+
+def get_rls_filter(request=None, user=None) -> RLSFilter:
+    """Build an RLSFilter from a JWTIdentity.
+
+    Typical usage as a FastAPI dependency::
+
+        from contextsynapse.context.acl import JWTIdentity
+        from contextsynapse.security.rls import get_rls_filter, RLSFilter
+
+        @router.get("/portfolios")
+        async def list_portfolios(
+            rls: RLSFilter = Depends(get_rls_filter),
+        ):
+            all_portfolios = fetch_all(...)
+            return rls.filter_portfolios(all_portfolios)
+
+    To wire this up, register a concrete dependency in your app that
+    resolves the JWTIdentity first::
+
+        from contextsynapse.security.jwt_identity import extract_identity_from_token
+
+        async def _resolve_identity(request: Request) -> JWTIdentity:
+            token = request.headers.get("Authorization", "").removeprefix("Bearer ")
+            identity = extract_identity_from_token(token)
+            if identity is None:
+                raise HTTPException(401, "Invalid token")
+            return identity
+
+        def get_rls(identity: JWTIdentity = Depends(_resolve_identity)) -> RLSFilter:
+            scoped = identity.portfolio_ids or identity.client_ids or []
+            return RLSFilter(
+                user_id=identity.sub,
+                role=identity.role.value,
+                scoped_ids=scoped,
+                tenant_id=identity.tenant,
+            )
+    """
+    # This function serves as a template.  Callers should override it
+    # with a concrete Depends() chain that extracts JWTIdentity from
+    # the request.  The default implementation is a no-op for import
+    # compatibility.
+    if user is not None:
+        # user is expected to be a JWTIdentity-like object
+        scoped = getattr(user, "portfolio_ids", None) or getattr(user, "scheme_ids", None) or []
+        return RLSFilter(
+            user_id=getattr(user, "sub", ""),
+            role=getattr(user, "role", "").value if hasattr(getattr(user, "role", ""), "value") else str(getattr(user, "role", "")),
+            scoped_ids=list(scoped),
+            tenant_id=getattr(user, "tenant", ""),
+        )
+    raise ValueError(
+        "get_rls_filter requires a JWTIdentity user. "
+        "Wire it as a FastAPI Depends() with your auth dependency."
+    )

contextsynapse/security/sanitize.py

@@ -0,0 +1,233 @@
+"""
+AIQL Input Sanitization
+========================
+Prevents SQL/AIQL injection by sanitizing user-provided identifiers and values
+before they are interpolated into AIQL query strings.
+
+Usage::
+
+    from contextsynapse.security.sanitize import sanitize_aiql_identifier, sanitize_aiql_value
+
+    safe_label = sanitize_aiql_identifier(user_label)
+    safe_value = sanitize_aiql_value(user_value)
+    query = f'SELECT * FROM {safe_label} WHERE name = "{safe_value}"'
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+# AIQL keywords that must never appear in user-provided identifiers
+_AIQL_KEYWORDS = frozenset({
+    "select", "from", "where", "create", "delete", "update", "drop",
+    "insert", "node", "edge", "set", "match", "find", "show", "use",
+    "graph", "explain", "load", "extract", "chunk", "embed", "index",
+    "grant", "revoke", "union", "and", "or", "not", "in", "like",
+    "between", "exists", "null", "true", "false",
+})
+
+# Pattern: only alphanumeric, underscore, hyphen allowed in identifiers
+_SAFE_IDENTIFIER = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_-]*$")
+
+# Pattern: namespace names — no colons, wildcards, or special Redis chars
+_SAFE_NAMESPACE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_-]*$")
+
+# Pattern for each segment within a hierarchical path
+_SAFE_SEGMENT = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_-]*$")
+
+# Reserved namespace names that cannot be created by users
+_RESERVED_NAMESPACES = frozenset({
+    "lru", "names", "deleted", "sync",
+})
+
+# System-internal namespaces — bypass validation entirely
+_SYSTEM_NAMESPACES = frozenset({
+    "default", "__intelligence_config__",
+})
+
+# Valid top-level scopes for hierarchical context paths
+VALID_SCOPES = frozenset({"market", "portfolio", "client", "frozen"})
+
+
+def parse_context_path(path: str) -> tuple:
+    """Parse a context path into (scope, segments).
+
+    Flat paths (no colon) default to 'market' scope.
+    Hierarchical paths split on ':' — first segment is the scope.
+
+    Args:
+        path: Context path like 'tcs' or 'market:tcs' or 'portfolio:p001:holdings'
+
+    Returns:
+        Tuple of (scope, [remaining_segments])
+    """
+    if ":" not in path:
+        return ("market", [path])
+
+    parts = path.split(":")
+    scope = parts[0]
+    segments = parts[1:]
+    return (scope, segments)
+
+
+def validate_namespace(name: str) -> str:
+    """Validate a context namespace name for safe use in Redis keys.
+
+    Accepts both flat names ('tcs') and hierarchical paths ('market:tcs',
+    'portfolio:p001:holdings'). Flat names are validated as single segments.
+    Hierarchical paths are validated segment-by-segment with scope checking.
+
+    Args:
+        name: Namespace name or hierarchical path to validate.
+
+    Returns:
+        The validated name (unchanged).
+
+    Raises:
+        ValueError: If the name is invalid, reserved, or too long.
+    """
+    if not name or not isinstance(name, str):
+        raise ValueError("Namespace must be a non-empty string")
+
+    name = name.strip()
+
+    # System-internal namespaces bypass all validation
+    if name in _SYSTEM_NAMESPACES:
+        return name
+
+    if ":" in name:
+        # Hierarchical path: scope:segment[:segment...]
+        parts = name.split(":")
+        scope = parts[0]
+        segments = parts[1:]
+
+        if scope not in VALID_SCOPES:
+            raise ValueError(
+                f"Invalid scope: {scope!r} — must be one of {sorted(VALID_SCOPES)}"
+            )
+
+        if len(segments) > 3:
+            raise ValueError(
+                f"Namespace path too deep: {len(segments) + 1} segments (max 4)"
+            )
+
+        for seg in segments:
+            if not seg:
+                raise ValueError("Empty segment in namespace path")
+            if not _SAFE_SEGMENT.match(seg):
+                raise ValueError(
+                    f"Invalid segment: {seg!r} — only letters, digits, underscores, "
+                    f"and hyphens allowed"
+                )
+            if len(seg) > 128:
+                raise ValueError(f"Segment too long: {len(seg)} chars (max 128)")
+
+        return name
+    else:
+        # Flat name (backward compat)
+        if not _SAFE_NAMESPACE.match(name):
+            raise ValueError(
+                f"Invalid namespace: {name!r} — only letters, digits, underscores, "
+                f"and hyphens allowed (no colons, wildcards, or spaces)"
+            )
+
+        if len(name) > 128:
+            raise ValueError(f"Namespace too long: {len(name)} chars (max 128)")
+
+        if name.lower() in _RESERVED_NAMESPACES:
+            raise ValueError(f"Reserved namespace name: {name!r}")
+
+        return name
+
+
+def sanitize_aiql_identifier(name: str) -> str:
+    """Sanitize a label or property name for use in AIQL queries.
+
+    Allows only alphanumeric characters, underscores, and hyphens.
+    Rejects AIQL keywords to prevent query manipulation.
+
+    Args:
+        name: User-provided label or property name.
+
+    Returns:
+        Sanitized identifier string.
+
+    Raises:
+        ValueError: If the identifier is invalid or contains AIQL keywords.
+    """
+    if not name or not isinstance(name, str):
+        raise ValueError("Identifier must be a non-empty string")
+
+    name = name.strip()
+
+    if not _SAFE_IDENTIFIER.match(name):
+        raise ValueError(
+            f"Invalid identifier: {name!r} — only letters, digits, underscores, and hyphens allowed"
+        )
+
+    if name.lower() in _AIQL_KEYWORDS:
+        raise ValueError(f"Reserved AIQL keyword: {name!r}")
+
+    if len(name) > 128:
+        raise ValueError(f"Identifier too long: {len(name)} chars (max 128)")
+
+    return name
+
+
+def sanitize_aiql_value(value: Any) -> str:
+    """Sanitize a value for use in AIQL string literals.
+
+    Escapes double quotes, backslashes, and strips dangerous characters
+    that could break out of a quoted string context.
+
+    Args:
+        value: User-provided value (will be converted to string).
+
+    Returns:
+        Escaped string safe for use inside double-quoted AIQL literals.
+    """
+    if value is None:
+        return ""
+
+    s = str(value)
+
+    # Strip null bytes
+    s = s.replace("\x00", "")
+
+    # Escape backslashes first, then double quotes
+    s = s.replace("\\", "\\\\")
+    s = s.replace('"', '\\"')
+
+    # Strip semicolons — prevent statement chaining
+    s = s.replace(";", "")
+
+    # Limit length to prevent abuse
+    if len(s) > 4096:
+        s = s[:4096]
+
+    return s
+
+
+def build_safe_where_clause(where_dict: dict) -> str:
+    """Build a safe AIQL WHERE clause from a user-provided dict.
+
+    Each key is sanitized as an identifier, each value as a string literal.
+
+    Args:
+        where_dict: Dict of {property_name: value} filters.
+
+    Returns:
+        AIQL WHERE clause string, e.g. ``'WHERE name = "Alice" AND age = "30"'``
+        Returns empty string if where_dict is empty or None.
+    """
+    if not where_dict:
+        return ""
+
+    conditions = []
+    for k, v in where_dict.items():
+        safe_key = sanitize_aiql_identifier(k)
+        safe_val = sanitize_aiql_value(v)
+        conditions.append(f'{safe_key} = "{safe_val}"')
+
+    return " WHERE " + " AND ".join(conditions)

contextsynapse/security/scoped_encryption.py

@@ -0,0 +1,131 @@
+"""Scoped Encryption — transparent per-scope encryption for context data.
+
+Market data is plaintext (public). Portfolio, client, and frozen data are
+encrypted with Fernet (AES-128-CBC). Client data uses per-client derived keys.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import logging
+import os
+from typing import Any, Dict
+
+from contextsynapse.security.sanitize import parse_context_path
+
+logger = logging.getLogger(__name__)
+
+# Scopes that require encryption
+_ENCRYPTED_SCOPES = {"portfolio", "client", "frozen"}
+
+try:
+    from cryptography.fernet import Fernet
+    _FERNET_AVAILABLE = True
+except ImportError:
+    _FERNET_AVAILABLE = False
+    logger.warning("cryptography package not installed — scoped encryption disabled")
+
+
+def derive_client_key(tenant_key: bytes, client_id: str) -> bytes:
+    """Derive a per-client Fernet key from the tenant master key.
+
+    Args:
+        tenant_key: Raw bytes of the tenant master key.
+        client_id: Unique client identifier used as PBKDF2 salt.
+
+    Returns:
+        URL-safe base64-encoded 32-byte key suitable for Fernet.
+    """
+    derived = hashlib.pbkdf2_hmac("sha256", tenant_key, client_id.encode(), 100_000)
+    return base64.urlsafe_b64encode(derived[:32])
+
+
+class ScopedEncryptor:
+    """Transparent encryption based on context scope.
+
+    - ``market`` scope: plaintext JSON (no encryption — public data)
+    - ``portfolio`` scope: Fernet-encrypted with tenant key
+    - ``client`` scope: Fernet-encrypted with per-client derived key
+    - ``frozen`` scope: Fernet-encrypted with tenant key
+
+    Usage::
+
+        enc = ScopedEncryptor()
+        raw = enc.encrypt("portfolio:p001:holdings", {"holdings": [...]})
+        data = enc.decrypt("portfolio:p001:holdings", raw)
+    """
+
+    def __init__(self, tenant_key: str = None):
+        self._tenant_key = (
+            tenant_key or os.environ.get("CONTEXTSYNAPSE_TENANT_KEY") or os.environ.get("AICONTEXTDB_TENANT_KEY", "")
+        ).encode()
+
+        if self._tenant_key and _FERNET_AVAILABLE:
+            # Derive a Fernet-compatible 32-byte key from the tenant key string
+            dk = hashlib.pbkdf2_hmac(
+                "sha256", self._tenant_key, b"contextcore_scope", 100_000
+            )
+            self._tenant_fernet_key = base64.urlsafe_b64encode(dk[:32])
+        else:
+            self._tenant_fernet_key = None
+
+    def _fernet_for(self, context_path: str) -> "Fernet":
+        """Return the correct Fernet instance for the given context path.
+
+        Client paths use a per-client derived key; all other encrypted scopes
+        use the shared tenant key.
+        """
+        scope, parts = parse_context_path(context_path)
+
+        if scope == "client" and parts:
+            client_id = parts[0]
+            key = derive_client_key(self._tenant_key, client_id)
+        else:
+            key = self._tenant_fernet_key
+
+        return Fernet(key)
+
+    def encrypt(self, context_path: str, data: Dict[str, Any]) -> bytes:
+        """Encrypt context data based on scope.
+
+        Market data is returned as plain JSON bytes. All other recognised
+        scopes (portfolio, client, frozen) are Fernet-encrypted.
+
+        Args:
+            context_path: Scoped path like ``"portfolio:p001:holdings"``.
+            data: JSON-serialisable dict to store.
+
+        Returns:
+            Encrypted bytes (Fernet token) or plain JSON bytes for market data.
+        """
+        scope, _ = parse_context_path(context_path)
+        serialized = json.dumps(data, default=str).encode("utf-8")
+
+        if scope not in _ENCRYPTED_SCOPES or not _FERNET_AVAILABLE:
+            return serialized
+
+        f = self._fernet_for(context_path)
+        return f.encrypt(serialized)
+
+    def decrypt(self, context_path: str, raw: bytes) -> Dict[str, Any]:
+        """Decrypt context data based on scope.
+
+        Market data is decoded directly from JSON. Encrypted scopes are
+        decrypted with the appropriate Fernet key before JSON parsing.
+
+        Args:
+            context_path: Scoped path matching the one used during encryption.
+            raw: Bytes returned by :meth:`encrypt`.
+
+        Returns:
+            Original data dict.
+        """
+        scope, _ = parse_context_path(context_path)
+
+        if scope not in _ENCRYPTED_SCOPES or not _FERNET_AVAILABLE:
+            return json.loads(raw)
+
+        f = self._fernet_for(context_path)
+        decrypted = f.decrypt(raw)
+        return json.loads(decrypted)