volter 0.0.179 → 0.0.180

package/AGENTS.md

@@ -0,0 +1,141 @@
+# AGENTS.md - Volter Package Guidelines
+
+This file contains guidelines and commands for agentic coding agents working in the Volter package repository.
+
+## Build & Development Commands
+
+### Core Commands
+- `bun test` - Run all tests
+- `bun build ./src/**.ts --outdir ./dist --target bun --minify && tsc --declarationMap false` - Build the package
+- `biome lint ./src --apply` - Lint and auto-fix code issues
+- `biome format ./src --write` - Format code according to project style
+
+### Running Single Tests
+Currently no test files exist in the project. When tests are added, use:
+- `bun test <test-file-name>` - Run specific test file
+- `bun test --grep <pattern>` - Run tests matching pattern
+
+## Project Structure
+
+```
+volter/
+├── src/
+│   ├── index.ts      # Main export file
+│   ├── utils.ts      # Utility functions and helpers
+│   ├── error.ts      # Error handling classes and enums
+│   ├── crypto.ts     # Cryptographic functions
+│   └── sessions.ts   # Session management and email verification
+├── dist/             # Built JavaScript files
+├── types/            # TypeScript declaration files
+└── package.json      # Package configuration
+```
+
+## Code Style Guidelines
+
+### TypeScript Configuration
+- Strict mode enabled
+- ESNext target with DOM libraries
+- ES modules with bundler resolution
+- Declarations emitted to `types/` directory
+- No unchecked indexed access
+
+### Import Style
+- Use default imports for external packages: `import ansi from "ansi-colors"`
+- Use named imports for internal modules: `import { hash } from "./crypto"`
+- Keep imports at the top of files
+- Group external imports first, then internal imports
+
+### Naming Conventions
+- **Classes**: PascalCase (e.g., `Session`, `ServerError`)
+- **Functions/Methods**: camelCase (e.g., `createRandom`, `validate`)
+- **Variables**: camelCase (e.g., `userId`, `expires`)
+- **Constants**: UPPER_SNAKE_CASE for enums and exported constants (e.g., `ErrorCodes`)
+- **Interfaces**: PascalCase with descriptive names (e.g., `SessionOptions`, `CipherText`)
+
+### Error Handling
+- Use custom `ServerError` class for application errors
+- Include error codes from `ErrorCodes` enum
+- Provide context with `at` property for stack traces
+- Use Zod for validation errors (`ValidationError`)
+- Throw errors with descriptive messages
+
+### Function Patterns
+- Use async/await for asynchronous operations
+- Return promises from async functions
+- Use optional parameters with defaults: `createRandom(length = 32)`
+- Export utility functions individually
+- Use factory functions for object creation
+
+### Type Safety
+- Use TypeScript interfaces for object shapes
+- Leverage Zod schemas for runtime validation
+- Use proper return types for functions
+- Import types with `type` keyword when possible: `import type { RedisClient } from "bun"`
+
+### Code Organization
+- Keep related functionality in separate files
+- Use barrel exports in `index.ts` for public API
+- Add JSDoc comments for complex functions
+- Use consistent indentation (Biome will handle this)
+
+### Security Best Practices
+- Use `crypto.getRandomValues()` for secure random generation
+- Implement proper key management in crypto functions
+- Hash sensitive data before storage
+- Use secure algorithms (AES-GCM, ECDSA, SHA-256)
+
+### Dependencies
+- **Runtime**: Bun (JavaScript runtime)
+- **Linting/Formatting**: Biome
+- **Type Checking**: TypeScript
+- **External Libraries**: 
+  - `zod` for validation
+  - `@paralleldrive/cuid2` for ID generation
+  - `ansi-colors` for console output
+  - `drizzle-orm` for database operations
+  - `resend` for email sending
+
+## Testing Guidelines
+
+When adding tests:
+- Use Bun test runner
+- Place test files alongside source files or in `test/` directory
+- Use descriptive test names
+- Test both success and error cases
+- Mock external dependencies (Redis, email services)
+
+## Build Process
+
+The build process involves:
+1. Bun compiles TypeScript to JavaScript in `dist/`
+2. TypeScript generates declaration files in `types/`
+3. Output is minified for production
+4. ES modules are generated for modern bundlers
+
+## Global Declarations
+
+The project extends the global `Request` interface to include:
+```typescript
+declare global {
+  interface Request {
+    ip: Bun.SocketAddress
+  }
+}
+```
+
+## Session Management
+
+The `Sessions` class provides:
+- Redis-backed session storage
+- Token-based authentication
+- Session rotation and revocation
+- User session listing
+- Fallback session cleanup
+
+## Email Verification
+
+The `e1T` class handles:
+- PIN-based email verification
+- Rate limiting with attempt tracking
+- Email sending via Resend
+- Customizable email templates

package/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to Volter 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]
+
+### Added
+- Initial release preparation
+
+## [1.0.0] - 2025-01-12
+
+**Note**: This release marks the transition from version 0.0.174 to stable 1.0.0 with API stability guarantees.
+
+### Added
+- **Core Features**
+  - Secure session management with Redis backend
+  - Email verification with PIN-based system
+  - Cryptographic utilities (AES-GCM encryption, ECDSA signatures)
+  - Structured error handling with custom `ServerError` class
+  - Secure random token and ID generation
+
+- **Session Management**
+  - Redis-backed session storage with configurable TTL
+  - Session rotation for security
+  - Session revocation and cleanup
+  - User session listing functionality
+  - Fallback session cleanup mechanisms
+
+- **Email Verification**
+  - PIN-based email verification system
+  - Rate limiting and attempt tracking
+  - Configurable PIN expiration
+  - Email sending via Resend service
+  - Customizable email templates
+
+- **Security Features**
+  - AES-GCM encryption for sensitive data
+  - ECDSA digital signatures
+  - SHA-256 hashing utilities
+  - Secure random generation using Web Crypto API
+  - Input validation with Zod schemas
+
+- **Developer Experience**
+  - TypeScript support with strict mode
+  - Comprehensive error codes
+  - Detailed documentation and examples
+  - Built-in logging and debugging support
+  - Biome for code formatting and linting
+
+- **Integrations**
+  - Redis client with connection pooling
+  - Drizzle ORM for database operations
+  - Resend for email delivery
+  - CUID2 for secure ID generation
+
+### Dependencies
+- Bun runtime (JavaScript engine)
+- zod for schema validation
+- @paralleldrive/cuid2 for ID generation
+- ansi-colors for console output
+- drizzle-orm for database operations
+- resend for email sending
+
+### Documentation
+- Comprehensive README with installation and usage guides
+- API documentation with examples
+- Security best practices
+- Contributing guidelines
+- Code of conduct
+
+## [0.9.0] - 2025-01-05 (Beta)
+
+### Added
+- Beta release of core session management
+- Basic Redis integration
+- Initial email verification system
+- Crypto utilities implementation
+
+### Known Issues
+- Limited error handling
+- Beta performance optimizations needed
+- Documentation incomplete
+
+---
+
+## Version Legend
+
+- **Major** (X.0.0) - Breaking changes, major new features
+- **Minor** (0.X.0) - New features, improvements
+- **Patch** (0.0.X) - Bug fixes, security patches, documentation updates
+
+## Migration Guides
+
+### From 0.9.x to 1.0.0
+
+No breaking changes from beta to stable release. Simply update:
+
+```bash
+bun update volter@latest
+```
+
+### Breaking Changes
+
+As this is the initial stable release, there are no breaking changes from previous versions. Future breaking changes will be clearly documented with migration guides.
+
+## Security Updates
+
+Security updates will be released as patch versions and marked clearly in the changelog. Always upgrade to the latest patch version for security fixes.
+
+## Support End of Life
+
+- **0.9.x** - Support ended 2025-02-01
+- **1.0.x** - Current stable version
+
+For support and upgrade assistance, see our [Support Policy](./SUPPORT.md).

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,89 @@
+# Contributor Covenant 3.0 Code of Conduct
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant.
+
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language.
+
+With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our community**.
+
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people.
+3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits.
+4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community.
+5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission.
+6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group.
+7. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions.
+2. **Failing to credit sources.** Not properly crediting the sources of content you contribute.
+3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community.
+4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors.
+
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm.
+
+When an incident does occur, it is important to report it promptly. To report a possible violation, email us at abuse@modlin.dev for convenience.
+
+Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution.
+
+
+## Addressing and Repairing Harm
+
+If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped.
+
+1) Warning
+   1) Event: A violation involving a single incident or series of incidents.
+   2) Consequence: A private, written warning from the Community Moderators.
+   3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations.
+2) Temporarily Limited Activities
+   1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation.
+   2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members.
+   3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over.
+3) Temporary Suspension
+   1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation.
+   2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
+   3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
+4) Permanent Ban
+   1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member.
+   2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior.
+   3) Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community.
+
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
+
+For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion).

package/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Code Style Guidelines for Modlin
+
+## Purpose & Scope
+
+This document defines the official code style guidelines for this project. Its goal is to ensure consistency, readability, maintainability, and long-term sustainability of the codebase.
+
+These guidelines apply to all contributors and all code written for this repository unless explicitly stated otherwise. When existing code conflicts with this guide, follow the guide for new code and refactor old code only when touching it.
+
+## Principles
+
+The following principles override individual rules:
+- Readability is more important than cleverness
+- Consistency is more important than personal preference
+- Explicit code is preferred over implicit behavior
+- Maintainability is prioritized over micro-optimizations
+- Tooling should enforce style wherever possible
+
+## Project & File Structure
+
+## Naming (Naming Conventions)
+
+Names must be only ASCII letters, digits, underscores, and the `$` sign. Don't use `-`.
+
+- **Variables:** snake_case
+    - Try using a single lowercase word e.g. `index`, `data`, `error`, and `result`.
+- **Constants:** UPPER_SNAKE_CASE
+    - Use only when something is not defined during runtime e.g. `TOKEN`, `PORT`, `DATABASE_URL`, and `VERSION`.
+- **Functions:** snake_case
+    - Try keeping it one worded that just describes what it does e.g. `hash` is used for hashing `string` to `SHA-256`.
+- **Classes:** PascalCase
+    - Preferably branded (`Resend`, `Volter`).
+- **Methods:** camelCase
+    - Keep it one word unless for events (`onError()`), checks (`isEnabled()`), or operations (`getUser()`).
+    - When you experince a situation where the function checks if a string is an HTTP URL then do `isHTTP_URL()` instead of `isHTTPURL()`.
+- **Types / Interfaces / Namespaces**: PascalCase
+    - With clear names.
+- **Comments:** Any
+    - Only for documentation, not for explaining code.

package/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "volter"
+version = "0.0.1"
+edition = "2024"
+
+[dependencies]
+chrono = "0.4.43"
+colored = "3.1.1"
+dotenvy = "0.15.7"
+tokio = { version = "1.49.0", features = ["net", "rt-multi-thread", "macros", "io-util", "time"] }

package/SECURITY.md

@@ -0,0 +1,63 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+The Volter team and community take all security vulnerabilities seriously. Thank you for improving the security of our project.
+
+### How to Report
+
+**Please do not report security vulnerabilities through public GitHub issues, discussions, or other public channels.**
+
+Instead, please send an email to: **security@modlin.dev**
+
+When reporting a vulnerability, please include:
+- A clear description of the vulnerability
+- Steps to reproduce the vulnerability
+- Any potential impact or exploit scenarios
+- Your name (optional - we give credit for responsible disclosure)
+
+### Response Timeline
+
+- **Initial Response**: Within 48 hours
+- **Detailed Response**: Within 7 days
+- **Patch Release**: Within 30 days (depending on severity)
+- **Public Disclosure**: After patch is released (with your permission, we'll credit you)
+
+### Security Best Practices
+
+We recommend following these security best practices when using Volter:
+
+1. **Keep dependencies updated** - Regularly update to the latest version
+2. **Use secure session storage** - Ensure Redis is properly secured with authentication
+3. **Environment variables** - Store sensitive data in environment variables, not in code
+4. **HTTPS only** - Always use HTTPS in production environments
+5. **Session rotation** - Enable session rotation to prevent session fixation attacks
+6. **Rate limiting** - Implement rate limiting for authentication endpoints
+
+### Security Features
+
+Volter includes several built-in security features:
+
+- **AES-GCM encryption** for sensitive data
+- **Secure random token generation** using `crypto.getRandomValues()`
+- **Session rotation** to prevent session hijacking
+- **PIN-based email verification** with rate limiting
+- **Input validation** using Zod schemas
+- **Structured error handling** to prevent information leakage
+
+### Dependency Security
+
+We regularly audit and update dependencies. To check for security vulnerabilities in your dependencies:
+
+```bash
+bun audit
+```
+
+For more information about our security practices, see our [README](./README.md#security).

package/SUPPORT.md

@@ -0,0 +1,91 @@
+# Support
+
+## Getting Help
+
+We're here to help you succeed with Volter. Here are the best ways to get support:
+
+### 📚 Documentation
+
+- **[Main Documentation](./README.md)** - Features, installation, and basic usage
+- **[API Reference](./AGENTS.md)** - For developers contributing to Volter
+- **[Examples](./examples/)** - Practical implementation examples (coming soon)
+
+### 🤝 Community Support
+
+#### GitHub Discussions
+- **[Questions & General Discussion](https://github.com/modlin-org/volter/discussions/categories/q-a)** - Ask questions, share your experiences
+- **[Show & Tell](https://github.com/modlin-org/volter/discussions/categories/show-and-tell)** - Share what you've built with Volter
+- **[Ideas & Feature Requests](https://github.com/modlin-org/volter/discussions/categories/ideas)** - Suggest new features or improvements
+
+#### GitHub Issues
+- **[Bug Reports](https://github.com/modlin-org/volter/issues/new?template=bug_report.yml)** - Report bugs or unexpected behavior
+- **[Feature Requests](https://github.com/modlin-org/volter/issues/new?template=feature_request.yml)** - Request new features
+- **[Security Issues](./SECURITY.md)** - Report security vulnerabilities (private)
+
+### 💬 Professional Support
+
+For enterprise users requiring priority support:
+
+- **Email**: support@modlin.dev
+- **Response Time**: Within 24 hours during business days
+- **Services**: Bug fixes, feature prioritization, architectural guidance
+
+### 🐛 Troubleshooting Common Issues
+
+#### Installation Problems
+```bash
+# Clear cache and reinstall
+bun cache clear
+bun install
+```
+
+#### Redis Connection Issues
+- Ensure Redis is running: `redis-server`
+- Check connection string format: `redis://localhost:6379`
+- Verify network connectivity to Redis server
+
+#### Session Issues
+- Check session expiration settings
+- Verify Redis key persistence
+- Ensure session middleware is properly configured
+
+### 📈 Contributing
+
+Want to contribute? See our [Contributing Guide](./CONTRIBUTING.md) for:
+- Development setup
+- Code style guidelines
+- Pull request process
+- Testing requirements
+
+### 📋 Bug Report Template
+
+When filing a bug report, please include:
+
+1. **Volter version**
+2. **Node/Bun version**
+3. **Operating system**
+4. **Steps to reproduce**
+5. **Expected behavior**
+6. **Actual behavior**
+7. **Error messages/stack traces**
+8. **Minimal reproduction case** (if possible)
+
+### 🔄 Release Schedule
+
+- **Major releases**: Every 3-4 months
+- **Minor releases**: Every 4-6 weeks
+- **Patch releases**: As needed for bug fixes
+- **Security patches**: Immediately as needed
+
+Follow our [Changelog](./CHANGELOG.md) for release announcements and details.
+
+### 📞 Contact
+
+- **General Inquiries**: hello@modlin.dev
+- **Security Issues**: security@modlin.dev
+- **Business/Enterprise**: business@modlin.dev
+- **Website**: [modlin.dev](https://modlin.dev)
+
+---
+
+**Note**: Community support is provided on a best-effort basis by volunteers. For guaranteed response times and SLAs, consider professional support options.

package/package.json

@@ -1,10 +1,10 @@
 {
 	"$schema": "https://json.schemastore.org/package",
 	"name": "volter",
-	"version": "0.0.179",
+	"version": "0.0.180",
 	"description": "Secure, lightweight, and user-friendly modern JavaScript toolchain optimized for performance and minimalism.",
-	"main": "dist/index.js",
-	"module": "dist/index.js",
+	"main": "./src/index.ts",
+	"module": "./src/index.ts",
 	"type": "module",
 	"scripts": {
 		"lint": "biome lint ./src --apply",
@@ -14,22 +14,39 @@
 	},
 	"exports": {
 		".": {
-			"types": "./types/index.d.ts",
-			"import": "./dist/index.js",
-			"default": "./dist/index.js"
+			"types": "./src/index.ts",
+			"import": "./src/index.ts",
+			"default": "./src/index.ts"
 		},
 		"./*": {
-			"types": "./types/*.d.ts",
-			"import": "./dist/*.js",
-			"default": "./dist/*.js"
+			"types": "./src/*.ts",
+			"import": "./src/*.ts",
+			"default": "./src/*.ts"
 		}
 	},
-	"files": [
-		"dist",
-		"types"
-	],
-	"types": "./types/index.d.ts",
-	"typings": "./types/index.d.ts",
+	"publishConfig": {
+		"main": "./dist/index.js",
+		"module": "./dist/index.js",
+		"types": "./types/index.d.ts",
+		"exports": {
+			".": {
+				"types": "./types/index.d.ts",
+				"import": "./dist/index.js",
+				"default": "./dist/index.js"
+			},
+			"./*": {
+				"types": "./types/*.d.ts",
+				"import": "./dist/*.js",
+				"default": "./dist/*.js"
+			}
+		},
+		"files": [
+			"dist",
+			"types"
+		]
+	},
+	"types": "./src/index.ts",
+	"typings": "./src/index.ts",
 	"devDependencies": {
 		"@types/bun": "^1.3.3",
 		"typescript": "^5.9.3"