fhirsmith 0.3.0

package/token/security_guide.md

@@ -0,0 +1,294 @@
+# Passport.js Security Implementation Guide
+
+## Overview
+
+This guide covers the security considerations and proper implementation of Passport.js OAuth authentication in the FHIR Token Server.
+
+## Key Security Features Implemented
+
+### 1. **Session Security**
+```javascript
+// Secure session configuration
+{
+  store: SQLiteStore,           // Persistent session storage
+  secret: crypto.randomBytes(64), // Strong session secret
+  name: 'fhir.token.sid',      // Custom session name (security through obscurity)
+  resave: false,               // Don't save unchanged sessions
+  saveUninitialized: false,    // Don't create sessions until something stored
+  rolling: true,               // Reset expiration on each request
+  cookie: {
+    secure: NODE_ENV === 'production', // HTTPS only in production
+    httpOnly: true,            // Prevent XSS access to cookies
+    maxAge: 24 * 60 * 60 * 1000, // 24 hour expiration
+    sameSite: 'lax'           // CSRF protection
+  }
+}
+```
+
+### 2. **CSRF Protection**
+```javascript
+// Using Lusca for comprehensive protection
+lusca({
+  csrf: true,                  // CSRF token validation
+  csp: { /* Content Security Policy */ },
+  xframe: 'SAMEORIGIN',       // Clickjacking protection
+  hsts: { maxAge: 31536000 }, // Force HTTPS
+  xssProtection: true,        // XSS header
+  nosniff: true              // MIME sniffing protection
+})
+```
+
+### 3. **Rate Limiting**
+```javascript
+// OAuth authentication rate limiting
+const authLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,   // 15 minutes
+  max: 5,                     // 5 attempts per window
+  message: 'Too many authentication attempts'
+});
+```
+
+### 4. **API Key Security**
+```javascript
+// Secure key generation and storage
+const keyData = crypto.randomBytes(32);      // Cryptographically secure
+const keyHash = await bcrypt.hash(fullKey, 12); // Strong bcrypt rounds
+const keyPrefix = 'tk_' + crypto.randomBytes(4).toString('hex'); // Identifiable prefix
+```
+
+## OAuth Provider Security
+
+### 1. **Google OAuth Configuration**
+```javascript
+// Recommended Google OAuth settings
+{
+  clientID: 'your-google-client-id',
+  clientSecret: 'your-google-client-secret',
+  callbackURL: 'https://yourdomain.com/token/callback/google', // HTTPS required
+  scope: ['openid', 'profile', 'email'], // Minimal required scopes
+  prompt: 'select_account' // Force account selection
+}
+```
+
+### 2. **Facebook OAuth Configuration**
+```javascript
+{
+  clientID: 'your-facebook-app-id',
+  clientSecret: 'your-facebook-app-secret',
+  callbackURL: 'https://yourdomain.com/token/callback/facebook',
+  profileFields: ['id', 'emails', 'name'], // Limit profile data
+  enableProof: true // App secret proof for added security
+}
+```
+
+### 3. **GitHub OAuth Configuration**
+```javascript
+{
+  clientID: 'your-github-client-id',
+  clientSecret: 'your-github-client-secret',
+  callbackURL: 'https://yourdomain.com/token/callback/github',
+  scope: ['user:email'], // Minimal scope for email access
+  userAgent: 'YourApp/1.0' // Identify your application
+}
+```
+
+## Security Audit Trail
+
+### 1. **Security Event Logging**
+All security-relevant events are logged:
+- OAuth login attempts
+- API key creation/deletion
+- Failed authentication attempts
+- Suspicious activity patterns
+
+```javascript
+await this.logSecurityEvent(userId, 'oauth_login', req.ip, req.get('User-Agent'), {
+  provider: 'google',
+  provider_id: profile.id
+});
+```
+
+### 2. **Usage Tracking**
+- Daily request counts per API key
+- IP address tracking for usage patterns
+- Anomaly detection capabilities
+
+## Production Deployment Checklist
+
+### 1. **Environment Variables**
+```bash
+# Required environment variables
+NODE_ENV=production
+SESSION_SECRET=your-super-secret-session-key-64-chars-minimum
+CSRF_SECRET=your-csrf-secret-key
+
+# OAuth Provider Credentials
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+FACEBOOK_CLIENT_ID=your-facebook-app-id
+FACEBOOK_CLIENT_SECRET=your-facebook-app-secret
+GITHUB_CLIENT_ID=your-github-client-id
+GITHUB_CLIENT_SECRET=your-github-client-secret
+```
+
+### 2. **OAuth Provider Setup**
+
+#### Google Cloud Console:
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select existing
+3. Enable Google+ API and Google OAuth2 API
+4. Go to Credentials → Create OAuth 2.0 Client ID
+5. Set authorized redirect URIs: `https://yourdomain.com/token/auth/google/callback`
+6. Configure OAuth consent screen with minimal scopes
+
+#### Facebook for Developers:
+1. Go to [Facebook for Developers](https://developers.facebook.com/)
+2. Create a new app or select existing
+3. Add Facebook Login product
+4. Configure Valid OAuth Redirect URIs: `https://yourdomain.com/token/auth/facebook/callback`
+5. Set app domain and privacy policy URL
+6. Request only `email` permission
+
+#### GitHub OAuth Apps:
+1. Go to GitHub Settings → Developer settings → OAuth Apps
+2. Create new OAuth App
+3. Set Authorization callback URL: `https://yourdomain.com/token/auth/github/callback`
+4. Configure application name and homepage URL
+
+### 3. **Database Security**
+```javascript
+// Database connection with security settings
+const db = new sqlite3.Database(dbPath, sqlite3.OPEN_READWRITE | sqlite3.OPEN_CREATE, (err) => {
+  if (err) throw err;
+  
+  // Enable foreign key constraints
+  db.run('PRAGMA foreign_keys = ON');
+  
+  // Set secure database settings
+  db.run('PRAGMA journal_mode = WAL'); // Write-Ahead Logging
+  db.run('PRAGMA synchronous = NORMAL'); // Balance performance/safety
+  db.run('PRAGMA temp_store = MEMORY'); // Store temp data in memory
+});
+```
+
+### 4. **HTTPS Configuration**
+```javascript
+// Production server setup with HTTPS
+const https = require('https');
+const fs = require('fs');
+
+const options = {
+  key: fs.readFileSync('path/to/private-key.pem'),
+  cert: fs.readFileSync('path/to/certificate.pem'),
+  // Optional: intermediate certificates
+  ca: fs.readFileSync('path/to/ca-bundle.pem')
+};
+
+https.createServer(options, app).listen(443, () => {
+  console.log('HTTPS server running on port 443');
+});
+```
+
+## Security Best Practices
+
+### 1. **API Key Management**
+- Keys are shown only once during creation
+- Keys are hashed with bcrypt (12 rounds)
+- Key prefixes allow for efficient database lookup
+- Usage tracking for anomaly detection
+- Configurable expiration dates
+- Scope-based permissions
+
+### 2. **User Session Management**
+- Sessions stored in database, not memory
+- Session rotation on privilege change
+- Automatic cleanup of expired sessions
+- Logout destroys both session and cookies
+
+### 3. **OAuth State Management**
+- CSRF protection via state parameter
+- State values are cryptographically random
+- State is validated on callback
+- Short-lived state tokens
+
+### 4. **Input Validation**
+- All inputs sanitized and validated
+- SQL injection prevention via parameterized queries
+- XSS prevention via output encoding
+- Rate limiting on all endpoints
+
+### 5. **Error Handling**
+- Generic error messages to prevent information leakage
+- Detailed logging for administrators
+- Graceful degradation on service failures
+- No sensitive data in error responses
+
+## Monitoring and Alerting
+
+### 1. **Security Events to Monitor**
+- Multiple failed authentication attempts
+- API key creation from new IP addresses
+- Unusual usage patterns
+- Session hijacking attempts
+- OAuth callback failures
+
+### 2. **Log Analysis**
+```javascript
+// Example log entries to monitor
+{
+  "level": "warn",
+  "message": "Failed authentication attempt",
+  "ip": "192.168.1.100",
+  "userAgent": "Mozilla/5.0...",
+  "provider": "google",
+  "timestamp": "2025-09-14T10:30:00Z"
+}
+```
+
+## Compliance Considerations
+
+### 1. **GDPR Compliance**
+- User consent for data processing
+- Right to data portability
+- Right to erasure (delete account)
+- Data minimization (only collect necessary data)
+- Privacy by design
+
+### 2. **HIPAA Considerations** (if handling health data)
+- Encryption at rest and in transit
+- Access logging and audit trails
+- User authentication and authorization
+- Business Associate Agreements with OAuth providers
+
+## Testing Security
+
+### 1. **Automated Security Testing**
+```javascript
+// Example security tests
+describe('OAuth Security', () => {
+  test('should reject requests without CSRF token', async () => {
+    const response = await request(app)
+      .post('/token/keys')
+      .send({ name: 'test' });
+    expect(response.status).toBe(403);
+  });
+
+  test('should rate limit authentication attempts', async () => {
+    // Make 6 failed requests
+    for (let i = 0; i < 6; i++) {
+      await request(app).get('/token/auth/google');
+    }
+    const response = await request(app).get('/token/auth/google');
+    expect(response.status).toBe(429);
+  });
+});
+```
+
+### 2. **Manual Security Testing**
+- Penetration testing of OAuth flows
+- Session management testing
+- CSRF attack simulation
+- XSS vulnerability testing
+- SQL injection testing
+
+This comprehensive security implementation ensures that your Passport.js OAuth integration follows security best practices and protects both user data and API access.

package/token/token-template.html

@@ -0,0 +1,330 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<html xml:lang="en" lang="en">
+<head>
+    <title>FHIRsmith: [%title%]</title>
+
+  <meta charset="utf-8"/>
+  <meta content="width=device-width, initial-scale=1.0" name="viewport"/>
+  <meta content="http://hl7.org/fhir" name="author"/>
+  <meta charset="utf-8" http-equiv="X-UA-Compatible" content="IE=edge" />
+
+  <link rel="stylesheet" href="/fhir.css"/>
+
+    <!-- Bootstrap core CSS -->
+  <link rel="stylesheet" href="/assets/css/bootstrap.css"/>
+  <link rel="stylesheet" href="/assets/css/bootstrap-fhir.css"/>
+
+    <!-- Project extras -->
+  <link rel="stylesheet" href="/assets/css/project.css"/>
+  <link rel="stylesheet" href="/assets/css/pygments-manni.css"/>
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!-- [if lt IE 9]>
+  <script src="/assets/js/html5shiv.js"></script>
+  <script src="/assets/js/respond.min.js"></script>
+  <![endif] -->
+
+    <!-- Favicons -->
+  <link sizes="144x144" rel="apple-touch-icon-precomposed" href="/assets/ico/apple-touch-icon-144-precomposed.png"/>
+  <link sizes="114x114" rel="apple-touch-icon-precomposed" href="/assets/ico/apple-touch-icon-114-precomposed.png"/>
+  <link sizes="72x72" rel="apple-touch-icon-precomposed" href="/assets/ico/apple-touch-icon-72-precomposed.png"/>
+  <link rel="apple-touch-icon-precomposed" href="/assets/ico/apple-touch-icon-57-precomposed.png"/>
+  <link rel="shortcut icon" href="/assets/ico/favicon.png"/>
+<script type="text/javascript" src="/assets/js/json2.js"></script>
+<script type="text/javascript" src="/assets/js/statuspage.js"></script>
+<script type="text/javascript" src="/assets/js/jquery.min.js"></script>
+<script type="text/javascript" src="/assets/js/jquery-ui.min.js"></script>
+<link rel="stylesheet" href="/assets/css/jquery.ui.all.css">
+<script type="text/javascript" src="/assets/js/jquery.ui.core.js"></script>
+<script type="text/javascript" src="/assets/js/jquery.ui.widget.js"></script>
+<script type="text/javascript" src="/assets/js/jquery.ui.mouse.js"></script>
+<script type="text/javascript" src="/assets/js/jquery.ui.resizable.js"></script>
+<script type="text/javascript" src="/assets/js/jquery.ui.draggable.js"></script>
+<script type="text/javascript" src="/assets/js/jtip.js"></script>
+<script type="text/javascript" src="/assets/js/jcookie.js"></script>
+<script type="text/javascript" src="/assets/js/fhir-gw.js"></script>
+
+<style>
+.api-key-display {
+  background: #f8f9fa;
+  border: 1px solid #dee2e6;
+  border-radius: 5px;
+  padding: 15px;
+  font-family: monospace;
+  word-break: break-all;
+  margin-bottom: 15px;
+}
+
+.usage-stats {
+  background: #e9ecef;
+  padding: 10px;
+  border-radius: 5px;
+  margin-bottom: 10px;
+}
+
+.oauth-provider {
+  display: flex;
+  align-items: center;
+  padding: 10px;
+  border: 1px solid #dee2e6;
+  border-radius: 5px;
+  margin-bottom: 10px;
+  text-decoration: none;
+  color: inherit;
+}
+
+.oauth-provider:hover {
+  background-color: #f8f9fa;
+  text-decoration: none;
+  color: inherit;
+}
+
+.oauth-icon {
+  width: 24px;
+  height: 24px;
+  margin-right: 10px;
+}
+
+.status-active { color: #198754; }
+.status-inactive { color: #6c757d; }
+
+.table-actions {
+  display: flex;
+  gap: 5px;
+}
+
+.key-warning {
+  background: #fff3cd;
+  border: 1px solid #ffeaa7;
+  border-radius: 5px;
+  padding: 15px;
+  margin-bottom: 20px;
+}
+
+.api-docs {
+  background: #f8f9fa;
+  border: 1px solid #dee2e6;
+  border-radius: 5px;
+  padding: 20px;
+  margin-top: 20px;
+}
+
+.api-endpoint {
+  background: #e9ecef;
+  padding: 8px 12px;
+  border-radius: 3px;
+  font-family: monospace;
+  font-size: 0.9em;
+  margin: 5px 0;
+}
+</style>
+
+</head>
+
+<body>
+  
+	<div id="segment-navbar" class="segment">  <!-- segment-breadcrumb -->
+		<div id="stripe"> </div>
+		<div class="container">  <!-- container -->
+		<div style="background-color: #ad1f2f; padding: 6px; color: white;">  <!-- container -->
+  <a href="http://www.hl7.org/fhir" style="color: gold" title="Fast Healthcare Interoperability Resources - Home Page"><img border="0" src="/icon-fhir-16.png" style="vertical-align: text-bottom"/> <b>FHIR</b></a> &copy; HL7.org &nbsp;|&nbsp;
+  <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" style="vertical-align: text-bottom"/> FHIRsmith</a> [%ver%] &nbsp;|&nbsp;
+  <a href="/" style="color: gold"> Server Home</a> &nbsp;|&nbsp;
+  <a href="/token" style="color: gold">Token Home</a> 
+		</div>  <!-- /container -->
+		</div>  <!-- /container -->
+</div>
+
+	<!-- /segment-breadcrumb -->
+
+	<div id="segment-content" class="segment">  <!-- segment-content -->
+	<div class="container">  <!-- container -->
+            <div class="row">
+            	<div class="inner-wrapper">
+ <div class="col-9">
+
+  <h2><img border="0" src="../FHIRsmith32.png" style="vertical-align: text-bottom"/> Token Server: [%title%] </h2>
+
+[%content%]
+
+<div class="api-docs">
+  <h4>API Documentation</h4>
+  <p>Use these endpoints to validate and track API key usage:</p>
+  
+  <div class="mb-3">
+    <strong>Validate API Key:</strong>
+    <div class="api-endpoint">GET /token/api/validate/{api_key}</div>
+    <p>Returns user information and allowed request count.</p>
+  </div>
+  
+  <div class="mb-3">
+    <strong>Record Usage:</strong>
+    <div class="api-endpoint">POST /token/api/usage/{api_key}</div>
+    <p>Records API usage. Send <code>{"count": 1}</code> in request body.</p>
+  </div>
+  
+  <div class="mb-3">
+    <strong>Get Usage Statistics:</strong>
+    <div class="api-endpoint">GET /token/api/stats/{api_key}?days=30</div>
+    <p>Returns usage statistics for the specified number of days.</p>
+  </div>
+</div>
+
+ </div>
+
+				</div>  <!-- /inner-wrapper -->
+            </div>  <!-- /row -->
+        </div>  <!-- /container -->
+    </div>  <!-- /segment-content -->
+
+	<div id="segment-footer" class="segment">  <!-- segment-footer -->
+		<div class="container">  <!-- container -->
+			<div class="inner-wrapper">
+				<p>
+                    <a href="http://www.hl7.org/fhir" style="color: gold" title="Fast Healthcare Interoperability Resources - Home Page"><img border="0" src="/icon-fhir-16.png" style="vertical-align: text-bottom"/> <b>FHIR</b></a> &copy; HL7.org 2011+.  &nbsp;|&nbsp;
+                    <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" style="vertical-align: text-bottom"/> FHIRsmith</a>  [%ver%]  &copy; HealthIntersections.com.au 2023+ &nbsp;|&nbsp;
+                     ([%ms%] ms)
+
+        </p>
+			</div>  <!-- /inner-wrapper -->
+		</div>  <!-- /container -->
+	</div>  <!-- /segment-footer -->
+
+	<div id="segment-post-footer" class="segment hidden">  <!-- segment-post-footer -->
+		<div class="container">  <!-- container -->
+		</div>  <!-- /container -->
+	</div>  <!-- /segment-post-footer -->
+
+      <!-- JS and analytics only. -->
+      <!-- Bootstrap core JavaScript
+================================================== -->
+  <!-- Placed at the end of the document so the pages load faster -->
+<script src="/assets/js/bootstrap.min.js"></script>
+<script src="/assets/js/respond.min.js"></script>
+<script src="/assets/js/fhir.js"></script>
+
+<script>
+// Handle API key creation
+document.addEventListener('DOMContentLoaded', function() {
+  const createForm = document.getElementById('create-key-form');
+  if (createForm) {
+    createForm.addEventListener('submit', async function(e) {
+      e.preventDefault();
+      const formData = new FormData(e.target);
+      
+      try {
+        const response = await fetch('/token/keys', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ name: formData.get('name') })
+        });
+        
+        const result = await response.json();
+        
+        if (response.ok) {
+          // Show the API key in a modal or alert
+          showApiKeyModal(result.apiKey);
+          
+          // Reset form and optionally reload
+          e.target.reset();
+          setTimeout(() => location.reload(), 2000);
+        } else {
+          alert('Error: ' + result.error);
+        }
+      } catch (error) {
+        alert('Error creating key: ' + error.message);
+      }
+    });
+  }
+});
+
+// Show API key in a modal (you might want to use Bootstrap modal instead)
+function showApiKeyModal(apiKey) {
+  const modal = document.createElement('div');
+  modal.innerHTML = `
+    <div style="position: fixed; top: 0; left: 0; width: 100%; height: 100%; background: rgba(0,0,0,0.5); z-index: 1000; display: flex; justify-content: center; align-items: center;">
+      <div style="background: white; padding: 30px; border-radius: 10px; max-width: 600px; width: 90%;">
+        <h4>API Key Created Successfully</h4>
+        <div class="key-warning">
+          <strong>Important:</strong> Please save this API key now. You won't be able to see it again!
+        </div>
+        <div class="api-key-display">
+          <strong>Your API Key:</strong><br>
+          ${apiKey}
+        </div>
+        <button onclick="copyToClipboard('${apiKey}')" class="btn btn-secondary me-2">Copy Key</button>
+        <button onclick="closeModal()" class="btn btn-primary">Close</button>
+      </div>
+    </div>
+  `;
+  
+  document.body.appendChild(modal);
+  
+  // Auto-close after 30 seconds
+  setTimeout(() => {
+    if (document.body.contains(modal)) {
+      document.body.removeChild(modal);
+    }
+  }, 30000);
+}
+
+function closeModal() {
+  const modal = document.querySelector('[style*="position: fixed"]');
+  if (modal) {
+    document.body.removeChild(modal);
+  }
+}
+
+function copyToClipboard(text) {
+  navigator.clipboard.writeText(text).then(function() {
+    alert('API key copied to clipboard!');
+  }).catch(function(err) {
+    console.error('Could not copy text: ', err);
+    // Fallback for older browsers
+    const textArea = document.createElement('textarea');
+    textArea.value = text;
+    document.body.appendChild(textArea);
+    textArea.select();
+    document.execCommand('copy');
+    document.body.removeChild(textArea);
+    alert('API key copied to clipboard!');
+  });
+}
+
+// Handle key deletion
+async function deleteKey(keyId) {
+  if (!confirm('Are you sure you want to delete this API key? This action cannot be undone.')) {
+    return;
+  }
+  
+  try {
+    const response = await fetch('/token/keys/' + keyId, {
+      method: 'DELETE'
+    });
+    
+    if (response.ok) {
+      location.reload();
+    } else {
+      const result = await response.json();
+      alert('Error: ' + result.error);
+    }
+  } catch (error) {
+    alert('Error deleting key: ' + error.message);
+  }
+}
+
+// Form validation
+function validateKeyForm(form) {
+  const nameInput = form.querySelector('input[name="name"]');
+  if (!nameInput.value.trim()) {
+    alert('Please enter a name for your API key');
+    nameInput.focus();
+    return false;
+  }
+  return true;
+}
+</script>
+
+</body>
+</html>