ciphertoken 0.1.5__tar.gz → 0.1.7__tar.gz

ciphertoken-0.1.7/.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v6
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - run: pip install zensical
+      - run: zensical build --clean
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+      - uses: actions/deploy-pages@v5
+        id: deployment

{ciphertoken-0.1.5 → ciphertoken-0.1.7}/Cargo.lock

@@ -56,7 +56,7 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "ciphertoken"
-version = "0.1.5"
+version = "0.1.7"
 dependencies = [
  "base64 0.21.7",
  "jsonwebtoken",

{ciphertoken-0.1.5 → ciphertoken-0.1.7}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ciphertoken"
-version = "0.1.5"
+version = "0.1.7"
 edition = "2021"
 readme = "README.md"
 

ciphertoken-0.1.7/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: ciphertoken
+Version: 0.1.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Rust
+Classifier: Operating System :: OS Independent
+Summary: High-performance token and crypto utilities written in Rust with PyO3
+Author: Cipher-Unit
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+<img src="https://github.com/cipherunits/CipherToken/blob/main/logo.png" width=100>
+
+# CipherToken
+
+**CipherToken** is a **next-generation** token engine built for developers who demand speed, security, and reliability. Currently focused on **JWT**, it provides a complete token lifecycle — from key generation and token minting to verification, rotation, and expiry tracking — all backed by the raw performance of **Rust**.
+
+- Python 3.8+
+- HMAC, RSA, ECDSA, RSA-PSS, EdDSA
+- Sync and Async APIs via **Tokio**
+
+Built by **[Cipher-Unit](https://cipherunit.xyz/)**.
+
+---
+
+## Documentation
+
+📖 **Official Documentation:** [https://cipherunits.github.io/CipherToken/](https://cipherunits.github.io/CipherToken/)
+
+---
+
+## Installation
+
+```bash
+pip install ciphertoken
+```
+
+---
+
+## Quick Example
+
+```python
+from ciphertoken import CipherToken
+from ciphertoken.algorithms import HS256
+from ciphertoken.time import minutes, days
+from ciphertoken.jwt import access, refresh, rotation
+
+token = CipherToken(
+    secret="your-strong-secret-key",
+    algorithm=HS256,
+    access_ttl=minutes(10),
+    refresh_ttl=days(7),
+)
+
+access_token = access(token, payload={"user_id": 42})
+refresh_token = refresh(token, payload={"user_id": 42})
+new_access, new_refresh = rotation(token, refresh_token)
+
+print(token.verify(access_token))  # True
+print(token.decode(access_token))
+```
+
+---
+
+## Contribute
+
+Contributions are welcome! Whether it's bug fixes, new algorithms, documentation improvements, or feature suggestions — feel free to open an issue or pull request.
+
+- **Repository:** [https://github.com/cipherunits/CipherToken](https://github.com/cipherunits/CipherToken)
+- **Issues:** [https://github.com/cipherunits/CipherToken/issues](https://github.com/cipherunits/CipherToken/issues)
+
+Please read the code of conduct and contribution guidelines before submitting. All contributions must follow the MIT license.
+
+---
+
+## License
+
+**MIT** — see [LICENSE](LICENSE) for details.
+

ciphertoken-0.1.7/README.md

@@ -0,0 +1,67 @@
+<img src="https://github.com/cipherunits/CipherToken/blob/main/logo.png" width=100>
+
+# CipherToken
+
+**CipherToken** is a **next-generation** token engine built for developers who demand speed, security, and reliability. Currently focused on **JWT**, it provides a complete token lifecycle — from key generation and token minting to verification, rotation, and expiry tracking — all backed by the raw performance of **Rust**.
+
+- Python 3.8+
+- HMAC, RSA, ECDSA, RSA-PSS, EdDSA
+- Sync and Async APIs via **Tokio**
+
+Built by **[Cipher-Unit](https://cipherunit.xyz/)**.
+
+---
+
+## Documentation
+
+📖 **Official Documentation:** [https://cipherunits.github.io/CipherToken/](https://cipherunits.github.io/CipherToken/)
+
+---
+
+## Installation
+
+```bash
+pip install ciphertoken
+```
+
+---
+
+## Quick Example
+
+```python
+from ciphertoken import CipherToken
+from ciphertoken.algorithms import HS256
+from ciphertoken.time import minutes, days
+from ciphertoken.jwt import access, refresh, rotation
+
+token = CipherToken(
+    secret="your-strong-secret-key",
+    algorithm=HS256,
+    access_ttl=minutes(10),
+    refresh_ttl=days(7),
+)
+
+access_token = access(token, payload={"user_id": 42})
+refresh_token = refresh(token, payload={"user_id": 42})
+new_access, new_refresh = rotation(token, refresh_token)
+
+print(token.verify(access_token))  # True
+print(token.decode(access_token))
+```
+
+---
+
+## Contribute
+
+Contributions are welcome! Whether it's bug fixes, new algorithms, documentation improvements, or feature suggestions — feel free to open an issue or pull request.
+
+- **Repository:** [https://github.com/cipherunits/CipherToken](https://github.com/cipherunits/CipherToken)
+- **Issues:** [https://github.com/cipherunits/CipherToken/issues](https://github.com/cipherunits/CipherToken/issues)
+
+Please read the code of conduct and contribution guidelines before submitting. All contributions must follow the MIT license.
+
+---
+
+## License
+
+**MIT** — see [LICENSE](LICENSE) for details.

ciphertoken-0.1.7/ciphertoken/__init__.py

@@ -0,0 +1,51 @@
+"""Public Python API for ciphertoken."""
+
+from .algorithms import EDDSA, ES256, ES384, HS256, HS384, HS512, PS256, PS384, PS512, RS256, RS384, RS512
+from .ciphertoken import CipherToken, is_jwt_format, validate_jwt_format
+from .jwt import TOKEN_ACCESS as JWT_TOKEN_ACCESS, TOKEN_REFRESH as JWT_TOKEN_REFRESH
+from .jwt import access as jwt_access, refresh as jwt_refresh, rotation as jwt_rotation
+from .jwt import access_async as jwt_access_async, refresh_async as jwt_refresh_async, rotation_async as jwt_rotation_async
+from .secret import generate_hmac_secret, generate_hmac_secret_async, generate_rsa_keypair, secret_key, secret_key_with_size
+from .time import days, hours, minutes, now, seconds, weeks
+from .utils import DEFAULT_SECRET_SIZE, MIN_SECRET_SIZE, TOKEN_ACCESS, TOKEN_REFRESH
+
+__all__ = [
+    "CipherToken",
+    "is_jwt_format",
+    "validate_jwt_format",
+    "EDDSA",
+    "ES256",
+    "ES384",
+    "HS256",
+    "HS384",
+    "HS512",
+    "PS256",
+    "PS384",
+    "PS512",
+    "RS256",
+    "RS384",
+    "RS512",
+    "JWT_TOKEN_ACCESS",
+    "JWT_TOKEN_REFRESH",
+    "jwt_access",
+    "jwt_refresh",
+    "jwt_rotation",
+    "jwt_access_async",
+    "jwt_refresh_async",
+    "jwt_rotation_async",
+    "generate_hmac_secret",
+    "generate_hmac_secret_async",
+    "generate_rsa_keypair",
+    "secret_key",
+    "secret_key_with_size",
+    "days",
+    "hours",
+    "minutes",
+    "now",
+    "seconds",
+    "weeks",
+    "DEFAULT_SECRET_SIZE",
+    "MIN_SECRET_SIZE",
+    "TOKEN_ACCESS",
+    "TOKEN_REFRESH",
+]

{ciphertoken-0.1.5 → ciphertoken-0.1.7}/ciphertoken/__init__.pyi

@@ -1,5 +1,9 @@
 from .algorithms import EDDSA, ES256, ES384, HS256, HS384, HS512, PS256, PS384, PS512, RS256, RS384, RS512
 from .ciphertoken import CipherToken, is_jwt_format, validate_jwt_format
+from .jwt import TOKEN_ACCESS as JWT_TOKEN_ACCESS, TOKEN_REFRESH as JWT_TOKEN_REFRESH
+from .jwt import access as jwt_access, refresh as jwt_refresh, rotation as jwt_rotation
+from .jwt import access_async as jwt_access_async, refresh_async as jwt_refresh_async, rotation_async as jwt_rotation_async
 from .secret import generate_hmac_secret, generate_hmac_secret_async, generate_rsa_keypair, secret_key, secret_key_with_size
 from .time import days, hours, minutes, now, seconds, weeks
 from .utils import DEFAULT_SECRET_SIZE, MIN_SECRET_SIZE, TOKEN_ACCESS, TOKEN_REFRESH
+    

ciphertoken-0.1.7/ciphertoken/algorithms.py

@@ -0,0 +1,18 @@
+"""Python wrapper for Rust algorithms submodule."""
+
+from .ciphertoken import algorithms as _algorithms
+
+HS256 = _algorithms.HS256
+HS384 = _algorithms.HS384
+HS512 = _algorithms.HS512
+RS256 = _algorithms.RS256
+RS384 = _algorithms.RS384
+RS512 = _algorithms.RS512
+ES256 = _algorithms.ES256
+ES384 = _algorithms.ES384
+PS256 = _algorithms.PS256
+PS384 = _algorithms.PS384
+PS512 = _algorithms.PS512
+EDDSA = _algorithms.EDDSA
+
+__all__ = ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "PS256", "PS384", "PS512", "EDDSA"]

{ciphertoken-0.1.5 → ciphertoken-0.1.7}/ciphertoken/ciphertoken.pyi

@@ -3,20 +3,21 @@ from typing import Any, Dict, Optional, Tuple
 class CipherToken:
     def __init__(self, secret: str, algorithm: str, access_ttl: int, refresh_ttl: int) -> None: ...
 
-    def access(self, user_id: int, extra_payload: Optional[Dict[str, Any]] = None) -> str: ...
-    def refresh(self, user_id: int, extra_payload: Optional[Dict[str, Any]] = None) -> str: ...
+    def payload(self, payload: Optional[Dict[str, Any]] = None) -> str: ...
+    def access(self, payload: Optional[Dict[str, Any]] = None) -> str: ...
+    def refresh(self, payload: Optional[Dict[str, Any]] = None) -> str: ...
     def decode(self, token: str) -> Dict[str, Any]: ...
     def verify(self, token: str) -> bool: ...
-    def rotation(self, refresh_token: str, extra_payload: Optional[Dict[str, Any]] = None) -> Tuple[str, str]: ...
+    def rotation(self, refresh_token: str, payload: Optional[Dict[str, Any]] = None) -> Tuple[str, str]: ...
     def inspect(self, token: str) -> Dict[str, Any]: ...
     def remaining_time(self, token: str) -> Optional[int]: ...
     def algorithm_name(self) -> str: ...
 
-    async def access_async(self, user_id: int, extra_payload: Optional[Dict[str, Any]] = None) -> str: ...
-    async def refresh_async(self, user_id: int, extra_payload: Optional[Dict[str, Any]] = None) -> str: ...
+    async def access_async(self, payload: Optional[Dict[str, Any]] = None) -> str: ...
+    async def refresh_async(self, payload: Optional[Dict[str, Any]] = None) -> str: ...
     async def decode_async(self, token: str) -> Dict[str, Any]: ...
     async def verify_async(self, token: str) -> bool: ...
-    async def rotation_async(self, refresh_token: str, extra_payload: Optional[Dict[str, Any]] = None) -> Tuple[str, str]: ...
+    async def rotation_async(self, refresh_token: str, payload: Optional[Dict[str, Any]] = None) -> Tuple[str, str]: ...
 
 def is_jwt_format(token: str) -> bool: ...
 def validate_jwt_format(token: str) -> bool: ...

ciphertoken-0.1.7/ciphertoken/jwt.py

@@ -0,0 +1,25 @@
+"""Python wrapper for Rust jwt submodule."""
+
+from .ciphertoken import jwt as _jwt
+
+TOKEN_ACCESS = _jwt.TOKEN_ACCESS
+TOKEN_REFRESH = _jwt.TOKEN_REFRESH
+
+access = _jwt.access
+refresh = _jwt.refresh
+rotation = _jwt.rotation
+
+access_async = _jwt.access_async
+refresh_async = _jwt.refresh_async
+rotation_async = _jwt.rotation_async
+
+__all__ = [
+    "TOKEN_ACCESS",
+    "TOKEN_REFRESH",
+    "access",
+    "refresh",
+    "rotation",
+    "access_async",
+    "refresh_async",
+    "rotation_async",
+]

ciphertoken-0.1.7/ciphertoken/jwt.pyi

@@ -0,0 +1,13 @@
+from typing import Any, Dict, Optional, Tuple
+from .ciphertoken import CipherToken
+
+TOKEN_ACCESS: str
+TOKEN_REFRESH: str
+
+def access(token: CipherToken, payload: Optional[Dict[str, Any]] = None) -> str: ...
+def refresh(token: CipherToken, payload: Optional[Dict[str, Any]] = None) -> str: ...
+def rotation(token: CipherToken, refresh_token: str, payload: Optional[Dict[str, Any]] = None) -> Tuple[str, str]: ...
+
+async def access_async(token: CipherToken, payload: Optional[Dict[str, Any]] = None) -> str: ...
+async def refresh_async(token: CipherToken, payload: Optional[Dict[str, Any]] = None) -> str: ...
+async def rotation_async(token: CipherToken, refresh_token: str, payload: Optional[Dict[str, Any]] = None) -> Tuple[str, str]: ...

ciphertoken-0.1.7/ciphertoken/secret.py

@@ -0,0 +1,17 @@
+"""Python wrapper for Rust secret submodule."""
+
+from .ciphertoken import secret as _secret
+
+secret_key = _secret.secret_key
+secret_key_with_size = _secret.secret_key_with_size
+generate_hmac_secret = _secret.generate_hmac_secret
+generate_hmac_secret_async = _secret.generate_hmac_secret_async
+generate_rsa_keypair = _secret.generate_rsa_keypair
+
+__all__ = [
+    "secret_key",
+    "secret_key_with_size",
+    "generate_hmac_secret",
+    "generate_hmac_secret_async",
+    "generate_rsa_keypair",
+]

ciphertoken-0.1.7/ciphertoken/time.py

@@ -0,0 +1,12 @@
+"""Python wrapper for Rust time submodule."""
+
+from .ciphertoken import time as _time
+
+now = _time.now
+seconds = _time.seconds
+minutes = _time.minutes
+hours = _time.hours
+days = _time.days
+weeks = _time.weeks
+
+__all__ = ["now", "seconds", "minutes", "hours", "days", "weeks"]

ciphertoken-0.1.7/ciphertoken/utils.py

@@ -0,0 +1,10 @@
+"""Python wrapper for Rust utils submodule."""
+
+from .ciphertoken import utils as _utils
+
+DEFAULT_SECRET_SIZE = _utils.DEFAULT_SECRET_SIZE
+MIN_SECRET_SIZE = _utils.MIN_SECRET_SIZE
+TOKEN_ACCESS = _utils.TOKEN_ACCESS
+TOKEN_REFRESH = _utils.TOKEN_REFRESH
+
+__all__ = ["DEFAULT_SECRET_SIZE", "MIN_SECRET_SIZE", "TOKEN_ACCESS", "TOKEN_REFRESH"]

ciphertoken-0.1.7/docs/advanced/async.md

@@ -0,0 +1,163 @@
+# Advanced Guide — Async
+
+**CipherToken** provides full asynchronous support via `pyo3-asyncio` and the `tokio` runtime. All token operations have async equivalents.
+
+---
+
+## When to Use Async
+
+Use async methods when your application already runs inside an async framework such as **FastAPI**, **Sanic**, or **AioHTTP**. The async methods provide the same functionality as sync methods without blocking the event loop.
+
+---
+
+## Async API Surface
+
+| Async Method | Sync Equivalent |
+|--------------|-----------------|
+| `access_async(payload) -> str` | `access(payload) -> str` |
+| `refresh_async(payload) -> str` | `refresh(payload) -> str` |
+| `decode_async(token) -> dict` | `decode(token) -> dict` |
+| `verify_async(token) -> bool` | `verify(token) -> bool` |
+| `rotation_async(refresh_token, payload) -> Tuple[str, str]` | `rotation(refresh_token, payload) -> Tuple[str, str]` |
+
+---
+
+## FastAPI Example
+
+```python
+from fastapi import FastAPI, Depends, HTTPException
+from ciphertoken import CipherToken
+from ciphertoken.algorithms import HS256
+from ciphertoken.time import minutes, days
+
+app = FastAPI()
+
+# Shared token instance (initialize once at startup)
+cipher = CipherToken(
+    secret="your-strong-secret-key",
+    algorithm=HS256,
+    access_ttl=minutes(10),
+    refresh_ttl=days(7),
+)
+
+@app.post("/auth/login")
+async def login(username: str, password: str):
+    # Validate credentials (pseudo-code)
+    user_id = await authenticate_user(username, password)
+    if not user_id:
+        raise HTTPException(status_code=401, detail="Invalid credentials")
+
+    access_token = await cipher.access_async(payload={"sub": username, "user_id": user_id})
+    refresh_token = await cipher.refresh_async(payload={"sub": username, "user_id": user_id})
+
+    return {"access_token": access_token, "refresh_token": refresh_token}
+
+
+@app.post("/auth/refresh")
+async def refresh_token_endpoint(refresh_token: str):
+    is_valid = await cipher.verify_async(refresh_token)
+    if not is_valid:
+        raise HTTPException(status_code=401, detail="Invalid refresh token")
+
+    payload = await cipher.decode_async(refresh_token)
+    new_access, new_refresh = await cipher.rotation_async(
+        refresh_token,
+        payload={"sub": payload["payload"]["sub"], "user_id": payload["payload"]["user_id"]},
+    )
+
+    return {"access_token": new_access, "refresh_token": new_refresh}
+```
+
+---
+
+## Direct `asyncio` Usage
+
+```python
+import asyncio
+from ciphertoken import CipherToken
+from ciphertoken.algorithms import HS256
+from ciphertoken.time import minutes, days
+
+cipher = CipherToken(
+    secret="my-secret",
+    algorithm=HS256,
+    access_ttl=minutes(10),
+    refresh_ttl=days(7),
+)
+
+async def main():
+    access_token = await cipher.access_async(payload={"user_id": 1})
+    refresh_token = await cipher.refresh_async(payload={"user_id": 1})
+
+    claims = await cipher.decode_async(access_token)
+    print(claims)
+
+    new_access, new_refresh = await cipher.rotation_async(refresh_token)
+
+    print(f"Valid: {await cipher.verify_async(access_token)}")
+
+asyncio.run(main())
+```
+
+---
+
+## Key Pair Generation (Async)
+
+```python
+import asyncio
+from ciphertoken.secret import generate_rsa_keypair, generate_hmac_secret_async
+from ciphertoken import CipherToken
+from ciphertoken.algorithms import RS256
+from ciphertoken.time import minutes
+
+async def setup():
+    private_key, public_key = generate_rsa_keypair(bits=4096)
+    secret = await generate_hmac_secret_async(64)
+
+    token_rsa = CipherToken(
+        secret=private_key,
+        algorithm=RS256,
+        access_ttl=minutes(15),
+        refresh_ttl=minutes(60),
+    )
+
+    token_hmac = CipherToken(
+        secret=secret,
+        algorithm=HS256,
+        access_ttl=minutes(15),
+        refresh_ttl=minutes(60),
+    )
+
+asyncio.run(setup())
+```
+
+---
+
+## Async with `jwt` Module
+
+```python
+import asyncio
+from ciphertoken.jwt import access_async, refresh_async, rotation_async
+
+async def main():
+    token = CipherToken(
+        secret="secret",
+        algorithm=HS256,
+        access_ttl=minutes(10),
+        refresh_ttl=days(7),
+    )
+
+    access_token = await access_async(token, payload={"sub": "user"})
+    refresh_token = await refresh_async(token, payload={"sub": "user"})
+    new_access, new_refresh = await rotation_async(token, refresh_token)
+
+asyncio.run(main())
+```
+
+---
+
+## Performance Notes
+
+- CipherToken async methods use **`tokio`** underneath — they scale well across concurrent requests.
+- There is **no performance penalty** for calling sync methods from sync contexts as long as you do not await them.
+- See the [security guide](security.md) for guidance on secret handling in async environments.

ciphertoken-0.1.7/docs/advanced/index.md

@@ -0,0 +1,17 @@
+# Advanced Guide
+
+Production topics for **CipherToken** — the next-generation token engine.
+
+## Topics
+
+- [Async Usage](async.md) — Full async API with Tokio under the hood
+- [Security Best Practices](security.md) — Key management, rotation, algorithm selection
+
+---
+
+## Async First
+
+Developed by **[Cipher-Unit](https://cipherunit.xyz/)**. Every sync method has an async twin, backed by **Tokio**. No secondary package, no compatibility layers — it is part of the core engine.
+
+!!! tip "Production async"
+    Use `CipherToken` async methods in FastAPI, Sanic, or AioHTTP for GIL-free token operations at scale.