# Firefrost Arbiter - Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## [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

---

## Links

- **Repository**: git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual
- **Implementation**: docs/implementation/discord-oauth-arbiter/
- **Consultation Archive**: docs/consultations/gemini-discord-oauth-2026-03-30/
- **Documentation**: README.md, DEPLOYMENT.md, TROUBLESHOOTING.md

---

**🔥❄️ Fire + Frost + Foundation = Where Love Builds Legacy 💙**

*Built for children not yet born.*