tausi 0.1.0__tar.gz

tausi-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/

tausi-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## Unreleased
+
+- `captcha_token=` for `sign_up()`, `sign_in()` and `forgot_password()`, and `get_captcha_config()`.
+- `PASSWORD_BREACHED`, `CAPTCHA_REQUIRED` and `CAPTCHA_INVALID` error codes.
+- `redirect_to=` for `sign_up()`, `send_verification_email()` and `forgot_password()`: choose where email links open.
+- Backend: `users.ban()`, `unban()`, `suspend(hours=|until=)`, `unsuspend()` and `bulk()`; `users.list(access=)`; `User.access`, `is_blocked` and the ban/suspension fields.
+- `ACCOUNT_BANNED` and `ACCOUNT_SUSPENDED` error codes and OAuth error messages.
+- `User` gains `first_name`, `last_name`, `username`, `phone_number`, `phone_number_verified`, `locale`, `timezone`, `public_metadata`, `last_sign_in_at`, and from the backend `private_metadata`, `last_sign_out_at`, `sign_in_count`, `active_sessions`, `last_active_at`, `status` and `is_signed_in`.
+- `sign_up()`, `update_user()` and `users.update()` accept the new attributes (and metadata for the backend).
+- `EMAIL_ALREADY_REGISTERED` and `USERNAME_TAKEN` error codes.
+
+## 0.1.0
+
+- First release: `TausiBackend` (verify sessions, manage users), `TausiClient` (server-rendered sign-in), Django decorators and middleware, Django REST framework authentication, and a Flask extension.

tausi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tausi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tausi-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.5
+Name: tausi
+Version: 0.1.0
+Summary: Official Python SDK for Tausi: verify sessions and manage users from your backend, with Django and Flask integrations.
+Project-URL: Homepage, https://tausi.app
+Project-URL: Documentation, https://github.com/Nelacommunity/tausi-auth/tree/main/sdks/python#readme
+Project-URL: Repository, https://github.com/Nelacommunity/tausi-auth
+Project-URL: Issues, https://github.com/Nelacommunity/tausi-auth/issues
+Project-URL: Changelog, https://github.com/Nelacommunity/tausi-auth/blob/main/sdks/python/CHANGELOG.md
+Author: Tausi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: auth,authentication,django,flask,oauth,sessions,tausi
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Session
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: django>=4.2; extra == 'dev'
+Requires-Dist: djangorestframework>=3.15; extra == 'dev'
+Requires-Dist: flask>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: flask
+Requires-Dist: flask>=2.3; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# tausi (Python)
+
+Official Python SDK for [Tausi](https://tausi.app), with Django, Django REST framework and Flask integrations. It needs Python 3.9 or later and has **no runtime dependencies**: it uses the standard library for HTTP.
+
+| | Key | Use it for |
+| --- | --- | --- |
+| `tausi.TausiBackend` | secret key `sk_…` | Protecting your API (verifying session tokens) and managing your project's users. |
+| `tausi.TausiClient` | publishable key `pk_…` | Server-rendered apps where Python signs the user in and keeps their token in the session, plus scripts and CLIs. |
+
+```sh
+pip install tausi            # core
+pip install "tausi[django]"  # + Django
+pip install "tausi[flask]"   # + Flask
+```
+
+## Protect your API
+
+Your frontend (built with `@tausi-auth/js`, Flutter, etc.) sends the user's session token as `Authorization: Bearer <token>`. Your backend checks it with the secret key:
+
+```python
+import os
+from tausi import TausiBackend
+
+tausi = TausiBackend("https://tausi.app", os.environ["TAUSI_SECRET_KEY"])
+
+auth = tausi.authenticate_request(request)   # any request with .headers, or the header value itself
+if auth is None:
+    ...                                       # 401
+print(auth.user.id, auth.user.email, auth.session.expires_at)
+```
+
+`authenticate_request()` and `verify_session(token)` return `None` when a token is invalid, expired, revoked or belongs to another project. They raise `TausiError` only when the problem is on your side: a wrong key, a network failure or a 5xx response.
+
+### Django
+
+```python
+# settings.py
+TAUSI_URL = "https://tausi.app"
+TAUSI_SECRET_KEY = os.environ["TAUSI_SECRET_KEY"]
+
+# views.py
+from django.http import JsonResponse
+from tausi.django import tausi_required, tausi_optional
+
+@tausi_required                   # 401 JSON without a valid token; works on async views too
+def me(request):
+    return JsonResponse(request.tausi.user.to_dict())
+
+@tausi_optional                   # request.tausi is an AuthResult or None
+def feed(request):
+    ...
+```
+
+To set `request.tausi` on every request, add `"tausi.django.TausiAuthMiddleware"` to `MIDDLEWARE`. Only requests that carry a bearer token cost a call to Tausi. When Tausi can't be reached, the decorators and middleware answer `503` with code `AUTH_UNAVAILABLE`.
+
+Each setting falls back to the environment variable of the same name (`TAUSI_URL`, `TAUSI_SECRET_KEY`, `TAUSI_PUBLISHABLE_KEY`). `TAUSI_TIMEOUT` sets the request timeout in seconds (default 10).
+
+### Django REST framework
+
+```python
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": ["tausi.django.rest_framework.TausiAuthentication"],
+    "DEFAULT_PERMISSION_CLASSES": ["rest_framework.permissions.IsAuthenticated"],
+}
+```
+
+In views, `request.user` is a `tausi.User` (with `is_authenticated = True`) and `request.auth` is the full `AuthResult`. Requests without a bearer token fall through to your other authentication classes.
+
+### Flask
+
+```python
+from flask import Flask, g
+from tausi.flask import Tausi
+
+app = Flask(__name__)
+app.config["TAUSI_URL"] = "https://tausi.app"
+app.config["TAUSI_SECRET_KEY"] = os.environ["TAUSI_SECRET_KEY"]
+tausi = Tausi(app)                # or tausi = Tausi(); tausi.init_app(app)
+
+@app.get("/api/me")
+@tausi.required                   # 401 JSON without a valid token
+def me():
+    return g.tausi.user.to_dict()
+
+@app.get("/api/feed")
+@tausi.optional                   # g.tausi is an AuthResult or None
+def feed():
+    ...
+```
+
+## Manage users
+
+```python
+page = tausi.users.list(q="asha", verified=True, page=1, page_size=50)   # Page[User]
+for user in page.items:
+    print(user.email, user.status, user.active_sessions, user.last_sign_in_at)
+
+detail = tausi.users.get(user_id)        # {"user": User, "accounts": [...], "sessions": [...], "recentAudit": [...]}
+tausi.users.update(user_id, name="Asha", email_verified=True)
+tausi.users.revoke_sessions(user_id)     # sign out everywhere
+tausi.users.delete(user_id)
+tausi.sessions.list(page=1)
+tausi.get_project()                      # startup check that the key works
+```
+
+From Django you get the configured backend with `tausi.django.get_backend()`; from Flask, `tausi.backend` inside an app context.
+
+## Server-rendered sign-in
+
+When your Python app renders the sign-in form itself, use `TausiClient` with the publishable key. The token stays in the server-side session and never reaches the browser.
+
+### Django
+
+```python
+# settings.py: TAUSI_PUBLISHABLE_KEY = os.environ["TAUSI_PUBLISHABLE_KEY"], plus SessionMiddleware
+from django.shortcuts import redirect, render
+from tausi import TausiError
+from tausi.django import get_client, tausi_login_required
+
+def sign_in(request):
+    if request.method == "POST":
+        try:
+            get_client(request).sign_in(request.POST["email"], request.POST["password"])
+            return redirect(request.GET.get("next", "/"))
+        except TausiError as e:
+            return render(request, "sign_in.html", {"error": e.message, "code": e.code})
+    return render(request, "sign_in.html")
+
+def sign_out(request):
+    get_client(request).sign_out()
+    return redirect("/")
+
+@tausi_login_required             # redirects to settings.LOGIN_URL with ?next=
+def dashboard(request):
+    return render(request, "dashboard.html", {"user": request.tausi.user})
+```
+
+### Flask
+
+```python
+@app.post("/sign-in")
+def login():
+    try:
+        tausi.client().sign_in(request.form["email"], request.form["password"])
+    except TausiError as e:
+        return render_template("sign_in.html", error=e.message), 400
+    return redirect(request.args.get("next", "/"))
+
+@app.get("/dashboard")
+@tausi.login_required(login_endpoint="login")
+def dashboard():
+    return render_template("dashboard.html", user=g.tausi.user)
+```
+
+### Social sign-in (PKCE)
+
+```python
+def start_google(request):
+    start = get_client(request).start_oauth("google", redirect_to="https://example.com/auth/callback")
+    request.session["tausi_verifier"] = start.code_verifier
+    return redirect(start.url)
+
+def callback(request):
+    verifier = request.session.pop("tausi_verifier", "")
+    try:
+        get_client(request).handle_oauth_redirect(request.build_absolute_uri(), verifier)
+    except TausiError as e:
+        return render(request, "sign_in.html", {"error": e.message})
+    return redirect("/")
+```
+
+`redirect_to` must be on one of the project's allowed origins.
+
+### All client methods
+
+`sign_up`, `sign_in`, `sign_out`, `get_session`, `send_verification_email`, `verify_email`, `forgot_password`, `reset_password`, `change_password`, `get_user`, `update_user`, `delete_account`, `list_sessions`, `revoke_session`, `revoke_other_sessions`, `get_providers`, `start_oauth`, `exchange_oauth_code`, `handle_oauth_redirect`.
+
+Outside a web framework, `TausiClient` keeps the token in memory. Pass `token_store=` with any object that has `get()` and `set(token)` to keep it elsewhere; `MappingTokenStore(some_dict)` stores it in a dict-like session.
+
+## Errors
+
+Every failure is a `TausiError` with `status`, `code`, `message`, `details`, `request_id` and `retry_after` (seconds, for `RATE_LIMITED`). Network failures have `status == 0` and code `NETWORK_ERROR` or `TIMEOUT`. Branch on `code`, not on the message.
+
+```python
+try:
+    client.sign_in(email, password)
+except TausiError as e:
+    if e.code == "EMAIL_NOT_VERIFIED":
+        ...
+```
+
+## Custom HTTP
+
+The default transport is `urllib` from the standard library. To use `requests`, `httpx` or a test double, pass `transport=` to either client: a callable `(method, url, headers, body, timeout) -> tausi.HttpResponse`.
+
+## Development
+
+```sh
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```

tausi-0.1.0/README.md

@@ -0,0 +1,201 @@
+# tausi (Python)
+
+Official Python SDK for [Tausi](https://tausi.app), with Django, Django REST framework and Flask integrations. It needs Python 3.9 or later and has **no runtime dependencies**: it uses the standard library for HTTP.
+
+| | Key | Use it for |
+| --- | --- | --- |
+| `tausi.TausiBackend` | secret key `sk_…` | Protecting your API (verifying session tokens) and managing your project's users. |
+| `tausi.TausiClient` | publishable key `pk_…` | Server-rendered apps where Python signs the user in and keeps their token in the session, plus scripts and CLIs. |
+
+```sh
+pip install tausi            # core
+pip install "tausi[django]"  # + Django
+pip install "tausi[flask]"   # + Flask
+```
+
+## Protect your API
+
+Your frontend (built with `@tausi-auth/js`, Flutter, etc.) sends the user's session token as `Authorization: Bearer <token>`. Your backend checks it with the secret key:
+
+```python
+import os
+from tausi import TausiBackend
+
+tausi = TausiBackend("https://tausi.app", os.environ["TAUSI_SECRET_KEY"])
+
+auth = tausi.authenticate_request(request)   # any request with .headers, or the header value itself
+if auth is None:
+    ...                                       # 401
+print(auth.user.id, auth.user.email, auth.session.expires_at)
+```
+
+`authenticate_request()` and `verify_session(token)` return `None` when a token is invalid, expired, revoked or belongs to another project. They raise `TausiError` only when the problem is on your side: a wrong key, a network failure or a 5xx response.
+
+### Django
+
+```python
+# settings.py
+TAUSI_URL = "https://tausi.app"
+TAUSI_SECRET_KEY = os.environ["TAUSI_SECRET_KEY"]
+
+# views.py
+from django.http import JsonResponse
+from tausi.django import tausi_required, tausi_optional
+
+@tausi_required                   # 401 JSON without a valid token; works on async views too
+def me(request):
+    return JsonResponse(request.tausi.user.to_dict())
+
+@tausi_optional                   # request.tausi is an AuthResult or None
+def feed(request):
+    ...
+```
+
+To set `request.tausi` on every request, add `"tausi.django.TausiAuthMiddleware"` to `MIDDLEWARE`. Only requests that carry a bearer token cost a call to Tausi. When Tausi can't be reached, the decorators and middleware answer `503` with code `AUTH_UNAVAILABLE`.
+
+Each setting falls back to the environment variable of the same name (`TAUSI_URL`, `TAUSI_SECRET_KEY`, `TAUSI_PUBLISHABLE_KEY`). `TAUSI_TIMEOUT` sets the request timeout in seconds (default 10).
+
+### Django REST framework
+
+```python
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": ["tausi.django.rest_framework.TausiAuthentication"],
+    "DEFAULT_PERMISSION_CLASSES": ["rest_framework.permissions.IsAuthenticated"],
+}
+```
+
+In views, `request.user` is a `tausi.User` (with `is_authenticated = True`) and `request.auth` is the full `AuthResult`. Requests without a bearer token fall through to your other authentication classes.
+
+### Flask
+
+```python
+from flask import Flask, g
+from tausi.flask import Tausi
+
+app = Flask(__name__)
+app.config["TAUSI_URL"] = "https://tausi.app"
+app.config["TAUSI_SECRET_KEY"] = os.environ["TAUSI_SECRET_KEY"]
+tausi = Tausi(app)                # or tausi = Tausi(); tausi.init_app(app)
+
+@app.get("/api/me")
+@tausi.required                   # 401 JSON without a valid token
+def me():
+    return g.tausi.user.to_dict()
+
+@app.get("/api/feed")
+@tausi.optional                   # g.tausi is an AuthResult or None
+def feed():
+    ...
+```
+
+## Manage users
+
+```python
+page = tausi.users.list(q="asha", verified=True, page=1, page_size=50)   # Page[User]
+for user in page.items:
+    print(user.email, user.status, user.active_sessions, user.last_sign_in_at)
+
+detail = tausi.users.get(user_id)        # {"user": User, "accounts": [...], "sessions": [...], "recentAudit": [...]}
+tausi.users.update(user_id, name="Asha", email_verified=True)
+tausi.users.revoke_sessions(user_id)     # sign out everywhere
+tausi.users.delete(user_id)
+tausi.sessions.list(page=1)
+tausi.get_project()                      # startup check that the key works
+```
+
+From Django you get the configured backend with `tausi.django.get_backend()`; from Flask, `tausi.backend` inside an app context.
+
+## Server-rendered sign-in
+
+When your Python app renders the sign-in form itself, use `TausiClient` with the publishable key. The token stays in the server-side session and never reaches the browser.
+
+### Django
+
+```python
+# settings.py: TAUSI_PUBLISHABLE_KEY = os.environ["TAUSI_PUBLISHABLE_KEY"], plus SessionMiddleware
+from django.shortcuts import redirect, render
+from tausi import TausiError
+from tausi.django import get_client, tausi_login_required
+
+def sign_in(request):
+    if request.method == "POST":
+        try:
+            get_client(request).sign_in(request.POST["email"], request.POST["password"])
+            return redirect(request.GET.get("next", "/"))
+        except TausiError as e:
+            return render(request, "sign_in.html", {"error": e.message, "code": e.code})
+    return render(request, "sign_in.html")
+
+def sign_out(request):
+    get_client(request).sign_out()
+    return redirect("/")
+
+@tausi_login_required             # redirects to settings.LOGIN_URL with ?next=
+def dashboard(request):
+    return render(request, "dashboard.html", {"user": request.tausi.user})
+```
+
+### Flask
+
+```python
+@app.post("/sign-in")
+def login():
+    try:
+        tausi.client().sign_in(request.form["email"], request.form["password"])
+    except TausiError as e:
+        return render_template("sign_in.html", error=e.message), 400
+    return redirect(request.args.get("next", "/"))
+
+@app.get("/dashboard")
+@tausi.login_required(login_endpoint="login")
+def dashboard():
+    return render_template("dashboard.html", user=g.tausi.user)
+```
+
+### Social sign-in (PKCE)
+
+```python
+def start_google(request):
+    start = get_client(request).start_oauth("google", redirect_to="https://example.com/auth/callback")
+    request.session["tausi_verifier"] = start.code_verifier
+    return redirect(start.url)
+
+def callback(request):
+    verifier = request.session.pop("tausi_verifier", "")
+    try:
+        get_client(request).handle_oauth_redirect(request.build_absolute_uri(), verifier)
+    except TausiError as e:
+        return render(request, "sign_in.html", {"error": e.message})
+    return redirect("/")
+```
+
+`redirect_to` must be on one of the project's allowed origins.
+
+### All client methods
+
+`sign_up`, `sign_in`, `sign_out`, `get_session`, `send_verification_email`, `verify_email`, `forgot_password`, `reset_password`, `change_password`, `get_user`, `update_user`, `delete_account`, `list_sessions`, `revoke_session`, `revoke_other_sessions`, `get_providers`, `start_oauth`, `exchange_oauth_code`, `handle_oauth_redirect`.
+
+Outside a web framework, `TausiClient` keeps the token in memory. Pass `token_store=` with any object that has `get()` and `set(token)` to keep it elsewhere; `MappingTokenStore(some_dict)` stores it in a dict-like session.
+
+## Errors
+
+Every failure is a `TausiError` with `status`, `code`, `message`, `details`, `request_id` and `retry_after` (seconds, for `RATE_LIMITED`). Network failures have `status == 0` and code `NETWORK_ERROR` or `TIMEOUT`. Branch on `code`, not on the message.
+
+```python
+try:
+    client.sign_in(email, password)
+except TausiError as e:
+    if e.code == "EMAIL_NOT_VERIFIED":
+        ...
+```
+
+## Custom HTTP
+
+The default transport is `urllib` from the standard library. To use `requests`, `httpx` or a test double, pass `transport=` to either client: a callable `(method, url, headers, body, timeout) -> tausi.HttpResponse`.
+
+## Development
+
+```sh
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```

tausi-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tausi"
+version = "0.1.0"
+description = "Official Python SDK for Tausi: verify sessions and manage users from your backend, with Django and Flask integrations."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Tausi" }]
+keywords = ["tausi", "auth", "authentication", "sessions", "oauth", "django", "flask"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Django",
+    "Framework :: Flask",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: WWW/HTTP :: Session",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+django = ["django>=4.2"]
+flask = ["flask>=2.3"]
+dev = ["pytest>=8", "django>=4.2", "flask>=2.3", "djangorestframework>=3.15"]
+
+[project.urls]
+Homepage = "https://tausi.app"
+Documentation = "https://github.com/Nelacommunity/tausi-auth/tree/main/sdks/python#readme"
+Repository = "https://github.com/Nelacommunity/tausi-auth"
+Issues = "https://github.com/Nelacommunity/tausi-auth/issues"
+Changelog = "https://github.com/Nelacommunity/tausi-auth/blob/main/sdks/python/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tausi"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/tausi", "tests", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tausi-0.1.0/src/tausi/__init__.py

@@ -0,0 +1,39 @@
+"""Official Python SDK for Tausi.
+
+* :class:`TausiBackend` (secret key ``sk_...``): verify session tokens and manage users.
+* :class:`TausiClient` (publishable key ``pk_...``): sign users in from server-rendered apps, scripts and CLIs.
+* ``tausi.django`` and ``tausi.flask``: framework integrations.
+"""
+
+from ._http import SDK_VERSION, HttpResponse, Transport, urllib_transport
+from .backend import TausiBackend, bearer_token
+from .client import TausiClient, oauth_error_message, parse_oauth_redirect, random_device_id
+from .errors import TausiError
+from .models import AuthResult, OAuthStart, Page, Session, User
+from .pkce import create_pkce
+from .token_store import MappingTokenStore, MemoryTokenStore, TokenStore
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "SDK_VERSION",
+    "AuthResult",
+    "HttpResponse",
+    "MappingTokenStore",
+    "MemoryTokenStore",
+    "OAuthStart",
+    "Page",
+    "Session",
+    "TausiBackend",
+    "TausiClient",
+    "TausiError",
+    "TokenStore",
+    "Transport",
+    "User",
+    "bearer_token",
+    "create_pkce",
+    "oauth_error_message",
+    "parse_oauth_redirect",
+    "random_device_id",
+    "urllib_transport",
+]