Winchester Coin Club Forum - Technical Design Document

Architecture Overview

The Winchester Coin Club forum is a cryptographically-signed message board using ECDSA P-256 signatures for authentication and a web-of-trust model for authorization.

System Components

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Web Browser │◄───────►│ Flask API │◄───────►│ PostgreSQL DB │ │ (Static HTML) │ HTTPS │ (forum-api) │ │ │ │ │ │ │ │ │ │ • forum.html │ │ • /messages │ │ • forum_users │ │ • forum.js │ │ • /users │ │ • forum_messages│ │ • forum-crypto │ │ • /register-* │ │ • forum_reg_req │ └─────────────────┘ └──────────────────┘ └─────────────────┘

Technology Stack

Frontend:

Backend:

Database:

Cryptographic Implementation

Key Generation (Client-Side)

Keys are generated using the Web Crypto API with ECDSA P-256 (secp256r1):

const keyPair = await crypto.subtle.generateKey(
  { name: 'ECDSA', namedCurve: 'P-256' },
  true,  // extractable
  ['sign', 'verify']
);

Private Key:

Public Key:

Address:

Message Signing

Each message is signed with the following process:

  1. Construct message string: messageToSign = address + nonce + body
  2. Sign with private key using ECDSA with SHA-256
  3. Send to server with signature as hex string

Signature Verification (Server-Side)

Server verifies each message signature before accepting using the python-ecdsa library.

Database Schema

forum_users

Column Type Description
id SERIAL Primary key
address VARCHAR(255) SHA-256 hash of public key (unique)
public_key TEXT SPKI PEM format public key
display_name VARCHAR(100) Human-readable name
directus_user_id UUID Link to Directus CMS user (nullable)
is_approved BOOLEAN Whether user can post
vouched_by VARCHAR(255) Address of user who vouched
user_role VARCHAR(20) 'member', 'friend', or 'bot'
created_at TIMESTAMP Registration timestamp

forum_messages

Column Type Description
id SERIAL Primary key
author_address VARCHAR(255) Foreign key to forum_users
parent_id INTEGER NULL for threads, message ID for replies
subject VARCHAR(255) Optional subject line
body TEXT Message content
signature TEXT Hex-encoded ECDSA signature
nonce VARCHAR(100) Timestamp + random (anti-replay)
created_at TIMESTAMP Post timestamp

API Endpoints

Public Endpoints (No Authentication)

Authenticated Endpoints

Authentication Flow

For Club Members (Directus Users)

  1. User logs in to Directus → receives access token
  2. User clicks "Register for Forum" on homepage
  3. Browser generates key pair
  4. POST /register-member with Directus token + public key
  5. Server verifies token with Directus API
  6. Server creates forum_users record with is_approved=TRUE
  7. User can immediately post

For Public Users (Web of Trust)

  1. User clicks "Get Started"
  2. Browser generates key pair
  3. POST /register-request with public key + display name
  4. Server stores request, returns public_key_hash
  5. User shares hash with existing member
  6. Member verifies identity (out-of-band)
  7. Admin/member approves via Directus or manual DB update
  8. User's is_approved set to TRUE
  9. User can now post

Security Considerations

Protections

Current Limitations

Frontend Architecture

Three-Column Layout

┌──────┬────────────┬─────────────────────┐ │ Nav │ Threads │ Message Content │ │ 70px │ 350px │ Flexible │ │ │ │ │ │ 🏠 │ Thread 1 │ ┌─────────────────┐ │ │ 📝 │ Thread 2 │ │ Parent Message │ │ │ 👥 │ Thread 3 │ └─────────────────┘ │ │ │ │ ┌───────────────┐ │ │ 💬 │ │ │ Reply (30px) │ │ │ ❓ │ │ └───────────────┘ │ │ 🇺🇸 │ │ ┌─────────────┐│ │ │ │ │Reply (60px)││ └──────┴────────────┴─────┴─────────────┘┘

View Modes

Threading Implementation

Messages support unlimited nesting depth through recursive rendering. Each reply is indented 30px from its parent, creating a visual hierarchy.

Thread Structure Example

Thread (parent_id = NULL) ├─ Reply A (parent_id = thread.id) ├─ Reply B (parent_id = thread.id) │ ├─ Reply to B.1 (parent_id = B.id) │ └─ Reply to B.2 (parent_id = B.id) └─ Reply C (parent_id = thread.id)

Integration with Directus

User Role Mapping

Directus roles map to forum roles:

Comparison with Traditional Forums

Feature Traditional Forum Cryptographic Forum
Authentication Username/password ECDSA key pair
User Registration Email verification Cryptographic identity
Authorization Admin/moderator approval Web of trust (vouching)
Password Reset Email link N/A (no passwords)
Identity Recovery Support ticket Export/import keys
Spam Prevention CAPTCHA, email blocks IP limiting, vouching
Message Integrity Database trust Cryptographic signatures
Centralization Admin-controlled Distributed trust

Future Enhancements

Planned Features

Conclusion

The Winchester Coin Club forum demonstrates that cryptographic identity can replace traditional password-based authentication while enabling decentralized trust through a web-of-trust model. The system is secure, user-friendly for non-technical users, and resistant to common attack vectors.

By using ECDSA signatures for message authentication and a vouching system for authorization, the forum creates a self-moderating community without requiring centralized control.

← Back to Layman's Explanation | ← Back to Winchester Coin Club Home

Version: 2025-10-19
Author: Winchester Coin Club Development Team
Winchester Coin Club - Building community through trust