joopjs 2.0.5 → 2.1.0

package/.claude/skills/encryption.md

@@ -0,0 +1,265 @@
+# /encryption — JoopJS Encryption Services
+
+> Author: Kundan Singh
+
+All encryption services are imported from `'joopjs'`. Uses Web Crypto API (browser) or Node.js `crypto` module — no external dependencies required for basic usage. Advanced ciphers use `@noble/ciphers` and `@noble/curves`.
+
+---
+
+## AES-GCM Symmetric Encryption
+
+```ts
+import { JoopGcmService } from 'joopjs';
+const gcm = new JoopGcmService();
+
+// Generate a key (256-bit)
+const key = await gcm.generateKey();                   // CryptoKey
+
+// Encrypt
+const encrypted = await gcm.encrypt('Hello, World!', key);
+// { ciphertext: string, iv: string, tag: string } — all base64
+
+// Decrypt
+const plaintext = await gcm.decrypt(encrypted.ciphertext, key, encrypted.iv);
+// 'Hello, World!'
+
+// Encrypt objects
+const enc = await gcm.encryptObject({ amount: 5000, userId: 'u-001' }, key);
+const obj = await gcm.decryptObject(enc, key);         // { amount: 5000, userId: 'u-001' }
+
+// Key export/import for storage
+const exported = await gcm.exportKey(key);             // base64 string
+const imported = await gcm.importKey(exported);        // CryptoKey
+```
+
+**Use for:** Encrypting data at rest, local storage encryption, session data.
+
+---
+
+## RSA-OAEP Asymmetric Encryption
+
+```ts
+import { JoopRsaService } from 'joopjs';
+const rsa = new JoopRsaService();
+
+// Generate key pair (2048-bit)
+const keyPair = await rsa.generateKeyPair();
+// { publicKey: CryptoKey, privateKey: CryptoKey }
+
+// Encrypt with public key
+const encrypted = await rsa.encrypt('sensitive data', keyPair.publicKey);
+
+// Decrypt with private key
+const plaintext = await rsa.decrypt(encrypted, keyPair.privateKey);
+
+// Export keys for storage/transport
+const pubPem  = await rsa.exportPublicKey(keyPair.publicKey);   // PEM string
+const privPem = await rsa.exportPrivateKey(keyPair.privateKey); // PEM string (store securely)
+const pub2    = await rsa.importPublicKey(pubPem);
+const priv2   = await rsa.importPrivateKey(privPem);
+
+// Sign + verify
+const signature = await rsa.sign('message', keyPair.privateKey);
+const valid     = await rsa.verify('message', signature, keyPair.publicKey);  // true
+```
+
+**Use for:** Encrypting symmetric keys, signing tokens, server-to-client key exchange.
+
+---
+
+## X25519 Key Exchange (ECDH)
+
+```ts
+import { JoopX25519Service } from 'joopjs';
+const x25519 = new JoopX25519Service();
+
+// Both parties generate their own key pairs
+const aliceKeys = x25519.generateKeyPair();            // { privateKey: Uint8Array, publicKey: Uint8Array }
+const bobKeys   = x25519.generateKeyPair();
+
+// Exchange public keys, derive shared secret
+const aliceShared = x25519.deriveSharedSecret(aliceKeys.privateKey, bobKeys.publicKey);
+const bobShared   = x25519.deriveSharedSecret(bobKeys.privateKey, aliceKeys.publicKey);
+// aliceShared === bobShared (both Uint8Array, 32 bytes)
+
+// Convert to AES key for actual encryption
+const aesKey = await x25519.deriveAesKey(aliceShared);  // CryptoKey for AES-GCM
+
+// Serialise keys for transport
+const pubHex = x25519.toHex(aliceKeys.publicKey);
+const pubBack = x25519.fromHex(pubHex);
+```
+
+**Use for:** Perfect forward secrecy, establishing E2E encrypted channels between parties.
+
+---
+
+## End-to-End (E2E) Encryption Flow
+
+Combines X25519 key exchange + AES-GCM message encryption:
+
+```ts
+import { JoopX25519Service, JoopGcmService } from 'joopjs';
+const dh  = new JoopX25519Service();
+const gcm = new JoopGcmService();
+
+// --- Setup (once per session) ---
+const clientKeys = dh.generateKeyPair();
+const serverPubKey = /* received from server */ new Uint8Array(32);
+
+const sharedSecret = dh.deriveSharedSecret(clientKeys.privateKey, serverPubKey);
+const sessionKey   = await dh.deriveAesKey(sharedSecret);
+
+// --- Per message ---
+async function sendMessage(plaintext: string) {
+  return gcm.encrypt(plaintext, sessionKey);
+}
+
+async function receiveMessage(ciphertext: string, iv: string) {
+  return gcm.decrypt(ciphertext, sessionKey, iv);
+}
+```
+
+---
+
+## Hashing
+
+```ts
+import { JoopHashService } from 'joopjs';
+const hash = new JoopHashService();
+
+const sha256 = await hash.sha256('password123');        // hex string
+const sha512 = await hash.sha512('password123');
+const hmac   = await hash.hmac('message', 'secret');   // HMAC-SHA256
+
+// Password hashing (bcrypt-equivalent, using PBKDF2)
+const hashPwd   = await hash.hashPassword('mypassword'); // { hash, salt }
+const matches   = await hash.verifyPassword('mypassword', hashPwd.hash, hashPwd.salt);
+
+// Integrity checksums
+const checksum  = await hash.checksum(dataBuffer);      // SHA-256 hex
+const isValid   = await hash.verifyChecksum(dataBuffer, checksum);
+```
+
+---
+
+## Key Manager
+
+```ts
+import { JoopKeyManagerService } from 'joopjs';
+const km = new JoopKeyManagerService();
+
+// Store and retrieve keys by ID
+await km.store('session-key', aesKey, { expiresAt: Date.now() + 3600_000 });
+const key = await km.retrieve('session-key');          // CryptoKey | null
+km.revoke('session-key');
+km.revokeExpired();                                    // cleanup expired keys
+
+// Key rotation
+const newKey = await km.rotate('session-key');         // generates new, stores, returns old
+const exists = km.has('session-key');
+const listing = km.list();                             // [{ id, type, expiresAt, metadata }]
+```
+
+---
+
+## Secure Random
+
+```ts
+import { JoopRandomService } from 'joopjs';
+const rand = new JoopRandomService();
+
+const bytes   = rand.bytes(32);                        // Uint8Array, cryptographically secure
+const hex     = rand.hex(32);                          // 64-char hex string
+const uuid    = rand.uuid();                           // UUID v4
+const token   = rand.token(48);                        // URL-safe base64 token
+const integer = rand.integer(1, 100);                  // inclusive range
+const nonce   = rand.nonce();                          // 16-byte hex nonce
+```
+
+---
+
+## Field-Level Encryption (PII Protection)
+
+```ts
+import { JoopFieldEncryptionService } from 'joopjs';
+const ffe = new JoopFieldEncryptionService();
+
+const key = await ffe.generateKey();
+
+// Encrypt sensitive fields in an object
+const protected = await ffe.encryptFields(
+  { name: 'Alice', pan: '4111111111111111', dob: '1990-01-01', email: 'alice@bank.com' },
+  ['pan', 'dob'],  // fields to encrypt
+  key,
+);
+// { name: 'Alice', pan: '<encrypted>', dob: '<encrypted>', email: 'alice@bank.com' }
+
+const restored = await ffe.decryptFields(protected, ['pan', 'dob'], key);
+// original object restored
+
+// Deterministic encryption (searchable, order-preserving)
+const detEnc = await ffe.encryptDeterministic('4111111111111111', key);
+// same input always produces same output — can be used as index
+```
+
+---
+
+## TLS / Certificate Utilities
+
+```ts
+import { JoopCertificateService } from 'joopjs';
+const cert = new JoopCertificateService();
+
+const parsed = cert.parsePem(pemString);               // { subject, issuer, validity, fingerprint, extensions }
+const valid  = cert.isValid(pemString);                // checks expiry + basic format
+const chain  = cert.buildChain([leafPem, intermediatePem, rootPem]);
+const pinned = cert.pin(pemString);                    // SHA-256 fingerprint for certificate pinning
+const days   = cert.daysUntilExpiry(pemString);
+```
+
+---
+
+## Vault (Secret Store)
+
+```ts
+import { JoopVaultService } from 'joopjs';
+const vault = new JoopVaultService({ masterKey: 'master-key-from-env' });
+
+await vault.set('db-password', 'super-secret');
+const secret = await vault.get('db-password');         // 'super-secret'
+vault.delete('db-password');
+
+// Versioned secrets
+await vault.setVersion('api-key', 'v1', 'key-abc');
+await vault.setVersion('api-key', 'v2', 'key-xyz');
+const current = await vault.get('api-key');            // 'key-xyz' (latest)
+const v1      = await vault.getVersion('api-key', 'v1'); // 'key-abc'
+
+vault.rotate('api-key', 'key-new');                    // sets new version, keeps old versions
+```
+
+---
+
+## What Gets Published to npm
+
+Controlled by `"files"` in `package.json` — acts as an allowlist. Only these two are included:
+
+| Published to npm | Never published |
+|-----------------|----------------|
+| `dist/` — ESM + CJS + `.d.ts` for all 34 sub-paths | `src/` — TypeScript source |
+| `CHANGELOG.md` — release history | `tests/` — test suite |
+| | `scripts/` — release automation |
+| | `playground/` — Vite demo app |
+| | `.claude/` — Claude skills (including this file) |
+| | `.cursor/` — Cursor rules |
+| | `.windsurf/` — Windsurf rules |
+| | `GEMINI.md`, `AGENTS.md` — AI tool instructions |
+| | `tsup.config.ts`, `vitest.config.ts`, `tsconfig.json` |
+
+Source code, AI rules, and dev tooling are **never** published to npm.
+
+Verify the tarball contents before any publish:
+```bash
+npm pack --dry-run
+```

package/.claude/skills/finance.md

@@ -0,0 +1,248 @@
+# /finance — JoopJS Finance Services
+
+> Author: Kundan Singh
+
+All finance services are imported from `'joopjs'`. Instantiate as plain singletons.
+
+---
+
+## Mutual Fund
+
+```ts
+import { JoopMutualFundService } from 'joopjs';
+const mf = new JoopMutualFundService();
+
+mf.registerFund({ id: 'EQ001', name: 'Equity Growth Fund', category: 'equity', currentNav: 45.50, currency: 'USD' });
+mf.updateNav('EQ001', 48.00);
+
+const holding = mf.invest('EQ001', 'inv-001', 5000);
+// holding.units = 5000/45.50, holding.averageCostNav = 45.50
+
+const redemption = mf.redeem('EQ001', 'inv-001', 50);   // redeem 50 units
+// redemption.proceeds, redemption.realizedGain
+
+mf.updateNav('EQ001', 48.00);                           // refreshes holding.currentValue
+const h = mf.getHolding('EQ001', 'inv-001');
+// h.currentValue, h.unrealizedGain, h.returnPercent
+
+// SIP (Systematic Investment Plan)
+const sip = mf.createSip('EQ001', 'inv-001', 500, 'monthly', Date.now(), {
+  endDate: Date.now() + 365 * 86_400_000,
+});
+mf.executeSip(sip.id);                                  // executes and advances nextExecutionDate
+mf.pauseSip(sip.id);  mf.resumeSip(sip.id);  mf.cancelSip(sip.id);
+```
+
+**Frequencies:** `'weekly'` | `'monthly'` | `'quarterly'`
+**Fund categories:** `'equity'` | `'debt'` | `'hybrid'` | `'money-market'` | `'index'` | `'etf'`
+**Key types:** `JoopMutualFund`, `JoopFundHolding`, `JoopFundRedemption`, `JoopSip`, `JoopSipStatus`, `JoopFundCategory`
+
+---
+
+## Budget Tracker
+
+```ts
+import { JoopBudgetTrackerService } from 'joopjs';
+const budget = new JoopBudgetTrackerService();
+
+budget.createBudget({ name: 'Monthly Budget', period: 'monthly', currency: 'USD', startDate: Date.now() });
+budget.addCategory(budgetId, { name: 'Food', limit: 500 });
+budget.recordSpend(budgetId, categoryId, 120, 'Groceries');
+const report = budget.getReport(budgetId);
+// { categories: [{ name, limit, spent, remaining, overBudget }], totalLimit, totalSpent }
+const alerts = budget.getAlerts(budgetId, 80);         // categories at >80% utilization
+```
+
+**Key types:** `JoopBudget`, `JoopBudgetCategory`, `JoopBudgetReport`, `JoopBudgetAlert`
+
+---
+
+## Portfolio Tracker
+
+```ts
+import { JoopPortfolioTrackerService } from 'joopjs';
+const portfolio = new JoopPortfolioTrackerService();
+
+portfolio.createPortfolio({ name: 'My Investments', currency: 'USD', userId: 'u-001' });
+portfolio.addHolding(pid, { symbol: 'AAPL', name: 'Apple Inc', quantity: 10, avgCostPrice: 150, currentPrice: 175, assetClass: 'equity' });
+portfolio.updatePrice(pid, 'AAPL', 180);
+const summary = portfolio.getSummary(pid);
+// { totalInvested, currentValue, totalGain, gainPercent, holdings[] }
+portfolio.rebalance(pid, { AAPL: 60, BONDS: 40 });      // target allocation %
+```
+
+---
+
+## Tax Calculator
+
+```ts
+import { JoopTaxCalculatorService } from 'joopjs';
+const tax = new JoopTaxCalculatorService();
+
+tax.setTaxProfile({ jurisdiction: 'US', filingStatus: 'single', year: 2025 });
+tax.addSlab(5000, 0);    tax.addSlab(45000, 12);   tax.addSlab(95000, 22);
+const liability = tax.calculate(75000);              // { taxableIncome, taxLiability, effectiveRate, slabs }
+const capitalGain = tax.calcCapitalGainsTax(50000, 12, 'US');
+```
+
+---
+
+## Cash Flow Forecaster
+
+```ts
+import { JoopCashFlowForecastService } from 'joopjs';
+const cf = new JoopCashFlowForecastService();
+
+cf.addCashFlow({ name: 'Salary', amount: 5000, frequency: 'monthly', startDate: Date.now(), type: 'inflow' });
+cf.addCashFlow({ name: 'Rent',   amount: 1500, frequency: 'monthly', startDate: Date.now(), type: 'outflow' });
+const forecast = cf.forecast(Date.now(), Date.now() + 90 * 86_400_000);
+// { periods: [{ date, inflows, outflows, netCashFlow, runningBalance }], summary }
+const summary = cf.getSummary(Date.now(), Date.now() + 90 * 86_400_000);
+```
+
+---
+
+## Expense Tracker
+
+```ts
+import { JoopExpenseTrackerService } from 'joopjs';
+const exp = new JoopExpenseTrackerService();
+
+exp.add({ userId: 'u-001', amount: 45.50, category: 'dining', description: 'Lunch', date: Date.now() });
+const monthly = exp.getByPeriod('u-001', startTs, endTs);
+const byCategory = exp.getByCategory('u-001', 'dining', startTs, endTs);
+const totals = exp.getTotals('u-001', startTs, endTs);  // { total, byCategory: Map }
+exp.setLimit('u-001', 'dining', 300);                   // monthly limit
+const limit = exp.checkLimit('u-001', 'dining');        // { limit, spent, exceeded }
+```
+
+---
+
+## Goal Savings
+
+```ts
+import { JoopGoalSavingsService } from 'joopjs';
+const goals = new JoopGoalSavingsService();
+
+const goal = goals.create({ name: 'Emergency Fund', targetAmount: 10000, currency: 'USD', targetDate: Date.now() + 365 * 86_400_000 });
+goals.contribute(goal.id, 500);
+const progress = goals.getProgress(goal.id);
+// { current, target, percent, remaining, projectedDate, onTrack }
+const monthly = goals.getSuggestedContribution(goal.id);  // amount needed per month to hit target
+```
+
+---
+
+## Net Worth
+
+```ts
+import { JoopNetWorthService } from 'joopjs';
+const nw = new JoopNetWorthService();
+
+nw.addAsset({ id: 'home', name: 'House', category: 'real-estate', value: 500000, currency: 'USD' });
+nw.addLiability({ id: 'mortgage', name: 'Mortgage', category: 'loans', balance: 350000, currency: 'USD' });
+const snapshot = nw.getSnapshot();
+// { totalAssets, totalLiabilities, netWorth, assetBreakdown, liabilityBreakdown }
+nw.updateAsset('home', { value: 520000 });
+const history = nw.getHistory();                       // snapshots over time
+```
+
+---
+
+## Investment Calculator
+
+```ts
+import { JoopInvestmentCalculatorService } from 'joopjs';
+const calc = new JoopInvestmentCalculatorService();
+
+const compound = calc.compoundInterest(10000, 8, 10);    // { principal, rate, years, finalAmount, interest }
+const sip = calc.sipReturns(5000, 12, 15);               // { monthlyAmount, months, annualRate, maturityAmount }
+const lumpsum = calc.lumpsumReturns(100000, 12, 10);
+const emi = calc.emiCalc(500000, 8.5, 20);               // { emi, totalPayment, totalInterest }
+const rule72 = calc.rule72(8);                           // 9 years to double
+```
+
+---
+
+## Financial Report Generator
+
+```ts
+import { JoopFinancialReportService } from 'joopjs';
+const reports = new JoopFinancialReportService();
+
+reports.addEntry({ type: 'income', category: 'salary', amount: 5000, date: Date.now() });
+reports.addEntry({ type: 'expense', category: 'rent', amount: 1500, date: Date.now() });
+const pnl = reports.getPnLStatement(startTs, endTs);
+// { income, expenses, grossProfit, operatingExpenses, netProfit }
+const balance = reports.getBalanceSheet();
+const cashFlow = reports.getCashFlowStatement(startTs, endTs);
+```
+
+---
+
+## Currency Converter
+
+```ts
+import { JoopCurrencyConverterService } from 'joopjs';
+const fx = new JoopCurrencyConverterService();
+
+fx.setRate('USD', 'EUR', 0.92);
+fx.setRate('USD', 'INR', 83.5);
+const result = fx.convert(1000, 'USD', 'EUR');         // { amount: 920, from, to, rate, timestamp }
+const multi = fx.convertMultiple(1000, 'USD', ['EUR', 'INR', 'GBP']);
+const history = fx.getRateHistory('USD', 'EUR');       // historical rates
+```
+
+---
+
+## Loan Calculator
+
+```ts
+import { JoopLoanCalculatorService } from 'joopjs';
+const lc = new JoopLoanCalculatorService();
+
+const emi = lc.calculateEmi(500000, 8.5, 20);          // { emi, totalPayment, totalInterest, schedule }
+const eligibility = lc.checkEligibility({ income: 80000, obligations: 20000, rate: 8.5, tenureYears: 20 });
+// { eligible, maxLoanAmount, maxEmi }
+const prepay = lc.calcPrepaymentImpact(500000, 8.5, 20, { amount: 100000, afterMonth: 24 });
+// { newTenure, interestSaved, reducedEmi }
+```
+
+---
+
+## Fixed Deposit
+
+```ts
+import { JoopFixedDepositService } from 'joopjs';
+const fd = new JoopFixedDepositService();
+
+const deposit = fd.create({ principal: 50000, annualRate: 6.5, tenureMonths: 12, currency: 'USD', compoundFrequency: 'quarterly' });
+const maturity = fd.calcMaturity(deposit.id);          // { maturityAmount, interestEarned, effectiveRate }
+fd.prematureClose(deposit.id, 0.5);                    // 0.5% penalty
+const due = fd.getMaturing(30 * 86_400_000);            // maturing in 30 days
+```
+
+---
+
+## What Gets Published to npm
+
+Controlled by `"files"` in `package.json` — acts as an allowlist. Only these two are included:
+
+| Published to npm | Never published |
+|-----------------|----------------|
+| `dist/` — ESM + CJS + `.d.ts` for all 34 sub-paths | `src/` — TypeScript source |
+| `CHANGELOG.md` — release history | `tests/` — test suite |
+| | `scripts/` — release automation |
+| | `playground/` — Vite demo app |
+| | `.claude/` — Claude skills (including this file) |
+| | `.cursor/` — Cursor rules |
+| | `.windsurf/` — Windsurf rules |
+| | `GEMINI.md`, `AGENTS.md` — AI tool instructions |
+| | `tsup.config.ts`, `vitest.config.ts`, `tsconfig.json` |
+
+Source code, AI rules, and dev tooling are **never** published to npm.
+
+Verify the tarball contents before any publish:
+```bash
+npm pack --dry-run
+```