clearauth 0.4.1 → 0.6.1

package/CHANGELOG.md

@@ -5,7 +5,105 @@ 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.6.0] - 2026-01-17
+
+### Added
+
+- **Hardware-Backed Device Authentication** - Phishing-resistant authentication for Web3, iOS, and Android
+  - **Multi-Platform Support** - Unified API for Web3 wallets, iOS App Attest, and Android Play Integrity
+  - **Web3 Wallet Registration** - Hardware-backed authentication for MetaMask and Web3 wallets (EIP-191)
+  - **iOS App Attest Support** - Secure Enclave-backed key attestation and verification
+  - **Android Play Integrity Support** - Hardware-backed key attestation via Google Play Integrity API
+  - **Request Signature Middleware** - Cryptographic verification of every API request via `verifyDeviceSignature()`
+  - **Device Management API** - Endpoints for users to list, monitor, and revoke their registered devices
+  - **Device-Bound JWTs** - Optional `deviceId` claim in JWT access tokens for enhanced session security
+  - **Architecture Compatibility** - Lazy-loading native bindings to prevent crashes on mismatched architectures
+
+  **New HTTP Endpoints:**
+  - `POST /auth/challenge` - Generate one-time cryptographic challenge
+  - `POST /auth/device/register` - Register a new hardware device (Web3, iOS, or Android)
+  - `GET /auth/devices` - List all registered devices for the authenticated user (with pagination)
+  - `DELETE /auth/devices/:deviceId` - Revoke a registered device (soft-delete with audit trail)
+
+  **New Functions:**
+  - `verifyDeviceSignature()` - Middleware to verify request signatures from registered devices
+  - `listUserDevices()` / `listActiveDevices()` - Data layer functions for device management
+  - `revokeDevice()` - Soft-delete device revocation
+  - `verifyIOSAttestation()` - Complete iOS App Attest verification chain
+  - `verifyIntegrityToken()` - Google Play Integrity token verification
+  - `verifyEIP191Signature()` - Web3 personal_sign verification
+  - `generateChallenge()` / `verifyChallenge()` - Challenge-response infrastructure
+
+  **Database Schema:**
+  - Uses existing `devices` table (introduced in v0.5.0) for hardware key storage
+  - Uses existing `challenges` table (introduced in v0.5.0) for one-time challenge storage
+  - Optimized indexes for user-based device queries and revocation
+
+  **Documentation:**
+  - Comprehensive README section with multi-platform device auth guide
+  - Client SDK examples for TypeScript (Web3), Swift (iOS), and Kotlin (Android)
+  - Troubleshooting guide updated for cross-architecture native binding issues
+
+  **Testing:**
+  - 194 comprehensive tests covering all device authentication modules (added in v0.5.0-v0.6.0)
+  - Integration tests for all new HTTP endpoints
+  - Total test suite now at 518 passing tests
+
+### Fixed
+
+- **Cross-Architecture Native Bindings** - Implemented lazy-loading for \`@node-rs/argon2\` to prevent startup crashes when running on mismatched architectures (e.g., x64 Node on ARM64). (Fixed in #25)
+- **Security Validation** - Hardened URL validation for device IDs to prevent path traversal and empty ID bypass. (Fixed in #25)
+- **Error Information Leakage** - Standardized generic error messages in API responses while maintaining detailed internal logging. (Fixed in #25)
+
+## [0.5.0] - 2026-01-15
+
+### Added
+
+- **JWT Bearer Token Authentication** - Complete stateless authentication for CLI tools, mobile apps, and API clients
+  - **ES256 Algorithm** - ECDSA with P-256 curve for edge-optimized signing/verification
+  - **Access Tokens** - 15-minute stateless JWT tokens (configurable TTL)
+  - **Refresh Tokens** - 30-day revocable tokens stored in database (configurable TTL)
+  - **Token Rotation** - Automatic refresh token rotation for enhanced security
+  - **Revocation Support** - Soft-delete revocation with audit trail via `revoked_at` timestamp
+  - **OAuth 2.0 Compliant** - Token responses follow RFC 6749 specification
+  - **Edge Compatible** - Web Crypto API only, works in Cloudflare Workers, Vercel Edge, browsers, Node.js
+  - **Zero Dependencies Added** - Uses existing `jose` library (6.1.3)
+
+  **New HTTP Endpoints:**
+  - `POST /auth/token` - Exchange credentials for JWT access + refresh token pair
+  - `POST /auth/refresh` - Rotate refresh token and get new access token
+  - `POST /auth/revoke` - Revoke refresh token (logout)
+
+  **New Functions:**
+  - `createAccessToken()` - Generate signed JWT access token
+  - `verifyAccessToken()` - Verify and decode JWT access token
+  - `parseBearerToken()` - Extract Bearer token from Authorization header
+  - `validateBearerToken()` - Validate Bearer token from request
+  - `createRefreshToken()` - Create revocable refresh token in database
+  - `rotateRefreshToken()` - Securely rotate refresh token
+  - `revokeRefreshToken()` - Revoke refresh token by ID
+  - `revokeAllUserRefreshTokens()` - Revoke all tokens for a user
+  - `cleanupExpiredTokens()` - Remove expired tokens from database
+
+  **Database Schema:**
+  - New `refresh_tokens` table with SHA-256 hashed tokens
+  - Migration scripts: `006_create_refresh_tokens.sql` and `rollback_006.sql`
+  - Indexes for performance: `idx_refresh_tokens_user`, `idx_refresh_tokens_expires`
+
+  **Entrypoint:**
+  - New `clearauth/jwt` submodule export for JWT-specific imports
+  - All JWT types and functions exported from main `clearauth` package
+
+  **Documentation:**
+  - Comprehensive README section with ES256 key generation instructions
+  - Usage examples for Node.js, Cloudflare Workers, CLI/mobile apps
+  - API reference table with all endpoints and functions
+  - Security considerations and best practices
+
+  **Testing:**
+  - 89 new comprehensive tests (31 signer + 36 refresh tokens + 22 handlers)
+  - 100% code coverage for all JWT modules
+  - All 320 tests passing
 
 ### Fixed