feat: implement prepared account claims

src/user_engine/domain/__init__.py

@@ -29,6 +29,11 @@ from user_engine.domain.models import (
     Mutability,
     OutboxEvent,
     PrincipalType,
+    PreparedAccount,
+    PreparedAccountStatus,
+    PreparedEntitlement,
+    PreparedEntitlementKind,
+    PreparedFactorRequirement,
     ProfileScope,
     ProfileValue,
     ProjectionType,
@@ -71,6 +76,11 @@ __all__ = [
     "Mutability",
     "OutboxEvent",
     "PrincipalType",
+    "PreparedAccount",
+    "PreparedAccountStatus",
+    "PreparedEntitlement",
+    "PreparedEntitlementKind",
+    "PreparedFactorRequirement",
     "ProfileScope",
     "ProfileValue",
     "ProjectionType",

src/user_engine/domain/models.py

@@ -69,6 +69,13 @@ class RegistrationStatus(StrEnum):
     REJECTED = "rejected"
 
 
+class PreparedAccountStatus(StrEnum):
+    PENDING = "pending"
+    CLAIMED = "claimed"
+    REVOKED = "revoked"
+    EXPIRED = "expired"
+
+
 class IdentityFactorType(StrEnum):
     EMAIL = "email"
     PHONE = "phone"
@@ -78,6 +85,14 @@ class IdentityFactorType(StrEnum):
     SSO = "sso"
 
 
+class PreparedEntitlementKind(StrEnum):
+    TENANT_ACCOUNT = "tenant_account"
+    MEMBERSHIP = "membership"
+    PROFILE_VALUE = "profile_value"
+    APPLICATION_BINDING = "application_binding"
+    ONBOARDING_JOURNEY = "onboarding_journey"
+
+
 class ProfileScope(StrEnum):
     GLOBAL = "global"
     TENANT = "tenant"
@@ -379,6 +394,54 @@ class RegistrationSession:
     rejected_at: datetime | None = None
 
 
+@dataclass(frozen=True)
+class PreparedFactorRequirement:
+    factor_type: IdentityFactorType
+    normalized_value: str
+    source_system: str | None = None
+    evidence_refs: tuple[CanonEntityReference, ...] = ()
+
+
+@dataclass(frozen=True)
+class PreparedEntitlement:
+    kind: PreparedEntitlementKind
+    tenant: str
+    entitlement_id: str = field(default_factory=lambda: new_id("pent"))
+    scope_type: str | None = None
+    scope_id: str | None = None
+    role: str | None = None
+    attribute_key: str | None = None
+    value: Any = None
+    profile_scope: ProfileScope = ProfileScope.GLOBAL
+    profile_scope_id: str | None = None
+    tenant_account_status: AccountStatus = AccountStatus.ACTIVE
+    application_binding: ApplicationBinding | None = None
+    onboarding_journey: str | None = None
+    requires_approval: bool = False
+    evidence_refs: tuple[CanonEntityReference, ...] = ()
+
+
+@dataclass(frozen=True)
+class PreparedAccount:
+    tenant: str
+    required_factor_matches: tuple[PreparedFactorRequirement, ...]
+    entitlements: tuple[PreparedEntitlement, ...]
+    prepared_account_id: str = field(default_factory=lambda: new_id("pacct"))
+    status: PreparedAccountStatus = PreparedAccountStatus.PENDING
+    display_name: str | None = None
+    primary_email: str | None = None
+    prepared_by_subject: str | None = None
+    correlation_id: str | None = None
+    expires_at: datetime | None = None
+    claimed_by_user_id: str | None = None
+    claimed_registration_id: str | None = None
+    created_at: datetime = field(default_factory=utc_now)
+    updated_at: datetime = field(default_factory=utc_now)
+    claimed_at: datetime | None = None
+    revoked_at: datetime | None = None
+    expired_at: datetime | None = None
+
+
 @dataclass(frozen=True)
 class AuthorizationRequest:
     actor: Actor