binarycookies 2.2.1__tar.gz → 2.3.0__tar.gz

{binarycookies-2.2.1 → binarycookies-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.1
 Name: binarycookies
-Version: 2.2.1
+Version: 2.3.0
 Summary: Python Binary Cookies (de)serializer
 Author: Daniel Tom
 Author-email: d.e.tom89@gmail.com
@@ -10,10 +10,8 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: pydantic (>=2.0.0,<3.0.0)
-Requires-Dist: typer (>=0.12.3,<0.17.0)
+Requires-Dist: typer (>=0.12.3,<0.21.0)
 Description-Content-Type: text/markdown
 
 [![Github Actions Status](https://github.com/dan1elt0m/binary-cookies-reader/workflows/test/badge.svg)](https://github.com/dan1elt0m/binary-cookies-reader/actions/workflows/test.yml)
@@ -24,6 +22,9 @@ Description-Content-Type: text/markdown
 
 CLI tool and Python library for reading and writing Binary Cookies.
 
+### Documentation
+For detailed documentation, please visit the [Binary Cookies Documentation](https://dan1elt0m.github.io/binarycookies/)
+
 ### Requirements
 
 - Python >= 3.9
@@ -61,49 +62,11 @@ Output:
   }
 ]
 ```
-
-
-### ASCII Output
-
-`ascii` output is also possible with the --output ascii flag.
-
-Example usage:
-```sh
-bcparser path/to/cookies.binarycookies --output ascii
-```
-
-Example output ASCII:
-```text
-Name: session_id
-Value: abc123
-URL: https://example.com
-Path: /
-Created: 2023-10-01T12:34:56+00:00
-Expires: 2023-12-31T23:59:59+00:00
-Flag: Secure
-----------------------------------------
-Name: user_token
-Value: xyz789
-URL: https://example.com
-Path: /account
-Created: 2023-10-01T12:34:56+00:00
-Expires: 2023-12-31T23:59:59+00:00
-Flag: HttpOnly
-----------------------------------------
-```
-### Netscape Output
-For `netscape` output use the --output netscape flag.
-Example usage:
-```sh
-bcparser path/to/cookies.binarycookies --output netscape
-```
-
-Example output Netscape:
-```netscape 
-# Netscape HTTP Cookie File
-example.com	FALSE	/	TRUE	1704067199	session_id	abc123
-example.com	FALSE	/account	FALSE	1704067199	user_token	xyz789
-```
+#### Output formats
+The CLI supports multiple output formats using the --output flag.
+- `json` (default): Outputs cookies in JSON format.
+- `ascii`: Outputs cookies in a human-readable ASCII format with each cookie property on a separate line.
+- `netscape`: Outputs cookies in the Netscape cookie file format.
 
 ### Basic Usage Python
 
@@ -135,6 +98,18 @@ with open("path/to/cookies.binarycookies", "wb") as f:
     binarycookies.dump(cookie, f)
 ```
 
+### Ethical Use & Responsible Handling
+This project is intended for lawful, ethical use only. Typical, appropriate uses include:
+- Inspecting Binary Cookies from your own devices or data you are authorized to access
+- DFIR, QA, and security testing performed with explicit, written permission
+- Educational/research work on datasets that are owned by you, anonymized, or publicly released for that purpose
+
+You must not use this tool to:
+- Access, extract, modify, or distribute cookies from systems or accounts you do not own or have permission to analyze
+- Bypass authentication, session management, DRM, or other technical controls
+- Enable tracking, stalking, doxxing, fraud, or other privacy-invasive or harmful activities
+
+
 ### License
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
 

{binarycookies-2.2.1 → binarycookies-2.3.0}/README.md

@@ -6,6 +6,9 @@
 
 CLI tool and Python library for reading and writing Binary Cookies.
 
+### Documentation
+For detailed documentation, please visit the [Binary Cookies Documentation](https://dan1elt0m.github.io/binarycookies/)
+
 ### Requirements
 
 - Python >= 3.9
@@ -43,49 +46,11 @@ Output:
   }
 ]
 ```
-
-
-### ASCII Output
-
-`ascii` output is also possible with the --output ascii flag.
-
-Example usage:
-```sh
-bcparser path/to/cookies.binarycookies --output ascii
-```
-
-Example output ASCII:
-```text
-Name: session_id
-Value: abc123
-URL: https://example.com
-Path: /
-Created: 2023-10-01T12:34:56+00:00
-Expires: 2023-12-31T23:59:59+00:00
-Flag: Secure
-----------------------------------------
-Name: user_token
-Value: xyz789
-URL: https://example.com
-Path: /account
-Created: 2023-10-01T12:34:56+00:00
-Expires: 2023-12-31T23:59:59+00:00
-Flag: HttpOnly
-----------------------------------------
-```
-### Netscape Output
-For `netscape` output use the --output netscape flag.
-Example usage:
-```sh
-bcparser path/to/cookies.binarycookies --output netscape
-```
-
-Example output Netscape:
-```netscape 
-# Netscape HTTP Cookie File
-example.com	FALSE	/	TRUE	1704067199	session_id	abc123
-example.com	FALSE	/account	FALSE	1704067199	user_token	xyz789
-```
+#### Output formats
+The CLI supports multiple output formats using the --output flag.
+- `json` (default): Outputs cookies in JSON format.
+- `ascii`: Outputs cookies in a human-readable ASCII format with each cookie property on a separate line.
+- `netscape`: Outputs cookies in the Netscape cookie file format.
 
 ### Basic Usage Python
 
@@ -117,6 +82,18 @@ with open("path/to/cookies.binarycookies", "wb") as f:
     binarycookies.dump(cookie, f)
 ```
 
+### Ethical Use & Responsible Handling
+This project is intended for lawful, ethical use only. Typical, appropriate uses include:
+- Inspecting Binary Cookies from your own devices or data you are authorized to access
+- DFIR, QA, and security testing performed with explicit, written permission
+- Educational/research work on datasets that are owned by you, anonymized, or publicly released for that purpose
+
+You must not use this tool to:
+- Access, extract, modify, or distribute cookies from systems or accounts you do not own or have permission to analyze
+- Bypass authentication, session management, DRM, or other technical controls
+- Enable tracking, stalking, doxxing, fraud, or other privacy-invasive or harmful activities
+
+
 ### License
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
 

{binarycookies-2.2.1 → binarycookies-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "binarycookies"
-version = "2.2.1"
+version = "2.3.0"
 description = "Python Binary Cookies (de)serializer"
 authors = ["Daniel Tom <d.e.tom89@gmail.com>"]
 readme = "README.md"
@@ -8,7 +8,7 @@ packages = [{include = "binarycookies", from="src"}]
 
 [tool.poetry.dependencies]
 python = ">=3.8,<4.0"
-typer = ">=0.12.3,<0.17.0"
+typer = ">=0.12.3,<0.21.0"
 pydantic = ">=2.0.0,<3.0.0"
 
 [tool.poetry.group.dev.dependencies]

binarycookies-2.3.0/setup.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+from setuptools import setup
+
+package_dir = \
+{'': 'src'}
+
+packages = \
+['binarycookies']
+
+package_data = \
+{'': ['*']}
+
+install_requires = \
+['pydantic>=2.0.0,<3.0.0', 'typer>=0.12.3,<0.21.0']
+
+entry_points = \
+{'console_scripts': ['bcparser = binarycookies.__main__:main']}
+
+setup_kwargs = {
+    'name': 'binarycookies',
+    'version': '2.3.0',
+    'description': 'Python Binary Cookies (de)serializer',
+    'long_description': '[![Github Actions Status](https://github.com/dan1elt0m/binary-cookies-reader/workflows/test/badge.svg)](https://github.com/dan1elt0m/binary-cookies-reader/actions/workflows/test.yml)\n<h1>\n  <img src="docs/bincook.png" width="30" style="vertical-align: middle; margin-right: 10px;">\n  Binary Cookies\n</h1>\n\nCLI tool and Python library for reading and writing Binary Cookies.\n\n### Documentation\nFor detailed documentation, please visit the [Binary Cookies Documentation](https://dan1elt0m.github.io/binarycookies/)\n\n### Requirements\n\n- Python >= 3.9\n\n### Installation\n```bash \npip install binarycookies\n```\n\n### CLI example:\n```sh\nbcparser path/to/cookies.binarycookies\n```\n\nOutput:\n```json\n[\n  {\n    "name": "session_id",\n    "value": "abc123",\n    "url": "https://example.com",\n    "path": "/",\n    "create_datetime": "2023-10-01T12:34:56+00:00",\n    "expiry_datetime": "2023-12-31T23:59:59+00:00",\n    "flag": "Secure"\n  },\n  {\n    "name": "user_token",\n    "value": "xyz789",\n    "url": "https://example.com",\n    "path": "/account",\n    "create_datetime": "2023-10-01T12:34:56+00:00",\n    "expiry_datetime": "2023-12-31T23:59:59+00:00",\n    "flag": "HttpOnly"\n  }\n]\n```\n#### Output formats\nThe CLI supports multiple output formats using the --output flag.\n- `json` (default): Outputs cookies in JSON format.\n- `ascii`: Outputs cookies in a human-readable ASCII format with each cookie property on a separate line.\n- `netscape`: Outputs cookies in the Netscape cookie file format.\n\n### Basic Usage Python\n\n#### Deserialization\n\n```python\nimport binarycookies \n\nwith open("path/to/cookies.binarycookies", "rb") as f:\n    cookies = binarycookies.load(f)\n```\n\n#### Serialization\n\n```python\nimport binarycookies \n\ncookie = {\n    "name": "session_id",\n    "value": "abc123",\n    "url": "https://example.com",\n    "path": "/",\n    "create_datetime": "2023-10-01T12:34:56+00:00",\n    "expiry_datetime": "2023-12-31T23:59:59+00:00",\n    "flag": "Secure"\n}\n\nwith open("path/to/cookies.binarycookies", "wb") as f:\n    binarycookies.dump(cookie, f)\n```\n\n### Ethical Use & Responsible Handling\nThis project is intended for lawful, ethical use only. Typical, appropriate uses include:\n- Inspecting Binary Cookies from your own devices or data you are authorized to access\n- DFIR, QA, and security testing performed with explicit, written permission\n- Educational/research work on datasets that are owned by you, anonymized, or publicly released for that purpose\n\nYou must not use this tool to:\n- Access, extract, modify, or distribute cookies from systems or accounts you do not own or have permission to analyze\n- Bypass authentication, session management, DRM, or other technical controls\n- Enable tracking, stalking, doxxing, fraud, or other privacy-invasive or harmful activities\n\n\n### License\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n### Contributing\nContributions are welcome! If you find a bug or have a feature request, please open an issue on GitHub. Pull requests are also welcome.\n',
+    'author': 'Daniel Tom',
+    'author_email': 'd.e.tom89@gmail.com',
+    'maintainer': 'None',
+    'maintainer_email': 'None',
+    'url': 'None',
+    'package_dir': package_dir,
+    'packages': packages,
+    'package_data': package_data,
+    'install_requires': install_requires,
+    'entry_points': entry_points,
+    'python_requires': '>=3.8,<4.0',
+}
+
+
+setup(**setup_kwargs)

binarycookies-2.3.0/src/binarycookies/__init__.py

@@ -0,0 +1,12 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from binarycookies._deserialize import load, loads
+from binarycookies._serialize import dump, dumps
+
+try:
+    __version__ = version("binarycookies")
+except PackageNotFoundError:
+    # Package is not installed, fallback to a default
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["dump", "dumps", "load", "loads"]

{binarycookies-2.2.1 → binarycookies-2.3.0}/src/binarycookies/__main__.py

@@ -1,11 +1,11 @@
 import json
 from datetime import datetime
-from typing import Type
+from typing import Optional, Type
 
 import typer
 from rich import print as rprint
 
-from binarycookies import load
+from binarycookies import __version__, load
 from binarycookies._output_handlers import OUTPUT_HANDLERS, OutputType
 
 
@@ -16,7 +16,24 @@ class DateTimeEncoder(json.JSONEncoder):
         return super().default(obj)
 
 
-def cli(file_path: str, output: OutputType = OutputType.json):
+app = typer.Typer()
+
+
+def version_callback(value: bool):  # noqa: FBT001
+    """Callback to print version and exit."""
+    if value:
+        rprint(f"binarycookies version {__version__}")
+        raise typer.Exit
+
+
+@app.command()
+def cli(
+    file_path: str = typer.Argument(..., help="Path to binary cookies file"),
+    output: OutputType = typer.Option(OutputType.json, "--output", "-o", help="Output format"),
+    version: Optional[bool] = typer.Option(  # noqa: ARG001
+        None, "--version", "-v", callback=version_callback, is_eager=True, help="Show version and exit"
+    ),
+):
     """CLI entrypoint for reading Binary Cookies"""
     with open(file_path, "rb") as f:
         cookies = load(f)
@@ -31,7 +48,7 @@ def cli(file_path: str, output: OutputType = OutputType.json):
 
 def main():
     """CLI entrypoint for reading Binary Cookies"""
-    typer.run(cli)
+    app()
 
 
 if __name__ == "__main__":

{binarycookies-2.2.1 → binarycookies-2.3.0}/src/binarycookies/_deserialize.py

@@ -1,4 +1,5 @@
-from datetime import datetime, timezone
+import sys
+from datetime import datetime, timedelta, timezone
 from io import BytesIO
 from struct import unpack
 from typing import BinaryIO, List, Union
@@ -26,21 +27,35 @@ def interpret_flag(flags: int) -> Flag:
     return FLAGS.get(flags, Flag.UNKNOWN)
 
 
+MAC_UNIX_OFFSET = 978307200  # Seconds from Unix epoch (1970) to Mac epoch (2001)
+INT32_TIME_T_MAX = 2147483647  # Max signed 32-bit time_t (Unix timestamp)
+INT32_CUTOFF_DT = datetime(2038, 1, 19, 3, 14, 7, tzinfo=timezone.utc)
+
+
 def mac_epoch_to_date(epoch: int) -> datetime:
     """
-    Converts a mac epoch time to a datetime object, handling potential
-    overflows on both 32-bit and 64-bit systems.
-    """
-    # The Mac epoch starts on 2001-01-01, which is 978307200 seconds after the Unix epoch.
-    unix_epoch = epoch + 978307200
+    Convert Mac epoch seconds (since 2001-01-01 UTC) to an aware datetime.
 
+    On 32-bit systems, clamp results that would overflow `time_t` to 2038-01-19T03:14:07Z.
+    On 64-bit systems, only clamp if the value exceeds datetime's range (-> datetime.max).
+    """
+    base = datetime(2001, 1, 1, tzinfo=timezone.utc)
+    # Fast path: pure Python arithmetic (independent of C time_t)
     try:
-        return datetime.fromtimestamp(unix_epoch, tz=timezone.utc)
-    except (OverflowError, OSError):
-        # This handles timestamps that are too large for the system's C library,
-        # which can happen for non-expiring cookies or on 32-bit systems (Year 2038 problem).
+        dt = base + timedelta(seconds=epoch)
+    except OverflowError:
+        # Beyond datetime range: choose appropriate cap
+        if sys.maxsize <= 2**31 - 1:
+            return INT32_CUTOFF_DT
         return datetime.max.replace(tzinfo=timezone.utc)
 
+    # 32-bit clamp logic
+    if sys.maxsize <= 2**31 - 1:
+        unix_ts = epoch + MAC_UNIX_OFFSET
+        if unix_ts > INT32_TIME_T_MAX:
+            return INT32_CUTOFF_DT
+    return dt
+
 
 def read_string(data: BytesIO, size: int) -> str:
     """Reads a string from binary file."""
@@ -71,6 +86,10 @@ def read_cookie(cookie: BytesIO, cookie_size: int) -> Cookie:
     flag_int = read_field(cookie, cookie_fields.flag)
     flag = interpret_flag(flag_int)
 
+    # Read comment offset at offset 32
+    cookie.seek(32)
+    comment_offset = unpack(Format.integer, cookie.read(4))[0]  # noqa: F841
+
     url_offset = read_field(cookie, cookie_fields.url_offset)
     name_offset = read_field(cookie, cookie_fields.name_offset)
     path_offset = read_field(cookie, cookie_fields.path_offset)
@@ -79,6 +98,7 @@ def read_cookie(cookie: BytesIO, cookie_size: int) -> Cookie:
     expiry_datetime = mac_epoch_to_date(read_field(cookie, cookie_fields.expiry_date))
     create_datetime = mac_epoch_to_date(read_field(cookie, cookie_fields.create_date))
 
+    # Read strings - comment comes first, then domain (url)
     url = read_field(cookie, BcField(offset=url_offset, size=name_offset - url_offset, format=Format.string))
     name = read_field(cookie, BcField(offset=name_offset, size=path_offset - name_offset, format=Format.string))
     path = read_field(cookie, BcField(offset=path_offset, size=value_offset - path_offset, format=Format.string))

binarycookies-2.3.0/src/binarycookies/_serialize.py

@@ -0,0 +1,222 @@
+from datetime import datetime, timezone
+from io import BufferedWriter, BytesIO
+from struct import pack
+from typing import BinaryIO, Dict, List, Tuple, Union
+
+from pydantic import __version__ as pydantic_version
+
+from binarycookies._deserialize import FLAGS
+from binarycookies.models import BcField, Cookie, CookieFields, FileFields, Format
+
+IS_PYDANTIC_V1 = pydantic_version.startswith("1.")
+
+CookiesCollection = Union[List[Dict], List[Cookie], Tuple[Dict], Tuple[Cookie], Cookie, Dict[str, str]]
+
+
+def date_to_mac_epoch(date: datetime) -> int:
+    """Converts a datetime object to mac epoch time."""
+    mac_epoch_start = datetime(2001, 1, 1, tzinfo=timezone.utc)
+    return int((date - mac_epoch_start).total_seconds())
+
+
+def write_string(data: BytesIO, value: str):
+    """Writes a string to binary file."""
+    data.write(value.encode() + b"\x00")
+
+
+def write_field(data: BytesIO, field: BcField, value: Union[str, int]):
+    """Writes a field to binary data."""
+    data.seek(field.offset)
+    if field.format == Format.string:
+        write_string(data, value)
+    else:
+        data.write(pack(field.format, value))
+
+
+def serialize_cookie(cookie: Cookie) -> bytes:
+    """Serializes a cookie object to binary format."""
+    cookie_fields = CookieFields()
+
+    # Pre-calculate the size to allocate buffer
+    # Cookie header is 60 bytes according to spec:
+    # 0-3: size, 4-7: unknownOne, 8-11: flags, 12-15: unknownTwo
+    # 16-19: domainOffset, 20-23: nameOffset, 24-27: pathOffset, 28-31: valueOffset
+    # 32-35: commentOffset, 36-39: endHeader
+    # 40-47: expires, 48-55: creation
+    # 56-59: comment (empty), 60+: domain, name, path, value strings
+    url_bytes = cookie.url.encode("utf-8")
+    name_bytes = cookie.name.encode("utf-8")
+    path_bytes = cookie.path.encode("utf-8")
+    value_bytes = cookie.value.encode("utf-8")
+    comment_bytes = b""  # Empty comment
+
+    # Each string has a null terminator
+    header_size = 60
+    strings_size = (
+        len(comment_bytes) + 1 + len(url_bytes) + 1 + len(name_bytes) + 1 + len(path_bytes) + 1 + len(value_bytes) + 1
+    )
+    total_size = header_size + strings_size
+
+    # Pre-allocate buffer with zeros
+    cookie_data = BytesIO(b"\x00" * total_size)
+
+    # Write flag
+    write_field(cookie_data, cookie_fields.flag, list(FLAGS.keys())[list(FLAGS.values()).index(cookie.flag)])
+
+    # Calculate offsets - strings start at byte 60 after header
+    comment_offset = 60
+    domain_offset = comment_offset + len(comment_bytes) + 1  # +1 for null terminator
+    name_offset = domain_offset + len(url_bytes) + 1
+    path_offset = name_offset + len(name_bytes) + 1
+    value_offset = path_offset + len(path_bytes) + 1
+
+    # Write offsets (note: spec calls it domain but code uses url)
+    write_field(cookie_data, cookie_fields.url_offset, domain_offset)
+    write_field(cookie_data, cookie_fields.name_offset, name_offset)
+    write_field(cookie_data, cookie_fields.path_offset, path_offset)
+    write_field(cookie_data, cookie_fields.value_offset, value_offset)
+
+    # Write commentOffset at offset 32
+    cookie_data.seek(32)
+    cookie_data.write(pack(Format.integer, comment_offset))
+
+    # Write endHeader marker at offset 36 (4 bytes of 0x00)
+    cookie_data.seek(36)
+    cookie_data.write(b"\x00\x00\x00\x00")
+
+    write_field(cookie_data, cookie_fields.expiry_date, date_to_mac_epoch(cookie.expiry_datetime))
+    write_field(cookie_data, cookie_fields.create_date, date_to_mac_epoch(cookie.create_datetime))
+
+    # Write string data starting at offset 60
+    cookie_data.seek(60)
+    # Write comment (empty string with null terminator)
+    write_string(cookie_data, "")
+    # Write domain (url), name, path, value
+    write_string(cookie_data, cookie.url)
+    write_string(cookie_data, cookie.name)
+    write_string(cookie_data, cookie.path)
+    write_string(cookie_data, cookie.value)
+
+    # Write size at the beginning
+    size = len(cookie_data.getvalue())
+    cookie_data.seek(0)
+    cookie_data.write(pack(Format.integer, size))
+    return cookie_data.getvalue()
+
+
+def dump(cookies: CookiesCollection, f: Union[BufferedWriter, BytesIO, BinaryIO]):
+    """Dumps a Binary Cookies object to create a binary cookies file.
+
+    Args:
+        cookies: A Binary Cookies object to be serialized.
+        f: The file-like object to write the binary cookies data to.
+    """
+    binary = dumps(cookies)
+    f.write(binary)
+
+
+def calculate_checksum(page_data: bytes) -> int:
+    """Calculates the checksum by summing every 4th byte of the page data.
+
+    Args:
+        page_data: The raw bytes of a page.
+    Returns:
+        int: The checksum value.
+    """
+    checksum = 0
+    # Sum every 4th byte (bytes at positions 0, 4, 8, 12, ...)
+    for i in range(0, len(page_data), 4):
+        checksum += page_data[i]
+    return checksum
+
+
+def dumps(cookies: CookiesCollection) -> bytes:
+    """Dumps a Binary Cookies object to a byte string.
+
+    Args:
+        cookies: A Binary Cookies object to be serialized.
+    Returns:
+        bytes: The serialized binary cookies data.
+    """
+    if isinstance(cookies, dict):
+        cookies = [Cookie.parse_obj(cookies)] if IS_PYDANTIC_V1 else [Cookie.model_validate(cookies)]
+    elif isinstance(cookies, (list, tuple)):
+        if IS_PYDANTIC_V1:
+            cookies = [Cookie.parse_obj(cookie) for cookie in cookies]
+        else:
+            cookies = [Cookie.model_validate(cookie) for cookie in cookies]
+    elif isinstance(cookies, Cookie):
+        cookies = [cookies]
+    else:
+        raise TypeError("Invalid type for cookies. Expected dict, list, tuple, or Cookie.")
+
+    file_fields = FileFields()
+
+    data = BytesIO()
+
+    # Write file header (4 bytes: "cook")
+    data.write(b"cook")
+
+    # Number of pages (1 for simplicity, big-endian)
+    write_field(data, file_fields.num_pages, 1)
+
+    # Write page size pointer
+    data.write(pack(Format.integer, 0))  # Placeholder, will be updated
+
+    # Store the position where page data starts
+    page_start_offset = data.tell()
+    page_data = BytesIO()
+
+    # Write pageStart marker (4 bytes) - Must be 0x00, 0x01, 0x00, 0x00
+    page_data.write(b"\x00\x01\x00\x00")
+
+    # Write number of cookies in the page
+    page_data.write(pack(Format.integer, len(cookies)))
+
+    cookie_data_list = []
+    # Serialize cookies
+    for cookie in cookies:
+        cookie_data_list.append(serialize_cookie(cookie))
+
+    # Calculate where cookie data will start:
+    # current position + (num_cookies * 4 bytes for offsets) + 4 bytes for pageEnd marker
+    initial_cookie_offset = page_data.tell() + (len(cookies) * 4) + 4
+    initial_cookie = True
+    previous_sizes = 0
+
+    # Write cookie offsets
+    for cookie_data in cookie_data_list:
+        if initial_cookie:
+            page_data.write(pack(Format.integer, initial_cookie_offset))
+            initial_cookie = False
+        else:
+            page_data.write(pack(Format.integer, previous_sizes + initial_cookie_offset))
+
+        previous_sizes += len(cookie_data)
+
+    # Write pageEnd marker (4 bytes) - Must be 0x00, 0x00, 0x00, 0x00
+    page_data.write(b"\x00\x00\x00\x00")
+
+    # Write cookie data
+    for cookie_data in cookie_data_list:
+        page_data.write(cookie_data)
+
+    # Get the complete page data
+    page_bytes = page_data.getvalue()
+    page_size = len(page_bytes)
+
+    # Update page size in the file header (big-endian format for page sizes)
+    data.seek(8)
+    data.write(pack(Format.integer_be, page_size))
+
+    # Write the page data
+    data.seek(page_start_offset)
+    data.write(page_bytes)
+
+    # Calculate and write checksum after all pages
+    # The checksum is the sum of every 4th byte of the page data
+    # Specification says 8 bytes, so we write it as a 64-bit integer
+    checksum = calculate_checksum(page_bytes)
+    data.write(pack("<Q", checksum))  # LE_uint64 (8 bytes)
+
+    return data.getvalue()

{binarycookies-2.2.1 → binarycookies-2.3.0}/src/binarycookies/models.py

@@ -20,6 +20,18 @@ class Flag(str, Enum):
 
 
 class Cookie(BaseModel):
+    """Represents a cookie in the binary cookies format.
+
+    Attributes:
+        name (str): The name of the cookie.
+        value (str): The value of the cookie.
+        url (str): The URL associated with the cookie.
+        path (str): The path for which the cookie is valid.
+        create_datetime (datetime): The creation date and time of the cookie.
+        expiry_datetime (datetime): The expiration date and time of the cookie.
+        flag (Flag): The flags associated with the cookie, such as Secure or HttpOnly.
+    """
+
     name: str
     value: str
     url: str

binarycookies-2.2.1/src/binarycookies/__init__.py

@@ -1,4 +0,0 @@
-from binarycookies._deserialize import load, loads
-from binarycookies._serialize import dump, dumps
-
-__all__ = ["dump", "dumps", "load", "loads"]

binarycookies-2.2.1/src/binarycookies/_serialize.py

@@ -1,149 +0,0 @@
-from datetime import datetime, timezone
-from io import BufferedWriter, BytesIO
-from struct import pack
-from typing import BinaryIO, Dict, List, Tuple, Union
-
-from pydantic import __version__ as pydantic_version
-
-from binarycookies._deserialize import FLAGS
-from binarycookies.models import BcField, Cookie, CookieFields, FileFields, Format
-
-IS_PYDANTIC_V1 = pydantic_version.startswith("1.")
-
-CookiesCollection = Union[List[Dict], List[Cookie], Tuple[Dict], Tuple[Cookie], Cookie, Dict[str, str]]
-
-
-def date_to_mac_epoch(date: datetime) -> int:
-    """Converts a datetime object to mac epoch time."""
-    mac_epoch_start = datetime(2001, 1, 1, tzinfo=timezone.utc)
-    return int((date - mac_epoch_start).total_seconds())
-
-
-def write_string(data: BytesIO, value: str):
-    """Writes a string to binary file."""
-    data.write(value.encode() + b"\x00")
-
-
-def write_field(data: BytesIO, field: BcField, value: Union[str, int]):
-    """Writes a field to binary data."""
-    data.seek(field.offset)
-    if field.format == Format.string:
-        write_string(data, value)
-    else:
-        data.write(pack(field.format, value))
-
-
-def serialize_cookie(cookie: Cookie) -> bytes:
-    """Serializes a cookie object to binary format."""
-    cookie_data = BytesIO()
-    cookie_fields = CookieFields()
-    # Write flag
-    write_field(cookie_data, cookie_fields.flag, list(FLAGS.keys())[list(FLAGS.values()).index(cookie.flag)])
-
-    # Calculate offsets
-    url_offset = 56  # The actual cookies content always starts at byte 56
-    name_offset = 1 + url_offset + len(cookie.url.encode("utf-8"))
-    path_offset = 1 + name_offset + len(cookie.name.encode("utf-8"))
-    value_offset = 1 + path_offset + len(cookie.path.encode("utf-8"))
-
-    write_field(cookie_data, cookie_fields.url_offset, url_offset)
-    write_field(cookie_data, cookie_fields.name_offset, name_offset)
-    write_field(cookie_data, cookie_fields.path_offset, path_offset)
-    write_field(cookie_data, cookie_fields.value_offset, value_offset)
-
-    write_field(cookie_data, cookie_fields.expiry_date, date_to_mac_epoch(cookie.expiry_datetime))
-    write_field(cookie_data, cookie_fields.create_date, date_to_mac_epoch(cookie.create_datetime))
-
-    # Write cookie data
-    write_string(cookie_data, cookie.url)
-    write_string(cookie_data, cookie.name)
-    write_string(cookie_data, cookie.path)
-    write_string(cookie_data, cookie.value)
-
-    # Write size at the beginning
-    size = len(cookie_data.getvalue())
-    cookie_data.seek(0)
-    cookie_data.write(pack(Format.integer, size))
-    return cookie_data.getvalue()
-
-
-def dump(cookies: CookiesCollection, f: Union[BufferedWriter, BytesIO, BinaryIO]):
-    """Dumps a Binary Cookies object to create a binary cookies file.k
-
-    Args:
-        cookies: A Binary Cookies object to be serialized.
-        f: The file-like object to write the binary cookies data to.
-    """
-    binary = dumps(cookies)
-    f.write(binary)
-
-
-def dumps(cookies: CookiesCollection) -> bytes:
-    """Dumps a Binary Cookies object to a byte string.
-    Args:
-        cookies: A Binary Cookies object to be serialized.
-    Returns:
-        bytes: The serialized binary cookies data.
-    """
-    if isinstance(cookies, dict):
-        cookies = [Cookie.parse_obj(cookies)] if IS_PYDANTIC_V1 else [Cookie.model_validate(cookies)]
-    elif isinstance(cookies, (list, tuple)):
-        if IS_PYDANTIC_V1:
-            cookies = [Cookie.parse_obj(cookie) for cookie in cookies]
-        else:
-            cookies = [Cookie.model_validate(cookie) for cookie in cookies]
-    elif isinstance(cookies, Cookie):
-        cookies = [cookies]
-    else:
-        raise TypeError("Invalid type for cookies. Expected dict, list, tuple, or Cookie.")
-
-    file_fields = FileFields()
-
-    data = BytesIO()
-
-    # Write file header
-    write_field(data, file_fields.header, "cook")
-
-    # Number of pages (1 for simplicity)
-    write_field(data, file_fields.num_pages, 1)
-
-    # Write number of cookies
-    data.write(pack(Format.integer, len(cookies)))
-
-    # Placeholder for page size
-    page_size_offset = data.tell()
-    data.write(b"\x00\x00\x00\x00")
-
-    # Write number of cookies
-    data.write(pack(Format.integer, len(cookies)))
-    cookie_data_list = []
-    # Write cookies
-    for cookie in cookies:
-        cookie_data_list.append(serialize_cookie(cookie))
-
-    initial_cookie_offset = data.tell() + (len(cookies) * 4)
-    initial_cookie = True
-    previous_sizes = 0
-    for cookie_data in cookie_data_list:
-        if initial_cookie:
-            data.write(pack(Format.integer, initial_cookie_offset))
-            initial_cookie = False
-        else:
-            data.write(pack(Format.integer, previous_sizes + initial_cookie_offset))
-
-        previous_sizes += len(cookie_data)
-
-    # Unknown data
-    data.write(b"\x00\x00\x00\x00")
-    data.write(b"\x00\x00\x00\x00")
-    data.write(b"\x00\x00\x00\x00")
-
-    for cookie_data in cookie_data_list:
-        data.write(cookie_data)
-
-    # Update page size
-    page_size = data.tell()
-    data.seek(page_size_offset)
-    data.write(pack(Format.integer, page_size))
-
-    return data.getvalue()