מדריך הגנה על פרויקט הגמר

Browser   ──HTTPS─►  Flask :5000  ──┐
                                    │  אותו תהליך, אותו זיכרון
Desktop   ──TCP─────►  NotificationHub :5001
Desktop   ◄──push──── (events: shared / file_changed)
Desktop   ──HTTPS───►  Flask :5000  (להורדת קבצים)

                       │
                       ▼
              Firestore (מטא-דאטה)
              Google Cloud Storage (בתים מוצפנים)

from abc import ABC, abstractmethod

class StorageItem(ABC):
    """Common contract for File and Directory items."""

    def __init__(self, doc_id, owner, parent_directory_id=None, created_at=None):
        self._id = doc_id
        self._owner = owner
        self._parent_directory_id = parent_directory_id
        self._created_at = created_at or datetime.utcnow().isoformat()

    @abstractmethod
    def item_type(self):
        """Return 'file' or 'directory'."""

    @abstractmethod
    def display_name(self):
        """Human-readable name."""

    @abstractmethod
    def permanently_delete(self):
        """Hard-delete from GCS + Firestore."""

StorageItem היא מחלקה מופשטת — היא יורשת מ-ABC ומגדירה מתודות עם @abstractmethod. זה אומר שלא ניתן ליצור ממנה אובייקט ישירות; חייבים לרשת ממנה ולממש את כל המתודות המופשטות. זו הפשטה (Abstraction): היא חוזה — אומרת "כל פריט אחסון חייב לדעת להגיד את הסוג שלו, להציג שם, ולמחוק את עצמו". הקובץ (FileItem) והתיקייה (DirectoryItem) הם מימושים קונקרטיים של החוזה הזה.

class FileItem(StorageItem):
    """Represents an uploaded file."""

    def __init__(self, doc_id, owner, filename, stored_filename, gcs_path,
                 size, content_type, directory_id=None, uploaded_at=None,
                 wrapped_dek=None):
        # Inheritance — pass shared fields up to StorageItem.__init__
        super().__init__(doc_id, owner,
                         parent_directory_id=directory_id,
                         created_at=uploaded_at)
        self._filename = filename
        self._stored_filename = stored_filename
        self._gcs_path = gcs_path
        self._size = size
        self._content_type = content_type
        self._wrapped_dek = wrapped_dek

הקריאה super().__init__(...) מעבירה את השדות המשותפים למחלקת-העל. FileItem מקבל "בחינם" את _id, _owner, _parent_directory_id ו-_created_at + את המתודה check_ownership וה-soft_delete.

class AdminUser(User):
    """The single admin account."""

    def __init__(self, username, password_hash, first_name='', last_name='',
                 profile_picture=None, doc_id=None,
                 public_key=None, wrapped_private_key=None):
        super().__init__(username, password_hash, first_name, last_name,
                         profile_picture, doc_id, public_key, wrapped_private_key)

    # Polymorphism — override of User.is_admin()
    def is_admin(self):
        return True

AdminUser יורש מ-User. הוא דורס רק מתודה אחת: is_admin(). אצל User הרגיל המתודה הזו בודקת username == 'admin', אצל AdminUser היא תמיד מחזירה True. הקוד שמשתמש במשתמש (ה-decorator admin_required) קורא user.is_admin() בלי לדעת אם זה User או AdminUser — וזה בדיוק פולימורפיזם.

def soft_delete(self, parent_directory_id_override=None, path=''):
    """Move this item into the recycle bin (30-day retention)."""
    expiration_date = datetime.utcnow() + timedelta(days=30)
    recycle_bin_data = {
        'item_id':   self._id,
        'item_type': self.item_type(),       # Polymorphism — subclass-specific
        'item_name': self.display_name(),    # Polymorphism — subclass-specific
        'original_data': self.to_dict(),     # Polymorphism — subclass-specific
        'deleted_by': self._owner,
        'deleted_at': datetime.utcnow().isoformat(),
        'expires_at': expiration_date.isoformat(),
        ...
    }
    ref = recycle_bin_collection.add(recycle_bin_data)
    self._collection_ref().document(self._id).delete()   # Polymorphism
    return ref[1].id

שימי לב: soft_delete נכתבת פעם אחת במחלקת-העל. היא קוראת ל-self.item_type(), self.display_name(), self._collection_ref(). בזמן ריצה Python בודק מהו האובייקט בפועל ומפעיל את המתודה הנכונה — אם זה FileItem היא מחזירה 'file' ומחקת מ-files; אם זה DirectoryItem היא מחזירה 'directory' ומחקת מ-directories. אותו קוד, התנהגות שונה. זה הלב של פולימורפיזם.

class User:
    def __init__(self, username, password_hash, ...):
        self._username = username
        self._password_hash = password_hash    # פרטי — קידומת underscore

    @property
    def username(self):
        return self._username                  # קריאה בלבד, אי-אפשר לדרוס מבחוץ

    def set_password(self, plain_password):
        # Encapsulation — הדרך היחידה להגדיר סיסמה היא דרך המתודה הזו,
        # שמבטיחה שהסיסמה תמיד נשמרת מוצפנת (hashed), אף פעם לא בטקסט גלוי.
        self._password_hash = generate_password_hash(plain_password, method='scrypt')

    def verify_password(self, plain_password):
        if not self._password_hash:
            return False
        return check_password_hash(self._password_hash, plain_password)

למה זה חשוב? כי אם הסיסמה הייתה public, מתכנת אחר בקוד היה יכול בטעות לכתוב user.password = "1234" ולשמור סיסמה בטקסט גלוי במסד הנתונים. הכימוס מאלץ אותו ללכת דרך set_password — שמכריחה hashing. הקופסה הסגורה הזו שומרת על אינווריאנט (חוק שאסור להפר): "סיסמאות תמיד מוצפנות".

class DesktopApp:
    def __init__(self, root):
        self.root = root
        self.api = None       # ייווצר ApiClient כשנתחבר
        self.nc = None        # ייווצר NotificationClient כשנתחבר
        self._shared_files = []
        ...

    def _connect_worker(self, server, username, password):
        api = ApiClient(server)        # אובייקט מוכל
        api.login(username, password)
        nc = NotificationClient()       # אובייקט מוכל
        nc.connect(host, SOCKET_PORT, api.token)

זו הכלה: DesktopApp לא יורש מ-ApiClient או מ-NotificationClient, אלא מחזיק בהם בתוכו. זה ההפך מהורשה — במקום "DesktopApp הוא ApiClient", זה "DesktopApp יש לו ApiClient". זה גם מאפשר לבדוק כל מחלקה בנפרד.

"""
Raw TCP socket server for real-time push notifications.

This is intentionally separate from Flask: it listens on its own port (default 5001)
and speaks a tiny hand-rolled application protocol -- newline-delimited JSON, one
object per line -- over a plain TCP socket (Python's `socket` module).

Protocol (each message is one UTF-8 JSON object terminated by '\n'):

    Client -> Server : {"type": "auth", "token": ""}   (must be first message)
    Client -> Server : {"type": "ping"}
    Server -> Client : {"type": "auth_ok", "username": "bob"}
    Server -> Client : {"type": "auth_error", "error": "Invalid token"}  then close
    Server -> Client : {"type": "pong"}
    Server -> Client : {"type": "shared", ...}        (someone shared an item with you)
    Server -> Client : {"type": "file_changed", ...}  (one of your files changed)
"""

זה הפרוטוקול שלי. כל הודעה היא אובייקט JSON אחד, מסתיימת ב-\n. המסר הראשון מהלקוח חייב להיות אימות עם ה-JWT. אם האימות נכשל, השרת שולח auth_error וסוגר את הסוקט. בזמן ריצה אמצעי: ping/pong כדי שאדע אם הצד השני עוד שם.

def start(self, host="127.0.0.1", port=5001):
    """Bind, listen, and spawn the accept loop on a daemon thread."""
    srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    srv.bind((host, port))
    srv.listen(16)
    self._server_socket = srv
    thread = threading.Thread(
        target=self._accept_loop, name="socket-accept-loop", daemon=True
    )
    thread.start()

def _accept_loop(self):
    while True:
        try:
            conn, addr = self._server_socket.accept()
        except OSError:
            break
        threading.Thread(
            target=self._handle_client,
            args=(conn, addr),
            name=f"socket-client-{addr}",
            daemon=True,
        ).start()

4 שלבים קלאסיים של שרת TCP:

1. socket(AF_INET, SOCK_STREAM) — AF_INET = IPv4, SOCK_STREAM = TCP (אם הייתי רוצה UDP זה היה SOCK_DGRAM).
2. bind — קושר את הסוקט לכתובת IP ופורט.
3. listen(16) — מתחיל להאזין, מכין תור של עד 16 חיבורים שמחכים.
4. accept() — חוסם עד שלקוח מתחבר; מחזיר סוקט חדש לתקשורת עם אותו לקוח ספציפי.

def connect(self, host, port, token, timeout=10):
    """Open the socket, authenticate, and start the receive loop."""
    self._stop.clear()
    sock = socket.create_connection((host, port), timeout=timeout)
    sock.settimeout(None)
    self._sock = sock
    self._reader = _LineReader(sock)

    self._send({"type": "auth", "token": token})
    response = self._read_message()
    if not response or response.get("type") != "auth_ok":
        err = (response or {}).get("error", "authentication failed")
        self.close()
        raise ConnectionError(err)

    self._recv_thread = threading.Thread(target=self._recv_loop, daemon=True)
    self._recv_thread.start()
    self._ping_thread = threading.Thread(target=self._ping_loop, daemon=True)
    self._ping_thread.start()
    return response

הלקוח: יוצרת חיבור (socket.create_connection), שולחת מסר אימות עם ה-JWT, מחכה ל-auth_ok. אם הכל בסדר — מפעילה שני threads ברקע: אחד מקבל הודעות מהשרת, אחד שולח ping כל 20 שניות.

class _LineReader:
    """Buffers bytes off a socket and yields one '\n'-terminated line at a time."""
    def __init__(self, conn):
        self._conn = conn
        self._buf = b""

    def readline(self):
        while b"\n" not in self._buf:
            chunk = self._conn.recv(4096)
            if not chunk:
                line, self._buf = self._buf, b""
                return line.decode("utf-8", "replace") if line else ""
            self._buf += chunk
        line, _, self._buf = self._buf.partition(b"\n")
        return line.decode("utf-8", "replace")

בעיה ב-TCP: TCP הוא זרם בייטים, לא הודעות. אם השרת שלח שתי הודעות, אני יכולה לקבל אותן ב-recv אחד; אם השרת שלח הודעה אחת ארוכה, אני יכולה לקבל אותה בשני recv-ים. אז אני צריכה שכבת פריימינג שתחלק את הזרם להודעות. הפתרון שלי: כל הודעה מסתיימת ב-\n, ויש לי באפר שאוסף בייטים ומחפש \n. כשיש — חותך את ההודעה הזו ושומר את השאר לבאפר לפעם הבאה. זו שכבת הפרוטוקול שאני יצרתי.

def push_to_user(self, username, event):
    """Send one JSON event to every live socket for `username`."""
    line = (json.dumps(event) + "\n").encode("utf-8")
    with self._lock:
        conns = list(self._connections.get(username, ()))
    dead = []
    for conn in conns:
        try:
            conn.sendall(line)
        except OSError:
            dead.append(conn)
    for conn in dead:
        self.unregister(username, conn)
        try:
            conn.close()
        except OSError:
            pass

הפונקציה הזו נקראת מתוך נתיבי Flask — למשל ב-server/routes/sharing.py:130: notification_hub.push_to_user(share_with_username, {...}). כלומר: כשמשתמש עושה Share דרך ה-REST API, השרת מסתכל בטבלת החיבורים הפעילים, ואם המקבל מחובר ב-Desktop — שולח לו דחיפה דרך הסוקט הפתוח. זה לא היה אפשרי על HTTP טהור.

def _accept_loop(self):
    while True:
        try:
            conn, addr = self._server_socket.accept()
        except OSError:
            break  # listening socket closed -> shut down the loop
        threading.Thread(
            target=self._handle_client,
            args=(conn, addr),
            name=f"socket-client-{addr}",
            daemon=True,
        ).start()

daemon=True אומר שאם התהליך הראשי מסתיים, גם ה-threads האלה ייסגרו מיד. בלי daemon=True התהליך לא יוכל להיסגר עד שכל ה-threads ייסגרו לבד.

def fetch_blob(file_info):
    if not file_info['gcs_path']:
        return None
    blob = gcs_bucket.blob(file_info['gcs_path'])
    if not blob.exists():
        return None
    return (file_info['relative'],
            decrypt_stored_file(blob.download_as_bytes(), file_info.get('wrapped_dek')))

zip_buffer = io.BytesIO()
files_added = 0
total_bytes = 0
with zipfile.ZipFile(zip_buffer, 'w', zipfile.ZIP_DEFLATED) as zf:
    with ThreadPoolExecutor(max_workers=8) as pool:
        futures = [pool.submit(fetch_blob, f) for f in all_files]
        for future in as_completed(futures):
            result = future.result()
            if result is None:
                continue
            relative, data = result
            total_bytes += len(data)
            if total_bytes > MAX_ZIP_BYTES:
                raise ZipLimitExceeded(...)
            zf.writestr(relative, data)
            files_added += 1

למה Thread Pool ולא threads רגילים? כי יצירת thread חדש לכל קובץ עולה לי הרבה במשאבים, וזה לא נכון להפעיל 200 threads בו-זמנית כש-GCS יכול לחנוק את ההורדות שלי. ThreadPoolExecutor(max_workers=8) מבטיח שמקסימום 8 הורדות יקרו במקביל, בעוד הקבצים האחרים מחכים בתור.
למה לא לעשות את הכתיבה ל-Zip במקביל? כי zipfile.ZipFile לא thread-safe. רק ההורדות (I/O ברשת) רצות במקביל; הכתיבה לזיפ נשארת ב-thread הראשי.

def __init__(self):
    self._connections = {}
    self._lock = threading.Lock()
    self._server_socket = None

def register(self, username, conn):
    with self._lock:
        self._connections.setdefault(username, set()).add(conn)

def unregister(self, username, conn):
    with self._lock:
        conns = self._connections.get(username)
        if conns:
            conns.discard(conn)
            if not conns:
                del self._connections[username]

טבלת ה-_connections משותפת בין כל ה-threads — accept loop רושם, handler מוסיף ומסיר, push_to_user קורא. אם שני threads ישנו אותה בו-זמנית — Race Condition. threading.Lock מבטיח שרק thread אחד יכול להיות בתוך with self._lock: בכל רגע נתון. זה סעיף קריטי (critical section).

def _download_selected(self):
    sel = self.shared_list.curselection()
    if not sel:
        messagebox.showinfo("Download", "Select a file first.")
        return
    index = sel[0]
    f = self._shared_files[index]
    dest = filedialog.asksaveasfilename(initialfile=f.get("filename", "download"))
    if not dest:
        return
    try:
        self.api.download_shared_file(f["id"], dest)
    except ApiError as e:
        messagebox.showerror("Download failed", str(e))
        return
    self._log(f"Downloaded \"{f.get('filename', '')}\" to {dest}")

filedialog.asksaveasfilename פותח את החלון של מערכת ההפעלה לבחירת מיקום שמירה. אחר כך אני קוראת ל-self.api.download_shared_file שכותבת את הבתים ל-open(dest, "wb"). זו גישה ישירה למערכת הקבצים של המחשב — בדיוק מה שהמחוון דורש.

# Initialize Firebase Admin SDK
cred_path = os.path.join(os.path.dirname(__file__), 'cloudstorageproject-privatekey.json')
cred = credentials.Certificate(cred_path)
firebase_admin.initialize_app(cred)

# Get Firestore database
db = firestore.client()
users_collection = db.collection('users')
items_collection = db.collection('items')
directories_collection = db.collection('directories')
shares_collection = db.collection('shares')
favorites_collection = db.collection('favorites')
recycle_bin_collection = db.collection('recycle_bin')

# Initialize Google Cloud Storage
GCS_BUCKET_NAME = 'clientstorage-6978a.firebasestorage.app'
storage_client = storage.Client.from_service_account_json(cred_path)
gcs_bucket = storage_client.bucket(GCS_BUCKET_NAME)

זה שימוש ב-API: אני שולחת בקשות מאומתות לשירותים חיצוניים של Google ומקבלת תוצאות. בשונה ממסד נתונים מקומי שאני מנהלת בעצמי, ה-APIs האלה מטפלים בהפצה גלובלית, בעמידה בעומס, וב-replication.

def generate_dek() -> bytes:
    """Generate a fresh per-file Data Encryption Key (a Fernet key)."""
    return Fernet.generate_key()

def encrypt_with_dek(plaintext: bytes, dek: bytes) -> bytes:
    """Encrypt file bytes under a per-file DEK."""
    return Fernet(dek).encrypt(plaintext)

def decrypt_with_dek(ciphertext: bytes, dek: bytes) -> bytes:
    """Decrypt file bytes that were encrypted under the given DEK."""
    return Fernet(dek).decrypt(ciphertext)

Fernet זה AES-128 ב-CBC mode + HMAC-SHA256 — הצפנה סימטרית מאומתת (Authenticated Encryption). זה אומר שלא רק הקובץ מוצפן, אלא יש חתימה שמוודאת שהוא לא שונה. אם מישהו מנסה לשנות בייט אחד ב-ciphertext, ה-HMAC ייכשל ו-decrypt יזרוק שגיאה.

def rsa_wrap_dek(dek: bytes, public_pem: bytes) -> str:
    """RSA-OAEP-encrypt a DEK under a recipient's public key."""
    if isinstance(public_pem, str):
        public_pem = public_pem.encode('utf-8')
    public_key = serialization.load_pem_public_key(public_pem)
    ciphertext = public_key.encrypt(
        dek,
        padding.OAEP(
            mgf=padding.MGF1(algorithm=hashes.SHA256()),
            algorithm=hashes.SHA256(),
            label=None,
        ),
    )
    return base64.b64encode(ciphertext).decode('utf-8')

def rsa_unwrap_dek(wrapped_b64: str, private_pem: bytes) -> bytes:
    """Reverse rsa_wrap_dek using the recipient's private-key PEM."""
    if isinstance(private_pem, str):
        private_pem = private_pem.encode('utf-8')
    private_key = serialization.load_pem_private_key(private_pem, password=None)
    return private_key.decrypt(
        base64.b64decode(wrapped_b64),
        padding.OAEP(
            mgf=padding.MGF1(algorithm=hashes.SHA256()),
            algorithm=hashes.SHA256(),
            label=None,
        ),
    )

איך עובד שיתוף קובץ?

1. אני (אליס) מעלה קובץ. נוצר DEK חדש. הקובץ מוצפן עם ה-DEK. ה-DEK נעטף ב-Master KEK ונשמר ב-Firestore.
2. אני משתפת עם בוב. השרת מביא את המפתח הציבורי של בוב, פותח את ה-DEK עם ה-Master KEK, ועוטף אותו שוב עם המפתח הציבורי של בוב (RSA-OAEP). זה נשמר במסמך השיתוף.
3. בוב מוריד את הקובץ. השרת לוקח את ה-DEK העטוף ב-RSA, פותח אותו עם המפתח הפרטי של בוב (גם הוא היה עטוף ב-Master KEK). עם ה-DEK הזה הוא מפענח את הקובץ.

def set_password(self, plain_password):
    # Pin scrypt explicitly so a future Werkzeug default change cannot
    # silently weaken hashing. check_password_hash still auto-detects the
    # algorithm prefix on verify, so old pbkdf2 hashes keep working.
    self._password_hash = generate_password_hash(plain_password, method='scrypt')

def verify_password(self, plain_password):
    if not self._password_hash:
        return False
    return check_password_hash(self._password_hash, plain_password)

סיסמה אף פעם לא מוצפנת — היא מ-Hash. ההבדל: הצפנה היא דו-כיוונית (אפשר להפך), Hash הוא חד-כיווני. מנסחר אקראי (salt) מתווסף לפני ה-Hash כדי שאם יש שני משתמשים עם אותה סיסמה, ה-Hash יוצא שונה.
למה scrypt ולא MD5 או SHA-256? כי MD5 ו-SHA הם מהירים מדי — תוקף שגונב את מסד הנתונים יכול לנסות מיליארדי סיסמאות בשנייה. scrypt תוכנן להיות איטי בכוונה ולדרוש זיכרון רב — מה שמקשה על מתקפות brute-force.

def _resolve_user(token):
    from routes.auth import JWT_ISSUER, JWT_AUDIENCE
    try:
        data = jwt.decode(
            token,
            app.config['SECRET_KEY'],
            algorithms=['HS256'],
            issuer=JWT_ISSUER,
            audience=JWT_AUDIENCE,
        )
    except jwt.ExpiredSignatureError:
        return None, ({"error": "Token has expired"}, 401)
    except jwt.InvalidTokenError:
        return None, ({"error": "Invalid token"}, 401)
    ...
    revoke_after = user_data.get('token_revoked_after')
    iat = data.get('iat')
    if revoke_after and iat is not None:
        try:
            iat_dt = datetime.utcfromtimestamp(int(iat))
            revoke_dt = datetime.fromisoformat(revoke_after)
            if iat_dt <= revoke_dt:
                return None, ({"error": "Token has been revoked"}, 401)
        except (ValueError, TypeError):
            return None, ({"error": "Token has been revoked"}, 401)

JWT (JSON Web Token) = "תעודה" שהשרת חתם דיגיטלית, ומכילה את שם המשתמש + זמן הוצאה + זמן תפוגה. הלקוח שולח את התעודה בכל בקשה ב-Header של Authorization. השרת מפענח, מוודא את החתימה (HS256 = HMAC-SHA256 עם SECRET_KEY), בודק שלא פג תוקף, ושלא שוללה. אם הכל בסדר — יודע מי המשתמש.
הסוד שעל פיו חותמים נטען מ-config.py:14 שמייצר אותו אקראית בפעם הראשונה ושומר ב-server/.secret_key (לא ב-git!).

def check_ownership(self, username):
    """True iff this item belongs to the given user."""
    return self._owner == username

זה לב הלב של מודל ההרשאות: לכל קובץ ולכל תיקייה יש שדה owner, וכל פעולה (הורדה, מחיקה, שיתוף) קוראת ל-check_ownership(current_user['username']). הנתיבים מחזירים 403 או 404 אם הבדיקה נכשלת. כך לא ניתן לגשת לקובץ של משתמש אחר רק כי יודעים את ה-ID שלו.

class DesktopApp:
    def __init__(self, root):
        self.root = root
        self.root.title("CloudStorage - Notifications")
        self.root.geometry("560x520")

        self.api = None
        self.nc = None
        self._shared_files = []

        self._build_login_frame()
        self._build_main_frame()
        self._show_login()

    def _build_login_frame(self):
        self.login_frame = ttk.Frame(self.root, padding=20)
        ttk.Label(self.login_frame, text="Connect to CloudStorage",
                  font=("Segoe UI", 14, "bold")).grid(...)
        ...

    def _build_main_frame(self):
        self.main_frame = ttk.Frame(self.root, padding=12)
        self.status_label = ttk.Label(self.main_frame, ...)
        self.notif_text = scrolledtext.ScrolledText(self.main_frame, height=10, ...)
        ...
        self.shared_list = tk.Listbox(self.main_frame, height=8)
        ...

שני מצבים: דף התחברות ודף ראשי. אחרי התחברות מוצלחת — עוברים לדף הראשי, רואים בלוק "Live notifications" שמתעדכן בזמן אמת מהסוקט, ורשימת קבצים ששותפו איתי.

def _poll_events(self):
    """Drain the socket client's event queue on the UI thread."""
    if self.nc is None:
        return
    try:
        while True:
            event = self.nc.events.get_nowait()
            self._handle_event(event)
    except Exception:
        pass  # queue empty
    self.root.after(150, self._poll_events)

def _handle_event(self, event):
    etype = event.get("type")
    if etype == "shared":
        owner = event.get("owner", "someone")
        name = event.get("item_name", "an item")
        self._log(f"{owner} shared \"{name}\" with you.")
        self._refresh_shared()
        messagebox.showinfo("New share", f'{owner} shared "{name}" with you.')

בעיה: ה-thread שמקבל הודעות מהסוקט הוא לא ה-UI thread. Tkinter לא thread-safe — אם הייתי קוראת ל-messagebox.showinfo מתוך ה-thread של הסוקט, ה-UI היה קורס. פתרון: ה-thread של הסוקט שם הודעות בתור (queue.Queue), ו-root.after(150, ...) רץ ב-UI thread כל 150 מילי-שניות ושולף הודעות מהתור.