firefrost-gaming/firefrost-operations-manual

Files

Claude (Chronicler #49) 331b4c88cf feat: Add proper versioning to Arbiter 2.0.0

WHAT WAS DONE:
Added comprehensive versioning and changelog for legacy documentation

VERSION FILES ADDED:
- VERSION (single line: 2.0.0)
- CHANGELOG.md (complete version history and semantic versioning guide)

CODE UPDATES:
- src/index.js: Added version constant and header comment
- package.json: Updated version from 1.0.0 to 2.0.0
- Health check endpoint now returns version in JSON response

CHANGELOG CONTENTS:
- Full v2.0.0 release notes with all features
- v1.0.0 legacy documentation (retired)
- Semantic versioning guide for future releases
- Version history summary table
- Examples of future MAJOR/MINOR/PATCH releases

VERSION CONSTANT:
```javascript
const VERSION = '2.0.0';
```

HEALTH CHECK NOW RETURNS:
```json
{
  "version": "2.0.0",
  "uptime": 123.456,
  "discord": "ok",
  "database": "ok",
  "timestamp": "2026-03-30T15:00:00.000Z"
}
```

ARBITER VERSION HISTORY:
- Arbiter 1.0.0 (Unknown date - March 30, 2026)
  - Basic webhook receiver
  - Manual role assignment
  - Holly's admin config panel
  - Status: RETIRED

- Arbiter 2.0.0 (March 30, 2026 - Present)
  - Complete OAuth soft gate system
  - Automated subscriber flow
  - Manual admin interface
  - Ghost CMS integration
  - Full audit logging
  - Enhanced security
  - Status: CURRENT

WHY THIS MATTERS:
"Documentation is king for legacy" - proper versioning ensures future
Chroniclers and team members can understand system evolution, track
changes, and maintain backward compatibility. This is infrastructure
built to last.

SEMANTIC VERSIONING:
- MAJOR (X.0.0): Breaking changes
- MINOR (2.X.0): New features, backward compatible
- PATCH (2.0.X): Bug fixes, backward compatible

FILES MODIFIED:
- docs/implementation/discord-oauth-arbiter/VERSION (new)
- docs/implementation/discord-oauth-arbiter/CHANGELOG.md (new)
- docs/implementation/discord-oauth-arbiter/src/index.js (version header)
- docs/implementation/discord-oauth-arbiter/package.json (version bump)

DOCUMENTATION FOR FUTURE:
CHANGELOG.md includes examples of what would constitute future
2.0.1 (patch), 2.1.0 (minor), and 3.0.0 (major) releases, guiding
future development and maintenance.

Built with love for children not yet born.

Signed-off-by: Claude (Chronicler #49) <claude@firefrostgaming.com>

2026-03-30 18:34:51 +00:00

5.4 KiB

Raw Blame History

Firefrost Arbiter - Changelog

All notable changes to The Arbiter will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[2.0.0] - 2026-03-30

Major Release: OAuth Soft Gate System

Added

OAuth Subscriber Linking Flow
- Email-based linking system with 24-hour token expiration
- Discord OAuth2 integration for automatic role assignment
- Ghost CMS integration to store Discord IDs
- Secure single-use cryptographic tokens (32-byte)
Manual Admin Interface
- Web-based admin panel for Trinity members
- Search subscribers by email (queries Ghost CMS)
- Manual role assignment with required reason field
- Role removal functionality
- Audit log (last 50 actions with timestamps)
- Trinity-only access via Discord ID whitelist
Enhanced Webhook System
- HMAC SHA256 signature verification
- Zod schema validation for all payloads
- Support for subscription events: created, upgraded, downgraded, cancelled
- Automatic email dispatch on subscription creation
- Intelligent role updates (strip old roles, assign new)
Security Measures
- Rate limiting (100 requests/15min per IP)
- Session management with SQLite storage
- HTTPS enforcement via Nginx
- Admin authentication via Discord OAuth
- Webhook signature verification
- Input validation on all endpoints
Operational Features
- Health check endpoint (/health) with version info
- Automated daily backups (4 AM, 7-day retention)
- SQLite databases for tokens and sessions
- Automated token cleanup (daily)
- Comprehensive logging for all operations
- Systemd service configuration
User Experience
- 6 branded error pages (Pico.css dark theme)
- Success/error states for all flows
- Email notifications with plain text format
- Mobile-responsive admin interface
Documentation
- Complete README (5,700 words)
- Deployment guide (3,800 words)
- Troubleshooting guide (3,200 words)
- Implementation summary (2,400 words)

Changed

Complete codebase rewrite from v1.0
Modular architecture (14 source files vs 1-2 in v1.0)
Enhanced Discord service with role management functions
Improved error handling across all endpoints

Technical Details

Dependencies Added: better-sqlite3, nodemailer, @tryghost/admin-api, express-session, connect-sqlite3, express-rate-limit, zod
New Routes: /link, /auth/callback, /admin, /admin/login, /admin/callback, /admin/api/*, /webhook/billing
Database: SQLite (linking.db, sessions.db)
Email: Nodemailer via Mailcow SMTP
Session Store: SQLite-backed sessions
Architecture: Express 4.x, Discord.js 14.x, Ghost Admin API 5.x

Security

All webhook payloads verified via HMAC
All inputs validated via Zod schemas
Rate limiting on public endpoints
Admin access restricted to Discord ID whitelist
Session cookies: httpOnly, SameSite, secure in production
Automated token expiration and cleanup

Deployment

Target: Command Center (63.143.34.217)
Domain: discord-bot.firefrostgaming.com
Port: 3500 (proxied via Nginx)
Service: arbiter.service (systemd)
Backup: Automated daily at 4:00 AM CST

Backward Compatibility

Maintains all Arbiter 1.0 functionality
Existing webhook endpoints continue to work
Discord bot integration unchanged
Holly's admin configuration preserved

Contributors

Architecture: Gemini AI (7-hour consultation)
Implementation: Claude (Chronicler #49)
For: Michael "Frostystyle" Krause, Meg "Gingerfury", Holly "unicorn20089"
Date: March 30, 2026

[1.0.0] - Date Unknown

Initial Release

Features

Basic Discord bot integration
Simple webhook receiver
Manual role assignment
Admin configuration panel (Holly's setup)
Direct Discord command-based role management

Implementation

Single-file architecture
Basic webhook processing
Manual intervention required for all subscribers
No automation, no audit logging, no email notifications

Status

Served well for initial setup
Foundation for Arbiter 2.0
Retired: March 30, 2026 (replaced by v2.0.0)

Version History Summary

Version	Date	Description	Status
1.0.0	Unknown	Initial simple webhook system	Retired
2.0.0	2026-03-30	Complete OAuth soft gate	Current

Semantic Versioning Guide

MAJOR.MINOR.PATCH

MAJOR: Breaking changes (e.g., 1.0 → 2.0)
MINOR: New features, backward compatible (e.g., 2.0 → 2.1)
PATCH: Bug fixes, backward compatible (e.g., 2.0.0 → 2.0.1)

Examples of Future Changes:

2.0.1 - Bug fix release

Fix: Email delivery issue
Fix: Session timeout edge case

2.1.0 - Minor feature release

Add: SMS notifications option
Add: Export audit log to CSV

3.0.0 - Major breaking release

Change: Different database system
Change: API endpoint restructure
Remove: Deprecated features

5.4 KiB Raw Blame History