kaappu-sdk 0.1.0__tar.gz

kaappu_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaappu
+
+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.

kaappu_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: kaappu-sdk
+Version: 0.1.0
+Summary: JWT authentication and permission-based authorization for Python services
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyJWT[crypto]>=2.8.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: flask
+Requires-Dist: Flask>=2.3.0; extra == "flask"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# kaappu-sdk
+
+JWT authentication and permission-based authorization for Python services. Works with Flask, FastAPI, or any Python HTTP framework.
+
+## Install
+
+```bash
+pip install kaappu-sdk
+
+# With Flask support
+pip install kaappu-sdk[flask]
+
+# With FastAPI support
+pip install kaappu-sdk[fastapi]
+```
+
+## Quick Start
+
+### Permission Checking
+
+```python
+from kaappu import check_permission, check_all_permissions, check_any_permission
+
+user_perms = ["users:read", "roles:read", "gateway:*"]
+
+check_permission(user_perms, "users:read")        # True
+check_permission(user_perms, "users:delete")       # False
+check_permission(user_perms, "gateway:view")       # True (wildcard)
+check_all_permissions(user_perms, ["users:read", "roles:read"])  # True
+check_any_permission(user_perms, ["users:delete", "roles:read"]) # True
+```
+
+Wildcard support:
+- `*` -- super wildcard, matches any permission
+- `resource:*` -- matches any action on that resource
+
+### Flask Route Protection
+
+```python
+from flask import Flask
+from kaappu.decorators import require_permission
+
+app = Flask(__name__)
+
+@app.route("/api/users")
+@require_permission("users:read")
+def list_users():
+    return {"users": []}
+```
+
+### Security Context
+
+```python
+from kaappu import SecurityContext
+from kaappu.context import set_context, get_context
+
+# Set context (typically in middleware)
+ctx = SecurityContext(
+    user_id="u_123",
+    account_id="acc_456",
+    email="user@example.com",
+    permissions=["users:read", "roles:read"],
+)
+set_context(ctx)
+
+# Read context anywhere in the same thread
+current = get_context()
+print(current.email)
+```
+
+### API Client
+
+```python
+from kaappu import KaappuClient
+
+client = KaappuClient(
+    base_url="https://your-kaappu-instance",
+    publishable_key="pk_live_...",
+)
+
+# Sign in
+result = client.sign_in("user@example.com", "password")
+access_token = result["accessToken"]
+
+# Get current user
+user = client.get_me(access_token)
+
+# Refresh token
+new_tokens = client.refresh_token(result["refreshToken"])
+```
+
+## API
+
+| Function / Class | Description |
+|------------------|-------------|
+| `check_permission(perms, required)` | Check a single permission with wildcard support |
+| `check_all_permissions(perms, required)` | Check that ALL permissions are satisfied |
+| `check_any_permission(perms, required)` | Check that ANY permission is satisfied |
+| `SecurityContext` | Dataclass holding user identity and permissions |
+| `set_context(ctx)` / `get_context()` | Thread-local security context storage |
+| `require_permission(perm)` | Flask route decorator for permission enforcement |
+| `KaappuClient` | API client for sign-in, sign-up, refresh, and user fetch |
+
+## Requirements
+
+- Python 3.9+
+- PyJWT 2.8+
+
+## License
+
+MIT

kaappu_sdk-0.1.0/README.md

@@ -0,0 +1,111 @@
+# kaappu-sdk
+
+JWT authentication and permission-based authorization for Python services. Works with Flask, FastAPI, or any Python HTTP framework.
+
+## Install
+
+```bash
+pip install kaappu-sdk
+
+# With Flask support
+pip install kaappu-sdk[flask]
+
+# With FastAPI support
+pip install kaappu-sdk[fastapi]
+```
+
+## Quick Start
+
+### Permission Checking
+
+```python
+from kaappu import check_permission, check_all_permissions, check_any_permission
+
+user_perms = ["users:read", "roles:read", "gateway:*"]
+
+check_permission(user_perms, "users:read")        # True
+check_permission(user_perms, "users:delete")       # False
+check_permission(user_perms, "gateway:view")       # True (wildcard)
+check_all_permissions(user_perms, ["users:read", "roles:read"])  # True
+check_any_permission(user_perms, ["users:delete", "roles:read"]) # True
+```
+
+Wildcard support:
+- `*` -- super wildcard, matches any permission
+- `resource:*` -- matches any action on that resource
+
+### Flask Route Protection
+
+```python
+from flask import Flask
+from kaappu.decorators import require_permission
+
+app = Flask(__name__)
+
+@app.route("/api/users")
+@require_permission("users:read")
+def list_users():
+    return {"users": []}
+```
+
+### Security Context
+
+```python
+from kaappu import SecurityContext
+from kaappu.context import set_context, get_context
+
+# Set context (typically in middleware)
+ctx = SecurityContext(
+    user_id="u_123",
+    account_id="acc_456",
+    email="user@example.com",
+    permissions=["users:read", "roles:read"],
+)
+set_context(ctx)
+
+# Read context anywhere in the same thread
+current = get_context()
+print(current.email)
+```
+
+### API Client
+
+```python
+from kaappu import KaappuClient
+
+client = KaappuClient(
+    base_url="https://your-kaappu-instance",
+    publishable_key="pk_live_...",
+)
+
+# Sign in
+result = client.sign_in("user@example.com", "password")
+access_token = result["accessToken"]
+
+# Get current user
+user = client.get_me(access_token)
+
+# Refresh token
+new_tokens = client.refresh_token(result["refreshToken"])
+```
+
+## API
+
+| Function / Class | Description |
+|------------------|-------------|
+| `check_permission(perms, required)` | Check a single permission with wildcard support |
+| `check_all_permissions(perms, required)` | Check that ALL permissions are satisfied |
+| `check_any_permission(perms, required)` | Check that ANY permission is satisfied |
+| `SecurityContext` | Dataclass holding user identity and permissions |
+| `set_context(ctx)` / `get_context()` | Thread-local security context storage |
+| `require_permission(perm)` | Flask route decorator for permission enforcement |
+| `KaappuClient` | API client for sign-in, sign-up, refresh, and user fetch |
+
+## Requirements
+
+- Python 3.9+
+- PyJWT 2.8+
+
+## License
+
+MIT

kaappu_sdk-0.1.0/kaappu/__init__.py

@@ -0,0 +1,14 @@
+"""Kaappu SDK for Python — JWT authentication and permission-based authorization."""
+
+from kaappu.permissions import check_permission, check_all_permissions, check_any_permission
+from kaappu.context import SecurityContext
+from kaappu.client import KaappuClient
+
+__version__ = "0.1.0"
+__all__ = [
+    "check_permission",
+    "check_all_permissions",
+    "check_any_permission",
+    "SecurityContext",
+    "KaappuClient",
+]

kaappu_sdk-0.1.0/kaappu/client.py

@@ -0,0 +1,71 @@
+"""API client for Kaappu Identity — sign in, sign up, refresh, verify."""
+
+from typing import Any, Dict, Optional
+import requests
+
+
+class KaappuClient:
+    """Framework-agnostic client for Kaappu Identity APIs."""
+
+    def __init__(self, base_url: str = "http://localhost:9091", publishable_key: str = ""):
+        self.base_url = base_url.rstrip("/")
+        self.publishable_key = publishable_key
+
+    def get_tenant_config(self) -> Optional[Dict[str, Any]]:
+        """Fetch tenant config (auth methods, branding, bot protection)."""
+        try:
+            r = requests.get(f"{self.base_url}/api/v1/accounts/config", params={"pk": self.publishable_key})
+            return r.json().get("data") if r.ok else None
+        except Exception:
+            return None
+
+    def sign_in(self, email: str, password: str, account_id: str = "default") -> Dict[str, Any]:
+        """Sign in with email + password. Returns accessToken, refreshToken, user."""
+        r = requests.post(f"{self.base_url}/api/v1/idm/auth/sign-in", json={
+            "email": email, "password": password, "accountId": account_id,
+        })
+        data = r.json()
+        if not data.get("success"):
+            raise Exception(data.get("error", "Sign in failed"))
+        return data["data"]
+
+    def sign_up(self, email: str, password: str, first_name: str = "", last_name: str = "",
+                account_id: str = "default") -> Dict[str, Any]:
+        """Sign up a new user. Returns accessToken, refreshToken, user."""
+        r = requests.post(f"{self.base_url}/api/v1/idm/auth/sign-up", json={
+            "email": email, "password": password,
+            "firstName": first_name, "lastName": last_name, "accountId": account_id,
+        })
+        data = r.json()
+        if not data.get("success"):
+            raise Exception(data.get("error", "Sign up failed"))
+        return data["data"]
+
+    def refresh_token(self, refresh_token: str) -> Optional[Dict[str, Any]]:
+        """Refresh an access token."""
+        try:
+            r = requests.post(f"{self.base_url}/api/v1/idm/auth/refresh", json={
+                "refreshToken": refresh_token,
+            })
+            return r.json().get("data") if r.ok else None
+        except Exception:
+            return None
+
+    def get_me(self, access_token: str) -> Optional[Dict[str, Any]]:
+        """Get current user profile."""
+        try:
+            r = requests.get(f"{self.base_url}/api/v1/idm/auth/me", headers={
+                "Authorization": f"Bearer {access_token}",
+            })
+            return r.json().get("data", {}).get("user") if r.ok else None
+        except Exception:
+            return None
+
+    def sign_out(self, access_token: str) -> None:
+        """Sign out — invalidate session."""
+        try:
+            requests.post(f"{self.base_url}/api/v1/idm/auth/sign-out", headers={
+                "Authorization": f"Bearer {access_token}",
+            })
+        except Exception:
+            pass

kaappu_sdk-0.1.0/kaappu/context.py

@@ -0,0 +1,33 @@
+"""Thread-local security context for the authenticated user."""
+
+import threading
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class SecurityContext:
+    """Holds the authenticated user's identity and permissions."""
+    user_id: str = ""
+    account_id: str = ""
+    email: str = ""
+    session_id: str = ""
+    permissions: List[str] = field(default_factory=list)
+
+
+_context = threading.local()
+
+
+def set_context(ctx: SecurityContext) -> None:
+    """Set the security context for the current thread."""
+    _context.kaappu = ctx
+
+
+def get_context() -> Optional[SecurityContext]:
+    """Get the security context for the current thread."""
+    return getattr(_context, "kaappu", None)
+
+
+def clear_context() -> None:
+    """Clear the security context for the current thread."""
+    _context.kaappu = None

kaappu_sdk-0.1.0/kaappu/decorators.py

@@ -0,0 +1,45 @@
+"""
+Decorators for Flask and FastAPI route protection.
+
+Flask usage:
+    @app.route("/api/users")
+    @require_permission("users:read")
+    def list_users():
+        ...
+
+FastAPI usage:
+    @app.get("/api/users")
+    async def list_users(ctx: SecurityContext = Depends(get_kaappu_context)):
+        ...
+"""
+
+from functools import wraps
+from typing import Callable
+
+from kaappu.context import get_context
+from kaappu.permissions import check_permission
+
+
+def require_permission(permission: str) -> Callable:
+    """
+    Decorator that checks the current SecurityContext for the required permission.
+    Returns 403 if the permission check fails.
+    Works with Flask routes.
+    """
+    def decorator(f: Callable) -> Callable:
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            ctx = get_context()
+            if ctx is None or not check_permission(ctx.permissions, permission):
+                # Flask import deferred to avoid hard dependency
+                try:
+                    from flask import jsonify
+                    return jsonify({
+                        "error": f"Forbidden: Requires {permission} permission",
+                        "code": "forbidden",
+                    }), 403
+                except ImportError:
+                    raise PermissionError(f"Requires {permission} permission")
+            return f(*args, **kwargs)
+        return wrapper
+    return decorator

kaappu_sdk-0.1.0/kaappu/permissions.py

@@ -0,0 +1,37 @@
+"""
+Framework-agnostic permission checking with wildcard support.
+Works with Flask, FastAPI, Django, or any Python service.
+"""
+
+from typing import List, Optional
+
+
+def check_permission(user_permissions: Optional[List[str]], required: str) -> bool:
+    """
+    Check if the user's permissions satisfy the required permission.
+
+    Supports:
+      - Exact match: 'users:read' satisfies 'users:read'
+      - Super wildcard: '*' satisfies any permission
+      - Resource wildcard: 'users:*' satisfies 'users:read', 'users:delete', etc.
+    """
+    if not required:
+        return True
+    if not user_permissions:
+        return False
+
+    resource = required.split(":")[0]
+    return any(
+        p == "*" or p == required or p == f"{resource}:*"
+        for p in user_permissions
+    )
+
+
+def check_all_permissions(user_permissions: Optional[List[str]], required: List[str]) -> bool:
+    """Check if the user has ALL required permissions."""
+    return all(check_permission(user_permissions, r) for r in required)
+
+
+def check_any_permission(user_permissions: Optional[List[str]], required: List[str]) -> bool:
+    """Check if the user has ANY of the required permissions."""
+    return any(check_permission(user_permissions, r) for r in required)

kaappu_sdk-0.1.0/kaappu_sdk.egg-info/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: kaappu-sdk
+Version: 0.1.0
+Summary: JWT authentication and permission-based authorization for Python services
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyJWT[crypto]>=2.8.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: flask
+Requires-Dist: Flask>=2.3.0; extra == "flask"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# kaappu-sdk
+
+JWT authentication and permission-based authorization for Python services. Works with Flask, FastAPI, or any Python HTTP framework.
+
+## Install
+
+```bash
+pip install kaappu-sdk
+
+# With Flask support
+pip install kaappu-sdk[flask]
+
+# With FastAPI support
+pip install kaappu-sdk[fastapi]
+```
+
+## Quick Start
+
+### Permission Checking
+
+```python
+from kaappu import check_permission, check_all_permissions, check_any_permission
+
+user_perms = ["users:read", "roles:read", "gateway:*"]
+
+check_permission(user_perms, "users:read")        # True
+check_permission(user_perms, "users:delete")       # False
+check_permission(user_perms, "gateway:view")       # True (wildcard)
+check_all_permissions(user_perms, ["users:read", "roles:read"])  # True
+check_any_permission(user_perms, ["users:delete", "roles:read"]) # True
+```
+
+Wildcard support:
+- `*` -- super wildcard, matches any permission
+- `resource:*` -- matches any action on that resource
+
+### Flask Route Protection
+
+```python
+from flask import Flask
+from kaappu.decorators import require_permission
+
+app = Flask(__name__)
+
+@app.route("/api/users")
+@require_permission("users:read")
+def list_users():
+    return {"users": []}
+```
+
+### Security Context
+
+```python
+from kaappu import SecurityContext
+from kaappu.context import set_context, get_context
+
+# Set context (typically in middleware)
+ctx = SecurityContext(
+    user_id="u_123",
+    account_id="acc_456",
+    email="user@example.com",
+    permissions=["users:read", "roles:read"],
+)
+set_context(ctx)
+
+# Read context anywhere in the same thread
+current = get_context()
+print(current.email)
+```
+
+### API Client
+
+```python
+from kaappu import KaappuClient
+
+client = KaappuClient(
+    base_url="https://your-kaappu-instance",
+    publishable_key="pk_live_...",
+)
+
+# Sign in
+result = client.sign_in("user@example.com", "password")
+access_token = result["accessToken"]
+
+# Get current user
+user = client.get_me(access_token)
+
+# Refresh token
+new_tokens = client.refresh_token(result["refreshToken"])
+```
+
+## API
+
+| Function / Class | Description |
+|------------------|-------------|
+| `check_permission(perms, required)` | Check a single permission with wildcard support |
+| `check_all_permissions(perms, required)` | Check that ALL permissions are satisfied |
+| `check_any_permission(perms, required)` | Check that ANY permission is satisfied |
+| `SecurityContext` | Dataclass holding user identity and permissions |
+| `set_context(ctx)` / `get_context()` | Thread-local security context storage |
+| `require_permission(perm)` | Flask route decorator for permission enforcement |
+| `KaappuClient` | API client for sign-in, sign-up, refresh, and user fetch |
+
+## Requirements
+
+- Python 3.9+
+- PyJWT 2.8+
+
+## License
+
+MIT

kaappu_sdk-0.1.0/kaappu_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+kaappu/__init__.py
+kaappu/client.py
+kaappu/context.py
+kaappu/decorators.py
+kaappu/permissions.py
+kaappu_sdk.egg-info/PKG-INFO
+kaappu_sdk.egg-info/SOURCES.txt
+kaappu_sdk.egg-info/dependency_links.txt
+kaappu_sdk.egg-info/requires.txt
+kaappu_sdk.egg-info/top_level.txt
+tests/test_permissions.py

kaappu_sdk-0.1.0/kaappu_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kaappu_sdk-0.1.0/kaappu_sdk.egg-info/requires.txt

@@ -0,0 +1,11 @@
+PyJWT[crypto]>=2.8.0
+requests>=2.31.0
+
+[dev]
+pytest>=7.0.0
+
+[fastapi]
+fastapi>=0.100.0
+
+[flask]
+Flask>=2.3.0

kaappu_sdk-0.1.0/kaappu_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+kaappu

kaappu_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kaappu-sdk"
+version = "0.1.0"
+description = "JWT authentication and permission-based authorization for Python services"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+dependencies = [
+    "PyJWT[crypto]>=2.8.0",
+    "requests>=2.31.0",
+]
+
+[project.optional-dependencies]
+flask = ["Flask>=2.3.0"]
+fastapi = ["fastapi>=0.100.0"]
+dev = ["pytest>=7.0.0"]
+
+[tool.setuptools.packages.find]
+include = ["kaappu*"]

kaappu_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kaappu_sdk-0.1.0/tests/test_permissions.py

@@ -0,0 +1,65 @@
+"""Tests for the permission checking module."""
+
+import pytest
+from kaappu.permissions import check_permission, check_all_permissions, check_any_permission
+
+
+class TestCheckPermission:
+    def test_exact_match(self):
+        assert check_permission(["users:read"], "users:read") is True
+
+    def test_no_match(self):
+        assert check_permission(["users:read"], "users:delete") is False
+
+    def test_super_wildcard(self):
+        assert check_permission(["*"], "anything:here") is True
+
+    def test_resource_wildcard(self):
+        assert check_permission(["users:*"], "users:delete") is True
+
+    def test_resource_wildcard_no_cross(self):
+        assert check_permission(["users:*"], "roles:read") is False
+
+    def test_empty_perms(self):
+        assert check_permission([], "users:read") is False
+
+    def test_none_perms(self):
+        assert check_permission(None, "users:read") is False
+
+    def test_empty_required(self):
+        assert check_permission([], "") is True
+
+    def test_owner_role(self):
+        assert check_permission(["*"], "gateway_instances:manage") is True
+
+    def test_admin_wildcards(self):
+        perms = ["users:*", "roles:*", "gateway:*"]
+        assert check_permission(perms, "users:delete") is True
+        assert check_permission(perms, "gateway:view") is True
+        assert check_permission(perms, "audit:read") is False
+
+    def test_viewer_denied_write(self):
+        perms = ["users:read", "roles:read"]
+        assert check_permission(perms, "users:read") is True
+        assert check_permission(perms, "users:delete") is False
+
+    def test_member_chat(self):
+        perms = ["governance_chat:use", "gateway_chat:use", "users:read"]
+        assert check_permission(perms, "governance_chat:use") is True
+        assert check_permission(perms, "gateway_instances:manage") is False
+
+
+class TestCheckAllPermissions:
+    def test_all_present(self):
+        assert check_all_permissions(["users:read", "roles:read"], ["users:read", "roles:read"]) is True
+
+    def test_one_missing(self):
+        assert check_all_permissions(["users:read"], ["users:read", "users:delete"]) is False
+
+
+class TestCheckAnyPermission:
+    def test_one_matches(self):
+        assert check_any_permission(["users:read"], ["users:delete", "users:read"]) is True
+
+    def test_none_match(self):
+        assert check_any_permission(["users:read"], ["roles:read", "groups:read"]) is False