working companion prototype
This commit is contained in:
181
docs/CONCEPT.md
181
docs/CONCEPT.md
@@ -94,10 +94,10 @@ Based on feedback from Reddit and Discord communities, league organizers are ove
|
||||
- Configure team vs solo racing formats
|
||||
|
||||
**Authentication & Security**
|
||||
- iRacing OAuth integration
|
||||
- Verify driver identities automatically
|
||||
- Zero-knowledge login: GridPilot never sees or stores your password
|
||||
- User performs login in visible browser window
|
||||
- Persistent sessions: login once, stay logged in
|
||||
- Secure access control for league admin functions
|
||||
- No separate account creation needed
|
||||
|
||||
### Migration Support
|
||||
|
||||
@@ -186,6 +186,177 @@ GridPilot acts as an admin assistant, not a bot:
|
||||
|
||||
GridPilot automates league management workflows - creating sessions, processing results, managing registrations. We never touch actual racing gameplay, driver behavior, or in-race activities. This is administrative automation to free organizers from manual work.
|
||||
|
||||
### iRacing Automation Rules
|
||||
|
||||
Understanding the distinction between iRacing's interfaces is critical:
|
||||
|
||||
**Two iRacing Interfaces:**
|
||||
|
||||
1. **iRacing Website (members.iracing.com)**: This is a standard HTML/DOM web application where hosted session management lives. Being a standard web application, it can be automated with browser automation tools like Playwright. This is 100% legal.
|
||||
|
||||
2. **iRacing Desktop App (Electron)**: The racing simulation itself runs in a sandboxed Electron application. Its DOM is inaccessible, and any modification violates iRacing's Terms of Service. This is why tools like iRefined were shut down.
|
||||
|
||||
**Our Approach:**
|
||||
- ✅ **Browser automation of the website** - Playwright automates members.iracing.com for session creation, form filling, and data extraction
|
||||
- ❌ **Never modify the desktop client** - No DOM injection, no script injection, no client modification
|
||||
|
||||
**Why This Matters:**
|
||||
- iRacing explicitly allows third-party tools that interact with their website
|
||||
- Client modification (like iRefined did) violates TOS and risks account bans
|
||||
- Browser automation is reliable, testable, and fully compliant
|
||||
|
||||
## Security & Authentication
|
||||
|
||||
### Zero-Knowledge Login Design
|
||||
|
||||
GridPilot requires access to your iRacing account to automate session creation, but **we never see, store, or transmit your password**. This section explains how we achieve secure authentication while maintaining complete transparency.
|
||||
|
||||
### The Trust Problem
|
||||
|
||||
When an app asks for your credentials, you're trusting that app with your identity. Many apps:
|
||||
- Store passwords in databases (risk of breach)
|
||||
- Transmit credentials through their servers (man-in-the-middle risk)
|
||||
- Have access to your login data internally (insider risk)
|
||||
|
||||
GridPilot takes a fundamentally different approach: **we never have access to your credentials at all**.
|
||||
|
||||
### How GridPilot Authentication Works
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ USER'S COMPUTER │
|
||||
│ ┌───────────────┐ ┌─────────────────────────────────┐ │
|
||||
│ │ GridPilot │ │ Playwright Browser Window │ │
|
||||
│ │ Companion │────────▶│ (Visible to User) │ │
|
||||
│ │ App │ │ │ │
|
||||
│ │ │ │ ┌─────────────────────────┐ │ │
|
||||
│ │ Cannot read │ │ │ iRacing Login Page │ │ │
|
||||
│ │ form inputs │ │ │ members.iracing.com │ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ Only detects │ │ │ [Email: *********** ] │ │ │
|
||||
│ │ URL changes │ │ │ [Password: ******** ] │ │ │
|
||||
│ │ │ │ │ [ Sign In ] │ │ │
|
||||
│ └───────────────┘ │ └─────────────────────────┘ │ │
|
||||
│ └─────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ HTTPS
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ iRacing Servers │
|
||||
│ (Direct connection │
|
||||
│ from browser) │
|
||||
└─────────────────────┘
|
||||
```
|
||||
|
||||
**Step-by-Step Flow:**
|
||||
|
||||
1. **User clicks "Connect to iRacing"** in GridPilot
|
||||
2. **A real browser window opens** showing the iRacing login page
|
||||
3. **User verifies the URL** - it's the real `members.iracing.com`
|
||||
4. **User enters credentials directly** - GridPilot cannot read input fields
|
||||
5. **iRacing authenticates the user** - credentials go directly to iRacing
|
||||
6. **GridPilot detects success** - only by observing the URL change
|
||||
7. **Browser session is saved locally** - for future automation runs
|
||||
|
||||
### What GridPilot CAN and CANNOT Do
|
||||
|
||||
| Capability | GridPilot Access |
|
||||
|------------|------------------|
|
||||
| Read your password | ❌ **Never** |
|
||||
| See what you type | ❌ **Never** |
|
||||
| Intercept credentials | ❌ **Never** |
|
||||
| Know if login succeeded | ✅ By URL change only |
|
||||
| Use authenticated session | ✅ For automation only |
|
||||
| Clear your session | ✅ User-initiated logout |
|
||||
|
||||
### Session Persistence
|
||||
|
||||
After your first login, GridPilot saves the browser session locally on your computer:
|
||||
|
||||
- **Location**: Your user data folder (not transmitted anywhere)
|
||||
- **Contents**: Browser cookies and state (encrypted by OS)
|
||||
- **Benefit**: You don't need to login every time you use GridPilot
|
||||
- **Control**: You can sign out anytime to clear the saved session
|
||||
|
||||
**Session Lifecycle:**
|
||||
|
||||
```
|
||||
First Use Return Visit Session Expired
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ Login │ │ Check │ │ Detect │
|
||||
│ Required│ │ Session │ │ Expiry │
|
||||
└────┬────┘ └────┬────┘ └────┬────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ Browser │ │ Valid? │───Yes────▶ │ Ready │
|
||||
│ Login │ └────┬────┘ │ to Use │
|
||||
└────┬────┘ │ No └─────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ Save │ │ Re-auth │ │ Pause │
|
||||
│ Session │ │ Prompt │ │ & Prompt│
|
||||
└────┬────┘ └─────────┘ └─────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────┐
|
||||
│ Ready │
|
||||
│ to Use │
|
||||
└─────────┘
|
||||
```
|
||||
|
||||
### User Verification Points
|
||||
|
||||
At every step, you can verify GridPilot's behavior:
|
||||
|
||||
1. **Browser Window**: You see the real browser - not an embedded frame
|
||||
2. **URL Bar**: Verify you're on `members.iracing.com` (look for HTTPS lock)
|
||||
3. **Network Traffic**: Your credentials go directly to iRacing's servers
|
||||
4. **Input Fields**: GridPilot cannot inject JavaScript to read form values
|
||||
5. **Logout Control**: You can sign out from GridPilot at any time
|
||||
|
||||
### Session Expiry During Automation
|
||||
|
||||
If your iRacing session expires while automation is running:
|
||||
|
||||
1. **Automation pauses** - no data loss
|
||||
2. **You're prompted to re-authenticate** - same secure flow
|
||||
3. **Automation resumes** - from where it left off
|
||||
|
||||
GridPilot never stores credentials to "auto-retry" - you always maintain control.
|
||||
|
||||
### Security Guarantees
|
||||
|
||||
| Guarantee | How We Ensure It |
|
||||
|-----------|------------------|
|
||||
| Zero-knowledge | Playwright browser is sandboxed; we cannot inject credential-reading code |
|
||||
| No transmission | Your login happens directly with iRacing; GridPilot servers never see traffic |
|
||||
| Local storage only | Session data stays on your computer, encrypted by your OS |
|
||||
| User control | You can logout, clear sessions, or revoke access anytime |
|
||||
| Transparency | Browser window is visible; you see exactly what's happening |
|
||||
|
||||
### Comparison to Other Approaches
|
||||
|
||||
| Approach | Password Exposure | Risk Level |
|
||||
|----------|-------------------|------------|
|
||||
| **GridPilot (Zero-Knowledge)** | Never exposed | ✅ Minimal |
|
||||
| OAuth (if iRacing offered it) | Never exposed | ✅ Minimal |
|
||||
| Password stored in app | App has access | ⚠️ Moderate |
|
||||
| Password in config file | File has plaintext | ❌ High |
|
||||
|
||||
### Technical Implementation
|
||||
|
||||
For developers interested in the implementation details, see [ARCHITECTURE.md](./ARCHITECTURE.md). Key points:
|
||||
|
||||
- **Playwright BrowserContext**: Manages browser state including cookies
|
||||
- **Persistent Context**: Saved to `app.getPath('userData')` in Electron
|
||||
- **Session Validation**: Navigates to protected page; detects login redirects
|
||||
- **No Credential Ports**: Application layer has no interfaces for password handling
|
||||
|
||||
## Future Vision
|
||||
|
||||
### Monetization Approach
|
||||
@@ -226,4 +397,6 @@ But first: nail the iRacing league management experience.
|
||||
|
||||
---
|
||||
|
||||
GridPilot exists to make league racing accessible and professional for organizers of all sizes, eliminating manual work so communities can focus on what matters: great racing and strong communities.
|
||||
GridPilot exists to make league racing accessible and professional for organizers of all sizes, eliminating manual work so communities can focus on what matters: great racing and strong communities.
|
||||
|
||||
*Last Updated: 2025-11-23*
|
||||
Reference in New Issue
Block a user