docs: polish README, CONTRIBUTING, package metadata, and add CHANGELOG

Expand README with architecture, security, and API sections. Fix all
login-utils references to auth-utils in CONTRIBUTING and package.json.
Fix repository/bugs/homepage URLs, add examples to files, create CHANGELOG.

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

Author: vveerrgg

CHANGELOG.md

@@ -0,0 +1,30 @@
+# 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).
+
+## [Unreleased]
+
+## [0.1.1] - 2025-02-19
+
+### Changed
+- Updated dependencies and fixed TypeScript 5.9 type errors
+- Refactored for npm package release
+- Updated package descriptions to clarify step-up authentication use case
+
+### Removed
+- Removed deprecated test-server and proof_of_concept directories
+
+## [0.1.0] - 2025-01-15
+
+### Added
+- Initial release
+- WebAuthn-based biometric authentication for Nostr applications
+- Support for TouchID/FaceID, Windows Hello, Android biometric, and security keys
+- NIP-19 compliant entity encoding/decoding
+- Nostr profile integration
+- Settings management via Nostr direct messages
+- Express.js example with WebAuthn and profile fetching
+- Comprehensive TypeScript type definitions

CONTRIBUTING.md

@@ -1,11 +1,11 @@
-# Contributing to nostr-biometric-login-utils
+# Contributing to nostr-biometric-auth-utils
 
-Thank you for considering contributing to **nostr-biometric-login-utils**! We appreciate your help in making this biometric authentication service better.
+Thank you for considering contributing to **nostr-biometric-auth-utils**! We appreciate your help in making this biometric authentication service better.
 
 ## How to Contribute
 
 ### Reporting Issues
-If you find a bug or have a feature request, please open an issue on our [GitHub repository](https://github.com/HumanjavaEnterprises/nostr-biometric-login-utils/issues).
+If you find a bug or have a feature request, please open an issue on our [GitHub repository](https://github.com/HumanjavaEnterprises/nostr-biometric-auth-utils/issues).
 
 ### Pull Requests
 1. Fork the repository.

README.md

@@ -1,15 +1,19 @@
 # Nostr Biometric Authentication Utilities
 
-A comprehensive utility library for implementing biometric authentication in Nostr applications using WebAuthn. This library provides a flexible set of tools for adding secure biometric authentication to your Nostr-based applications.
+[![npm version](https://img.shields.io/npm/v/nostr-biometric-auth-utils.svg)](https://www.npmjs.com/package/nostr-biometric-auth-utils)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+A comprehensive utility library for implementing biometric authentication in Nostr applications using WebAuthn. This library provides a flexible set of tools for adding secure biometric authentication as a step-up factor to your Nostr-based applications.
 
 ## Features
 
 - **WebAuthn Integration**: Ready-to-use utilities for implementing WebAuthn-based biometric authentication
-- **Platform Support**: 
+- **Platform Support**:
   - TouchID/FaceID for iOS and macOS
   - Windows Hello
   - Android biometric authentication
-  - Security Key support
+  - Security Key support (FIDO2/U2F)
 - **Nostr-Specific Tools**:
   - Full NIP-19 compliance for entity encoding/decoding
   - Nostr profile integration
@@ -24,7 +28,7 @@ A comprehensive utility library for implementing biometric authentication in Nos
 npm install nostr-biometric-auth-utils
 ```
 
-## Usage
+## Quick Start
 
 ### Basic Authentication Flow
 
@@ -77,30 +81,151 @@ await settings.updateSettings({
 
 The library is organized into several core modules:
 
-- **Client**: Main client-side implementation for managing authentication flow
-- **Core**: 
-  - WebAuthn implementation
-  - TouchID/FaceID integration
-  - Security key support
-- **Settings**: Nostr-based settings management
-- **Utils**: Helper functions for Nostr entity handling
+```
+nostr-biometric-auth-utils/
+├── src/
+│   ├── client/          # Main client-side authentication flow
+│   │   └── index.ts     # NostrBiometricClient implementation
+│   ├── core/            # Core authentication implementations
+│   │   ├── webauthn.ts  # WebAuthn registration & verification
+│   │   ├── touchid.ts   # TouchID/FaceID integration
+│   │   └── security-key.ts  # Hardware security key support
+│   ├── settings/        # Nostr-based settings management
+│   │   └── index.ts     # SettingsManager for DM-based config
+│   └── utils/           # Helper functions
+│       └── nostr.ts     # Nostr entity encoding/decoding (NIP-19)
+```
+
+### Authentication Flow
+
+```
+1. User provides their npub
+         │
+         v
+2. Magic link sent via Nostr DM
+         │
+         v
+3. User clicks magic link
+         │
+         v
+4. WebAuthn biometric challenge
+   (TouchID / FaceID / Windows Hello / Security Key)
+         │
+         v
+5. Session established
+```
+
+The flow combines Nostr's cryptographic identity with WebAuthn biometrics for two-factor authentication. The magic link verifies the user controls the Nostr key, and biometrics verify the user is physically present.
+
+## API Reference
+
+### NostrBiometricClient
+
+The main client for managing the authentication flow.
+
+```typescript
+const client = new NostrBiometricClient(options: ClientOptions);
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `relays` | `string[]` | Nostr relay URLs to connect to |
+| `magicLinkExpiry` | `number` | Magic link expiry in seconds (default: 300) |
+| `sessionDuration` | `number` | Session duration in seconds (default: 86400) |
+
+#### Methods
+
+- `startAuth(npub: string)` — Begins the authentication flow for a given npub
+- `onStateChange(callback)` — Registers a callback for auth state transitions
+- `cancelAuth()` — Cancels an in-progress authentication
+
+### SettingsManager
+
+Manages user settings stored via Nostr direct messages.
+
+```typescript
+const settings = new SettingsManager(nostrService, userPubkey);
+```
+
+#### Methods
+
+- `loadSettings()` — Loads the user's current settings
+- `updateSettings(settings)` — Updates and persists settings
+- `resetSettings()` — Resets settings to defaults
+
+### WebAuthn Utilities
+
+Low-level WebAuthn functions for custom flows.
+
+```typescript
+import { registerCredential, verifyCredential } from 'nostr-biometric-auth-utils';
+
+// Register a new biometric credential
+const credential = await registerCredential({
+  rpName: 'Your App',
+  rpId: 'your-app.com',
+  userId: npub,
+  userName: displayName,
+});
+
+// Verify a credential during authentication
+const result = await verifyCredential({
+  credentialId: credential.id,
+  challenge: serverChallenge,
+});
+```
 
 ## Security Considerations
 
-- All biometric data remains on the user's device
-- Implements FIDO2 WebAuthn specifications
-- Follows security best practices for key management
-- Proper error handling for all security-critical operations
+### Biometric Data Privacy
+
+- All biometric data remains on the user's device — it is never transmitted to servers
+- The WebAuthn protocol only exchanges cryptographic proofs, not biometric templates
+- Implements FIDO2 WebAuthn specifications for maximum interoperability
+
+### Key Management
+
+- Nostr private keys are never handled by this library
+- Magic link signing uses nostr-crypto-utils for NIP-compliant operations
+- WebAuthn credentials are bound to the origin (domain) and cannot be phished
+
+### Threat Model
+
+| Threat | Mitigation |
+|--------|------------|
+| Stolen npub | Magic link requires access to Nostr DMs |
+| Compromised relay | Multi-relay support with verification |
+| Phishing | WebAuthn origin binding prevents cross-site use |
+| Session hijacking | Configurable session expiry with biometric re-auth |
+
+### Best Practices
+
+1. Always use multiple relays for magic link delivery
+2. Set appropriate expiry times for magic links (5-15 minutes)
+3. Implement session refresh with biometric re-verification
+4. Monitor failed authentication attempts
+5. Use HTTPS in production for WebAuthn origin verification
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `examples/proof_of_concept/` — Minimal Express.js server with WebAuthn flow
 
 ## Contributing
 
-Contributions are welcome! Please read our contributing guidelines for details on our code of conduct and the process for submitting pull requests.
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.
 
 ## License
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 ## Related Projects
 
-- [nostr-dm-magiclink-utils](https://github.com/HumanjavaEnterprises/nostr-dm-magiclink-utils)
-- [MaiQR Platform](https://github.com/HumanjavaEnterprises/MaiQR-Platform)
+- [nostr-crypto-utils](https://github.com/HumanjavaEnterprises/nostr-crypto-utils) — Core cryptographic utilities for Nostr
+- [nostr-dm-magiclink-utils](https://github.com/HumanjavaEnterprises/nostr-dm-magiclink-utils) — Magic link authentication via Nostr DMs
+- [nostr-auth-middleware](https://github.com/HumanjavaEnterprises/nostr-auth-middleware) — Authentication middleware for Nostr apps

package.json

@@ -14,6 +14,7 @@
   },
   "files": [
     "dist",
+    "examples/**/*",
     "README.md",
     "LICENSE"
   ],
@@ -40,12 +41,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/HumanjavaEnterprises/nostr-biometric-login-utils.git"
+    "url": "git+https://github.com/HumanjavaEnterprises/nostr-biometric-auth-utils.git"
   },
   "bugs": {
-    "url": "https://github.com/HumanjavaEnterprises/nostr-biometric-login-utils/issues"
+    "url": "https://github.com/HumanjavaEnterprises/nostr-biometric-auth-utils/issues"
   },
-  "homepage": "https://github.com/HumanjavaEnterprises/nostr-biometric-login-utils#readme",
+  "homepage": "https://github.com/HumanjavaEnterprises/nostr-biometric-auth-utils#readme",
   "dependencies": {
     "@scure/base": "^1.2.6",
     "@simplewebauthn/browser": "^8.3.7",