CPA Update Center

CPA Update Center is a CLIProxyAPI ABI v1 management plugin backed by a detached transactional updater helper. The in-process plugin is only the control plane: it renders the Update Center, checks stable GitHub releases, verifies and launches the helper, and writes a private update plan. The helper owns all staging, process control, executable replacement, validation, and rollback work.

The plugin ID is cpa-update-center. The native library must therefore be named cpa-update-center.dll, cpa-update-center.so, or cpa-update-center.dylib.

Deployment support

Deployment	Check	Apply
Windows native portable	Yes	Yes
Linux/macOS writable native portable	Yes	Yes
Docker or Kubernetes	Yes	No; update the image and recreate the workload
Homebrew, apt, rpm, Snap, Nix, or obvious system paths	Yes	No; use the package manager
Unsupported operating systems	Yes where GitHub metadata is reachable	No

Linux and macOS apply support is enabled only when the exact executable directory is writable, the process is not containerized, and the resolved executable path is not recognized as package-managed. Windows still requires writable portable executables.

Safety boundary

• Trusted update repositories are fixed to router-for-me/CLIProxyAPI and seakee/CPA-Manager-Plus.
• Only non-draft, non-prerelease GitHub releases are accepted.
• Exactly one GOOS/GOARCH archive and exactly one checksums.txt must be present.
• SHA-256, optional GitHub asset digest, asset size, and HTTP Content-Length are cross-checked.
• The staged executable and helper must also parse as the selected platform's PE, ELF, or Mach-O architecture.
• ZIP and tar.gz entries are fully read and validated before any process is stopped. Traversal, symlinks, special files, duplicate output paths, and size-limit violations fail the update.
• Only cliproxyapi, cli-proxy-api, and cpa-manager-plus executables are eligible for replacement.
• Configuration, auths, SQLite files, data, logs, run, and installation directories are never copied or replaced.
• PID, process start token, and executable path are revalidated immediately before stop to prevent PID reuse.
• A private installed manifest records only updater-owned executable paths, versions, and SHA-256 values so already-current files are skipped without trusting unrelated installation contents.
• Backups and same-directory atomic renames are used. A failed restart or business validation stops the new processes, restores the old executables, and restarts the recorded old commands.

Management routes

• Resource page: /v0/resource/plugins/cpa-update-center/update-center
• Status: GET /v0/management/plugins/cpa-update-center/status
• Check: POST /v0/management/plugins/cpa-update-center/check
• Apply: POST /v0/management/plugins/cpa-update-center/apply

The three Management API routes are authenticated by CLIProxyAPI before dispatch to the plugin. The browser resource first tries the current same-origin management session. If the host returns 401 or 403, the page asks for the plaintext Management API key, keeps it only in page memory, and sends it as the request Authorization header. It is never written to browser storage.

The page loads status and checks the latest stable CPA release automatically. The normal CPA flow shows the installed and latest versions, then asks only for the CPA API key when the operator confirms an update. Manager process fields remain available under the advanced section rather than occupying the default update screen.

After Apply is accepted, the page clears the business-validation password fields and polls the persisted journal every two seconds. Download, switch, restart, validation, completion, and rollback states remain visible after a page refresh.

The Update Center offers CPA, Manager, and Both. Manager PID, executable path, working directory, and one-literal-argument-per-line restart arguments are explicit inputs so the helper can validate and reproduce the intended portable process. CPA restart arguments are captured from the running host process.

The CLIProxyAPI Management API key, CPA API key, and Manager key use password inputs and are not persisted by the page. The Management key is used only as the browser request Authorization header. A CPA-only update requires the CPA API key but does not require Manager credentials. Manager-only and combined updates still require both business-validation keys. Apply writes the required validation keys only to a mode 0600 or current-user ACL-protected plan, passes only the plan path on the helper command line, and removes the plan immediately after the helper loads it. Keys are never written to the journal, and restarted child stdout/stderr are discarded rather than captured by the updater.

Post-update acceptance

Before the helper starts, the plugin verifies the CPA base URL and API key with an authenticated Chat Completions request. Invalid credentials therefore fail before any process is stopped. For Manager-only or combined updates, the plugin also records Manager /status values for events and collector.totalInserted. After restart, the helper:

1. Sends an authenticated Chat Completions request to gpt-5.5 with user content hi.
2. Requires a successful completion with non-empty assistant content. The response model field is deliberately ignored and is never presented as proof of the native upstream model.
3. For Manager-only or combined updates, polls authenticated Manager /status until both counters increase and collector.lastError is empty.

Failure triggers rollback.

Installation

Enable dynamic plugins and place the current-platform library in the configured plugin directory, normally plugins/<GOOS>/<GOARCH>:

plugins:
  enabled: true
  dir: plugins
  configs:
    cpa-update-center:
      enabled: true
      priority: 1

Open the Update Center resource from the CLIProxyAPI management interface.

Release assets

Tagged releases build native assets on official GitHub-hosted runners for Windows, Linux, and macOS on amd64 and arm64:

cpa-update-center_<version>_<goos>_<goarch>.zip
cpa-update-helper_<version>_<goos>_<goarch>.zip
checksums.txt

Every plugin ZIP contains exactly one root entry named cpa-update-center.dll, cpa-update-center.so, or cpa-update-center.dylib. Every helper ZIP is separate and contains exactly one root helper executable. The project does not claim or fabricate a code-signing capability; release integrity is based on GitHub release identity plus SHA-256 verification.

Plugins Store submission

1. Publish a tagged GitHub release using .github/workflows/release.yml.
2. Verify the six plugin ZIPs, six helper ZIPs, and checksums.txt; confirm each plugin ZIP has only the correctly named root library.
3. Confirm plugin metadata points to this repository and the library basename remains cpa-update-center.
4. Open a pull request against router-for-me/CLIProxyAPI-Plugins-Store that updates only registry.json unless the official documentation also needs clarification.
5. Add this schema-v1 entry, updating the repository owner first if the project is transferred:

{
  "id": "cpa-update-center",
  "name": "CPA Update Center",
  "description": "Checks and transactionally updates portable CPA and CPA Manager Plus executables.",
  "author": "systemoutprintlnhelloworld",
  "repository": "https://github.com/systemoutprintlnhelloworld/CPA-Update-Center-Plugin",
  "homepage": "https://github.com/systemoutprintlnhelloworld/CPA-Update-Center-Plugin",
  "license": "MIT",
  "tags": ["management", "update"]
}

6. Include the latest v<version> release tag, evidence for the platform plugin ZIPs and checksums.txt, and a short summary of the ManagementAPI capability in the pull request. The helper ZIPs remain author-hosted companion assets and do not replace the store-required plugin ZIPs.

Development

The plugin requires Go 1.26 and CGO for -buildmode=c-shared. The helper is a normal Go executable. Typical local commands are:

gofmt -w .
go build -buildmode=c-shared -o cpa-update-center.so ./cmd/plugin
go build -o cpa-update-helper ./cmd/cpa-update-helper
go test ./...

A build whose embedded version contains -local runs in explicit local development mode. It loads cpa-update-helper(.exe) from the host's plugins/<GOOS>/<GOARCH> directory instead of querying a nonexistent development GitHub release. CPA-only updates always use authenticated CPA validation without requiring Manager validation. Manager-only and combined updates retain the Manager baseline and counter checks in both local and tagged builds.

See docs/design.md for the complete transaction design and remaining platform caveats.