{"id":48794046,"url":"https://github.com/amirhosein2004/secure-token","last_synced_at":"2026-04-13T21:33:26.196Z","repository":{"id":313671470,"uuid":"1051831946","full_name":"amirhosein2004/secure-token","owner":"amirhosein2004","description":"package secure-token","archived":false,"fork":false,"pushed_at":"2025-11-10T08:27:54.000Z","size":122,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-25T05:00:07.854Z","etag":null,"topics":["cryptography","pypi-packages","python","secure-token"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/secure-token/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amirhosein2004.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-06T20:11:47.000Z","updated_at":"2025-11-10T08:27:58.000Z","dependencies_parsed_at":"2025-11-05T22:07:08.657Z","dependency_job_id":null,"html_url":"https://github.com/amirhosein2004/secure-token","commit_stats":null,"previous_names":["amirhosein2004/secure-token"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/amirhosein2004/secure-token","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amirhosein2004%2Fsecure-token","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amirhosein2004%2Fsecure-token/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amirhosein2004%2Fsecure-token/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amirhosein2004%2Fsecure-token/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amirhosein2004","download_url":"https://codeload.github.com/amirhosein2004/secure-token/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amirhosein2004%2Fsecure-token/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31771883,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T20:17:16.280Z","status":"ssl_error","status_checked_at":"2026-04-13T20:17:08.216Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptography","pypi-packages","python","secure-token"],"created_at":"2026-04-13T21:33:17.232Z","updated_at":"2026-04-13T21:33:26.120Z","avatar_url":"https://github.com/amirhosein2004.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔐 Secure Token\n\n[![PyPI version](https://badge.fury.io/py/secure-token.svg)](https://badge.fury.io/py/secure-token)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Downloads](https://static.pepy.tech/badge/secure-token)](https://pepy.tech/project/secure-token)\n[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](https://github.com/amirhosein2004/secure-token)\n\nA simple and secure token management library for Python applications. Generate, validate, and manage encrypted tokens with ease.\n\nPerfect for **authentication**, **API security**, **session management**, and **microservices**.\n\n## ✨ Features\n\n- **🛡️ Secure**: Fernet encryption with PBKDF2 key derivation\n- **⚡ Fast**: Stateless design, no database required\n- **🎯 Simple**: Easy-to-use API with clear examples\n- **🔧 Flexible**: Custom permissions and expiration times\n- **📦 Lightweight**: Minimal dependencies\n\n## 📋 Contents\n\n- [Installation](#-installation)\n- [Quick Start](#-quick-start)\n- [Methods Guide](#-methods-guide)\n- [Configuration](#-configuration)\n- [Error Handling](#-error-handling)\n- [Utility Functions](#-utility-functions)\n- [Validators](#-validators)\n- [Complete Example](#-complete-example)\n\n## 🚀 Installation\n\n```bash\npip install secure-token\n```\n\n## 💡 Quick Start\n\nA simple example to get you started:\n\n```python\nfrom secure_token import SecureTokenManager\n\n# 1. Create token manager\nmanager = SecureTokenManager()\n\n# 2. Generate a token (simplest way)\ntoken = manager.generate_token(user_id=\"user_123\")\n\n# 3. Validate the token\nresult = manager.validate_token(token)\nprint(f\"User: {result['user_id']}\")  # User: user_123\n```\n\n### Example with Permissions\n\n```python\n# Token with different permissions\ntoken = manager.generate_token(\n    user_id=\"john_doe\",\n    permissions=[\"read\", \"write\"],\n    expires_in_hours=24\n)\n\n# Check specific permission\ntry:\n    manager.check_permission(token, \"write\")\n    print(\"Access granted!\")\nexcept PermissionDeniedError:\n    print(\"Access denied!\")\n```\n\n## 📚 Methods Guide\n\n### 1️⃣ **generate_token** - Create Token\n\nGenerates a secure encrypted token.\n\n**Parameters:**\n- `user_id` (required): User identifier\n- `permissions` (optional): List of permissions\n- `expires_in_hours` (optional): Expiration time in hours\n- `additional_data` (optional): Additional data to store\n\n**Simple Examples:**\n```python\nfrom secure_token import SecureTokenManager\n\nmanager = SecureTokenManager()\n\n# Example 1: Simplest form\ntoken = manager.generate_token(user_id=\"user_123\")\n\n# Example 2: With permissions\ntoken = manager.generate_token(\n    user_id=\"admin_456\",\n    permissions=[\"read\", \"write\", \"delete\"]\n)\n\n# Example 3: Complete with all options\ntoken = manager.generate_token(\n    user_id=\"user_789\",\n    permissions=[\"admin\"],\n    expires_in_hours=48,  # 2 days\n    additional_data={\n        \"role\": \"administrator\",\n        \"department\": \"IT\"\n    }\n)\n```\n\n---\n\n### 2️⃣ **validate_token** - Validate Token\n\nValidates a token and returns its information.\n\n**Returns:**\n- `valid`: Token validity status\n- `user_id`: User identifier\n- `permissions`: List of permissions\n- `expires_at`: Expiration datetime\n- `time_remaining`: Time remaining until expiration\n\n**Simple Examples:**\n```python\n# Example 1: Simple validation\nresult = manager.validate_token(token)\nif result['valid']:\n    print(f\"User: {result['user_id']}\")\n\n# Example 2: Get complete information\nresult = manager.validate_token(token)\nuser_id = result['user_id']\npermissions = result['permissions']\ntime_left = result['time_remaining']\nprint(f\"User {user_id} - Time left: {time_left}\")\n\n# Example 3: Error handling\nfrom secure_token import TokenExpiredError, InvalidTokenError\n\ntry:\n    result = manager.validate_token(token)\n    print(\"Token is valid!\")\nexcept TokenExpiredError:\n    print(\"Token has expired!\")\nexcept InvalidTokenError:\n    print(\"Token is invalid!\")\n```\n\n---\n\n### 3️⃣ **check_permission** - Check Permission\n\nChecks if a user has a specific permission.\n\n**Parameters:**\n- `token`: User's token\n- `required_permission`: Required permission to check\n\n**Simple Examples:**\n```python\nfrom secure_token import PermissionDeniedError\n\n# Example 1: Simple check\ntry:\n    manager.check_permission(token, \"admin\")\n    print(\"User is admin!\")\nexcept PermissionDeniedError:\n    print(\"User is not admin!\")\n\n# Example 2: Check multiple permissions\npermissions_to_check = [\"read\", \"write\", \"delete\"]\n\nfor perm in permissions_to_check:\n    try:\n        manager.check_permission(token, perm)\n        print(f\"✓ Has {perm} access\")\n    except PermissionDeniedError:\n        print(f\"✗ No {perm} access\")\n\n# Example 3: Use in a function\ndef has_admin_access(token):\n    try:\n        return manager.check_permission(token, \"admin\")\n    except:\n        return False\n\nif has_admin_access(token):\n    print(\"Welcome to admin panel!\")\n```\n\n---\n\n### 4️⃣ **refresh_token** - Refresh Token\n\nCreates a new token with the same information.\n\n**Parameters:**\n- `token`: Current token\n- `new_expires_in_hours` (optional): New expiration time\n\n**Simple Examples:**\n```python\n# Example 1: Simple refresh (24 hours default)\nnew_token = manager.refresh_token(old_token)\n\n# Example 2: Refresh with custom time\nnew_token = manager.refresh_token(old_token, new_expires_in_hours=72)\n\n# Example 3: Auto-refresh\ndef auto_refresh_if_needed(token):\n    \"\"\"Refresh if less than 2 hours remaining\"\"\"\n    try:\n        info = manager.get_token_info(token)\n        remaining = info['time_remaining']\n        \n        # If less than 2 hours remaining\n        if \"1:\" in remaining or \"0:\" in remaining:\n            return manager.refresh_token(token)\n        return token\n    except:\n        return None\n\nrefreshed = auto_refresh_if_needed(my_token)\n```\n\n---\n\n### 5️⃣ **get_token_info** - Get Token Information\n\nReturns complete token information.\n\n**Returns:**\n- `token_id`: Unique identifier\n- `user_id`: User identifier\n- `permissions`: List of permissions\n- `time_remaining`: Time remaining until expiration\n- And more...\n\n**Simple Examples:**\n```python\n# Example 1: Get simple information\ninfo = manager.get_token_info(token)\nprint(f\"User: {info['user_id']}\")\nprint(f\"Time left: {info['time_remaining']}\")\n\n# Example 2: Display complete information\ninfo = manager.get_token_info(token)\nprint(f\"\"\"\n📋 Token Information:\n- User: {info['user_id']}\n- Permissions: {info['permissions']}\n- Issued at: {info['issued_at']}\n- Expires at: {info['expires_at']}\n- Time remaining: {info['time_remaining']}\n\"\"\")\n\n# Example 3: Check token status\ninfo = manager.get_token_info(token)\nif info['valid']:\n    print(\"✓ Token is active\")\n    print(f\"⏱ {info['time_remaining']} remaining\")\nelse:\n    print(\"✗ Token is inactive\")\n```\n\n---\n\n### 6️⃣ **export_config** - Export Configuration\n\nReturns encryption configuration (for backup purposes).\n\n**Simple Examples:**\n```python\n# Get configuration\nconfig = manager.export_config()\nprint(f\"Algorithm: {config['algorithm']}\")\nprint(f\"Version: {config['version']}\")\n\n# Save for backup\nimport json\n\nconfig = manager.export_config()\nwith open('backup_config.json', 'w') as f:\n    json.dump(config, f)\n```\n\n## 🔧 Configuration\n\n### Configuration Methods\n\n**1️⃣ Simple Method (Default):**\n```python\nfrom secure_token import SecureTokenManager\n\n# Automatic settings\nmanager = SecureTokenManager()\n```\n\n**2️⃣ With Environment Variables:**\n```python\nimport os\nfrom secure_token import SecureTokenManager\n\n# Set variables\nos.environ['SECRET_KEY'] = 'MySecretKey@123'\nos.environ['DEFAULT_EXPIRATION_HOURS'] = '12'\n\nmanager = SecureTokenManager()\n```\n\n**3️⃣ With .env File:**\n```bash\n# Create .env file:\nSECRET_KEY=MySecretKey@123\nDEFAULT_EXPIRATION_HOURS=12\n```\n\n```python\nfrom dotenv import load_dotenv\nfrom secure_token import SecureTokenManager\n\nload_dotenv()\nmanager = SecureTokenManager()\n```\n\n**4️⃣ With Custom Settings:**\n```python\nfrom secure_token import SecureTokenManager, Settings\n\nsettings = Settings(\n    SECRET_KEY=\"MyCustomKey@456!\",\n    DEFAULT_EXPIRATION_HOURS=48\n)\n\nmanager = SecureTokenManager(settings_instance=settings)\n```\n\n\u003e **🔒 Security Note:** `Settings` automatically validates all parameters during initialization. \n\u003e If you provide invalid SECRET_KEY, SALT, or expiration time, it will raise an error immediately.\n\n### Settings Validation Requirements\n\n**SECRET_KEY Requirements:**\n- Minimum 16 characters\n- Contains uppercase and lowercase letters\n- At least one number\n- At least one special character (@$!%*?\u0026#)\n\n**Valid SECRET_KEY Examples:**\n```python\n# ✓ Valid\n\"MyPassword@123\"\n\"SecureApp#2025\"\n\"StrongKey!Abc123\"\n\n# ✗ Invalid - Will raise TokenError\n\"weak\"           # Too short\n\"nocapitals123\"  # No uppercase letters\n\"NoNumbers!\"     # No numbers\n\"NoSpecial123\"   # No special characters\n```\n\n**Example with Error Handling:**\n```python\nfrom secure_token import Settings, SecureTokenManager, TokenError\n\ntry:\n    settings = Settings(\n        SECRET_KEY=\"weak\",  # Too weak!\n        DEFAULT_EXPIRATION_HOURS=24\n    )\nexcept TokenError as e:\n    print(f\"Settings validation error: {e}\")\n\n# Valid settings\nsettings = Settings(\n    SECRET_KEY=\"MyStrongPassword@123\",\n    DEFAULT_EXPIRATION_HOURS=24\n)\nmanager = SecureTokenManager(settings_instance=settings)\n```\n\n\n## ⚠️ Error Handling\n\nThe library provides 4 different error types:\n\n**Error Types:**\n- `TokenError` - Base exception\n- `TokenExpiredError` - Token has expired\n- `InvalidTokenError` - Token is invalid\n- `PermissionDeniedError` - Permission denied\n\n**Simple Examples:**\n```python\nfrom secure_token import (\n    SecureTokenManager,\n    TokenExpiredError,\n    InvalidTokenError,\n    PermissionDeniedError\n)\n\nmanager = SecureTokenManager()\n\n# Example 1: Simple handling\ntry:\n    result = manager.validate_token(token)\n    print(\"Token is valid!\")\nexcept TokenExpiredError:\n    print(\"⏱ Token expired - please login again\")\nexcept InvalidTokenError:\n    print(\"❌ Token is invalid\")\nexcept Exception as e:\n    print(f\"Error: {e}\")\n\n# Example 2: Check permission\ntry:\n    manager.check_permission(token, \"admin\")\n    print(\"✓ Has admin access\")\nexcept PermissionDeniedError:\n    print(\"✗ No admin access\")\nexcept TokenExpiredError:\n    print(\"⏱ Token expired\")\n\n# Example 3: Safe validation function\ndef safe_validate(token):\n    \"\"\"Safe validation\"\"\"\n    try:\n        return manager.validate_token(token)\n    except TokenExpiredError:\n        return {\"valid\": False, \"error\": \"expired\"}\n    except InvalidTokenError:\n        return {\"valid\": False, \"error\": \"invalid\"}\n    except Exception:\n        return {\"valid\": False, \"error\": \"unknown\"}\n```\n\n---\n\n## 🎨 Complete Example\n\nA simple authentication system:\n\n```python\nfrom secure_token import SecureTokenManager\n\nclass AuthSystem:\n    \"\"\"Simple authentication system\"\"\"\n    \n    def __init__(self):\n        self.manager = SecureTokenManager()\n    \n    def login(self, username, permissions=None):\n        \"\"\"Login user and create token\"\"\"\n        token = self.manager.generate_token(\n            user_id=username,\n            permissions=permissions or [\"read\"],\n            expires_in_hours=24\n        )\n        print(f\"✓ {username} logged in\")\n        return token\n    \n    def check_access(self, token, permission):\n        \"\"\"Check access permission\"\"\"\n        try:\n            self.manager.check_permission(token, permission)\n            return True\n        except:\n            return False\n    \n    def get_user(self, token):\n        \"\"\"Get user information\"\"\"\n        try:\n            result = self.manager.validate_token(token)\n            return result['user_id']\n        except:\n            return None\n\n# Usage\nauth = AuthSystem()\n\n# Login regular user\nuser_token = auth.login(\"john\", [\"read\", \"write\"])\n\n# Login admin\nadmin_token = auth.login(\"admin\", [\"read\", \"write\", \"admin\"])\n\n# Check access\nif auth.check_access(user_token, \"write\"):\n    print(\"✓ User can write\")\n\nif auth.check_access(user_token, \"admin\"):\n    print(\"✓ User is admin\")\nelse:\n    print(\"✗ User is not admin\")\n\n# Get username\nusername = auth.get_user(user_token)\nprint(f\"Username: {username}\")\n```\n\n## 🔧 Utility Functions\n\n### **generate_secret_key** - Generate Secret Key\n\nGenerates a secure random secret key.\n\n**Examples:**\n```python\nfrom secure_token import generate_secret_key\n\n# Generate 32-character key\nkey = generate_secret_key(32)\nprint(key)  # Example: \"kJ8mN3qR7sT2vW9yB4xD6zA1cF5gH0iL\"\n\n# Generate 16-character key\nshort_key = generate_secret_key(16)\n\n# Use in settings\nfrom secure_token import Settings, SecureTokenManager\n\nsettings = Settings(\n    SECRET_KEY=generate_secret_key(32),\n    DEFAULT_EXPIRATION_HOURS=24\n)\nmanager = SecureTokenManager(settings_instance=settings)\n```\n\n---\n\n### **generate_salt** - Generate Salt\n\nGenerates random salt for enhanced security.\n\n**Examples:**\n```python\nfrom secure_token import generate_salt\n\n# Generate 32-byte salt\nsalt = generate_salt(32)\nprint(len(salt))  # 32\n\n# Generate 16-byte salt\nsmall_salt = generate_salt(16)\n\n# Use in settings\nfrom secure_token import Settings, SecureTokenManager\n\nsettings = Settings(\n    SECRET_KEY=\"MySecretKey@123\",\n    SALT=generate_salt(32),\n    DEFAULT_EXPIRATION_HOURS=24\n)\nmanager = SecureTokenManager(settings_instance=settings)\n```\n\n---\n\n## ✅ Validators\n\n### **validate_permissions** - Validate Permissions\n\nValidates a list of permissions.\n\n**Examples:**\n```python\nfrom secure_token import validate_permissions\n\n# Example 1: Valid list\ntry:\n    validate_permissions([\"read\", \"write\", \"admin\"])\n    print(\"✓ Permissions are valid\")\nexcept Exception as e:\n    print(f\"✗ Error: {e}\")\n\n# Example 2: Invalid list\ntry:\n    validate_permissions([\"x\"])  # Too short!\nexcept Exception as e:\n    print(f\"Error: {e}\")  # Length must be between 2 and 30\n\n# Example 3: Use in a function\ndef add_permission(permissions, new_perm):\n    \"\"\"Add new permission\"\"\"\n    test_list = permissions + [new_perm]\n    try:\n        validate_permissions(test_list)\n        return test_list\n    except:\n        return permissions  # Return previous list\n```\n\n---\n\n### **validate_expires_hours** - Validate Expiration Time\n\nValidates expiration time (must be between 0 and 8760 hours).\n\n**Examples:**\n```python\nfrom secure_token import validate_expires_hours\n\n# Example 1: Valid times\ntry:\n    validate_expires_hours(24)  # ✓ 24 hours\n    validate_expires_hours(168)  # ✓ 1 week\n    validate_expires_hours(720)  # ✓ 1 month\n    print(\"✓ Times are valid\")\nexcept Exception as e:\n    print(f\"✗ Error: {e}\")\n\n# Example 2: Invalid time\ntry:\n    validate_expires_hours(10000)  # Too much!\nexcept Exception as e:\n    print(f\"Error: {e}\")  # Must be less than 8760\n\n# Example 3: Use in a function\ndef safe_expiration(hours):\n    \"\"\"Safe expiration setting\"\"\"\n    try:\n        validate_expires_hours(hours)\n        return hours\n    except:\n        return 24  # Default 24 hours\n```\n\n---\n\n## 📚 Documentation\n\n### 📖 Complete Documentation\n\nFor more information:\n\n- **📋 [API Reference](docs/api-reference.md)** - Complete API reference\n- **🎓 [Tutorial Guide](docs/tutorial-guide.md)** - Step-by-step guide\n- **🔧 [Advanced Examples](docs/advanced-examples.md)** - Advanced examples with Flask and Django\n- **⚙️ [Development Setup](docs/development-setup.md)** - Development environment setup\n- **🧪 [Testing Guide](docs/testing-guide.md)** - Testing guide\n\n### 🌐 Online Documentation\n\n\u003e **[📖 Full Online Documentation](https://secure-token.readthedocs.io/en/)**\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions!\n\nPlease see our [Contributing Guide](CONTRIBUTING.md) for more information.\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n## 🔗 Links\n\n- **📦 PyPI**: [pypi.org/project/secure-token](https://pypi.org/project/secure-token/)\n- **💻 GitHub**: [github.com/amirhosein2004/secure-token](https://github.com/amirhosein2004/secure-token)\n- **📖 Docs**: [secure-token.readthedocs.io](https://secure-token.readthedocs.io/en/)\n- **🐛 Issues**: [Report Bug](https://github.com/amirhosein2004/secure-token/issues)\n- 💬 Join the discussion here: [GitHub Discussions](https://github.com/amirhosein2004/secure-token/discussions)\n\n---\n\n## 👨‍💻 Author\n\n**Made with ❤️ by [AmirHossein Babaee](https://github.com/amirhosein2004)**\n\n*Secure Token - Because your application's security matters*\n\n---\n\n## 📊 Methods Summary\n\n| Method | Purpose | Example |\n|--------|---------|---------|\n| `generate_token` | Create token | `manager.generate_token(\"user_123\")` |\n| `validate_token` | Validate token | `manager.validate_token(token)` |\n| `check_permission` | Check permission | `manager.check_permission(token, \"admin\")` |\n| `refresh_token` | Refresh token | `manager.refresh_token(token)` |\n| `get_token_info` | Get token info | `manager.get_token_info(token)` |\n| `export_config` | Export config | `manager.export_config()` |\n| `generate_secret_key` | Generate key | `generate_secret_key(32)` |\n| `generate_salt` | Generate salt | `generate_salt(32)` |\n\n---\n\n**⭐ If you find this project useful, don't forget to give it a star!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famirhosein2004%2Fsecure-token","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famirhosein2004%2Fsecure-token","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famirhosein2004%2Fsecure-token/lists"}