volter 0.0.174 → 0.0.177

package/README.md

@@ -1,2 +1,309 @@
+<img src="/public/cover.png" alt="Volter" />
+
 # Volter
-Secure, lightweight, and user-friendly modern JavaScript toolchain optimized for performance and minimalism.
+
+Secure, lightweight session management and authentication library for modern JavaScript applications. Built with Bun runtime optimization, it provides Redis-backed session storage, email verification, encryption utilities, and structured error handling.
+
+## Features
+
+- **Session Management** - Redis-backed sessions with secure token validation
+- **Email Verification** - PIN-based verification with Resend integration
+- **Cryptography** - AES-GCM encryption, RSA key pairs, ECDSA signatures
+- **Security Utilities** - Secure ID generation, hashing, and validation
+- **Error Handling** - Structured error codes and custom error classes
+- **TypeScript Support** - Full type definitions included
+- **Bun Optimized** - Leverages Bun's built-in Redis and crypto APIs
+
+## Installation
+
+```bash
+npm install volter
+```
+```bash
+bun add volter
+```
+
+### Required Dependencies
+
+- **Redis Server** - For session storage
+- **Resend API Key** - For email verification (optional)
+- **Bun Runtime** - Recommended for optimal performance
+- **Node.js** - Also supported (v18+)
+
+## Quick Start
+
+```typescript
+import { Sessions } from "volter";
+
+// Initialize sessions with Redis
+const sessions = new Sessions({
+  expiry: 2592000, // 30 days in seconds
+});
+
+// Create session for user
+const session = await sessions.create("user-123");
+console.log("Session token:", session.token);
+
+// Validate session
+const userId = await sessions.validate(session.token);
+console.log("User ID:", userId); // 'user-123'
+```
+
+## API Overview
+
+### Sessions Class
+
+Complete session lifecycle management with Redis backend.
+
+```typescript
+import { RedisClient } from "bun"
+import { Sessions } from "volter";
+
+const redis = new RedisClient(Bun.env.REDIS_URL)
+
+const sessions = new Sessions({
+    store: redis, // Optional, defaults to Bun.redis
+    expiry: 2592000, // 30 days in seconds
+    createID: crypto.randomUUID, // Optional custom ID generator
+});
+
+// Create new session
+const session = await sessions.create("user-id");
+
+// Validate session token
+const userId = await sessions.validate(token);
+
+// Get session details
+const details = await sessions.get(token);
+
+// List all user sessions
+const userSessions = await sessions.list("user-id");
+
+// Revoke session
+await sessions.revoke(token);
+```
+
+### Email Verification (e1T)
+
+PIN-based email verification with Resend integration.
+
+```typescript
+import { e1T } from "volter";
+import { Resend } from "resend";
+
+const e1t = new e1T({
+    resend: new Resend("re_xxxxxxxxx"),
+    expiry: 300, // 5 minutes
+    attempts: 5, // Max verification attempts
+    template: (email, code) => ({
+        from: "noreply@app.dev",
+        to: email,
+        subject: `${code}: is your verification code.`,
+        text: `Enter ${code} to verify your email. For your security, do not share.`,
+    }),
+});
+
+// Send verification code
+const result = await e1t.send("user@app.dev");
+console.log("Verification code:", result.code);
+
+// Verify code
+const isValid = await e1t.verify("user@app.dev", "855 004");
+```
+
+### Cryptography Utilities
+
+Secure encryption, signing, and key management.
+
+```typescript
+import {
+  cipher,
+  decipher,
+  sign,
+  verifySign,
+  generateECDSAKeyPair,
+  hash,
+} from "volter";
+
+// AES-GCM encryption
+const encrypted = await cipher("secret data", "encryption-key");
+const decrypted = await decipher(encrypted, "encryption-key");
+
+// Digital signatures
+const keyPair = await generateECDSAKeyPair();
+const signature = await sign("message to sign", keyPair.privateKey);
+const isValid = await verifySign(
+  "message to sign",
+  signature,
+  keyPair.publicKey,
+);
+
+// Secure hashing
+const hashed = hash("password", "salt");
+```
+
+### Error Handling
+
+Structured error codes and custom error classes.
+
+```typescript
+import { ServerError, ErrorCodes, ValidationError } from "volter";
+
+// Custom server error
+throw new ServerError("User not found", {
+  code: ErrorCodes.RESOURCE_NOT_FOUND,
+  at: ["UserService", "getUserById"],
+});
+
+// Validation with Zod
+import { z } from "zod";
+const schema = z.string().email();
+try {
+  schema.parse("invalid-email");
+} catch (error) {
+  throw new ValidationError("Invalid email format");
+}
+```
+
+## Configuration
+
+### Redis Setup
+
+```typescript
+// Using default Bun Redis
+const sessions = new Sessions();
+
+// Using custom Redis client
+const sessions = new Sessions({
+  store: new RedisClient({
+    host: "localhost",
+    port: 6379,
+    password: "your-password",
+  }),
+});
+```
+
+### Resend Email Setup
+
+```typescript
+import { Resend } from "resend";
+
+const emailVerify = new e1T({
+  resend: new Resend(process.env.RESEND_API_KEY),
+  template: (email, code) => ({
+    from: process.env.FROM_EMAIL,
+    to: email,
+    subject: `Verify your account - Code: ${code}`,
+    html: `<h1>Your verification code is: <strong>${code}</strong></h1>`,
+  }),
+});
+```
+
+## Security Best Practices
+
+- Always use HTTPS in production
+- Store sensitive keys in environment variables
+- Set appropriate session expiry times
+- Implement rate limiting for verification attempts
+- Use secure, random session tokens
+- Regularly rotate encryption keys
+
+## TypeScript Support
+
+Volter includes full TypeScript definitions:
+
+```typescript
+import {
+  Sessions,
+  Session,
+  SessionPayload,
+  e1T,
+  ServerError,
+  ErrorCodes,
+} from "volter";
+
+// Full type safety and IntelliSense support
+const sessions: Sessions = new Sessions();
+const session: Session = await sessions.get(token);
+```
+
+## Examples
+
+### Web Server Integration
+
+```typescript
+import { Sessions } from "volter";
+
+const sessions = new Sessions();
+
+// Middleware for session validation
+export async function requireAuth(req: Request) {
+  const token = req.headers.get("authorization")?.replace("Bearer ", "");
+  if (!token)
+    throw new ServerError("No token provided", {
+      code: ErrorCodes.AUTHENTICATION_FAILED,
+    });
+
+  const userId = await sessions.validate(token);
+  if (!userId)
+    throw new ServerError("Invalid token", { code: ErrorCodes.INVALID_TOKEN });
+
+  return userId;
+}
+```
+
+### Complete Auth Flow
+
+```typescript
+import { Sessions, e1T } from "volter";
+
+const sessions = new Sessions();
+const emailVerify = new e1T();
+
+// 1. Send verification code
+await emailVerify.send(email);
+
+// 2. Verify email and create session
+const isValid = await emailVerify.verify(email, code);
+if (isValid) {
+  const session = await sessions.create(userId);
+  return { token: session.token };
+}
+```
+
+## Contributing
+
+We welcome contributions! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/volter.git
+cd volter
+
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Build the project
+bun run build
+```
+
+## License
+
+The Modlin Distributable License (MDL) © [Modlin](https://modlin.dev) - See [LICENSE](LICENSE) file for details
+
+## Support
+
+- [Documentation](https://modlin.dev/volter/docs)
+- [Issue Tracker](https://github.com/modlin-dev/volter/issues)
+- [Email Support](mailto:volter@modlin.dev)

package/dist/crypto.js

@@ -1,2 +1 @@
-// @bun
-var c=Object.create;var{getPrototypeOf:s,defineProperty:o,getOwnPropertyNames:p}=Object;var u=Object.prototype.hasOwnProperty;var A=(e,t,r)=>{r=e!=null?c(s(e)):{};let n=t||!e||!e.__esModule?o(r,"default",{value:e,enumerable:!0}):r;for(let a of p(e))if(!u.call(n,a))o(n,a,{get:()=>e[a],enumerable:!0});return n};var d=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var m=(e,t)=>{for(var r in t)o(e,r,{get:t[r],enumerable:!0,configurable:!0,set:(n)=>t[r]=()=>n})};var x=import.meta.require;function f(e,t){return new Bun.CryptoHasher("sha256",t).update(e).digest("hex")}async function i(e){if(e){if(e instanceof CryptoKey)return e;if(e instanceof Uint8Array){if(e.length===32)return await crypto.subtle.importKey("raw",e,{name:"AES-GCM",length:256},!0,["encrypt","decrypt"]);return await crypto.subtle.importKey("raw",e,{name:"AES-GCM",length:256},!0,["encrypt","decrypt"])}if(e.length===64)return await crypto.subtle.importKey("raw",Uint8Array.fromHex(e),{name:"AES-GCM",length:256},!0,["encrypt","decrypt"]);else return await crypto.subtle.importKey("raw",Uint8Array.fromHex(f(e)),{name:"AES-GCM",length:256},!0,["encrypt","decrypt"])}else return await crypto.subtle.generateKey({name:"AES-GCM",length:256},!0,["encrypt","decrypt"])}async function C(e,t){let r=await crypto.subtle.exportKey(t,e);return new Uint8Array(r).toBase64()}async function K(){return await crypto.subtle.generateKey({name:"ECDSA",namedCurve:"P-256"},!0,["sign","verify"])}async function l(e){return await crypto.subtle.exportKey("jwk",e)}async function w(e,t){return await crypto.subtle.importKey("jwk",e,{name:"ECDSA",namedCurve:"P-256"},!0,t)}async function b(e,t){let r=new TextEncoder().encode(e),n=await crypto.subtle.sign({name:"ECDSA",hash:{name:"SHA-256"}},t,r);return new Uint8Array(n)}async function h(e,t,r){let n=new TextEncoder().encode(e);return await crypto.subtle.verify({name:"ECDSA",hash:{name:"SHA-256"}},r,t,n)}async function E(e,t){let n=new TextEncoder().encode(e),a=crypto.getRandomValues(new Uint8Array(12)),y=await crypto.subtle.encrypt({name:"AES-GCM",iv:a},await i(t),n);return{text:new Uint8Array(y).toHex(),iv:a,buffer:y}}async function S(e,t){let r=new TextDecoder,n=await crypto.subtle.decrypt({name:"AES-GCM",iv:e.iv},await i(t),Uint8Array.fromHex(e.text));return r.decode(n)}async function P(){return await crypto.subtle.generateKey({name:"RSA-OAEP",modulusLength:2048,publicExponent:new Uint8Array([1,0,1]),hash:{name:"SHA-256"}},!0,["encrypt","decrypt"])}async function U(e,t){let r=new TextEncoder().encode(e),n=await crypto.subtle.encrypt({name:"RSA-OAEP"},t,r);return new Uint8Array(n)}async function v(e,t){let r=await crypto.subtle.decrypt({name:"RSA-OAEP"},t,e);return new TextDecoder().decode(r)}export{h as verifySign,b as sign,P as keypair,w as importJWK,f as hash,K as generateECDSAKeyPair,C as exportKey,l as exportJWK,U as encrypt,v as decrypt,S as decipher,i as cryptoKey,E as cipher};
+var u=Object.create;var{getPrototypeOf:f,defineProperty:o,getOwnPropertyNames:c,getOwnPropertyDescriptor:A}=Object,s=Object.prototype.hasOwnProperty;var m=(e,t,r)=>{r=e!=null?u(f(e)):{};let n=t||!e||!e.__esModule?o(r,"default",{value:e,enumerable:!0}):r;for(let a of c(e))if(!s.call(n,a))o(n,a,{get:()=>e[a],enumerable:!0});return n},i=new WeakMap,x=(e)=>{var t=i.get(e),r;if(t)return t;if(t=o({},"__esModule",{value:!0}),e&&typeof e==="object"||typeof e==="function")c(e).map((n)=>!s.call(t,n)&&o(t,n,{get:()=>e[n],enumerable:!(r=A(e,n))||r.enumerable}));return i.set(e,t),t},g=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var C=(e,t)=>{for(var r in t)o(e,r,{get:t[r],enumerable:!0,configurable:!0,set:(n)=>t[r]=()=>n})};var K=(e,t)=>()=>(e&&(t=e(e=0)),t);var l=((e)=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(e,{get:(t,r)=>(typeof require<"u"?require:t)[r]}):e)(function(e){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+e+'" is not supported')});function d(e,t){return new Bun.CryptoHasher("sha256",t).update(e).digest("hex")}async function p(e){if(e){if(e instanceof CryptoKey)return e;if(e instanceof Uint8Array){if(e.length===32)return await crypto.subtle.importKey("raw",e,{name:"AES-GCM",length:256},!0,["encrypt","decrypt"]);return await crypto.subtle.importKey("raw",e,{name:"AES-GCM",length:256},!0,["encrypt","decrypt"])}if(e.length===64)return await crypto.subtle.importKey("raw",Uint8Array.fromHex(e),{name:"AES-GCM",length:256},!0,["encrypt","decrypt"]);else return await crypto.subtle.importKey("raw",Uint8Array.fromHex(d(e)),{name:"AES-GCM",length:256},!0,["encrypt","decrypt"])}else return await crypto.subtle.generateKey({name:"AES-GCM",length:256},!0,["encrypt","decrypt"])}async function b(e,t){let r=await crypto.subtle.exportKey(t,e);return new Uint8Array(r).toBase64()}async function h(){return await crypto.subtle.generateKey({name:"ECDSA",namedCurve:"P-256"},!0,["sign","verify"])}async function E(e){return await crypto.subtle.exportKey("jwk",e)}async function S(e,t){return await crypto.subtle.importKey("jwk",e,{name:"ECDSA",namedCurve:"P-256"},!0,t)}async function P(e,t){let r=new TextEncoder().encode(e),n=await crypto.subtle.sign({name:"ECDSA",hash:{name:"SHA-256"}},t,r);return new Uint8Array(n)}async function U(e,t,r){let n=new TextEncoder().encode(e);return await crypto.subtle.verify({name:"ECDSA",hash:{name:"SHA-256"}},r,t,n)}async function v(e,t){let n=new TextEncoder().encode(e),a=crypto.getRandomValues(new Uint8Array(12)),y=await crypto.subtle.encrypt({name:"AES-GCM",iv:a},await p(t),n);return{text:new Uint8Array(y).toHex(),iv:a,buffer:y}}async function B(e,t){let r=new TextDecoder,n=await crypto.subtle.decrypt({name:"AES-GCM",iv:e.iv},await p(t),Uint8Array.fromHex(e.text));return r.decode(n)}async function T(){return await crypto.subtle.generateKey({name:"RSA-OAEP",modulusLength:2048,publicExponent:new Uint8Array([1,0,1]),hash:{name:"SHA-256"}},!0,["encrypt","decrypt"])}async function H(e,t){let r=new TextEncoder().encode(e),n=await crypto.subtle.encrypt({name:"RSA-OAEP"},t,r);return new Uint8Array(n)}async function D(e,t){let r=await crypto.subtle.decrypt({name:"RSA-OAEP"},t,e);return new TextDecoder().decode(r)}export{U as verifySign,P as sign,T as keypair,S as importJWK,d as hash,h as generateECDSAKeyPair,b as exportKey,E as exportJWK,H as encrypt,D as decrypt,B as decipher,p as cryptoKey,v as cipher};