sealedwebtoken 1.0.0__py3-none-any.whl

sealedwebtoken-1.0.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: sealedwebtoken
+Version: 1.0.0
+Summary: Official Python SDK for Odysii Sealed Web Tokens (SWT)
+Project-URL: Homepage, https://swt.odysii.in
+Project-URL: Repository, https://github.com/snskar125/swt
+Author: snskar125
+License: ISC
+Keywords: authentication,jwt,sealed-web-tokens,swt,tokens
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.9; extra == 'async'
+Description-Content-Type: text/markdown
+
+# sealedwebtoken
+
+The official Python SDK for Odysii Sealed Web Tokens (SWT).
+
+## Installation
+
+```bash
+# Sync client only (zero dependencies)
+pip install sealedwebtoken
+
+# With async support (installs aiohttp)
+pip install sealedwebtoken[async]
+```
+
+## Usage
+
+### Sync
+
+```python
+import time
+import swt
+
+secret = "your-super-secret-key"
+payload = {"user_id": 123, "role": "admin"}
+
+# 1. Sign a token (expiresAt is required, max 31 days)
+expires_at = int(time.time()) + 3600  # 1 hour from now
+resp = swt.sign(payload, secret=secret, expires_at=expires_at)
+print("Token:", resp.token)
+print("Expires at:", resp.expires_at)
+
+# 2. Verify a token
+v = swt.verify(resp.token, secret=secret)
+if v.valid:
+    print("Payload:", v.payload)
+
+# 3. Revoke a token
+swt.revoke(resp.token, secret=secret)
+print("Token revoked")
+```
+
+### Async
+
+```python
+import asyncio, time
+import swt
+
+async def main():
+    client = swt.AsyncSWTClient()
+    expires_at = int(time.time()) + 3600
+
+    resp = await client.sign({"user_id": 42}, secret="mysecret123", expires_at=expires_at)
+    print("Token:", resp.token)
+
+    v = await client.verify(resp.token, secret="mysecret123")
+    if v.valid:
+        print("Payload:", v.payload)
+
+    await client.revoke(resp.token, secret="mysecret123")
+    print("Token revoked")
+
+asyncio.run(main())
+```
+
+### Using the class-based client
+
+```python
+import swt
+
+# Create a reusable client
+client = swt.SWTClient()
+resp = client.sign({"user_id": 1}, secret="mysecret123", expires_at=...)
+```
+
+## API Reference
+
+### `swt.sign(payload, *, secret, expires_at) → SignResponse`
+
+- `payload` — `dict` to embed in the token (max 512 bytes serialised)
+- `secret` — string, min 8 characters
+- `expires_at` — Unix timestamp in seconds, **required**, max 31 days from now
+
+### `swt.verify(token, *, secret=None) → VerifyResponse`
+
+- `token` — the SWT token string
+- `secret` — optional; if provided, validates the secret matches
+
+### `swt.revoke(token, *, secret) → RevokeResponse`
+
+- `token` — the SWT token string to revoke
+- `secret` — the secret used when signing

sealedwebtoken-1.0.0.dist-info/RECORD

@@ -0,0 +1,4 @@
+swt/__init__.py,sha256=tbHi8fD7upx-Sj0p-136aQA_O5jLqgbnRN7KjeAAFpY,12684
+sealedwebtoken-1.0.0.dist-info/METADATA,sha256=BSP5NlpDBSWCvrT63tJdK221cs0ohVqxo2K0F3ObNIk,2757
+sealedwebtoken-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sealedwebtoken-1.0.0.dist-info/RECORD,,

sealedwebtoken-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

swt/__init__.py

@@ -0,0 +1,345 @@
+"""
+swt — Official Python SDK for Odysii Sealed Web Tokens (SWT).
+
+Provides both a synchronous client (SWTClient) and an async client
+(AsyncSWTClient) that mirror the Node.js SDK's sign/verify/revoke API.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+# ─────────────────────────────────────────────────────────────────────────────
+# RESPONSE TYPES
+# ─────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class SignResponse:
+    """Returned by sign() on success."""
+
+    token: str
+    """The issued SWT token string."""
+
+    expires_at: int
+    """Unix timestamp (seconds) when the token expires."""
+
+
+@dataclass
+class VerifyResponse:
+    """Returned by verify() on success."""
+
+    valid: bool
+    """True if the token is valid, not expired, and not revoked."""
+
+    payload: dict[str, Any] | None = None
+    """The caller-supplied payload embedded in the token. None if invalid."""
+
+    expires_at: int | None = None
+    """Unix timestamp when the token expires. None if invalid."""
+
+
+@dataclass
+class RevokeResponse:
+    """Returned by revoke() on success."""
+
+    success: bool
+    """True if the token was revoked (or was already revoked)."""
+
+    message: str | None = None
+    """Optional human-readable status message."""
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# EXCEPTIONS
+# ─────────────────────────────────────────────────────────────────────────────
+
+class SWTError(Exception):
+    """Raised when the SWT API returns an error response."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# CONSTANTS
+# ─────────────────────────────────────────────────────────────────────────────
+
+_API_URL = "https://api.swt.odysii.in"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# SYNC CLIENT
+# ─────────────────────────────────────────────────────────────────────────────
+
+class SWTClient:
+    """
+    Synchronous SWT client using urllib (zero dependencies).
+
+    Example::
+
+        import swt
+
+        client = swt.SWTClient()
+
+        # Sign
+        import time
+        expires_at = int(time.time()) + 3600  # 1 hour from now
+        resp = client.sign({"user_id": 42}, secret="mysecret123", expires_at=expires_at)
+        print(resp.token)
+
+        # Verify
+        v = client.verify(resp.token, secret="mysecret123")
+        if v.valid:
+            print(v.payload)
+
+        # Revoke
+        client.revoke(resp.token, secret="mysecret123")
+    """
+
+    def __init__(self, base_url: str = _API_URL) -> None:
+        self._base_url = base_url.rstrip("/")
+
+    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        """Make a synchronous POST request using urllib (no third-party deps)."""
+        import urllib.request
+        import urllib.error
+
+        data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(
+            f"{self._base_url}{path}",
+            data=data,
+            headers={
+                "Content-Type": "application/json",
+                "User-Agent": "odysii-swt-python/1.0.0",
+            },
+            method="POST",
+        )
+
+        try:
+            with urllib.request.urlopen(req) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            # Read the error body for the API error message
+            try:
+                error_body = json.loads(exc.read().decode("utf-8"))
+                msg = error_body.get("error", f"HTTP {exc.code}")
+            except Exception:
+                msg = f"HTTP {exc.code}"
+            raise SWTError(msg, status_code=exc.code) from exc
+
+    def sign(
+        self,
+        payload: dict[str, Any],
+        *,
+        secret: str,
+        expires_at: int,
+    ) -> SignResponse:
+        """
+        Issue a new SWT token.
+
+        :param payload:    Arbitrary dict to embed in the token (max 512 bytes serialised).
+        :param secret:     Secret used for signing (min 8 characters).
+        :param expires_at: Required Unix timestamp (seconds) for expiry. Max 31 days from now.
+        :raises SWTError:  If the API returns an error.
+        """
+        data = self._post("/v1/sign", {
+            "secret": secret,
+            "payload": payload,
+            "expiresAt": expires_at,
+        })
+        return SignResponse(token=data["token"], expires_at=data["expiresAt"])
+
+    def verify(
+        self,
+        token: str,
+        *,
+        secret: str | None = None,
+    ) -> VerifyResponse:
+        """
+        Verify a SWT token.
+
+        :param token:     The token string to verify.
+        :param secret:    Optional — if provided, also validates the secret matches.
+        :raises SWTError: If the API returns a non-auth error.
+        """
+        body: dict[str, Any] = {"token": token}
+        if secret is not None:
+            body["secret"] = secret
+
+        data = self._post("/v1/verify", body)
+        return VerifyResponse(
+            valid=data.get("valid", False),
+            payload=data.get("payload"),
+            expires_at=data.get("expiresAt"),
+        )
+
+    def revoke(self, token: str, *, secret: str) -> RevokeResponse:
+        """
+        Revoke a SWT token.
+
+        :param token:     The token string to revoke.
+        :param secret:    The secret that was used to sign the token.
+        :raises SWTError: If the API returns an error.
+        """
+        data = self._post("/v1/revoke", {"token": token, "secret": secret})
+        return RevokeResponse(success=data.get("success", False), message=data.get("message"))
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# ASYNC CLIENT
+# ─────────────────────────────────────────────────────────────────────────────
+
+class AsyncSWTClient:
+    """
+    Asynchronous SWT client using aiohttp.
+
+    Requires ``aiohttp`` to be installed::
+
+        pip install swt[async]
+
+    Example::
+
+        import asyncio, time
+        import swt
+
+        async def main():
+            client = swt.AsyncSWTClient()
+            expires_at = int(time.time()) + 3600
+
+            resp = await client.sign({"user_id": 42}, secret="mysecret123", expires_at=expires_at)
+            print(resp.token)
+
+            v = await client.verify(resp.token, secret="mysecret123")
+            if v.valid:
+                print(v.payload)
+
+            await client.revoke(resp.token, secret="mysecret123")
+
+        asyncio.run(main())
+    """
+
+    def __init__(self, base_url: str = _API_URL) -> None:
+        self._base_url = base_url.rstrip("/")
+
+    async def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        """Make an async POST request using aiohttp."""
+        try:
+            import aiohttp
+        except ImportError as exc:
+            raise ImportError(
+                "AsyncSWTClient requires aiohttp. Install it with: pip install swt[async]"
+            ) from exc
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                f"{self._base_url}{path}",
+                json=body,
+                headers={
+                    "Content-Type": "application/json",
+                    "User-Agent": "odysii-swt-python/1.0.0",
+                },
+            ) as resp:
+                data = await resp.json()
+                if not resp.ok:
+                    msg = data.get("error", f"HTTP {resp.status}") if isinstance(data, dict) else f"HTTP {resp.status}"
+                    raise SWTError(msg, status_code=resp.status)
+                return data
+
+    async def sign(
+        self,
+        payload: dict[str, Any],
+        *,
+        secret: str,
+        expires_at: int,
+    ) -> SignResponse:
+        """
+        Issue a new SWT token (async).
+
+        :param payload:    Arbitrary dict to embed in the token (max 512 bytes serialised).
+        :param secret:     Secret used for signing (min 8 characters).
+        :param expires_at: Required Unix timestamp (seconds) for expiry. Max 31 days from now.
+        :raises SWTError:  If the API returns an error.
+        """
+        data = await self._post("/v1/sign", {
+            "secret": secret,
+            "payload": payload,
+            "expiresAt": expires_at,
+        })
+        return SignResponse(token=data["token"], expires_at=data["expiresAt"])
+
+    async def verify(
+        self,
+        token: str,
+        *,
+        secret: str | None = None,
+    ) -> VerifyResponse:
+        """
+        Verify a SWT token (async).
+
+        :param token:     The token string to verify.
+        :param secret:    Optional — if provided, also validates the secret matches.
+        :raises SWTError: If the API returns a non-auth error.
+        """
+        body: dict[str, Any] = {"token": token}
+        if secret is not None:
+            body["secret"] = secret
+
+        data = await self._post("/v1/verify", body)
+        return VerifyResponse(
+            valid=data.get("valid", False),
+            payload=data.get("payload"),
+            expires_at=data.get("expiresAt"),
+        )
+
+    async def revoke(self, token: str, *, secret: str) -> RevokeResponse:
+        """
+        Revoke a SWT token (async).
+
+        :param token:     The token string to revoke.
+        :param secret:    The secret that was used to sign the token.
+        :raises SWTError: If the API returns an error.
+        """
+        data = await self._post("/v1/revoke", {"token": token, "secret": secret})
+        return RevokeResponse(success=data.get("success", False), message=data.get("message"))
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# MODULE-LEVEL CONVENIENCE (mirrors Node.js SDK's functional API)
+# ─────────────────────────────────────────────────────────────────────────────
+
+_default_client = SWTClient()
+
+
+def sign(
+    payload: dict[str, Any],
+    *,
+    secret: str,
+    expires_at: int,
+) -> SignResponse:
+    """Module-level sign() — uses a shared default SWTClient."""
+    return _default_client.sign(payload, secret=secret, expires_at=expires_at)
+
+
+def verify(token: str, *, secret: str | None = None) -> VerifyResponse:
+    """Module-level verify() — uses a shared default SWTClient."""
+    return _default_client.verify(token, secret=secret)
+
+
+def revoke(token: str, *, secret: str) -> RevokeResponse:
+    """Module-level revoke() — uses a shared default SWTClient."""
+    return _default_client.revoke(token, secret=secret)
+
+
+__all__ = [
+    "SWTClient",
+    "AsyncSWTClient",
+    "SignResponse",
+    "VerifyResponse",
+    "RevokeResponse",
+    "SWTError",
+    "sign",
+    "verify",
+    "revoke",
+]