@ryopc/koshi 0.2.0

package/bin/server.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// ============================================================================
+// koshi – Terminal-Native Decentralized SNS
+// Server Entry Point (Express + WebSocket)
+// License: MIT
+// ============================================================================
+// Starts the HTTP server with Express and attaches WebSocket support.
+// Reads configuration from environment variables.
+//
+// Usage:
+//   node bin/server.js
+//
+// Environment:
+//   PORT          - HTTP server port (default: 3000)
+//   DATABASE_URL  - PostgreSQL connection string (required)
+//   JWT_SECRET    - Secret key for JWT signing (required)
+//   NODE_ENV      - 'development' or 'production' (default: 'development')
+//   LOG_LEVEL     - 'debug', 'info', 'warn', 'error' (default: 'info' in prod, 'debug' in dev)
+// ============================================================================
+
+import { createServer } from 'node:http';
+import { app, logger } from '../src/index.js';
+import { initWebSocket, startHeartbeat } from '../src/ws/index.js';
+import { closePool } from '../src/db/pool.js';
+import { getOnlineCount } from '../src/ws/index.js';
+
+// Load .env file in development
+try {
+    const dotenv = await import('dotenv');
+    dotenv.config();
+} catch {
+    // dotenv not available; that's fine
+}
+
+const PORT = parseInt(process.env.PORT) || 3000;
+
+// Validate required environment variables
+const requiredEnvVars = ['DATABASE_URL', 'JWT_SECRET'];
+const missing = requiredEnvVars.filter((name) => !process.env[name]);
+
+if (missing.length > 0) {
+    logger.error(
+        { missing },
+        `Missing required environment variables: ${missing.join(', ')}`
+    );
+    console.error(`\n❌ Missing required environment variables:`);
+    missing.forEach((name) => {
+        console.error(`   - ${name}`);
+    });
+    console.error(`\n   Create a .env file or export these variables.`);
+    console.error(`   See .env.example for reference.\n`);
+    process.exit(1);
+}
+
+// Create HTTP server
+const server = createServer(app);
+
+// Initialize WebSocket server
+const wss = initWebSocket(server, logger);
+startHeartbeat();
+
+// Start listening
+server.listen(PORT, () => {
+    logger.info(
+        { port: PORT, env: process.env.NODE_ENV || 'development' },
+        `🚀 koshi server running on port ${PORT}`
+    );
+    console.log(`\n  ╔══════════════════════════════════════════════╗`);
+    console.log(`  ║        🏄 koshi board server v0.2.0         ║`);
+    console.log(`  ╠══════════════════════════════════════════════╣`);
+    console.log(`  ║  REST API : http://localhost:${PORT}/api            ║`);
+    console.log(`  ║  WebSocket: ws://localhost:${PORT}/ws               ║`);
+    console.log(`  ║  Health   : http://localhost:${PORT}/api/health      ║`);
+    console.log(`  ╠══════════════════════════════════════════════╣`);
+    console.log(`  ║  Environment: ${(process.env.NODE_ENV || 'development').padEnd(17)}║`);
+    console.log(`  ╚══════════════════════════════════════════════╝\n`);
+});
+
+// Graceful shutdown
+async function shutdown(signal) {
+    logger.info({ signal }, 'Shutdown signal received');
+
+    // Close WebSocket server
+    if (wss) {
+        wss.close(() => {
+            logger.info('WebSocket server closed');
+        });
+    }
+
+    // Close HTTP server
+    server.close(() => {
+        logger.info('HTTP server closed');
+    });
+
+    // Close database pool
+    try {
+        await closePool();
+    } catch (err) {
+        logger.error({ err }, 'Error closing database pool');
+    }
+
+    process.exit(0);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+
+// Expose server for testing
+export { server, wss };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@ryopc/koshi",
+  "version": "0.2.0",
+  "description": "Terminal-native decentralized SNS — koshi board",
+  "type": "module",
+  "bin": {
+    "kb": "bin/cli.js"
+  },
+  "scripts": {
+    "dev": "nodemon --exec node bin/server.js",
+    "dev:cli": "nodemon --exec node bin/cli.js",
+    "start": "node bin/server.js",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest || true",
+    "lint": "eslint . --ext .js || true",
+    "migrate": "node src/db/migrate.js",
+    "postinstall": "echo '🍄 Thank you for installing koshi! Type kb --help to get started.'"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^2.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^7.0.1",
+    "tweetnacl": "^1.0.3",
+    "ws": "^8.14.2"
+  },
+  "devDependencies": {
+    "cors": "^2.8.5",
+    "dotenv": "^16.3.1",
+    "eslint": "^8.50.0",
+    "express": "^4.18.2",
+    "express-rate-limit": "^7.1.1",
+    "helmet": "^7.0.0",
+    "jsonwebtoken": "^9.0.2",
+    "nodemon": "^3.0.1",
+    "pg": "^8.11.3",
+    "pino": "^8.14.1",
+    "pino-pretty": "^10.2.0",
+    "uuid": "^9.0.0"
+  },
+  "license": "MIT",
+  "author": "game_ryo",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ryopc/koshi"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "src/auth/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "sns",
+    "decentralized",
+    "terminal",
+    "cli",
+    "ed25519",
+    "nostr"
+  ]
+}

package/src/auth/ed25519.js

@@ -0,0 +1,91 @@
+// ============================================================================
+// koshi – Terminal-Native Decentralized SNS
+// Ed25519 Cryptographic Utilities
+// License: MIT
+// ============================================================================
+// Provides key generation, signing, and verification using the ed25519
+// elliptic curve. Wraps @noble/ed25519 for the heavy lifting (pure JS,
+// no native dependencies) and tweetnacl for compatibility.
+//
+// All keys and signatures are hex-encoded strings for storage and transport.
+// ============================================================================
+
+import * as ed from '@noble/ed25519';
+import nacl from 'tweetnacl';
+import { hexToBytes, bytesToHex } from './utils.js';
+
+/**
+ * Generate a new ed25519 keypair.
+ *
+ * @returns {{ publicKey: string, secretKey: string }}
+ *   publicKey  - 64-char hex string (32 bytes)
+ *   secretKey  - 128-char hex string (64 bytes, seed + public)
+ */
+export function generateKeypair() {
+    const keypair = nacl.sign.keyPair();
+    return {
+        publicKey: bytesToHex(keypair.publicKey),
+        secretKey: bytesToHex(keypair.secretKey),
+    };
+}
+
+/**
+ * Sign a message with the given secret key.
+ *
+ * @param {string} message - The message content to sign
+ * @param {string} secretKey - Hex-encoded ed25519 secret key (64 bytes = seed+pub or 32 bytes = seed)
+ * @returns {Promise<string>} Hex-encoded signature
+ */
+export async function signMessage(message, secretKey) {
+    const skBytes = hexToBytes(secretKey);
+    const msgBytes = new TextEncoder().encode(message);
+    const signature = await ed.sign(msgBytes, skBytes);
+    return bytesToHex(signature);
+}
+
+/**
+ * Verify a message signature against a public key.
+ *
+ * @param {string} message - The original message content
+ * @param {string} signature - Hex-encoded signature to verify
+ * @param {string} publicKey - Hex-encoded ed25519 public key (32 bytes)
+ * @returns {Promise<boolean>} Whether the signature is valid
+ */
+export async function verifySignature(message, signature, publicKey) {
+    try {
+        const msgBytes = new TextEncoder().encode(message);
+        const sigBytes = hexToBytes(signature);
+        const pkBytes = hexToBytes(publicKey);
+        return await ed.verify(sigBytes, msgBytes, pkBytes);
+    } catch (err) {
+        // If any input is malformed (wrong length, invalid hex, etc.), return false
+        return false;
+    }
+}
+
+/**
+ * Derive the public key from a secret key.
+ * Useful when the user only has their secret key stored.
+ *
+ * @param {string} secretKey - Hex-encoded ed25519 secret key (64 bytes)
+ * @returns {string} Hex-encoded public key (32 bytes)
+ */
+export function derivePublicKey(secretKey) {
+    const skBytes = hexToBytes(secretKey);
+    // tweetnacl's secretKey is 64 bytes: first 32 = seed, last 32 = public
+    // If given only a 32-byte seed, derive from that
+    if (skBytes.length === 32) {
+        const kp = nacl.sign.keyPair.fromSeed(skBytes);
+        return bytesToHex(kp.publicKey);
+    }
+    // 64-byte secret key: last 32 bytes are the public key
+    const publicKeyBytes = skBytes.slice(32, 64);
+    return bytesToHex(publicKeyBytes);
+}
+
+export default {
+    generateKeypair,
+    signMessage,
+    verifySignature,
+    derivePublicKey,
+};

package/src/auth/jwt.js

@@ -0,0 +1,100 @@
+// ============================================================================
+// koshi – Terminal-Native Decentralized SNS
+// JWT Authentication Utilities
+// License: MIT
+// ============================================================================
+// Wraps jsonwebtoken for token generation and verification.
+// Tokens encode the userId and expire after 24 hours.
+// ============================================================================
+
+import jwt from 'jsonwebtoken';
+
+/**
+ * Get the JWT secret from environment or use a development fallback.
+ * In production (PandaStack), JWT_SECRET is set via environment config.
+ *
+ * @returns {string}
+ */
+function getSecret() {
+    const secret = process.env.JWT_SECRET;
+    if (!secret) {
+        throw new Error(
+            'JWT_SECRET environment variable is not set. ' +
+            'Generate one with: node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'hex\'))"'
+        );
+    }
+    return secret;
+}
+
+/**
+ * Sign a JWT token for the given user.
+ *
+ * @param {object} payload - Token payload (must include userId)
+ * @param {string} payload.userId - The user's UUID
+ * @param {string} [payload.username] - Optional username for quick lookup
+ * @returns {string} Signed JWT token
+ */
+export function signToken(payload) {
+    const secret = getSecret();
+    const token = jwt.sign(
+        {
+            userId: payload.userId,
+            username: payload.username || null,
+            iat: Math.floor(Date.now() / 1000),
+        },
+        secret,
+        {
+            expiresIn: '24h',       // Tokens expire after 24 hours
+            algorithm: 'HS256',     // HMAC with SHA-256
+        }
+    );
+    return token;
+}
+
+/**
+ * Verify and decode a JWT token.
+ *
+ * @param {string} token - JWT token string
+ * @returns {{ userId: string, username: string|null, iat: number, exp: number }}
+ * @throws {Error} If token is invalid, expired, or malformed
+ */
+export function verifyToken(token) {
+    const secret = getSecret();
+    try {
+        const decoded = jwt.verify(token, secret, {
+            algorithms: ['HS256'],
+        });
+        return {
+            userId: decoded.userId,
+            username: decoded.username || null,
+            iat: decoded.iat,
+            exp: decoded.exp,
+        };
+    } catch (err) {
+        if (err instanceof jwt.TokenExpiredError) {
+            throw new Error('Token has expired. Please log in again.');
+        }
+        if (err instanceof jwt.JsonWebTokenError) {
+            throw new Error('Invalid token. Please log in again.');
+        }
+        throw err;
+    }
+}
+
+/**
+ * Decode a token without verifying the signature.
+ * Useful for extracting the userId from an expired token (e.g., for refresh).
+ * NOTE: Do NOT use this for authentication — always use verifyToken().
+ *
+ * @param {string} token
+ * @returns {object|null}
+ */
+export function decodeToken(token) {
+    try {
+        return jwt.decode(token);
+    } catch {
+        return null;
+    }
+}
+
+export default { signToken, verifyToken, decodeToken };

package/src/auth/utils.js

@@ -0,0 +1,46 @@
+// ============================================================================
+// koshi – Terminal-Native Decentralized SNS
+// Hex Encoding/Decoding Utilities
+// License: MIT
+// ============================================================================
+
+/**
+ * Convert a hex string to a Uint8Array (byte array).
+ * @param {string} hex - Hex-encoded string
+ * @returns {Uint8Array}
+ */
+export function hexToBytes(hex) {
+    if (typeof hex !== 'string') {
+        throw new TypeError('Expected a hex string');
+    }
+    if (hex.length % 2 !== 0) {
+        throw new Error('Hex string must have an even number of characters');
+    }
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+    }
+    return bytes;
+}
+
+/**
+ * Convert a Uint8Array (byte array) to a hex string.
+ * @param {Uint8Array} bytes - Byte array
+ * @returns {string}
+ */
+export function bytesToHex(bytes) {
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+
+/**
+ * Generate a random hex string of the given byte length.
+ * @param {number} byteLength - Number of random bytes
+ * @returns {string} Hex-encoded random string
+ */
+export function randomHex(byteLength = 32) {
+    const bytes = new Uint8Array(byteLength);
+    crypto.getRandomValues(bytes);
+    return bytesToHex(bytes);
+}