iflow-mcp_enuno-unifi-mcp-server 0.2.1__py3-none-any.whl

src/models/radius.py

@@ -0,0 +1,141 @@
+"""RADIUS profile data models."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class RADIUSProfile(BaseModel):
+    """UniFi RADIUS authentication profile."""
+
+    id: str = Field(..., description="RADIUS profile ID", alias="_id")
+    name: str = Field(..., description="Profile name")
+
+    # Authentication server configuration
+    auth_server: str = Field(..., description="Authentication server IP/hostname")
+    auth_port: int = Field(1812, description="Authentication port")
+    auth_secret: str | None = Field(None, description="Authentication server shared secret")
+
+    # Accounting server configuration (optional)
+    acct_server: str | None = Field(None, description="Accounting server IP/hostname")
+    acct_port: int = Field(1813, description="Accounting port")
+    acct_secret: str | None = Field(None, description="Accounting server shared secret")
+    use_same_secret: bool = Field(True, description="Use auth_secret for accounting")
+
+    # VLAN configuration
+    vlan_enabled: bool = Field(False, description="VLAN assignment enabled")
+    vlan_wlan_mode: str | None = Field(None, description="VLAN mode for WLAN")
+
+    # Advanced settings
+    enabled: bool = Field(True, description="Whether profile is enabled")
+    interim_update_interval: int | None = Field(
+        None, description="Interim accounting update interval (seconds)"
+    )
+    use_usg_accounting_server: bool = Field(False, description="Use USG as accounting proxy")
+
+    # Metadata
+    site_id: str | None = Field(None, description="Site ID")
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_schema_extra={
+            "example": {
+                "_id": "507f191e810c19729de860ea",
+                "name": "Corporate RADIUS",
+                "auth_server": "radius.example.com",
+                "auth_port": 1812,
+                "auth_secret": "secret123",
+                "acct_port": 1813,
+                "enabled": True,
+                "vlan_enabled": True,
+            }
+        },
+    )
+
+
+class RADIUSAccount(BaseModel):
+    """RADIUS user account for guest access."""
+
+    id: str = Field(..., description="Account ID", alias="_id")
+    name: str = Field(..., description="Username")
+    password: str = Field(..., description="Password")
+
+    # Time-based settings
+    enabled: bool = Field(True, description="Account is enabled")
+    start_time: int | None = Field(None, description="Account activation time (Unix timestamp)")
+    end_time: int | None = Field(None, description="Account expiration time (Unix timestamp)")
+
+    # VLAN assignment
+    vlan_id: int | None = Field(None, description="Assigned VLAN ID")
+
+    # Tunnel settings (for WPA2-Enterprise)
+    tunnel_type: int | None = Field(None, description="RADIUS tunnel type")
+    tunnel_medium_type: int | None = Field(None, description="RADIUS tunnel medium type")
+
+    # Metadata
+    site_id: str = Field(..., description="Site ID")
+    note: str | None = Field(None, description="Admin notes")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class GuestPortalConfig(BaseModel):
+    """Guest portal customization configuration."""
+
+    site_id: str = Field(..., description="Site ID")
+
+    # Portal settings
+    enabled: bool = Field(True, description="Guest portal enabled")
+    portal_title: str = Field("Guest WiFi", description="Portal page title")
+    redirect_enabled: bool = Field(False, description="Redirect after authentication")
+    redirect_url: str | None = Field(None, description="Redirect URL")
+
+    # Authentication method
+    auth_method: Literal["none", "password", "voucher", "radius", "external"] = Field(
+        "voucher", description="Authentication method"
+    )
+    password: str | None = Field(None, description="Portal password (if auth_method=password)")
+
+    # Terms of service
+    terms_of_service_enabled: bool = Field(False, description="Require ToS acceptance")
+    terms_of_service_text: str | None = Field(None, description="Terms of service text")
+
+    # Session limits
+    session_timeout: int = Field(480, description="Session timeout in minutes (0=unlimited)")
+    download_limit_kbps: int | None = Field(None, description="Download speed limit in kbps")
+    upload_limit_kbps: int | None = Field(None, description="Upload speed limit in kbps")
+
+    # Customization
+    background_image_url: str | None = Field(None, description="Background image URL")
+    logo_url: str | None = Field(None, description="Logo image URL")
+    custom_css: str | None = Field(None, description="Custom CSS")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class HotspotPackage(BaseModel):
+    """Hotspot package with time and bandwidth limits."""
+
+    id: str = Field(..., description="Package ID", alias="_id")
+    name: str = Field(..., description="Package name")
+
+    # Time limits
+    duration_minutes: int = Field(..., description="Duration in minutes")
+
+    # Bandwidth limits
+    download_limit_kbps: int | None = Field(None, description="Download speed limit in kbps")
+    upload_limit_kbps: int | None = Field(None, description="Upload speed limit in kbps")
+
+    # Data quotas
+    download_quota_mb: int | None = Field(None, description="Download quota in MB")
+    upload_quota_mb: int | None = Field(None, description="Upload quota in MB")
+
+    # Pricing (for payment gateway integration)
+    price: float | None = Field(None, description="Package price")
+    currency: str = Field("USD", description="Currency code")
+
+    # Metadata
+    enabled: bool = Field(True, description="Package is available")
+    site_id: str = Field(..., description="Site ID")
+
+    model_config = ConfigDict(populate_by_name=True)

src/models/reference_data.py

@@ -0,0 +1,34 @@
+"""Reference data models for supporting resources."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DeviceTag(BaseModel):
+    """UniFi device tag for WiFi broadcast assignments."""
+
+    id: str = Field(..., description="Tag ID", alias="_id")
+    name: str = Field(..., description="Tag name")
+    devices: list[str] | None = Field(None, description="Associated device IDs")
+    site_id: str | None = Field(None, description="Site ID")
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_schema_extra={
+            "example": {
+                "_id": "507f191e810c19729de860ea",
+                "name": "Guest WiFi APs",
+                "devices": ["device-id-1", "device-id-2"],
+            }
+        },
+    )
+
+
+class Country(BaseModel):
+    """ISO country code and name."""
+
+    code: str = Field(..., description="ISO 3166-1 alpha-2 country code")
+    name: str = Field(..., description="Country name")
+
+    model_config = ConfigDict(
+        json_schema_extra={"example": {"code": "US", "name": "United States"}}
+    )

src/models/site.py

@@ -0,0 +1,59 @@
+"""Site data model."""
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, model_validator
+
+
+class Site(BaseModel):
+    """UniFi site information (compatible with Cloud and Local API)."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        extra="allow",  # Allow extra fields from Cloud API
+        json_schema_extra={
+            "example": {
+                "_id": "default",
+                "name": "Default Site",
+                "desc": "Default site description",
+            }
+        },
+    )
+
+    id: str = Field(
+        ...,
+        description="Site ID",
+        alias="_id",
+        validation_alias=AliasChoices("_id", "siteId", "id"),
+    )
+
+    name: str | None = Field(
+        None,
+        description="Site name",
+        validation_alias=AliasChoices("name", "siteName"),
+    )
+
+    desc: str | None = Field(
+        None,
+        description="Site description",
+        validation_alias=AliasChoices("desc", "description"),
+    )
+
+    # Cloud API specific fields
+    is_owner: bool | None = Field(
+        None, alias="isOwner", description="Whether user owns the site (Cloud API)"
+    )
+
+    # Optional metadata fields (Local API)
+    attr_hidden_id: str | None = Field(None, description="Hidden ID attribute")
+    attr_no_delete: bool | None = Field(None, description="Whether site can be deleted")
+    role: str | None = Field(None, description="Site role")
+
+    @model_validator(mode="after")
+    def set_name_fallback(self) -> "Site":
+        """Set name from ID if not provided (Cloud API compatibility).
+
+        Returns:
+            The Site instance with name populated
+        """
+        if self.name is None or self.name == "":
+            self.name = f"Site {self.id}"
+        return self

src/models/site_manager.py

@@ -0,0 +1,120 @@
+"""Site Manager API models."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class SiteHealthSummary(BaseModel):
+    """Health status for a site."""
+
+    site_id: str = Field(..., description="Site identifier")
+    site_name: str = Field(..., description="Site name")
+    status: Literal["healthy", "degraded", "down"] = Field(..., description="Health status")
+    devices_online: int = Field(0, description="Number of online devices")
+    devices_total: int = Field(0, description="Total number of devices")
+    clients_active: int = Field(0, description="Number of active clients")
+    uptime_percentage: float = Field(0.0, description="Uptime percentage")
+    last_updated: str = Field(..., description="Last update timestamp (ISO)")
+
+
+class InternetHealthMetrics(BaseModel):
+    """Internet connectivity metrics."""
+
+    site_id: str | None = Field(None, description="Site identifier (None for aggregate)")
+    latency_ms: float | None = Field(None, description="Average latency in milliseconds")
+    packet_loss_percent: float = Field(0.0, description="Packet loss percentage")
+    jitter_ms: float | None = Field(None, description="Jitter in milliseconds")
+    bandwidth_up_mbps: float | None = Field(None, description="Upload bandwidth in Mbps")
+    bandwidth_down_mbps: float | None = Field(None, description="Download bandwidth in Mbps")
+    status: Literal["healthy", "degraded", "down"] = Field(..., description="Health status")
+    last_tested: str = Field(..., description="Last test timestamp (ISO)")
+
+
+class CrossSiteStatistics(BaseModel):
+    """Aggregated statistics across multiple sites."""
+
+    total_sites: int = Field(0, description="Total number of sites")
+    sites_healthy: int = Field(0, description="Number of healthy sites")
+    sites_degraded: int = Field(0, description="Number of degraded sites")
+    sites_down: int = Field(0, description="Number of down sites")
+    total_devices: int = Field(0, description="Total number of devices")
+    devices_online: int = Field(0, description="Total online devices")
+    total_clients: int = Field(0, description="Total number of clients")
+    total_bandwidth_up_mbps: float = Field(0.0, description="Total upload bandwidth")
+    total_bandwidth_down_mbps: float = Field(0.0, description="Total download bandwidth")
+    site_summaries: list[SiteHealthSummary] = Field(
+        default_factory=list, description="Health summary for each site"
+    )
+
+
+class VantagePoint(BaseModel):
+    """Vantage Point information."""
+
+    vantage_point_id: str = Field(..., description="Vantage Point identifier")
+    name: str = Field(..., description="Vantage Point name")
+    location: str | None = Field(None, description="Location")
+    latitude: float | None = Field(None, description="Latitude")
+    longitude: float | None = Field(None, description="Longitude")
+    status: Literal["active", "inactive"] = Field(..., description="Status")
+    site_ids: list[str] = Field(default_factory=list, description="Associated site IDs")
+
+
+class SiteInventory(BaseModel):
+    """Comprehensive inventory for a single site."""
+
+    site_id: str = Field(..., description="Site identifier")
+    site_name: str = Field(..., description="Site name")
+    device_count: int = Field(0, description="Total devices")
+    device_types: dict[str, int] = Field(default_factory=dict, description="Count by device type")
+    client_count: int = Field(0, description="Total active clients")
+    network_count: int = Field(0, description="Total networks/VLANs")
+    ssid_count: int = Field(0, description="Total SSIDs")
+    uplink_count: int = Field(0, description="Total WAN uplinks")
+    vpn_tunnel_count: int = Field(0, description="Total VPN tunnels")
+    firewall_rule_count: int = Field(0, description="Total firewall rules")
+    last_updated: str = Field(..., description="Inventory timestamp (ISO)")
+
+
+class SitePerformanceMetrics(BaseModel):
+    """Performance metrics for a single site."""
+
+    site_id: str = Field(..., description="Site identifier")
+    site_name: str = Field(..., description="Site name")
+    avg_latency_ms: float | None = Field(None, description="Average latency")
+    avg_bandwidth_up_mbps: float | None = Field(None, description="Average upload bandwidth")
+    avg_bandwidth_down_mbps: float | None = Field(None, description="Average download bandwidth")
+    uptime_percentage: float = Field(0.0, description="Uptime percentage")
+    device_online_percentage: float = Field(0.0, description="Percentage of devices online")
+    client_count: int = Field(0, description="Active clients")
+    health_status: Literal["healthy", "degraded", "down"] = Field(..., description="Overall status")
+
+
+class CrossSitePerformanceComparison(BaseModel):
+    """Performance comparison across multiple sites."""
+
+    total_sites: int = Field(0, description="Number of sites compared")
+    best_performing_site: SitePerformanceMetrics | None = Field(
+        None, description="Site with best overall performance"
+    )
+    worst_performing_site: SitePerformanceMetrics | None = Field(
+        None, description="Site with worst overall performance"
+    )
+    average_uptime: float = Field(0.0, description="Average uptime across all sites")
+    average_latency_ms: float | None = Field(None, description="Average latency across sites")
+    site_metrics: list[SitePerformanceMetrics] = Field(
+        default_factory=list, description="Metrics for each site"
+    )
+
+
+class CrossSiteSearchResult(BaseModel):
+    """Search result from cross-site search."""
+
+    total_results: int = Field(0, description="Total number of results found")
+    search_query: str = Field(..., description="Original search query")
+    result_type: Literal["device", "client", "network", "all"] = Field(
+        ..., description="Type of results"
+    )
+    results: list[dict] = Field(
+        default_factory=list, description="Search results with site context"
+    )

src/models/topology.py

@@ -0,0 +1,138 @@
+"""Network topology data models."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TopologyNode(BaseModel):
+    """A node in the network topology (device, client, or network)."""
+
+    node_id: str = Field(..., description="Unique node identifier")
+    node_type: Literal["device", "client", "network"] = Field(..., description="Type of node")
+    name: str | None = Field(None, description="Node name")
+    mac: str | None = Field(None, description="MAC address (for devices/clients)")
+    ip: str | None = Field(None, description="IP address")
+    model: str | None = Field(None, description="Device model (for devices)")
+    type_detail: str | None = Field(None, description="Device type detail (uap, usw, ugw, etc.)")
+
+    # Position and connectivity
+    uplink_device_id: str | None = Field(
+        None, description="ID of uplink device this node connects to"
+    )
+    uplink_port: int | None = Field(None, description="Uplink port number")
+    uplink_depth: int | None = Field(0, description="Depth in network hierarchy (0=gateway)")
+
+    # Status
+    state: int | None = Field(None, description="Node state (0=offline, 1=online)")
+    adopted: bool | None = Field(None, description="Whether device is adopted")
+
+    # Coordinates for visualization
+    x_coordinate: float | None = Field(None, description="X coordinate for layout")
+    y_coordinate: float | None = Field(None, description="Y coordinate for layout")
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_schema_extra={
+            "example": {
+                "node_id": "507f1f77bcf86cd799439011",
+                "node_type": "device",
+                "name": "AP-Office",
+                "mac": "aa:bb:cc:dd:ee:ff",
+                "ip": "192.168.1.10",
+                "model": "U6-LR",
+                "type_detail": "uap",
+                "uplink_device_id": "507f1f77bcf86cd799439012",
+                "uplink_port": 5,
+                "uplink_depth": 1,
+                "state": 1,
+                "adopted": True,
+            }
+        },
+    )
+
+
+class TopologyConnection(BaseModel):
+    """A connection between two nodes in the network topology."""
+
+    connection_id: str = Field(..., description="Unique connection identifier")
+    source_node_id: str = Field(..., description="Source node ID")
+    target_node_id: str = Field(..., description="Target node ID")
+    connection_type: Literal["wired", "wireless", "uplink"] = Field(
+        ..., description="Type of connection"
+    )
+
+    # Port information
+    source_port: int | None = Field(None, description="Source port number")
+    target_port: int | None = Field(None, description="Target port number")
+    port_name: str | None = Field(None, description="Port name/description")
+
+    # Connection quality
+    speed_mbps: int | None = Field(None, description="Connection speed in Mbps")
+    duplex: str | None = Field(None, description="Duplex mode (full/half)")
+    link_quality: int | None = Field(None, description="Link quality percentage (0-100)")
+
+    # Status
+    status: str | None = Field(None, description="Connection status (up/down)")
+    is_uplink: bool = Field(False, description="Whether this is an uplink connection")
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_schema_extra={
+            "example": {
+                "connection_id": "conn_001",
+                "source_node_id": "507f1f77bcf86cd799439011",
+                "target_node_id": "507f1f77bcf86cd799439012",
+                "connection_type": "wired",
+                "source_port": 5,
+                "target_port": 1,
+                "speed_mbps": 1000,
+                "duplex": "full",
+                "link_quality": 100,
+                "status": "up",
+                "is_uplink": True,
+            }
+        },
+    )
+
+
+class NetworkDiagram(BaseModel):
+    """Complete network topology structure."""
+
+    site_id: str = Field(..., description="Site identifier")
+    site_name: str | None = Field(None, description="Site name")
+    generated_at: str = Field(..., description="Timestamp when topology was generated (ISO)")
+
+    # Topology data
+    nodes: list[TopologyNode] = Field(default_factory=list, description="All nodes in the topology")
+    connections: list[TopologyConnection] = Field(
+        default_factory=list, description="All connections between nodes"
+    )
+
+    # Summary statistics
+    total_devices: int = Field(0, description="Total number of devices")
+    total_clients: int = Field(0, description="Total number of clients")
+    total_connections: int = Field(0, description="Total number of connections")
+    max_depth: int = Field(0, description="Maximum depth in network hierarchy")
+
+    # Layout metadata
+    layout_algorithm: str | None = Field(None, description="Algorithm used for node positioning")
+    has_coordinates: bool = Field(False, description="Whether nodes have position coordinates")
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_schema_extra={
+            "example": {
+                "site_id": "507f1f77bcf86cd799439013",
+                "site_name": "Default",
+                "generated_at": "2025-01-24T12:00:00Z",
+                "nodes": [],
+                "connections": [],
+                "total_devices": 5,
+                "total_clients": 12,
+                "total_connections": 16,
+                "max_depth": 3,
+                "has_coordinates": False,
+            }
+        },
+    )

src/models/traffic_flow.py

@@ -0,0 +1,137 @@
+"""Traffic flow models."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class TrafficFlow(BaseModel):
+    """Individual traffic flow record."""
+
+    flow_id: str = Field(..., description="Flow identifier")
+    site_id: str = Field(..., description="Site identifier")
+    source_ip: str = Field(..., description="Source IP address")
+    source_port: int | None = Field(None, description="Source port")
+    destination_ip: str = Field(..., description="Destination IP address")
+    destination_port: int | None = Field(None, description="Destination port")
+    protocol: str = Field(..., description="Protocol (tcp/udp/icmp)")
+    application_id: str | None = Field(None, description="DPI application identifier")
+    application_name: str | None = Field(None, description="Application name")
+    bytes_sent: int = Field(0, description="Bytes sent")
+    bytes_received: int = Field(0, description="Bytes received")
+    packets_sent: int = Field(0, description="Packets sent")
+    packets_received: int = Field(0, description="Packets received")
+    start_time: str = Field(..., description="Flow start timestamp (ISO)")
+    end_time: str | None = Field(None, description="Flow end timestamp (ISO)")
+    duration: int | None = Field(None, description="Flow duration in seconds")
+    client_mac: str | None = Field(None, description="Client MAC address")
+    device_id: str | None = Field(None, description="Device identifier")
+
+
+class FlowStatistics(BaseModel):
+    """Aggregated flow statistics."""
+
+    site_id: str = Field(..., description="Site identifier")
+    time_range: str = Field(..., description="Time range for statistics")
+    total_flows: int = Field(0, description="Total number of flows")
+    total_bytes_sent: int = Field(0, description="Total bytes sent")
+    total_bytes_received: int = Field(0, description="Total bytes received")
+    total_bytes: int = Field(0, description="Total bytes")
+    total_packets_sent: int = Field(0, description="Total packets sent")
+    total_packets_received: int = Field(0, description="Total packets received")
+    unique_sources: int = Field(0, description="Number of unique source IPs")
+    unique_destinations: int = Field(0, description="Number of unique destination IPs")
+    top_applications: list[dict] = Field(
+        default_factory=list, description="Top applications by bandwidth"
+    )
+
+
+class FlowRisk(BaseModel):
+    """Risk assessment data for a flow."""
+
+    flow_id: str = Field(..., description="Flow identifier")
+    risk_score: float = Field(..., description="Risk score (0-100)")
+    risk_level: Literal["low", "medium", "high", "critical"] = Field(..., description="Risk level")
+    indicators: list[str] = Field(default_factory=list, description="List of risk indicators")
+    threat_type: str | None = Field(None, description="Type of threat detected")
+    description: str | None = Field(None, description="Risk description")
+
+
+class FlowView(BaseModel):
+    """Saved flow view configuration."""
+
+    view_id: str = Field(..., description="View identifier")
+    site_id: str = Field(..., description="Site identifier")
+    name: str = Field(..., description="View name")
+    description: str | None = Field(None, description="View description")
+    filter_expression: str | None = Field(None, description="Filter expression")
+    time_range: str = Field("24h", description="Time range")
+    created_at: str = Field(..., description="Creation timestamp (ISO)")
+
+
+class FlowStreamUpdate(BaseModel):
+    """Real-time flow update for streaming."""
+
+    update_type: Literal["new", "update", "closed"] = Field(..., description="Update type")
+    flow: TrafficFlow = Field(..., description="Flow data")
+    timestamp: str = Field(..., description="Update timestamp (ISO)")
+    bandwidth_rate: dict[str, float] | None = Field(
+        None, description="Current bandwidth rates (bps)"
+    )
+
+
+class ConnectionState(BaseModel):
+    """Connection state tracking."""
+
+    flow_id: str = Field(..., description="Flow identifier")
+    state: Literal["active", "closed", "timed_out"] = Field(..., description="Connection state")
+    last_seen: str = Field(..., description="Last activity timestamp (ISO)")
+    total_duration: int | None = Field(None, description="Total duration in seconds")
+    termination_reason: str | None = Field(None, description="Reason for connection closure")
+
+
+class ClientFlowAggregation(BaseModel):
+    """Client traffic aggregation with enhanced metrics."""
+
+    client_mac: str = Field(..., description="Client MAC address")
+    client_ip: str | None = Field(None, description="Client IP address")
+    site_id: str = Field(..., description="Site identifier")
+    total_flows: int = Field(0, description="Total number of flows")
+    total_bytes: int = Field(0, description="Total bytes transferred")
+    total_packets: int = Field(0, description="Total packets transferred")
+    active_flows: int = Field(0, description="Currently active flows")
+    closed_flows: int = Field(0, description="Closed flows")
+    auth_failures: int = Field(0, description="Authentication failure count")
+    top_applications: list[dict] = Field(
+        default_factory=list, description="Top applications by bandwidth"
+    )
+    top_destinations: list[dict] = Field(default_factory=list, description="Top destination IPs")
+
+
+class FlowExportConfig(BaseModel):
+    """Configuration for flow export."""
+
+    export_format: Literal["csv", "json", "pcap"] = Field(..., description="Export format")
+    time_range: str = Field(..., description="Time range for export")
+    include_fields: list[str] | None = Field(
+        None, description="Specific fields to include (None = all)"
+    )
+    filter_expression: str | None = Field(None, description="Filter expression")
+    max_records: int | None = Field(None, description="Maximum number of records")
+
+
+class BlockFlowAction(BaseModel):
+    """Result of a flow block action."""
+
+    action_id: str = Field(..., description="Block action identifier")
+    block_type: Literal["source_ip", "destination_ip", "application"] = Field(
+        ..., description="Type of block"
+    )
+    blocked_target: str = Field(..., description="Blocked IP or application ID")
+    rule_id: str | None = Field(None, description="Created firewall rule ID")
+    zone_id: str | None = Field(None, description="Zone ID if using ZBF")
+    duration: Literal["permanent", "temporary"] | None = Field(
+        None, description="Block duration type"
+    )
+    expires_at: str | None = Field(None, description="Expiration timestamp for temporary blocks")
+    created_at: str = Field(..., description="Creation timestamp (ISO)")