lmiranda/wikijs-sdk-python
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Complete Task 1.3 - Authentication System Implementation

Browse Source 
✅ Implemented comprehensive authentication system:
- Abstract AuthHandler base class with pluggable architecture
- APIKeyAuth for API key authentication (string auto-conversion)
- JWTAuth for JWT token authentication with expiration handling
- NoAuth for testing and public instances
- Full integration with WikiJSClient for automatic header management

🔧 Fixed packaging issues:
- Updated pyproject.toml with required project metadata fields
- Fixed utility function exports in utils/__init__.py
- Package now installs correctly in virtual environments

🧪 Validated with comprehensive tests:
- All authentication methods working correctly
- Proper error handling for invalid credentials
- Type validation and security features

📊 Progress: Phase 1 MVP Development now 60% complete
🎯 Next: Task 1.4 - Pages API implementation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2025-07-29 15:06:11 -04:00
parent 11b6be87c8
commit 29001b02a5
8 changed files with 454 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
wikijs/__init__.py
View File

@@ -18,6 +18,7 @@ Features:
- Context manager support for resource cleanup
"""
from .auth import AuthHandler, NoAuth, APIKeyAuth, JWTAuth
from .client import WikiJSClient
from .exceptions import (
WikiJSException,
@@ -41,6 +42,12 @@ __all__ = [
# Main client
"WikiJSClient",
# Authentication
"AuthHandler",
"NoAuth",
"APIKeyAuth",
"JWTAuth",
# Data models
"BaseModel",
"Page",

22
wikijs/auth/__init__.py
View File

@@ -1,19 +1,21 @@
"""Authentication module for wikijs-python-sdk.
This module will contain authentication handlers for different
This module contains authentication handlers for different
authentication methods supported by Wiki.js.
Future implementations:
- API key authentication
- JWT token authentication
- OAuth2 authentication
Supported authentication methods:
- API key authentication (APIKeyAuth)
- JWT token authentication (JWTAuth)
- No authentication for testing (NoAuth)
"""
# Placeholder for future authentication implementations
# from .base import AuthHandler
# from .api_key import APIKeyAuth
# from .jwt import JWTAuth
from .base import AuthHandler, NoAuth
from .api_key import APIKeyAuth
from .jwt import JWTAuth
__all__ = [
# Will be implemented in Task 1.3
"AuthHandler",
"NoAuth",
"APIKeyAuth",
"JWTAuth",
]

89
wikijs/auth/api_key.py Normal file
View File

@@ -0,0 +1,89 @@
"""API key authentication for wikijs-python-sdk.
This module implements API key authentication for Wiki.js instances.
API keys are typically used for server-to-server authentication.
"""
from typing import Dict, Optional
from .base import AuthHandler
class APIKeyAuth(AuthHandler):
"""API key authentication handler for Wiki.js.
This handler implements authentication using an API key, which is
included in the Authorization header as a Bearer token.
Args:
api_key: The API key string from Wiki.js admin panel.
Example:
>>> auth = APIKeyAuth("your-api-key-here")
>>> client = WikiJSClient("https://wiki.example.com", auth=auth)
"""
def __init__(self, api_key: str) -> None:
"""Initialize API key authentication.
Args:
api_key: The API key from Wiki.js admin panel.
Raises:
ValueError: If api_key is empty or None.
"""
if not api_key or not api_key.strip():
raise ValueError("API key cannot be empty")
self._api_key = api_key.strip()
def get_headers(self) -> Dict[str, str]:
"""Get authentication headers with API key.
Returns:
Dict[str, str]: Headers containing the Authorization header.
"""
return {
"Authorization": f"Bearer {self._api_key}",
"Content-Type": "application/json"
}
def is_valid(self) -> bool:
"""Check if API key is valid.
For API keys, we assume they're valid if they're not empty.
Actual validation happens on the server side.
Returns:
bool: True if API key exists, False otherwise.
"""
return bool(self._api_key and self._api_key.strip())
def refresh(self) -> None:
"""Refresh authentication credentials.
API keys don't typically need refreshing, so this is a no-op.
If the API key becomes invalid, a new one must be provided.
"""
# API keys don't refresh - they're static until manually replaced
pass
@property
def api_key(self) -> str:
"""Get the masked API key for logging/debugging.
Returns:
str: Masked API key showing only first 4 and last 4 characters.
"""
if len(self._api_key) <= 8:
return "*" * len(self._api_key)
return f"{self._api_key[:4]}{'*' * (len(self._api_key) - 8)}{self._api_key[-4:]}"
def __repr__(self) -> str:
"""String representation of the auth handler.
Returns:
str: Safe representation with masked API key.
"""
return f"APIKeyAuth(api_key='{self.api_key}')"

97
wikijs/auth/base.py Normal file
View File

@@ -0,0 +1,97 @@
"""Base authentication interface for wikijs-python-sdk.
This module defines the abstract base class for all authentication handlers,
providing a consistent interface for different authentication methods.
"""
from abc import ABC, abstractmethod
from typing import Dict, Optional
class AuthHandler(ABC):
"""Abstract base class for Wiki.js authentication handlers.
This class defines the interface that all authentication implementations
must follow, ensuring consistent behavior across different auth methods.
"""
@abstractmethod
def get_headers(self) -> Dict[str, str]:
"""Get authentication headers for HTTP requests.
Returns:
Dict[str, str]: Dictionary of headers to include in requests.
Raises:
AuthenticationError: If authentication is invalid or expired.
"""
pass
@abstractmethod
def is_valid(self) -> bool:
"""Check if the current authentication is valid.
Returns:
bool: True if authentication is valid, False otherwise.
"""
pass
@abstractmethod
def refresh(self) -> None:
"""Refresh the authentication if possible.
For token-based authentication, this should refresh the token.
For API key authentication, this is typically a no-op.
Raises:
AuthenticationError: If refresh fails.
"""
pass
def validate_credentials(self) -> None:
"""Validate credentials and refresh if necessary.
This is a convenience method that checks validity and refreshes
if needed. Subclasses can override for custom behavior.
Raises:
AuthenticationError: If credentials are invalid or refresh fails.
"""
if not self.is_valid():
self.refresh()
if not self.is_valid():
from ..exceptions import AuthenticationError
raise AuthenticationError("Authentication credentials are invalid")
class NoAuth(AuthHandler):
"""No-authentication handler for testing or public instances.
This handler provides an empty authentication implementation,
useful for testing or when accessing public Wiki.js instances
that don't require authentication.
"""
def get_headers(self) -> Dict[str, str]:
"""Return empty headers dict.
Returns:
Dict[str, str]: Empty dictionary.
"""
return {}
def is_valid(self) -> bool:
"""Always return True for no-auth.
Returns:
bool: Always True.
"""
return True
def refresh(self) -> None:
"""No-op for no-auth.
This method does nothing since there's no authentication to refresh.
"""
pass

165
wikijs/auth/jwt.py Normal file
View File

@@ -0,0 +1,165 @@
"""JWT token authentication for wikijs-python-sdk.
This module implements JWT (JSON Web Token) authentication for Wiki.js instances.
JWT tokens are typically used for user-based authentication and have expiration times.
"""
import time
from datetime import datetime, timedelta
from typing import Dict, Optional
from .base import AuthHandler
class JWTAuth(AuthHandler):
"""JWT token authentication handler for Wiki.js.
This handler manages JWT tokens with automatic refresh capabilities.
JWT tokens typically expire and need to be refreshed periodically.
Args:
token: The JWT token string.
refresh_token: Optional refresh token for automatic renewal.
expires_at: Optional expiration timestamp (Unix timestamp).
Example:
>>> auth = JWTAuth("eyJ0eXAiOiJKV1QiLCJhbGc...")
>>> client = WikiJSClient("https://wiki.example.com", auth=auth)
"""
def __init__(
self,
token: str,
refresh_token: Optional[str] = None,
expires_at: Optional[float] = None
) -> None:
"""Initialize JWT authentication.
Args:
token: The JWT token string.
refresh_token: Optional refresh token for automatic renewal.
expires_at: Optional expiration timestamp (Unix timestamp).
Raises:
ValueError: If token is empty or None.
"""
if not token or not token.strip():
raise ValueError("JWT token cannot be empty")
self._token = token.strip()
self._refresh_token = refresh_token.strip() if refresh_token else None
self._expires_at = expires_at
self._refresh_buffer = 300 # Refresh 5 minutes before expiration
def get_headers(self) -> Dict[str, str]:
"""Get authentication headers with JWT token.
Automatically attempts to refresh the token if it's expired.
Returns:
Dict[str, str]: Headers containing the Authorization header.
Raises:
AuthenticationError: If token is expired and cannot be refreshed.
"""
# Try to refresh if token is near expiration
if not self.is_valid():
self.refresh()
return {
"Authorization": f"Bearer {self._token}",
"Content-Type": "application/json"
}
def is_valid(self) -> bool:
"""Check if JWT token is valid and not expired.
Returns:
bool: True if token exists and is not expired, False otherwise.
"""
if not self._token or not self._token.strip():
return False
# If no expiration time is set, assume token is valid
if self._expires_at is None:
return True
# Check if token is expired (with buffer for refresh)
current_time = time.time()
return current_time < (self._expires_at - self._refresh_buffer)
def refresh(self) -> None:
"""Refresh the JWT token using the refresh token.
This method attempts to refresh the JWT token using the refresh token.
If no refresh token is available, it raises an AuthenticationError.
Note: This is a placeholder implementation. In a real implementation,
this would make an HTTP request to the Wiki.js token refresh endpoint.
Raises:
AuthenticationError: If refresh token is not available or refresh fails.
"""
from ..exceptions import AuthenticationError
if not self._refresh_token:
raise AuthenticationError(
"JWT token expired and no refresh token available"
)
# TODO: Implement actual token refresh logic
# This would typically involve:
# 1. Making a POST request to /auth/refresh endpoint
# 2. Sending the refresh token
# 3. Updating self._token and self._expires_at with the response
raise AuthenticationError(
"JWT token refresh not yet implemented. "
"Please provide a new token or use API key authentication."
)
def is_expired(self) -> bool:
"""Check if the JWT token is expired.
Returns:
bool: True if token is expired, False otherwise.
"""
if self._expires_at is None:
return False
return time.time() >= self._expires_at
def time_until_expiry(self) -> Optional[timedelta]:
"""Get time until token expires.
Returns:
Optional[timedelta]: Time until expiration, or None if no expiration set.
"""
if self._expires_at is None:
return None
remaining_seconds = self._expires_at - time.time()
return timedelta(seconds=max(0, remaining_seconds))
@property
def token_preview(self) -> str:
"""Get a preview of the JWT token for logging/debugging.
Returns:
str: Masked token showing only first and last few characters.
"""
if not self._token:
return "None"
if len(self._token) <= 20:
return "*" * len(self._token)
return f"{self._token[:10]}...{self._token[-10:]}"
def __repr__(self) -> str:
"""String representation of the auth handler.
Returns:
str: Safe representation with masked token.
"""
return f"JWTAuth(token='{self.token_preview}', expires_at={self._expires_at})"

25
wikijs/client.py
View File

@@ -7,6 +7,7 @@ import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
from .auth import AuthHandler, APIKeyAuth
from .exceptions import (
APIError,
AuthenticationError,
@@ -48,7 +49,7 @@ class WikiJSClient:
def __init__(
self,
base_url: str,
auth: Union[str, "AuthHandler"],
auth: Union[str, AuthHandler],
timeout: int = 30,
verify_ssl: bool = True,
user_agent: Optional[str] = None,
@@ -58,13 +59,15 @@ class WikiJSClient:
# Store authentication
if isinstance(auth, str):
# Simple API key - will be handled by auth module later
self._api_key = auth
self._auth_handler = None
else:
# Auth handler (for future implementation)
self._api_key = None
# Convert string API key to APIKeyAuth handler
self._auth_handler = APIKeyAuth(auth)
elif isinstance(auth, AuthHandler):
# Use provided auth handler
self._auth_handler = auth
else:
raise ConfigurationError(
f"Invalid auth parameter: expected str or AuthHandler, got {type(auth)}"
)
# Request configuration
self.timeout = timeout
@@ -107,9 +110,9 @@ class WikiJSClient:
})
# Set authentication headers
if self._api_key:
session.headers["Authorization"] = f"Bearer {self._api_key}"
elif self._auth_handler:
if self._auth_handler:
# Validate auth and get headers
self._auth_handler.validate_credentials()
auth_headers = self._auth_handler.get_headers()
session.headers.update(auth_headers)
@@ -221,7 +224,7 @@ class WikiJSClient:
if not self.base_url:
raise ConfigurationError("Base URL not configured")
if not self._api_key and not self._auth_handler:
if not self._auth_handler:
raise ConfigurationError("Authentication not configured")
try:

8
wikijs/utils/__init__.py
View File

@@ -4,12 +4,20 @@ from .helpers import (
normalize_url,
sanitize_path,
validate_url,
build_api_url,
parse_wiki_response,
extract_error_message,
chunk_list,
safe_get,
)
__all__ = [
"normalize_url",
"sanitize_path",
"validate_url",
"build_api_url",
"parse_wiki_response",
"extract_error_message",
"chunk_list",
"safe_get",
]