analygo-foundation 1.0.0__tar.gz

analygo_foundation-1.0.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: analygo-foundation
+Version: 1.0.0
+Summary: Foundation runtime — shared identity, org resolution, RBAC, and observability for the Analygo ecosystem
+Author-email: Analygo <engineering@analygo.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pyjwt[crypto]>=2.8.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Provides-Extra: observability
+Requires-Dist: sentry-sdk>=2.0.0; extra == "observability"
+Requires-Dist: opentelemetry-api>=1.20.0; extra == "observability"
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "observability"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0; extra == "observability"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == "observability"
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.41b0; extra == "observability"
+Requires-Dist: opentelemetry-instrumentation-redis>=0.41b0; extra == "observability"
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.41b0; extra == "observability"
+Requires-Dist: structlog>=24.0.0; extra == "observability"

analygo_foundation-1.0.0/README.md

@@ -0,0 +1,5 @@
+# analygo-foundation (Python)
+
+Foundation runtime — shared identity resolution, org resolution, RBAC, observability, and onboarding state management.
+
+Consumed as `analygo-foundation` from PyPI.

analygo_foundation-1.0.0/analygo_foundation/__init__.py

@@ -0,0 +1,117 @@
+"""analygo-foundation: Shared identity resolution, authority services, observability, and onboarding state."""
+
+from analygo_foundation.contracts import (
+    EntitlementGrant,
+    Organization,
+    Property,
+    Role,
+    Seat,
+    SeatKind,
+    Session,
+    SubscriptionGuard,
+    Target,
+    UsageRecord,
+    UsageUnit,
+    Workspace,
+)
+
+from analygo_foundation.user_identity import UserIdentity, UserIdentityValidator
+
+from analygo_foundation.identity_resolution_log import (
+    Surface,
+    ResolutionStatus,
+    log_identity_resolution,
+)
+
+from analygo_foundation.authority_service import AuthorityService
+
+from analygo_foundation.onboarding import (
+    StepStatus,
+    OnboardingStep,
+    OnboardingState,
+)
+
+from analygo_foundation.guards import require_staff
+
+from analygo_foundation.runtime import (
+    AuthTracer,
+    BoundaryLogger,
+    CorrelationIdMiddleware,
+    IdentityContext,
+    IdentityHealthResponse,
+    IdentityResolutionError,
+    REQUEST_ID_HEADER,
+    build_identity_health,
+    get_current_identity,
+    get_request_id,
+    identity_middleware,
+    install_boundary_logging,
+    resolve_identity,
+)
+
+from analygo_foundation.org_scope import (
+    HEADER_AUDITOR_INTERNAL,
+    HEADER_CLIENT_ID,
+    HEADER_ORG_ID,
+    HEADER_PORTAL_REQUEST_ID,
+    HEADER_PORTAL_SERVICE,
+    LineageSource,
+    OrgScope,
+    OrgScopeResolvedTo,
+    ResolvedOrg,
+    SYSTEM_ORG_ID,
+    SystemOrgReason,
+    get_org_scope,
+    is_portal_originated,
+)
+
+__all__ = [
+    "AuthTracer",
+    "BoundaryLogger",
+    "CorrelationIdMiddleware",
+    "IdentityContext",
+    "IdentityHealthResponse",
+    "IdentityResolutionError",
+    "REQUEST_ID_HEADER",
+    "build_identity_health",
+    "get_current_identity",
+    "get_request_id",
+    "identity_middleware",
+    "install_boundary_logging",
+    "require_staff",
+    "resolve_identity",
+    "EntitlementGrant",
+    "Organization",
+    "SubscriptionGuard",
+    "Property",
+    "Role",
+    "Seat",
+    "SeatKind",
+    "Session",
+    "Target",
+    "UsageRecord",
+    "UsageUnit",
+    "Workspace",
+    "UserIdentity",
+    "UserIdentityValidator",
+    "Surface",
+    "ResolutionStatus",
+    "log_identity_resolution",
+    "AuthorityService",
+    "StepStatus",
+    "OnboardingStep",
+    "OnboardingState",
+    "OrgScope",
+    "ResolvedOrg",
+    "HEADER_ORG_ID",
+    "HEADER_CLIENT_ID",
+    "HEADER_PORTAL_REQUEST_ID",
+    "HEADER_PORTAL_SERVICE",
+    "HEADER_AUDITOR_INTERNAL",
+    "SYSTEM_ORG_ID",
+    "LineageSource",
+    "OrgScopeResolvedTo",
+    "SystemOrgReason",
+    "get_org_scope",
+    "is_portal_originated",
+]

analygo_foundation-1.0.0/analygo_foundation/authority_service.py

@@ -0,0 +1,111 @@
+"""Abstract base for authority services across Analygo surfaces.
+
+An authority service validates whether a user has the right to perform
+an action within an organization context. Concrete implementations
+resolve membership from different backends:
+
+- Backend-native: org membership resolver + Portal DB (platform)
+- Portal-forwarded: HTTP-forwarded authority checks (legacy Portal)
+- AEGIS-native: brain-level agent authorization
+
+All authority services share a common interface so consumers can
+validate access without knowing which backend is authoritative.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, List, Optional
+
+
+@dataclass(frozen=True)
+class AuthorityResult:
+    """Result of an authority check.
+
+    Attributes:
+        granted: True when the action is authorized
+        reason: Human-readable explanation when not granted
+        context: Additional metadata about the decision (role used, source, etc.)
+    """
+
+    granted: bool
+    reason: str = ""
+    context: dict[str, Any] = field(default_factory=dict)
+
+
+class AuthorityService(ABC):
+    """Abstract base for identity authority services.
+
+    Concrete subclasses implement ``authorize`` and ``resolve_identity``
+    to validate user access for a given organization context.
+
+    Thread-safe: subclasses should not mutate instance state during checks.
+    """
+
+    @abstractmethod
+    async def authorize(
+        self,
+        *,
+        user_sub: str,
+        org_id: Optional[str] = None,
+        action: str = "access",
+        **kwargs: Any,
+    ) -> AuthorityResult:
+        """Check whether a user is authorized for an action in an org context.
+
+        Args:
+            user_sub: Canonical user identifier (sub claim from auth).
+            org_id: Target organization ID. May be None for global actions.
+            action: Action being authorized (e.g. "access", "admin", "invite").
+            **kwargs: Subclass-specific parameters.
+
+        Returns:
+            AuthorityResult with granted=True/False and reason.
+        """
+        ...
+
+    @abstractmethod
+    async def resolve_identity(
+        self,
+        *,
+        user_sub: str,
+        org_id: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Resolve identity information for a user in an org context.
+
+        Args:
+            user_sub: Canonical user identifier.
+            org_id: Optional org to scope the resolution.
+
+        Returns:
+            Dict with at minimum ``org_ids``, ``role``, and any available profile data.
+        """
+        ...
+
+    async def require(
+        self,
+        *,
+        user_sub: str,
+        org_id: Optional[str] = None,
+        action: str = "access",
+        **kwargs: Any,
+    ) -> None:
+        """Authorize and raise if not granted.
+
+        Convenience wrapper for callers that want exception-based gating.
+
+        Raises:
+            PermissionError: If authorization is denied.
+        """
+        result = await self.authorize(
+            user_sub=user_sub,
+            org_id=org_id,
+            action=action,
+            **kwargs,
+        )
+        if not result.granted:
+            raise PermissionError(
+                f"Authorization denied for user={user_sub} "
+                f"org={org_id} action={action}: {result.reason}"
+            )

analygo_foundation-1.0.0/analygo_foundation/contracts.py

@@ -0,0 +1,187 @@
+"""Canonical identity type hierarchy for Analygo platform."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+from uuid import UUID
+from pydantic import BaseModel, Field
+
+
+class Organization(BaseModel):
+    """Root tenant entity. All other entities belong to an organization."""
+
+    id: UUID = Field(..., description="Unique organization identifier")
+    name: str = Field(..., description="Organization display name")
+    slug: str = Field(..., description="URL-safe organization identifier")
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+
+    class Config:
+        frozen = True
+
+
+class Workspace(BaseModel):
+    """Groups projects, teams, or clients within an organization."""
+
+    id: UUID = Field(..., description="Unique workspace identifier")
+    org_id: UUID = Field(..., description="Parent organization ID")
+    name: str = Field(..., description="Workspace display name")
+    slug: str = Field(..., description="URL-safe workspace identifier")
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+
+    class Config:
+        frozen = True
+
+
+class Property(BaseModel):
+    """Auditable entity: website, mobile app, or digital property."""
+
+    id: UUID = Field(..., description="Unique property identifier")
+    org_id: UUID = Field(..., description="Parent organization ID")
+    workspace_id: Optional[UUID] = Field(None, description="Optional workspace grouping")
+    name: str = Field(..., description="Property display name (e.g., 'Main Website')")
+    domain: str = Field(..., description="Primary domain or identifier")
+    property_type: str = Field("website", description="Type: website, mobile_app, etc.")
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+
+    class Config:
+        frozen = True
+
+
+class Target(BaseModel):
+    """Specific URL or identifier to audit within a property."""
+
+    id: UUID = Field(..., description="Unique target identifier")
+    property_id: UUID = Field(..., description="Parent property ID")
+    url: str = Field(..., description="Target URL or identifier")
+    label: Optional[str] = Field(None, description="Human-readable label")
+    is_primary: bool = Field(False, description="Primary target for this property")
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+
+    class Config:
+        frozen = True
+
+
+class Session(BaseModel):
+    """Optional audit run or conversation session instance."""
+
+    id: UUID = Field(..., description="Unique session identifier")
+    org_id: UUID = Field(..., description="Parent organization ID")
+    workspace_id: Optional[UUID] = Field(None, description="Optional workspace context")
+    property_id: Optional[UUID] = Field(None, description="Optional property context")
+    user_id: UUID = Field(..., description="User who initiated session")
+    session_type: str = Field("audit", description="Type: audit, conversation, etc.")
+    started_at: datetime = Field(default_factory=datetime.utcnow)
+    ended_at: Optional[datetime] = Field(None)
+
+    class Config:
+        frozen = True
+
+
+class Role(str, Enum):
+    """Membership role within an organization."""
+
+    ORG_OWNER = "org_owner"
+    ORG_ADMIN = "org_admin"
+    PROJECT_MANAGER = "project_manager"
+    AUDITOR = "auditor"
+    VIEWER = "viewer"
+
+
+class SeatKind(str, Enum):
+    """Kind of seat occupying a license within an organization."""
+
+    HUMAN = "human"
+    AI = "ai"
+    SERVICE = "service"
+
+
+class UsageUnit(str, Enum):
+    """Unit of measurement for usage tracking."""
+
+    API_CALL = "api_call"
+    AUDIT_RUN = "audit_run"
+    REPORT_GENERATED = "report_generated"
+    TOKENS = "tokens"
+
+
+@dataclass(frozen=True)
+class Seat:
+    """A seat assigned to a user within an organization."""
+
+    org_id: UUID
+    user_id: UUID
+    kind: SeatKind
+    role: Role
+    active: bool = True
+    usage_limit: Optional[int] = None
+    usage_unit: Optional[UsageUnit] = None
+
+
+@dataclass(frozen=True)
+class UsageRecord:
+    """A record of resource usage attributed to a seat."""
+
+    seat_id: UUID
+    timestamp: datetime
+    unit: UsageUnit
+    quantity: int
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class EntitlementGrant:
+    """A grant of a specific capability to an organization."""
+
+    org_id: UUID
+    capability: str
+    granted_at: datetime
+    expires_at: Optional[datetime] = None
+
+
+class SubscriptionGuard:
+    """Prevents duplicate active subscriptions per org per product area.
+
+    Called before Stripe Checkout session creation to verify the org
+    does not already have an active subscription for the given product_area.
+
+    Example:
+        >>> from analygo_foundation import SubscriptionGuard
+        >>> exists = await SubscriptionGuard.has_active(org_id, "auditor")
+        >>> if exists:
+        ...     return {"status": "already_active", ...}
+    """
+
+    @staticmethod
+    def has_active(org_id: UUID, product_area: str) -> bool:
+        """Check if org has an active subscription for product_area.
+
+        Queries Portal DB billing.stripe_subscriptions via psycopg.
+        Returns True if any active subscription exists.
+        """
+        import os
+        import psycopg
+
+        dsn = os.environ.get("PORTAL_DATABASE_URL", "")
+        if not dsn:
+            return False
+        # Strip SQLAlchemy dialect prefix if present
+        if dsn.startswith("postgresql+"):
+            dsn = "postgresql://" + dsn.split("://", 1)[1]
+
+        try:
+            with psycopg.connect(dsn, connect_timeout=5) as conn:
+                with conn.cursor() as cur:
+                    cur.execute(
+                        """SELECT 1 FROM billing.stripe_subscriptions
+                        WHERE org_id = %s::uuid AND status = 'active'
+                        LIMIT 1""",
+                        (str(org_id),),
+                    )
+                    return cur.fetchone() is not None
+        except Exception:
+            return False

analygo_foundation-1.0.0/analygo_foundation/guards.py

@@ -0,0 +1,49 @@
+"""Staff access guard for internal-only services and routes.
+
+Checks app_metadata.is_staff from the Supabase JWT claims dict.
+Designed to be composed with existing auth dependencies rather than
+baking in FastAPI Depends(verify_token) — each consumer chains it
+with their own auth pipeline.
+
+Raises FastAPI's HTTPException directly since every consumer is a FastAPI
+service. The package adds `fastapi` to its dependencies for this.
+"""
+
+from fastapi import HTTPException, status
+
+
+def require_staff(user: dict) -> dict:
+    """Check that user has is_staff=true in app_metadata.
+
+    Args:
+        user: Decoded JWT claims dict from Supabase (must include
+              app_metadata key). Typically the return value of
+              verify_token or verify_token_sse.
+
+    Returns:
+        The user dict unchanged if the check passes.
+
+    Raises:
+        HTTPException: 403 if app_metadata.is_staff is not truthy.
+
+    Usage:
+        from analygo_foundation import require_staff
+        from app.middleware.auth import verify_token
+
+        # Compose with your auth dependency:
+        def require_staff_rest(
+            user: Annotated[dict, Depends(verify_token)],
+        ) -> dict:
+            return require_staff(user)
+
+        @router.get("/admin")
+        def admin(user: Annotated[dict, Depends(require_staff_rest)]):
+            ...
+    """
+    app_meta = user.get("app_metadata", {}) if isinstance(user, dict) else {}
+    if not app_meta.get("is_staff"):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Internal access only",
+        )
+    return user

analygo_foundation-1.0.0/analygo_foundation/identity_resolution_log.py

@@ -0,0 +1,96 @@
+"""Canonical structured logging for identity / org membership resolution.
+
+Uses stdlib ``logging`` with ``extra={"identity_event": {...}}``.
+
+**identity_event schema** (stable keys; all values JSON-serializable primitives or lists of strings):
+
+- ``event``: always ``identity.resolution`` unless overridden.
+- ``surface``: ``backend_resolver`` | ``backend_me_orgs`` | ``portal_user_orgs`` | ``portal_verify_org_access``.
+- ``resolution_status``: ``ok`` | ``empty`` | ``unavailable``.
+- ``request_id``: correlation id when set.
+- ``sub_prefix``: first 8 chars of ``membership_sub``.
+- ``effective_lookup_sub``: first 8 chars of the canonical Portal/cache lookup key.
+- ``users_logs_sub_prefix``: optional; first 8 of ``UsersLog.sub`` when supplied.
+- ``error_code``: optional when guarded or failed (e.g. ``canonical_sub_missing``).
+- ``org_count``, ``org_ids``: UUID strings from the resolved payload (empty when unavailable).
+- ``identity_source``: how membership sub was derived.
+- ``resolver_source``: ``ResolveResult.source`` when applicable.
+- ``active_org_id``: when known.
+
+**Never** log access tokens, refresh tokens, or cookie values.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, List, Literal, Optional
+
+logger = logging.getLogger("analygo_foundation.identity_resolution")
+
+Surface = Literal["backend_resolver", "backend_me_orgs", "portal_user_orgs", "portal_verify_org_access"]
+ResolutionStatus = Literal["ok", "empty", "unavailable"]
+
+
+def _sub_prefix(sub: Optional[str]) -> Optional[str]:
+    s = (sub or "").strip()
+    if not s:
+        return None
+    return s[:8]
+
+
+def log_identity_resolution(
+    *,
+    surface: Surface,
+    resolution_status: ResolutionStatus,
+    request_id: Optional[str] = None,
+    identity_source: Optional[str] = None,
+    resolver_source: Optional[str] = None,
+    membership_sub: Optional[str] = None,
+    users_logs_sub: Optional[str] = None,
+    effective_lookup_sub: Optional[str] = None,
+    org_ids: Optional[List[str]] = None,
+    org_count: Optional[int] = None,
+    active_org_id: Optional[str] = None,
+    email: Optional[str] = None,
+    error_code: Optional[str] = None,
+    event: str = "identity.resolution",
+    log_level: int = logging.INFO,
+) -> None:
+    """Emit one structured ``identity_event`` line for cross-surface correlation."""
+    oids = [str(x) for x in (org_ids or []) if x is not None and str(x).strip()]
+    count = org_count if org_count is not None else len(oids)
+    canonical_for_prefix = (
+        effective_lookup_sub if effective_lookup_sub is not None else membership_sub
+    )
+    mem_prefix = _sub_prefix(membership_sub) or ""
+    eff_prefix = _sub_prefix(canonical_for_prefix) or ""
+    payload: dict[str, Any] = {
+        "event": event,
+        "surface": surface,
+        "resolution_status": resolution_status,
+        "request_id": request_id or "",
+        "sub_prefix": mem_prefix,
+        "effective_lookup_sub": eff_prefix,
+        "org_count": count,
+        "org_ids": oids,
+    }
+    usp = _sub_prefix(users_logs_sub)
+    if usp:
+        payload["users_logs_sub_prefix"] = usp
+    if identity_source:
+        payload["identity_source"] = identity_source
+    if resolver_source:
+        payload["resolver_source"] = resolver_source
+    if active_org_id:
+        payload["active_org_id"] = str(active_org_id)
+    if email is not None:
+        payload["has_email"] = bool((email or "").strip())
+    ec = (error_code or "").strip()
+    if ec:
+        payload["error_code"] = ec
+
+    logger.log(
+        log_level,
+        "identity.resolution",
+        extra={"identity_event": payload},
+    )