feat: Add session verification and profile caching

- Add session verification for browser and server environments
- Implement profile caching with automatic invalidation
- Add development mode logging for debugging
- Update documentation with session management details
- Add COLAB-DOCS for session management
- Bump version to 0.3.4

Author: vveerrgg

CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.4] - 2025-02-09
+
+### Added
+- Session verification support for browser environments
+- TypeScript definitions for window.nostr interface
+- Improved error handling for session verification
+
+### Changed
+- Enhanced browser compatibility checks
+- Better error messages for session-related operations
+
 ## [0.2.6] - 2023-12-05
 
 ### Added

COLAB-DOCS/SESSION-MANAGEMENT.md

@@ -0,0 +1,198 @@
+# Session Management in Nostr Auth Middleware
+
+This document outlines the session management capabilities of the Nostr Auth Middleware, including verification, caching, and development tools.
+
+## Overview
+
+Session management in Nostr applications requires careful handling of user authentication state and profile information. The middleware provides tools for:
+- Session verification
+- Profile caching
+- Development logging
+- Graceful error handling
+
+## Session Verification
+
+### Browser Environment
+
+In browser environments, session verification works by checking if:
+1. The Nostr extension is still available
+2. The user's public key matches the stored session
+3. The connection is active and valid
+
+```javascript
+const auth = new NostrAuthMiddleware();
+
+// Verify session
+const isValid = await auth.verifySession(userPubkey);
+if (!isValid) {
+  // Handle invalid session
+  await auth.logout();
+  redirectToLogin();
+}
+```
+
+### Server Environment
+
+In server environments, session verification:
+1. Validates the pubkey format
+2. Checks token expiration
+3. Verifies signature if applicable
+
+```javascript
+const auth = new NostrAuthMiddleware();
+
+app.use(async (req, res, next) => {
+  const pubkey = req.session.pubkey;
+  if (!(await auth.verifySession(pubkey))) {
+    return res.status(401).json({ error: 'Invalid session' });
+  }
+  next();
+});
+```
+
+## Profile Caching
+
+The middleware includes profile caching to improve performance:
+
+### Cache Operations
+```javascript
+// Fetch profile (uses cache if available)
+const profile = await auth.fetchNostrProfile(pubkey);
+
+// Manually clear cache
+auth.clearProfileCache(pubkey);
+```
+
+### Cache Configuration
+- Default cache duration: 1 hour
+- Automatic cache invalidation
+- Cache clearing on logout
+- Error handling for failed cache operations
+
+## Development Mode
+
+When `import.meta.env.MODE === 'development'`, the middleware provides detailed logging:
+
+### Profile Operations
+```javascript
+🔵 Cached Profile: {
+  name: "user123",
+  about: "Nostr enthusiast",
+  picture: "https://..."
+}
+
+🟢 Fresh Profile: {
+  profile: { /* profile data */ },
+  event: { /* raw nostr event */ }
+}
+```
+
+### Cache Operations
+```javascript
+🔵 Profile Cache Hit: {
+  pubkey: "npub...",
+  cacheAge: "30 minutes"
+}
+
+🔴 Profile Cache Expired: {
+  pubkey: "npub...",
+  cacheAge: "65 minutes"
+}
+
+💾 Profile Cached: {
+  pubkey: "npub...",
+  profile: { /* profile data */ }
+}
+
+🗑️ Profile Cache Cleared: {
+  pubkey: "npub..."
+}
+```
+
+## Best Practices
+
+1. **Regular Verification**
+   - Verify sessions on sensitive operations
+   - Implement periodic verification for long-lived sessions
+   - Handle verification failures gracefully
+
+2. **Cache Management**
+   - Use appropriate cache duration for your use case
+   - Clear cache on profile updates
+   - Handle cache misses gracefully
+
+3. **Error Handling**
+   - Always handle verification errors
+   - Provide clear user feedback
+   - Implement proper fallback mechanisms
+
+4. **Development**
+   - Use development mode logs for debugging
+   - Monitor cache performance
+   - Test session edge cases
+
+## Security Considerations
+
+1. **Session Storage**
+   - Use secure storage mechanisms
+   - Clear sessions on logout
+   - Implement proper session expiration
+
+2. **Profile Data**
+   - Validate cached profile data
+   - Handle missing or corrupt cache
+   - Implement proper access controls
+
+3. **Error Cases**
+   - Handle extension disconnection
+   - Manage multiple device sessions
+   - Protect against session hijacking
+
+## Example Implementation
+
+```javascript
+class AuthManager {
+  constructor() {
+    this.auth = new NostrAuthMiddleware();
+  }
+
+  async verifyUserSession(pubkey) {
+    try {
+      const isValid = await this.auth.verifySession(pubkey);
+      if (!isValid) {
+        await this.handleInvalidSession();
+        return false;
+      }
+      return true;
+    } catch (error) {
+      console.error('Session verification failed:', error);
+      return false;
+    }
+  }
+
+  async handleInvalidSession() {
+    await this.auth.logout();
+    this.auth.clearProfileCache(pubkey);
+    // Additional cleanup...
+  }
+}
+```
+
+## Troubleshooting
+
+Common issues and solutions:
+
+1. **Invalid Session**
+   - Check Nostr extension connection
+   - Verify pubkey format
+   - Check token expiration
+
+2. **Cache Issues**
+   - Clear corrupted cache
+   - Check storage limits
+   - Verify cache timing
+
+3. **Development Mode**
+   - Enable development mode for detailed logs
+   - Check browser console
+   - Monitor cache operations

README.md

@@ -163,6 +163,38 @@ const auth = new NostrAuthMiddleware({
    - Configure appropriate token expiration times
    - Implement proper error handling for token validation
 
+## Session Management
+
+### Browser Session Verification
+```javascript
+// Verify if a user's session is still valid
+const isValid = await auth.verifySession(userPubkey);
+if (isValid) {
+  console.log('Session is valid');
+} else {
+  console.log('Session is invalid or expired');
+  // Handle logout
+}
+```
+
+The session verification:
+- Checks if the Nostr extension is still available
+- Verifies the public key matches
+- Handles disconnection gracefully
+- Works in both browser and server environments
+
+### Development Mode
+When running in development mode, the middleware provides detailed logging:
+```javascript
+// Development mode logs
+Cached Profile: { /* profile data */ }
+Fresh Profile: { /* profile and event data */ }
+Profile Cache Hit: { pubkey, cacheAge }
+Profile Cache Expired: { pubkey, cacheAge }
+Profile Cached: { pubkey, profile }
+Profile Cache Cleared: { pubkey }
+```
+
 ## Documentation
 
 - [Architecture Guide](docs/architecture-guide.md) - Understanding the service architecture

package.json

@@ -1,6 +1,6 @@
 {
   "name": "nostr-auth-middleware",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "A focused, security-first authentication middleware for Nostr applications",
   "author": "vveerrgg",
   "type": "module",

src/browser/nostr-browser-auth.ts

@@ -11,7 +11,7 @@ declare global {
     nostr?: {
       getPublicKey(): Promise<string>;
       signEvent(event: NostrEvent): Promise<NostrEvent>;
-      getRelays(): Promise<{ [url: string]: { read: boolean; write: boolean } }>;
+      getRelays?(): Promise<{ [url: string]: { read: boolean; write: boolean; } }>;
       nip04?: {
         encrypt(pubkey: string, plaintext: string): Promise<string>;
         decrypt(pubkey: string, ciphertext: string): Promise<string>;

src/middleware/nostr-auth.middleware.ts

@@ -148,6 +148,27 @@ export class NostrAuthMiddleware {
     }
   }
 
+  /**
+   * Verify if a session is still valid by checking if the pubkey is still accessible
+   * @param pubkey - The public key to verify
+   * @returns Promise<boolean> - True if session is valid, false otherwise
+   */
+  async verifySession(pubkey: string): Promise<boolean> {
+    try {
+      // In browser mode, verify through extension
+      if (typeof window !== 'undefined' && window.nostr) {
+        const extensionPubkey = await window.nostr.getPublicKey();
+        return extensionPubkey === pubkey;
+      }
+      
+      // In server mode, just verify pubkey format
+      return /^[0-9a-f]{64}$/.test(pubkey);
+    } catch (error) {
+      console.error('Error verifying session:', error);
+      return false;
+    }
+  }
+
   /**
    * Gets the Express router instance
    * @returns {Router} Express router

src/types.ts

@@ -108,3 +108,18 @@ export interface VerificationResult {
   pubkey?: string;
   data?: Record<string, unknown>;
 }
+
+// Extend Window interface to include Nostr
+declare global {
+  interface Window {
+    nostr?: {
+      getPublicKey(): Promise<string>;
+      signEvent(event: NostrEvent): Promise<NostrEvent>;
+      getRelays?(): Promise<{ [url: string]: { read: boolean; write: boolean; } }>;
+      nip04?: {
+        encrypt(pubkey: string, plaintext: string): Promise<string>;
+        decrypt(pubkey: string, ciphertext: string): Promise<string>;
+      };
+    };
+  }
+}