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

4.0 KiB

Raw Blame History

Contributing Guidelines

Thank you for your interest in contributing to opencode-openai-codex-auth!

Before submitting contributions, please review these guidelines to ensure all changes maintain compliance with OpenAI's Terms of Service and the project's goals.

Compliance Requirements

All contributions MUST:

✅ Maintain TOS Compliance

Use only official OAuth authentication methods
Not facilitate violations of OpenAI's Terms of Service
Focus on legitimate personal productivity use cases
Include appropriate user warnings and disclaimers

✅ Respect OpenAI's Systems

No session token scraping or cookie extraction
No bypassing of rate limits or authentication controls
No reverse-engineering of undocumented APIs
Use only officially supported authentication flows

✅ Proper Use Cases

Personal development and coding assistance
Individual productivity enhancements
Terminal-based workflows
Educational purposes

❌ Prohibited Features

Commercial resale or multi-user authentication
Rate limit circumvention techniques
Session token scraping or extraction
Credential sharing mechanisms
Features designed to violate OpenAI's terms

Code Standards

TypeScript: All code must be TypeScript with strict type checking
Testing: Include tests for new functionality (we maintain 159+ unit tests)
Documentation: Update README.md for user-facing changes
Modular design: Keep functions focused and under 40 lines
No external dependencies: Minimize dependencies (currently only @openauthjs/openauth)

Pull Request Process

Fork the repository and create a feature branch
Write clear commit messages explaining the "why" not just "what"
Include tests for new functionality
Update documentation (README.md, config examples, etc.)
Ensure compliance with guidelines above
Test thoroughly with actual ChatGPT Plus/Pro account
Submit PR with clear description of changes

Reporting Issues

When reporting issues, please:

Check existing issues to avoid duplicates
Provide clear reproduction steps
Include version information (opencode --version, plugin version)
Confirm compliance: Verify you're using the plugin for personal use with your own subscription
Attach logs (if using ENABLE_PLUGIN_REQUEST_LOGGING=1)

Issue Template

Please include:

**Issue Description:**
[Clear description of the problem]

**Steps to Reproduce:**
1.
2.
3.

**Expected Behavior:**
[What should happen]

**Actual Behavior:**
[What actually happens]

**Environment:**
- opencode version:
- Plugin version:
- OS:
- Node version:

**Compliance Confirmation:**
- [ ] I'm using this for personal development only
- [ ] I have an active ChatGPT Plus/Pro subscription
- [ ] This is not related to commercial use or TOS violations

Feature Requests

We welcome feature requests that:

Enhance personal productivity
Improve developer experience
Maintain compliance with OpenAI's terms
Align with the project's scope

We will decline features that:

Violate or circumvent OpenAI's Terms of Service
Enable commercial resale or multi-user access
Bypass authentication or rate limiting
Facilitate improper use

Code of Conduct

Our Standards

✅ Encouraged:

Respectful and constructive communication
Focus on legitimate use cases
Transparency about limitations and compliance
Helping other users with proper usage

❌ Not Acceptable:

Requesting help with TOS violations
Promoting commercial misuse
Hostile or disrespectful behavior
Sharing credentials or tokens

Questions?

For questions about:

Plugin usage: Open a GitHub issue
OpenAI's terms: Contact OpenAI support
Contributing: Open a discussion thread

License

By contributing, you agree that your contributions will be licensed under the MIT License with Usage Disclaimer (see LICENSE file).

Thank you for helping make this plugin better while maintaining compliance and ethics!

4.0 KiB Raw Blame History