hanzoai/opencode-openai-codex-auth
2
0
Fork 0
mirror of https://github.com/hanzoai/opencode-openai-codex-auth.git synced 2026-09-24 17:01:02 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
opencode-openai-codex-auth/docs/privacy.md
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

5.6 KiB
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 for how OpenAI handles data.

Your Data Rights

You have complete control over your data:

Delete OAuth Tokens

opencode auth logout
# Or manually:
rm ~/.opencode/auth/openai.json

Delete Cache Files

rm -rf ~/.opencode/cache/

Delete Logs

rm -rf ~/.opencode/logs/codex-plugin/

Revoke OAuth Access

  1. Visit ChatGPT Settings โ†’ Authorized Apps
  2. Find "OpenCode" or "Codex CLI"
  3. 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:

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:

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:

Last Updated: 2025-10-12

Back to: Documentation Home | Getting Started

Reference in New Issue View Git Blame Copy Permalink