nostr-auth-middleware 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+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.2.6] - 2023-12-05
+
+### Added
+- New TypeScript interfaces in `interfaces/nostr.interface.ts` for better type safety
+- More comprehensive event validation with detailed error messages
+
+### Enhanced
+- Improved event validation with stricter type checking
+- Better error handling and logging in event validator
+- Updated to use latest crypto utilities
+
+## [0.2.5] - 2024-01-09
+
+### Changed
+- Updated to use published versions of @humanjavaenterprises/nostr-crypto-utils@0.2.0 and @humanjavaenterprises/nostr-nsec-seedphrase-library@0.2.0
+- Updated key generation to use new generateKeyPairWithSeed function from nostr-nsec-seedphrase-library
+
+## [0.2.3] - 2023-12-06
+
+### Added
+- Comprehensive test suite with 94.8% coverage
+- Tests for challenge generation and verification
+- Tests for profile fetching
+- Tests for enrollment and verification
+- Tests for error handling
+- Tests for router integration
+
+### Changed
+- Updated README with testing documentation
+- Improved error handling in middleware
+- Enhanced TypeScript type safety
+
+## [0.2.2] - Previous Release
+
+### Added
+- Initial implementation of Nostr authentication middleware
+- NIP-07 compatible authentication
+- Secure user enrollment with Nostr
+- Comprehensive event validation
+- Advanced cryptographic operations
+- Supabase integration for data persistence
+- JWT-based session management

package/COLAB-DOCS/DEVELOPMENT.md

@@ -0,0 +1,203 @@
+# Development Guide
+
+## Strategy and Architecture
+
+### Purpose
+This document outlines the key architectural decisions, development patterns, and modernization strategies for the nostr-auth-middleware project. It serves as a living document to help maintain consistency across development sessions and preserve the reasoning behind important technical decisions.
+
+### Core Architecture Principles
+
+#### 1. Single Responsibility
+- **Authentication Only**: Middleware focuses solely on Nostr key-based authentication
+- **No Business Logic**: Business rules, user tiers, and application logic belong in the API layer
+- **Simple JWT**: Issues basic JWTs with minimal claims (npub, timestamp)
+
+#### 2. Security First
+- **Open Source**: Fully auditable security-critical code
+- **Transparent**: Clear, readable implementation
+- **Focused Scope**: Does one thing well - Nostr authentication
+
+#### 3. Integration Architecture
+```plaintext
+┌─────────────────┐
+│   Client App    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Nostr Auth     │ ◄── This Service
+│   Service       │     Simple Auth Only
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  App Platform   │ ◄── Your Business Logic
+│     API         │     User Tiers
+└─────────────────┘     Rate Limits
+```
+
+#### 4. Environment-Aware Design
+##### Development Mode Features
+- Local directory structure
+- Auto-generated test keys
+- In-memory data storage option
+- Hot-reloading enabled
+- Detailed logging
+- No root permissions required
+
+##### Production Mode Features
+- System-level directory structure
+- Secure key management via Supabase
+- Proper file permissions
+- Log rotation and compression
+- Automatic backups
+- Rate limiting
+- IP whitelisting
+
+## Development Checklist
+
+### Version Requirements
+- [ ] Specify Node.js version requirements:
+  ```json
+  {
+    "engines": {
+      "node": ">=18.0.0"  // Only support active LTS versions
+    }
+  }
+  ```
+- [ ] Document version requirements in README.md
+- [ ] Configure CI to test only supported versions
+- [ ] Remove legacy version support and polyfills
+
+### Package Configuration
+- [ ] Configure package.json exports properly:
+  ```json
+  {
+    "exports": {
+      ".": {
+        "types": "./dist/types/index.d.ts",  // Types must come first
+        "import": "./dist/esm/index.js",
+        "require": "./dist/cjs/index.js"
+      }
+    }
+  }
+  ```
+- [ ] Include standard fields at root level:
+  - [ ] "main" for CommonJS entry
+  - [ ] "module" for ESM entry
+  - [ ] "types" for TypeScript types
+  - [ ] "browser" for browser bundles
+
+### Module System Strategy
+
+#### Hybrid Module Support (ESM/CommonJS)
+- Package supports both ESM and CommonJS through dual publishing
+- Entry points defined in package.json:
+  ```json
+  {
+    "main": "./dist/cjs/index.js",    // CommonJS
+    "module": "./dist/esm/index.js",  // ESM
+    "types": "./dist/types/index.d.ts" // TypeScript
+  }
+  ```
+- Browser bundle available at `dist/browser/nostr-auth-middleware.min.js`
+
+#### TypeScript Declaration Patterns
+- Browser-specific declarations in `browser.d.ts` follow top-level pattern:
+  ```typescript
+  // Define interfaces and types at top level
+  interface NostrAuthConfig { ... }
+  interface NostrEvent { ... }
+  
+  // Declare classes at top level
+  declare class NostrAuthClient { ... }
+  
+  // Global augmentations after type definitions
+  declare global {
+    interface Window {
+      NostrAuthMiddleware: typeof NostrAuthClient;
+    }
+  }
+  
+  // Single export at the end
+  export = NostrAuthClient;
+  ```
+- Avoid module augmentation blocks (`declare module`) in browser declarations
+- Keep type definitions close to their implementation files
+
+### Build Configuration
+
+#### TypeScript Configuration
+- [ ] Use `NodeNext` for both `module` and `moduleResolution` in tsconfig.json
+- [ ] Include `tslib` in dependencies for TypeScript helpers
+- [ ] Use `.js` extensions in import statements (TypeScript convention for ESM)
+- [ ] Configure separate tsconfig files for different build targets (browser, CJS, ESM)
+- [ ] Handle type definitions:
+  - [ ] Consider inlining small type definitions instead of separate files
+  - [ ] Use declaration merging for global types (e.g., window object)
+
+#### Webpack Configuration
+- [ ] Configure proper module resolution:
+  - [ ] Add `.js` extension alias for `.ts` files
+  - [ ] Handle `.d.ts` files appropriately (use ignore-loader)
+  - [ ] Set up Node.js polyfills or fallbacks for browser environment
+- [ ] Configure TypeScript loader:
+  - [ ] Use `ts-loader` with appropriate options
+  - [ ] Enable `transpileOnly` for faster builds
+  - [ ] Set correct module resolution strategy
+- [ ] Handle external dependencies properly:
+  - [ ] Mark Node.js-only packages as external
+  - [ ] Configure fallbacks for Node.js core modules
+
+### Build Process
+- [ ] Test builds before committing changes:
+  ```bash
+  npm run build && npm test
+  ```
+- [ ] Verify all build targets work:
+  - [ ] TypeScript declarations
+  - [ ] CommonJS build
+  - [ ] ESM build
+  - [ ] Browser bundle
+- [ ] Check bundle size and consider optimizations if needed
+- [ ] Ensure source maps are generated correctly
+
+### Testing
+- [ ] Configure test environment properly:
+  - [ ] Set up test globals
+  - [ ] Configure coverage reporting
+  - [ ] Ensure tests run in both ESM and CommonJS environments
+- [ ] Test browser bundle in different environments
+- [ ] Run tests across supported Node.js versions
+- [ ] Verify package exports work in different environments
+
+### Development Workflow
+- [ ] Run builds and tests before committing changes
+- [ ] Update documentation when making significant changes
+- [ ] Keep track of bundle size and performance impacts
+- [ ] Document any workarounds or special configurations
+
+### Browser Integration
+- [ ] Test browser bundle in different environments
+- [ ] Verify global object access works correctly
+- [ ] Check for any Node.js-specific code that needs browser alternatives
+- [ ] Ensure proper error handling for browser-specific features
+
+### Dependencies
+- [ ] Keep dependencies up to date
+- [ ] Document any specific version requirements
+- [ ] Consider the impact of dependencies on bundle size
+- [ ] Use appropriate dependency types (dependencies vs devDependencies)
+- [ ] Include necessary TypeScript helpers (e.g., tslib)
+
+### Common Issues and Solutions
+
+#### Type assertions and casting:
+- [ ] Avoid using `as unknown as Type` when possible
+- [ ] Create proper type guards for runtime checks
+- [ ] Use type predicates for narrowing types
+
+#### External library types:
+- [ ] Maintain proper type definitions for external libraries
+- [ ] Use declaration merging for extending third-party types
+- [ ] Document any type-related workarounds or limitations

package/COLAB-DOCS/WORKING-WITH-AI.md

@@ -0,0 +1,178 @@
+# Working with AI: Collaborative Development Guide
+
+## Introduction
+
+This guide outlines best practices for collaborating with AI Language Models (LLMs) in software development, based on our successful experience building the nostr-auth-middleware package. It aims to help developers maximize the benefits of AI pair programming while maintaining code quality and security.
+
+## Key Principles
+
+### 1. Iterative Development
+- Start with small, well-defined tasks
+- Build incrementally with continuous validation
+- Let the AI help refactor and improve code quality
+- Use the AI to help maintain consistency across the codebase
+
+### 2. Clear Communication
+- Be specific about requirements and constraints
+- Share context about the broader system
+- Ask for explanations when changes aren't clear
+- Use the AI to document decisions and rationale
+
+### 3. Quality Control
+- Always review AI-generated code
+- Run tests after each significant change
+- Use the AI to help write and improve tests
+- Let the AI help with code reviews
+
+## Effective Collaboration Patterns
+
+### 1. Setting Up the Project
+```markdown
+Good: "Let's set up a TypeScript project with ESM and CommonJS support, including proper build configuration."
+Bad: "Create a new project for me."
+```
+
+### 2. Implementing Features
+```markdown
+Good: "We need to implement JWT token generation with these specific claims: [x, y, z]"
+Bad: "Add authentication to the project"
+```
+
+### 3. Testing and Debugging
+```markdown
+Good: "These specific tests are failing with this error message: [error]. Can you help debug?"
+Bad: "Fix the tests"
+```
+
+## Best Practices
+
+### 1. Documentation
+- Have the AI help maintain documentation alongside code changes
+- Use the AI to generate detailed comments and JSDoc
+- Ask the AI to explain complex parts of the codebase
+- Keep a record of architectural decisions
+
+### 2. Code Quality
+- Use the AI to identify potential improvements
+- Ask for suggestions on code organization
+- Have the AI help with type definitions
+- Use the AI to ensure consistent coding style
+
+### 3. Testing
+- Let the AI help write comprehensive tests
+- Use the AI to identify edge cases
+- Have the AI help with test organization
+- Ask for help with test coverage improvements
+
+## Common Pitfalls to Avoid
+
+### 1. Over-Reliance
+- Don't accept AI suggestions without review
+- Maintain understanding of your codebase
+- Keep security-critical decisions human-reviewed
+- Verify generated code meets requirements
+
+### 2. Unclear Requirements
+- Avoid vague or ambiguous requests
+- Provide specific context when needed
+- Be clear about constraints and limitations
+- Share relevant error messages and logs
+
+### 3. Ignoring AI Capabilities
+- Leverage AI for repetitive tasks
+- Use AI for documentation generation
+- Let AI help with code organization
+- Take advantage of AI's pattern recognition
+
+## Real Examples from Our Project
+
+### 1. Build Configuration
+```typescript
+// AI helped set up proper module exports
+{
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  }
+}
+```
+
+### 2. Test Implementation
+```typescript
+// AI helped write clear, focused tests
+describe('handleChallenge', () => {
+  it('should create and return a challenge', async () => {
+    await middleware.handleChallenge(
+      mockReq as Request,
+      mockRes as Response,
+      mockNext
+    );
+    expect(mockRes.json).toHaveBeenCalledWith({ 
+      challenge: mockChallenge 
+    });
+  });
+});
+```
+
+### 3. Error Handling
+```typescript
+// AI helped implement proper error handling
+try {
+  const challenge = await this.nostrService.createChallenge(pubkey);
+  res.json({ challenge });
+} catch (error) {
+  logger.error('Error handling challenge:', { 
+    error: error instanceof Error ? error.message : String(error) 
+  });
+  next(error);
+}
+```
+
+## Workflow Tips
+
+### 1. Development Cycle
+1. Define clear task objectives
+2. Let AI suggest implementation approach
+3. Review and refine AI's suggestions
+4. Implement with AI's assistance
+5. Test and validate changes
+6. Document with AI's help
+
+### 2. Code Review Process
+1. Have AI review code changes
+2. Ask for potential improvements
+3. Discuss trade-offs with AI
+4. Implement suggested improvements
+5. Verify changes meet standards
+
+### 3. Documentation Updates
+1. Ask AI to explain complex changes
+2. Have AI update relevant docs
+3. Review documentation accuracy
+4. Ensure docs match implementation
+5. Keep architecture docs current
+
+## Measuring Success
+
+### 1. Code Quality Metrics
+- Passing tests
+- Clean lint results
+- Type safety
+- Documentation coverage
+- Code organization
+
+### 2. Development Velocity
+- Faster implementation
+- Fewer regressions
+- Better test coverage
+- Clearer documentation
+- Consistent patterns
+
+## Conclusion
+
+Working with AI can significantly enhance development productivity while maintaining high code quality. The key is to establish clear communication patterns, maintain proper review processes, and leverage AI's strengths while being mindful of its limitations.
+
+Remember that AI is a powerful tool to augment human development capabilities, not replace human judgment. Use it wisely to improve code quality, maintain documentation, and accelerate development while keeping security and reliability as top priorities.

package/CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing to Nostr Auth Middleware
+
+First off, thank you for considering contributing to Nostr Auth Middleware! It's people like you that make this tool better for everyone.
+
+## Code of Conduct
+
+By participating in this project, you are expected to uphold our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating bug reports, please check the issue list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:
+
+* Use a clear and descriptive title
+* Describe the exact steps which reproduce the problem
+* Provide specific examples to demonstrate the steps
+* Describe the behavior you observed after following the steps
+* Explain which behavior you expected to see instead and why
+* Include any error messages or logs
+
+### Suggesting Enhancements
+
+If you have a suggestion for a new feature or enhancement:
+
+* Use a clear and descriptive title
+* Provide a step-by-step description of the suggested enhancement
+* Provide specific examples to demonstrate the steps
+* Describe the current behavior and explain which behavior you expected to see instead
+* Explain why this enhancement would be useful
+
+### Pull Requests
+
+* Fill in the required template
+* Do not include issue numbers in the PR title
+* Follow the TypeScript styleguide
+* Include thoughtfully-worded, well-structured tests
+* Document new code
+* End all files with a newline
+
+## Development Process
+
+1. Fork the repo
+2. Create a new branch from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+3. Make your changes
+4. Run the tests:
+   ```bash
+   npm test
+   ```
+5. Commit your changes using a descriptive commit message
+6. Push to your fork
+7. Submit a Pull Request
+
+## Pull Request Process
+
+1. Update the README.md with details of changes if needed
+2. Update the documentation with details of any changes to the interface
+3. The PR will be merged once you have the sign-off of at least one maintainer
+
+## Style Guides
+
+### Git Commit Messages
+
+* Use the present tense ("Add feature" not "Added feature")
+* Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
+* Limit the first line to 72 characters or less
+* Reference issues and pull requests liberally after the first line
+
+### TypeScript Style Guide
+
+* Use TypeScript for all new code
+* Follow the existing code style
+* Use meaningful variable names
+* Document complex code sections
+* Add types for all parameters and return values
+
+### Documentation Style Guide
+
+* Use Markdown
+* Reference functions and classes with backticks: \`myFunction()\`
+* Include code examples for new features
+* Keep explanations clear and concise
+
+## Community
+
+* Join our [Discord](https://discord.gg/your-invite-link)
+* Follow us on [Twitter](https://twitter.com/your-handle)
+* Read our [blog](https://your-blog-url.com)
+
+## Questions?
+
+Feel free to open an issue with your question or reach out to the maintainers directly.
+
+Thank you for contributing! 🚀

package/SECURITY.md

@@ -0,0 +1,36 @@
+# Security Policy
+
+## Supported Versions
+
+We release patches for security vulnerabilities. Which versions are eligible for receiving such patches depends on the CVSS v3.0 Rating:
+
+| CVSS v3.0 | Supported Versions                        |
+| --------- | ---------------------------------------- |
+| 9.0-10.0  | Releases within the last 6 months        |
+| 4.0-8.9   | Most recent release                      |
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities to security@humanjavaenterprises.com.
+
+The team will acknowledge your email within 48 hours, and will send a more detailed response within 72 hours indicating the next steps in handling your report.
+
+After the initial reply to your report, the security team will endeavor to keep you informed of the progress towards a fix and full announcement, and may ask for additional information or guidance.
+
+## Security Best Practices
+
+When using this authentication middleware:
+
+1. Always use HTTPS in production
+2. Keep your JWT secret keys secure and rotate them regularly
+3. Set appropriate token expiration times
+4. Monitor for suspicious authentication patterns
+5. Keep the middleware and its dependencies up to date
+
+## Disclosure Policy
+
+When the security team receives a security bug report, they will assign it to a primary handler. This person will coordinate the fix and release process.
+
+## Comments on this Policy
+
+If you have suggestions on how this process could be improved please submit a pull request.