Merge pull request #103 from bsv-blockchain/feature/middleware_feedback

Feature/middleware feedback

Author: ALiberalVoluntarist

bsv/auth/__init__.py

@@ -0,0 +1,42 @@
+"""
+BSV Authentication Module
+
+This module provides BSV authentication protocol implementation including:
+- Peer: Central authentication protocol implementation
+- SessionManager: Session management
+- Certificate: Certificate handling
+- Transport: Communication layer
+"""
+
+# Export main authentication classes
+from .peer import Peer, PeerOptions, PeerSession
+from .session_manager import SessionManager
+
+# Certificate imports with fallbacks
+try:
+    from .certificate import Certificate
+except (ImportError, AttributeError):
+    Certificate = None  # type: ignore
+
+try:
+    from .verifiable_certificate import VerifiableCertificate
+except (ImportError, AttributeError):
+    # VerifiableCertificate might have different structure
+    VerifiableCertificate = None  # type: ignore
+
+from .requested_certificate_set import RequestedCertificateSet
+from .auth_message import AuthMessage
+from .transports.transport import Transport
+
+__all__ = [
+    'Peer',
+    'PeerOptions',
+    'PeerSession',
+    'SessionManager',
+    'Certificate',
+    'VerifiableCertificate',
+    'RequestedCertificateSet',
+    'AuthMessage',
+    'Transport',
+]
+

bsv/auth/auth_message.py

@@ -4,13 +4,49 @@
 
 
 class AuthMessage:
-    """Represents a message exchanged during the auth protocol."""
+    """
+    Represents a message exchanged during the auth protocol (BRC-103).
+    
+    Required Fields (always):
+        version: Protocol version (e.g., "1.0")
+        message_type: Message type ('initialRequest', 'initialResponse', 'general', etc.)
+        identity_key: Sender's public key for identity verification
+    
+    Conditional Fields (depends on message_type):
+        nonce: Required for 'initialRequest' and 'initialResponse'
+        initial_nonce: Required for 'initialResponse'
+        your_nonce: Required for 'general' messages
+    
+    Optional Fields:
+        certificates: List of verifiable certificates
+        requested_certificates: Set of requested certificate types
+        payload: Message payload data
+        signature: Digital signature of the message
+    
+    Example:
+        >>> # Initial request
+        >>> msg = AuthMessage(
+        ...     version="1.0",
+        ...     message_type="initialRequest",
+        ...     identity_key=public_key,
+        ...     nonce="abc123..."
+        ... )
+        
+        >>> # General message
+        >>> msg = AuthMessage(
+        ...     version="1.0",
+        ...     message_type="general",
+        ...     identity_key=public_key,
+        ...     your_nonce="def456...",
+        ...     payload=b"Hello"
+        ... )
+    """
 
     def __init__(
         self,
-        version: str = "",
-        message_type: str = "",
-        identity_key: Optional[PublicKey] = None,
+        version: str,
+        message_type: str,
+        identity_key: PublicKey,
         nonce: str = "",
         initial_nonce: str = "",
         your_nonce: str = "",
@@ -19,6 +55,39 @@ def __init__(
         payload: Optional[bytes] = None,
         signature: Optional[bytes] = None,
     ):
+        """
+        Initialize an AuthMessage.
+        
+        Args:
+            version: Protocol version (e.g., "1.0") - REQUIRED
+            message_type: Message type - REQUIRED
+                ('initialRequest', 'initialResponse', 'certificateRequest', 
+                 'certificateResponse', 'general')
+            identity_key: Sender's public key - REQUIRED
+            nonce: Sender's nonce (required for initial messages)
+            initial_nonce: Original nonce from initial request (required for response)
+            your_nonce: Recipient's nonce from previous message (required for general)
+            certificates: List of verifiable certificates
+            requested_certificates: Set of requested certificates
+            payload: Message payload data
+            signature: Digital signature of the message
+            
+        Raises:
+            ValueError: If required fields are empty or None
+            
+        Note:
+            This constructor now enforces required fields at instantiation time.
+            If upgrading from previous versions, ensure all required parameters
+            are provided when creating AuthMessage instances.
+        """
+        # Validate required fields
+        if not version:
+            raise ValueError("version is required and cannot be empty")
+        if not message_type:
+            raise ValueError("message_type is required and cannot be empty")
+        if identity_key is None:
+            raise ValueError("identity_key is required and cannot be None")
+        
         self.version = version
         self.message_type = message_type
         self.identity_key = identity_key
@@ -28,4 +97,4 @@ def __init__(
         self.certificates = certificates if certificates is not None else []
         self.requested_certificates = requested_certificates
         self.payload = payload
-        self.signature = signature
+        self.signature = signature