npm - @javagt/express-easy-auth - Versions diffs - 1.0.0 - Mend

@javagt/express-easy-auth 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/.env.example +13 -0
package/demo/profileRouter.js +64 -0
package/demo/public/css/style.css +1293 -0
package/demo/public/index.html +272 -0
package/demo/public/js/app.js +540 -0
package/demo/server.js +195 -0
package/examples/01-basic-setup.js +118 -0
package/examples/02-passkeys.js +106 -0
package/examples/03-api-keys.js +108 -0
package/examples/04-totp-setup.js +125 -0
package/examples/05-custom-logger.js +105 -0
package/examples/06-password-reset.js +104 -0
package/examples/08-external-db-linking.js +158 -0
package/examples/README.md +32 -0
package/openapi.yaml +263 -0
package/package.json +35 -0
package/readme.md +165 -0
package/scratch/debug_bindings.js +29 -0
package/scratch/test_sqlite.js +7 -0
package/scratch/test_sqlite_multargs.js +17 -0
package/scratch/test_sqlite_undefined.js +9 -0
package/scratch/verify_sqlite_fix.js +14 -0
package/src/client.js +295 -0
package/src/db/init.js +203 -0
package/src/db/sessionStore.js +67 -0
package/src/index.js +61 -0
package/src/middleware/auth.js +111 -0
package/src/routes/auth.js +569 -0
package/src/utils/authHelpers.js +48 -0
package/src/utils/logger.js +71 -0
package/test/auth.test.js +32 -0
package/test/passkeys.test.js +19 -0
package/test/user.test.js +29 -0

package/examples/05-custom-logger.js ADDED Viewed

@@ -0,0 +1,105 @@
+/**
+ * Example 05: Custom Logger
+ *
+ * Shows how to plug in a custom logger implementation (e.g. for Winston or Pino)
+ */
+import express from 'express';
+import { setupAuth, authRouter, DefaultLogger } from '../src/index.js';
+const app = express();
+app.use(express.json());
+// 1. Define a custom logger
+// It must implement: error, warn, info, debug
+class MyCustomLogger {
+  error(msg, meta) {
+    console.log(`[MY-APP-ERROR] ${msg}`, meta.err?.stack || '');
+    // You could send to Sentry, Datadog, etc. here
+  }
+  warn(msg, meta) { console.log(`[MY-APP-WARN] ${msg}`); }
+  info(msg, meta) { console.log(`[MY-APP-INFO] ${msg}`); }
+  debug(msg, meta) { console.log(`[MY-APP-DEBUG] ${msg}`); }
+}
+// 2. Or extend the DefaultLogger to keep DB logging but change console output
+class EnhancedLogger extends DefaultLogger {
+  info(msg, meta) {
+    super.info(msg, meta); // Keep default behavior (DB + Console)
+    console.log('--- Custom log decorator ---');
+  }
+}
+// 3. Initialize with custom logger
+setupAuth(app, {
+  dataDir: './data-example',
+  exposeErrors: true, // Always show details for this demo
+  logger: new MyCustomLogger(), // Plug in your implementation
+  config: { domain: 'localhost' }
+});
+// Standard mount point
+app.use('/api/v1/auth', authRouter);
+// Test route to trigger an error
+app.get('/test-error', (req, res, next) => {
+  next(new Error('This is a simulated system error'));
+});
+// Import the error logger middleware last!
+import { authErrorLogger } from '../src/index.js';
+app.use(authErrorLogger);
+app.get('/', (req, res) => {
+  res.send(`
+    <!DOCTYPE html>
+    <html>
+    <head><title>Auth SDK Demo - Custom Logger</title></head>
+    <body style="font-family: sans-serif; padding: 2rem; background: #fafafa;">
+      <h1>Auth SDK Demo: Custom Logger</h1>
+      <p>This page demonstrates how the SDK interacts with a custom server-side logger.</p>
+      <div id="controls">
+        <button id="triggerErrorBtn">1. Trigger Server Error (500)</button>
+        <button id="reportBtn">2. Manually Report SDK Error</button>
+      </div>
+      <hr>
+      <div id="output" style="background: #333; color: #fff; padding: 1rem; border-radius: 4px; font-family: monospace; min-height: 100px; white-space: pre-wrap;">Console Output...</div>
+      <p><small>Check the <b>Node.js terminal</b> to see the [MY-APP-ERROR] logs!</small></p>
+      <script type="module">
+        import { AuthClient } from '/auth-sdk.js';
+        const auth = new AuthClient();
+        const log = (msg) => {
+          document.getElementById('output').innerText += '\\n> ' + msg;
+        };
+        document.getElementById('triggerErrorBtn').onclick = async () => {
+          try {
+            log('Fetching /test-error...');
+            const res = await fetch('/test-error');
+            const data = await res.json();
+            log('Server matched error: ' + JSON.stringify(data));
+          } catch (e) { log('Fetch error: ' + e.message); }
+        };
+        document.getElementById('reportBtn').onclick = async () => {
+          try {
+            log('Reporting client-side error to server...');
+            await auth.reportError(new Error('Something went wrong on the client!'), {
+              browser: navigator.userAgent
+            });
+            log('Error reported successfully!');
+          } catch (e) { log('Report Error: ' + e.message); }
+        };
+      </script>
+    </body>
+    </html>
+  `);
+});
+const PORT = 3000;
+app.listen(PORT, () => {
+  console.log(`Example 05 running at http://localhost:${PORT}`);
+});

package/examples/06-password-reset.js ADDED Viewed

@@ -0,0 +1,104 @@
+/**
+ * Example 06: Password Reset
+ *
+ * Demonstrates the full flow of requesting a reset token and resetting a password.
+ */
+import express from 'express';
+import session from 'express-session';
+import {
+  setupAuth,
+  authRouter,
+  SQLiteSessionStore,
+  authDb
+} from '../src/index.js';
+const app = express();
+app.use(express.json());
+setupAuth(app, {
+  dataDir: './data-example-reset',
+  exposeErrors: true,
+  config: { domain: 'localhost' }
+});
+app.use(session({
+  secret: 'reset-secret',
+  store: new SQLiteSessionStore(),
+  resave: false,
+  saveUninitialized: false,
+  cookie: { secure: false }
+}));
+// Standard mount point
+app.use('/api/v1/auth', authRouter);
+app.get('/', (req, res) => {
+  res.send(`
+    <!DOCTYPE html>
+    <html>
+    <head><title>Auth SDK Demo - Password Reset</title></head>
+    <body style="font-family: sans-serif; padding: 2rem; background: #f0fdf4;">
+      <h1>Auth SDK Demo: Password Reset</h1>
+      <p>This demo shows how to request a reset token and use it to change a password.</p>
+      <div id="controls">
+        <button id="regBtn">1. Register User (user_reset)</button>
+        <button id="forgotBtn">2. Forgot Password</button>
+      </div>
+      <div id="resetArea" style="margin-top: 2rem; display: none; background: #fff; padding: 1.5rem; border: 1px solid #dcfce7; border-radius: 8px;">
+        <h3>Reset Password</h3>
+        <p>A token was generated in the database (simulating an email).</p>
+        <input type="text" id="tokenIn" placeholder="Enter Token">
+        <input type="password" id="passIn" placeholder="New Password">
+        <button id="resetBtn">3. Reset Password</button>
+      </div>
+      <hr>
+      <div id="output" style="background: #333; color: #fff; padding: 1rem; border-radius: 4px; font-family: monospace; min-height: 100px; white-space: pre-wrap;">Console Output...</div>
+      <script type="module">
+        import { AuthClient } from '/auth-sdk.js';
+        const auth = new AuthClient();
+        const log = (msg) => {
+          document.getElementById('output').innerText += '\\n> ' + msg;
+        };
+        document.getElementById('regBtn').onclick = async () => {
+          try {
+            await auth.register('user_reset', 'reset@example.com', 'oldpassword');
+            log('User registered with password: oldpassword');
+          } catch (e) { log('Error: ' + e.message); }
+        };
+        document.getElementById('forgotBtn').onclick = async () => {
+          try {
+            log('Requesting reset for user_reset...');
+            const res = await auth.forgotPassword('user_reset');
+            log('Request success! Check the server logs (or DB) for the token.');
+            document.getElementById('resetArea').style.display = 'block';
+          } catch (e) { log('Error: ' + e.message); }
+        };
+        document.getElementById('resetBtn').onclick = async () => {
+          const token = document.getElementById('tokenIn').value;
+          const pass = document.getElementById('passIn').value;
+          try {
+            await auth.resetPassword(token, pass);
+            log('Password successfully reset! You can now login with the new password.');
+            document.getElementById('resetArea').style.display = 'none';
+          } catch (e) { log('Error: ' + e.message); }
+        };
+      </script>
+    </body>
+    </html>
+  `);
+});
+const PORT = 3000;
+app.listen(PORT, () => {
+  console.log(`Example 06 running at http://localhost:${PORT}`);
+  console.log(`NOTE: In a real app, you would email the token to the user.`);
+});

package/examples/08-external-db-linking.js ADDED Viewed

@@ -0,0 +1,158 @@
+/**
+ * Example 08: External Database Linking
+ *
+ * Demonstrates the "contained identity" model:
+ * Auth server handles identity, while your app database handles profile data.
+ */
+import express from 'express';
+import session from 'express-session';
+import { DatabaseSync } from 'node:sqlite';
+import {
+  setupAuth,
+  authRouter,
+  SQLiteSessionStore,
+  requireAuth,
+  AuthClient
+} from '../src/index.js';
+const app = express();
+app.use(express.json());
+// ─── 1. SETUP AUTH SERVER ────────────────────────────────────────────────────
+setupAuth(app, {
+  dataDir: './data-example-external',
+  config: { domain: 'localhost' }
+});
+app.use(session({
+  secret: 'external-db-secret',
+  store: new SQLiteSessionStore(),
+  resave: false,
+  saveUninitialized: false,
+  cookie: { secure: false }
+}));
+// Standard mount point
+app.use('/api/v1/auth', authRouter);
+// ─── 2. SETUP APPLICATION DATABASE (Managed by Developer) ────────────────────
+const appDataDb = new DatabaseSync('./data-example-external/app_data.db');
+appDataDb.exec(`
+  CREATE TABLE IF NOT EXISTS user_profiles (
+    user_id TEXT PRIMARY KEY,
+    bio TEXT,
+    website TEXT,
+    theme TEXT DEFAULT 'light'
+  )
+`);
+const getProfile = appDataDb.prepare('SELECT * FROM user_profiles WHERE user_id = ?');
+const upsertProfile = appDataDb.prepare(`
+  INSERT INTO user_profiles (user_id, bio, website)
+  VALUES (?, ?, ?)
+  ON CONFLICT(user_id) DO UPDATE SET bio=excluded.bio, website=excluded.website
+`);
+// ─── 3. APP ROUTES (Combining Identity + Data) ───────────────────────────────
+// Get merged profile (Auth Identity + App Data)
+app.get('/api/app/profile', requireAuth, async (req, res) => {
+  // req.userId comes from the Auth Server middleware
+  const profile = getProfile.get(req.userId) || { bio: '', website: '' };
+  res.json({
+    userId: req.userId,
+    username: req.session.user.username, // From session
+    ...profile
+  });
+});
+// Update app-specific data
+app.post('/api/app/profile', requireAuth, (req, res) => {
+  const { bio, website } = req.body;
+  upsertProfile.run(req.userId, bio, website);
+  res.json({ success: true });
+});
+app.get('/', (req, res) => {
+  res.send(`
+    <!DOCTYPE html>
+    <html>
+    <head><title>Auth SDK Demo - External DB</title></head>
+    <body style="font-family: sans-serif; padding: 2rem; background: #f8fafc;">
+      <h1>Auth SDK Demo: External DB Linking</h1>
+      <p>This demo shows how to keep Identity (Auth Server) separate from Application Data.</p>
+      <div id="status">Checking Auth...</div>
+      <hr>
+      <div id="profileSection" style="display:none; background:white; padding:1.5 val rem; border:1px solid #e2e8f0; border-radius:8px; max-width:400px;">
+        <h3>Your Profile (App Data)</h3>
+        <p>User ID: <span id="uidDisplay"></span></p>
+        <div style="margin-bottom:1rem">
+          <label>Bio:</label><br>
+          <textarea id="bioInput" style="width:100%"></textarea>
+        </div>
+        <div style="margin-bottom:1rem">
+          <label>Website:</label><br>
+          <input type="text" id="webInput" style="width:100%">
+        </div>
+        <button id="saveBtn">Save App Data</button>
+      </div>
+      <div id="authSection" style="display:none;">
+        <button id="loginBtn">Login / Register</button>
+      </div>
+      <script type="module">
+        import { AuthClient } from '/auth-sdk.js';
+        const auth = new AuthClient();
+        async function init() {
+          const status = await auth.getStatus();
+          if (status.authenticated) {
+            document.getElementById('profileSection').style.display = 'block';
+            document.getElementById('uidDisplay').innerText = status.userId;
+            // Fetch app data
+            const res = await fetch('/api/app/profile');
+            const profile = await res.json();
+            document.getElementById('bioInput').value = profile.bio;
+            document.getElementById('webInput').value = profile.website;
+            document.getElementById('status').innerText = 'Logged in as ' + status.username;
+          } else {
+            document.getElementById('authSection').style.display = 'block';
+            document.getElementById('status').innerText = 'Not logged in';
+          }
+        }
+        document.getElementById('loginBtn').onclick = async () => {
+          const u = 'db_user_' + Math.floor(Math.random()*1000);
+          await auth.register(u, u+'@example.com', 'password123').catch(()=>{});
+          await auth.login(u, 'password123');
+          location.reload();
+        };
+        document.getElementById('saveBtn').onclick = async () => {
+          const bio = document.getElementById('bioInput').value;
+          const website = document.getElementById('webInput').value;
+          await fetch('/api/app/profile', {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({ bio, website })
+          });
+          alert('Saved to App Database!');
+        };
+        init();
+      </script>
+    </body>
+    </html>
+  `);
+});
+const PORT = 3000;
+app.listen(PORT, () => {
+  console.log(`Example 08 running at http://localhost:${PORT}`);
+});

package/examples/README.md ADDED Viewed

@@ -0,0 +1,32 @@
+# Auth Server Library Examples
+This directory contains standalone, well-documented reference implementations for each major feature of the library. These examples are designed to be read and run in isolation.
+## 🚀 How to Run
+Most examples require an Express environment. To run an example:
+1. `npm install` (if you haven't already)
+2. `node examples/01-basic-setup.js`
+## 📖 Available Examples
+### 01. Basic Setup
+**File**: `01-basic-setup.js`
+The "Hello World" of the library. Shows how to initialize `setupAuth`, configure standard Express sessions, and protect a basic route.
+### 02. Passkeys (WebAuthn)
+**File**: `02-passkeys.js`
+Focuses on the passwordless experience. Shows how to mount the `passkeysRouter` and integrate the `AuthClient` ceremonies for registration and login.
+### 03. API Keys
+**File**: `03-api-keys.js`
+Demonstrates programmatic access. Create machine-to-machine keys with granular permissions (`action:read`, `action:write`) and verify them using the `requireApiKey` middleware.
+### 04. TOTP 2FA lifecycle
+**File**: `04-totp-setup.js`
+Covers the setup and verification of Google Authenticator-style 2FA. Includes an example of `requireFreshAuth` for sensitive actions.
+---
+> [!TIP]
+> **Prototyping**: You can copy these files directly into your project as a starting point. All examples use local SQLite databases (`./data-example`) by default.

package/openapi.yaml ADDED Viewed

@@ -0,0 +1,263 @@
+openapi: 3.0.3
+info:
+  title: Auth Server API
+  version: 1.0.0
+  description: |
+    API for authentication, user management, passkeys, and API key access.
+    All endpoints require either session or API key authentication.
+servers:
+  - url: /api/v1
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: API_KEY
+    cookieAuth:
+      type: apiKey
+      in: cookie
+      name: connect.sid
+paths:
+  /user/me:
+    get:
+      summary: Get user profile
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          description: User profile
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  username:
+                    type: string
+                  email:
+                    type: string
+                  profile:
+                    type: object
+        '401':
+          description: Not authenticated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+  /user/keys:
+    get:
+      summary: List API keys
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          description: List of API keys
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  keys:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                        name:
+                          type: string
+                        permissions:
+                          type: array
+                          items:
+                            type: string
+                        created_at:
+                          type: integer
+                        last_used:
+                          type: integer
+        '401':
+          description: Not authenticated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+    post:
+      summary: Create API key
+      security:
+        - cookieAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                permissions:
+                  type: array
+                  items:
+                    type: string
+      responses:
+        '201':
+          description: Created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  key:
+                    type: string
+                  metadata:
+                    type: object
+        '400':
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+    delete:
+      summary: Delete API key
+      security:
+        - cookieAuth: []
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+        '404':
+          description: Not found
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+/auth/register:
+    post:
+      summary: Register a new user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                username:
+                  type: string
+                email:
+                  type: string
+                password:
+                  type: string
+      responses:
+        '201':
+          description: Registered
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  userId:
+                    type: string
+                  username:
+                    type: string
+                  message:
+                    type: string
+                  user:
+                    type: object
+        '400':
+          description: Missing or invalid input
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+        '409':
+          description: Username or email taken
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+  /auth/login:
+    post:
+      summary: Login with username and password
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                username:
+                  type: string
+                password:
+                  type: string
+      responses:
+        '200':
+          description: Login successful
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  userId:
+                    type: string
+                  username:
+                    type: string
+                  user:
+                    type: object
+        '400':
+          description: Missing credentials
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+        '401':
+          description: Invalid credentials
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+        '403':
+          description: Account locked
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string

package/package.json ADDED Viewed

@@ -0,0 +1,35 @@
+{
+  "name": "@javagt/express-easy-auth",
+  "version": "1.0.0",
+  "description": "",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node demo/server.js",
+    "dev": "node demo/server.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@simplewebauthn/server": "^13.3.0",
+    "bcrypt": "^6.0.0",
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.6",
+    "dotenv": "^17.4.1",
+    "express": "^5.2.1",
+    "express-session": "^1.19.0",
+    "helmet": "^8.1.0",
+    "otplib": "^13.4.0",
+    "qrcode": "^1.5.4",
+    "uuid": "^13.0.0"
+  }
+}