models.py

"""
Federation Node — Data Models & Enums
======================================
Contract: C-FED-NODE-001 v0.1.1

Refusal reason codes (§7.4), delivery statuses (§9.3),
trust tiers (§7), and request/response schemas.
"""
from __future__ import annotations

from datetime import datetime, timezone
from enum import Enum
from typing import Optional

from pydantic import BaseModel, Field


# ─── Refusal Reason Codes (§7.4) ───

class RefusalReason(str, Enum):
    """Structured refusal reason codes per C-FED-NODE-001 §7.4."""
    UNSUPPORTED_PROTOCOL_VERSION = "UNSUPPORTED_PROTOCOL_VERSION"
    UNSUPPORTED_MESSAGE_CLASS = "UNSUPPORTED_MESSAGE_CLASS"
    INVALID_DELEGATION = "INVALID_DELEGATION"
    SENDER_NOT_TRUSTED = "SENDER_NOT_TRUSTED"
    SENDER_BLOCKED = "SENDER_BLOCKED"
    MALFORMED_ENVELOPE = "MALFORMED_ENVELOPE"
    QUARANTINED = "QUARANTINED"
    REFUSED_BY_POLICY = "REFUSED_BY_POLICY"
    PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE"
    RATE_LIMITED = "RATE_LIMITED"
    INBOX_FULL = "INBOX_FULL"


# ─── Delivery Statuses (§9.3) ───

class DeliveryStatus(str, Enum):
    """Envelope delivery status progression per C-FED-NODE-001 §9.3."""
    RECEIVED = "RECEIVED"
    VALIDATED = "VALIDATED"
    REJECTED = "REJECTED"
    QUEUED = "QUEUED"
    QUARANTINED = "QUARANTINED"
    DELIVERED = "DELIVERED"
    READ = "READ"
    PROCESSED = "PROCESSED"
    WITNESSED = "WITNESSED"
    EXPIRED = "EXPIRED"


# ─── Trust Tiers (§7.2) ───

class TrustTier(str, Enum):
    TRUSTED = "TRUSTED"
    KNOWN = "KNOWN"
    UNKNOWN = "UNKNOWN"
    BLOCKED = "BLOCKED"


# ─── Refusal Response Model ───

class FederationRefusal(BaseModel):
    """Structured refusal response per C-FED-NODE-001 §7.4."""
    refusal: bool = True
    reason: RefusalReason
    message: str
    node_seal: str
    timestamp: str


# ─── Request Models ───

class HandshakeRequest(BaseModel):
    """Incoming handshake from another node."""
    caller_seal: str = Field(..., description="The Glyph-Seal of the caller")
    protocol: str = Field(default="C-FED-001", description="Protocol version")
    message: Optional[str] = Field(default=None, description="Optional signal payload")


class HandshakeResponse(BaseModel):
    """Response to a handshake."""
    node_seal: str
    link_seal: str
    status: str
    message: str
    timestamp: str


class VerifyRequest(BaseModel):
    """Request to verify a seal string."""
    seal: str


class MintRequest(BaseModel):
    """Request to mint a new seal."""
    class_name: str = Field(..., description="NODE, LAW, LINK, RITE, ART, WIT")
    origin: str = Field(..., description="Origin namespace")
    state: str = Field(default="VALID")
    mode: str = Field(default="hybrid", description="random | hybrid | deterministic")
    material: Optional[str] = Field(default=None, description="For deterministic mode")


class EnvelopeSubmission(BaseModel):
    """Incoming envelope per C-FED-NODE-001 §9.1."""
    protocol_version: str = Field(default="1.0.0")
    message_class: str = Field(..., description="Message class (THOUGHT, PROPOSAL, etc.)")
    sender: dict = Field(..., description="Sender block: {seal, delegation_token?}")
    recipient: dict = Field(..., description="Recipient block: {seal}")
    payload: dict = Field(..., description="Payload block: {content_type, body, ...}")
    delivery: dict = Field(default_factory=lambda: {"ttl_seconds": 86400, "priority": "normal"})
    signature: Optional[dict] = Field(default=None, description="Signature block (Phase 3)")