@blindflare/fortress

⚔️ @blindflare/fortress

Modular implementation of core Blindflare protocol primitives (handshake, envelopes, symmetric + hybrid crypto, sessions & signatures) in TypeScript. Works in Node (>=16) and modern browsers (WebCrypto fallback) – hex‑only, zero PEM fuss.

✨ Features

• 🔐 AES‑256‑GCM symmetric encryption (12‑byte IV, AAD binding)
• 🛰️ Blindflare handshake helpers (HELLO / HELLO_ACK, session key wrap)
• 🧬 ECIES‑like hybrid encryption over secp256k1 (ephemeral shared secret)
• ✍️ ECDSA signatures (secp256k1 + SHA‑256) – DER hex
• 🪪 Time‑bound session keys, rotation & token wrapping (symmetric / ECC)
• 🧪 Transaction helpers (serialize / encrypt / decrypt) + envelopes
• 🧂 PBKDF2‑SHA512 hashing & verification
• 🎲 Secure random token + key generation
• 🧹 Memory wipe helper
• 🌐 Node & Browser compatibility (pure JS SHA‑256 fallback)

📦 Install

npm install @blindflare/fortress
# or pnpm add @blindflare/fortress

🚀 Quick Start

import blindflare, { Fortress } from '@blindflare/fortress';

// Singleton
const key = blindflare.generateKey();
const enc = blindflare.encrypt('hello', key);
const dec = blindflare.decrypt(enc, key);

// Custom instance & session
const svc = new Fortress();
const session = svc.generateSessionKey({ user: 'alice', expirationMinutes: 60 });

🔑 Key & Session Flow (Blindflare Style)

• Client derives / provides secp256k1 key (hex public key)
• HELLO: client signs canonical string; server returns HELLO_ACK + ECIES session key
• Subsequent TX envelopes encrypted (symmetric or ECC) with versioned meta (kid, nonce, ts)
• Session key rotation optional; tokens optionally encrypted / rewrapped

🧷 Symmetric Encryption

const key = blindflare.generateKey(); // hex
const payload = { secret: true };
const encrypted = blindflare.encrypt(JSON.stringify(payload), key);
const decrypted = JSON.parse(blindflare.decrypt(encrypted, key));

🛰️ ECC Hybrid (Ephemeral secp256k1)

const { publicKey, privateKey } = blindflare.generateKeyPair();
const encECC = blindflare.encryptWithECC('top secret', publicKey);
const plain = blindflare.decryptWithECC(encECC, privateKey);

✍️ Signatures

const { publicKey, privateKey } = blindflare.generateKeyPair();
const sig = blindflare.signData('message', privateKey);
const ok = blindflare.verifySignature('message', sig, publicKey);

🪪 Session Tokens

const sessionKey = blindflare.generateSessionKey({ user: 'alice', expirationMinutes: 120 });
const token = blindflare.createSessionToken(sessionKey, { role: 'admin' });
const claims = blindflare.verifySessionToken(token, sessionKey);

📦 Transactions

import type { BlindflareMeta } from '@blindflare/fortress';
const meta: BlindflareMeta = { type: 'TRANSACTION', version: '1.0.0' };
const payload = { amount: 42 };

// Symmetric
const tx = blindflare.encryptTransaction(payload, key, meta);
const obj = blindflare.decryptTransaction<typeof payload>(tx, key);

// ECC hybrid
const { publicKey, privateKey } = blindflare.generateKeyPair();
const txECC = blindflare.encryptTransactionWithECC(payload, publicKey, meta);
const objECC = blindflare.decryptECCTransaction<typeof payload>(txECC, privateKey);

📩 Envelopes

Wrap arbitrary JSON with deterministic AAD context (kid, nonce, ts, type) for tamper‑resistant transport.

const envelope = blindflare.createEnvelope({ ver: '1', kid: 'abcd1234', ts: Date.now(), nonce: 'ff00aa', type: 'TX' }, { foo: 'bar' }, key);
const opened = blindflare.openEnvelope(envelope, key);

🧂 Hashing

const { hash, salt } = blindflare.hashData('password123');
const ok = blindflare.verifyHash('password123', hash, salt);

🔐 Types (Essentials)

interface EncryptedData { data: string; iv: string; tag?: string; }
interface EncryptedECCData extends EncryptedData { ephemeralPublicKey: string; }
interface SessionKey { id: string; key: string; sessionId: string; createdAt: Date; expiresAt: Date; isActive: boolean; user?: string; }

🌐 Browser Notes

• Uses WebCrypto random + pure JS SHA‑256 fallback when Node crypto.createHash unavailable.
• Avoids Node buffers in public API (hex & base64 only). If you need Buffer, convert manually in Node.

⚠️ Security Considerations

• Example flows omit authentication of peer public keys – validate before trust.
• DER signatures returned (ECDSA) – normalize if forwarding to other libs.
• For production mnemonic / key derivation, use hardened HD derivation (BIP32/BIP39) outside this module.

🧪 Testing

bun test

🗺️ Roadmap

• Optional Ed25519 profile
• WASM accelerated hashing
• Streaming large object encryption

📄 License

MIT © Sierra

Made with ⚔️ & caffeine.