analygo-identity 0.1.0__tar.gz

analygo_identity-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: analygo-identity
+Version: 0.1.0
+Summary: Canonical identity types and validators for Analygo services
+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
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"

analygo_identity-0.1.0/README.md

@@ -0,0 +1,5 @@
+# analygo-identity (Python)
+
+Shared identity resolution, authority services, and onboarding state management.
+
+Consumed as `analygo-identity` from GitHub Packages.

analygo_identity-0.1.0/analygo_identity/__init__.py

@@ -0,0 +1,71 @@
+"""analygo-identity: Shared identity resolution, authority services, and onboarding state."""
+
+from analygo_identity.contracts import (
+    Organization,
+    Workspace,
+    Property,
+    Target,
+    Session,
+)
+
+from analygo_identity.user_identity import UserIdentity, UserIdentityValidator
+
+from analygo_identity.identity_resolution_log import (
+    Surface,
+    ResolutionStatus,
+    log_identity_resolution,
+)
+
+from analygo_identity.authority_service import AuthorityService
+
+from analygo_identity.onboarding import (
+    StepStatus,
+    OnboardingStep,
+    OnboardingState,
+)
+
+from analygo_identity.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__ = [
+    "Organization",
+    "Workspace",
+    "Property",
+    "Target",
+    "Session",
+    "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_identity-0.1.0/analygo_identity/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_identity-0.1.0/analygo_identity/contracts.py

@@ -0,0 +1,80 @@
+"""Canonical identity type hierarchy for Analygo platform."""
+
+from datetime import datetime
+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

analygo_identity-0.1.0/analygo_identity/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_identity.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},
+    )

analygo_identity-0.1.0/analygo_identity/onboarding.py

@@ -0,0 +1,250 @@
+"""Onboarding state machine for multi-surface identity lifecycle.
+
+Defines generic steps common to all Analygo surfaces. Per-service
+extensions (e.g. Platform: ``connect_first_site``, AEGIS: ``select_default_agent``,
+Portal: ``invite_team_members``) live in each service's own code, not in this package.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Callable, Dict, List, Optional
+
+
+class StepStatus(Enum):
+    """Status of a single onboarding step."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    SKIPPED = "skipped"
+
+
+class OnboardingStep(str, Enum):
+    """Generic onboarding steps shared across all Analygo surfaces.
+
+    These four steps are the minimum common path. Services extend via
+    ExtensionStep API (see ``OnboardingState.add_extension_step``).
+    """
+
+    VERIFY_EMAIL = "verify_email"
+    CREATE_ORG = "create_org"
+    CREATE_WORKSPACE = "create_workspace"
+    SETUP_BILLING = "setup_billing"
+
+
+@dataclass
+class OnboardingState:
+    """Onboarding progress for a user across one or more surfaces.
+
+    The state machine tracks which steps exist, their status, and when
+    each was completed. Steps are ordered; the ``current_step`` property
+    returns the first non-completed step.
+
+    Extension steps can be added at runtime via ``add_extension_step``
+    for service-specific onboarding requirements.
+
+    Example:
+        >>> state = OnboardingState()
+        >>> state.advance(OnboardingStep.VERIFY_EMAIL)
+        >>> state.current_step
+        <OnboardingStep.CREATE_ORG: 'create_org'>
+        >>> state.is_complete
+        False
+    """
+
+    steps: list[OnboardingStep] = field(
+        default_factory=lambda: [
+            OnboardingStep.VERIFY_EMAIL,
+            OnboardingStep.CREATE_ORG,
+            OnboardingStep.CREATE_WORKSPACE,
+            OnboardingStep.SETUP_BILLING,
+        ]
+    )
+    statuses: dict[OnboardingStep, StepStatus] = field(default_factory=dict)
+    completed_at: dict[OnboardingStep, Optional[datetime]] = field(default_factory=dict)
+
+    # Extension-point API for per-service steps
+    _extension_loaders: list[Callable[[], list[OnboardingStep]]] = field(default_factory=list, repr=False)
+
+    def __post_init__(self) -> None:
+        """Initialize all steps as PENDING."""
+        for step in self.steps:
+            if step not in self.statuses:
+                self.statuses[step] = StepStatus.PENDING
+            if step not in self.completed_at:
+                self.completed_at[step] = None
+
+    @property
+    def current_step(self) -> Optional[OnboardingStep]:
+        """The first step that is not COMPLETED or SKIPPED, or None if all done."""
+        for step in self.steps:
+            status = self.statuses.get(step, StepStatus.PENDING)
+            if status not in (StepStatus.COMPLETED, StepStatus.SKIPPED):
+                return step
+        return None
+
+    @property
+    def is_complete(self) -> bool:
+        """True when all registered steps are COMPLETED or SKIPPED."""
+        return self.current_step is None
+
+    def advance(self, step: OnboardingStep) -> None:
+        """Mark a step as COMPLETED at the current time.
+
+        Args:
+            step: The step to advance. Must be in ``steps``.
+        """
+        if step not in self.steps:
+            raise ValueError(
+                f"Unknown onboarding step: {step!r}. "
+                f"Known steps: {[s.value for s in self.steps]}"
+            )
+        self.statuses[step] = StepStatus.COMPLETED
+        self.completed_at[step] = datetime.utcnow()
+
+    def skip(self, step: OnboardingStep) -> None:
+        """Mark a step as SKIPPED.
+
+        Args:
+            step: The step to skip. Must be in ``steps``.
+        """
+        if step not in self.steps:
+            raise ValueError(
+                f"Unknown onboarding step: {step!r}. "
+                f"Known steps: {[s.value for s in self.steps]}"
+            )
+        self.statuses[step] = StepStatus.SKIPPED
+        self.completed_at[step] = None
+
+    def progress(self, step: OnboardingStep) -> None:
+        """Mark a step as IN_PROGRESS.
+
+        Args:
+            step: The step being worked on. Must be in ``steps``.
+        """
+        if step not in self.steps:
+            raise ValueError(
+                f"Unknown onboarding step: {step!r}. "
+                f"Known steps: {[s.value for s in self.steps]}"
+            )
+        self.statuses[step] = StepStatus.IN_PROGRESS
+
+    def reset(self, step: OnboardingStep) -> None:
+        """Reset a step back to PENDING.
+
+        Useful for re-doing a step after a failure.
+
+        Args:
+            step: The step to reset.
+        """
+        if step not in self.steps:
+            raise ValueError(
+                f"Unknown onboarding step: {step!r}. "
+                f"Known steps: {[s.value for s in self.steps]}"
+            )
+        self.statuses[step] = StepStatus.PENDING
+        self.completed_at[step] = None
+
+    # ------------------------------------------------------------------
+    # Extension Point API
+    # ------------------------------------------------------------------
+
+    def register_extension_loader(
+        self,
+        loader: Callable[[], list[OnboardingStep]],
+    ) -> None:
+        """Register a callable that returns service-specific extension steps.
+
+        The loader is called once, when ``load_extensions`` is invoked.
+        This allows lazy discovery of extension steps without tight coupling.
+
+        Args:
+            loader: A zero-argument callable returning a list of OnboardingStep values.
+        """
+        self._extension_loaders.append(loader)
+
+    def load_extensions(self) -> list[OnboardingStep]:
+        """Invoke all registered extension loaders and append new steps.
+
+        Returns:
+            The list of newly added extension steps.
+        """
+        added: list[OnboardingStep] = []
+        for loader in self._extension_loaders:
+            try:
+                ext_steps = loader()
+                for ext_step in ext_steps:
+                    if ext_step not in self.steps:
+                        self.steps.append(ext_step)
+                        self.statuses[ext_step] = StepStatus.PENDING
+                        self.completed_at[ext_step] = None
+                        added.append(ext_step)
+            except Exception:
+                # Fail-soft: log and continue
+                logger = __import__("logging").getLogger(__name__)
+                logger.exception("Onboarding extension loader failed: %s", loader)
+        return added
+
+    # ------------------------------------------------------------------
+    # Serialization
+    # ------------------------------------------------------------------
+
+    def to_dict(self) -> dict:
+        """Serialize onboarding state to a JSON-compatible dict.
+
+        Returns:
+            Dict with ``current_step``, ``is_complete``, ``steps``, and
+            per-step status/completed_at entries.
+        """
+        return {
+            "current_step": self.current_step.value if self.current_step else None,
+            "is_complete": self.is_complete,
+            "steps": [
+                {
+                    "step": s.value,
+                    "status": (self.statuses.get(s) or StepStatus.PENDING).value,
+                    "completed_at": (
+                        self.completed_at[s].isoformat()
+                        if self.completed_at.get(s)
+                        else None
+                    ),
+                }
+                for s in self.steps
+            ],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "OnboardingState":
+        """Deserialize onboarding state from a dict.
+
+        Args:
+            data: A dict previously produced by ``to_dict``.
+
+        Returns:
+            A new OnboardingState instance.
+        """
+        step_map = {s.value: s for s in OnboardingStep}
+        raw_steps = data.get("steps", [])
+        steps: list[OnboardingStep] = []
+        statuses: dict[OnboardingStep, StepStatus] = {}
+        completed_at: dict[OnboardingStep, Optional[datetime]] = {}
+
+        for entry in raw_steps:
+            step = step_map.get(entry["step"])
+            if step is None:
+                continue
+            steps.append(step)
+            raw_status = entry.get("status", "pending")
+            statuses[step] = StepStatus(raw_status)
+            raw_completed = entry.get("completed_at")
+            completed_at[step] = (
+                datetime.fromisoformat(raw_completed)
+                if raw_completed
+                else None
+            )
+
+        state = cls(steps=steps, statuses=statuses, completed_at=completed_at)
+        return state

analygo_identity-0.1.0/analygo_identity/org_scope.py

@@ -0,0 +1,89 @@
+"""Workspace resolution types and header parsing for multi-tenant org scoping."""
+
+from dataclasses import dataclass
+from typing import Optional, Literal
+from uuid import UUID
+
+# ── Header constants ──────────────────────────────────────────────
+
+HEADER_ORG_ID = "X-Org-Id"
+HEADER_CLIENT_ID = "X-Client-Id"
+HEADER_PORTAL_REQUEST_ID = "X-Portal-Request-Id"
+HEADER_PORTAL_SERVICE = "X-Portal-Service"
+HEADER_AUDITOR_INTERNAL = "X-Auditor-Internal"
+
+# ── System org ────────────────────────────────────────────────────
+
+SYSTEM_ORG_ID = "00000000-0000-0000-0000-000000000001"
+
+# ── Literal types ─────────────────────────────────────────────────
+
+LineageSource = Literal[
+    "portal_request",
+    "org_scope",
+    "portal_membership",
+    "fallback_org",
+    "refresh_parent",
+]
+
+OrgScopeResolvedTo = Literal["system", "portal", "header"]
+
+SystemOrgReason = Literal["no_portal_orgs", "internal_run", "demo", "worker"]
+
+
+# ── Dataclasses ───────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class ResolvedOrg:
+    """Result of org resolution — mirrors TS OrgContext."""
+    org_id: UUID
+    client_id: Optional[UUID]
+    portal_request_id: Optional[UUID]
+    lineage_source: LineageSource
+    lineage_reason: Optional[str]
+    org_scope_resolved_to: OrgScopeResolvedTo
+    system_org_reason: Optional[SystemOrgReason] = None
+
+
+@dataclass(frozen=True)
+class OrgScope:
+    """Tenant scope extracted from request headers."""
+    org_id: UUID
+    client_id: Optional[UUID] = None
+    portal_request_id: Optional[UUID] = None
+
+
+# ── Header parsing ────────────────────────────────────────────────
+
+
+def _parse_uuid(value: Optional[str]) -> Optional[UUID]:
+    """Parse a string to UUID, returning None for invalid/missing input."""
+    if not value:
+        return None
+    try:
+        return UUID(value)
+    except (ValueError, AttributeError):
+        return None
+
+
+def get_org_scope(headers: dict[str, str]) -> Optional[OrgScope]:
+    """Extract OrgScope from request headers.
+
+    Returns None if X-Org-Id header is missing or invalid.
+    """
+    org_id_raw = headers.get(HEADER_ORG_ID)
+    org_id = _parse_uuid(org_id_raw)
+    if org_id is None:
+        return None
+
+    return OrgScope(
+        org_id=org_id,
+        client_id=_parse_uuid(headers.get(HEADER_CLIENT_ID)),
+        portal_request_id=_parse_uuid(headers.get(HEADER_PORTAL_REQUEST_ID)),
+    )
+
+
+def is_portal_originated(headers: dict[str, str]) -> bool:
+    """Check if request originated from the portal service."""
+    return HEADER_PORTAL_REQUEST_ID in headers or HEADER_PORTAL_SERVICE in headers

analygo_identity-0.1.0/analygo_identity/user_identity.py

@@ -0,0 +1,139 @@
+"""User identity protocol for type-safe authentication across services.
+
+This module defines the canonical interface for user objects, preventing
+type mismatches like accessing .id when the attribute is .sub.
+"""
+
+from typing import Protocol, runtime_checkable, cast, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any
+
+
+@runtime_checkable
+class UserIdentity(Protocol):
+    """Protocol defining the canonical interface for authenticated users.
+
+    Any object representing an authenticated user must satisfy this protocol.
+    Primary identifier is 'sub' (subject), not 'id', following JWT/OIDC conventions.
+
+    Example:
+        >>> user: UserIdentity = get_current_user()
+        >>> user.sub  # Canonical user identifier
+        'auth0|123456'
+    """
+
+    @property
+    def sub(self) -> str:
+        """Canonical user identifier (subject claim from auth provider)."""
+        ...
+
+    @property
+    def email(self) -> str | None:
+        """User's email address, if available."""
+        ...
+
+
+class UserIdentityValidator:
+    """Runtime validator for user objects.
+
+    Provides clear error messages when objects don't satisfy UserIdentity protocol,
+    catching issues like missing .sub or using .id instead.
+    """
+
+    @staticmethod
+    def _get_sub(user: object) -> str | None:
+        """Extract 'sub' from an object or dict."""
+        if isinstance(user, dict):
+            return user.get("sub")  # type: ignore[return-value]
+        if hasattr(user, "sub"):
+            return getattr(user, "sub")
+        return None
+
+    @staticmethod
+    def _has_sub(user: object) -> bool:
+        """Check if user has 'sub' (as attribute or dict key)."""
+        if isinstance(user, dict):
+            return "sub" in user
+        return hasattr(user, "sub")
+
+    @staticmethod
+    def _has_id_not_sub(user: object) -> bool:
+        """Check for common mistake: has 'id' but not 'sub'."""
+        if isinstance(user, dict):
+            return "id" in user and "sub" not in user
+        return hasattr(user, "id") and not hasattr(user, "sub")
+
+    @staticmethod
+    def _dir(user: object) -> list[str]:
+        """List available keys/attributes for error messages."""
+        if isinstance(user, dict):
+            return list(user.keys())
+        return [a for a in dir(user) if not a.startswith("_")]
+
+    @staticmethod
+    def validate_sub(user: object, context: str = "") -> str:
+        """Extract and validate user.sub with clear error on failure.
+
+        Supports both objects (attribute access) and dicts (key access).
+
+        Args:
+            user: Object or dict expected to satisfy UserIdentity protocol
+            context: Additional context for error messages (e.g., function name)
+
+        Returns:
+            The user's sub (subject identifier)
+
+        Raises:
+            AttributeError: If user.sub is missing or user uses wrong attribute name
+            TypeError: If user is None or wrong type
+        """
+        if user is None:
+            raise TypeError(
+                f"{context}: User object is None. "
+                "Ensure authentication dependency returned a valid user."
+            )
+
+        # Check for common mistake: using .id / ["id"] instead of .sub / ["sub"]
+        if UserIdentityValidator._has_id_not_sub(user):
+            raise AttributeError(
+                f"{context}: User object has 'id' but not 'sub'. "
+                "Use user.sub (not user.id) for the canonical user identifier."
+            )
+
+        if not UserIdentityValidator._has_sub(user):
+            raise AttributeError(
+                f"{context}: User object missing 'sub' attribute. "
+                f"Available attributes: {UserIdentityValidator._dir(user)}. "
+                "User must satisfy UserIdentity protocol."
+            )
+
+        sub = UserIdentityValidator._get_sub(user)
+        if not isinstance(sub, str):
+            raise TypeError(
+                f"{context}: user.sub must be str, got {type(sub).__name__}"
+            )
+
+        return sub
+
+    @staticmethod
+    def validate(user: object, context: str = "") -> "UserIdentity":
+        """Validate user object satisfies UserIdentity protocol.
+
+        Args:
+            user: Object to validate
+            context: Additional context for error messages
+
+        Returns:
+            The user object cast to UserIdentity
+
+        Raises:
+            TypeError: If user doesn't satisfy the protocol
+        """
+        if not isinstance(user, UserIdentity):
+            raise TypeError(
+                f"{context}: User object does not satisfy UserIdentity protocol. "
+                f"Type: {type(user).__name__}. "
+                "Required: .sub (str), .email (str | None)"
+            )
+        return cast("UserIdentity", user)

analygo_identity-0.1.0/analygo_identity.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: analygo-identity
+Version: 0.1.0
+Summary: Canonical identity types and validators for Analygo services
+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
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"

analygo_identity-0.1.0/analygo_identity.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+analygo_identity/__init__.py
+analygo_identity/authority_service.py
+analygo_identity/contracts.py
+analygo_identity/identity_resolution_log.py
+analygo_identity/onboarding.py
+analygo_identity/org_scope.py
+analygo_identity/py.typed
+analygo_identity/user_identity.py
+analygo_identity.egg-info/PKG-INFO
+analygo_identity.egg-info/SOURCES.txt
+analygo_identity.egg-info/dependency_links.txt
+analygo_identity.egg-info/requires.txt
+analygo_identity.egg-info/top_level.txt

analygo_identity-0.1.0/analygo_identity.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

analygo_identity-0.1.0/analygo_identity.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pydantic>=2.0.0
+
+[dev]
+pytest>=7.0.0

analygo_identity-0.1.0/analygo_identity.egg-info/top_level.txt

@@ -0,0 +1 @@
+analygo_identity

analygo_identity-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "analygo-identity"
+version = "0.1.0"
+description = "Canonical identity types and validators for Analygo services"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Analygo", email = "engineering@analygo.com" },
+]
+dependencies = [
+    "pydantic>=2.0.0",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+]
+
+[build-system]
+requires = ["setuptools>=75.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["analygo_identity*"]
+
+[tool.setuptools.package-data]
+analygo_identity = ["py.typed"]

analygo_identity-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+