binarycookies 2.2.3__tar.gz → 2.4.0__tar.gz

{binarycookies-2.2.3 → binarycookies-2.4.0}/PKG-INFO

@@ -1,17 +1,17 @@
 Metadata-Version: 2.1
 Name: binarycookies
-Version: 2.2.3
+Version: 2.4.0
 Summary: Python Binary Cookies (de)serializer
 Author: Daniel Tom
 Author-email: d.e.tom89@gmail.com
-Requires-Python: >=3.8,<4.0
+Requires-Python: >=3.9,<4.0
 Classifier: Programming Language :: Python :: 3
-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
 Requires-Dist: pydantic (>=2.0.0,<3.0.0)
-Requires-Dist: typer (>=0.12.3,<0.20.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)
@@ -49,7 +49,9 @@ Output:
     "path": "/",
     "create_datetime": "2023-10-01T12:34:56+00:00",
     "expiry_datetime": "2023-12-31T23:59:59+00:00",
-    "flag": "Secure"
+    "flag": "Secure",
+    "raw_flags": 1,
+    "comment": null
   },
   {
     "name": "user_token",
@@ -58,7 +60,9 @@ Output:
     "path": "/account",
     "create_datetime": "2023-10-01T12:34:56+00:00",
     "expiry_datetime": "2023-12-31T23:59:59+00:00",
-    "flag": "HttpOnly"
+    "flag": "HttpOnly",
+    "raw_flags": 4,
+    "comment": null
   }
 ]
 ```
@@ -87,7 +91,7 @@ import binarycookies
 cookie = {
     "name": "session_id",
     "value": "abc123",
-    "url": "https://example.com",
+    "url": "https://example.com",  # "domain" is accepted as an alias for "url"
     "path": "/",
     "create_datetime": "2023-10-01T12:34:56+00:00",
     "expiry_datetime": "2023-12-31T23:59:59+00:00",
@@ -98,6 +102,13 @@ with open("path/to/cookies.binarycookies", "wb") as f:
     binarycookies.dump(cookie, f)
 ```
 
+Optional fields:
+- `comment`: cookie comment string stored in the file (default: no comment)
+- `raw_flags`: the raw flags bitfield written to disk. When omitted, it is derived
+  from `flag` (`Secure` = 1, `HttpOnly` = 4, `Secure; HttpOnly` = 5). Cookies read
+  with `load`/`loads` always carry `raw_flags`, so unknown flag bits survive a
+  read-modify-write round trip.
+
 ### 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

{binarycookies-2.2.3 → binarycookies-2.4.0}/README.md

@@ -33,7 +33,9 @@ Output:
     "path": "/",
     "create_datetime": "2023-10-01T12:34:56+00:00",
     "expiry_datetime": "2023-12-31T23:59:59+00:00",
-    "flag": "Secure"
+    "flag": "Secure",
+    "raw_flags": 1,
+    "comment": null
   },
   {
     "name": "user_token",
@@ -42,7 +44,9 @@ Output:
     "path": "/account",
     "create_datetime": "2023-10-01T12:34:56+00:00",
     "expiry_datetime": "2023-12-31T23:59:59+00:00",
-    "flag": "HttpOnly"
+    "flag": "HttpOnly",
+    "raw_flags": 4,
+    "comment": null
   }
 ]
 ```
@@ -71,7 +75,7 @@ import binarycookies
 cookie = {
     "name": "session_id",
     "value": "abc123",
-    "url": "https://example.com",
+    "url": "https://example.com",  # "domain" is accepted as an alias for "url"
     "path": "/",
     "create_datetime": "2023-10-01T12:34:56+00:00",
     "expiry_datetime": "2023-12-31T23:59:59+00:00",
@@ -82,6 +86,13 @@ with open("path/to/cookies.binarycookies", "wb") as f:
     binarycookies.dump(cookie, f)
 ```
 
+Optional fields:
+- `comment`: cookie comment string stored in the file (default: no comment)
+- `raw_flags`: the raw flags bitfield written to disk. When omitted, it is derived
+  from `flag` (`Secure` = 1, `HttpOnly` = 4, `Secure; HttpOnly` = 5). Cookies read
+  with `load`/`loads` always carry `raw_flags`, so unknown flag bits survive a
+  read-modify-write round trip.
+
 ### 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

{binarycookies-2.2.3 → binarycookies-2.4.0}/pyproject.toml

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

binarycookies-2.4.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.3 → binarycookies-2.4.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.3 → binarycookies-2.4.0}/src/binarycookies/_deserialize.py

@@ -14,6 +14,10 @@ from binarycookies.models import (
     Format,
 )
 
+SECURE_BIT = 0x1
+HTTP_ONLY_BIT = 0x4
+
+# Kept for backwards compatibility; interpret_flag treats flags as a bitfield instead
 FLAGS = {
     0: Flag.UNKNOWN,
     1: Flag.SECURE,
@@ -23,8 +27,16 @@ FLAGS = {
 
 
 def interpret_flag(flags: int) -> Flag:
-    """Interprets the flags of a cookie and returns a human-readable string."""
-    return FLAGS.get(flags, Flag.UNKNOWN)
+    """Interprets the Secure/HttpOnly bits of the raw flags bitfield."""
+    secure = bool(flags & SECURE_BIT)
+    http_only = bool(flags & HTTP_ONLY_BIT)
+    if secure and http_only:
+        return Flag.SECURE_HTTPONLY
+    if secure:
+        return Flag.SECURE
+    if http_only:
+        return Flag.HTTPONLY
+    return Flag.UNKNOWN
 
 
 MAC_UNIX_OFFSET = 978307200  # Seconds from Unix epoch (1970) to Mac epoch (2001)
@@ -58,17 +70,12 @@ def mac_epoch_to_date(epoch: int) -> datetime:
 
 
 def read_string(data: BytesIO, size: int) -> str:
-    """Reads a string from binary file."""
-    result = ""
-    count = 0
-    c = data.read(1)
-    while unpack("<b", c)[0] != 0:
-        count += 1
-        if count > size:
-            break
-        result += str(c.decode())
-        c = data.read(1)
-    return result
+    """Reads a null-terminated UTF-8 string of at most `size` bytes from binary data."""
+    raw = data.read(size)
+    end = raw.find(b"\x00")
+    if end != -1:
+        raw = raw[:end]
+    return raw.decode("utf-8")
 
 
 def read_field(data: BytesIO, field: BcField) -> Union[str, int]:
@@ -83,8 +90,12 @@ def read_cookie(cookie: BytesIO, cookie_size: int) -> Cookie:
     """Reads a cookie from the given offset in the page."""
 
     cookie_fields = CookieFields()
-    flag_int = read_field(cookie, cookie_fields.flag)
-    flag = interpret_flag(flag_int)
+    raw_flags = read_field(cookie, cookie_fields.flag)
+    flag = interpret_flag(raw_flags)
+
+    # Read comment offset at offset 32 (0 means the cookie has no comment)
+    cookie.seek(32)
+    comment_offset = unpack(Format.integer, cookie.read(4))[0]
 
     url_offset = read_field(cookie, cookie_fields.url_offset)
     name_offset = read_field(cookie, cookie_fields.name_offset)
@@ -94,6 +105,13 @@ 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 - the comment (if any) comes first, then domain (url)
+    comment = None
+    if comment_offset > 0:
+        comment_end = url_offset if comment_offset <= url_offset else cookie_size
+        comment = read_field(
+            cookie, BcField(offset=comment_offset, size=comment_end - comment_offset, format=Format.string)
+        )
     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))
@@ -107,6 +125,8 @@ def read_cookie(cookie: BytesIO, cookie_size: int) -> Cookie:
         create_datetime=create_datetime,
         expiry_datetime=expiry_datetime,
         flag=flag,
+        raw_flags=raw_flags,
+        comment=comment,
     )
 
 

binarycookies-2.4.0/src/binarycookies/_serialize.py

@@ -0,0 +1,215 @@
+import plistlib
+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.models import BcField, Cookie, CookieFields, FileFields, Flag, Format
+
+IS_PYDANTIC_V1 = pydantic_version.startswith("1.")
+
+CookiesCollection = Union[List[Dict], List[Cookie], Tuple[Dict], Tuple[Cookie], Cookie, Dict[str, str]]
+
+# Every page starts with these 4 bytes (0x00000100 stored big-endian)
+PAGE_HEADER = b"\x00\x00\x01\x00"
+# 4 zero bytes terminate the page's cookie offset table
+PAGE_FOOTER = b"\x00\x00\x00\x00"
+# 8-byte magic that follows the checksum at the end of the file
+FILE_FOOTER = b"\x07\x17\x20\x05\x00\x00\x00\x4b"
+# Cookie records without comments have a 56-byte fixed header; strings follow
+COOKIE_HEADER_SIZE = 56
+# Value Safari stores in the trailing NSHTTPCookieAcceptPolicy plist
+DEFAULT_COOKIE_ACCEPT_POLICY = 2
+# Raw flag bitfield written when a cookie has no raw_flags set
+FLAG_VALUES = {Flag.UNKNOWN: 0, Flag.SECURE: 1, Flag.HTTPONLY: 4, Flag.SECURE_HTTPONLY: 5}
+
+
+def date_to_mac_epoch(date: datetime) -> int:
+    """Converts a datetime object to mac epoch time. Naive datetimes are assumed to be UTC."""
+    if date.tzinfo is None:
+        date = date.replace(tzinfo=timezone.utc)
+    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 Apple's binary cookie record format."""
+    cookie_fields = CookieFields()
+
+    # Cookie record layout (matches Safari/CFNetwork):
+    # 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 (0 = no comment), 36-39: commentURLOffset (0 = none)
+    # 40-47: expires (float64 LE), 48-55: creation (float64 LE)
+    # 56+: null-terminated comment (if any), 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 = cookie.comment.encode("utf-8") if cookie.comment else None
+
+    # Each string has a null terminator
+    strings_size = len(url_bytes) + 1 + len(name_bytes) + 1 + len(path_bytes) + 1 + len(value_bytes) + 1
+    if comment_bytes is not None:
+        strings_size += len(comment_bytes) + 1
+    total_size = COOKIE_HEADER_SIZE + strings_size
+
+    # Pre-allocate buffer with zeros; the comment URL offset at 36 stays 0
+    cookie_data = BytesIO(b"\x00" * total_size)
+
+    # Write size and raw flags (falling back to the bits implied by the flag enum)
+    cookie_data.write(pack(Format.integer, total_size))
+    raw_flags = cookie.raw_flags if cookie.raw_flags is not None else FLAG_VALUES[cookie.flag]
+    write_field(cookie_data, cookie_fields.flag, raw_flags)
+
+    # Calculate offsets - strings start right after the fixed header, comment first
+    comment_offset = COOKIE_HEADER_SIZE if comment_bytes is not None else 0
+    domain_offset = COOKIE_HEADER_SIZE if comment_bytes is None else comment_offset + len(comment_bytes) + 1
+    name_offset = domain_offset + len(url_bytes) + 1  # +1 for null terminator
+    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)
+
+    if comment_offset:
+        cookie_data.seek(32)
+        cookie_data.write(pack(Format.integer, comment_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 comment (if any), domain (url), name, path, value strings
+    cookie_data.seek(COOKIE_HEADER_SIZE)
+    if cookie.comment:
+        write_string(cookie_data, cookie.comment)
+    write_string(cookie_data, cookie.url)
+    write_string(cookie_data, cookie.name)
+    write_string(cookie_data, cookie.path)
+    write_string(cookie_data, cookie.value)
+
+    return cookie_data.getvalue()
+
+
+def serialize_page(cookies: List[Cookie]) -> bytes:
+    """Serializes a list of cookies into a single page in Apple's binary cookies format."""
+    cookie_data_list = [serialize_cookie(cookie) for cookie in cookies]
+
+    page = BytesIO()
+    page.write(PAGE_HEADER)
+    page.write(pack(Format.integer, len(cookie_data_list)))
+
+    # Cookie offsets are relative to the page start:
+    # 8-byte page header + 4 bytes per offset + 4-byte page footer
+    cookie_offset = 8 + (len(cookie_data_list) * 4) + 4
+    for cookie_data in cookie_data_list:
+        page.write(pack(Format.integer, cookie_offset))
+        cookie_offset += len(cookie_data)
+
+    page.write(PAGE_FOOTER)
+
+    for cookie_data in cookie_data_list:
+        page.write(cookie_data)
+
+    return page.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 _as_cookie(cookie: Union[Dict, Cookie]) -> Cookie:
+    """Coerces a dict (accepting `domain` as an alias for `url`) into a Cookie."""
+    if isinstance(cookie, Cookie):
+        return cookie
+    if isinstance(cookie, dict) and "url" not in cookie and "domain" in cookie:
+        cookie = {**cookie}
+        cookie["url"] = cookie.pop("domain")
+    return Cookie.parse_obj(cookie) if IS_PYDANTIC_V1 else Cookie.model_validate(cookie)
+
+
+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, Cookie)):
+        cookies = [cookies]
+    elif not isinstance(cookies, (list, tuple)):
+        raise TypeError("Invalid type for cookies. Expected dict, list, tuple, or Cookie.")
+    cookies = [_as_cookie(cookie) for cookie in cookies]
+
+    file_fields = FileFields()
+
+    # Safari stores one page per domain, in first-seen order
+    cookies_by_domain: Dict[str, List[Cookie]] = {}
+    for cookie in cookies:
+        cookies_by_domain.setdefault(cookie.url, []).append(cookie)
+    pages = [serialize_page(domain_cookies) for domain_cookies in cookies_by_domain.values()]
+
+    data = BytesIO()
+
+    # Write file header (4 bytes: "cook")
+    data.write(b"cook")
+
+    # Number of pages (big-endian)
+    write_field(data, file_fields.num_pages, len(pages))
+
+    # Page sizes (big-endian), followed by the page data itself
+    for page in pages:
+        data.write(pack(Format.integer_be, len(page)))
+    for page in pages:
+        data.write(page)
+
+    # File tail: 4-byte big-endian checksum over every 4th byte of each page,
+    # the 8-byte footer magic, and a binary plist with the cookie accept policy
+    checksum = sum(calculate_checksum(page) for page in pages)
+    data.write(pack(">I", checksum & 0xFFFFFFFF))
+    data.write(FILE_FOOTER)
+    data.write(plistlib.dumps({"NSHTTPCookieAcceptPolicy": DEFAULT_COOKIE_ACCEPT_POLICY}, fmt=plistlib.FMT_BINARY))
+
+    return data.getvalue()

{binarycookies-2.2.3 → binarycookies-2.4.0}/src/binarycookies/models.py

@@ -1,5 +1,6 @@
 from datetime import datetime
 from enum import Enum
+from typing import Optional
 
 from pydantic import BaseModel
 
@@ -25,11 +26,14 @@ class Cookie(BaseModel):
     Attributes:
         name (str): The name of the cookie.
         value (str): The value of the cookie.
-        url (str): The URL associated with the cookie.
+        url (str): The domain the cookie belongs to (also exposed as `domain`).
         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.
+        flag (Flag): Human-readable interpretation of the Secure/HttpOnly flag bits.
+        raw_flags (Optional[int]): The raw flags bitfield as stored on disk. Populated when
+            reading so unknown bits survive a round trip; derived from `flag` when absent.
+        comment (Optional[str]): The optional comment stored with the cookie.
     """
 
     name: str
@@ -39,6 +43,13 @@ class Cookie(BaseModel):
     create_datetime: datetime
     expiry_datetime: datetime
     flag: Flag
+    raw_flags: Optional[int] = None
+    comment: Optional[str] = None
+
+    @property
+    def domain(self) -> str:
+        """The domain the cookie belongs to; alias for `url`."""
+        return self.url
 
 
 class Format(str, Enum):

binarycookies-2.2.3/setup.py

@@ -1,38 +0,0 @@
-# -*- 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.20.0']
-
-entry_points = \
-{'console_scripts': ['bcparser = binarycookies.__main__:main']}
-
-setup_kwargs = {
-    'name': 'binarycookies',
-    'version': '2.2.3',
-    '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.2.3/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.3/src/binarycookies/_serialize.py

@@ -1,150 +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.
-
-    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()