{"id":31762238,"url":"https://github.com/clgcon/nodejs-auth-starter","last_synced_at":"2025-10-09T22:06:11.370Z","repository":{"id":276325153,"uuid":"913205764","full_name":"clgcon/nodejs-auth-starter","owner":"clgcon","description":"Web dashboard boilerplate for NodeJS with custom user authentication, mandatory 2FA, SQLite3 and JWT","archived":false,"fork":false,"pushed_at":"2025-07-09T02:30:31.000Z","size":1641,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-15T06:36:40.354Z","etag":null,"topics":["2fa","auth","authentication","dashboard","gui-application","jwt","nodejs","sqlite3","user-management","vanilla-js"],"latest_commit_sha":null,"homepage":"","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/clgcon.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-07T08:32:29.000Z","updated_at":"2025-07-09T02:30:35.000Z","dependencies_parsed_at":"2025-02-07T15:29:57.553Z","dependency_job_id":"c5f3e101-c5f8-4888-a65b-ed116a8add77","html_url":"https://github.com/clgcon/nodejs-auth-starter","commit_stats":null,"previous_names":["cgtwig/nodejs-auth-starter","drummacon/nodejs-auth-starter","conrsg/nodejs-auth-starter","httpcg/nodejs-auth-starter","grayc4/nodejs-auth-starter","ipwill/nodejs-auth-starter","grayip/nodejs-auth-starter","clgcon/nodejs-auth-starter"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/clgcon/nodejs-auth-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clgcon%2Fnodejs-auth-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clgcon%2Fnodejs-auth-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clgcon%2Fnodejs-auth-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clgcon%2Fnodejs-auth-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clgcon","download_url":"https://codeload.github.com/clgcon/nodejs-auth-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clgcon%2Fnodejs-auth-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002113,"owners_count":26083306,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["2fa","auth","authentication","dashboard","gui-application","jwt","nodejs","sqlite3","user-management","vanilla-js"],"created_at":"2025-10-09T22:06:05.702Z","updated_at":"2025-10-09T22:06:11.361Z","avatar_url":"https://github.com/clgcon.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"### About\n`nodejs-auth-starter` is a boilerplate user authentication web app for NodeJS.\n\n![dark-register.png](public/images/dark-register.png)\n![dark-login.png](public/images/dark-login.png)\n\n## Security\nIncludes basic support for JWT, CSRF, password hashing, signup/login pages, password reset, username editing and more.\n\n### Features\n\n- **better-sqlite3** (user data)\n- **JWT-token** (token-based auth)\n- **2FA**\n- **Helmet.js** (CSRF/HTTP)\n- **Webpack**\n- **EJS**\n- **Responsive**\n- **Rate Limiting**\n- **Password Reset**\n- **Light/Dark toggle**\u003cbr\u003e\n  and more...\n\n### Requirements\n\n- **Node.js:** 18.x or higher\n- **npm:** 8.x or higher\n- **OpenSSL:** Required for security keys\n- **Ports:**\n  - 3000 (app server)\n  - 1025 (MailHog SMTP)\n  - 8025 (MailHog UI)\n- **OS:** Windows 10/11, macOS 10.15+, or Linux (Ubuntu 20.04+, Debian 11+)\n\n### Dependencies\n\n| Category      | Package            | Version   |\n|---------------|--------------------|-----------|\n| **Core**      | express            | ^4.18.x   |\n|               | better-sqlite3     | ^11.8.x   |\n|               | jsonwebtoken       | ^9.0.x    |\n|               | nodemailer         | ^6.9.x    |\n|               | dotenv             | ^16.4.x   |\n|               | axios              | ^1.6.x    |\n| **Security**  | helmet             | ^7.1.x    |\n|               | express-rate-limit | ^7.1.x    |\n|               | csrf               | ^3.1.x    |\n|               | cookie-parser      | ^1.4.x    |\n|               | crypto (built-in)  | N/A       |\n| **Validation**| express-validator  | ^7.0.x    |\n| **Frontend**  | ejs                | ^3.1.x    |\n|               | cors               | ^2.8.x    |\n| **Development**| mailhog           | N/A       |\n|               | webpack            | ^5.90.x   |\n|               | @babel/core        | ^7.23.x   |\n\n### Database schema\n\n```sql\n-- Users table\nCREATE TABLE IF NOT EXISTS users (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  username TEXT UNIQUE NOT NULL,\n  email TEXT UNIQUE NOT NULL,\n  password TEXT NOT NULL,\n  two_factor_method TEXT,\n  email_code TEXT,\n  email_code_expires INTEGER,\n  password_reset_token TEXT,\n  password_reset_expires INTEGER,\n  bypass_2fa BOOLEAN DEFAULT 0,\n  current_token TEXT,\n  dashboard_token TEXT UNIQUE,\n  created_at INTEGER NOT NULL,\n  updated_at INTEGER NOT NULL\n);\n\n-- User history table to track changes\nCREATE TABLE IF NOT EXISTS user_history (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  user_id INTEGER NOT NULL,\n  old_username TEXT,\n  old_email TEXT,\n  old_password TEXT,\n  changed_at INTEGER NOT NULL,\n  FOREIGN KEY (user_id) REFERENCES users(id)\n);\n```\n\n### More screenshots\n![light-register.png](public/images/light-register.png)\n![light-login.png](public/images/light-login.png)\n\n### API routes\n\n**Authentication**\n- `GET /api/check-auth` - Check if user is authenticated\n- `POST /api/register` - Register new user\n- `POST /api/login` - User login\n- `POST /api/verify-2fa` - Verify 2FA code\n- `POST /api/resend-2fa` - Resend 2FA code\n- `POST /api/logout` - User logout\n\n**Password management**\n- `POST /api/forgot-password` - Request password reset\n- `GET /reset-password` - Display password reset form\n- `POST /api/reset-password` - Process password reset\n\n**User settings \u0026 Data**\n- `POST /api/settings/update` - Update user settings (username, email, password)\n- `GET /api/check-username-availability` - Check if username is available\n- `GET /api/admin/username-history/:userId` - Get username change history for a user\n\n**Frontend Routes (Server-Rendered)**\n- `GET /user/:dashboardToken` - Access user dashboard\n- `GET /dashboard` - Redirects to user-specific dashboard\n- `GET /` - Login/Register page\n- `GET /logged-out` - Logout confirmation page\n\n### Setup\n\n1.  **Clone:**\n    ```bash\n    git clone https://github.com/cgtwig/nodejs-auth-starter\n    cd nodejs-auth-starter\n    ```\n\n2.  **Install:**\n    ```bash\n    npm install\n    ```\n\n3.  **Configure environment (`.env`)**\n\n    **(Required)** Rename `.env-example` to `.env` (or create file named `.env` with the contents below)\n\n    ```env\n    # Server Configuration\n    PORT=3000\n    NODE_ENV=development\n    \n    # MailHog SMTP Configuration (Local Development)\n    SMTP_HOST=127.0.0.1\n    SMTP_PORT=1025\n    SMTP_SECURE=false\n\n    # SQLite Database File\n    DB_PATH=./database.db\n\n    # Allowed Origins (CORS)\n    ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000\n\n    # Allowed Hosts (Host Header Injection Prevention)\n    ALLOWED_HOSTS=localhost:3000,127.0.0.1:3000\n\n    # REQUIRED\n    JWT_SECRET=\n    ENCRYPTION_KEY=\n    CSRF_SECRET=\n    ENCRYPTION_IV=\n    ```\n\n    **(Required)** Generate the following values for the values at the end of the `.env`\n    ```bash\n    # run in terminal (openssl will need to be installed)\n    openssl rand -hex 32   # JWT_SECRET\n    openssl rand -hex 32   # ENCRYPTION_KEY\n    openssl rand -hex 32   # CSRF_SECRET\n    openssl rand -hex 16   # ENCRYPTION_IV\n    ```\n\n4.  **2FA: MailHog**\n\n    One-liner commands to download and run MailHog\n\n     a) **macOS/Linux/Unix (terminal):**\n    ```bash\n    sh -c 'os=$(uname -s); arch=$(uname -m); V=\"v1.0.1\"; case \"$os-$arch\" in Linux-x86_64|Linux-amd64) suffix=\"linux_amd64\";; Linux-aarch64|Linux-arm64) suffix=\"linux_arm64\";; Darwin-x86_64|Darwin-amd64) suffix=\"darwin_amd64\";; Darwin-arm64) suffix=\"darwin_amd64\"; echo \"NOTE: Using amd64 binary via Rosetta 2 on arm64 Mac.\";; *) echo \"Error: Unsupported OS/Arch: $os-$arch\"; exit 1;; esac; echo \"Downloading MailHog_$suffix...\"; curl -fL \"https://github.com/mailhog/MailHog/releases/download/$V/MailHog_$suffix\" -o mailhog \u0026\u0026 chmod +x mailhog \u0026\u0026 echo \"Starting MailHog...\" \u0026\u0026 ./mailhog || echo \"MailHog download or execution failed.\"'\n    ```\n    \n    b) **Windows (Powershell):**\n    ```powershell\n    Invoke-WebRequest -Uri \"https://github.com/mailhog/MailHog/releases/download/v1.0.1/MailHog_windows_amd64.exe\" -OutFile \"mailhog.exe\" ; Start-Process -FilePath \".\\mailhog.exe\"\n    ```\n    \n    c) **(Optional) Docker**\n    ```\n    docker run --rm -d -p 1025:1025 -p 8025:8025 --name mailhog mailhog/mailhog\n    ```\n    \n    Note: Access MailHog UI at [http://localhost:8025](http://localhost:8025) after installation\n\n6.  **Build:**\n    ```bash\n    npm run build\n    ```\n\n7.  **Start:**\n    ```bash\n    # Development (hot reloading)\n    npm run dev\n\n    # Production\n    npm start\n    ```\n\n    Access the application at [http://localhost:3000](http://localhost:3000)\n\n### License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclgcon%2Fnodejs-auth-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclgcon%2Fnodejs-auth-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclgcon%2Fnodejs-auth-starter/lists"}