{"id":31956345,"url":"https://github.com/profullstack/auth-system","last_synced_at":"2026-02-27T09:12:27.000Z","repository":{"id":292679926,"uuid":"981596757","full_name":"profullstack/auth-system","owner":"profullstack","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-18T14:32:31.000Z","size":137,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-10-23T19:52:02.591Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/profullstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-05-11T13:22:46.000Z","updated_at":"2025-05-18T14:32:34.000Z","dependencies_parsed_at":"2025-05-11T15:19:03.491Z","dependency_job_id":"9e03acb8-2141-4eb0-8b83-02415453f327","html_url":"https://github.com/profullstack/auth-system","commit_stats":null,"previous_names":["profullstack/auth-system"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/profullstack/auth-system","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fauth-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fauth-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fauth-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fauth-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/profullstack","download_url":"https://codeload.github.com/profullstack/auth-system/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fauth-system/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29889074,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T08:34:21.514Z","status":"ssl_error","status_checked_at":"2026-02-27T08:32:38.035Z","response_time":57,"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":[],"created_at":"2025-10-14T14:48:36.446Z","updated_at":"2026-02-27T09:12:26.981Z","avatar_url":"https://github.com/profullstack.png","language":"JavaScript","readme":"# @profullstack/auth-system\n\nA flexible authentication system with user registration, login/logout, password reset, and session management.\n\n## Features\n\n- **User Management**: Registration, login, profile management\n- **Authentication**: JWT-based authentication with access and refresh tokens\n- **Password Management**: Secure password hashing, validation, reset\n- **Email Verification**: Email verification for new accounts\n- **Adapters**: Pluggable storage adapters (memory, Supabase, MySQL, PostgreSQL, MongoDB, PocketBase, etc.)\n- **Middleware**: Express/Connect/Hono middleware for protected routes\n- **Validation**: Input validation for emails, passwords, etc.\n- **Customization**: Configurable password requirements, token expiry, etc.\n\n## Installation\n\n```bash\nnpm install @profullstack/auth-system\n```\n\n## Basic Usage\n\n```javascript\nimport { createAuthSystem } from '@profullstack/auth-system';\n\n// Create an auth system with default options\nconst authSystem = createAuthSystem({\n  tokenOptions: {\n    secret: 'your-secret-key-here',\n    accessTokenExpiry: 3600, // 1 hour\n    refreshTokenExpiry: 604800 // 7 days\n  }\n});\n\n// Register a new user\nconst registrationResult = await authSystem.register({\n  email: 'user@example.com',\n  password: 'Password123',\n  profile: {\n    firstName: 'John',\n    lastName: 'Doe'\n  }\n});\n\n// Login\nconst loginResult = await authSystem.login({\n  email: 'user@example.com',\n  password: 'Password123'\n});\n\n// Use the tokens for authentication\nconst { accessToken, refreshToken } = loginResult.tokens;\n```\n\n## API Reference\n\n### Creating an Auth System\n\n```javascript\nimport { createAuthSystem, MemoryAdapter } from '@profullstack/auth-system';\n\nconst authSystem = createAuthSystem({\n  // Storage adapter (optional, defaults to in-memory)\n  adapter: new MemoryAdapter(),\n  \n  // Token configuration (optional)\n  tokenOptions: {\n    accessTokenExpiry: 3600, // 1 hour\n    refreshTokenExpiry: 604800, // 7 days\n    secret: 'your-secret-key-here'\n  },\n  \n  // Password configuration (optional)\n  passwordOptions: {\n    minLength: 8,\n    requireUppercase: true,\n    requireLowercase: true,\n    requireNumbers: true,\n    requireSpecialChars: false\n  },\n  \n  // Email configuration (optional)\n  emailOptions: {\n    sendEmail: async (emailData) =\u003e {\n      // Your email sending implementation\n    },\n    fromEmail: 'noreply@example.com',\n    resetPasswordTemplate: {\n      subject: 'Reset Your Password',\n      text: 'Click the link to reset your password: {resetLink}',\n      html: '\u003cp\u003eClick the link to reset your password: \u003ca href=\"{resetLink}\"\u003e{resetLink}\u003c/a\u003e\u003c/p\u003e'\n    },\n    verificationTemplate: {\n      subject: 'Verify Your Email',\n      text: 'Click the link to verify your email: {verificationLink}',\n      html: '\u003cp\u003eClick the link to verify your email: \u003ca href=\"{verificationLink}\"\u003e{verificationLink}\u003c/a\u003e\u003c/p\u003e'\n    }\n  }\n});\n```\n\n### User Registration\n\n```javascript\nconst registrationResult = await authSystem.register({\n  email: 'user@example.com',\n  password: 'Password123',\n  profile: {\n    firstName: 'John',\n    lastName: 'Doe'\n  },\n  autoVerify: false // Set to true to skip email verification\n});\n```\n\n### User Login\n\n```javascript\nconst loginResult = await authSystem.login({\n  email: 'user@example.com',\n  password: 'Password123'\n});\n\n// The login result contains user data and tokens\nconst { user, tokens } = loginResult;\n```\n\n### Token Refresh\n\n```javascript\nconst refreshResult = await authSystem.refreshToken(refreshToken);\n\n// The refresh result contains new tokens\nconst { accessToken, refreshToken } = refreshResult.tokens;\n```\n\n### Password Reset\n\n```javascript\n// Request password reset\nconst resetResult = await authSystem.resetPassword('user@example.com');\n\n// Confirm password reset (in a real app, the token would come from the email link)\nconst confirmResult = await authSystem.resetPasswordConfirm({\n  token: 'reset-token-from-email',\n  password: 'NewPassword123'\n});\n```\n\n### Email Verification\n\n```javascript\n// Verify email (in a real app, the token would come from the email link)\nconst verificationResult = await authSystem.verifyEmail('verification-token-from-email');\n```\n\n### User Profile Management\n\n```javascript\n// Get user profile\nconst profileResult = await authSystem.getProfile(userId);\n\n// Update user profile\nconst updateResult = await authSystem.updateProfile({\n  userId,\n  profile: {\n    firstName: 'John',\n    lastName: 'Doe',\n    phoneNumber: '555-123-4567'\n  }\n});\n\n// Change password\nconst changePasswordResult = await authSystem.changePassword({\n  userId,\n  currentPassword: 'Password123',\n  newPassword: 'NewPassword123'\n});\n```\n\n### Token Validation\n\n```javascript\n// Validate an access token\nconst user = await authSystem.validateToken(accessToken);\n\nif (user) {\n  // Token is valid, user contains user data\n  console.log(`Valid token for user: ${user.email}`);\n} else {\n  // Token is invalid or expired\n  console.log('Invalid token');\n}\n```\n\n### Logout\n\n```javascript\n// Logout (invalidates the refresh token)\nconst logoutResult = await authSystem.logout(refreshToken);\n```\n\n### Middleware\n\n```javascript\nimport express from 'express';\nimport { createAuthSystem } from '@profullstack/auth-system';\n\nconst app = express();\nconst authSystem = createAuthSystem();\n\n// Protect routes with authentication middleware\napp.use('/api/protected', authSystem.middleware());\n\napp.get('/api/protected/profile', (req, res) =\u003e {\n  // req.user contains the authenticated user data\n  res.json({ user: req.user });\n});\n\napp.listen(3000);\n```\n\n## Storage Adapters\n\n### Memory Adapter (Default)\n\nStores user data in memory. Suitable for development or testing.\n\n```javascript\nimport { createAuthSystem, MemoryAdapter } from '@profullstack/auth-system';\n\nconst authSystem = createAuthSystem({\n  adapter: new MemoryAdapter()\n});\n```\n\n### JWT Adapter\n\nUses JSON Web Tokens (JWT) for authentication. Requires a database adapter for user storage.\n\n```javascript\nimport { createAuthSystem, MemoryAdapter, JwtAdapter } from '@profullstack/auth-system';\n\nconst dbAdapter = new MemoryAdapter();\nconst jwtAdapter = new JwtAdapter({\n  dbAdapter,\n  secret: 'your-secret-key-here'\n});\n\nconst authSystem = createAuthSystem({\n  adapter: jwtAdapter\n});\n```\n\n### Supabase Adapter\n\nUses Supabase for user storage and authentication. Requires the `@supabase/supabase-js` package.\n\n```javascript\nimport { createAuthSystem, SupabaseAdapter } from '@profullstack/auth-system';\n\nconst supabaseAdapter = new SupabaseAdapter({\n  supabaseUrl: 'https://your-project-id.supabase.co',\n  supabaseKey: 'your-supabase-api-key',\n  tableName: 'users', // Optional: defaults to 'users'\n  tokensTableName: 'invalidated_tokens' // Optional: defaults to 'invalidated_tokens'\n});\n\nconst authSystem = createAuthSystem({\n  adapter: supabaseAdapter,\n  tokenOptions: {\n    secret: 'your-jwt-secret-key'\n  }\n});\n```\n\n\u003e **Note:** Before using the Supabase adapter, you need to set up the required tables in your Supabase database. You can use the [supabase-schema.sql](./examples/supabase-schema.sql) file to create the necessary tables and indexes.\n\n### MySQL Adapter\n\nUses MySQL for user storage and authentication. Requires the `mysql2` package.\n\n```javascript\nimport { createAuthSystem, MySQLAdapter } from '@profullstack/auth-system';\n\nconst mysqlAdapter = new MySQLAdapter({\n  host: 'localhost',\n  port: 3306,\n  database: 'auth_system',\n  user: 'root',\n  password: 'password',\n  usersTable: 'users', // Optional: defaults to 'users'\n  tokensTable: 'invalidated_tokens' // Optional: defaults to 'invalidated_tokens'\n});\n\nconst authSystem = createAuthSystem({\n  adapter: mysqlAdapter,\n  tokenOptions: {\n    secret: 'your-jwt-secret-key'\n  }\n});\n```\n\n\u003e **Note:** This is a stub implementation. You'll need to complete the implementation before using it in production.\n\n### PostgreSQL Adapter\n\nUses PostgreSQL for user storage and authentication. Requires the `pg` package.\n\n```javascript\nimport { createAuthSystem, PostgresAdapter } from '@profullstack/auth-system';\n\nconst postgresAdapter = new PostgresAdapter({\n  host: 'localhost',\n  port: 5432,\n  database: 'auth_system',\n  user: 'postgres',\n  password: 'password',\n  usersTable: 'users', // Optional: defaults to 'users'\n  tokensTable: 'invalidated_tokens' // Optional: defaults to 'invalidated_tokens'\n});\n\nconst authSystem = createAuthSystem({\n  adapter: postgresAdapter,\n  tokenOptions: {\n    secret: 'your-jwt-secret-key'\n  }\n});\n```\n\n\u003e **Note:** This is a stub implementation. You'll need to complete the implementation before using it in production.\n\n### MongoDB Adapter\n\nUses MongoDB for user storage and authentication. Requires the `mongodb` package.\n\n```javascript\nimport { createAuthSystem, MongoDBAdapter } from '@profullstack/auth-system';\n\nconst mongodbAdapter = new MongoDBAdapter({\n  uri: 'mongodb://localhost:27017',\n  dbName: 'auth_system',\n  usersCollection: 'users', // Optional: defaults to 'users'\n  tokensCollection: 'invalidated_tokens' // Optional: defaults to 'invalidated_tokens'\n});\n\nconst authSystem = createAuthSystem({\n  adapter: mongodbAdapter,\n  tokenOptions: {\n    secret: 'your-jwt-secret-key'\n  }\n});\n```\n\n\u003e **Note:** This is a stub implementation. You'll need to complete the implementation before using it in production.\n\n### PocketBase Adapter\n\nUses PocketBase for user storage and authentication. Requires the `pocketbase` package.\n\n```javascript\nimport { createAuthSystem, PocketBaseAdapter } from '@profullstack/auth-system';\n\nconst pocketbaseAdapter = new PocketBaseAdapter({\n  url: 'http://127.0.0.1:8090',\n  usersCollection: 'auth_users', // Optional: defaults to 'auth_users'\n  tokensCollection: 'auth_invalidated_tokens', // Optional: defaults to 'auth_invalidated_tokens'\n  adminEmail: 'admin@example.com', // Optional: for admin authentication\n  adminPassword: 'password' // Optional: for admin authentication\n});\n\nconst authSystem = createAuthSystem({\n  adapter: pocketbaseAdapter,\n  tokenOptions: {\n    secret: 'your-jwt-secret-key'\n  }\n});\n```\n\n### Creating Custom Adapters\n\nYou can create custom adapters by implementing the adapter interface:\n\n```javascript\nclass CustomAdapter {\n  async createUser(userData) { /* ... */ }\n  async getUserById(userId) { /* ... */ }\n  async getUserByEmail(email) { /* ... */ }\n  async updateUser(userId, updates) { /* ... */ }\n  async deleteUser(userId) { /* ... */ }\n  async invalidateToken(token) { /* ... */ }\n  async isTokenInvalidated(token) { /* ... */ }\n}\n```\n\n\u003e **Note:** Before using the PocketBase adapter, you need to set up the required collections in your PocketBase database. You can use the [pocketbase-schema.json](./examples/pocketbase-schema.json) file to create the necessary collections and indexes.\n\n## Examples\n\nSee the [examples](./examples) directory for complete usage examples:\n\n- [Basic Usage](./examples/basic-usage.js): Simple example of using the auth system\n- [Supabase Usage](./examples/supabase-usage.js): Example of using the auth system with Supabase\n- [Supabase Schema](./examples/supabase-schema.sql): SQL schema for setting up Supabase tables\n- [PocketBase Usage](./examples/pocketbase-usage.js): Example of using the auth system with PocketBase\n- [PocketBase Schema](./examples/pocketbase-schema.json): JSON schema for setting up PocketBase collections\n- [Browser Integration](./examples/browser-integration/): Complete example of integrating the auth system into a browser-based web application\n\n### Browser Integration\n\nThe browser integration example provides a complete authentication system for web applications, including:\n\n- User registration with payment integration (Stripe, crypto)\n- Login/logout functionality\n- Password reset and change\n- Profile management\n- API key management\n- Authentication status utilities\n\nIt includes a browser-friendly wrapper around the auth-system module with localStorage support and event handling. See the [Browser Integration README](./examples/browser-integration/README.md) for more details.\n\n## License\n\nMIT","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprofullstack%2Fauth-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprofullstack%2Fauth-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprofullstack%2Fauth-system/lists"}