opencode-openai-codex-auth/docs/privacy.md at main

mirror of https://github.com/hanzoai/opencode-openai-codex-auth.git synced 2026-09-24 17:01:02 +00:00

Files

T

Numman AliandHanzo Dev fe29b2110d feat: Add comprehensive compliance documentation and fix critical bugs (v2.1.2)

This release includes comprehensive OpenAI ToS compliance updates and fixes
4 critical bugs that prevented per-model options and multi-turn conversations
from working correctly.

## 🔒 Compliance & Legal Updates

### Terms of Service & Usage Guidelines
- Added comprehensive ToS & Usage Notice to README emphasizing personal use only
- Added Rate Limits & Responsible Use section with best practices
- Added extensive FAQ section addressing TOS compliance questions
- Updated LICENSE with MIT + Usage Disclaimer for personal development use
- Added compliance header to index.ts documenting intended use cases

### New Documentation
- **CONTRIBUTING.md**: Complete contribution guidelines with compliance requirements
- **SECURITY.md**: Security policy, vulnerability reporting, best practices
- **docs/privacy.md**: Comprehensive privacy & data handling documentation
- **Issue Templates**: Bug reports & feature requests with compliance checklists

### Documentation Updates
- Updated docs/index.md with usage notice and trademark disclaimers
- Updated docs/getting-started.md with "Before You Begin" compliance notice
- Updated docs/troubleshooting.md with subscription & compliance sections
- All references updated to "Plus/Pro" (removed Team/Enterprise mentions)

### Key Compliance Principles
- ✅ Emphasizes personal development use with own ChatGPT Plus/Pro subscription
- ✅ Uses OpenAI's official OAuth authentication (same as Codex CLI)
- ✅ Clear prohibition of commercial resale, multi-user services
- ✅ Not a "free API alternative" - uses existing ChatGPT subscription
- ✅ Proper trademark notices and attribution to OpenAI
- ✅ Transparent about data handling and privacy

## 🐛 Critical Bug Fixes

### Bug #1: Per-Model Options Ignored (Config Lookup Mismatch)
**Severity:** 🔴 HIGH

Users configured different reasoning levels for each model variant, but all
variants behaved identically because the plugin was looking up normalized
model names instead of the original config keys.

**Fix:** lib/request/request-transformer.ts:277
- Use original model name for config lookup before normalization
- Allows per-model options to work correctly
- Impact: Different reasoning levels now properly applied per variant

### Bug #2: Multi-Turn Conversations Fail (AI SDK Compatibility)
**Severity:** 🔴 CRITICAL

Multi-turn conversations failed with "Item not found" errors because:
1. AI SDK sends `item_reference` (not in Codex API spec)
2. IDs weren't completely stripped for stateless mode (store: false)

**Fix:** lib/request/request-transformer.ts:114-135
- Filter out AI SDK `item_reference` items
- Strip ALL IDs from remaining items (not just rs_* prefix)
- Confirmed ChatGPT backend requires store: false via testing
- Full message history preserved for LLM context

### Bug #3: Case-Sensitive Normalization
**Severity:** 🟡 MEDIUM

**Fix:** lib/request/request-transformer.ts:22-27
- Added toLowerCase() for case-insensitive matching
- Backwards compatible with old verbose config names
- Handles uppercase/mixed case user input

### Bug #4: GitHub API Rate Limiting
**Severity:** 🟡 MEDIUM

Plugin checked GitHub on every request, exhausting 60 req/hour limit.
15-minute cache timestamp was stored but never checked.

**Fix:** lib/prompts/codex.ts:50-53, lib/prompts/opencode-codex.ts:47-50
- Check cache TTL before GitHub API call
- Only fetch if cache >15min old
- Prevents rate limit exhaustion during testing

## ✨ Enhancements

### Debug Logging System
- New environment variable: `DEBUG_CODEX_PLUGIN=1`
- Added logDebug() and logWarn() functions
- Shows config lookups, ID filtering, options resolution
- File: lib/logger.ts

### Optimized Config Structure
- Changed to Codex CLI preset names (gpt-5-codex-low, etc.)
- Removed redundant `id` field (not used by OpenAI provider)
- Added `name` field for friendly TUI display
- File: config/full-opencode.json

### GitHub Pages Documentation
- Complete documentation restructure for GitHub Pages
- User guides: getting-started.md, configuration.md, troubleshooting.md
- Developer guides: ARCHITECTURE.md, CONFIG_FLOW.md, CONFIG_FIELDS.md, TESTING.md
- Privacy policy, security policy, contribution guidelines

## 🧪 Testing

### Test Coverage
- ✅ 159 unit tests passing (30+ new tests)
- ✅ 14 integration tests passing (actual API verification)
- ✅ All documented scenarios have test coverage

### Integration Tests (scripts/test-all-models.sh)
- Tests all 9 custom model configurations
- Tests all 4 default OpenCode models
- Verifies backwards compatibility with old config format
- Uses ENABLE_PLUGIN_REQUEST_LOGGING to verify actual API requests

### Test Results
- 14/14 model configuration tests passing
- All per-model options verified correct
- Multi-turn conversations work without errors
- Backwards compatibility confirmed

## 📝 Files Changed

### Modified (7 files)
- lib/request/request-transformer.ts: Config lookup & ID filtering fixes
- lib/prompts/codex.ts: 15-minute cache TTL
- lib/prompts/opencode-codex.ts: 15-minute cache TTL
- lib/logger.ts: Debug logging system
- config/full-opencode.json: Optimized structure
- test/request-transformer.test.ts: 30+ new tests
- LICENSE: Added usage disclaimer
- index.ts: Added compliance header
- README.md: Added ToS, Rate Limits, FAQ sections

### Created (20+ files)
- CONTRIBUTING.md: Contribution guidelines
- SECURITY.md: Security policy
- docs/index.md: GitHub Pages landing
- docs/getting-started.md: Installation guide
- docs/configuration.md: Advanced config
- docs/troubleshooting.md: Debug guide
- docs/privacy.md: Privacy policy
- docs/development/ARCHITECTURE.md: Technical architecture
- docs/development/CONFIG_FLOW.md: Config system internals
- docs/development/CONFIG_FIELDS.md: Field usage guide
- docs/development/TESTING.md: Testing guide
- .github/ISSUE_TEMPLATE/bug_report.md
- .github/ISSUE_TEMPLATE/feature_request.md
- .github/ISSUE_TEMPLATE/config.yml
- scripts/test-all-models.sh: Automated testing

## 🎯 Verification

All scenarios tested and verified:
- ✅ Default models work without config
- ✅ Custom models with per-variant options
- ✅ Old config format (backwards compatible)
- ✅ Mixed default + custom models
- ✅ Multi-turn conversations (no "item not found" errors)
- ✅ Model switching with different options
- ✅ All normalization patterns
- ✅ Complete ID filtering

## 📚 Documentation

Complete documentation suite (100+ KB):
- User guides for installation, configuration, troubleshooting
- Developer guides for architecture, config system, testing
- Privacy policy and security policy
- Compliance guidelines and contribution requirements
- Release notes in tmp/release-notes/

## 🔗 References

- OpenAI Terms of Use: https://openai.com/policies/terms-of-use/
- OpenAI Usage Policies: https://openai.com/policies/usage-policies/
- OpenAI Platform API: https://platform.openai.com/
- OpenAI Codex CLI: https://github.com/openai/codex

Co-authored-by: Hanzo Dev <[email protected]>

2025-10-12 21:25:43 +01:00

202 lines

5.6 KiB

Markdown

Raw Permalink Blame History

 # Privacy & Data Handling
 This page explains how the OpenCode OpenAI Codex Auth Plugin handles your data and protects your privacy.
 ## Overview
 This plugin prioritizes user privacy and data security. We believe in transparency about data handling and giving you full control over your information.
 ---
 ## What We Collect
 **Nothing.** This plugin does not collect, store, or transmit usage data to third parties.
 - ❌ No telemetry
 - ❌ No analytics
 - ❌ No usage tracking
 - ❌ No personal information collection
 ---
 ## Data Storage
 All data is stored **locally on your machine**:
 ### OAuth Tokens
 - **Location:** `~/.opencode/auth/openai.json`
 - **Contents:** Access tokens, refresh tokens, expiration timestamps
 - **Managed by:** OpenCode's credential management system
 - **Security:** File permissions restrict access to your user account
 ### Cache Files
 - **Location:** `~/.opencode/cache/`
 - **Contents:**
   - `codex-instructions.txt` - Codex system instructions (fetched from GitHub)
   - `codex-instructions-meta.json` - ETag and timestamp metadata
 - **Purpose:** Reduce GitHub API calls and improve performance
 - **TTL:** 15 minutes (automatically refreshes when stale)
 ### Debug Logs
 - **Location:** `~/.opencode/logs/codex-plugin/`
 - **Contents:** Request/response logs (only when `ENABLE_PLUGIN_REQUEST_LOGGING=1` is set)
 - **Includes:**
   - API request bodies
   - API response data
   - Timestamps
   - Configuration used
 - **⚠️ Warning:** Logs may contain your prompts and model responses - handle with care
 ---
 ## Data Transmission
 ### Direct to OpenAI
 All API requests go **directly from your machine to OpenAI's servers**:
 - ✅ No intermediary proxies
 - ✅ No third-party data collection
 - ✅ HTTPS encrypted communication
 - ✅ OAuth-secured authentication
 ### What Gets Sent to OpenAI
 When you use the plugin, the following is transmitted to OpenAI:
 - Your prompts and conversation history
 - OAuth access token (for authentication)
 - ChatGPT account ID (from token JWT)
 - Configuration options (reasoning effort, verbosity, etc.)
 - Model selection
 **Note:** This is identical to what the official OpenAI Codex CLI sends.
 ### What Does NOT Get Sent
 - ❌ Your filesystem contents (unless explicitly requested via tools)
 - ❌ Personal information beyond what's in your prompts
 - ❌ Usage statistics or analytics
 - ❌ Plugin version or system information
 ---
 ## Third-Party Services
 ### GitHub API
 The plugin fetches Codex instructions from GitHub:
 - **URL:** `https://api.github.com/repos/openai/codex/releases/latest`
 - **Purpose:** Get latest Codex system instructions
 - **Frequency:** Once per 15 minutes (cached with ETag)
 - **Data sent:** HTTP GET request (no personal data)
 - **Rate limiting:** 60 requests/hour (unauthenticated)
 ### OpenAI Services
 All interactions with OpenAI go through:
 - **OAuth:** `https://chatgpt.com/oauth`
 - **API:** `https://chatgpt.com/backend-api/conversation`
 See [OpenAI Privacy Policy](https://openai.com/policies/privacy-policy/) for how OpenAI handles data.
 ---
 ## Your Data Rights
 You have complete control over your data:
 ### Delete OAuth Tokens
 ```bash
 opencode auth logout
 # Or manually:
 rm ~/.opencode/auth/openai.json
 ```
 ### Delete Cache Files
 ```bash
 rm -rf ~/.opencode/cache/
 ```
 ### Delete Logs
 ```bash
 rm -rf ~/.opencode/logs/codex-plugin/
 ```
 ### Revoke OAuth Access
 . Visit [ChatGPT Settings → Authorized Apps](https://chatgpt.com/settings/apps)
 . Find "OpenCode" or "Codex CLI"
 . Click "Revoke"
 This immediately invalidates all access tokens.
 ---
 ## Security Measures
 ### Token Protection
 - **Local storage only:** Tokens never leave your machine except when sent to OpenAI for authentication
 - **File permissions:** Auth files are readable only by your user account
 - **No logging:** OAuth tokens are never written to debug logs
 - **Automatic refresh:** Expired tokens are refreshed automatically
 ### PKCE Flow
 The plugin uses **PKCE (Proof Key for Code Exchange)** for OAuth:
 - Prevents authorization code interception attacks
 - Industry-standard security for OAuth 2.0
 - Same method used by OpenAI's official Codex CLI
 ### HTTPS Encryption
 All network communication uses HTTPS:
 - OAuth authorization: Encrypted
 - API requests: Encrypted
 - Token refresh: Encrypted
 ---
 ## Compliance
 ### OpenAI's Privacy Policy
 When using this plugin, you are subject to:
 - [OpenAI Privacy Policy](https://openai.com/policies/privacy-policy/)
 - [OpenAI Terms of Use](https://openai.com/policies/terms-of-use/)
 **Your responsibility:** Ensure your usage complies with OpenAI's policies.
 ### GDPR Considerations
 This plugin:
 - ✅ Does not collect personal data
 - ✅ Does not process data on behalf of third parties
 - ✅ Stores data locally under your control
 - ✅ Provides clear data deletion mechanisms
 However, data sent to OpenAI is subject to OpenAI's privacy practices.
 ---
 ## Transparency
 ### Open Source
 The entire plugin source code is available at:
 - **GitHub:** [https://github.com/numman-ali/opencode-openai-codex-auth](https://github.com/numman-ali/opencode-openai-codex-auth)
 You can:
 - Review all code
 - Audit data handling
 - Verify no hidden telemetry
 - Inspect network requests
 ### No Hidden Behavior
 - No obfuscated code
 - No minified dependencies
 - All network requests are documented
 - Debug logging shows exactly what's sent to APIs
 ---
 ## Questions?
 For privacy-related questions:
 - **Plugin-specific:** [GitHub Issues](https://github.com/numman-ali/opencode-openai-codex-auth/issues)
 - **OpenAI data handling:** [OpenAI Support](https://help.openai.com/)
 - **Security concerns:** See [SECURITY.md](../SECURITY.md)
 ---
 **Last Updated:** 2025-10-12
 **Back to:** [Documentation Home](index.md) | [Getting Started](getting-started.md)

202 lines 5.6 KiB Markdown Raw Permalink Blame History

202 lines

5.6 KiB

Markdown

Raw Permalink Blame History