ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/schemas/services/authority/jwt.py

@@ -0,0 +1,158 @@
+"""
+JWT-related schemas for authentication.
+
+Provides type-safe structures for JWT tokens and claims.
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field, field_validator
+
+from ciris_engine.schemas.services.authority_core import JWTSubType, WARole
+
+
+class JWTAlgorithm(str, Enum):
+    """Supported JWT signature algorithms."""
+
+    HS256 = "HS256"  # HMAC SHA256 (gateway tokens)
+    EdDSA = "EdDSA"  # Ed25519 (WA tokens)
+
+
+class JWTHeader(BaseModel):
+    """JWT header information."""
+
+    alg: JWTAlgorithm = Field(..., description="Signature algorithm")
+    typ: str = Field("JWT", description="Token type")
+    kid: Optional[str] = Field(None, description="Key identifier for WA tokens")
+
+    @field_validator("typ")
+    def validate_typ(cls, v: str) -> str:
+        """Ensure typ is JWT."""
+        if v != "JWT":
+            raise ValueError("typ must be 'JWT'")
+        return v
+
+
+class JWTClaims(BaseModel):
+    """Standard JWT claims for CIRIS tokens."""
+
+    # Standard JWT claims
+    iss: str = Field(..., description="Issuer (gateway or WA ID)")
+    sub: str = Field(..., description="Subject (WA ID or channel identity)")
+    aud: Union[str, List[str]] = Field(..., description="Audience (service or adapter)")
+    exp: datetime = Field(..., description="Expiration time")
+    iat: datetime = Field(..., description="Issued at time")
+    jti: Optional[str] = Field(None, description="JWT ID for revocation")
+
+    # CIRIS-specific claims
+    sub_type: JWTSubType = Field(..., description="Subject type classification")
+    role: Optional[WARole] = Field(None, description="WA role if applicable")
+    name: Optional[str] = Field(None, description="Human-readable name")
+    scopes: List[str] = Field(default_factory=list, description="Granted scopes/permissions")
+
+    # Channel identity claims (for channel tokens)
+    adapter_type: Optional[str] = Field(None, description="Adapter type for channel tokens")
+    adapter_instance_id: Optional[str] = Field(None, description="Adapter instance ID")
+    external_user_id: Optional[str] = Field(None, description="External user ID")
+    external_username: Optional[str] = Field(None, description="External username")
+
+    # OAuth claims (for OAuth tokens)
+    oauth_provider: Optional[str] = Field(None, description="OAuth provider name")
+    oauth_external_id: Optional[str] = Field(None, description="OAuth external ID")
+
+    # Additional metadata
+    metadata: Dict[str, str] = Field(default_factory=dict, description="Additional metadata")
+
+    @field_validator("exp", "iat")
+    def validate_timestamps(cls, v: datetime) -> datetime:
+        """Ensure timestamps have timezone info."""
+        if v.tzinfo is None:
+            raise ValueError("Timestamps must include timezone info")
+        return v
+
+    def is_expired(self, current_time: Optional[datetime] = None) -> bool:
+        """Check if token is expired."""
+        if current_time is None:
+            from datetime import timezone
+
+            current_time = datetime.now(timezone.utc)
+        return current_time >= self.exp
+
+    def is_valid_for_audience(self, expected_audience: str) -> bool:
+        """Check if token is valid for the expected audience."""
+        if isinstance(self.aud, str):
+            return self.aud == expected_audience
+        return expected_audience in self.aud
+
+    def has_scope(self, scope: str) -> bool:
+        """Check if token has a specific scope."""
+        return scope in self.scopes
+
+    def get_wa_id(self) -> Optional[str]:
+        """Extract WA ID from claims if applicable."""
+        if self.sub_type in [JWTSubType.AUTHORITY, JWTSubType.USER]:
+            return self.sub
+        return None
+
+    def get_channel_identity(self) -> Optional[Dict[str, str]]:
+        """Extract channel identity if this is a channel token."""
+        if self.sub_type == JWTSubType.ANON and self.adapter_type:
+            return {
+                "adapter_type": self.adapter_type,
+                "adapter_instance_id": self.adapter_instance_id or "",
+                "external_user_id": self.external_user_id or "",
+                "external_username": self.external_username or "",
+            }
+        return None
+
+
+class JWTToken(BaseModel):
+    """Complete JWT token with header and claims."""
+
+    header: JWTHeader = Field(..., description="JWT header")
+    claims: JWTClaims = Field(..., description="JWT claims")
+    signature: Optional[str] = Field(None, description="Base64url encoded signature")
+
+    def to_string(self) -> str:
+        """Convert to standard JWT string format."""
+        import base64
+        import json
+
+        # Encode header
+        header_json = json.dumps(self.header.model_dump(exclude_none=True), separators=(",", ":"))
+        header_b64 = base64.urlsafe_b64encode(header_json.encode()).decode().rstrip("=")
+
+        # Encode claims (convert datetime to timestamp)
+        claims_dict = self.claims.model_dump(exclude_none=True)
+        claims_dict["exp"] = int(self.claims.exp.timestamp())
+        claims_dict["iat"] = int(self.claims.iat.timestamp())
+        claims_json = json.dumps(claims_dict, separators=(",", ":"))
+        claims_b64 = base64.urlsafe_b64encode(claims_json.encode()).decode().rstrip("=")
+
+        # Combine with signature if present
+        if self.signature:
+            return f"{header_b64}.{claims_b64}.{self.signature}"
+        return f"{header_b64}.{claims_b64}"
+
+
+class JWTValidationResult(BaseModel):
+    """Result of JWT validation."""
+
+    valid: bool = Field(..., description="Whether token is valid")
+    token: Optional[JWTToken] = Field(None, description="Parsed token if valid")
+    error: Optional[str] = Field(None, description="Error message if invalid")
+    error_type: Optional[str] = Field(None, description="Type of validation error")
+
+    def get_wa_id(self) -> Optional[str]:
+        """Get WA ID from validated token."""
+        if self.valid and self.token:
+            return self.token.claims.get_wa_id()
+        return None
+
+    def get_role(self) -> Optional[WARole]:
+        """Get role from validated token."""
+        if self.valid and self.token:
+            return self.token.claims.role
+        return None

ciris_engine/schemas/services/authority/wa_updates.py

@@ -0,0 +1,138 @@
+"""
+WA certificate update schemas for CIRIS.
+
+Provides type-safe structures for updating WA certificates with partial updates.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from ciris_engine.schemas.services.authority_core import WARole
+from ciris_engine.schemas.types import JSONDict
+
+
+class WACertificateUpdate(BaseModel):
+    """Request to update an existing WA certificate with partial updates."""
+
+    # Identity fields (read-only, included for validation only)
+    wa_id: Optional[str] = Field(None, description="WA ID to update (read-only)")
+
+    # Updatable fields
+    name: Optional[str] = Field(None, min_length=1, max_length=255, description="Update display name")
+    role: Optional[WARole] = Field(None, description="Update role (requires authority permission)")
+
+    # Authentication updates
+    password: Optional[str] = Field(None, description="New password (will be hashed)")
+    api_key: Optional[str] = Field(None, description="New API key (will be hashed)")
+
+    # OAuth updates
+    oauth_provider: Optional[str] = Field(None, description="Update OAuth provider")
+    oauth_external_id: Optional[str] = Field(None, description="Update OAuth external ID")
+
+    # Veilid updates
+    veilid_id: Optional[str] = Field(None, description="Update Veilid ID")
+
+    # Trust chain updates (requires authority permission)
+    parent_wa_id: Optional[str] = Field(None, description="Update parent WA ID")
+    parent_signature: Optional[str] = Field(None, description="Update parent signature")
+
+    # Scope updates
+    scopes: Optional[List[str]] = Field(None, description="Replace all scopes")
+    add_scopes: Optional[List[str]] = Field(None, description="Add new scopes")
+    remove_scopes: Optional[List[str]] = Field(None, description="Remove existing scopes")
+
+    # Adapter updates
+    adapter_id: Optional[str] = Field(None, description="Update adapter ID")
+    adapter_name: Optional[str] = Field(None, description="Update adapter name")
+    adapter_metadata: Optional[Dict[str, str]] = Field(None, description="Update adapter metadata")
+
+    @field_validator("scopes", "add_scopes", "remove_scopes")
+    def validate_scope_lists(cls, v: Optional[List[str]]) -> Optional[List[str]]:
+        """Ensure scope lists contain unique values."""
+        if v is not None:
+            return list(set(v))
+        return v
+
+    @field_validator("password", "api_key")
+    def validate_credentials(cls, v: Optional[str]) -> Optional[str]:
+        """Ensure credentials meet minimum requirements."""
+        if v is not None and len(v) < 8:
+            raise ValueError("Credentials must be at least 8 characters long")
+        return v
+
+    def has_updates(self) -> bool:
+        """Check if any fields are set for update."""
+        exclude_fields = {"wa_id"}  # Fields that don't count as updates
+        for field_name, field_value in self.model_dump(exclude_unset=True).items():
+            if field_name not in exclude_fields and field_value is not None:
+                return True
+        return False
+
+    def get_update_fields(self) -> JSONDict:
+        """Get only the fields that are being updated."""
+        updates: JSONDict = {}
+        exclude_fields = {"wa_id", "add_scopes", "remove_scopes"}
+
+        for field_name, field_value in self.model_dump(exclude_unset=True).items():
+            if field_name not in exclude_fields and field_value is not None:
+                updates[field_name] = field_value
+
+        return updates
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class WACertificateUpdateResponse(BaseModel):
+    """Response after updating a WA certificate."""
+
+    success: bool = Field(..., description="Whether update succeeded")
+    wa_id: str = Field(..., description="ID of updated certificate")
+    updated_fields: List[str] = Field(..., description="List of fields that were updated")
+    updated_at: datetime = Field(..., description="When certificate was updated")
+    message: Optional[str] = Field(None, description="Additional information about the update")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class WABulkUpdate(BaseModel):
+    """Request to update multiple WA certificates."""
+
+    wa_ids: List[str] = Field(..., min_length=1, description="List of WA IDs to update")
+    update: WACertificateUpdate = Field(..., description="Update to apply to all certificates")
+
+    @field_validator("wa_ids")
+    def validate_wa_ids(cls, v: List[str]) -> List[str]:
+        """Ensure WA IDs are unique and valid."""
+        unique_ids = list(set(v))
+        if len(unique_ids) != len(v):
+            raise ValueError("WA IDs must be unique")
+
+        # Validate each ID matches expected pattern
+        import re
+
+        pattern = re.compile(r"^wa-\d{4}-\d{2}-\d{2}-[A-Z0-9]{6}$")
+        for wa_id in unique_ids:
+            if not pattern.match(wa_id):
+                raise ValueError(f"Invalid WA ID format: {wa_id}")
+
+        return unique_ids
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class WABulkUpdateResponse(BaseModel):
+    """Response after bulk updating WA certificates."""
+
+    total_requested: int = Field(..., description="Number of certificates requested to update")
+    total_updated: int = Field(..., description="Number of certificates successfully updated")
+    failures: List[Dict[str, str]] = Field(
+        default_factory=list, description="List of failures with wa_id and error message"
+    )
+    updated_at: datetime = Field(..., description="When bulk update was completed")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+__all__ = ["WACertificateUpdate", "WACertificateUpdateResponse", "WABulkUpdate", "WABulkUpdateResponse"]

ciris_engine/schemas/services/authority/wise_authority.py

@@ -0,0 +1,163 @@
+"""
+Wise Authority service schemas.
+
+Provides typed schemas in WA service operations.
+"""
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field
+
+from ciris_engine.schemas.types import JSONDict
+
+
+class PermissionEntry(BaseModel):
+    """A single permission entry for a WA."""
+
+    action: str = Field(..., description="The action permitted")
+    resource: Optional[str] = Field(None, description="Resource this permission applies to (* for all)")
+    granted_at: str = Field(..., description="ISO timestamp when granted")
+    granted_by: str = Field(..., description="Who granted this permission")
+
+
+class ApprovalRequestContext(BaseModel):
+    """Context for approval requests."""
+
+    wa_id: str = Field(..., description="WA requesting approval")
+    resource: Optional[str] = Field(None, description="Resource being accessed")
+    metadata: Dict[str, str] = Field(default_factory=dict, description="Additional context")
+
+
+class AuthenticationResult(BaseModel):
+    """Result of WA authentication."""
+
+    authenticated: bool = Field(..., description="Whether authentication succeeded")
+    wa_id: str = Field(..., description="Wise Authority identifier")
+    name: str = Field(..., description="WA name")
+    role: str = Field(..., description="WA role")
+    expires_at: datetime = Field(..., description="Token expiration time")
+    permissions: List[str] = Field(default_factory=list, description="Granted permissions")
+    metadata: Dict[str, str] = Field(default_factory=dict, description="Additional metadata")
+
+
+class WAUpdate(BaseModel):
+    """Updates to apply to a WA certificate."""
+
+    name: Optional[str] = Field(None, description="New name")
+    role: Optional[str] = Field(None, description="New role")
+    permissions: Optional[List[str]] = Field(None, description="New permissions")
+    metadata: Optional[Dict[str, str]] = Field(None, description="Metadata updates")
+    is_active: Optional[bool] = Field(None, description="Active status")
+
+
+class TokenVerification(BaseModel):
+    """Result of token verification."""
+
+    valid: bool = Field(..., description="Whether token is valid")
+    wa_id: Optional[str] = Field(None, description="WA ID if valid")
+    name: Optional[str] = Field(None, description="WA name if valid")
+    role: Optional[str] = Field(None, description="WA role if valid")
+    expires_at: Optional[datetime] = Field(None, description="Expiration if valid")
+    error: Optional[str] = Field(None, description="Error message if invalid")
+
+
+class PendingDeferral(BaseModel):
+    """A deferral awaiting WA review."""
+
+    deferral_id: str = Field(..., description="Unique deferral identifier")
+    created_at: datetime = Field(..., description="When deferral was created")
+    deferred_by: str = Field(..., description="Agent that deferred")
+
+    # Deferral details
+    task_id: str = Field(..., description="Associated task ID")
+    thought_id: str = Field(..., description="Associated thought ID")
+    reason: str = Field(..., description="Reason for deferral")
+
+    # Context
+    channel_id: Optional[str] = Field(None, description="Channel where deferred")
+    user_id: Optional[str] = Field(None, description="User involved")
+    priority: str = Field("normal", description="Deferral priority")
+
+    # WA assignment
+    assigned_wa_id: Optional[str] = Field(None, description="Assigned WA if any")
+    requires_role: Optional[str] = Field(None, description="Required WA role")
+
+    # Resolution
+    status: str = Field("pending", description="Current status")
+    resolution: Optional[str] = Field(None, description="Resolution if completed")
+    resolved_at: Optional[datetime] = Field(None, description="Resolution time")
+
+    # UI compatibility fields
+    question: Optional[str] = Field(None, description="Question/description for UI display")
+    context: JSONDict = Field(default_factory=dict, description="Additional context for UI")
+    timeout_at: Optional[str] = Field(None, description="When deferral times out (ISO format)")
+
+
+class DeferralResolution(BaseModel):
+    """Resolution of a deferral by WA."""
+
+    deferral_id: str = Field(..., description="Deferral being resolved")
+    wa_id: str = Field(..., description="WA resolving it")
+    resolution: str = Field(..., description="approve, reject, or modify")
+
+    # Guidance
+    guidance: Optional[str] = Field(None, description="WA guidance")
+    modified_action: Optional[str] = Field(None, description="Modified action if changed")
+    modified_parameters: Optional[Dict[str, Union[str, int, float, bool, List[Any]]]] = Field(
+        None, description="Modified parameters"
+    )
+
+    # Constraints
+    new_constraints: List[str] = Field(default_factory=list, description="New constraints added")
+    removed_constraints: List[str] = Field(default_factory=list, description="Constraints removed")
+
+    # Metadata
+    resolution_time: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    resolution_metadata: Dict[str, str] = Field(default_factory=dict, description="Additional metadata")
+
+
+class WAResource(BaseModel):
+    """Resource accessible to a WA."""
+
+    resource_id: str = Field(..., description="Resource identifier")
+    resource_type: str = Field(..., description="Type of resource")
+    resource_name: str = Field(..., description="Resource name")
+
+    # Access control
+    permissions: List[str] = Field(..., description="Permissions on resource")
+    granted_at: datetime = Field(..., description="When access was granted")
+    granted_by: str = Field(..., description="Who granted access")
+
+    # Constraints
+    expires_at: Optional[datetime] = Field(None, description="Access expiration")
+    usage_limit: Optional[int] = Field(None, description="Usage limit if any")
+    usage_count: int = Field(0, description="Current usage count")
+
+    # Metadata
+    resource_metadata: Dict[str, str] = Field(default_factory=dict, description="Resource metadata")
+
+
+class OAuthConfig(BaseModel):
+    """OAuth provider configuration."""
+
+    provider: str = Field(..., description="OAuth provider name")
+    enabled: bool = Field(True, description="Whether provider is enabled")
+
+    # OAuth settings
+    client_id: str = Field(..., description="OAuth client ID")
+    client_secret: str = Field(..., description="OAuth client secret")
+    redirect_uri: str = Field(..., description="OAuth redirect URI")
+
+    # Scopes and permissions
+    scopes: List[str] = Field(default_factory=list, description="OAuth scopes")
+
+    # Provider-specific settings
+    authorization_url: Optional[str] = Field(None, description="Auth URL if custom")
+    token_url: Optional[str] = Field(None, description="Token URL if custom")
+    userinfo_url: Optional[str] = Field(None, description="User info URL if custom")
+
+    # Mapping
+    id_field: str = Field("id", description="Field for user ID")
+    name_field: str = Field("name", description="Field for user name")
+    email_field: str = Field("email", description="Field for user email")