aurastamp-sdk 1.0.0__tar.gz

aurastamp_sdk-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+node_modules
+.DS_store
+
+.venv
+__pycache__/
+.ruff_cache/
+.pytest_cache/
+dist/
+.vercel
+.firebase/
+firebase-debug.log
+firestore-debug.log
+/package-lock.json

aurastamp_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.5
+Name: aurastamp-sdk
+Version: 1.0.0
+Summary: Hide and reveal short messages inside images, via the Aurastamp API
+Project-URL: Homepage, https://aurastamp.com
+Project-URL: Repository, https://github.com/sunutf/aurastamp
+Author: sunutf
+License: MIT
+Keywords: aurastamp,image,steganography,watermark
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Aurastamp SDK (Python)
+
+Hide and reveal short messages inside images.
+
+```sh
+pip install aurastamp-sdk
+```
+
+## The payload is 7 bytes
+
+The message is embedded in the image itself, and the model reserves exactly
+**7 bytes** for it. Anything longer is rejected before a request is made.
+
+That is 7 characters of ASCII, but fewer for anything else — `'가나'` is two
+characters and six bytes.
+
+To hide something longer, store the text somewhere and embed a short key
+instead; that is what [aurastamp.com](https://aurastamp.com) does.
+
+## Usage
+
+```python
+from aurastamp_sdk import Aurastamp
+
+aurastamp = Aurastamp()  # or Aurastamp("http://localhost:8000")
+
+# Hide a message
+encoded = aurastamp.image.encode_file(
+    image_file_path="photo.png",
+    message="hello",
+    output_path="encoded.png",
+)
+
+# Reveal it again
+print(aurastamp.image.decode_file(image_file_path="encoded.png"))
+#=> '  hello'   (padded to 7 bytes)
+```
+
+Working with bytes directly:
+
+```python
+with open("photo.png", "rb") as f:
+    encoded = aurastamp.image.encode(image=f.read(), message="hello", filename="photo.png")
+
+message = aurastamp.image.decode(image=encoded, filename="encoded.png")
+```
+
+## Configuration
+
+| Setting            | Default                     |
+| ------------------ | --------------------------- |
+| `server_url` arg   | `AURASTAMP_API_URL` env var |
+| `AURASTAMP_API_URL`| `https://api.aurastamp.com` |
+
+## Errors
+
+Every failure raises `AurastampError`, carrying the server's `detail` message
+and the HTTP status where there is one.
+
+```python
+from aurastamp_sdk import AurastampError
+
+try:
+    aurastamp.image.encode_file(image_file_path="photo.png", message="way too long")
+except AurastampError as error:
+    print(error, error.status)
+```
+
+## Coming from the `aurastamp` package
+
+This supersedes `aurastamp` on PyPI, which is unmaintained and published from an
+account this project no longer controls. Its last release could not talk to the
+current API: it base64-decoded a response that was already raw PNG bytes and
+read keys off the decode response that the server never sends.
+
+The import is `aurastamp_sdk`, not `aurastamp` — two distributions installing
+the same top-level package would overwrite each other's files.
+
+If you depend on `aurastamp`, switch to `aurastamp-sdk`. What changed:
+
+- `encode` / `encode_local_file` → `encode` / `encode_file`, and they now return
+  **PNG bytes** rather than a `requests.Response`
+- `decode` / `decode_local_file` → `decode` / `decode_file`, returning the
+  message **string**
+- the unused `model`, `return_type` and `hidden_image` arguments are gone
+- failures raise `AurastampError` instead of returning a non-2xx response

aurastamp_sdk-1.0.0/README.md

@@ -0,0 +1,86 @@
+# Aurastamp SDK (Python)
+
+Hide and reveal short messages inside images.
+
+```sh
+pip install aurastamp-sdk
+```
+
+## The payload is 7 bytes
+
+The message is embedded in the image itself, and the model reserves exactly
+**7 bytes** for it. Anything longer is rejected before a request is made.
+
+That is 7 characters of ASCII, but fewer for anything else — `'가나'` is two
+characters and six bytes.
+
+To hide something longer, store the text somewhere and embed a short key
+instead; that is what [aurastamp.com](https://aurastamp.com) does.
+
+## Usage
+
+```python
+from aurastamp_sdk import Aurastamp
+
+aurastamp = Aurastamp()  # or Aurastamp("http://localhost:8000")
+
+# Hide a message
+encoded = aurastamp.image.encode_file(
+    image_file_path="photo.png",
+    message="hello",
+    output_path="encoded.png",
+)
+
+# Reveal it again
+print(aurastamp.image.decode_file(image_file_path="encoded.png"))
+#=> '  hello'   (padded to 7 bytes)
+```
+
+Working with bytes directly:
+
+```python
+with open("photo.png", "rb") as f:
+    encoded = aurastamp.image.encode(image=f.read(), message="hello", filename="photo.png")
+
+message = aurastamp.image.decode(image=encoded, filename="encoded.png")
+```
+
+## Configuration
+
+| Setting            | Default                     |
+| ------------------ | --------------------------- |
+| `server_url` arg   | `AURASTAMP_API_URL` env var |
+| `AURASTAMP_API_URL`| `https://api.aurastamp.com` |
+
+## Errors
+
+Every failure raises `AurastampError`, carrying the server's `detail` message
+and the HTTP status where there is one.
+
+```python
+from aurastamp_sdk import AurastampError
+
+try:
+    aurastamp.image.encode_file(image_file_path="photo.png", message="way too long")
+except AurastampError as error:
+    print(error, error.status)
+```
+
+## Coming from the `aurastamp` package
+
+This supersedes `aurastamp` on PyPI, which is unmaintained and published from an
+account this project no longer controls. Its last release could not talk to the
+current API: it base64-decoded a response that was already raw PNG bytes and
+read keys off the decode response that the server never sends.
+
+The import is `aurastamp_sdk`, not `aurastamp` — two distributions installing
+the same top-level package would overwrite each other's files.
+
+If you depend on `aurastamp`, switch to `aurastamp-sdk`. What changed:
+
+- `encode` / `encode_local_file` → `encode` / `encode_file`, and they now return
+  **PNG bytes** rather than a `requests.Response`
+- `decode` / `decode_local_file` → `decode` / `decode_file`, returning the
+  message **string**
+- the unused `model`, `return_type` and `hidden_image` arguments are gone
+- failures raise `AurastampError` instead of returning a non-2xx response

aurastamp_sdk-1.0.0/aurastamp_sdk/__init__.py

@@ -0,0 +1,16 @@
+from .aurastamp_image import (
+    DEFAULT_API_URL,
+    MAX_MESSAGE_BYTES,
+    AurastampError,
+    AurastampImage,
+)
+from .main import Aurastamp
+
+__all__ = [
+    "Aurastamp",
+    "AurastampError",
+    "AurastampImage",
+    "DEFAULT_API_URL",
+    "MAX_MESSAGE_BYTES",
+]
+__version__ = "2.0.0"

aurastamp_sdk-1.0.0/aurastamp_sdk/aurastamp_image.py

@@ -0,0 +1,130 @@
+import os
+from pathlib import Path
+
+import requests
+
+DEFAULT_API_URL = "https://api.aurastamp.com"
+
+# The steganographic payload is exactly 7 bytes wide.
+MAX_MESSAGE_BYTES = 7
+
+_CONTENT_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+}
+
+
+class AurastampError(Exception):
+    def __init__(self, message: str, status: int | None = None):
+        super().__init__(message)
+        self.status = status
+
+
+def _content_type_for(filename: str) -> str:
+    content_type = _CONTENT_TYPES.get(Path(filename).suffix.lower())
+    if content_type is None:
+        raise AurastampError(
+            f"unsupported image type: {filename}. only png and jpeg are supported"
+        )
+    return content_type
+
+
+def _describe(response: requests.Response) -> str:
+    try:
+        detail = response.json().get("detail")
+        if detail:
+            return detail
+    except ValueError:
+        pass
+    return f"request failed with status {response.status_code}"
+
+
+class AurastampImage:
+    def __init__(self, server_url: str | None = None):
+        self.server_url = (
+            server_url or os.getenv("AURASTAMP_API_URL") or DEFAULT_API_URL
+        ).rstrip("/")
+
+    def encode(
+        self,
+        image: bytes,
+        message: str,
+        filename: str = "image.png",
+        content_type: str | None = None,
+        headers: dict | None = None,
+        timeout: float = 120,
+    ) -> bytes:
+        """Hide `message` inside `image` and return the stamped PNG bytes."""
+        byte_length = len(message.encode("utf-8"))
+        if byte_length > MAX_MESSAGE_BYTES:
+            raise AurastampError(
+                f"message is {byte_length} bytes; "
+                f"the payload holds at most {MAX_MESSAGE_BYTES}"
+            )
+
+        response = requests.post(
+            f"{self.server_url}/encode",
+            files={"file": (filename, image, content_type or _content_type_for(filename))},
+            data={"message": message},
+            headers=headers or {},
+            timeout=timeout,
+        )
+        if not response.ok:
+            raise AurastampError(_describe(response), response.status_code)
+        # The endpoint returns the PNG itself, not a base64 payload.
+        return response.content
+
+    def decode(
+        self,
+        image: bytes,
+        filename: str = "image.png",
+        content_type: str | None = None,
+        headers: dict | None = None,
+        timeout: float = 120,
+    ) -> str:
+        """Recover the message hidden in `image`."""
+        response = requests.post(
+            f"{self.server_url}/decode",
+            files={"file": (filename, image, content_type or _content_type_for(filename))},
+            headers=headers or {},
+            timeout=timeout,
+        )
+        if not response.ok:
+            raise AurastampError(_describe(response), response.status_code)
+        # The endpoint returns the message as a bare JSON string.
+        return response.json()
+
+    def encode_file(
+        self,
+        image_file_path: str,
+        message: str,
+        output_path: str | None = None,
+        headers: dict | None = None,
+        timeout: float = 120,
+    ) -> bytes:
+        source = Path(image_file_path)
+        encoded = self.encode(
+            image=source.read_bytes(),
+            message=message,
+            filename=source.name,
+            headers=headers,
+            timeout=timeout,
+        )
+        if output_path:
+            Path(output_path).write_bytes(encoded)
+        return encoded
+
+    def decode_file(
+        self,
+        image_file_path: str,
+        headers: dict | None = None,
+        timeout: float = 120,
+    ) -> str:
+        source = Path(image_file_path)
+        return self.decode(
+            image=source.read_bytes(),
+            filename=source.name,
+            headers=headers,
+            timeout=timeout,
+        )

aurastamp_sdk-1.0.0/aurastamp_sdk/main.py

@@ -0,0 +1,6 @@
+from .aurastamp_image import AurastampImage
+
+
+class Aurastamp:
+    def __init__(self, server_url: str | None = None):
+        self.image = AurastampImage(server_url)

aurastamp_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aurastamp-sdk"
+version = "1.0.0"
+description = "Hide and reveal short messages inside images, via the Aurastamp API"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "sunutf" }]
+keywords = ["aurastamp", "steganography", "watermark", "image"]
+requires-python = ">=3.10"
+dependencies = ["requests>=2.31"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Multimedia :: Graphics",
+]
+
+[project.urls]
+Homepage = "https://aurastamp.com"
+Repository = "https://github.com/sunutf/aurastamp"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "responses>=0.25"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["aurastamp_sdk"]

aurastamp_sdk-1.0.0/tests/test_aurastamp.py

@@ -0,0 +1,62 @@
+import pytest
+import responses
+
+from aurastamp_sdk import Aurastamp, AurastampError
+
+API = "https://api.test"
+
+
+@responses.activate
+def test_encode_posts_message_and_returns_png_bytes():
+    responses.add(responses.POST, f"{API}/encode", body=b"\x89PNG", status=200)
+
+    result = Aurastamp(API).image.encode(image=b"fake", message="abc", filename="a.png")
+
+    assert result == b"\x89PNG"
+    request = responses.calls[0].request
+    # The server reads `message`, and returns raw PNG bytes rather than base64.
+    assert b'name="message"' in request.body
+    assert b"abc" in request.body
+
+
+@responses.activate
+def test_decode_returns_the_message():
+    responses.add(responses.POST, f"{API}/decode", json="  hello", status=200)
+
+    assert Aurastamp(API).image.decode(image=b"fake", filename="a.png") == "  hello"
+
+
+def test_message_longer_than_the_payload_is_rejected():
+    with pytest.raises(AurastampError, match="8 bytes"):
+        Aurastamp(API).image.encode(image=b"fake", message="12345678", filename="a.png")
+
+
+def test_message_is_measured_in_bytes_not_characters():
+    # '가나다' is 3 characters but 9 utf-8 bytes.
+    with pytest.raises(AurastampError, match="9 bytes"):
+        Aurastamp(API).image.encode(image=b"fake", message="가나다", filename="a.png")
+
+
+def test_unsupported_image_type_is_rejected():
+    with pytest.raises(AurastampError, match="only png and jpeg"):
+        Aurastamp(API).image.encode(image=b"fake", message="ok", filename="a.gif")
+
+
+@responses.activate
+def test_server_error_detail_is_surfaced():
+    responses.add(
+        responses.POST, f"{API}/encode", json={"detail": "could not read image"}, status=422
+    )
+
+    with pytest.raises(AurastampError, match="could not read image"):
+        Aurastamp(API).image.encode(image=b"fake", message="ok", filename="a.png")
+
+
+def test_server_url_falls_back_to_the_environment(monkeypatch):
+    monkeypatch.setenv("AURASTAMP_API_URL", "https://from-env.test")
+    assert Aurastamp().image.server_url == "https://from-env.test"
+
+
+def test_explicit_server_url_wins(monkeypatch):
+    monkeypatch.setenv("AURASTAMP_API_URL", "https://from-env.test")
+    assert Aurastamp("https://explicit.test/").image.server_url == "https://explicit.test"