# Sub2API Business Plugin Control Plane V1

This directory contains the independent administrator-only control plane for
Business Plugins. It is deliberately separate from Sub2API Core and from the
existing `.s2plugin` OpenAI OAuth transport runtime.

The control plane owns the installed-plugin registry, a constrained marketplace
catalog, signed package verification,
revision directories, lifecycle state, encrypted configuration metadata,
menu preview/apply, and its own audit log. Core remains authoritative for
users, administrator roles, balances, subscriptions, billing, and audit
records. The service never connects to Core PostgreSQL/Redis and never sends a
Core JWT or Admin Key to the browser.

## Run locally

```sh
CORE_BASE_URL=http://127.0.0.1:8080 \
PLUGIN_HOST=127.0.0.1 PLUGIN_PORT=8090 \
PLUGIN_REGISTRY_DIR=./data \
PLUGIN_ENV=development \
PLUGIN_ALLOW_UNSIGNED=true \
PLUGIN_CONFIG_KEY=local-development-secret-at-least-32-chars \
go run .
```

`PLUGIN_ALLOW_UNSIGNED=true` is a development-only switch. Production
packages must contain `signature.json`, use Ed25519, and match a trusted key
from `PLUGIN_TRUSTED_PUBLISHERS` (a JSON object of key ID to base64 public
key). `PLUGIN_CONFIG_KEY` is required in every environment; use a randomly
generated secret in production and keep it stable across restarts so encrypted
plugin configuration remains decryptable.

When the optional subscription module is enabled, set `PLUGIN_PUBLIC_URL` to
the externally reachable Plugin Admin base URL (without `/admin`), for example
`https://CORE_ORIGIN/extensions/qiu.plugin-admin`. Menu apply then always emits
`/admin/#/modules/subscription/overview`; a subscription service URL is never
used as a browser entrypoint.

Open `/admin/` directly or expose the service through the reverse proxy in
`deploy/`. The first login is the existing Core administrator login; no plugin
user table is created. The control plane stores only a short-lived server-side
session and encrypted plugin configuration.

The administrator UI is organized as separate hash-routed pages: overview,
installed plugins, marketplace, and operations. Each plugin has its own detail
route with secondary tabs for health, revisions, configuration, menu
integration, and history. See
[`../../docs/PLUGIN_ADMIN_UI_INFORMATION_ARCHITECTURE.md`](../../docs/PLUGIN_ADMIN_UI_INFORMATION_ARCHITECTURE.md)
for the page responsibilities and responsive layout contract.

### TDesign UI build

The browser shell is a standalone Vue 3 application based on the Tencent
TDesign Vue Next starter. It is built outside the Core repository and then
embedded by this Go service:

```sh
./build-ui.sh
```

The command runs `npm ci`, type-checks the application, bundles TDesign Icons
and ECharts locally (the service CSP does not allow a CDN), and copies the
three runtime files into `ui/`. The generated shell keeps the existing
`/login`, `/api/me`, CSRF and lifecycle contracts; no Core source or frontend
build configuration is involved.

### 会话与令牌生命周期

插件进程是常驻服务，不会因为一次登录、一次请求或一次令牌刷新而重启。
Core 的 access token 过期时，插件后端在当前请求链路中使用对应的 refresh
token 刷新一次，并继续完成请求；刷新后的 token 仍只保存在插件服务端。
浏览器始终只持有插件的 HttpOnly 会话 Cookie 和 CSRF token。

默认会话策略如下：

| 情况 | 行为 |
| --- | --- |
| 持续使用 | 每次请求滑动续期，通常无需重新登录 |
| 空闲超过 30 分钟 | 插件会话失效，下一次访问回到登录页 |
| 会话达到 8 小时 | 绝对过期，需要重新登录 |
| Core access token 过期 | 后端透明 refresh，不重启插件 |
| refresh token 被撤销/失效 | 清除插件会话并要求重新登录 |
| 插件进程重启 | V1 内存会话清空，需要重新登录一次；已登记的插件由控制面按 registry 恢复 |

因此日常使用不需要“用完就重启”。生产多实例若需要跨实例或跨重启保留
会话，应接入插件自己的加密 Redis/会话存储，并使用稳定的密钥；不要把
Core token 写入浏览器、Core 数据库或 URL。

## Control-plane endpoints

```text
GET  /healthz
GET  /readyz
POST /login                 POST /login/2fa       POST /logout
GET  /api/captcha-config
GET  /api/marketplace       POST /api/marketplace/install (JSON: plugin_id, version)
GET  /api/me                GET  /api/plugins     GET /api/plugins/{id}
POST /api/plugins/install         (multipart field: package)
POST /api/plugins/{id}/install    (multipart field: package)
POST /api/plugins/{id}/upgrade    (multipart field: package)
POST /api/plugins/{id}/enable|disable|rollback|uninstall
DELETE /api/plugins/{id}          (same delete operation as uninstall)
GET|PUT /api/plugins/{id}/config
POST /api/plugins/{id}/menu-preview|menu-apply
POST /api/menu-items/preview|apply   (JSON: {"plugin_id":"..."})
GET  /api/audit
GET  /api/subscription/status
GET  /api/subscription/audit
GET  /api/subscription/plans
GET  /api/subscription/subscriptions[/{id}]
GET  /api/subscription/users/{id}[/subscriptions]
```

Every mutation requires the plugin CSRF token and an `Idempotency-Key`. A
mutation returns an operation ID even when it completes synchronously. A local
upload or marketplace download only verifies and stages the package in the
registry (`disabled` / “已入库，待启用”); it never starts a process. The
administrator must configure the service and click **enable**. Only a
successful health and readiness check changes the plugin to `healthy` and
installs its runtime/menu. Failed installation and upgrade never replace the
active revision. Delete/uninstall is allowed only after disable and removes
plugin files, not Core data.

The login page reads only public CAPTCHA fields from `/api/captcha-config`.
When Core enables Turnstile, Tencent Captcha, or Aliyun Captcha, the matching
challenge is rendered in this page and its one-time proof is forwarded
server-side to Core. Provider secrets are never returned. Keep the provider
origins in the example CSP when CAPTCHA is enabled; changing the Core setting
is picked up on the next login-page load and does not require a plugin restart.

## Marketplace catalog

The marketplace is server-side only. The browser receives metadata and sends a
plugin ID/version; it never receives an archive URL and cannot request an
arbitrary download. Set `PLUGIN_MARKETPLACE_INDEX` to a local JSON file (the
default) or an HTTPS index URL. Remote indexes and archives are restricted to
the exact hosts in `PLUGIN_MARKETPLACE_ALLOWED_HOSTS`; HTTP is accepted only
for loopback sources in `PLUGIN_ENV=development`. Redirects, credentials,
queries, fragments, oversized responses, path escapes, and hash mismatches are
rejected. The package must still pass the normal manifest signature, file hash,
and Core compatibility checks.

Catalog format (schema version 1):

```json
{
  "schema_version": 1,
  "source": "internal-release-catalog",
  "entries": [
    {
      "plugin_id": "example.plugin",
      "name": "Example Plugin",
      "version": "1.0.0",
      "description": "Administrator extension",
      "archive_url": "example.plugin-1.0.0.s2plugin",
      "archive_sha256": "SHA256_OF_ARCHIVE",
      "archive_size": 12345,
      "publisher_key_id": "publisher-key-id",
      "core_api_baseline": "sub2api-0.1.183",
      "tested_core_versions": ["0.1.183"],
      "capabilities": ["example.v1"]
    }
  ]
}
```

An entry is never an implicit upgrade. If the plugin ID is already registered,
use the existing upgrade flow, then enable it explicitly.

## Plugin package

Packages are ZIP files with `manifest.json`, optional detached
`signature.json`, and declared `ui/` files. A package may also include
`service/` files when the control plane owns the plugin process; external
service packages omit `backend.command` and require a configured loopback
`service_url` before enabling. SHA-256 hashes in the manifest cover every
declared file. Absolute paths, traversal, duplicate entries, symlinks,
undeclared hashes, oversized files, unknown manifest fields, and untrusted
publishers are rejected before staging. Installation uses a per-plugin
revision directory and an atomic registry JSON update.

## Deliberate V1 limits

The control plane does not register Core routes, change Core migrations, run
arbitrary proxy URLs, provide transparent iframe SSO, or move billing and
subscription hot-path logic out of Core. A subscription manager remains a
separate business plugin that consumes its own typed Core API adapter.