memuron 0.1.1__py3-none-any.whl

memuron/security/auth.py

@@ -0,0 +1,143 @@
+"""Authentication for Memuron and mounted engine routes."""
+
+from __future__ import annotations
+
+import secrets
+
+from fastapi import HTTPException, Request, Security
+from fastapi.security import APIKeyHeader, HTTPAuthorizationCredentials, HTTPBearer
+from artha_engine.runtime.auth import AuthContext
+
+from memuron.application.config import settings
+from memuron.security.jwt_tokens import TokenError, decode_access_token
+from memuron.security.tenant import role_scopes
+
+_bearer = HTTPBearer(auto_error=False)
+_api_key_header = APIKeyHeader(name="X-Memuron-Api-Key", auto_error=False)
+
+
+def extract_bearer_token(
+    request: Request,
+    bearer: HTTPAuthorizationCredentials | None = None,
+    header_key: str | None = None,
+) -> str | None:
+    if bearer and bearer.credentials:
+        return bearer.credentials
+    auth_header = request.headers.get("authorization")
+    if auth_header and auth_header.lower().startswith("bearer "):
+        return auth_header[7:].strip()
+    if header_key:
+        return header_key
+    return request.headers.get("x-memuron-api-key")
+
+
+def verify_request_api_key(request: Request) -> bool:
+    configured = settings.api_key
+    if not configured:
+        return True
+    provided = extract_bearer_token(request)
+    if not provided:
+        return False
+    return secrets.compare_digest(provided, configured)
+
+
+def _csv_header(value: str | None) -> list[str]:
+    if not value:
+        return []
+    return [part.strip() for part in value.split(",") if part.strip()]
+
+
+def _auth_context_from_request(request: Request, *, authenticated: bool) -> AuthContext:
+    actor_id = request.headers.get("x-memuron-actor-id")
+    tenant_id = request.headers.get("x-memuron-tenant-id")
+    scopes = _csv_header(request.headers.get("x-memuron-scopes"))
+    if actor_id is None:
+        actor_id = "api_key" if authenticated else "anonymous"
+    return AuthContext(
+        actor_id=actor_id,
+        tenant_id=tenant_id,
+        scopes=scopes,
+        claims={
+            "auth_scheme": "api_key" if authenticated else "none",
+            "service": "memuron",
+        },
+    )
+
+
+def _auth_context_from_jwt(payload: dict[str, object]) -> AuthContext:
+    role = str(payload.get("role") or "")
+    return AuthContext(
+        actor_id=str(payload["sub"]),
+        tenant_id=str(payload["org_id"]) if payload.get("org_id") else None,
+        scopes=role_scopes(role),
+        claims={
+            "auth_scheme": "jwt",
+            "service": "memuron",
+            "email": str(payload.get("email") or ""),
+            "org_slug": str(payload.get("org_slug") or ""),
+            "role": role,
+        },
+    )
+
+
+def _is_public_path(path: str) -> bool:
+    normalized = path.rstrip("/")
+    if normalized.endswith("/health"):
+        return True
+    if normalized.endswith("/auth/register") or normalized.endswith("/auth/login"):
+        return True
+    return False
+
+
+def _looks_like_jwt(token: str) -> bool:
+    return token.count(".") == 2
+
+
+def require_auth_context(
+    request: Request,
+    bearer: HTTPAuthorizationCredentials | None = Security(_bearer),
+    header_key: str | None = Security(_api_key_header),
+) -> AuthContext:
+    if _is_public_path(request.url.path):
+        return AuthContext(actor_id="public", scopes=["health:read"])
+
+    token = extract_bearer_token(request, bearer, header_key)
+    if token and _looks_like_jwt(token):
+        try:
+            payload = decode_access_token(token)
+            return _auth_context_from_jwt(payload)
+        except TokenError as exc:
+            raise HTTPException(status_code=401, detail="Invalid or expired token") from exc
+
+    if settings.api_key:
+        if token and secrets.compare_digest(token, settings.api_key):
+            return _auth_context_from_request(request, authenticated=True)
+        raise HTTPException(status_code=401, detail="Invalid or missing credentials")
+
+    if settings.auth_required:
+        raise HTTPException(status_code=401, detail="Authentication required")
+
+    return _auth_context_from_request(request, authenticated=False)
+
+
+def require_api_key(
+    request: Request,
+    bearer: HTTPAuthorizationCredentials | None = Security(_bearer),
+    header_key: str | None = Security(_api_key_header),
+) -> None:
+    require_auth_context(request, bearer, header_key)
+
+
+def verify_engine_request(request: Request) -> bool:
+    if not (settings.auth_required or settings.api_key):
+        return True
+    token = extract_bearer_token(request)
+    if token and _looks_like_jwt(token):
+        try:
+            decode_access_token(token)
+            return True
+        except TokenError:
+            return False
+    if settings.api_key:
+        return verify_request_api_key(request)
+    return not settings.auth_required

memuron/security/auth_provider.py

@@ -0,0 +1,119 @@
+"""Memuron authentication providers (Clerk + API key for agents)."""
+
+from __future__ import annotations
+
+import os
+import secrets
+from dataclasses import dataclass
+from typing import Any
+
+from artha_engine.app.auth import (
+    AnonymousAuthProvider,
+    AuthenticationError,
+    AuthConfigurationError,
+    AuthProvider,
+    ClerkAuthProvider,
+)
+from artha_engine.app.managed_api_keys import (
+    CompositeAuthProvider,
+    ManagedApiKeyAuthProvider,
+)
+from artha_engine.runtime.auth import AuthContext
+from artha_engine.store.api_key_store import ApiKeyStore
+
+from memuron.security.clerk_scopes import enrich_auth_context
+from memuron.application.config import settings
+
+
+def _bearer_token(request: Any) -> str | None:
+    header = request.headers.get("authorization")
+    if header and header.lower().startswith("bearer "):
+        return header[7:].strip()
+    return None
+
+
+def _csv_header(value: str | None) -> list[str]:
+    return [part.strip() for part in (value or "").split(",") if part.strip()]
+
+
+@dataclass(frozen=True)
+class MemuronApiKeyAuthProvider:
+    """API key auth with Memuron and Artha header conventions."""
+
+    env_var: str = "MEMURON_API_KEY"
+    actor_id: str = "api_key"
+    scopes: tuple[str, ...] = ("*",)
+
+    async def authenticate_http(self, request: Any) -> AuthContext:
+        expected = os.environ.get(self.env_var, "").strip() or settings.api_key
+        if not expected:
+            if not settings.auth_required:
+                return AuthContext(actor_id="anonymous", scopes=["*"])
+            raise AuthConfigurationError(
+                f"Set {self.env_var} before serving protected Memuron actions"
+            )
+        provided = (
+            _bearer_token(request)
+            or request.headers.get("x-memuron-api-key")
+            or request.headers.get("x-artha-api-key")
+        )
+        if not provided or not secrets.compare_digest(provided, expected):
+            raise AuthenticationError("Invalid or missing API key")
+        actor_id = (
+            request.headers.get("x-memuron-actor-id")
+            or request.headers.get("x-artha-actor-id")
+            or self.actor_id
+        )
+        tenant_id = request.headers.get("x-memuron-tenant-id") or request.headers.get(
+            "x-artha-tenant-id"
+        )
+        header_scopes = _csv_header(request.headers.get("x-memuron-scopes")) or _csv_header(
+            request.headers.get("x-artha-scopes")
+        )
+        return AuthContext(
+            actor_id=actor_id,
+            tenant_id=tenant_id,
+            scopes=header_scopes or list(self.scopes),
+            claims={"auth_scheme": "api_key", "service": "memuron"},
+        )
+
+
+@dataclass(frozen=True)
+class MemuronClerkAuthProvider:
+    inner: ClerkAuthProvider
+
+    async def authenticate_http(self, request: Any) -> AuthContext:
+        auth = await self.inner.authenticate_http(request)
+        return enrich_auth_context(auth)
+
+
+def create_memuron_auth_provider(
+    *,
+    api_key_store: ApiKeyStore | None = None,
+) -> AuthProvider:
+    provider = os.environ.get("ARTHA_AUTH_PROVIDER", "clerk_api_key").strip().lower()
+    if provider in {"none", "anonymous"} or not settings.auth_required:
+        return AnonymousAuthProvider()
+    if provider in {"api-key", "api_key"}:
+        if api_key_store is not None:
+            return ManagedApiKeyAuthProvider(
+                store=api_key_store,
+                bootstrap_env_var="MEMURON_API_KEY",
+                alternate_header_names=("x-memuron-api-key",),
+            )
+        return MemuronApiKeyAuthProvider()
+    clerk = MemuronClerkAuthProvider(ClerkAuthProvider())
+    if provider == "clerk":
+        return clerk
+    if provider in {"composite", "clerk_api_key"}:
+        fallback: AuthProvider
+        if api_key_store is not None:
+            fallback = ManagedApiKeyAuthProvider(
+                store=api_key_store,
+                bootstrap_env_var="MEMURON_API_KEY",
+                alternate_header_names=("x-memuron-api-key",),
+            )
+        else:
+            fallback = MemuronApiKeyAuthProvider()
+        return CompositeAuthProvider(primary=clerk, fallback=fallback)
+    raise AuthConfigurationError(f"Unknown ARTHA_AUTH_PROVIDER: {provider}")

memuron/security/authorization.py

@@ -0,0 +1,53 @@
+"""Memuron authorization policy for Artha actions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from artha_engine.app.actions import ActionDefinition
+from artha_engine.app.authorization import AuthorizationDenied, ScopeAuthorizationPolicy
+from artha_engine.app.context import ActionContext
+
+ORG_SCOPED_PREFIXES = ("space.", "memory.")
+
+
+@dataclass(frozen=True)
+class MemuronAuthorizationPolicy:
+    """Scope checks plus org context for tenant-scoped actions."""
+
+    scopes: ScopeAuthorizationPolicy | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "scopes", self.scopes or ScopeAuthorizationPolicy())
+
+    def authorize(self, action: ActionDefinition, context: ActionContext) -> None:
+        self.scopes.authorize(action, context)
+        if action.public:
+            return
+        if not _requires_org_context(action.name):
+            return
+        if context.auth.tenant_id:
+            return
+        raise AuthorizationDenied(
+            f"Action {action.name} requires an active organization (Clerk org_id)"
+        )
+
+
+def _requires_org_context(action_name: str) -> bool:
+    if action_name.startswith(ORG_SCOPED_PREFIXES):
+        return True
+    if action_name in {
+        "node.create",
+        "node.link",
+        "collection.create",
+        "collection.place",
+        "collection.members",
+        "document.ingest",
+        "graph.export",
+        "graph.hubs",
+        "graph.neighborhood",
+        "graph.path",
+        "graph.traverse",
+    }:
+        return True
+    return False

memuron/security/clerk_scopes.py

@@ -0,0 +1,94 @@
+"""Map Clerk session claims to Memuron action scopes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from artha_engine.runtime.auth import AuthContext
+
+MEMURON_OWNER_SCOPES = [
+    "memory:read",
+    "memory:write",
+    "memory:delete",
+    "space:admin",
+    "org:admin",
+    "artha:admin",
+    "api_key:manage",
+]
+
+MEMURON_MEMBER_SCOPES = [
+    "memory:read",
+    "memory:write",
+    "memory:delete",
+]
+
+
+def clerk_org_claims(claims: dict[str, Any]) -> tuple[str | None, str | None]:
+    """Extract org id and role from Clerk JWT v1 or v2 session tokens."""
+    org_object = claims.get("o")
+    if claims.get("v") == 2 and isinstance(org_object, dict):
+        org_id = org_object.get("id")
+        raw_role = org_object.get("rol")
+        if raw_role:
+            role_text = str(raw_role).lower()
+            org_role = role_text if role_text.startswith("org:") else f"org:{role_text}"
+        else:
+            org_role = None
+        return (
+            str(org_id) if org_id is not None else None,
+            org_role,
+        )
+
+    org_id = claims.get("org_id")
+    raw_role = claims.get("org_role") or claims.get("role")
+    org_role = str(raw_role).lower() if raw_role else None
+    return (
+        str(org_id) if org_id is not None else None,
+        org_role,
+    )
+
+
+def scopes_from_clerk_claims(claims: dict[str, Any]) -> list[str]:
+    _, org_role = clerk_org_claims(claims)
+    if not org_role:
+        org_role = str(claims.get("org_role") or claims.get("role") or "").lower()
+    if org_role in {"org:admin", "admin"}:
+        return list(MEMURON_OWNER_SCOPES)
+    if org_role in {"org:member", "basic_member", "member"}:
+        return list(MEMURON_MEMBER_SCOPES)
+    for claim_name in ("permissions", "org_permissions", "scope", "scp"):
+        value = claims.get(claim_name)
+        if isinstance(value, str):
+            parts = [part.strip() for part in value.replace(",", " ").split() if part.strip()]
+            if parts:
+                return parts
+        if isinstance(value, list) and value:
+            return [str(item) for item in value]
+    org_object = claims.get("o")
+    if isinstance(org_object, dict):
+        perms = org_object.get("per")
+        if isinstance(perms, str):
+            parts = [part.strip() for part in perms.replace(",", " ").split() if part.strip()]
+            if parts:
+                return parts
+    return list(MEMURON_MEMBER_SCOPES)
+
+
+def enrich_auth_context(auth: AuthContext) -> AuthContext:
+    if auth.claims.get("auth_scheme") == "api_key":
+        return auth
+    scopes = scopes_from_clerk_claims(auth.claims)
+    if "*" in auth.scopes:
+        return auth
+    merged = list(auth.scopes)
+    for scope in scopes:
+        if scope not in merged:
+            merged.append(scope)
+    org_id, _ = clerk_org_claims(auth.claims)
+    tenant_id = auth.tenant_id or org_id
+    return AuthContext(
+        actor_id=auth.actor_id,
+        tenant_id=tenant_id,
+        scopes=merged,
+        claims=auth.claims,
+    )

memuron/security/clerk_webhooks.py

@@ -0,0 +1,61 @@
+"""Clerk webhook handlers for org/space provisioning."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+
+from memuron.persistence.identity_store import IdentityStore
+
+router = APIRouter(tags=["webhooks"])
+
+
+def _verify_clerk_webhook(request: Request, body: bytes) -> dict[str, Any]:
+    secret = os.environ.get("CLERK_WEBHOOK_SECRET", "").strip()
+    if not secret:
+        raise HTTPException(status_code=503, detail="CLERK_WEBHOOK_SECRET is not configured")
+    try:
+        from svix.webhooks import Webhook
+    except ImportError as exc:
+        raise HTTPException(
+            status_code=503,
+            detail="Install svix to verify Clerk webhooks",
+        ) from exc
+    headers = {
+        "svix-id": request.headers.get("svix-id", ""),
+        "svix-timestamp": request.headers.get("svix-timestamp", ""),
+        "svix-signature": request.headers.get("svix-signature", ""),
+    }
+    try:
+        payload = Webhook(secret).verify(body.decode("utf-8"), headers)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail="Invalid Clerk webhook signature") from exc
+    if isinstance(payload, str):
+        return json.loads(payload)
+    return payload
+
+
+@router.post("/memuron/webhooks/clerk")
+async def clerk_webhook(request: Request) -> dict[str, str]:
+    body = await request.body()
+    event = _verify_clerk_webhook(request, body)
+    event_type = str(event.get("type") or "")
+    data = event.get("data") or {}
+    identity: IdentityStore | None = getattr(request.app.state, "identity_store", None)
+    if identity is None:
+        raise HTTPException(status_code=503, detail="Identity store unavailable")
+
+    if event_type == "organization.created":
+        org_id = str(data.get("id") or "")
+        if org_id:
+            identity.ensure_org_spaces(org_id, user_id="system")
+    elif event_type in {"organizationMembership.created", "organizationMembership.updated"}:
+        org_id = str(data.get("organization_id") or data.get("organization", {}).get("id") or "")
+        user_id = str(data.get("public_user_data", {}).get("user_id") or data.get("user_id") or "")
+        if org_id and user_id:
+            identity.ensure_org_spaces(org_id, user_id)
+
+    return {"status": "ok"}

memuron/security/jwt_tokens.py

@@ -0,0 +1,53 @@
+"""JWT access tokens for Memuron users."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import jwt
+
+from memuron.application.config import settings
+
+
+class TokenError(Exception):
+    pass
+
+
+def create_access_token(
+    *,
+    user_id: str,
+    email: str,
+    org_id: str | None,
+    org_slug: str | None,
+    role: str | None,
+) -> str:
+    now = datetime.now(UTC)
+    payload = {
+        "sub": user_id,
+        "email": email,
+        "org_id": org_id,
+        "org_slug": org_slug,
+        "role": role,
+        "iat": int(now.timestamp()),
+        "exp": int((now + timedelta(hours=settings.jwt_expire_hours)).timestamp()),
+        "iss": settings.jwt_issuer,
+        "typ": "access",
+    }
+    return jwt.encode(payload, settings.jwt_secret, algorithm=settings.jwt_algorithm)
+
+
+def decode_access_token(token: str) -> dict[str, Any]:
+    try:
+        payload = jwt.decode(
+            token,
+            settings.jwt_secret,
+            algorithms=[settings.jwt_algorithm],
+            issuer=settings.jwt_issuer,
+            options={"require": ["exp", "sub", "iat", "iss"]},
+        )
+    except jwt.PyJWTError as exc:
+        raise TokenError(str(exc)) from exc
+    if payload.get("typ") != "access":
+        raise TokenError("invalid token type")
+    return payload

memuron/security/passwords.py

@@ -0,0 +1,38 @@
+"""Password hashing helpers (stdlib only)."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+
+_PBKDF2_ITERATIONS = 600_000
+
+
+def hash_password(password: str) -> str:
+    if len(password) < 8:
+        raise ValueError("password must be at least 8 characters")
+    salt = secrets.token_hex(16)
+    digest = hashlib.pbkdf2_hmac(
+        "sha256",
+        password.encode("utf-8"),
+        salt.encode("utf-8"),
+        _PBKDF2_ITERATIONS,
+    )
+    return f"pbkdf2_sha256${_PBKDF2_ITERATIONS}${salt}${digest.hex()}"
+
+
+def verify_password(password: str, stored: str) -> bool:
+    try:
+        scheme, iterations, salt, digest_hex = stored.split("$", 3)
+    except ValueError:
+        return False
+    if scheme != "pbkdf2_sha256":
+        return False
+    computed = hashlib.pbkdf2_hmac(
+        "sha256",
+        password.encode("utf-8"),
+        salt.encode("utf-8"),
+        int(iterations),
+    )
+    return hmac.compare_digest(computed.hex(), digest_hex)

memuron/security/tenant.py

@@ -0,0 +1,58 @@
+"""Org tenancy and space scope helpers."""
+
+from __future__ import annotations
+
+
+def org_scope_token(org_id: str) -> str:
+    return f"org:{org_id}"
+
+
+def normalize_tenant_scope(scope: list[str] | None, org_id: str | None) -> list[str]:
+    """Drop foreign org:* tokens and ensure the caller's org token is present."""
+    if not org_id:
+        return list(scope or [])
+    token = org_scope_token(org_id)
+    cleaned = [item for item in (scope or []) if not str(item).startswith("org:")]
+    return [token, *cleaned]
+
+
+def merge_org_scope(scope: list[str] | None, org_id: str | None) -> list[str]:
+    return normalize_tenant_scope(scope, org_id)
+
+
+def merge_space_scope(
+    scope: list[str] | None,
+    *,
+    org_id: str | None,
+    space_token: str | None,
+) -> list[str]:
+    merged = merge_org_scope(scope, org_id)
+    if not space_token:
+        return merged
+    if space_token not in merged:
+        insert_at = 1 if org_id and merged else 0
+        merged.insert(insert_at, space_token)
+    return merged
+
+
+def ensure_space_token(scope: list[str], space_token: str) -> list[str]:
+    if space_token in scope:
+        return scope
+    return [space_token, *scope]
+
+
+def tenant_scope_query(org_id: str | None, scope: str | None) -> str | None:
+    if not org_id:
+        return scope
+    org_pattern = org_scope_token(org_id)
+    if scope:
+        return f"{org_pattern},{scope}"
+    return org_pattern
+
+
+def role_scopes(role: str | None) -> list[str]:
+    if role == "owner":
+        return ["memory:read", "memory:write", "memory:delete", "org:admin"]
+    if role == "member":
+        return ["memory:read", "memory:write", "memory:delete"]
+    return []

memuron/spaces/__init__.py

@@ -0,0 +1 @@
+"""Space token model and space-scoping services."""

memuron/spaces/model.py

@@ -0,0 +1,35 @@
+"""Space token helpers — compile names to scope tokens."""
+
+from __future__ import annotations
+
+import re
+
+SPACE_TOKEN_PREFIX = "space."
+
+
+def slugify_space(value: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+    return slug or "space"
+
+
+def compile_space_token(slug: str) -> str:
+    normalized = slug.strip().lower()
+    if normalized.startswith(SPACE_TOKEN_PREFIX):
+        return normalized
+    return f"{SPACE_TOKEN_PREFIX}{normalized}"
+
+
+def default_personal_space(*, org_id: str) -> dict[str, str]:
+    slug = "personal"
+    return {
+        "slug": slug,
+        "name": "Personal",
+        "token": compile_space_token(slug),
+        "description": "General personal notes and preferences",
+        "guardian_prompt": (
+            "General personal notes, preferences, and life context. "
+            "Exclude work-specific project details unless explicitly personal."
+        ),
+        "is_default": "true",
+        "org_id": org_id,
+    }