binarycookies 2.2.0__tar.gz → 2.2.3__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.1
 Name: binarycookies
-Version: 2.2.0
+Version: 2.2.3
 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.20.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.0 → binarycookies-2.2.3}/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.0 → binarycookies-2.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "binarycookies"
-version = "2.2.0"
+version = "2.2.3"
 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.20.0"
 pydantic = ">=2.0.0,<3.0.0"
 
 [tool.poetry.group.dev.dependencies]

binarycookies-2.2.3/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.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.0 → binarycookies-2.2.3}/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."""

{binarycookies-2.2.0 → binarycookies-2.2.3}/src/binarycookies/_serialize.py

@@ -68,7 +68,7 @@ def serialize_cookie(cookie: Cookie) -> bytes:
 
 
 def dump(cookies: CookiesCollection, f: Union[BufferedWriter, BytesIO, BinaryIO]):
-    """Dumps a Binary Cookies object to create a binary cookies file.k
+    """Dumps a Binary Cookies object to create a binary cookies file.
 
     Args:
         cookies: A Binary Cookies object to be serialized.
@@ -80,6 +80,7 @@ def dump(cookies: CookiesCollection, f: Union[BufferedWriter, BytesIO, BinaryIO]
 
 def dumps(cookies: CookiesCollection) -> bytes:
     """Dumps a Binary Cookies object to a byte string.
+
     Args:
         cookies: A Binary Cookies object to be serialized.
     Returns:

{binarycookies-2.2.0 → binarycookies-2.2.3}/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