@suhbro/core

A framework-agnostic TypeScript library for encoding/decoding shareable message chains.

Installation

npm install @suhbro/core

Features

• Chain Encoding - DEFLATE-raw compression + base64url for URL-safe chains
• Encryption - AES-256-GCM with PBKDF2 (100k iterations)
• Signatures - djb2 hash for content-bound identity
• Polls - Distributed voting with vote tallying
• Chaos Engine - Seeded random greeting generator

Requirements

• Node.js 20+ or modern browser with Web Crypto API and CompressionStream support

Usage

Chain Encoding/Decoding

import { createChain, encodeChain, decodeChain, addReplyToChain } from '@suhbro/core';

// Create a chain (with optional timestamp)
const node = createChain({
  title: 'Hello World',
  description: 'My first chain',
  passphrase: 'secret123',
  timestamp: Date.now()
});

// Encode to URL-safe string
const encoded = await encodeChain([node]);

// Decode back
const { nodes } = await decodeChain(encoded);

// Add a reply
const withReply = await addReplyToChain({
  payload: encoded,
  title: 'Reply',
  description: 'This is a reply'
});

Encryption

import { encryptNode, decryptNode } from '@suhbro/core';

const node = { t: 'Secret Message', d: 'Confidential content' };

// Encrypt
const encrypted = await encryptNode(node, 'password123');

// Decrypt
const decrypted = await decryptNode(encrypted, 'password123');

Signatures

import { generateNodeSignature, verifyNodeSignature, getAuthorFingerprint } from '@suhbro/core';

const node = { t: 'Signed content' };
const passphrase = 'my-secret';

// Generate signature
node.s = generateNodeSignature(passphrase, node);

// Verify signature
const isValid = verifyNodeSignature(passphrase, node);

// Get author fingerprint (4-char ID)
const fingerprint = getAuthorFingerprint(passphrase);

Polls

import { createPoll, addVote, getPollResults, encodeChain } from '@suhbro/core';

// Create a poll
const poll = createPoll('Favorite color?', ['Red', 'Blue', 'Green']);
let encoded = await encodeChain([poll]);

// Add votes
encoded = await addVote(encoded, 0, 'Alice');
encoded = await addVote(encoded, 1, 'Bob');

// Get results
const results = await getPollResults(encoded);
// { question: 'Favorite color?', options: [...], counts: [1, 1, 0], total: 2 }

Chaos Engine

import { generateFromSeed, generateFromCategory, getCategories } from '@suhbro/core';

// Generate deterministic greeting from seed
const greeting = generateFromSeed('user-123');

// Generate from specific category
const formalGreeting = generateFromCategory('user-123', 'formal');

// Available categories
const categories = getCategories();
// ['casual', 'warm', 'hype', 'silly', 'formal', 'cosmic', 'internet', 'animal']

API Reference

Chain

| Function | Description | |----------|-------------| | createChain(options) | Create a new chain node | | encodeChain(nodes) | Compress nodes to URL-safe string | | decodeChain(encoded) | Decompress back to ChainData | | addReplyToChain(options) | Add a reply to existing chain |

Encryption

| Function | Description | |----------|-------------| | encryptNode(node, passcode) | Encrypt a node with AES-256-GCM | | decryptNode(node, passcode) | Decrypt an encrypted node |

Signatures

| Function | Description | |----------|-------------| | generateNodeSignature(passphrase, node, parentHash?) | Generate djb2 signature | | verifyNodeSignature(passphrase, node, parentHash?) | Verify signature | | getAuthorFingerprint(passphrase) | Get stable 4-char author ID |

Polls

| Function | Description | |----------|-------------| | createPoll(question, options, passphrase?) | Create a poll node | | addVote(payload, voteIndex, voterName?, passphrase?) | Add vote to chain | | getPollResults(payload) | Get vote counts |

Chaos Engine

| Function | Description | |----------|-------------| | generateFromSeed(seed) | Deterministic greeting from seed | | generateFromCategory(seed, category) | Greeting from specific category | | getCategories() | List all 8 categories |

Development

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Watch mode
npm run dev

License

MIT