docs: polish README, CHANGELOG, package metadata, and add doc stubs

Fix broken doc links, add keywords/repository/homepage/bugs to package.json,
remove COLAB-DOCS from files, fix CHANGELOG date order and add v0.3.0-0.3.5
entries, create CODE_OF_CONDUCT and doc stubs for getting-started, API,
security, and TypeScript guides.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: vveerrgg

CHANGELOG.md

@@ -5,6 +5,13 @@ 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).
 
+## [Unreleased]
+
+## [0.3.5] - 2025-02-19
+
+### Changed
+- Updated dependencies to latest within major versions
+
 ## [0.3.4] - 2025-02-09
 
 ### Added
@@ -16,22 +23,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Enhanced browser compatibility checks
 - Better error messages for session-related operations
 
-## [0.2.6] - 2023-12-05
+## [0.3.3] - 2025-02-01
+
+### Added
+- JWT secret validation at startup
+
+## [0.3.2] - 2025-01-25
+
+### Added
+- Comprehensive JWT configuration and browser compatibility documentation
+
+## [0.3.1] - 2025-01-20
+
+### Changed
+- Included documentation in npm package
+
+## [0.3.0] - 2025-01-15
+
+### Changed
+- Major codebase improvements and documentation updates
+- Removed Node.js 16.x support, upgraded GitHub Actions to v4
+- Prepared for npm publish
+
+## [0.2.6] - 2024-01-09
 
 ### Added
 - New TypeScript interfaces in `interfaces/nostr.interface.ts` for better type safety
 - More comprehensive event validation with detailed error messages
 
-### Enhanced
+### Changed
 - 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
+## [0.2.5] - 2023-12-08
 
 ### 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
+- Updated to use published versions of nostr-crypto-utils and nostr-nsec-seedphrase
+- Updated key generation to use new generateKeyPairWithSeed function
 
 ## [0.2.3] - 2023-12-06
 
@@ -48,7 +77,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Improved error handling in middleware
 - Enhanced TypeScript type safety
 
-## [0.2.2] - Previous Release
+## [0.2.2] - 2023-12-01
 
 ### Added
 - Initial implementation of Nostr authentication middleware

CODE_OF_CONDUCT.md

@@ -0,0 +1,110 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[conduct@humanjavaenterprises.org](mailto:conduct@humanjavaenterprises.org).
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

README.md

@@ -197,17 +197,10 @@ Profile Cache Cleared: { pubkey }
 
 ## Documentation
 
-- [Architecture Guide](docs/architecture-guide.md) - Understanding the service architecture
-- [Key Management Guide](docs/key-management.md) - Comprehensive key management documentation
-- [Deployment Guide](docs/deployment-guide.md) - Environment-specific deployment instructions
 - [Getting Started](docs/getting-started.md) - Quick start guide
-- [Authentication Flow](docs/authentication-flow.md) - Detailed authentication process
-- [Troubleshooting Guide](docs/troubleshooting.md) - Common issues and solutions
 - [API Documentation](docs/api.md) - API endpoints and usage
-- [Security Guide](docs/security.md) - Security best practices and considerations
-- [Automated Tests](docs/automated-tests.md) - Comprehensive test suite documentation
+- [Security Guide](docs/security.md) - Security best practices and key management
 - [TypeScript Guide](docs/typescript.md) - TypeScript declaration patterns and best practices
-- [Browser Authentication](docs/browser-authentication.md) - Browser-based authentication flow
 
 ### TypeScript Declaration Pattern
 

docs/api.md

@@ -0,0 +1,101 @@
+# API Reference
+
+## NostrAuthMiddleware
+
+The main class for Nostr authentication.
+
+### Constructor
+
+```typescript
+new NostrAuthMiddleware(options: NostrAuthOptions)
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `jwtSecret` | `string` | — | Secret for JWT signing (required in production) |
+| `expiresIn` | `string` | `'24h'` | JWT token expiration time |
+
+### Methods
+
+#### `generateToken(payload)`
+
+Generates a JWT token with minimal claims.
+
+```typescript
+const token = await auth.generateToken({ pubkey: 'npub1...' });
+```
+
+**Returns:** `Promise<string>` — The signed JWT token containing `pubkey`, `iat`, and `exp` claims.
+
+#### `verifyToken(token)`
+
+Verifies a JWT token.
+
+```typescript
+const isValid = await auth.verifyToken(token);
+```
+
+**Returns:** `Promise<boolean>`
+
+#### `verifySession(pubkey)`
+
+Verifies if a user's session is still valid.
+
+```typescript
+const isValid = await auth.verifySession(userPubkey);
+```
+
+**Returns:** `Promise<boolean>`
+
+#### `authenticate()`
+
+Returns Express middleware that authenticates requests using Nostr.
+
+```typescript
+app.get('/protected', auth.authenticate(), handler);
+```
+
+## NostrBrowserAuth
+
+Lightweight browser-based authentication using NIP-07.
+
+### Constructor
+
+```typescript
+new NostrBrowserAuth(options?: BrowserAuthOptions)
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `customKind` | `number` | `22242` | Custom event kind for auth |
+| `timeout` | `number` | `30000` | Timeout in milliseconds |
+
+### Methods
+
+#### `getPublicKey()`
+
+Gets the user's public key from their Nostr extension.
+
+```typescript
+const publicKey = await auth.getPublicKey();
+```
+
+#### `signChallenge()`
+
+Signs an authentication challenge.
+
+```typescript
+const challenge = await auth.signChallenge();
+```
+
+#### `validateSession(session)`
+
+Validates an existing session.
+
+```typescript
+const isValid = await auth.validateSession(session);
+```

docs/getting-started.md

@@ -0,0 +1,72 @@
+# Getting Started
+
+## Prerequisites
+
+- Node.js >= 18.0.0
+- npm >= 7.0.0
+
+## Installation
+
+```bash
+npm install nostr-auth-middleware
+```
+
+## Basic Setup
+
+### ESM (Recommended)
+
+```typescript
+import { NostrAuthMiddleware } from 'nostr-auth-middleware';
+
+const auth = new NostrAuthMiddleware({
+  jwtSecret: process.env.JWT_SECRET,
+  expiresIn: '24h',
+});
+```
+
+### CommonJS
+
+```javascript
+const { NostrAuthMiddleware } = require('nostr-auth-middleware');
+
+const auth = new NostrAuthMiddleware({
+  jwtSecret: process.env.JWT_SECRET,
+  expiresIn: '24h',
+});
+```
+
+## Express Integration
+
+```typescript
+import express from 'express';
+import { NostrAuthMiddleware } from 'nostr-auth-middleware';
+
+const app = express();
+app.use(express.json());
+
+const auth = new NostrAuthMiddleware({
+  jwtSecret: process.env.JWT_SECRET,
+});
+
+// Protect routes with Nostr authentication
+app.get('/protected', auth.authenticate(), (req, res) => {
+  res.json({ message: 'Authenticated!', pubkey: req.pubkey });
+});
+
+app.listen(3000);
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `JWT_SECRET` | Production | Secret key for signing JWTs |
+| `NODE_ENV` | No | Set to `production` for production mode |
+
+In development mode, a default secret is used if `JWT_SECRET` is not provided. **Never use the default secret in production.**
+
+## Next Steps
+
+- [API Documentation](api.md) — Full API reference
+- [Security Guide](security.md) — Key management and security best practices
+- [TypeScript Guide](typescript.md) — TypeScript patterns and declarations