openkitx403 0.1.1__py3-none-any.whl

openkitx403/__init__.py

@@ -0,0 +1,47 @@
+"""OpenKitx403 - HTTP-native wallet authentication for Solana"""
+
+__version__ = "0.1.0"
+
+from .core import (
+    Challenge,
+    AuthorizationParams,
+    VerifyResult,
+    ReplayStore,
+    InMemoryReplayStore,
+    create_challenge,
+    verify_authorization,
+    base64url_encode,
+    base64url_decode,
+    generate_nonce,
+    current_timestamp,
+    parse_authorization_header,
+    build_signing_string
+)
+
+from .middleware import (
+    OpenKit403Config,
+    OpenKit403Middleware,
+    OpenKit403User,
+    require_openkitx403_user
+)
+
+__all__ = [
+    '__version__',
+    'Challenge',
+    'AuthorizationParams',
+    'VerifyResult',
+    'ReplayStore',
+    'InMemoryReplayStore',
+    'create_challenge',
+    'verify_authorization',
+    'base64url_encode',
+    'base64url_decode',
+    'generate_nonce',
+    'current_timestamp',
+    'parse_authorization_header',
+    'build_signing_string',
+    'OpenKit403Config',
+    'OpenKit403Middleware',
+    'OpenKit403User',
+    'require_openkitx403_user'
+]

openkitx403/core.py

@@ -0,0 +1,387 @@
+"""OpenKitx403 Python Server SDK - Core Functions"""
+import json
+import base64
+import secrets
+from datetime import datetime, timedelta, timezone
+from typing import Dict, Optional, Any, Protocol
+from dataclasses import dataclass
+import base58
+from nacl.signing import VerifyKey
+from nacl.exceptions import BadSignatureError
+
+
+@dataclass
+class Challenge:
+    """OpenKitx403 challenge structure"""
+    v: int
+    alg: str
+    nonce: str
+    ts: str
+    aud: str
+    method: str
+    path: str
+    uaBind: bool
+    originBind: bool
+    serverId: str
+    exp: str
+    ext: Dict[str, Any]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "v": self.v,
+            "alg": self.alg,
+            "nonce": self.nonce,
+            "ts": self.ts,
+            "aud": self.aud,
+            "method": self.method,
+            "path": self.path,
+            "uaBind": self.uaBind,
+            "originBind": self.originBind,
+            "serverId": self.serverId,
+            "exp": self.exp,
+            "ext": self.ext
+        }
+
+
+@dataclass
+class AuthorizationParams:
+    """Parsed authorization header parameters"""
+    addr: str
+    sig: str
+    challenge: str
+    ts: str
+    nonce: str
+    bind: Optional[str] = None
+
+
+@dataclass
+class VerifyResult:
+    """Verification result"""
+    ok: bool
+    address: Optional[str] = None
+    challenge: Optional[Challenge] = None
+    error: Optional[str] = None
+
+
+class ReplayStore(Protocol):
+    """Protocol for replay protection stores"""
+    async def check(self, key: str, ttl_seconds: int) -> bool:
+        """Check if nonce was already used"""
+        ...
+    
+    async def store(self, key: str, ttl_seconds: int) -> None:
+        """Store nonce to prevent replay"""
+        ...
+
+
+class InMemoryReplayStore:
+    """Simple in-memory replay store with LRU-like behavior"""
+    
+    def __init__(self, max_size: int = 10000):
+        self._cache: Dict[str, float] = {}
+        self._max_size = max_size
+    
+    async def check(self, key: str, ttl_seconds: int) -> bool:
+        """Check if key exists and not expired"""
+        expiry = self._cache.get(key)
+        if not expiry:
+            return False
+        
+        if datetime.now(timezone.utc).timestamp() > expiry:
+            del self._cache[key]
+            return False
+        
+        return True
+    
+    async def store(self, key: str, ttl_seconds: int) -> None:
+        """Store key with expiry"""
+        # Simple LRU: remove oldest if at capacity
+        if len(self._cache) >= self._max_size:
+            oldest = next(iter(self._cache))
+            del self._cache[oldest]
+        
+        expiry = datetime.now(timezone.utc).timestamp() + ttl_seconds
+        self._cache[key] = expiry
+        
+        # Periodic cleanup
+        if secrets.randbelow(100) < 1:  # 1% chance
+            self._cleanup()
+    
+    def _cleanup(self) -> None:
+        """Remove expired entries"""
+        now = datetime.now(timezone.utc).timestamp()
+        expired = [k for k, v in self._cache.items() if now > v]
+        for k in expired:
+            del self._cache[k]
+
+
+def base64url_encode(data: bytes | str) -> str:
+    """Encode to base64url (no padding)"""
+    if isinstance(data, str):
+        data = data.encode('utf-8')
+    
+    b64 = base64.urlsafe_b64encode(data).decode('ascii')
+    return b64.rstrip('=')
+
+
+def base64url_decode(s: str) -> str:
+    """Decode from base64url"""
+    # Add padding
+    padding = (4 - len(s) % 4) % 4
+    s_padded = s + '=' * padding
+    
+    decoded = base64.urlsafe_b64decode(s_padded)
+    return decoded.decode('utf-8')
+
+
+def generate_nonce() -> str:
+    """Generate cryptographically random nonce"""
+    return base64url_encode(secrets.token_bytes(16))
+
+
+def current_timestamp() -> str:
+    """Get current UTC timestamp in ISO format"""
+    return datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
+
+
+def parse_authorization_header(header: str) -> Optional[AuthorizationParams]:
+    """Parse OpenKitx403 authorization header"""
+    if not header.startswith('OpenKitx403 '):
+        return None
+    
+    params: Dict[str, str] = {}
+    import re
+    
+    for match in re.finditer(r'(\w+)="([^"]*)"', header):
+        params[match.group(1)] = match.group(2)
+    
+    required = ['addr', 'sig', 'challenge', 'ts', 'nonce']
+    if not all(k in params for k in required):
+        return None
+    
+    return AuthorizationParams(
+        addr=params['addr'],
+        sig=params['sig'],
+        challenge=params['challenge'],
+        ts=params['ts'],
+        nonce=params['nonce'],
+        bind=params.get('bind')
+    )
+
+
+def build_signing_string(challenge: Challenge) -> str:
+    """Build canonical signing string"""
+    # Sort keys for deterministic JSON
+    payload = json.dumps(challenge.to_dict(), sort_keys=True)
+    
+    lines = [
+        'OpenKitx403 Challenge',
+        '',
+        f'domain: {challenge.aud}',
+        f'server: {challenge.serverId}',
+        f'nonce: {challenge.nonce}',
+        f'ts: {challenge.ts}',
+        f'method: {challenge.method}',
+        f'path: {challenge.path}',
+        '',
+        f'payload: {payload}'
+    ]
+    
+    return '\n'.join(lines)
+
+
+def create_challenge(
+    method: str,
+    path: str,
+    audience: str,
+    issuer: str,
+    ttl_seconds: int = 60,
+    ua_binding: bool = False,
+    origin_binding: bool = False,
+    ext: Optional[Dict[str, Any]] = None
+) -> tuple[str, Challenge]:
+    """
+    Create an OpenKitx403 challenge
+    
+    Returns:
+        (header_value, challenge_object)
+    """
+    now = datetime.now(timezone.utc)
+    exp = now + timedelta(seconds=ttl_seconds)
+    
+    challenge = Challenge(
+        v=1,
+        alg='ed25519-solana',
+        nonce=generate_nonce(),
+        ts=now.strftime('%Y-%m-%dT%H:%M:%SZ'),
+        aud=audience,
+        method=method,
+        path=path,
+        uaBind=ua_binding,
+        originBind=origin_binding,
+        serverId=issuer,
+        exp=exp.strftime('%Y-%m-%dT%H:%M:%SZ'),
+        ext=ext or {}
+    )
+    
+    challenge_json = json.dumps(challenge.to_dict(), sort_keys=True)
+    challenge_encoded = base64url_encode(challenge_json)
+    
+    header_value = f'OpenKitx403 realm="{issuer}", version="1", challenge="{challenge_encoded}"'
+    
+    return header_value, challenge
+
+
+async def verify_authorization(
+    auth_header: str,
+    method: str,
+    path: str,
+    audience: str,
+    issuer: str,
+    ttl_seconds: int = 60,
+    clock_skew_seconds: int = 120,
+    bind_method_path: bool = False,
+    origin_binding: bool = False,
+    ua_binding: bool = False,
+    replay_store: Optional[ReplayStore] = None,
+    token_gate: Optional[callable] = None,
+    headers: Optional[Dict[str, str]] = None
+) -> VerifyResult:
+    """
+    Verify OpenKitx403 authorization header
+    
+    Returns:
+        VerifyResult with ok=True and address on success
+    """
+    # Parse header
+    params = parse_authorization_header(auth_header)
+    if not params:
+        return VerifyResult(ok=False, error="Invalid authorization header")
+    
+    # Decode challenge
+    try:
+        challenge_json = base64url_decode(params.challenge)
+        challenge_dict = json.loads(challenge_json)
+        challenge = Challenge(**challenge_dict)
+    except Exception as e:
+        return VerifyResult(ok=False, error=f"Invalid challenge format: {e}")
+    
+    # Check protocol version
+    if challenge.v != 1:
+        return VerifyResult(ok=False, error="Unsupported protocol version")
+    
+    # Check algorithm
+    if challenge.alg != 'ed25519-solana':
+        return VerifyResult(ok=False, error="Unsupported algorithm")
+    
+    # Check expiration
+    try:
+        exp_time = datetime.fromisoformat(challenge.exp.replace('Z', '+00:00'))
+        if datetime.now(timezone.utc) > exp_time:
+            return VerifyResult(ok=False, error="Challenge expired")
+    except Exception:
+        return VerifyResult(ok=False, error="Invalid expiration format")
+    
+    # Check audience
+    if challenge.aud != audience:
+        return VerifyResult(ok=False, error="Invalid audience")
+    
+    # Check server ID
+    if challenge.serverId != issuer:
+        return VerifyResult(ok=False, error="Invalid server ID")
+    
+    # Check timestamp skew
+    try:
+        client_ts = datetime.fromisoformat(params.ts.replace('Z', '+00:00'))
+        now = datetime.now(timezone.utc)
+        diff = abs((now - client_ts).total_seconds())
+        
+        if diff > clock_skew_seconds:
+            return VerifyResult(ok=False, error="Timestamp outside allowed skew")
+    except Exception:
+        return VerifyResult(ok=False, error="Invalid timestamp format")
+    
+    # Check method/path binding
+    if bind_method_path or params.bind:
+        if challenge.method != method or challenge.path != path:
+            return VerifyResult(ok=False, error="Method/path mismatch")
+        
+        if params.bind:
+            expected_bind = f"{method}:{path}"
+            if params.bind != expected_bind:
+                return VerifyResult(ok=False, error="Bind parameter mismatch")
+    
+    # Check origin binding
+    if challenge.originBind and headers:
+        origin = headers.get('origin') or headers.get('referer')
+        if not origin:
+            return VerifyResult(ok=False, error="Origin binding required but not provided")
+        
+        try:
+            from urllib.parse import urlparse
+            origin_parsed = urlparse(origin)
+            aud_parsed = urlparse(challenge.aud)
+            
+            if f"{origin_parsed.scheme}://{origin_parsed.netloc}" != f"{aud_parsed.scheme}://{aud_parsed.netloc}":
+                return VerifyResult(ok=False, error="Origin binding mismatch")
+        except Exception:
+            return VerifyResult(ok=False, error="Invalid origin format")
+    
+    # Check UA binding
+    if challenge.uaBind and headers:
+        if not headers.get('user-agent'):
+            return VerifyResult(ok=False, error="User-Agent binding required but not provided")
+    
+    # Check replay
+    if replay_store:
+        replay_key = f"{params.addr}:{params.nonce}"
+        is_replay = await replay_store.check(replay_key, ttl_seconds)
+        
+        if is_replay:
+            return VerifyResult(ok=False, error="Nonce already used (replay detected)")
+        
+        await replay_store.store(replay_key, ttl_seconds)
+    
+    # Verify signature
+    try:
+        public_key_bytes = base58.b58decode(params.addr)
+        signature_bytes = base58.b58decode(params.sig)
+        
+        signing_string = build_signing_string(challenge)
+        message = signing_string.encode('utf-8')
+        
+        verify_key = VerifyKey(public_key_bytes)
+        verify_key.verify(message, signature_bytes)
+        
+    except BadSignatureError:
+        return VerifyResult(ok=False, error="Invalid signature")
+    except Exception as e:
+        return VerifyResult(ok=False, error=f"Signature verification failed: {e}")
+    
+    # Check token gate
+    if token_gate:
+        try:
+            allowed = await token_gate(params.addr)
+            if not allowed:
+                return VerifyResult(ok=False, error="Token gate check failed")
+        except Exception as e:
+            return VerifyResult(ok=False, error=f"Token gate error: {e}")
+    
+    return VerifyResult(ok=True, address=params.addr, challenge=challenge)
+
+
+__all__ = [
+    'Challenge',
+    'AuthorizationParams',
+    'VerifyResult',
+    'ReplayStore',
+    'InMemoryReplayStore',
+    'create_challenge',
+    'verify_authorization',
+    'base64url_encode',
+    'base64url_decode',
+    'generate_nonce',
+    'current_timestamp',
+    'parse_authorization_header',
+    'build_signing_string'
+]

openkitx403/middleware.py

@@ -0,0 +1,194 @@
+"""OpenKitx403 FastAPI Middleware"""
+from typing import Optional, Callable, Dict, Any
+from fastapi import Request, Response, status
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.types import ASGIApp
+
+from .core import (
+    create_challenge,
+    verify_authorization,
+    ReplayStore,
+    InMemoryReplayStore,
+    VerifyResult
+)
+
+
+class OpenKit403Config:
+    """Configuration for OpenKit403 middleware"""
+    
+    def __init__(
+        self,
+        audience: str,
+        issuer: str,
+        ttl_seconds: int = 60,
+        clock_skew_seconds: int = 120,
+        bind_method_path: bool = False,
+        origin_binding: bool = False,
+        ua_binding: bool = False,
+        replay_store: Optional[ReplayStore] = None,
+        token_gate: Optional[Callable[[str], bool]] = None
+    ):
+        self.audience = audience
+        self.issuer = issuer
+        self.ttl_seconds = ttl_seconds
+        self.clock_skew_seconds = clock_skew_seconds
+        self.bind_method_path = bind_method_path
+        self.origin_binding = origin_binding
+        self.ua_binding = ua_binding
+        self.replay_store = replay_store or InMemoryReplayStore()
+        self.token_gate = token_gate
+
+
+class OpenKit403Middleware(BaseHTTPMiddleware):
+    """FastAPI middleware for OpenKit403 authentication"""
+    
+    def __init__(
+        self,
+        app: ASGIApp,
+        audience: str,
+        issuer: str,
+        ttl_seconds: int = 60,
+        clock_skew_seconds: int = 120,
+        bind_method_path: bool = False,
+        origin_binding: bool = False,
+        ua_binding: bool = False,
+        replay_backend: str = "memory",
+        token_gate: Optional[Callable[[str], bool]] = None,
+        excluded_paths: Optional[list[str]] = None
+    ):
+        super().__init__(app)
+        
+        # Setup replay store
+        if replay_backend == "memory":
+            replay_store = InMemoryReplayStore()
+        else:
+            replay_store = None  # User must provide custom store
+        
+        self.config = OpenKit403Config(
+            audience=audience,
+            issuer=issuer,
+            ttl_seconds=ttl_seconds,
+            clock_skew_seconds=clock_skew_seconds,
+            bind_method_path=bind_method_path,
+            origin_binding=origin_binding,
+            ua_binding=ua_binding,
+            replay_store=replay_store,
+            token_gate=token_gate
+        )
+        
+        self.excluded_paths = excluded_paths or []
+    
+    async def dispatch(self, request: Request, call_next):
+        """Process request through OpenKit403 authentication"""
+        
+        # Skip excluded paths
+        if request.url.path in self.excluded_paths:
+            return await call_next(request)
+        
+        auth_header = request.headers.get('authorization')
+        
+        if not auth_header:
+            # No auth header - send challenge
+            header_value, _ = create_challenge(
+                method=request.method,
+                path=request.url.path,
+                audience=self.config.audience,
+                issuer=self.config.issuer,
+                ttl_seconds=self.config.ttl_seconds,
+                ua_binding=self.config.ua_binding,
+                origin_binding=self.config.origin_binding
+            )
+            
+            return JSONResponse(
+                status_code=status.HTTP_403_FORBIDDEN,
+                content={
+                    "error": "wallet_auth_required",
+                    "detail": "Sign the challenge using your Solana wallet and resend the request."
+                },
+                headers={"WWW-Authenticate": header_value}
+            )
+        
+        # Verify authorization
+        result = await verify_authorization(
+            auth_header=auth_header,
+            method=request.method,
+            path=request.url.path,
+            audience=self.config.audience,
+            issuer=self.config.issuer,
+            ttl_seconds=self.config.ttl_seconds,
+            clock_skew_seconds=self.config.clock_skew_seconds,
+            bind_method_path=self.config.bind_method_path,
+            origin_binding=self.config.origin_binding,
+            ua_binding=self.config.ua_binding,
+            replay_store=self.config.replay_store,
+            token_gate=self.config.token_gate,
+            headers=dict(request.headers)
+        )
+        
+        if not result.ok:
+            # Invalid auth - send new challenge
+            header_value, _ = create_challenge(
+                method=request.method,
+                path=request.url.path,
+                audience=self.config.audience,
+                issuer=self.config.issuer,
+                ttl_seconds=self.config.ttl_seconds,
+                ua_binding=self.config.ua_binding,
+                origin_binding=self.config.origin_binding
+            )
+            
+            return JSONResponse(
+                status_code=status.HTTP_403_FORBIDDEN,
+                content={
+                    "error": result.error,
+                    "detail": "Authentication failed. Please sign the new challenge."
+                },
+                headers={"WWW-Authenticate": header_value}
+            )
+        
+        # Success - attach user to request state
+        request.state.openkitx403_user = {
+            "address": result.address,
+            "challenge": result.challenge
+        }
+        
+        response = await call_next(request)
+        return response
+
+
+class OpenKit403User:
+    """User information from OpenKit403 authentication"""
+    
+    def __init__(self, address: str, challenge: Optional[Dict[str, Any]] = None):
+        self.address = address
+        self.challenge = challenge
+
+
+def require_openkitx403_user(request: Request) -> OpenKit403User:
+    """
+    Dependency to extract OpenKit403 user from request
+    
+    Usage:
+        @app.get("/protected")
+        async def protected(user: OpenKit403User = Depends(require_openkitx403_user)):
+            return {"address": user.address}
+    """
+    user_data = getattr(request.state, "openkitx403_user", None)
+    
+    if not user_data:
+        # This should not happen if middleware is properly configured
+        raise RuntimeError("OpenKit403 user not found in request state")
+    
+    return OpenKit403User(
+        address=user_data["address"],
+        challenge=user_data.get("challenge")
+    )
+
+
+__all__ = [
+    'OpenKit403Config',
+    'OpenKit403Middleware',
+    'OpenKit403User',
+    'require_openkitx403_user'
+]

openkitx403-0.1.1.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: openkitx403
+Version: 0.1.1
+Summary: Python server SDK for OpenKitx403 wallet authentication
+License: MIT
+Author: OpenKitx403 Contributors
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: base58 (>=2.1.1,<3.0.0)
+Requires-Dist: fastapi (>=0.104.0,<0.105.0)
+Requires-Dist: pydantic (>=2.5.0,<3.0.0)
+Requires-Dist: pynacl (>=1.5.0,<2.0.0)
+Project-URL: Documentation, https://openkitx403.github.io/openkitx403-docs
+Project-URL: Homepage, https://www.openkitx403.dev
+Project-URL: Repository, https://github.com/openkitx403/openkitx403
+Description-Content-Type: text/markdown
+
+# openkitx403 - Python Server SDK
+
+FastAPI middleware for OpenKitx403 wallet authentication.
+
+## Installation
+
+```bash
+pip install openkitx403
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI, Depends
+from openkitx403 import OpenKit403Middleware, require_openkitx403_user
+
+app = FastAPI()
+
+app.add_middleware(
+    OpenKit403Middleware,
+    audience="https://api.example.com",
+    issuer="my-api-v1",
+    ttl_seconds=60,
+    bind_method_path=True,
+    replay_backend="memory"
+)
+
+@app.get("/protected")
+async def protected(user = Depends(require_openkitx403_user)):
+    return {"wallet": user.address}
+```
+
+## Documentation
+
+See [USAGE_EXAMPLES.md](../../USAGE_EXAMPLES.md#5-python-server-fastapi) for complete examples.
+
+## License
+
+MIT
+

openkitx403-0.1.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+openkitx403/__init__.py,sha256=QQkXku6MSuD4b2PYqAsAc10PjE2FGjKOFvpLP1IMjRg,987
+openkitx403/core.py,sha256=pZURaZZyQ037YKTqR-RNUcW1jXV8qsA2hANUZEl55G8,11596
+openkitx403/middleware.py,sha256=RRzmnd5PdLYDouv6TtPDAZInLzMpfyDPcXELlu16CQo,6491
+openkitx403-0.1.1.dist-info/METADATA,sha256=g9BP22DlMga1Z-w_X8DDGXi1TwMyI66d3fe8Y_tHs_g,1643
+openkitx403-0.1.1.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+openkitx403-0.1.1.dist-info/RECORD,,

openkitx403-0.1.1.dist-info/WHEEL

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