Package Exports

@blindflare/fortress
@blindflare/fortress/src/index.ts

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@blindflare/fortress) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

⚔️ @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.