Koshi Documentation

Welcome to the Koshi documentation. This guide covers everything from installation to the full API reference. Koshi is a terminal-native, decentralized social network powered by ed25519 cryptography.

Installation

Koshi requires Node.js 18+ and PostgreSQL 15+ (for the server). The CLI can be installed independently.

Global Install (CLI only)

# From npm (requires package to be published)
$ npm install -g @ryopc/koshi

# Or from source
$ git clone https://github.com/ryopc/koshi.git
$ cd koshi
$ npm install
$ npm link

Server Installation

$ git clone https://github.com/ryopc/koshi.git
$ cd koshi
$ npm install

# Create PostgreSQL database
$ createdb koshi

# Run database migrations
$ DATABASE_URL=postgresql://user:pass@localhost:5432/koshi \
  JWT_SECRET=your-secret \
  node src/db/migrate.js

# Start the server
$ DATABASE_URL=postgresql://user:pass@localhost:5432/koshi \
  JWT_SECRET=your-secret \
  node bin/server.js

Or use a .env file:

# .env
DATABASE_URL=postgresql://user:pass@localhost:5432/koshi
JWT_SECRET=your-secret-change-in-production
PORT=3000
NODE_ENV=development

Quick Start

Once the server is running and you have the CLI installed:

# Register a new account (generates ed25519 keypair)
$ kb register alice
✔ Registration successful!

# Post to the board
$ kb post "Hello, koshi! 🌊"
✔ Post created!

# View your feed
$ kb feed --limit=10
📋 Koshi Board Feed

# Follow someone
$ kb follow bob

# Live stream
$ kb realtime

Configuration

Credentials are stored in ~/.config/koshi/config.json and ~/.snsrc. The CLI reads these automatically.

CLI Reference

The kb command is the gateway to Koshi. All commands are terminal-native with colored output via Chalk and loading spinners via Ora.

$ kb --help

  🏄 koshi — Terminal-Native Decentralized SNS
  Version 1.2.0

  Commands:
    register   Create a new account with ed25519 keypair
    login      Authenticate using existing keypair
    whoami     Show your profile information
    post       Create a new post on the koshi board
    feed       Display your post feed
    follow     Follow a user
    unfollow   Unfollow a user
    dm         Send a direct message
    dms        View your direct messages
    profile    View a user profile
    search     Search users by username
    realtime   Connect to the real-time event stream
    chat       Real-time interactive DM chat
    edit-profile  Update your own profile
    admin      Admin: users, delete-user, grant, revoke
    help       Show this help message

Auth Commands

kb register <username>

Creates a new account. Generates an ed25519 keypair locally, sends the public key to the server, and stores credentials in ~/.config/koshi/config.json.

$ kb register alice
⠋ Generating ed25519 keypair...
✔ Registration successful!

  Username:  alice
  User ID:   e7d00463-38f8-4d85-8231-6762bb988f7d
  Token:     eyJhbGciOiJIUzI1NiIs...
  ✓ You are now logged in.

kb login <username>

Authenticates using an existing keypair stored in ~/.snsrc. Signs a challenge with your secret key to prove identity.

$ kb login alice
⠋ Signing authentication challenge...
✔ Login successful!

Post Commands

kb post <message>

Creates a new post on the Koshi board. Content is signed with your ed25519 key. Max 2000 characters.

$ kb post "Hello, koshi! 🌊"
⠋ Signing and posting...
✔ Post created!

  ID:      550e8400-e29b-41d4-a716-446655440000
  Posted:  7/14/2026, 2:30:00 PM

kb feed [--limit=N]

Displays the post feed. Shows posts from users you follow plus your own. Falls back to global feed when not authenticated.

$ kb feed --limit=5
  📋 Koshi Board Feed (5 posts)
  ────────────────────────────────────────────
  Alice @alice
  7/14/2026, 2:30:00 PM
  Hello, koshi! 🌊

Social Commands

kb follow <username>

$ kb follow bob
⠋ Following @bob...
✔ You are now following @bob!

kb unfollow <username>

$ kb unfollow bob
⠋ Unfollowing @bob...
✔ Unfollowed @bob.

kb profile [username]

View a user's public profile. Defaults to your own profile when no username is given.

$ kb profile alice

  👤 Profile
  ────────────────────────────────────────
  Username:        alice
  Display Name:    Alice
  Bio:             Building the terminal future
  Followers:       42
  Following:       12
  Joined:          7/14/2026

kb search <query>

Search users by username or display name. Query must be at least 2 characters.

$ kb search ali
  🔍 Search Results for "ali"
  ──────────────────────────────────
  alice — Alice

kb whoami

Show your own profile information.

$ kb whoami
  Username:        alice
  Followers:       42
  Following:       12
  Joined:          7/14/2026

Multi-Account Management 🆕

Koshi v2.0 supports managing multiple accounts from a single CLI configuration. Each account has its own ed25519 keypair, Nostr keys (optional), and JWT token.

kb register <username>

Create a new account. The new account is automatically added to the multi-account config and set as active.

kb login [username]

Without arguments, shows an interactive list of saved accounts to choose from. With a username, logs in to that specific account.

$ kb login

  🔑 アカウントを選択
  1. alice ✓ ← 現在
  2. bob   ○
  0. キャンセル

  番号を選択 (1-2): 2
  → bob を選択しました

kb switch [username]

Switch between saved accounts without re-authenticating. Interactive selection if no username is given.

kb accounts

List all saved accounts and their login status.

$ kb accounts

  📋 アカウント一覧 (2件)
  1. alice  ✓ ログイン済  ← 現在のアカウント
  2. bob    未ログイン

kb account remove <username>

Remove a saved account from the local configuration. Shows confirmation prompt before deleting.

$ kb account remove bob
  🗑️ @bob をローカル設定から削除してもよろしいですか？ (y/N): y
✔ @bob をローカル設定から削除しました。

Account credentials are stored in ~/.config/koshi/config.json in the following format:

{
  "version": "2.0.2",
  "activeUsername": "alice",
  "accounts": {
    "alice": {
      "userId": "uuid",
      "username": "alice",
      "publicKey": "hex...",
      "secretKey": "hex...",
      "token": "jwt...",
      "nostr": { ... }
    },
    "bob": { ... }
  }
}

kb edit-profile --display-name=... --bio=... --avatar-url=...

Update your own profile fields. Only include the flags you want to change.

$ kb edit-profile --display-name="Alice" --bio="Building the terminal future"
⠋ Updating profile...
✔ Profile updated!

  Username:        alice
  Display Name:    Alice
  Bio:             Building the terminal future

Available flags:

--display-name="Your Name"   # Max 64 characters
--bio="About you"            # Max 500 characters
--avatar-url="https://..."   # Max 512 characters, must be valid URL

Message Commands

kb dm <username> <message>

Send a signed direct message to another user.

$ kb dm bob "Hey, how's it going?"
⠋ Sending DM to @bob...
✔ DM sent to @bob!
  ID: 550e8400-e29b-41d4-a716-446655440001

kb dms [--unread] [--limit=N]

View your DM inbox. Use --unread to show only unread messages.

$ kb dms --unread

  📨 Unread Messages (2 messages)
  ────────────────────────────────────────────
  ← From: Bob @bob
  7/14/2026, 2:35:00 PM
  Hey Alice! Welcome to koshi 🎉

Realtime Command

kb realtime

Connects to the WebSocket event stream for live updates. Shows new posts, DMs, and user online/offline events in real time.

$ kb realtime
  📡 Connecting to realtime feed...
  ✓ Connected! Waiting for new posts...

  📝 New Post
  bob 2:40:00 PM
  Just joined koshi!

Press Ctrl+C to disconnect.

Interactive Chat Command

kb chat <username>

Starts an interactive real-time DM session with another user. Messages are sent and received via WebSocket in real time, with ed25519 signatures for authenticity.

$ kb chat bob
  💬 Live Chat with bob
  Connect to real-time DMs. Type your message and press Enter.
  Type /exit or press Ctrl+C to quit.

  ✓ Connected!

  🟢 bob is now online
  > Hey Bob! How are you?
  Bob: Hey Alice! I'm great, thanks!
  > 

Features:

• Real-time message delivery via WebSocket
• Messages signed with your ed25519 key
• See when the other user is online/offline
• Type /exit or press Ctrl+C to quit

Admin Commands

kb admin users

List all registered users with their stats (posts, followers, join date). Admin privileges required.

$ kb admin users
  👥 All Users (3 total)
  ──────────────────────────────────────────────────────
  alice [ADMIN] — Alice
    ID: e7d00463-...  |  Posts: 42  |  Followers: 12  |  Joined: 7/14/2026

  bob — Bob
    ID: f8e11574-...  |  Posts: 7  |  Followers: 3  |  Joined: 7/14/2026

kb admin user <id|username>

View detailed information about a specific user, including public key, DM count, and admin status. Accepts either a UUID or a username.

kb admin delete-user <username>

Permanently delete a user account and all associated data (posts, follows, DMs — cascade deleted). Uses interactive confirmation.

$ kb admin delete-user bob
  ⚠️  WARNING: This will permanently delete the user and all their data.
  This action cannot be undone.

  Target: @bob
  Type the username to confirm: bob
✔ User @bob has been permanently deleted.

Use --force flag to skip confirmation for scripting.

kb admin grant <username>

Grant admin privileges to a user.

$ kb admin grant bob
✔ @bob is now an admin!

kb admin revoke <username>

Revoke admin privileges from a user.

$ kb admin revoke bob
✔ Admin privileges removed from @bob.

CLI Environment Variables

Nostr Integration 🆕

Koshi v2.0 integrates with the Nostr protocol, allowing you to bridge your koshi identity with the broader Nostr network. You can generate Nostr keys, push posts to relays, and pull events from the Nostr ecosystem.

Key Management

Generate or import Nostr keys (nsec/npub) directly from the CLI:

# Generate a new Nostr keypair
$ kb nostr key generate
✔ Nostr keypair generated and saved!

  npub: npub1...
  nsec: nsec1...

# Import an existing nsec key
$ kb nostr key import nsec1...

# Show current keys
$ kb nostr key show

# Display public key (npub)
$ kb nostr npub

Pushing Posts to Nostr

Publish your koshi board posts to Nostr relays as kind 1 (short text note) events:

$ kb nostr push --limit=20
✔ 5/20 posts published to Nostr!

  📡 Relay Results:
    • wss://relay.damus.io ✓ 5 published
    • wss://relay.nostr.band ✓ 5 published

Pulling Events from Nostr

Fetch Nostr events and display them in koshi format:

$ kb nostr pull --limit=50
✔ Found 12 Nostr events!

  📡 Nostr Events (12件)
  ────────────────────────────────────────────
  nostr:a1b2c3d4 ...
  Hello from Nostr!

Relay Management

Add, remove, list, and test Nostr relay connections:

$ kb nostr relay list
  🌐 Nostr Relays (4件)
    • wss://relay.damus.io
    • wss://relay.nostr.band

$ kb nostr relay add wss://relay.example.com
✓ リレーを追加しました: wss://relay.example.com

$ kb nostr relay test wss://relay.damus.io
✓ wss://relay.damus.io  Latency: 120ms

P2P Sync 🆕

Koshi v2.0 introduces peer-to-peer synchronization powered by the Hypercore protocol stack. Your posts and DMs are replicated across connected peers using hyperswarm DHT for discovery, enabling offline-first and decentralized data distribution.

Starting a P2P Node

Launch a P2P node to start syncing with peers:

$ kb p2p start
✔ P2P node started!

  Status:     Running
  Posts:      42
  DMs:        12
  Peers:      3

$ kb p2p status
  Status:     Running
  Posts:      42
  DMs:        12
  Peers:      3

Data Sync

View synced data and manage replication:

# View synced posts
$ kb p2p sync

# View synced DMs
$ kb p2p dms

# Stop the P2P node
$ kb p2p stop
✔ P2P node stopped.

Configuration

P2P settings are stored in ~/.config/koshi/config.json under the p2p key:

{
  "p2p": {
    "corestorePath": "/home/user/.config/koshi/corestore",
    "autoSync": false,
    "port": 0
  }
}

Enable automatic P2P startup by setting "autoSync": true in the config.

API Reference

Koshi exposes a RESTful JSON API. All endpoints are prefixed with /api.

Authentication

Authenticated endpoints require a JWT Bearer token in the Authorization header:

Authorization: Bearer <token>

POST /api/auth/register

Register a new user with an ed25519 public key. Rate limited to 10 req/min.

Request Body:

{
  "username": "alice",       // 3-32 chars, alphanumeric + underscores
  "publicKey": "abcdef..."   // 64-char hex string (32 bytes)
}

Response (201):

{
  "userId": "e7d00463-38f8-4d85-8231-6762bb988f7d",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Errors: 400 (validation), 409 (already registered), 500 (server error)

POST /api/auth/login

Login by signing a challenge with your ed25519 key. The challenge format is koshi:login:{username}.

Request Body:

{
  "username": "alice",
  "signature": "abc123..."   // 128-char hex signature of challenge
}

Response (200):

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "userId": "e7d00463-38f8-4d85-8231-6762bb988f7d"
}

User Endpoints

GET /api/users/:username

$ curl https://koshi-api.ryopc.f5.si/api/users/alice

{
  "id": "e7d00463-38f8-4d85-8231-6762bb988f7d",
  "username": "alice",
  "displayName": "Alice",
  "bio": "Building the terminal future",
  "avatarUrl": null,
  "followersCount": 42,
  "followingCount": 12,
  "createdAt": "2026-07-14T05:00:00.000Z"
}

PUT /api/users/me

Update profile fields. Only include fields you want to change.

$ curl -X PUT https://koshi-api.ryopc.f5.si/api/users/me \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Alice",
    "bio": "Building the terminal future"
  }'

Post Endpoints

GET /api/posts/feed

Returns posts from followed users + own posts (authenticated) or global feed (anonymous).

Query params: ?limit=20 (max 100), ?offset=0

POST /api/posts

Create a new post. Content must be signed with your ed25519 key. Rate limited to 10 posts/min.

$ curl -X POST https://koshi-api.ryopc.f5.si/api/posts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello, koshi! 🌊",
    "signature": "abc123..."
  }'

Response (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "author": {
    "id": "e7d00463-38f8-4d85-8231-6762bb988f7d",
    "username": "alice",
    "displayName": "Alice"
  },
  "content": "Hello, koshi! 🌊",
  "signature": "abc123...",
  "createdAt": "2026-07-14T05:00:00.000Z"
}

Admin Endpoints

Admin endpoints require authentication AND admin privileges. Admin status is determined by the is_admin flag in the database or the ADMIN_USERNAME environment variable.

DELETE /api/admin/users/:id

Permanently deletes a user and all associated data (posts, follows, DMs) via database CASCADE. Accepts either a UUID or a username as the :id parameter.

$ curl -X DELETE https://koshi-api.ryopc.f5.si/api/admin/users/bob \
  -H "Authorization: Bearer <admin-token>"

# Or using a UUID:
$ curl -X DELETE https://koshi-api.ryopc.f5.si/api/admin/users/f8e11574-38f8-4d85-8231-6762bb988f7d \
  -H "Authorization: Bearer <admin-token>"

{
  "success": true,
  "deletedUser": {
    "id": "f8e11574-...",
    "username": "bob"
  }
}

PUT /api/admin/users/:id/admin

Toggle admin status for a user. Accepts either a UUID or a username as the :id parameter. Body: { "isAdmin": true } or { "isAdmin": false }.

$ curl -X PUT https://koshi-api.ryopc.f5.si/api/admin/users/bob/admin \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"isAdmin": true}'

{
  "success": true,
  "user": {
    "id": "...",
    "username": "bob",
    "isAdmin": true
  }
}

DM Endpoints

GET /api/dms

Query params: ?limit=50, ?offset=0, ?unread=true

POST /api/dms/:userId

Send a signed direct message. Content max 5000 characters.

$ curl -X POST https://koshi-api.ryopc.f5.si/api/dms/TARGET_USER_ID \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hey there!",
    "signature": "abc123..."
  }'

Health Check

$ curl https://koshi-api.ryopc.f5.si/api/health
{
  "status": "ok",
  "service": "koshi-api",
  "version": "1.2.0",
  "timestamp": "2026-07-14T05:00:00.000Z"
}

Cryptography

Koshi uses ed25519 elliptic curve cryptography for all identity and signing operations. This is the same curve used by the Nostr protocol.

Key Generation

When you register, a new ed25519 keypair is generated locally using tweetnacl. Keys are hex-encoded for storage:

import nacl from 'tweetnacl';

function generateKeypair() {
  const keypair = nacl.sign.keyPair();
  return {
    publicKey: bytesToHex(keypair.publicKey),   // 64 hex chars (32 bytes)
    secretKey: bytesToHex(keypair.secretKey),   // 128 hex chars (64 bytes)
  };
}

Signing & Verification

Messages (posts, DMs) are signed with your secret key using @noble/ed25519. Verification uses your public key.

Signing (CLI side)

import * as ed from '@noble/ed25519';

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);
}

Verification (Server side)

async function verifySignature(message, signature, publicKey) {
  const msgBytes = new TextEncoder().encode(message);
  const sigBytes = hexToBytes(signature);
  const pkBytes = hexToBytes(publicKey);
  return await ed.verify(sigBytes, msgBytes, pkBytes);
}

Authentication Flow

The authentication flow works as follows:

1. Registration: Client generates keypair, sends public key + username to server. Server stores the public key and issues a JWT.
2. Login: Client signs the challenge string "koshi:login:{username}" with their secret key. Server verifies the signature against the stored public key and issues a JWT.
3. Subsequent requests: JWT token is sent in the Authorization: Bearer {token} header for all authenticated endpoints.

JWT Tokens

JWTs are signed using HS256 (HMAC with SHA-256) and expire after 24 hours.

{
  // Token payload
  userId: "e7d00463-38f8-4d85-8231-6762bb988f7d",
  username: "alice",
  iat: 1784006345,
  exp: 1784092745  // 24 hours
}

Key Derivation

You can derive the public key from a secret key using derivePublicKey(secretKey). This works for both 32-byte seeds and 64-byte full secret keys.

WebSocket Reference

Koshi supports real-time communication via WebSocket. Connect with your JWT token for authentication.

Connection

# Connect with JWT token
ws://host:port/ws?token=<your-jwt-token>

# Production example
wss://koshi-api.ryopc.f5.si/ws?token=eyJhbGciOiJIUzI1NiIs...

Server Events (received from server)

Client Actions (sent to server)

Example: Create post via WebSocket

// Send
{
  "type": "post:create",
  "payload": {
    "content": "Hello from WebSocket!",
    "signature": "abc123..."
  }
}

// Receive confirmation
{
  "type": "post:created",
  "payload": {
    "id": "550e8400-...",
    "author": { "id": "...", "username": "alice" },
    "content": "Hello from WebSocket!",
    "timestamp": "2026-07-14T05:00:00.000Z"
  }
}

Database Schema

Koshi uses PostgreSQL 15 with the following schema. All tables use UUID primary keys and include timestamps.

Tables

users

Stores user identities with ed25519 public keys.

follows

Tracks user follow relationships.

kb_posts

Stores signed posts on the Koshi board.

dms

Stores signed direct messages between users.

Indexes exist on username, public_key, follower/following IDs, post timestamps, and DM recipient inbox queries.

Deployment

Render.com + Neon.tech (Recommended)

1. Set up Neon.tech Database

1. Go to Neon.tech and create an account
2. Create a new project (PostgreSQL 15)
3. Get your connection string from Connection Details
4. For production, use the pooled connection string (?pgbouncer=true)

2. Deploy on Render.com

1. Push the repo to GitHub
2. Go to Render.com and connect your GitHub repo
3. Render will auto-detect render.yaml (Blueprint) and create the service
4. In Render dashboard, add environment variables:
   • DATABASE_URL — your Neon.tech connection string
   • JWT_SECRET — generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
5. Render will auto-deploy on every push to main

Server Environment Variables

Docker

# Build the image
$ docker build -t koshi-api .

# Run the container
$ docker run -d \
  --name koshi-api \
  -p 3000:3000 \
  -e DATABASE_URL=postgresql://... \
  -e JWT_SECRET=... \
  koshi-api

Docker Compose

version: '3.8'
services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: koshi
      POSTGRES_PASSWORD: postgres
    volumes:
      - pgdata:/var/lib/postgresql/data

  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://postgres:postgres@db:5432/koshi
      JWT_SECRET: change-this-in-production
    depends_on:
      - db

volumes:
  pgdata:

Security

• Ed25519 Signatures — All posts and DMs are signed for authenticity. No passwords.
• JWT Auth — Tokens expire after 24 hours. Use JWT_SECRET environment variable.
• Parameterized Queries — All SQL uses parameterized queries ($1, $2) to prevent SQL injection.
• Input Validation — All endpoints validate input format, length, and types.
• Helmet — Security headers (CSP, HSTS, X-Frame-Options, etc.) are enabled.
• No Hardcoded Secrets — Everything via environment variables.
• CORS — Configured for CLI client origins.

Rate Limiting

Koshi uses express-rate-limit to protect endpoints:

Development

Setup

$ git clone https://github.com/ryopc/koshi.git
$ cd koshi
$ npm install
$ npm run dev    # Auto-reload with nodemon
$ npm run migrate # Run database migrations
$ npm test        # Run tests
$ npm run lint    # Run linter

Project Structure

koshi/
├── bin/
│   ├── cli.js              # CLI/TUI entry point (kb command)
│   └── server.js           # Express + WebSocket server
├── src/
│   ├── api/
│   │   ├── auth.js         # Auth routes (register/login)
│   │   ├── users.js        # User management routes
│   │   ├── posts.js        # Posts routes (koshi board)
│   │   ├── dms.js          # Direct messages routes
│   │   └── admin.js        # Admin routes (users, delete, grant)
│   ├── auth/
│   │   ├── ed25519.js      # Ed25519 crypto utilities
│   │   ├── jwt.js          # JWT token utilities
│   │   └── utils.js        # Hex encoding utilities
│   ├── db/
│   │   ├── schema.sql      # PostgreSQL schema
│   │   ├── migrate.js      # Migration script
│   │   └── pool.js         # Database connection pool
│   ├── middleware/
│   │   ├── auth.js         # Auth middleware
│   │   └── rateLimit.js    # Rate limiting
│   ├── ws/
│   │   ├── index.js        # WebSocket server setup
│   │   └── handlers.js     # WebSocket message handlers
│   └── index.js            # Express app setup
├── Dockerfile
├── render.yaml             # Render Blueprint config
└── package.json