session-python 1.0.0__py3-none-any.whl

session_python/crypto.py

@@ -0,0 +1,298 @@
+import os
+import hashlib
+import binascii
+import nacl.signing
+import nacl.public
+import nacl.exceptions
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives import hashes, hmac as crypto_hmac
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from typing import Optional
+from .protobuf.signalservice_pb2 import WebSocketMessage, WebSocketRequestMessage, Envelope
+
+def remove_prefix_if_needed(val):
+    if isinstance(val, str):
+        if val.startswith("05"):
+            return val[2:]
+    elif isinstance(val, (bytes, bytearray)):
+        if len(val) > 0 and val[0] == 5:
+            return val[1:]
+    return val
+
+def add_prefix_if_needed(val: bytes) -> bytes:
+    if len(val) == 32:
+        return b'\x05' + val
+    return val
+
+class KeyPair:
+    def __init__(self, key_type: str, private_key: bytes, public_key: bytes):
+        self.key_type = key_type
+        self.private_key = private_key
+        self.public_key = public_key
+
+class SessionKeys:
+    def __init__(self, seed_hex: str):
+        if len(seed_hex) != 64:
+            seed_hex = (seed_hex + "0" * 32)[:64]
+        
+        self.seed = binascii.unhexlify(seed_hex)
+        
+        # Ed25519 KeyPair
+        self.signing_key = nacl.signing.SigningKey(self.seed)
+        self.verify_key = self.signing_key.verify_key
+        
+        self.ed25519 = KeyPair(
+            key_type="ed25519",
+            private_key=self.seed,
+            public_key=self.verify_key.encode()
+        )
+        
+        # X25519 KeyPair
+        self.x25519_private = self.signing_key.to_curve25519_private_key()
+        self.x25519_public = self.verify_key.to_curve25519_public_key()
+        
+        prepended_public = b'\x05' + self.x25519_public.encode()
+        
+        self.x25519 = KeyPair(
+            key_type="x25519",
+            private_key=self.x25519_private.encode(),
+            public_key=prepended_public
+        )
+
+def crypto_box_seal(message: bytes, recipient_pk: bytes) -> bytes:
+    recipient_pk_clean = remove_prefix_if_needed(recipient_pk)
+    if len(recipient_pk_clean) != 32:
+        raise ValueError(f"Recipient public key must be 32 bytes, got {len(recipient_pk_clean)}")
+        
+    pk = nacl.public.PublicKey(recipient_pk_clean)
+    box = nacl.public.SealedBox(pk)
+    return box.encrypt(message)
+
+def crypto_box_seal_open(sealed: bytes, recipient_sk: bytes) -> bytes:
+    if len(recipient_sk) != 32:
+        raise ValueError(f"Recipient secret key must be 32 bytes, got {len(recipient_sk)}")
+        
+    sk = nacl.public.PrivateKey(recipient_sk)
+    box = nacl.public.SealedBox(sk)
+    try:
+        return box.decrypt(sealed)
+    except nacl.exceptions.CryptoError:
+        raise ValueError("Decryption failed (crypto_box_seal_open)")
+
+def add_message_padding(message_bytes: bytes) -> bytes:
+    orig_len = len(message_bytes)
+    target_len = (((orig_len + 2 + 159) // 160) * 160) - 1
+    padded = bytearray(target_len)
+    padded[:orig_len] = message_bytes
+    padded[orig_len] = 0x80
+    return bytes(padded)
+
+def remove_message_padding(padded_bytes: bytes) -> bytes:
+    for i in range(len(padded_bytes) - 1, -1, -1):
+        if padded_bytes[i] == 0x80:
+            return padded_bytes[:i]
+        if padded_bytes[i] != 0x00:
+            return padded_bytes
+    raise ValueError("Invalid padding")
+
+def encrypt_using_session_protocol(sender_keys: SessionKeys, recipient: str, plaintext: bytes) -> bytes:
+    recipient_pk = binascii.unhexlify(remove_prefix_if_needed(recipient))
+    verification_data = plaintext + sender_keys.ed25519.public_key + recipient_pk
+    signature = sender_keys.signing_key.sign(verification_data).signature
+    plaintext_with_metadata = plaintext + sender_keys.ed25519.public_key + signature
+    return crypto_box_seal(plaintext_with_metadata, recipient_pk)
+
+def decrypt_with_session_protocol(recipient_keys: SessionKeys, envelope_content: bytes) -> tuple[bytes, str]:
+    recipient_x25519_pk = remove_prefix_if_needed(recipient_keys.x25519.public_key)
+    
+    plaintext_with_metadata = crypto_box_seal_open(
+        envelope_content,
+        recipient_keys.x25519.private_key
+    )
+    
+    signature_size = 64
+    ed25519_public_key_size = 32
+    min_size = signature_size + ed25519_public_key_size
+    
+    if len(plaintext_with_metadata) <= min_size:
+        raise ValueError("Decrypted content too short")
+        
+    signature_start = len(plaintext_with_metadata) - signature_size
+    signature = plaintext_with_metadata[signature_start:]
+    
+    pubkey_start = len(plaintext_with_metadata) - min_size
+    pubkey_end = len(plaintext_with_metadata) - signature_size
+    sender_ed25519_pubkey = plaintext_with_metadata[pubkey_start:pubkey_end]
+    
+    plainTextEnd = len(plaintext_with_metadata) - min_size
+    plaintext = plaintext_with_metadata[:plainTextEnd]
+    
+    verification_data = plaintext + sender_ed25519_pubkey + recipient_x25519_pk
+    verify_key = nacl.signing.VerifyKey(sender_ed25519_pubkey)
+    
+    try:
+        verify_key.verify(verification_data, signature)
+    except nacl.exceptions.BadSignatureError:
+        raise ValueError("Invalid message signature")
+        
+    sender_x25519_pubkey = verify_key.to_curve25519_public_key().encode()
+    sender_session_id = "05" + binascii.hexlify(sender_x25519_pubkey).decode()
+    
+    return plaintext, sender_session_id
+
+def wrap_envelope(envelope_bytes: bytes) -> bytes:
+    request = WebSocketRequestMessage(
+        id=0,
+        body=envelope_bytes,
+        verb="PUT",
+        path="/api/v1/message"
+    )
+    
+    websocket = WebSocketMessage(
+        type=WebSocketMessage.Type.REQUEST,
+        request=request
+    )
+    return websocket.SerializeToString()
+
+# --- Attachment encryption and decryption ---
+
+def pkcs7_pad(data: bytes, block_size: int = 16) -> bytes:
+    pad_len = block_size - (len(data) % block_size)
+    return data + bytes([pad_len] * pad_len)
+
+def pkcs7_unpad(data: bytes) -> bytes:
+    pad_len = data[-1]
+    if pad_len < 1 or pad_len > 16:
+        raise ValueError("Invalid PKCS7 padding length")
+    for b in data[-pad_len:]:
+        if b != pad_len:
+            raise ValueError("Invalid PKCS7 padding bytes")
+    return data[:-pad_len]
+
+def add_attachment_padding(data: bytes) -> bytes:
+    import math
+    orig_len = len(data)
+    # Math.max(541, Math.floor(Math.pow(1.05, Math.ceil(Math.log(orig_len) / Math.log(1.05)))))
+    if orig_len == 0:
+        padded_size = 541
+    else:
+        log_len = math.log(orig_len)
+        log_base = math.log(1.05)
+        padded_size = int(max(541, math.floor(math.pow(1.05, math.ceil(log_len / log_base)))))
+        
+    max_attachment_size = 15 * 1024 * 1024 # 15MB
+    if padded_size > max_attachment_size and orig_len <= max_attachment_size:
+        padded_size = max_attachment_size
+        
+    padded = bytearray(padded_size)
+    padded[:orig_len] = data
+    return bytes(padded)
+
+def encrypt_attachment_data(plaintext: bytes, keys: bytes, iv: bytes) -> tuple[bytes, bytes]:
+    if len(keys) != 64:
+        raise ValueError("Attachment key must be 64 bytes")
+    if len(iv) != 16:
+        raise ValueError("Attachment IV must be 16 bytes")
+        
+    aes_key = keys[:32]
+    mac_key = keys[32:]
+    
+    # Pad plaintext for AES-CBC
+    padded_plaintext = pkcs7_pad(plaintext, 16)
+    
+    # AES-CBC encrypt
+    cipher = Cipher(algorithms.AES(aes_key), modes.CBC(iv))
+    encryptor = cipher.encryptor()
+    ciphertext = encryptor.update(padded_plaintext) + encryptor.finalize()
+    
+    # ivAndCiphertext = iv || ciphertext
+    iv_and_ciphertext = iv + ciphertext
+    
+    # Compute MAC
+    h = crypto_hmac.HMAC(mac_key, hashes.SHA256())
+    h.update(iv_and_ciphertext)
+    mac = h.finalize()
+    
+    # final payload: iv || ciphertext || mac
+    encrypted_bin = iv_and_ciphertext + mac
+    
+    # digest: sha256 of encrypted_bin
+    digest = hashlib.sha256(encrypted_bin).digest()
+    
+    return encrypted_bin, digest
+
+def encrypt_attachment(data: bytes, add_padding: bool = True) -> dict:
+    pointer_key = os.urandom(64)
+    iv = os.urandom(16)
+    padded = add_attachment_padding(data) if add_padding else data
+    ciphertext, digest = encrypt_attachment_data(padded, pointer_key, iv)
+    return {
+        "ciphertext": ciphertext,
+        "digest": digest,
+        "key": pointer_key
+    }
+
+def decrypt_attachment(data: bytes, key: bytes, digest: bytes, size: Optional[int] = None) -> bytes:
+    if len(key) != 64:
+        raise ValueError("Attachment key must be 64 bytes")
+    if len(data) < 48:
+        raise ValueError("Attachment data too short")
+        
+    aes_key = key[:32]
+    mac_key = key[32:]
+    
+    iv = data[:16]
+    ciphertext = data[16:-32]
+    iv_and_ciphertext = data[:-32]
+    mac = data[-32:]
+    
+    # Verify MAC
+    h = crypto_hmac.HMAC(mac_key, hashes.SHA256())
+    h.update(iv_and_ciphertext)
+    calculated_mac = h.finalize()
+    if calculated_mac != mac:
+        raise ValueError("Bad attachment MAC")
+        
+    # Verify Digest
+    calculated_digest = hashlib.sha256(data).digest()
+    if calculated_digest != digest:
+        raise ValueError("Bad attachment digest")
+        
+    # AES-CBC decrypt
+    cipher = Cipher(algorithms.AES(aes_key), modes.CBC(iv))
+    decryptor = cipher.decryptor()
+    decrypted_padded = decryptor.update(ciphertext) + decryptor.finalize()
+    
+    decrypted = pkcs7_unpad(decrypted_padded)
+    
+    # If size is specified, truncate the padding added by add_attachment_padding
+    if size is not None:
+        if size <= len(decrypted):
+            decrypted = decrypted[:size]
+        else:
+            raise ValueError("Decrypted attachment size mismatch")
+            
+    return decrypted
+
+# --- Profile GCM Encryption/Decryption ---
+
+def encrypt_profile(data: bytes, key: bytes) -> bytes:
+    if len(key) != 32:
+        raise ValueError("Profile key must be 32 bytes")
+    iv = os.urandom(12)
+    aesgcm = AESGCM(key)
+    ciphertext = aesgcm.encrypt(iv, data, None) # returns ciphertext + 16-byte tag appended
+    return iv + ciphertext
+
+def decrypt_profile(data: bytes, key: bytes) -> bytes:
+    if len(key) != 32:
+        raise ValueError("Profile key must be 32 bytes")
+    if len(data) < 29: # 12 bytes IV + 16 bytes tag + at least 1 byte ciphertext
+        raise ValueError("Profile data too short")
+    iv = data[:12]
+    ciphertext = data[12:]
+    aesgcm = AESGCM(key)
+    try:
+        return aesgcm.decrypt(iv, ciphertext, None)
+    except Exception:
+        raise ValueError("Failed to decrypt profile data")

session_python/mnemonic.py

@@ -0,0 +1,76 @@
+import binascii
+
+WORDS = ['abbey', 'abducts', 'ability', 'ablaze', 'abnormal', 'abort', 'abrasive', 'absorb', 'abyss', 'academy', 'aces', 'aching', 'acidic', 'acoustic', 'acquire', 'across', 'actress', 'acumen', 'adapt', 'addicted', 'adept', 'adhesive', 'adjust', 'adopt', 'adrenalin', 'adult', 'adventure', 'aerial', 'afar', 'affair', 'afield', 'afloat', 'afoot', 'afraid', 'after', 'against', 'agenda', 'aggravate', 'agile', 'aglow', 'agnostic', 'agony', 'agreed', 'ahead', 'aided', 'ailments', 'aimless', 'airport', 'aisle', 'ajar', 'akin', 'alarms', 'album', 'alchemy', 'alerts', 'algebra', 'alkaline', 'alley', 'almost', 'aloof', 'alpine', 'already', 'also', 'altitude', 'alumni', 'always', 'amaze', 'ambush', 'amended', 'amidst', 'ammo', 'amnesty', 'among', 'amply', 'amused', 'anchor', 'android', 'anecdote', 'angled', 'ankle', 'annoyed', 'answers', 'antics', 'anvil', 'anxiety', 'anybody', 'apart', 'apex', 'aphid', 'aplomb', 'apology', 'apply', 'apricot', 'aptitude', 'aquarium', 'arbitrary', 'archer', 'ardent', 'arena', 'argue', 'arises', 'army', 'around', 'arrow', 'arsenic', 'artistic', 'ascend', 'ashtray', 'aside', 'asked', 'asleep', 'aspire', 'assorted', 'asylum', 'athlete', 'atlas', 'atom', 'atrium', 'attire', 'auburn', 'auctions', 'audio', 'august', 'aunt', 'austere', 'autumn', 'avatar', 'avidly', 'avoid', 'awakened', 'awesome', 'awful', 'awkward', 'awning', 'awoken', 'axes', 'axis', 'axle', 'aztec', 'azure', 'baby', 'bacon', 'badge', 'baffles', 'bagpipe', 'bailed', 'bakery', 'balding', 'bamboo', 'banjo', 'baptism', 'basin', 'batch', 'bawled', 'bays', 'because', 'beer', 'befit', 'begun', 'behind', 'being', 'below', 'bemused', 'benches', 'berries', 'bested', 'betting', 'bevel', 'beware', 'beyond', 'bias', 'bicycle', 'bids', 'bifocals', 'biggest', 'bikini', 'bimonthly', 'binocular', 'biology', 'biplane', 'birth', 'biscuit', 'bite', 'biweekly', 'blender', 'blip', 'bluntly', 'boat', 'bobsled', 'bodies', 'bogeys', 'boil', 'boldly', 'bomb', 'border', 'boss', 'both', 'bounced', 'bovine', 'bowling', 'boxes', 'boyfriend', 'broken', 'brunt', 'bubble', 'buckets', 'budget', 'buffet', 'bugs', 'building', 'bulb', 'bumper', 'bunch', 'business', 'butter', 'buying', 'buzzer', 'bygones', 'byline', 'bypass', 'cabin', 'cactus', 'cadets', 'cafe', 'cage', 'cajun', 'cake', 'calamity', 'camp', 'candy', 'casket', 'catch', 'cause', 'cavernous', 'cease', 'cedar', 'ceiling', 'cell', 'cement', 'cent', 'certain', 'chlorine', 'chrome', 'cider', 'cigar', 'cinema', 'circle', 'cistern', 'citadel', 'civilian', 'claim', 'click', 'clue', 'coal', 'cobra', 'cocoa', 'code', 'coexist', 'coffee', 'cogs', 'cohesive', 'coils', 'colony', 'comb', 'cool', 'copy', 'corrode', 'costume', 'cottage', 'cousin', 'cowl', 'criminal', 'cube', 'cucumber', 'cuddled', 'cuffs', 'cuisine', 'cunning', 'cupcake', 'custom', 'cycling', 'cylinder', 'cynical', 'dabbing', 'dads', 'daft', 'dagger', 'daily', 'damp', 'dangerous', 'dapper', 'darted', 'dash', 'dating', 'dauntless', 'dawn', 'daytime', 'dazed', 'debut', 'decay', 'dedicated', 'deepest', 'deftly', 'degrees', 'dehydrate', 'deity', 'dejected', 'delayed', 'demonstrate', 'dented', 'deodorant', 'depth', 'desk', 'devoid', 'dewdrop', 'dexterity', 'dialect', 'dice', 'diet', 'different', 'digit', 'dilute', 'dime', 'dinner', 'diode', 'diplomat', 'directed', 'distance', 'ditch', 'divers', 'dizzy', 'doctor', 'dodge', 'does', 'dogs', 'doing', 'dolphin', 'domestic', 'donuts', 'doorway', 'dormant', 'dosage', 'dotted', 'double', 'dove', 'down', 'dozen', 'dreams', 'drinks', 'drowning', 'drunk', 'drying', 'dual', 'dubbed', 'duckling', 'dude', 'duets', 'duke', 'dullness', 'dummy', 'dunes', 'duplex', 'duration', 'dusted', 'duties', 'dwarf', 'dwelt', 'dwindling', 'dying', 'dynamite', 'dyslexic', 'each', 'eagle', 'earth', 'easy', 'eating', 'eavesdrop', 'eccentric', 'echo', 'eclipse', 'economics', 'ecstatic', 'eden', 'edgy', 'edited', 'educated', 'eels', 'efficient', 'eggs', 'egotistic', 'eight', 'either', 'eject', 'elapse', 'elbow', 'eldest', 'eleven', 'elite', 'elope', 'else', 'eluded', 'emails', 'ember', 'emerge', 'emit', 'emotion', 'empty', 'emulate', 'energy', 'enforce', 'enhanced', 'enigma', 'enjoy', 'enlist', 'enmity', 'enough', 'enraged', 'ensign', 'entrance', 'envy', 'epoxy', 'equip', 'erase', 'erected', 'erosion', 'error', 'eskimos', 'espionage', 'essential', 'estate', 'etched', 'eternal', 'ethics', 'etiquette', 'evaluate', 'evenings', 'evicted', 'evolved', 'examine', 'excess', 'exhale', 'exit', 'exotic', 'exquisite', 'extra', 'exult', 'fabrics', 'factual', 'fading', 'fainted', 'faked', 'fall', 'family', 'fancy', 'farming', 'fatal', 'faulty', 'fawns', 'faxed', 'fazed', 'feast', 'february', 'federal', 'feel', 'feline', 'females', 'fences', 'ferry', 'festival', 'fetches', 'fever', 'fewest', 'fiat', 'fibula', 'fictional', 'fidget', 'fierce', 'fifteen', 'fight', 'films', 'firm', 'fishing', 'fitting', 'five', 'fixate', 'fizzle', 'fleet', 'flippant', 'flying', 'foamy', 'focus', 'foes', 'foggy', 'foiled', 'folding', 'fonts', 'foolish', 'fossil', 'fountain', 'fowls', 'foxes', 'foyer', 'framed', 'friendly', 'frown', 'fruit', 'frying', 'fudge', 'fuel', 'fugitive', 'fully', 'fuming', 'fungal', 'furnished', 'fuselage', 'future', 'fuzzy', 'gables', 'gadget', 'gags', 'gained', 'galaxy', 'gambit', 'gang', 'gasp', 'gather', 'gauze', 'gave', 'gawk', 'gaze', 'gearbox', 'gecko', 'geek', 'gels', 'gemstone', 'general', 'geometry', 'germs', 'gesture', 'getting', 'geyser', 'ghetto', 'ghost', 'giant', 'giddy', 'gifts', 'gigantic', 'gills', 'gimmick', 'ginger', 'girth', 'giving', 'glass', 'gleeful', 'glide', 'gnaw', 'gnome', 'goat', 'goblet', 'godfather', 'goes', 'goggles', 'going', 'goldfish', 'gone', 'goodbye', 'gopher', 'gorilla', 'gossip', 'gotten', 'gourmet', 'governing', 'gown', 'greater', 'grunt', 'guarded', 'guest', 'guide', 'gulp', 'gumball', 'guru', 'gusts', 'gutter', 'guys', 'gymnast', 'gypsy', 'gyrate', 'habitat', 'hacksaw', 'haggled', 'hairy', 'hamburger', 'happens', 'hashing', 'hatchet', 'haunted', 'having', 'hawk', 'haystack', 'hazard', 'hectare', 'hedgehog', 'heels', 'hefty', 'height', 'hemlock', 'hence', 'heron', 'hesitate', 'hexagon', 'hickory', 'hiding', 'highway', 'hijack', 'hiker', 'hills', 'himself', 'hinder', 'hippo', 'hire', 'history', 'hitched', 'hive', 'hoax', 'hobby', 'hockey', 'hoisting', 'hold', 'honked', 'hookup', 'hope', 'hornet', 'hospital', 'hotel', 'hounded', 'hover', 'howls', 'hubcaps', 'huddle', 'huge', 'hull', 'humid', 'hunter', 'hurried', 'husband', 'huts', 'hybrid', 'hydrogen', 'hyper', 'iceberg', 'icing', 'icon', 'identity', 'idiom', 'idled', 'idols', 'igloo', 'ignore', 'iguana', 'illness', 'imagine', 'imbalance', 'imitate', 'impel', 'inactive', 'inbound', 'incur', 'industrial', 'inexact', 'inflamed', 'ingested', 'initiate', 'injury', 'inkling', 'inline', 'inmate', 'innocent', 'inorganic', 'input', 'inquest', 'inroads', 'insult', 'intended', 'inundate', 'invoke', 'inwardly', 'ionic', 'irate', 'iris', 'irony', 'irritate', 'island', 'isolated', 'issued', 'italics', 'itches', 'items', 'itinerary', 'itself', 'ivory', 'jabbed', 'jackets', 'jaded', 'jagged', 'jailed', 'jamming', 'january', 'jargon', 'jaunt', 'javelin', 'jaws', 'jazz', 'jeans', 'jeers', 'jellyfish', 'jeopardy', 'jerseys', 'jester', 'jetting', 'jewels', 'jigsaw', 'jingle', 'jittery', 'jive', 'jobs', 'jockey', 'jogger', 'joining', 'joking', 'jolted', 'jostle', 'journal', 'joyous', 'jubilee', 'judge', 'juggled', 'juicy', 'jukebox', 'july', 'jump', 'junk', 'jury', 'justice', 'juvenile', 'kangaroo', 'karate', 'keep', 'kennel', 'kept', 'kernels', 'kettle', 'keyboard', 'kickoff', 'kidneys', 'king', 'kiosk', 'kisses', 'kitchens', 'kiwi', 'knapsack', 'knee', 'knife', 'knowledge', 'knuckle', 'koala', 'laboratory', 'ladder', 'lagoon', 'lair', 'lakes', 'lamb', 'language', 'laptop', 'large', 'last', 'later', 'launching', 'lava', 'lawsuit', 'layout', 'lazy', 'lectures', 'ledge', 'leech', 'left', 'legion', 'leisure', 'lemon', 'lending', 'leopard', 'lesson', 'lettuce', 'lexicon', 'liar', 'library', 'licks', 'lids', 'lied', 'lifestyle', 'light', 'likewise', 'lilac', 'limits', 'linen', 'lion', 'lipstick', 'liquid', 'listen', 'lively', 'loaded', 'lobster', 'locker', 'lodge', 'lofty', 'logic', 'loincloth', 'long', 'looking', 'lopped', 'lordship', 'losing', 'lottery', 'loudly', 'love', 'lower', 'loyal', 'lucky', 'luggage', 'lukewarm', 'lullaby', 'lumber', 'lunar', 'lurk', 'lush', 'luxury', 'lymph', 'lynx', 'lyrics', 'macro', 'madness', 'magically', 'mailed', 'major', 'makeup', 'malady', 'mammal', 'maps', 'masterful', 'match', 'maul', 'maverick', 'maximum', 'mayor', 'maze', 'meant', 'mechanic', 'medicate', 'meeting', 'megabyte', 'melting', 'memoir', 'menu', 'merger', 'mesh', 'metro', 'mews', 'mice', 'midst', 'mighty', 'mime', 'mirror', 'misery', 'mittens', 'mixture', 'moat', 'mobile', 'mocked', 'mohawk', 'moisture', 'molten', 'moment', 'money', 'moon', 'mops', 'morsel', 'mostly', 'motherly', 'mouth', 'movement', 'mowing', 'much', 'muddy', 'muffin', 'mugged', 'mullet', 'mumble', 'mundane', 'muppet', 'mural', 'musical', 'muzzle', 'myriad', 'mystery', 'myth', 'nabbing', 'nagged', 'nail', 'names', 'nanny', 'napkin', 'narrate', 'nasty', 'natural', 'nautical', 'navy', 'nearby', 'necklace', 'needed', 'negative', 'neither', 'neon', 'nephew', 'nerves', 'nestle', 'network', 'neutral', 'never', 'newt', 'nexus', 'nibs', 'niche', 'niece', 'nifty', 'nightly', 'nimbly', 'nineteen', 'nirvana', 'nitrogen', 'nobody', 'nocturnal', 'nodes', 'noises', 'nomad', 'noodles', 'northern', 'nostril', 'noted', 'nouns', 'novelty', 'nowhere', 'nozzle', 'nuance', 'nucleus', 'nudged', 'nugget', 'nuisance', 'null', 'number', 'nuns', 'nurse', 'nutshell', 'nylon', 'oaks', 'oars', 'oasis', 'oatmeal', 'obedient', 'object', 'obliged', 'obnoxious', 'observant', 'obtains', 'obvious', 'occur', 'ocean', 'october', 'odds', 'odometer', 'offend', 'often', 'oilfield', 'ointment', 'okay', 'older', 'olive', 'olympics', 'omega', 'omission', 'omnibus', 'onboard', 'oncoming', 'oneself', 'ongoing', 'onion', 'online', 'onslaught', 'onto', 'onward', 'oozed', 'opacity', 'opened', 'opposite', 'optical', 'opus', 'orange', 'orbit', 'orchid', 'orders', 'organs', 'origin', 'ornament', 'orphans', 'oscar', 'ostrich', 'otherwise', 'otter', 'ouch', 'ought', 'ounce', 'ourselves', 'oust', 'outbreak', 'oval', 'oven', 'owed', 'owls', 'owner', 'oxidant', 'oxygen', 'oyster', 'ozone', 'pact', 'paddles', 'pager', 'pairing', 'palace', 'pamphlet', 'pancakes', 'paper', 'paradise', 'pastry', 'patio', 'pause', 'pavements', 'pawnshop', 'payment', 'peaches', 'pebbles', 'peculiar', 'pedantic', 'peeled', 'pegs', 'pelican', 'pencil', 'people', 'pepper', 'perfect', 'pests', 'petals', 'phase', 'pheasants', 'phone', 'phrases', 'physics', 'piano', 'picked', 'pierce', 'pigment', 'piloted', 'pimple', 'pinched', 'pioneer', 'pipeline', 'pirate', 'pistons', 'pitched', 'pivot', 'pixels', 'pizza', 'playful', 'pledge', 'pliers', 'plotting', 'plus', 'plywood', 'poaching', 'pockets', 'podcast', 'poetry', 'point', 'poker', 'polar', 'ponies', 'pool', 'popular', 'portents', 'possible', 'potato', 'pouch', 'poverty', 'powder', 'pram', 'present', 'pride', 'problems', 'pruned', 'prying', 'psychic', 'public', 'puck', 'puddle', 'puffin', 'pulp', 'pumpkins', 'punch', 'puppy', 'purged', 'push', 'putty', 'puzzled', 'pylons', 'pyramid', 'python', 'queen', 'quick', 'quote', 'rabbits', 'racetrack', 'radar', 'rafts', 'rage', 'railway', 'raking', 'rally', 'ramped', 'randomly', 'rapid', 'rarest', 'rash', 'rated', 'ravine', 'rays', 'razor', 'react', 'rebel', 'recipe', 'reduce', 'reef', 'refer', 'regular', 'reheat', 'reinvest', 'rejoices', 'rekindle', 'relic', 'remedy', 'renting', 'reorder', 'repent', 'request', 'reruns', 'rest', 'return', 'reunion', 'revamp', 'rewind', 'rhino', 'rhythm', 'ribbon', 'richly', 'ridges', 'rift', 'rigid', 'rims', 'ringing', 'riots', 'ripped', 'rising', 'ritual', 'river', 'roared', 'robot', 'rockets', 'rodent', 'rogue', 'roles', 'romance', 'roomy', 'roped', 'roster', 'rotate', 'rounded', 'rover', 'rowboat', 'royal', 'ruby', 'rudely', 'ruffled', 'rugged', 'ruined', 'ruling', 'rumble', 'runway', 'rural', 'rustled', 'ruthless', 'sabotage', 'sack', 'sadness', 'safety', 'saga', 'sailor', 'sake', 'salads', 'sample', 'sanity', 'sapling', 'sarcasm', 'sash', 'satin', 'saucepan', 'saved', 'sawmill', 'saxophone', 'sayings', 'scamper', 'scenic', 'school', 'science', 'scoop', 'scrub', 'scuba', 'seasons', 'second', 'sedan', 'seeded', 'segments', 'seismic', 'selfish', 'semifinal', 'sensible', 'september', 'sequence', 'serving', 'session', 'setup', 'seventh', 'sewage', 'shackles', 'shelter', 'shipped', 'shocking', 'shrugged', 'shuffled', 'shyness', 'siblings', 'sickness', 'sidekick', 'sieve', 'sifting', 'sighting', 'silk', 'simplest', 'sincerely', 'sipped', 'siren', 'situated', 'sixteen', 'sizes', 'skater', 'skew', 'skirting', 'skulls', 'skydive', 'slackens', 'sleepless', 'slid', 'slower', 'slug', 'smash', 'smelting', 'smidgen', 'smog', 'smuggled', 'snake', 'sneeze', 'sniff', 'snout', 'snug', 'soapy', 'sober', 'soccer', 'soda', 'software', 'soggy', 'soil', 'solved', 'somewhere', 'sonic', 'soothe', 'soprano', 'sorry', 'southern', 'sovereign', 'sowed', 'soya', 'space', 'speedy', 'sphere', 'spiders', 'splendid', 'spout', 'sprig', 'spud', 'spying', 'square', 'stacking', 'stellar', 'stick', 'stockpile', 'strained', 'stunning', 'stylishly', 'subtly', 'succeed', 'suddenly', 'suede', 'suffice', 'sugar', 'suitcase', 'sulking', 'summon', 'sunken', 'superior', 'surfer', 'sushi', 'suture', 'swagger', 'swept', 'swiftly', 'sword', 'swung', 'syllabus', 'symptoms', 'syndrome', 'syringe', 'system', 'taboo', 'tacit', 'tadpoles', 'tagged', 'tail', 'taken', 'talent', 'tamper', 'tanks', 'tapestry', 'tarnished', 'tasked', 'tattoo', 'taunts', 'tavern', 'tawny', 'taxi', 'teardrop', 'technical', 'tedious', 'teeming', 'tell', 'template', 'tender', 'tepid', 'tequila', 'terminal', 'testing', 'tether', 'textbook', 'thaw', 'theatrics', 'thirsty', 'thorn', 'threaten', 'thumbs', 'thwart', 'ticket', 'tidy', 'tiers', 'tiger', 'tilt', 'timber', 'tinted', 'tipsy', 'tirade', 'tissue', 'titans', 'toaster', 'tobacco', 'today', 'toenail', 'toffee', 'together', 'toilet', 'token', 'tolerant', 'tomorrow', 'tonic', 'toolbox', 'topic', 'torch', 'tossed', 'total', 'touchy', 'towel', 'toxic', 'toyed', 'trash', 'trendy', 'tribal', 'trolling', 'truth', 'trying', 'tsunami', 'tubes', 'tucks', 'tudor', 'tuesday', 'tufts', 'tugs', 'tuition', 'tulips', 'tumbling', 'tunnel', 'turnip', 'tusks', 'tutor', 'tuxedo', 'twang', 'tweezers', 'twice', 'twofold', 'tycoon', 'typist', 'tyrant', 'ugly', 'ulcers', 'ultimate', 'umbrella', 'umpire', 'unafraid', 'unbending', 'uncle', 'under', 'uneven', 'unfit', 'ungainly', 'unhappy', 'union', 'unjustly', 'unknown', 'unlikely', 'unmask', 'unnoticed', 'unopened', 'unplugs', 'unquoted', 'unrest', 'unsafe', 'until', 'unusual', 'unveil', 'unwind', 'unzip', 'upbeat', 'upcoming', 'update', 'upgrade', 'uphill', 'upkeep', 'upload', 'upon', 'upper', 'upright', 'upstairs', 'uptight', 'upwards', 'urban', 'urchins', 'urgent', 'usage', 'useful', 'usher', 'using', 'usual', 'utensils', 'utility', 'utmost', 'utopia', 'uttered', 'vacation', 'vague', 'vain', 'value', 'vampire', 'vane', 'vapidly', 'vary', 'vastness', 'vats', 'vaults', 'vector', 'veered', 'vegan', 'vehicle', 'vein', 'velvet', 'venomous', 'verification', 'vessel', 'veteran', 'vexed', 'vials', 'vibrate', 'victim', 'video', 'viewpoint', 'vigilant', 'viking', 'village', 'vinegar', 'violin', 'vipers', 'virtual', 'visited', 'vitals', 'vivid', 'vixen', 'vocal', 'vogue', 'voice', 'volcano', 'vortex', 'voted', 'voucher', 'vowels', 'voyage', 'vulture', 'wade', 'waffle', 'wagtail', 'waist', 'waking', 'wallets', 'wanted', 'warped', 'washing', 'water', 'waveform', 'waxing', 'wayside', 'weavers', 'website', 'wedge', 'weekday', 'weird', 'welders', 'went', 'wept', 'were', 'western', 'wetsuit', 'whale', 'when', 'whipped', 'whole', 'wickets', 'width', 'wield', 'wife', 'wiggle', 'wildly', 'winter', 'wipeout', 'wiring', 'wise', 'withdrawn', 'wives', 'wizard', 'wobbly', 'woes', 'woken', 'wolf', 'womanly', 'wonders', 'woozy', 'worry', 'wounded', 'woven', 'wrap', 'wrist', 'wrong', 'yacht', 'yahoo', 'yanks', 'yard', 'yawning', 'yearbook', 'yellow', 'yesterday', 'yeti', 'yields', 'yodel', 'yoga', 'younger', 'yoyo', 'zapped', 'zeal', 'zebra', 'zero', 'zesty', 'zigzags', 'zinger', 'zippers', 'zodiac', 'zombie', 'zones', 'zoom']
+TRUNC_WORDS = [w[:3] for w in WORDS]
+N = len(WORDS)
+
+def crc32(s: str) -> int:
+    return binascii.crc32(s.encode('utf-8')) & 0xffffffff
+
+def get_checksum_index(words_list: list[str], prefix_len: int) -> int:
+    trimmed_words = "".join([w[:prefix_len] for w in words_list])
+    checksum = crc32(trimmed_words)
+    return checksum % len(words_list)
+
+def swap_endian_4byte(s: str) -> str:
+    if len(s) != 8:
+        raise ValueError(f"Invalid input length: {len(s)}")
+    return s[6:8] + s[4:6] + s[2:4] + s[0:2]
+
+def encode(seed_hex: str) -> str:
+    # Turns seed's hex to 13-words mnemonic phrase
+    out = []
+    # Seed must be hex string
+    str_copy = seed_hex
+    # Swap endian for every 8 characters (4 bytes)
+    for j in range(0, len(str_copy), 8):
+        part = str_copy[j:j+8]
+        str_copy = str_copy[:j] + swap_endian_4byte(part) + str_copy[j+8:]
+        
+    for i in range(0, len(str_copy), 8):
+        x = int(str_copy[i:i+8], 16)
+        w1 = x % N
+        w2 = (x // N + w1) % N
+        w3 = ((x // N) // N + w2) % N
+        out.extend([WORDS[w1], WORDS[w2], WORDS[w3]])
+        
+    # Checksum word
+    out.append(out[get_checksum_index(out, 3)])
+    return " ".join(out)
+
+def decode(mnemonic: str) -> str:
+    # Turns 13-words mnemonic phrase to seed's hex
+    wlist = mnemonic.strip().split()
+    if len(wlist) < 12:
+        raise ValueError("Invalid number of words in mnemonic. Expected 13 words, got less.")
+        
+    # Checksum word
+    checksum_word = wlist.pop()
+    
+    out = ""
+    for i in range(0, len(wlist), 3):
+        w1_val = wlist[i]
+        w2_val = wlist[i+1]
+        w3_val = wlist[i+2]
+        
+        w1 = TRUNC_WORDS.index(w1_val[:3]) if w1_val[:3] in TRUNC_WORDS else -1
+        w2 = TRUNC_WORDS.index(w2_val[:3]) if w2_val[:3] in TRUNC_WORDS else -1
+        w3 = TRUNC_WORDS.index(w3_val[:3]) if w3_val[:3] in TRUNC_WORDS else -1
+        
+        if w1 == -1 or w2 == -1 or w3 == -1:
+            raise ValueError("Invalid word in mnemonic")
+            
+        x = w1 + N * ((N - w1 + w2) % N) + N * N * ((N - w2 + w3) % N)
+        if x % N != w1:
+            raise ValueError("Couldn't decode mnemonic")
+            
+        hex_val = f"{x:08x}"
+        out += swap_endian_4byte(hex_val)
+        
+    # Verify checksum
+    index = get_checksum_index(wlist, 3)
+    expected_checksum_word = wlist[index]
+    if expected_checksum_word[:3] != checksum_word[:3]:
+        raise ValueError("Invalid checksum last word in mnemonic")
+        
+    return out

session_python/network.py

@@ -0,0 +1,193 @@
+import time
+import random
+import requests
+import binascii
+import urllib3
+from typing import List, Dict, Any, Union, Optional
+from urllib.parse import urlparse
+
+# Suppress self-signed certificate warnings for storage node connections
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+# Seeds list
+SEEDS = [
+    {"url": "seed1.getsession.org"},
+    {"url": "seed2.getsession.org"},
+    {"url": "seed3.getsession.org"}
+]
+
+class NetworkError(Exception):
+    pass
+
+class SnodeFetchError(NetworkError):
+    pass
+
+class SnodeRPCError(NetworkError):
+    pass
+
+class SessionNetwork:
+    def __init__(self, proxy: Optional[str] = None):
+        """
+        proxy: proxy URL (e.g. 'socks5h://user:pass@host:port' or 'http://host:port')
+        """
+        self.proxy = proxy
+        self.session = requests.Session()
+        if proxy:
+            # Normalize socks5 to socks5h for remote DNS resolution
+            if proxy.startswith("socks5://"):
+                proxy = "socks5h://" + proxy[len("socks5://"):]
+            self.session.proxies = {
+                "http": proxy,
+                "https": proxy
+            }
+            
+    def request(self, method: str, url: str, json_data: dict, headers: Optional[dict] = None, timeout: int = 10) -> dict:
+        default_headers = {
+            "User-Agent": "WhatsApp",
+            "Accept-Language": "en-us",
+            "Content-Type": "application/json"
+        }
+        if headers:
+            default_headers.update(headers)
+            
+        try:
+            # We disable SSL certificate verification for storage node RPCs because
+            # storage nodes use self-signed certificates in the Session network.
+            response = self.session.post(
+                url,
+                json=json_data,
+                headers=default_headers,
+                timeout=timeout,
+                verify=False
+            )
+            
+            if response.status_code == 421:
+                raise SnodeRPCError("421 handled. Retry this request with a new snode.")
+                
+            if not response.ok:
+                raise SnodeRPCError(f"HTTP Error {response.status_code}: {response.text}")
+                
+            return response.json()
+        except requests.RequestException as e:
+            raise SnodeFetchError(f"Network request failed: {e}")
+
+    def get_snodes_from_seeds(self) -> List[Dict[str, Any]]:
+        # Randomize seeds list
+        seeds_pool = list(SEEDS)
+        random.shuffle(seeds_pool)
+        
+        for seed in seeds_pool:
+            url = f"http://{seed['url']}/json_rpc"
+            body = {
+                "jsonrpc": "2.0",
+                "id": 0,
+                "method": "get_n_service_nodes",
+                "params": {
+                    "fields": {
+                        "public_ip": True,
+                        "storage_port": True,
+                        "pubkey_x25519": True,
+                        "pubkey_ed25519": True
+                    }
+                }
+            }
+            try:
+                res = self.request("POST", url, body, timeout=8)
+                if "result" in res and "service_node_states" in res["result"]:
+                    snodes = res["result"]["service_node_states"]
+                    # Filter out nodes with invalid IP
+                    filtered_snodes = [
+                        s for s in snodes 
+                        if s.get("public_ip") and s["public_ip"] != "0.0.0.0"
+                    ]
+                    if filtered_snodes:
+                        return filtered_snodes
+            except Exception as e:
+                # Fallback to next seed
+                continue
+                
+        raise SnodeFetchError("Failed to fetch service nodes from all seed nodes.")
+
+    def snode_batch_request(
+        self, 
+        snode: Dict[str, Any], 
+        requests_list: List[Dict[str, Any]], 
+        timeout: int = 10,
+        method: str = "batch"
+    ) -> List[Dict[str, Any]]:
+        """
+        snode: dict containing public_ip, storage_port
+        requests_list: list of subrequests, e.g. [{"method": "get_swarm", "params": {...}}]
+        """
+        url = f"https://{snode['public_ip']}:{snode['storage_port']}/storage_rpc/v1"
+        body = {
+            "jsonrpc": "2.0",
+            "method": method,
+            "params": {
+                "requests": requests_list
+            }
+        }
+        res = self.request("POST", url, body, timeout=timeout)
+        if "results" not in res:
+            raise SnodeRPCError(f"Invalid snode RPC response (no 'results'): {res}")
+            
+        return res["results"]
+
+    def upload_attachment(self, data: bytes, timeout: int = 30) -> dict:
+        url = "http://filev2.getsession.org/file"
+        try:
+            response = self.session.post(
+                url,
+                data=data,
+                headers={"User-Agent": "WhatsApp"},
+                timeout=timeout
+            )
+            if not response.ok:
+                raise NetworkError(f"Upload failed with status code {response.status_code}")
+            res_json = response.json()
+            file_id = res_json["id"]
+            return {
+                "id": int(file_id),
+                "url": f"http://filev2.getsession.org/file/{file_id}"
+            }
+        except Exception as e:
+            raise NetworkError(f"Failed to upload attachment: {e}")
+
+    def download_attachment(self, file_id: Union[int, str], timeout: int = 30) -> bytes:
+        url = f"http://filev2.getsession.org/file/{file_id}"
+        try:
+            response = self.session.get(
+                url,
+                headers={"User-Agent": "WhatsApp"},
+                timeout=timeout
+            )
+            if not response.ok:
+                raise NetworkError(f"Download failed with status code {response.status_code}")
+            return response.content
+        except Exception as e:
+            raise NetworkError(f"Failed to download attachment: {e}")
+
+    def sogs_request(
+        self,
+        host: str,
+        endpoint: str,
+        method: str,
+        body: Optional[Union[str, bytes]] = None,
+        headers: Optional[dict] = None,
+        timeout: int = 15
+    ) -> dict:
+        url = host + endpoint
+        default_headers = {"User-Agent": "WhatsApp"}
+        if headers:
+            default_headers.update(headers)
+        try:
+            res = self.session.request(
+                method=method,
+                url=url,
+                data=body,
+                headers=default_headers,
+                timeout=timeout
+            )
+            return res.json()
+        except Exception as e:
+            raise NetworkError(f"Failed SOGS request: {e}")