auth-framework-py 1.0.0__tar.gz

auth_framework_py-1.0.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-08-26
+
+### Added
+- Initial release of Auth & Authorization Framework
+- Local authentication with PBKDF2 password hashing (100k iterations)
+- API key authentication provider
+- JWT token generation and verification (zero dependencies)
+- Opaque token support with server-side storage
+- Token refresh and revocation mechanisms
+- RBAC (Role-Based Access Control) engine
+- ABAC (Attribute-Based Access Control) with policy rules
+- Session management with device tracking
+- Multi-tenant support with tenant isolation
+- Wildcard pattern matching in policy rules
+- Context-aware policy decisions
+- Comprehensive test suite (40 tests, 100% passing)
+- Full documentation and examples
+
+### Security
+- PBKDF2-SHA256 password hashing with 100,000 iterations
+- HMAC-SHA256 token signatures
+- Timing-safe password comparison
+- Cryptographically secure random token generation
+- Server-side token revocation list
+
+## [Unreleased]
+
+### Planned
+- OAuth2/OIDC provider implementation
+- SAML provider implementation
+- Redis-backed session storage
+- Database-backed token storage
+- Rate limiting for authentication endpoints
+- Two-factor authentication (2FA) support
+- Passwordless authentication
+- Social login providers (Google, GitHub, etc.)
+
+[1.0.0]: https://github.com/parthivrawat/auth-framework/releases/tag/v1.0.0

auth_framework_py-1.0.0/LICENSE

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

auth_framework_py-1.0.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include pyproject.toml
+recursive-include auth_framework *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

auth_framework_py-1.0.0/PKG-INFO

@@ -0,0 +1,394 @@
+Metadata-Version: 2.4
+Name: auth-framework-py
+Version: 1.0.0
+Summary: A unified identity, session, token, and permission framework with pluggable providers
+Author-email: Parthiv Rawat <parthiv05022000@gmail.com>
+Maintainer-email: Parthiv Rawat <parthiv05022000@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/parthivrawat/auth-framework
+Project-URL: Documentation, https://github.com/parthivrawat/auth-framework/tree/main/python#readme
+Project-URL: Repository, https://github.com/parthivrawat/auth-framework
+Project-URL: Bug Tracker, https://github.com/parthivrawat/auth-framework/issues
+Project-URL: Changelog, https://github.com/parthivrawat/auth-framework/blob/main/python/CHANGELOG.md
+Keywords: auth,authentication,authorization,jwt,oauth2,rbac,abac,security,session,token,policy,permissions
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# Auth & Authorization Framework (Python)
+
+A unified identity, session, token, and permission framework with pluggable providers, strong defaults, and production-ready security.
+
+## Features
+
+- ✅ **Multiple Authentication Methods**
+  - Username/password with secure password hashing (PBKDF2)
+  - OAuth2/OIDC support (pluggable)
+  - SAML support (pluggable)
+  - API key authentication
+
+- ✅ **Token Management**
+  - JWT tokens (simple implementation, no external dependencies)
+  - Opaque tokens with server-side storage
+  - Refresh token support
+  - Token revocation
+
+- ✅ **Authorization**
+  - Role-Based Access Control (RBAC)
+  - Attribute-Based Access Control (ABAC)
+  - Policy engine with wildcard matching
+  - Multi-tenant permission scoping
+
+- ✅ **Session Management**
+  - Device and IP tracking
+  - Session expiry and renewal
+  - Multi-device support
+  - Session revocation
+
+- ✅ **Security**
+  - Secure password hashing (PBKDF2 with salt)
+  - Token signature verification
+  - Audit logging support
+  - Zero dependencies for core functionality
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install auth-framework-py
+```
+
+### From Source
+
+```bash
+git clone https://github.com/parthivrawat/auth-framework
+cd auth-framework/python
+pip install -e .
+```
+
+### Development Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Basic Authentication
+
+```python
+from auth_framework import Auth, LocalAuthProvider
+
+# Initialize auth framework
+auth = Auth()
+
+# Add local authentication provider
+provider = LocalAuthProvider()
+auth.add_provider("local", provider)
+
+# Register a user
+user = provider.register_user(
+    username="alice",
+    password="secure_password",
+    email="alice@example.com",
+    roles={"admin", "user"}
+)
+
+# Login
+result = auth.login("local", {
+    "username": "alice",
+    "password": "secure_password"
+})
+
+print(f"Access Token: {result['access_token']}")
+print(f"Refresh Token: {result['refresh_token']}")
+print(f"Session ID: {result['session_id']}")
+```
+
+### Token Verification
+
+```python
+# Verify an access token
+token = auth.verify_token(result['access_token'])
+
+if token and not token.is_expired():
+    print(f"Token is valid for user: {token.user_id}")
+else:
+    print("Token is invalid or expired")
+```
+
+### Permission Checking (RBAC)
+
+```python
+from auth_framework import User
+
+# Create a user with roles
+user = User(
+    id="user123",
+    username="alice",
+    roles={"admin"}
+)
+
+# Add role permissions
+auth.policy_engine.add_role_permission("admin", "read:*")
+auth.policy_engine.add_role_permission("admin", "write:*")
+
+# Check permissions
+if auth.check_permission(user, "read", "document:123"):
+    print("User can read the document")
+
+if auth.check_permission(user, "write", "document:123"):
+    print("User can write the document")
+```
+
+### Policy Rules (ABAC)
+
+```python
+from auth_framework import PolicyRule
+
+# Add a custom policy rule
+auth.policy_engine.add_rule(PolicyRule(
+    subject="user:alice",
+    action="delete",
+    resource="document:*",
+    effect="allow",
+    conditions={"tenant": "tenant1"}
+))
+
+# Check with context
+context = {"tenant": "tenant1"}
+if auth.check_permission(user, "delete", "document:123", context):
+    print("User can delete the document in tenant1")
+```
+
+### API Key Authentication
+
+```python
+from auth_framework import APIKeyAuthProvider
+
+# Add API key provider
+api_provider = APIKeyAuthProvider()
+auth.add_provider("api_key", api_provider)
+
+# Create an API key for a user
+api_key = api_provider.create_api_key(user)
+print(f"API Key: {api_key}")
+
+# Authenticate with API key
+authenticated_user = auth.authenticate("api_key", {"api_key": api_key})
+if authenticated_user:
+    print(f"Authenticated as: {authenticated_user.username}")
+```
+
+### Session Management
+
+```python
+# Create a session
+session = auth.session_manager.create_session(
+    user_id=user.id,
+    device_id="device123",
+    ip_address="192.168.1.1",
+    user_agent="Mozilla/5.0",
+    ttl=3600  # 1 hour
+)
+
+# Get session
+active_session = auth.session_manager.get_session(session.id)
+if active_session and not active_session.is_expired():
+    print(f"Session is active for user: {active_session.user_id}")
+
+# Revoke session
+auth.session_manager.revoke_session(session.id)
+
+# Revoke all sessions for a user
+auth.session_manager.revoke_user_sessions(user.id)
+```
+
+### Token Refresh
+
+```python
+# Refresh an access token using refresh token
+new_tokens = auth.refresh_token(result['refresh_token'])
+
+if new_tokens:
+    print(f"New Access Token: {new_tokens['access_token']}")
+```
+
+### Opaque Tokens
+
+```python
+from auth_framework import TokenType
+
+# Use opaque tokens instead of JWT
+auth = Auth(token_type=TokenType.OPAQUE)
+
+# Rest of the code remains the same
+# Opaque tokens are stored server-side and can be easily revoked
+```
+
+## Advanced Usage
+
+### Custom Password Hasher
+
+```python
+from auth_framework import PasswordHasher
+
+class CustomHasher(PasswordHasher):
+    def hash(self, password: str) -> str:
+        # Your custom hashing logic
+        pass
+    
+    def verify(self, password: str, hashed: str) -> bool:
+        # Your custom verification logic
+        pass
+
+# Use custom hasher
+provider = LocalAuthProvider(password_hasher=CustomHasher())
+```
+
+### Custom Authentication Provider
+
+```python
+from auth_framework import AuthProvider, User
+
+class LDAPAuthProvider(AuthProvider):
+    def authenticate(self, credentials: dict) -> Optional[User]:
+        # Your LDAP authentication logic
+        username = credentials.get('username')
+        password = credentials.get('password')
+        
+        # Authenticate against LDAP
+        # ...
+        
+        return User(
+            id=ldap_user_id,
+            username=username,
+            roles=ldap_roles,
+            permissions=ldap_permissions
+        )
+
+# Add custom provider
+auth.add_provider("ldap", LDAPAuthProvider())
+```
+
+### Multi-Tenant Support
+
+```python
+# Register users with tenant IDs
+user1 = provider.register_user(
+    username="alice",
+    password="password",
+    tenant_id="tenant1"
+)
+
+user2 = provider.register_user(
+    username="bob",
+    password="password",
+    tenant_id="tenant2"
+)
+
+# Add tenant-scoped policy rules
+auth.policy_engine.add_rule(PolicyRule(
+    subject="user:alice",
+    action="read",
+    resource="document:*",
+    effect="allow",
+    conditions={"tenant": "tenant1"}
+))
+
+# Check with tenant context
+context = {"tenant": "tenant1"}
+can_read = auth.check_permission(user1, "read", "document:123", context)
+```
+
+## API Reference
+
+### Core Classes
+
+- **Auth**: Main authentication and authorization framework
+- **User**: Represents an authenticated user
+- **Token**: Represents an authentication token
+- **Session**: Represents a user session
+- **PolicyRule**: Represents a policy rule for RBAC/ABAC
+
+### Providers
+
+- **LocalAuthProvider**: Username/password authentication
+- **APIKeyAuthProvider**: API key authentication
+- **AuthProvider**: Abstract base class for custom providers
+
+### Token Generators
+
+- **SimpleJWTGenerator**: JWT token generation (no external dependencies)
+- **OpaqueTokenGenerator**: Opaque token generation with server-side storage
+
+### Utilities
+
+- **PolicyEngine**: RBAC/ABAC policy engine
+- **SessionManager**: Session management
+- **PBKDF2Hasher**: Secure password hashing
+
+## Testing
+
+Run the test suite:
+
+```bash
+pytest test_auth_framework.py -v
+```
+
+With coverage:
+
+```bash
+pytest test_auth_framework.py -v --cov=auth_framework --cov-report=term-missing
+```
+
+## Security Considerations
+
+1. **Password Storage**: Passwords are hashed using PBKDF2 with 100,000 iterations and a random salt
+2. **Token Secrets**: Use a strong, random secret for JWT signing
+3. **Token Expiry**: Set appropriate TTLs for access and refresh tokens
+4. **Session Security**: Track device IDs and IP addresses for session validation
+5. **HTTPS**: Always use HTTPS in production to protect tokens in transit
+6. **Token Revocation**: Implement token revocation for logout and security events
+
+## Performance
+
+- **Zero Dependencies**: Core functionality has no external dependencies
+- **Efficient Token Verification**: JWT tokens are verified without database lookups
+- **Session Cleanup**: Regularly cleanup expired sessions with `session_manager.cleanup_expired()`
+- **Policy Caching**: Consider caching policy decisions for frequently accessed resources
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
+
+For issues and questions, please open an issue on GitHub.