Sub2 CPA Sync

Overview

Sub2 CPA Sync provides a local Web interface for comparing OpenAI/Codex OAuth accounts from a Sub2API/RelayHub deployment with local CPAQuota auth files.

The tool performs a preview-first workflow. Account differences are displayed before any write operation. Synchronization writes occur only after explicit selection and confirmation in the local Web interface.

Scope

• Supported source accounts: platform=openai, type=oauth.
• Supported target format: CPAQuota flat Codex auth JSON files under the configured CPA auth directory.
• Unsupported non-OpenAI account types are excluded from the primary diff table and are not synchronized.
• CPA-only accounts are never deleted automatically.
• Sensitive fields such as access_token, refresh_token, and id_token are not displayed in the Web interface or exported report.
• The CPA management key is loaded process-locally from the configured key file when the file exists. Manual key input overrides the process-local value and is not persisted by this tool.

Runtime Paths

Item	Default
Web UI	http://127.0.0.1:18731/
Sub2 API	http://127.0.0.1:18081/api/v1
Sub2 SSH alias	sub2api
Sub2 deployment directory	/opt/sub2api-deploy
CPA root	%USERPROFILE%\CPAQuota
CPA auth directory	%USERPROFILE%\CPAQuota\auth
CPA management key file	%USERPROFILE%\CPAQuota\secrets\management-key.txt
CPA start script	%USERPROFILE%\CPAQuota\start-cpa.ps1
CPA base URL	http://127.0.0.1:8317

Environment variables can override these defaults:

Variable	Purpose
SUB2_CPA_SYNC_PORT	Local Web UI port
SUB2_API_BASE_URL	Sub2API base URL ending at /api/v1
SUB2_SSH_ALIAS	SSH alias for fallback reads
SUB2_DEPLOY_DIR	Remote deployment directory
CPA_ROOT	CPAQuota root directory
CPA_AUTH_DIR	CPAQuota auth directory
CPA_MANAGEMENT_KEY_PATH	CPAQuota management key file
CPA_START_SCRIPT	CPA start script path
CPA_BASE_URL	CPA local base URL

Startup

npm start

The Web UI opens at:

http://127.0.0.1:18731/

Workflow

1. The refresh action reads Sub2 accounts and local CPA auth files.
2. The diff table groups accounts into missing, possible update, matched, CPA-only, and unsupported categories.
3. Missing accounts are selected by default.
4. Possible updates require manual selection.
5. The apply action creates a full CPA auth backup, uploads selected Codex auth JSON files through the CPA management API, restarts CPA, and rechecks CPA health.
6. The report action exports a Markdown diff report without secrets.

Sub2 Account Read Strategy

The primary source is the Sub2API administrator export endpoint:

GET /api/v1/admin/accounts/data?platform=openai&type=oauth&include_proxies=false

If the API request fails, the tool falls back to a read-only SSH query:

ssh sub2api
cd /opt/sub2api-deploy
docker compose exec -T postgres psql -U sub2api -d sub2api -Atc <query>

The administrator JWT field in the Web UI is process-local. The token is not persisted to disk.

CPA Write Strategy

The apply action prefers the CPA management API when a process-local management key is loaded. The upload request uses POST /v0/management/auth-files with multipart/form-data and a file field, matching the built-in CPA Management Center upload flow.

If no management key is loaded, the action writes CPA auth JSON files directly to the configured auth directory as a fallback. Fallback writes are reported in the apply result as wroteViaManagementApi: false.

If a management key is loaded and the CPA management upload fails, the apply action stops with an error instead of falling back to a direct directory write.

Before writing, the complete auth directory is copied to:

%USERPROFILE%\CPAQuota\auth_backup_before_sub2_sync_<timestamp>

After writing, the CPA process is restarted through the configured start script. A health check treats 200 through 499 responses from /v1/models as proof that the local service is reachable; 401 means the service is alive and requires API key authentication.

Tests

npm test

The test suite covers account mapping, identity matching, diff categories, filename normalization, collision handling, and apply-plan filtering.