wirekx 0.1.0__py3-none-any.whl

wirekx/__init__.py

@@ -0,0 +1,880 @@
+"""Experimental wirekx v1 anonymous key exchange library."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+from dataclasses import dataclass
+from enum import Enum, IntEnum
+from typing import Optional
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import x25519
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+
+__version__ = "0.1.0"
+
+VERSION = 0x01
+HEADER_LEN = 4
+PUBLIC_KEY_LEN = 32
+NONCE_LEN = 32
+VERIFY_DATA_LEN = 32
+SYMMETRIC_KEY_LEN = 32
+MAX_PAYLOAD_LEN = 0xFFFF
+HELLO_PAYLOAD_LEN = PUBLIC_KEY_LEN + NONCE_LEN
+CONFIRM_PAYLOAD_LEN = VERIFY_DATA_LEN
+
+SESSION_INFO = b"wirekx v1 session key"
+INITIATOR_CONFIRM_LABEL = b"wirekx v1 initiator confirm"
+RESPONDER_CONFIRM_LABEL = b"wirekx v1 responder confirm"
+
+
+class MessageType(IntEnum):
+    """Wire message type codes."""
+
+    HELLO = 0x01
+    HELLO_BACK = 0x02
+    CONFIRM = 0x03
+
+
+class Role(IntEnum):
+    """Local role in the anonymous handshake."""
+
+    INITIATOR = 1
+    RESPONDER = 2
+
+
+class ProtectionLevel(str, Enum):
+    """Peer-authentication strength of a completed handshake."""
+
+    OPPORTUNISTIC = "opportunistic"
+    AUTHENTICATED = "authenticated"
+
+
+class WireKXError(Exception):
+    """Base error for handshake failures."""
+
+    def __init__(self, message: str, *, reason: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.reason = reason
+
+
+class MalformedMessage(WireKXError):
+    """Raised when bytes cannot be parsed according to the wire format."""
+
+
+class UnexpectedMessage(WireKXError):
+    """Raised when a valid message arrives in the wrong handshake state."""
+
+
+class VerificationFailed(WireKXError):
+    """Raised when confirm verify_data does not match."""
+
+
+@dataclass(frozen=True)
+class Envelope:
+    """Decoded envelope header plus raw payload."""
+
+    msg_type: MessageType
+    payload: bytes
+
+
+@dataclass(frozen=True)
+class HelloPayload:
+    """Payload shared by HELLO and HELLO_BACK."""
+
+    eph_pub: bytes
+    nonce: bytes
+
+
+@dataclass(frozen=True)
+class ConfirmPayload:
+    """Payload for CONFIRM."""
+
+    verify_data: bytes
+
+
+@dataclass(frozen=True)
+class HandshakeResult:
+    """Returned only after both CONFIRM messages verify."""
+
+    symmetric_key: bytes
+    transcript_hash: bytes
+    protection_level: ProtectionLevel = ProtectionLevel.OPPORTUNISTIC
+    peer_identity: Optional[bytes] = None
+
+
+@dataclass
+class HandshakeState:
+    """
+    Mutable per-handshake state.
+
+    Keep ephemeral private keys in this object only while needed, clear
+    all references after deriving the symmetric key.
+    """
+
+    role: Role
+    own_private_key: object | None = None
+    own_public_key: bytes | None = None
+    peer_public_key: bytes | None = None
+    own_nonce: bytes | None = None
+    peer_nonce: bytes | None = None
+    hello_bytes: bytes | None = None
+    hello_back_bytes: bytes | None = None
+    symmetric_key: bytes | None = None
+    transcript_hash: bytes | None = None
+    peer_confirm_verified: bool = False
+    own_confirm_sent: bool = False
+
+
+def encode_envelope(msg_type: MessageType, payload: bytes) -> bytes:
+    """
+    Build VERSION || msg_type || payload_len_be || payload.
+
+    Pseudocode:
+    - Reject payloads longer than MAX_PAYLOAD_LEN.
+    - Convert len(payload) to 2 big-endian bytes.
+    - Return bytes([VERSION, msg_type]) + length_bytes + payload.
+    """
+
+    if not isinstance(msg_type, MessageType):
+        try:
+            msg_type = MessageType(msg_type)
+        except ValueError:
+            raise MalformedMessage(
+                "unknown message type",
+                reason=f"message type {msg_type} is not allowed",
+            )
+
+    if len(payload) > MAX_PAYLOAD_LEN:
+        raise MalformedMessage(
+            "payload too large",
+            reason="payload length must fit in a 2-byte unsigned integer",
+        )
+
+    length_bytes = len(payload).to_bytes(2, "big")
+    return bytes([VERSION, msg_type]) + length_bytes + payload
+
+
+
+def decode_envelope(message: bytes) -> Envelope:
+    """
+    Parse and validate the 4-byte envelope header.
+
+    Pseudocode:
+    - Require at least HEADER_LEN bytes.
+    - Read version, msg_type, and 2-byte big-endian payload length.
+    - Require version == VERSION.
+    - Require msg_type is one of MessageType.
+    - Require remaining bytes exactly match payload_len.
+    - Return Envelope(msg_type=MessageType(msg_type), payload=payload).
+    """
+
+    if len(message) < HEADER_LEN:
+        raise MalformedMessage(
+            "Payload malformed",
+            reason="Payload less than minimum length"
+        )
+
+    version = message[0]
+    msg_type_raw = message[1]
+    payload_len = int.from_bytes(message[2:4], "big")
+    payload = message[4:]
+    
+    if version != VERSION:
+        raise MalformedMessage(
+            "unsupported version",
+            reason=f"expected version {VERSION}, got {version}"
+        )
+    
+    try:
+        msg_type = MessageType(msg_type_raw)
+    except ValueError:
+        raise MalformedMessage(
+            "unknown message type",
+            reason=f"message type {msg_type_raw} is not allowed"
+        )
+    
+    if len(payload) != payload_len:
+        raise MalformedMessage(
+            "payload length mismatch",
+            reason=f"header says {payload_len} bytes, got {len(payload)} bytes"
+        )
+    
+    return Envelope(msg_type=msg_type, payload=payload)
+        
+
+def encode_hello_payload(eph_pub: bytes, nonce: bytes) -> bytes:
+    """
+    Build eph_pub || nonce for HELLO or HELLO_BACK.
+
+    Pseudocode:
+    - Require eph_pub is 32 bytes.
+    - Require nonce is 32 bytes.
+    - Return eph_pub + nonce.
+    """
+    
+    if len(eph_pub) != PUBLIC_KEY_LEN:
+        raise MalformedMessage(
+            "public key length mismatch",
+            reason=f"expected {PUBLIC_KEY_LEN} bytes, got {len(eph_pub)} bytes",
+        )
+
+    if len(nonce) != NONCE_LEN:
+        raise MalformedMessage(
+            "nonce length mismatch",
+            reason=f"expected {NONCE_LEN} bytes, got {len(nonce)} bytes",
+        )
+
+    return eph_pub + nonce
+
+
+def decode_hello_payload(payload: bytes) -> HelloPayload:
+    """
+    Parse eph_pub || nonce.
+
+    Pseudocode:
+    - Require payload length is PUBLIC_KEY_LEN + NONCE_LEN.
+    - Split first 32 bytes as eph_pub.
+    - Split next 32 bytes as nonce.
+    - Return HelloPayload(eph_pub, nonce).
+    """
+
+    if len(payload) != HELLO_PAYLOAD_LEN:
+        raise MalformedMessage(
+            "invalid HELLO payload length",
+            reason=f"expected {HELLO_PAYLOAD_LEN} bytes, got {len(payload)} bytes",
+        )
+    
+    eph_pub = payload[:PUBLIC_KEY_LEN]
+    nonce = payload[PUBLIC_KEY_LEN:]
+    
+    return HelloPayload(eph_pub=eph_pub, nonce=nonce)
+
+
+def encode_confirm_payload(verify_data: bytes) -> bytes:
+    """
+    Build the 32-byte CONFIRM payload.
+
+    Pseudocode:
+    - Require verify_data is VERIFY_DATA_LEN bytes.
+    - Return verify_data unchanged.
+    """
+
+    if len(verify_data) != VERIFY_DATA_LEN:
+        raise MalformedMessage(
+            "invalid verify_data length",
+            reason=f"expected {VERIFY_DATA_LEN} bytes, got {len(verify_data)} bytes",
+        )
+
+    return verify_data
+
+
+def decode_confirm_payload(payload: bytes) -> ConfirmPayload:
+    """
+    Parse the 32-byte CONFIRM payload.
+
+    Pseudocode:
+    - Require payload length is VERIFY_DATA_LEN.
+    - Return ConfirmPayload(verify_data=payload).
+    """
+
+    if len(payload) != CONFIRM_PAYLOAD_LEN:
+        raise MalformedMessage(
+            "invalid CONFIRM payload length",
+            reason=f"expected {CONFIRM_PAYLOAD_LEN} bytes, got {len(payload)} bytes",
+        )
+
+    return ConfirmPayload(verify_data=payload)
+
+
+def generate_ephemeral_keypair() -> tuple[x25519.X25519PrivateKey, bytes]:
+    """
+    Generate a fresh X25519 private key and raw 32-byte public key.
+
+    Pseudocode:
+    - private_key = x25519.X25519PrivateKey.generate()
+    - public_key = private_key.public_key()
+    - public_bytes = public_key.public_bytes(Encoding.Raw, PublicFormat.Raw)
+    - Return private_key, public_bytes.
+    """
+
+    private_key = x25519.X25519PrivateKey.generate()
+    public_bytes = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+    return private_key, public_bytes
+
+
+def generate_nonce() -> bytes:
+    """
+    Generate 32 random bytes.
+
+    Pseudocode:
+    - Return secrets.token_bytes(NONCE_LEN).
+    """
+
+    return secrets.token_bytes(NONCE_LEN)
+
+
+def load_peer_public_key(raw_public_key: bytes) -> x25519.X25519PublicKey:
+    """
+    Convert a raw 32-byte X25519 public key into a cryptography key object.
+
+    Pseudocode:
+    - Require raw_public_key length is PUBLIC_KEY_LEN.
+    - Return x25519.X25519PublicKey.from_public_bytes(raw_public_key).
+    """
+
+    if len(raw_public_key) != PUBLIC_KEY_LEN:
+        raise MalformedMessage(
+            "invalid public key length",
+            reason=f"expected {PUBLIC_KEY_LEN} bytes, got {len(raw_public_key)} bytes",
+        )
+
+    return x25519.X25519PublicKey.from_public_bytes(raw_public_key)
+
+
+def derive_shared_secret(
+    own_private_key: x25519.X25519PrivateKey,
+    peer_public_key_bytes: bytes,
+) -> bytes:
+    """
+    Run X25519(own_eph_priv, peer_eph_pub).
+
+    Pseudocode:
+    - peer_key = load_peer_public_key(peer_public_key_bytes)
+    - Return own_private_key.exchange(peer_key).
+    """
+
+    peer_key = load_peer_public_key(peer_public_key_bytes)
+    return own_private_key.exchange(peer_key)
+
+
+def derive_symmetric_key(
+    shared_secret: bytes,
+    nonce_a: bytes,
+    nonce_b: bytes,
+) -> bytes:
+    """
+    Derive the 32-byte session key with HKDF-SHA256.
+
+    Pseudocode:
+    - salt = nonce_a + nonce_b, always initiator nonce first.
+    - Use HKDF(algorithm=SHA256, length=32, salt=salt, info=SESSION_INFO).
+    - Return hkdf.derive(shared_secret).
+    """
+
+    if len(shared_secret) != SYMMETRIC_KEY_LEN:
+        raise MalformedMessage(
+            "invalid shared secret length",
+            reason=f"expected {SYMMETRIC_KEY_LEN} bytes, got {len(shared_secret)} bytes",
+        )
+
+    if len(nonce_a) != NONCE_LEN:
+        raise MalformedMessage(
+            "invalid initiator nonce length",
+            reason=f"expected {NONCE_LEN} bytes, got {len(nonce_a)} bytes",
+        )
+
+    if len(nonce_b) != NONCE_LEN:
+        raise MalformedMessage(
+            "invalid responder nonce length",
+            reason=f"expected {NONCE_LEN} bytes, got {len(nonce_b)} bytes",
+        )
+
+    hkdf = HKDF(
+        algorithm=hashes.SHA256(),
+        length=SYMMETRIC_KEY_LEN,
+        salt=nonce_a + nonce_b,
+        info=SESSION_INFO,
+    )
+    return hkdf.derive(shared_secret)
+
+
+def compute_transcript_hash(hello_bytes: bytes, hello_back_bytes: bytes) -> bytes:
+    """
+    Compute SHA-256(HELLO_bytes || HELLO_BACK_bytes).
+
+    Pseudocode:
+    - Hash the exact encoded envelope bytes sent on the wire.
+    - Return 32-byte digest.
+    """
+
+    return hashlib.sha256(hello_bytes + hello_back_bytes).digest()
+
+
+def confirm_label_for(role: Role) -> bytes:
+    """
+    Select the HMAC label for the sender of a CONFIRM message.
+
+    Pseudocode:
+    - Role.INITIATOR -> INITIATOR_CONFIRM_LABEL.
+    - Role.RESPONDER -> RESPONDER_CONFIRM_LABEL.
+    """
+
+    if role == Role.INITIATOR:
+        return INITIATOR_CONFIRM_LABEL
+    if role == Role.RESPONDER:
+        return RESPONDER_CONFIRM_LABEL
+
+    raise UnexpectedMessage(
+        "unknown role",
+        reason=f"role {role} is not allowed",
+    )
+
+
+def compute_verify_data(
+    symmetric_key: bytes,
+    sender_role: Role,
+    transcript_hash: bytes,
+) -> bytes:
+    """
+    Compute HMAC-SHA256(key=symmetric_key, data=label || transcript_hash).
+
+    Pseudocode:
+    - label = confirm_label_for(sender_role)
+    - data = label + transcript_hash
+    - Return HMAC-SHA256(symmetric_key, data).
+    """
+
+    if len(symmetric_key) != SYMMETRIC_KEY_LEN:
+        raise MalformedMessage(
+            "invalid symmetric key length",
+            reason=f"expected {SYMMETRIC_KEY_LEN} bytes, got {len(symmetric_key)} bytes",
+        )
+
+    if len(transcript_hash) != SYMMETRIC_KEY_LEN:
+        raise MalformedMessage(
+            "invalid transcript hash length",
+            reason=f"expected {SYMMETRIC_KEY_LEN} bytes, got {len(transcript_hash)} bytes",
+        )
+
+    label = confirm_label_for(sender_role)
+    return hmac.new(
+        symmetric_key,
+        label + transcript_hash,
+        hashlib.sha256,
+    ).digest()
+
+
+def verify_confirm_data(
+    symmetric_key: bytes,
+    sender_role: Role,
+    transcript_hash: bytes,
+    received_verify_data: bytes,
+) -> None:
+    """
+    Validate received verify_data with constant-time comparison.
+
+    Pseudocode:
+    - expected = compute_verify_data(symmetric_key, sender_role, transcript_hash)
+    - Use hmac.compare_digest(expected, received_verify_data).
+    - If comparison fails, raise VerificationFailed.
+    """
+
+    expected = compute_verify_data(
+        symmetric_key=symmetric_key,
+        sender_role=sender_role,
+        transcript_hash=transcript_hash,
+    )
+
+    if not hmac.compare_digest(expected, received_verify_data):
+        raise VerificationFailed(
+            "confirm verification failed",
+            reason="received verify_data does not match expected HMAC",
+        )
+
+
+def clear_sensitive_state(state: HandshakeState) -> None:
+    """
+    Drop references to ephemeral private key material after use or on abort.
+
+    Pseudocode:
+    - Set state.own_private_key = None.
+    - Optionally clear symmetric_key if aborting before success.
+    - Note: immutable Python bytes cannot be reliably zeroized in place.
+    """
+
+    state.own_private_key = None
+
+
+class InitiatorHandshake:
+    """
+    Initiator-side state machine for anonymous wirekx v1.
+
+    Expected call order:
+    1. create_hello()
+    2. receive_hello_back(hello_back_bytes)
+    3. create_confirm()
+    4. receive_confirm(confirm_bytes)
+    5. result()
+    """
+
+    def __init__(self) -> None:
+        """
+        Pseudocode:
+        - Create HandshakeState(role=Role.INITIATOR).
+        - Do not generate keys until create_hello(), unless you prefer eager init.
+        """
+
+        self.state = HandshakeState(role=Role.INITIATOR)
+
+    def create_hello(self) -> bytes:
+        """
+        Build the first message.
+
+        Pseudocode:
+        - Generate fresh X25519 keypair.
+        - Generate nonce_a.
+        - payload = encode_hello_payload(eph_pub_a, nonce_a).
+        - hello_bytes = encode_envelope(MessageType.HELLO, payload).
+        - Store own key, own public key, nonce_a, and hello_bytes.
+        - Return hello_bytes.
+        """
+
+        own_private_key, own_public_key = generate_ephemeral_keypair()
+        own_nonce = generate_nonce()
+        payload = encode_hello_payload(own_public_key, own_nonce)
+        hello_bytes = encode_envelope(MessageType.HELLO, payload)
+
+        self.state.own_private_key = own_private_key
+        self.state.own_public_key = own_public_key
+        self.state.own_nonce = own_nonce
+        self.state.hello_bytes = hello_bytes
+
+        return hello_bytes
+
+    def receive_hello_back(self, message: bytes) -> None:
+        """
+        Process responder HELLO_BACK and derive key material.
+
+        Pseudocode:
+        - Decode envelope and require MessageType.HELLO_BACK.
+        - Parse eph_pub_b and nonce_b.
+        - Store exact hello_back bytes for transcript.
+        - shared_secret = derive_shared_secret(own_private_key, eph_pub_b).
+        - symmetric_key = derive_symmetric_key(shared_secret, nonce_a, nonce_b).
+        - transcript_hash = compute_transcript_hash(hello_bytes, hello_back_bytes).
+        - Clear own_private_key reference after deriving.
+        """
+
+        if self.state.own_private_key is None:
+            raise UnexpectedMessage(
+                "HELLO has not been created",
+                reason="call create_hello() before receive_hello_back()",
+            )
+        if self.state.own_nonce is None or self.state.hello_bytes is None:
+            raise UnexpectedMessage(
+                "initiator state is incomplete",
+                reason="missing nonce or HELLO transcript bytes",
+            )
+
+        envelope = decode_envelope(message)
+        if envelope.msg_type != MessageType.HELLO_BACK:
+            raise UnexpectedMessage(
+                "unexpected message type",
+                reason=f"expected HELLO_BACK, got {envelope.msg_type.name}",
+            )
+
+        hello_back = decode_hello_payload(envelope.payload)
+        shared_secret = derive_shared_secret(
+            self.state.own_private_key,
+            hello_back.eph_pub,
+        )
+        symmetric_key = derive_symmetric_key(
+            shared_secret,
+            self.state.own_nonce,
+            hello_back.nonce,
+        )
+        transcript_hash = compute_transcript_hash(self.state.hello_bytes, message)
+
+        self.state.peer_public_key = hello_back.eph_pub
+        self.state.peer_nonce = hello_back.nonce
+        self.state.hello_back_bytes = message
+        self.state.symmetric_key = symmetric_key
+        self.state.transcript_hash = transcript_hash
+        clear_sensitive_state(self.state)
+
+    def create_confirm(self) -> bytes:
+        """
+        Build initiator CONFIRM.
+
+        Pseudocode:
+        - Require symmetric_key and transcript_hash exist.
+        - verify_data = compute_verify_data(key, Role.INITIATOR, transcript_hash).
+        - payload = encode_confirm_payload(verify_data).
+        - confirm_bytes = encode_envelope(MessageType.CONFIRM, payload).
+        - Mark own_confirm_sent.
+        - Return confirm_bytes.
+        """
+
+        if self.state.symmetric_key is None or self.state.transcript_hash is None:
+            raise UnexpectedMessage(
+                "key material has not been derived",
+                reason="call receive_hello_back() before create_confirm()",
+            )
+
+        verify_data = compute_verify_data(
+            self.state.symmetric_key,
+            Role.INITIATOR,
+            self.state.transcript_hash,
+        )
+        payload = encode_confirm_payload(verify_data)
+        confirm_bytes = encode_envelope(MessageType.CONFIRM, payload)
+        self.state.own_confirm_sent = True
+        return confirm_bytes
+
+    def receive_confirm(self, message: bytes) -> None:
+        """
+        Verify responder CONFIRM.
+
+        Pseudocode:
+        - Decode envelope and require MessageType.CONFIRM.
+        - Parse verify_data.
+        - verify_confirm_data(key, Role.RESPONDER, transcript_hash, verify_data).
+        - Mark peer_confirm_verified.
+        """
+
+        if self.state.symmetric_key is None or self.state.transcript_hash is None:
+            raise UnexpectedMessage(
+                "key material has not been derived",
+                reason="call receive_hello_back() before receive_confirm()",
+            )
+
+        envelope = decode_envelope(message)
+        if envelope.msg_type != MessageType.CONFIRM:
+            raise UnexpectedMessage(
+                "unexpected message type",
+                reason=f"expected CONFIRM, got {envelope.msg_type.name}",
+            )
+
+        confirm = decode_confirm_payload(envelope.payload)
+        verify_confirm_data(
+            self.state.symmetric_key,
+            Role.RESPONDER,
+            self.state.transcript_hash,
+            confirm.verify_data,
+        )
+        self.state.peer_confirm_verified = True
+
+    def result(self) -> HandshakeResult:
+        """
+        Return final output only after both CONFIRM messages are complete.
+
+        Pseudocode:
+        - Require own_confirm_sent and peer_confirm_verified.
+        - Require symmetric_key and transcript_hash exist.
+        - Return HandshakeResult(symmetric_key, transcript_hash).
+        """
+
+        if not self.state.own_confirm_sent or not self.state.peer_confirm_verified:
+            raise UnexpectedMessage(
+                "handshake is not complete",
+                reason="both local and peer CONFIRM messages must complete first",
+            )
+        if self.state.symmetric_key is None or self.state.transcript_hash is None:
+            raise UnexpectedMessage(
+                "handshake result is unavailable",
+                reason="missing symmetric key or transcript hash",
+            )
+
+        return HandshakeResult(
+            symmetric_key=self.state.symmetric_key,
+            transcript_hash=self.state.transcript_hash,
+        )
+
+
+class ResponderHandshake:
+    """
+    Responder-side state machine for anonymous wirekx v1.
+
+    Expected call order:
+    1. receive_hello(hello_bytes)
+    2. create_hello_back()
+    3. receive_confirm(confirm_bytes)
+    4. create_confirm()
+    5. result()
+    """
+
+    def __init__(self) -> None:
+        """
+        Pseudocode:
+        - Create HandshakeState(role=Role.RESPONDER).
+        - Do not generate keys until receive_hello() or create_hello_back().
+        """
+
+        self.state = HandshakeState(role=Role.RESPONDER)
+
+    def receive_hello(self, message: bytes) -> None:
+        """
+        Process initiator HELLO.
+
+        Pseudocode:
+        - Decode envelope and require MessageType.HELLO.
+        - Parse eph_pub_a and nonce_a.
+        - Store exact hello bytes for transcript.
+        - Store peer public key and peer nonce.
+        """
+
+        envelope = decode_envelope(message)
+        if envelope.msg_type != MessageType.HELLO:
+            raise UnexpectedMessage(
+                "unexpected message type",
+                reason=f"expected HELLO, got {envelope.msg_type.name}",
+            )
+
+        hello = decode_hello_payload(envelope.payload)
+        self.state.peer_public_key = hello.eph_pub
+        self.state.peer_nonce = hello.nonce
+        self.state.hello_bytes = message
+
+    def create_hello_back(self) -> bytes:
+        """
+        Build responder HELLO_BACK and derive key material.
+
+        Pseudocode:
+        - Require initiator HELLO has been received.
+        - Generate fresh X25519 keypair.
+        - Generate nonce_b.
+        - payload = encode_hello_payload(eph_pub_b, nonce_b).
+        - hello_back_bytes = encode_envelope(MessageType.HELLO_BACK, payload).
+        - shared_secret = derive_shared_secret(own_private_key, eph_pub_a).
+        - symmetric_key = derive_symmetric_key(shared_secret, nonce_a, nonce_b).
+        - transcript_hash = compute_transcript_hash(hello_bytes, hello_back_bytes).
+        - Clear own_private_key reference after deriving.
+        - Return hello_back_bytes.
+        """
+
+        if self.state.peer_public_key is None:
+            raise UnexpectedMessage(
+                "HELLO has not been received",
+                reason="call receive_hello() before create_hello_back()",
+            )
+        if self.state.peer_nonce is None or self.state.hello_bytes is None:
+            raise UnexpectedMessage(
+                "responder state is incomplete",
+                reason="missing peer nonce or HELLO transcript bytes",
+            )
+
+        own_private_key, own_public_key = generate_ephemeral_keypair()
+        own_nonce = generate_nonce()
+        payload = encode_hello_payload(own_public_key, own_nonce)
+        hello_back_bytes = encode_envelope(MessageType.HELLO_BACK, payload)
+        shared_secret = derive_shared_secret(own_private_key, self.state.peer_public_key)
+        symmetric_key = derive_symmetric_key(
+            shared_secret,
+            self.state.peer_nonce,
+            own_nonce,
+        )
+        transcript_hash = compute_transcript_hash(
+            self.state.hello_bytes,
+            hello_back_bytes,
+        )
+
+        self.state.own_private_key = own_private_key
+        self.state.own_public_key = own_public_key
+        self.state.own_nonce = own_nonce
+        self.state.hello_back_bytes = hello_back_bytes
+        self.state.symmetric_key = symmetric_key
+        self.state.transcript_hash = transcript_hash
+        clear_sensitive_state(self.state)
+
+        return hello_back_bytes
+
+    def receive_confirm(self, message: bytes) -> None:
+        """
+        Verify initiator CONFIRM.
+
+        Pseudocode:
+        - Decode envelope and require MessageType.CONFIRM.
+        - Parse verify_data.
+        - verify_confirm_data(key, Role.INITIATOR, transcript_hash, verify_data).
+        - Mark peer_confirm_verified.
+        """
+
+        if self.state.symmetric_key is None or self.state.transcript_hash is None:
+            raise UnexpectedMessage(
+                "key material has not been derived",
+                reason="call create_hello_back() before receive_confirm()",
+            )
+
+        envelope = decode_envelope(message)
+        if envelope.msg_type != MessageType.CONFIRM:
+            raise UnexpectedMessage(
+                "unexpected message type",
+                reason=f"expected CONFIRM, got {envelope.msg_type.name}",
+            )
+
+        confirm = decode_confirm_payload(envelope.payload)
+        verify_confirm_data(
+            self.state.symmetric_key,
+            Role.INITIATOR,
+            self.state.transcript_hash,
+            confirm.verify_data,
+        )
+        self.state.peer_confirm_verified = True
+
+    def create_confirm(self) -> bytes:
+        """
+        Build responder CONFIRM.
+
+        Pseudocode:
+        - Require initiator CONFIRM has verified.
+        - verify_data = compute_verify_data(key, Role.RESPONDER, transcript_hash).
+        - payload = encode_confirm_payload(verify_data).
+        - confirm_bytes = encode_envelope(MessageType.CONFIRM, payload).
+        - Mark own_confirm_sent.
+        - Return confirm_bytes.
+        """
+
+        if not self.state.peer_confirm_verified:
+            raise UnexpectedMessage(
+                "peer CONFIRM has not been verified",
+                reason="call receive_confirm() before create_confirm()",
+            )
+        if self.state.symmetric_key is None or self.state.transcript_hash is None:
+            raise UnexpectedMessage(
+                "key material has not been derived",
+                reason="call create_hello_back() before create_confirm()",
+            )
+
+        verify_data = compute_verify_data(
+            self.state.symmetric_key,
+            Role.RESPONDER,
+            self.state.transcript_hash,
+        )
+        payload = encode_confirm_payload(verify_data)
+        confirm_bytes = encode_envelope(MessageType.CONFIRM, payload)
+        self.state.own_confirm_sent = True
+        return confirm_bytes
+
+    def result(self) -> HandshakeResult:
+        """
+        Return final output only after both CONFIRM messages are complete.
+
+        Pseudocode:
+        - Require own_confirm_sent and peer_confirm_verified.
+        - Require symmetric_key and transcript_hash exist.
+        - Return HandshakeResult(symmetric_key, transcript_hash).
+        """
+
+        if not self.state.own_confirm_sent or not self.state.peer_confirm_verified:
+            raise UnexpectedMessage(
+                "handshake is not complete",
+                reason="both local and peer CONFIRM messages must complete first",
+            )
+        if self.state.symmetric_key is None or self.state.transcript_hash is None:
+            raise UnexpectedMessage(
+                "handshake result is unavailable",
+                reason="missing symmetric key or transcript hash",
+            )
+
+        return HandshakeResult(
+            symmetric_key=self.state.symmetric_key,
+            transcript_hash=self.state.transcript_hash,
+        )

wirekx-0.1.0.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: wirekx
+Version: 0.1.0
+Summary: Experimental anonymous X25519 key exchange wire format.
+Project-URL: Homepage, https://github.com/wirekx/wirekx
+Project-URL: Repository, https://github.com/wirekx/wirekx
+Project-URL: Issues, https://github.com/wirekx/wirekx/issues
+Author: wirekx contributors
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: cryptography,experimental,key-exchange,x25519
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=49.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+```text
+  *   *      __        __  ___  ____   _____  _  __ __  __
+   \ /       \ \      / / |_ _||  _ \ | ____|| |/ / \ \/ /
+ ^/ | \^      \ \ /\ / /   | | | |_) ||  _|  | ' /   \  /
+ | o:1 |       \ V  V /    | | |  _ < | |___ | . \   /  \
+-| 1:o |-       \_/\_/    |___||_| \_\|_____||_|\_\ /_/\_\
+/ \_|_/ \
+```
+
+Python library and wire format for anonymous X25519 key exchange.
+
+> **wirekx v1 performs the following:**
+>
+> - Opportunistic key agreement for anonymous handshake
+>
+> **V1 caveat:** Since this is an anonymous handshake, MITM is undetectable.
+>
+> **Use cases:**
+>
+> - Derive symmetric key for payload encryption between trusted services
+>
+> **Future releases:**
+>
+> - publicCA validation for anonymous handshake
+> - Pre-shared fingerprint validation
+> - Quantum-safe encryption
+
+## Install for development
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+```
+
+Run the manual example:
+
+```bash
+.venv/bin/python testrun.py
+```
+
+Run tests:
+
+```bash
+.venv/bin/python -m pytest
+```
+
+Use as a library:
+
+```python
+from wirekx import InitiatorHandshake, ResponderHandshake
+
+initiator = InitiatorHandshake()
+responder = ResponderHandshake()
+
+hello = initiator.create_hello()
+responder.receive_hello(hello)
+
+hello_back = responder.create_hello_back()
+initiator.receive_hello_back(hello_back)
+
+initiator_confirm = initiator.create_confirm()
+responder.receive_confirm(initiator_confirm)
+
+responder_confirm = responder.create_confirm()
+initiator.receive_confirm(responder_confirm)
+
+result = initiator.result()
+print(result.symmetric_key.hex())
+```
+
+## Open source contribution flow
+
+1. Fork the repository on GitHub.
+2. Create a branch for your change.
+3. Install development dependencies with `.venv/bin/python -m pip install -e ".[dev]"`.
+4. Add or update tests in `tests/`.
+5. Run `.venv/bin/python -m pytest`.
+6. Open a pull request.
+
+## License
+
+wirekx is licensed under the Apache License, Version 2.0. See `LICENSE`.
+
+Redistributions should preserve the attribution notices in `NOTICE`. If you use
+wirekx in a public project, a README or documentation mention is appreciated.
+
+## wirekx wire format (v1, anonymous mode)
+
+Two parties run a handshake and end up holding the same 32-byte symmetric key.
+This document specifies the bytes that go on the wire.
+
+## Envelope
+
+Every message starts with a 4-byte header followed by its payload.
+
+```
+┌─────────┬──────────┬─────────────┬──────────────┐
+│ version │ msg_type │ payload_len │   payload    │
+│ 1 byte  │  1 byte  │  2 bytes BE │ payload_len  │
+└─────────┴──────────┴─────────────┴──────────────┘
+```
+
+`version` = `0x01`. Multi-byte integers are big-endian.
+
+## Messages
+
+| Code   | Name         | From      | Payload                           |
+|--------|--------------|-----------|-----------------------------------|
+| `0x01` | `HELLO`      | initiator | `eph_pub_a` (32) + `nonce_a` (32) |
+| `0x02` | `HELLO_BACK` | responder | `eph_pub_b` (32) + `nonce_b` (32) |
+| `0x03` | `CONFIRM`    | both      | `verify_data` (32)                |
+
+`eph_pub_*` is an X25519 public key. `nonce_*` is 32 random bytes.
+
+## Cryptography
+
+```
+shared_secret  = X25519(own_eph_priv, peer_eph_pub)
+
+symmetric_key  = HKDF-SHA256(
+    ikm    = shared_secret,
+    salt   = nonce_a || nonce_b,
+    info   = "wirekx v1 session key",
+    length = 32)
+
+transcript     = SHA-256(HELLO_bytes || HELLO_BACK_bytes)
+
+verify_data    = HMAC-SHA256(
+    key  = symmetric_key,
+    data = "wirekx v1 <role> confirm" || transcript)
+```
+
+`<role>` is `initiator` or `responder` depending on who sent the `CONFIRM`.
+Compare received `verify_data` with constant-time equality. Mismatch = abort.
+
+## Flow
+
+```
+initiator                              responder
+    │                                       │
+    │   HELLO  (eph_pub_a, nonce_a)         │
+    │ ────────────────────────────────────► │
+    │                                       │
+    │   HELLO_BACK  (eph_pub_b, nonce_b)    │
+    │ ◄──────────────────────────────────── │
+    │                                       │
+    │   derive symmetric_key, transcript    │
+    │   CONFIRM  (verify_data_initiator)    │
+    │ ────────────────────────────────────► │
+    │                                       │
+    │                                       │   verify, then:
+    │   CONFIRM  (verify_data_responder)    │
+    │ ◄──────────────────────────────────── │
+    │                                       │
+    │   verify                              │
+    │   COMPLETE                            │   COMPLETE
+```
+
+On any malformed message, unexpected type, or verification mismatch: abort,
+discard state, do not return the key.
+
+## Output
+
+After both `CONFIRM` messages verify, return to the caller:
+
+- `symmetric_key` — 32 bytes
+- `transcript_hash` — 32 bytes
+- `protection_level` = `"opportunistic"`
+- `peer_identity` = `null`
+
+## Notes
+
+- `transcript_hash` is unique per handshake.
+- Possible values for `protection_level` are `"opportunistic"` and `"authenticated"`. Opportunistic means anonymous players, active MITM is undetectable. Authenticated means you have verified peer's identity by exchanging certificate via an external channel.
+- Ephemeral keys are fresh per handshake and discarded after use.
+- No version negotiation. Different versions cannot interoperate.
+- Authenticated modes (`fingerprint`, `shared`, `publicCA`) will be built in future.

wirekx-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+wirekx/__init__.py,sha256=DttXcmYAxQ4OF_Ln5PvUqIMsdpXiMoSlzz2G-Z11Fz8,27462
+wirekx-0.1.0.dist-info/METADATA,sha256=AeKYW2VCKJSflDHBdaGAFCHAXzfxwkfxBJP8jqW9VFA,6918
+wirekx-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+wirekx-0.1.0.dist-info/licenses/LICENSE,sha256=JE3Cn08i5iAJ6crI446FQJt83avkor0twT8LkYZuNFU,10417
+wirekx-0.1.0.dist-info/licenses/NOTICE,sha256=-GtiOtdPGq0CEcKEb8sH_MrYTl-79-yykd_hFzH3XAA,174
+wirekx-0.1.0.dist-info/RECORD,,

wirekx-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

wirekx-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,185 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work (an example is provided in the Appendix
+below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable (except as stated in this section) patent
+license to make, have made, use, offer to sell, sell, import, and otherwise
+transfer the Work, where such license applies only to those patent claims
+licensable by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s) with the Work
+to which such Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a lawsuit)
+alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate as of the date
+such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+   (a) You must give any other recipients of the Work or Derivative Works a copy
+       of this License; and
+
+   (b) You must cause any modified files to carry prominent notices stating that
+       You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works that You
+       distribute, all copyright, patent, trademark, and attribution notices
+       from the Source form of the Work, excluding those notices that do not
+       pertain to any part of the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its distribution,
+       then any Derivative Works that You distribute must include a readable copy
+       of the attribution notices contained within such NOTICE file, excluding
+       those notices that do not pertain to any part of the Derivative Works, in
+       at least one of the following places: within a NOTICE text file
+       distributed as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or, within a
+       display generated by the Derivative Works, if and wherever such
+       third-party notices normally appear. The contents of the NOTICE file are
+       for informational purposes only and do not modify the License. You may add
+       Your own attribution notices within Derivative Works that You distribute,
+       alongside or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed as modifying
+       the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties or
+conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any character
+arising as a result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill, work stoppage,
+computer failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility of such
+damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree to
+indemnify, defend, and hold each Contributor harmless for any liability incurred
+by, or claims asserted against, such Contributor by reason of your accepting any
+such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. Do not include the brackets. The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification
+within third-party archives.
+
+   Copyright 2026 wirekx contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+   WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+   License for the specific language governing permissions and limitations under
+   the License.

wirekx-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,7 @@
+wirekx
+Copyright 2026 wirekx contributors
+
+This product includes wirekx, an anonymous X25519 key exchange
+library and wire format.
+
+Project: https://github.com/wirekx/wirekx