{"id":29626408,"url":"https://github.com/nekzus/tokenly","last_synced_at":"2026-03-05T23:34:23.454Z","repository":{"id":273158151,"uuid":"918811143","full_name":"Nekzus/tokenly","owner":"Nekzus","description":"Secure JWT token manager","archived":false,"fork":false,"pushed_at":"2025-05-08T18:32:35.000Z","size":2695,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-23T19:42:41.467Z","etag":null,"topics":["access-token","authentication","cookie","httponly","jwt","oauth","refresh-token","security","token","tyepscript"],"latest_commit_sha":null,"homepage":"https://nekzus.github.io/tokenly/","language":"TypeScript","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/Nekzus.png","metadata":{"files":{"readme":".github/README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","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},"funding":{"ko_fi":"nekzus"}},"created_at":"2025-01-18T23:02:16.000Z","updated_at":"2025-05-08T18:30:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"a8bb423e-fc91-46bd-b22c-d7e154cc6cef","html_url":"https://github.com/Nekzus/tokenly","commit_stats":null,"previous_names":["nekzus/tokenly"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/Nekzus/tokenly","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nekzus%2Ftokenly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nekzus%2Ftokenly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nekzus%2Ftokenly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nekzus%2Ftokenly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nekzus","download_url":"https://codeload.github.com/Nekzus/tokenly/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nekzus%2Ftokenly/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30155369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T22:39:40.138Z","status":"ssl_error","status_checked_at":"2026-03-05T22:39:24.771Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["access-token","authentication","cookie","httponly","jwt","oauth","refresh-token","security","token","tyepscript"],"created_at":"2025-07-21T07:06:04.595Z","updated_at":"2026-03-05T23:34:23.423Z","avatar_url":"https://github.com/Nekzus.png","language":"TypeScript","funding_links":["https://ko-fi.com/nekzus","https://paypal.me/maseortega"],"categories":[],"sub_categories":[],"readme":"# Tokenly 🔐\n\n[![Github Workflow](https://github.com/nekzus/tokenly/actions/workflows/publish.yml/badge.svg?event=push)](https://github.com/Nekzus/tokenly/actions/workflows/publish.yml)\n[![npm-version](https://img.shields.io/npm/v/@nekzus/tokenly.svg)](https://www.npmjs.com/package/@nekzus/tokenly)\n[![npm-month](https://img.shields.io/npm/dm/@nekzus/tokenly.svg)](https://www.npmjs.com/package/@nekzus/tokenly)\n[![npm-total](https://img.shields.io/npm/dt/@nekzus/tokenly.svg?style=flat)](https://www.npmjs.com/package/@nekzus/tokenly)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Nekzus/tokenly)\n[![Donate](https://img.shields.io/badge/donate-paypal-blue.svg?style=flat-square)](https://paypal.me/maseortega)\n\n\u003cdiv align=\"center\"\u003e\n\n**Advanced JWT Token Management with Device Fingerprinting**\n\n_Enterprise-grade security by default for modern applications_\n\n\u003c/div\u003e\n\n## Contents\n\n- [Features](#-features)\n- [Installation](#-installation)\n- [Quick Start](#-quick-start)\n- [Configuration](#-configuration)\n- [Security Features](#%EF%B8%8F-security-features)\n- [API Reference](#-api-reference)\n- [Environment Variables](#-environment-variables--secrets)\n- [Best Practices](#-best-practices)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## ✨ Features\n\n- **Zero Configuration Required**: Works out of the box with secure defaults\n- **Device Fingerprinting**: Unique identification of devices to prevent token\n  theft\n- **Framework Agnostic**: Use with Express, Fastify, Koa, or any Node.js\n  framework\n- **TypeScript First**: Full type safety and excellent IDE support\n- **Production Ready**: Built for enterprise applications\n\n## 📦 Installation\n\n```bash\nnpm install @nekzus/tokenly\n```\n\n### Required Dependencies\n\n```bash\nnpm install cookie-parser\n```\n\n\u003e ⚠️ **Important**: `cookie-parser` is required for secure handling of refresh\n\u003e tokens with HttpOnly cookies.\n\n## 🚀 Quick Start\n\n```typescript\nimport { getClientIP, Tokenly } from \"@nekzus/tokenly\";\nimport cookieParser from \"cookie-parser\";\nimport dotenv from \"dotenv\";\n\n// Load environment variables\ndotenv.config();\n\n// Initialize Express\nconst app = express();\n\n// Required middleware for refresh tokens\napp.use(cookieParser());\n\n// Initialize Tokenly\nconst auth = new Tokenly({\n    accessTokenExpiry: \"15m\",\n    refreshTokenExpiry: \"7d\",\n    securityConfig: {\n        enableFingerprint: true,\n        maxDevices: 5,\n    },\n});\n\n// Generate token with fingerprinting\napp.post(\"/login\", (req, res) =\u003e {\n    const token = auth.generateAccessToken(\n        { userId: \"123\", role: \"user\" },\n        undefined,\n        {\n            userAgent: req.headers[\"user-agent\"] || \"\",\n            ip: getClientIP(req.headers),\n        },\n    );\n    res.json({ token });\n});\n```\n\n## 🔧 Configuration\n\n### Basic Configuration\n\n```typescript\nconst auth = new Tokenly({\n    accessTokenExpiry: \"15m\", // 15 minutes\n    refreshTokenExpiry: \"7d\", // 7 days\n    securityConfig: {\n        enableFingerprint: true, // Enable device tracking\n        maxDevices: 5, // Max devices per user\n    },\n});\n```\n\n### Advanced Security Configuration\n\n```typescript\nconst auth = new Tokenly({\n    accessTokenExpiry: \"5m\", // Shorter token life\n    refreshTokenExpiry: \"1d\", // Daily refresh required\n    securityConfig: {\n        enableFingerprint: true, // Required for device tracking\n        enableBlacklist: true, // Enable token revocation\n        maxDevices: 3, // Strict device limit\n    },\n});\n```\n\n## 🛡️ Security Features\n\n### Device Fingerprinting\n\n- **User Agent**: Browser/client identification\n- **IP Address**: Client's IP address\n- **Cryptographic Salt**: Unique per instance\n- **Consistent Hashing**: Same device = Same fingerprint\n\n### Token Management\n\n- **Access Tokens**: Short-lived JWTs for API access\n- **Refresh Tokens**: Long-lived tokens for session maintenance\n- **Blacklisting**: Optional token revocation support\n- **Expiration Control**: Configurable token lifetimes\n\n### Security Events\n\n```typescript\n// Invalid Fingerprint Detection\nauth.on(\"invalid_fingerprint\", (event) =\u003e {\n    console.log(`Security Alert: Invalid fingerprint detected`);\n    console.log(`User: ${event.userId}`);\n    console.log(`IP: ${event.context.ip}`);\n});\n\n// Device Limit Reached\nauth.on(\"max_devices_reached\", (event) =\u003e {\n    console.log(`Device limit reached for user: ${event.userId}`);\n    console.log(`Current devices: ${event.context.currentDevices}`);\n});\n```\n\n## 📘 API Reference\n\n### Token Generation\n\n```typescript\nconst token = auth.generateAccessToken(\n    payload: { userId: string; role: string },\n    options?: { fingerprint?: string; deviceId?: string },\n    context?: { userAgent: string; ip: string }\n);\n```\n\n### IP Detection Helper\n\n```typescript\nimport { getClientIP } from \"@nekzus/tokenly\";\n\nconst clientIP = getClientIP(headers, defaultIP);\n```\n\nPriority order:\n\n1. `X-Real-IP`: Direct proxy IP\n2. `X-Forwarded-For`: First IP in proxy chain\n3. Default IP (if provided)\n4. Empty string (fallback)\n\n### Type Definitions\n\n```typescript\ninterface AccessToken {\n    raw: string;\n    payload: {\n        userId: string;\n        role: string;\n        [key: string]: any;\n    };\n}\n\ninterface InvalidFingerprintEvent {\n    type: \"invalid_fingerprint\";\n    userId: string;\n    token: string;\n    context: {\n        expectedFingerprint: string;\n        receivedFingerprint: string;\n        ip: string;\n        userAgent: string;\n        timestamp: string;\n    };\n}\n\ninterface MaxDevicesEvent {\n    type: \"max_devices_reached\";\n    userId: string;\n    context: {\n        currentDevices: number;\n        maxAllowed: number;\n        ip: string;\n        userAgent: string;\n        timestamp: string;\n    };\n}\n```\n\n## 🔑 Environment Variables \u0026 Secrets\n\n### Required Variables\n\n```env\n# .env\nJWT_SECRET_ACCESS=your_secure_access_token_secret\nJWT_SECRET_REFRESH=your_secure_refresh_token_secret\n```\n\nWhen environment variables are not provided, Tokenly automatically:\n\n- Generates cryptographically secure random secrets\n- Uses SHA-256 for secret generation\n- Implements secure entropy sources\n- Creates unique secrets per instance\n\n\u003e ⚠️ **Important**: While auto-generated secrets are cryptographically secure,\n\u003e they regenerate on each application restart. This means all previously issued\n\u003e tokens will become invalid. For production environments, always provide\n\u003e permanent secrets through environment variables.\n\n### Secret Generation\n\n```bash\n# Generate secure random secrets\nnode -e \"console.log(require('crypto').randomBytes(64).toString('hex'))\"\n```\n\n### Security Guidelines\n\n- Never commit secrets to version control\n- Use different secrets for development and production\n- Minimum length of 32 characters recommended\n- Rotate secrets periodically in production\n- Use secret management services when available\n\n## 🔐 Best Practices\n\n### Token Security\n\n- Use short-lived access tokens (5-15 minutes)\n- Implement refresh token rotation\n- Enable blacklisting for critical applications\n\n### Refresh Token Security\n\n- Use HttpOnly cookies for refresh tokens\n- Configure cookie-parser middleware\n- Enable secure and sameSite options in production\n- Implement proper CORS configuration when needed\n\n### Device Management\n\n- Enable fingerprinting for sensitive applications\n- Set reasonable device limits per user\n- Monitor security events\n\n### IP Detection\n\n- Configure proxy headers correctly\n- Use `X-Real-IP` for single proxy setups\n- Handle `X-Forwarded-For` for proxy chains\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md)\nfor details.\n\n## 📄 License\n\nMIT © [Nekzus](https://github.com/Nekzus)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnekzus%2Ftokenly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnekzus%2Ftokenly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnekzus%2Ftokenly/lists"}