@javagt/express-easy-auth 1.0.0

package/readme.md

@@ -0,0 +1,165 @@
+# Express Auth Service (Library)
+
+**Express Auth Service** is a modular, professional-grade authentication and session management library for Node.js/Express. It provides a complete identity solution with a focus on modern security (Passkeys) and developer experience.
+
+- **🚀 Passkeys (WebAuthn)**: Passwordless biometric authentication (TouchID, FaceID).
+- **🛡️ TOTP 2FA**: Google Authenticator, Authy, and hardware token support.
+- **🔑 API Key Management**: Per-user API keys with granular permissions for programmatic access.
+- **💾 Session Store**: Secure, ACID-compliant SQLite-backed session management.
+- **🔒 Fresh Auth**: Middleware to require recent re-authentication for sensitive actions.
+- **📜 System Logs**: Built-in diagnostics and activity logging.
+
+---
+
+## 🚀 5-Minute Quickstart
+
+### 1. Install
+```bash
+npm install auth-server
+```
+
+### 2. Initialize
+```javascript
+import express from 'express';
+import { setupAuth, authRouter } from 'auth-server';
+
+const app = express();
+app.use(express.json());
+
+setupAuth(app, {
+  dataDir: './data',
+  config: { 
+    domain: 'localhost',
+    rpName: 'My Auth App',
+    rpID: 'localhost',
+    origin: 'http://localhost:3000'
+  }
+});
+
+// Standard mounting pattern
+app.use('/api/v1/auth', authRouter);
+app.listen(3000);
+```
+
+### 3. Protect
+```javascript
+import { requireAuth } from 'auth-server';
+
+app.get('/dashboard', requireAuth, (req, res) => {
+  res.json({ message: `Hello User ${req.userId}` });
+});
+```
+
+---
+
+## 🌐 Frontend SDK
+
+The library hosts its own lightweight SDK at `/auth-sdk.js` (can be customized). No installation required.
+
+```html
+<script type="module">
+  import { AuthClient } from '/auth-sdk.js';
+  const auth = new AuthClient();
+  
+  // High-level ceremonies
+  await auth.loginWithPasskey();
+  await auth.registerPasskey('My Mac');
+  
+  // Standard methods
+  const status = await auth.getStatus();
+</script>
+```
+
+---
+
+## 📖 Features & Documentation
+
+### 🛡️ Multi-Factor Auth (TOTP)
+Users can enable TOTP 2FA for an extra layer of security.
+- **Setup**: `POST /api/v1/auth/2fa/setup`
+- **Verify**: `POST /api/v1/auth/2fa/verify-setup`
+- [View Example: TOTP Setup](examples/04-totp-setup.js)
+
+### 🏎️ Passkeys (WebAuthn)
+Full WebAuthn support including discovery and residency.
+- **Integration**: Use `AuthClient.loginWithPasskey()` and `AuthClient.registerPasskey()`.
+- [View Example: Passkey Ceremony](examples/02-passkeys.js)
+
+### 🔑 Programmatic Access (API Keys)
+Allow users to create and manage their own API keys for your service.
+- **Middleware**: Use `requireApiKey` to protect machine-to-machine routes.
+- **Permissions**: Supports `action:read` and `action:write`.
+- [View Example: API Key Integration](examples/03-api-keys.js)
+
+### 🔗 Linking to your Application Database
+**Auth-server** is designed to be a standalone identity provider. It does not store application-specific data (like bios or preferences). Instead, you should link your application database to the `userId` provided by the library.
+
+**Pattern:**
+1. Use `requireAuth` to get `req.userId`.
+2. Query your own database using that ID.
+
+[View full example of linking databases](examples/08-external-db-linking.js)
+
+### 📜 Logging & Debugging
+The library provides a flexible logging system and explicit control over error exposure.
+- **`exposeErrors`**: Boolean flag to toggle detailed error messages in the API responses. Recommended to set to `process.env.NODE_ENV !== 'production'`.
+- **Custom Logger**: Plug in your own logger (e.g., Winston, Pino) by passing it to `setupAuth`.
+- [View Example: Custom Logger](examples/05-custom-logger.js)
+
+---
+
+## 📜 API Reference
+
+### Backend API (V1)
+All identity endpoints are nested under the router (recommended path: `/api/v1/auth`).
+
+| Category | Method | Path | Auth | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| **Auth** | POST | `/login` | — | Login with password |
+| | POST | `/register` | — | Create account |
+| | POST | `/logout` | ✓ | Destroy session |
+| | GET | `/status` | — | Check session status |
+| **2FA** | POST | `/2fa/setup` | ✓ | Generate TOTP secret |
+| | POST | `/2fa/verify-setup` | ✓ | Enable 2FA after verification |
+| | POST | `/2fa/disable` | ✓ (Fresh) | Disable TOTP |
+| **Passkeys** | POST | `/passkeys/register/options` | ✓ | Get registration options |
+| | POST | `/passkeys/register/verify` | ✓ | Verify and save passkey |
+| | POST | `/passkeys/authenticate/options` | — | Get login options |
+| | POST | `/passkeys/authenticate/verify` | — | Verify passkey login |
+| | GET | `/passkeys` | ✓ | List registered passkeys |
+| | DELETE | `/passkeys/:id` | ✓ | Delete a passkey |
+| **Password Reset** | POST | `/password-reset/request` | — | Generate reset token |
+| | POST | `/password-reset/reset` | — | Complete reset |
+| **API Keys** | GET | `/api-keys` | ✓ | List user API keys |
+| | POST | `/api-keys` | ✓ | Create new API key |
+| | DELETE | `/api-keys/:id` | ✓ | Revoke API key |
+
+### Frontend SDK (AuthClient)
+The SDK is available at `/auth-sdk.js`.
+
+#### Methods
+- `client.login(username, password)`: Manual login.
+- `client.register(username, email, password)`: Manual registration.
+- `client.logout()`: Logout.
+- `client.getStatus()`: Get authentication and security status.
+- `client.loginWithPasskey(username?)`: Biometric login.
+- `client.registerPasskey(name)`: Register a biometric key.
+- `client.createApiKey(name, permissions)`: Generate a new API key.
+- `client.listApiKeys()`: List keys.
+- `client.reportError(err, context)`: Report client-side errors to server.
+
+## Examples
+The `examples/` directory contains standalone, documented reference implementations.
+
+1. `01-basic-setup.js`: Minimal Express integration.
+2. `02-passkeys.js`: WebAuthn registration and login.
+3. `03-api-keys.js`: Service-to-service authentication.
+4. `04-totp-setup.js`: TOTP 2FA lifecycle.
+5. `05-custom-logger.js`: Injecting a custom logger.
+6. `06-password-reset.js`: Full password recovery flow.
+7. `08-external-db-linking.js`: Linking to your own application database.
+
+---
+
+## License
+MIT

package/scratch/debug_bindings.js

@@ -0,0 +1,29 @@
+import { DatabaseSync } from 'node:sqlite';
+const db = new DatabaseSync(':memory:');
+db.exec('CREATE TABLE test (a TEXT, b TEXT)');
+const p1 = 'val1';
+const p2 = undefined;
+
+try {
+    // This represents my "fix" that failed
+    db.prepare('SELECT * FROM test WHERE a=? AND b=?').get([p1 || null, p2 || null]);
+    console.log('Array format worked');
+} catch (e) {
+    console.error('Array format failed:', e.message);
+}
+
+try {
+    // This represents the original problematic call
+    db.prepare('SELECT * FROM test WHERE a=? AND b=?').get(p1, p2);
+    console.log('Positional with undefined worked');
+} catch (e) {
+    console.error('Positional with undefined failed:', e.message);
+}
+
+try {
+    // This represents the REAL fix
+    db.prepare('SELECT * FROM test WHERE a=? AND b=?').get(p1 || null, p2 || null);
+    console.log('Positional with null fallback worked');
+} catch (e) {
+    console.error('Positional with null fallback failed:', e.message);
+}

package/scratch/test_sqlite.js

@@ -0,0 +1,7 @@
+import { DatabaseSync } from 'node:sqlite';
+const db = new DatabaseSync(':memory:');
+db.exec('CREATE TABLE test (a TEXT, b TEXT)');
+db.prepare('INSERT INTO test (a, b) VALUES (?, ?)').run('val1', 'val2');
+console.log('Single run with multiple args finished');
+const row = db.prepare('SELECT * FROM test WHERE a=? AND b=?').get('val1', 'val2');
+console.log('Result:', row);

package/scratch/test_sqlite_multargs.js

@@ -0,0 +1,17 @@
+import { DatabaseSync } from 'node:sqlite';
+const db = new DatabaseSync(':memory:');
+db.exec('CREATE TABLE test (a TEXT, b TEXT)');
+// This SHOULD fail if it only takes one argument because ? ? needs two values
+try {
+    db.prepare('INSERT INTO test (a, b) VALUES (?, ?)').run('a', 'b');
+    console.log('Run with 2 args succeeded (Wait, how?)');
+} catch (e) {
+    console.error('Run with 2 args failed:', e.message);
+}
+
+try {
+    const row = db.prepare('SELECT * FROM test WHERE a=? AND b=?').get('a', 'b');
+    console.log('Get with 2 args returned:', row);
+} catch (e) {
+    console.error('Get with 2 args failed:', e.message);
+}

package/scratch/test_sqlite_undefined.js

@@ -0,0 +1,9 @@
+import { DatabaseSync } from 'node:sqlite';
+const db = new DatabaseSync(':memory:');
+db.exec('CREATE TABLE test (a TEXT, b TEXT)');
+try {
+    db.prepare('SELECT * FROM test WHERE a=? AND b=?').get('val1', undefined);
+    console.log('Finished with undefined');
+} catch (e) {
+    console.error('Error with undefined:', e);
+}

package/scratch/verify_sqlite_fix.js

@@ -0,0 +1,14 @@
+import { DatabaseSync } from 'node:sqlite';
+const db = new DatabaseSync(':memory:');
+db.exec('CREATE TABLE users (id TEXT, username TEXT, email TEXT)');
+const username = 'testuser';
+const email = undefined;
+
+// This mimics the problematic call
+try {
+    const user = db.prepare('SELECT * FROM users WHERE username=? OR email=?').get([username || null, email || null]);
+    console.log('Final verification: Array format with null fallbacks succeeded!');
+    console.log('Result:', user);
+} catch (e) {
+    console.error('Final verification failed:', e.message);
+}

package/src/client.js

@@ -0,0 +1,295 @@
+/**
+ * AuthClient - Frontend SDK for Auth Server
+ * 
+ * This library handles authentication ceremonies, including WebAuthn (Passkeys),
+ * TOTP 2FA, and session management.
+ */
+
+export class AuthClient {
+  /**
+   * @param {Object} options
+   * @param {string} [options.baseUrl] - The base URL for the API (default: '/api')
+   * @param {string} [options.apiVersion] - The API version (default: 'v1')
+   */
+  constructor(options = {}) {
+    this.baseUrl = options.baseUrl || '/api';
+    this.apiVersion = options.apiVersion || 'v1';
+    this.apiPrefix = `${this.baseUrl}/${this.apiVersion}/auth`;
+  }
+
+  // ─── PRIVATE HELPERS ────────────────────────────────────────────────────────
+
+  /**
+   * Standard fetch wrapper with error handling
+   * @param {string} path - The API path (relative to /auth or /v1)
+   * @param {Object} [options] - Fetch options
+   */
+  /**
+   * Standard fetch wrapper with error handling
+   * @param {string} path - The API path (relative to /auth or /v1)
+   * @param {Object} [options] - Fetch options
+   */
+  async request(path, options = {}) {
+    // Standardize path: remove redundant prefixes if they exist
+    let cleanPath = path
+      .replace(/^\/?api\/v1\/auth/, '')
+      .replace(/^\/?api\/v1/, '')
+      .replace(/^\/?auth/, '')
+      .replace(/^\//, '');
+    
+    const url = `${this.apiPrefix}/${cleanPath}`;
+
+    const res = await fetch(url, {
+      headers: {
+        'Content-Type': 'application/json',
+        ...(options.headers || {}),
+      },
+      credentials: 'same-origin',
+      ...options,
+      body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw Object.assign(new Error(data.error || 'Request failed'), {
+        code: data.code,
+        status: res.status,
+        data,
+      });
+    }
+    return data;
+  }
+
+  _base64urlToBuffer(base64url) {
+    const base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = base64.length % 4;
+    const padded = pad ? base64 + '='.repeat(4 - pad) : base64;
+    const binary = window.atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return bytes.buffer;
+  }
+
+  _bufferToBase64url(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+    const base64 = window.btoa(binary);
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+  }
+
+  // ─── AUTH METHODS ──────────────────────────────────────────────────────────
+
+  async getStatus() {
+    return this.request('/status');
+  }
+
+  async login(username, password, totp) {
+    return this.request('/login', {
+      method: 'POST',
+      body: { username, password, totp: totp || undefined },
+    });
+  }
+
+  async register(username, email, password) {
+    return this.request('/register', {
+      method: 'POST',
+      body: { username, email, password },
+    });
+  }
+
+  async logout() {
+    return this.request('/logout', { method: 'POST' });
+  }
+
+  async changePassword(newPassword, token) {
+    return this.request('/change-password', {
+      method: 'POST',
+      body: { newPassword, token }
+    });
+  }
+
+  // ─── PASSKEY METHODS ────────────────────────────────────────────────────────
+
+  async registerPasskey(name = 'My Device') {
+    if (!window.PublicKeyCredential) throw new Error('WebAuthn not supported');
+    const opts = await this.request('/passkeys/register/options', { method: 'POST' });
+    const creationOptions = {
+      ...opts,
+      challenge: this._base64urlToBuffer(opts.challenge),
+      user: { ...opts.user, id: this._base64urlToBuffer(opts.user.id) },
+      excludeCredentials: (opts.excludeCredentials || []).map(c => ({
+        ...c, id: this._base64urlToBuffer(c.id)
+      })),
+    };
+    const cred = await navigator.credentials.create({ publicKey: creationOptions });
+    const response = {
+      id: cred.id,
+      rawId: this._bufferToBase64url(cred.rawId),
+      type: cred.type,
+      response: {
+        clientDataJSON: this._bufferToBase64url(cred.response.clientDataJSON),
+        attestationObject: this._bufferToBase64url(cred.response.attestationObject),
+        transports: cred.response.getTransports ? cred.response.getTransports() : [],
+      },
+    };
+    return this.request('/passkeys/register/verify', {
+      method: 'POST',
+      body: { response, name },
+    });
+  }
+
+  async loginWithPasskey(username) {
+    if (!window.PublicKeyCredential) throw new Error('WebAuthn not supported');
+    const opts = await this.request('/passkeys/authenticate/options', {
+      method: 'POST',
+      body: { username },
+    });
+    const requestOptions = {
+      ...opts,
+      challenge: this._base64urlToBuffer(opts.challenge),
+      allowCredentials: (opts.allowCredentials || []).map(c => ({
+        ...c, id: this._base64urlToBuffer(c.id)
+      })),
+    };
+    const cred = await navigator.credentials.get({ publicKey: requestOptions });
+    const response = {
+      id: cred.id,
+      rawId: this._bufferToBase64url(cred.rawId),
+      type: cred.type,
+      response: {
+        clientDataJSON: this._bufferToBase64url(cred.response.clientDataJSON),
+        authenticatorData: this._bufferToBase64url(cred.response.authenticatorData),
+        signature: this._bufferToBase64url(cred.response.signature),
+        userHandle: cred.response.userHandle ? this._bufferToBase64url(cred.response.userHandle) : null,
+      },
+    };
+    return this.request('/passkeys/authenticate/verify', {
+      method: 'POST',
+      body: { response },
+    });
+  }
+
+  async listPasskeys() {
+    return this.request('/passkeys');
+  }
+
+  async deletePasskey(id) {
+    return this.request(`/passkeys/${id}`, { method: 'DELETE' });
+  }
+
+  // ─── SESSION METHODS ────────────────────────────────────────────────────────
+
+  async listSessions() {
+    return this.request('/sessions');
+  }
+
+  async revokeSession(id) {
+    return this.request(`/sessions/${id}`, { method: 'DELETE' });
+  }
+
+  // ─── API KEY METHODS ────────────────────────────────────────────────────────
+
+  async listApiKeys() {
+    return this.request('/api-keys');
+  }
+
+  async createApiKey(name, permissions) {
+    return this.request('/api-keys', {
+      method: 'POST',
+      body: { name, permissions }
+    });
+  }
+
+  async deleteApiKey(id) {
+    return this.request(`/api-keys/${id}`, { method: 'DELETE' });
+  }
+
+  // ─── 2FA METHODS ────────────────────────────────────────────────────────────
+
+  /**
+   * Start 2FA (TOTP) setup
+   */
+  async setup2FA() {
+    return this.request('/2fa/setup', { method: 'POST' });
+  }
+
+  /**
+   * Verify and enable 2FA
+   */
+  async verify2FASetup(token) {
+    return this.request('/2fa/verify-setup', {
+      method: 'POST',
+      body: { token },
+    });
+  }
+
+  /**
+   * Disable 2FA
+   * @param {string} password - Required for security
+   * @param {string} [token] - Optional current code
+   */
+  async disable2FA(password, token) {
+    return this.request('/2fa/disable', {
+      method: 'POST',
+      body: { password, token },
+    });
+  }
+
+  // ─── UTIL METHODS ───────────────────────────────────────────────────────────
+
+  /**
+   * Report an error to the server's system logs
+   */
+  async reportError(error, context = {}) {
+    const isString = typeof error === 'string';
+    const message = isString ? error : (error.message || String(error));
+    const stack = isString ? null : (error.stack || null);
+
+    return this.request('/report-error', {
+      method: 'POST',
+      body: { level: 'error', message, stack, context },
+    }).catch(e => console.warn('[Auth SDK] Failed to report error:', e));
+  }
+
+  // ─── PASSWORD RESET METHODS ──────────────────────────────────────────────────
+
+  /**
+   * Request a password reset token
+   * @param {string} identity - Username or email
+   */
+  async forgotPassword(identity) {
+    return this.request('/password-reset/request', {
+      method: 'POST',
+      body: { username: identity, email: identity }
+    });
+  }
+
+  /**
+   * Reset password using a token
+   * @param {string} token - The reset token
+   * @param {string} newPassword - The new password
+   */
+  async resetPassword(token, newPassword) {
+    return this.request('/password-reset/reset', {
+      method: 'POST',
+      body: { token, newPassword }
+    });
+  }
+
+  /**
+   * Sync passkeys with device (conditional UI / Signal API)
+   */
+  async syncPasskeys(credentialIds) {
+    if (!window.PublicKeyCredential || !PublicKeyCredential.signalAllAcceptedCredentials) {
+      return { supported: false };
+    }
+    try {
+      const ids = credentialIds.map(id => this._base64urlToBuffer(id));
+      await PublicKeyCredential.signalAllAcceptedCredentials({ credentialIds: ids });
+      return { supported: true, success: true };
+    } catch (err) {
+      return { supported: true, success: false, error: err };
+    }
+  }
+}