diff --git a/docs/implementation/discord-oauth-arbiter/CHANGELOG.md b/docs/implementation/discord-oauth-arbiter/CHANGELOG.md new file mode 100644 index 0000000..e6bf8e6 --- /dev/null +++ b/docs/implementation/discord-oauth-arbiter/CHANGELOG.md @@ -0,0 +1,176 @@ +# 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.* diff --git a/docs/implementation/discord-oauth-arbiter/VERSION b/docs/implementation/discord-oauth-arbiter/VERSION new file mode 100644 index 0000000..227cea2 --- /dev/null +++ b/docs/implementation/discord-oauth-arbiter/VERSION @@ -0,0 +1 @@ +2.0.0 diff --git a/docs/implementation/discord-oauth-arbiter/package.json b/docs/implementation/discord-oauth-arbiter/package.json index 72e3a71..1ad74e1 100644 --- a/docs/implementation/discord-oauth-arbiter/package.json +++ b/docs/implementation/discord-oauth-arbiter/package.json @@ -1,6 +1,6 @@ { "name": "firefrost-arbiter", - "version": "1.0.0", + "version": "2.0.0", "description": "Discord Role Management and Subscription OAuth Gateway for Firefrost Gaming", "main": "src/index.js", "scripts": { diff --git a/docs/implementation/discord-oauth-arbiter/src/index.js b/docs/implementation/discord-oauth-arbiter/src/index.js index ae5d30b..51bd32a 100644 --- a/docs/implementation/discord-oauth-arbiter/src/index.js +++ b/docs/implementation/discord-oauth-arbiter/src/index.js @@ -1,5 +1,8 @@ -// src/index.js -// Main application entry point for Firefrost Arbiter +// Firefrost Arbiter v2.0.0 +// Discord Role Management & OAuth Gateway +// Built: March 30, 2026 + +const VERSION = '2.0.0'; require('dotenv').config(); const express = require('express');