feat: connect through an issued access token, not a host OAuth link

The gateway's /oauth/pat page hands out a token after the same login,
workspace and consent screens the OAuth flow used; the client then sends
it as an Authorization header. The OAuth link it replaces needs a browser
redirect over TLS, which an internal deployment without a trusted
certificate cannot complete.

plasma-mcp-setup is rewritten as a step-by-step walkthrough, and its
permission and diagnosis sections now speak in terms of re-issuing a
token rather than re-linking a connection: a new token does not inherit
an earlier one's scopes, so what is needed has to be ticked at issue time.

ChatGPT web drops out of scope. It connects from OpenAI's servers and
cannot reach an internal gateway at all, which is not something a
certificate would fix, so its connection and submission sections go
rather than sit there describing a path nobody can take.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Eeec7777

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plasma-plugin",
   "description": "以 Ophion 知識查核 SQL，建立並核對 Plasma view／mview 定義的工作流程。使用已連結的遠端 Plasma MCP 工具。",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "author": {
     "name": "Brobridge",
     "email": "bbgai@brobridge.com"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "plasma-plugin",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "以 Ophion 知識查核 SQL，建立並核對 Plasma view／mview 定義的工作流程。使用已連結的遠端 Plasma MCP 工具。",
   "author": {
     "name": "Brobridge",

README.md

@@ -1,6 +1,6 @@
 # Plasma workflows
 
-供 **ChatGPT 網頁版與 Claude** 使用的共用工作流程 plugin。
+供 **Claude Code 與 Codex CLI** 使用的共用工作流程 plugin。
 以 Ophion 知識查核來源與 SQL，建立 view／manual mview 並核對定義後結束。
 兩種宿主共用同一份 skills，分別提供原生 manifest 與 ZIP。
 
@@ -10,13 +10,15 @@
 安裝 plugin 不會自動建立 MCP 連線或授予服務權限。
 
 ```text
-ChatGPT / Claude
+Claude Code / Codex CLI
 ├─ Plasma plugin：共用 skills
-└─ 宿主的 MCP client ── HTTPS + OAuth ──> plasma-backend /mcp
-                                         ├─ Plasma REST API
-                                         └─ Ophion 知識工具
+└─ 宿主的 MCP client ── HTTP + 存取權杖 ──> plasma-backend /mcp
+                                           ├─ Plasma REST API
+                                           └─ Ophion 知識工具
 ```
 
+ChatGPT 網頁版目前不支援：它由 OpenAI 伺服器連出，連不到內網的 gateway 位址。
+
 ## 功能與平台相容性
 
 | Skill | 用途 |
@@ -34,48 +36,38 @@ ChatGPT / Claude
 不建立 blueprint、不匯出檔案或外部資料庫、不發布資料 API，也不安排同步排程。
 後端若仍暴露其他工具，本 plugin 不把它們納入流程；伺服器工具權限由後端管理。
 
-## ChatGPT 網頁版
-
-### 先連結 Plasma 工具
+## 先連結 Plasma 工具
 
-管理員需提供可達的 HTTPS MCP endpoint，例如 `https://mcp.example.com/mcp`。
-在帳號及工作區政策允許時，開啟 developer mode，在 Plugins 建立遠端 MCP 連線，
-完成 OAuth 登入、選 workspace、同意 scopes，並將連線加入對話。
-已由管理員配置 Plasma app 時，直接連結該 app。以目前產品 UI 為準。
+管理員需提供可達的 MCP gateway 位址，並在後端開啟 `pat_enabled`。
+使用者到 `<gateway>/oauth/pat` 用自己的 Plasma 帳號登入、選 workspace、
+逐項勾選權限，核發一張存取權杖；該頁只顯示權杖一次。
 
-開始使用後先呼叫 `whoami`，確認 workspace、scopes 與知識服務狀態。
-詳見 [官方連線測試指南](https://developers.openai.com/plugins/deploy/connect-chatgpt)。
+把權杖放進環境變數後設定連線：
 
-### 安裝 workflows
+```bash
+export PLASMA_MCP_TOKEN='<權杖>'
 
-- **工作區 GitHub 匯入**：支援此能力的工作區由管理員在 Admin → Plugins 匯入本
-  repository；現有 Claude-compatible marketplace 可供匯入。成員仍須另外連結
-  Plasma app，並在對話啟用。匯入不代表已授權後端。
-- **ChatGPT 原生封裝**：`make release` 產生 `plasma-plugin_0.3.1_chatgpt.zip`，
-  內含 `.codex-plugin/plugin.json` 與三份 skills，供支援該格式的安裝／匯入流程使用。
-  這是未綁定 app 的 workflow 包，不是已上架或已完成工具連線的 plugin。
-- **綁定既有工作區 app**：取得真實 app ID 後，執行：
+# Claude Code
+claude mcp add --transport http plasma http://mcp.internal:5002/mcp \
+  --header 'Authorization: Bearer ${PLASMA_MCP_TOKEN}'
+```
 
-  ```bash
-  python3 scripts/package_plugin.py --app-id "$PLASMA_CHATGPT_APP_ID"
-  ```
+單引號與 `${...}` 讓 Claude Code 讀取設定時才展開，權杖不會寫進 `~/.claude.json`。
 
-  環境變數僅用來將真實 ID 傳給維護者封裝指令，執行 plugin 不需要它。
-  會產生額外的 `plasma-plugin_0.3.1_chatgpt-linked.zip`，包含 `.app.json` 與
-  manifest 的 app 引用，且不修改 repository 的共用 manifest。
-  支援 ID 前綴 `asdk_app_`、`connector_`、`templated_apps_`；不能使用 `plugin_` ID。
-  此指令只做封裝，不會註冊 app、驗證其存在、安裝或授予權限。
-- **公開 plugin 發布**：使用 OpenAI 的 **With MCP** 流程提交正式 endpoint，並在
-  同一 draft 加入 skills；不能以 skills-only 提交代替本專案需要的 MCP 整合。
-  `.app.json` 的工作區引用也不能代替公開 MCP 提交。
+```toml
+# Codex CLI — ~/.codex/config.toml
+[mcp_servers.plasma]
+url = "http://mcp.internal:5002/mcp"
+bearer_token_env_var = "PLASMA_MCP_TOKEN"
+experimental_use_rmcp_client = true
+```
 
-不要為了綁定網頁版工具而新增 `.mcp.json`、`mcp.json` 或 inline `mcpServers`：
-官方工作區匯入會把這類 plugin 標示為 Desktop only，即使 URL 是 HTTPS。
-參考 [官方工作區 plugin 管理](https://learn.chatgpt.com/docs/enterprise/plugin-management)
-與 [Claude plugin 移植／提交指南](https://developers.openai.com/plugins/guides/submit-claude-plugin)。
+開新對話後先呼叫 `whoami`，確認 workspace、scopes 與知識服務狀態。
+權杖到期不會自動更新，重新核發一張即可；外洩時用 `<gateway>/oauth/revoke` 撤銷。
 
-目前沒有預填 endpoint 或 app ID。完整連線與寫入流程仍須完成後端項目並在真實
-ChatGPT 帳號驗收，見 [後端修改清單](docs/backend-integration.md)。
+身分驗證、workspace 綁定與權限勾選都由 gateway 的核發頁執行，
+權杖本身則是長效憑證，沒有 PKCE 與輪替。取捨與後端設定見
+[後端修改清單](docs/backend-integration.md) 的 B7。
 
 ## Claude Code
 
@@ -86,14 +78,10 @@ ChatGPT 帳號驗收，見 [後端修改清單](docs/backend-integration.md)。
 /plugin install plasma-plugin@plasma-plugin-local
 ```
 
-透過 Claude Code 加入同一個遠端 MCP server（將 URL 換成真實部署）：
-
-```bash
-claude mcp add --transport http plasma https://mcp.example.com/mcp
-```
+MCP server 依上節「先連結 Plasma 工具」加入，URL 換成真實部署位址。
 
-完成授權後開新 session，先呼叫 `whoami`。不再安裝或執行任何 plugin binary。
-Claude 安裝包為 `plasma-plugin_0.3.1_claude.zip`；保留相同的三份 skills，無 hooks。
+設定完成後開新 session，先呼叫 `whoami`。不再安裝或執行任何 plugin binary。
+Claude 安裝包為 `plasma-plugin_0.3.2_claude.zip`；保留相同的三份 skills，無 hooks。
 其他 Claude 介面的 plugin 安裝能力以該產品為準，這裡的安裝指令專供 Claude Code。
 
 ## 升級自舊版
@@ -103,14 +91,15 @@ Claude 安裝包為 `plasma-plugin_0.3.1_claude.zip`；保留相同的三份 ski
 不要沿用舊對話載入的匯出／發布指示；新包中只有三份 skills。
 若曾手動將舊 hook 複製到宿主設定，請在該宿主刪除該自訂設定；新版不會執行舊 binary。
 本次不自動修改使用者家目錄、既有 MCP 連線或其他宿主設定。
-workspace 綁定於後端授權；換 workspace 要重新授權，plugin 不保存選擇。
+workspace 綁在權杖上；換 workspace 要重新核發一張，plugin 不保存選擇。
 
 ## 從 GitHub Actions 取得安裝包
 
 在 GitHub 開啟 **Actions → Package plugins → Run workflow**，選擇要封裝的分支，
 `tag` 留空即可。完成後在該次執行頁面的 **Artifacts** 下載
-`plasma-plugin-<版本>`，解壓縮後可取得 ChatGPT ZIP、Claude ZIP 與
-SHA-256 `checksums.txt`。Artifact 保留 30 天。
+`plasma-plugin-<版本>`，解壓縮後可取得 Claude ZIP、Codex ZIP 與
+SHA-256 `checksums.txt`。Codex 包的檔名沿用 `_chatgpt.zip`，內容是
+`.codex-plugin/plugin.json` 與同一份 skills。Artifact 保留 30 天。
 
 手動執行且 tag 留空只產生安裝包，不建立 GitHub Release。
 推送 `v*` tag，或手動指定既有 tag，會封裝該 tag 的程式，並同時將安裝包附加到
@@ -124,10 +113,10 @@ make check
 make release
 ```
 
-僅需 Python 3.10+；封裝使用標準函式庫。產物在 `dist/v0.3.1/`，包括兩個 ZIP
+僅需 Python 3.10+；封裝使用標準函式庫。產物在 `dist/v0.3.2/`，包括兩個 ZIP
 與 SHA-256 `checksums.txt`。安裝包只收錄對應宿主 manifest 與共用 Markdown skills，
 避免將開發工具、本機功能或後端修改清單帶入執行環境。
 
 更新 `VERSION`、兩份 manifest 與對應的 `releases/vX.Y.Z.md`，再依團隊流程提交
 及推送 tag。正式安裝包由 GitHub Actions 驗證、封裝並上傳，不再跨平台編譯 binary。
-本機產生 ZIP 不會自動推送 tag、發 GitHub Release 或上架 ChatGPT。
+本機產生 ZIP 不會自動推送 tag 或發 GitHub Release。

VERSION

@@ -1 +1 @@
-0.3.1
+0.3.2

docs/backend-integration.md

@@ -1,8 +1,13 @@
-# ChatGPT 網頁版：後端修改與驗收清單
+# 後端修改與驗收清單
 
 評估日期：2026-09-17。目標 repository：`plasma-backend`。
-本文件列的是 **backend 要補的項目**；plugin v0.3.1 僅調整封裝與 skills，沒有修改後端。
-MCP server 繼續由 Claude 與 ChatGPT 共用，不建立第二套工具服務。
+本文件列的是 **backend 要補的項目**。
+
+**目前的連線路徑是 B7 的存取權杖核發**，plugin 的 skills 與 README 只描述這一條。
+B1、B5 與下方部署章節中屬於 ChatGPT 網頁版的項目暫緩：網頁版由 OpenAI 伺服器連出，
+連不到內網 gateway，要支援得先有對外可達的 HTTPS endpoint。保留這些條目是因為
+它們記錄了後端尚未完成的工作，不代表 plugin 目前支援該宿主。
+B2、B4 與 Claude Code／Codex CLI 同樣相關。
 
 v0.3.1 範圍更新：唯一流程是建立並核對 view／manual mview 定義，沒有後續同步、
 blueprint、匯出或 API 發布。先前 B3（blueprint 輸出）與 B6（目的地／job 追蹤）
@@ -84,6 +89,49 @@ plugin 只呼叫 `whoami`、知識查核工具、`list_views`、`get_view`、`ru
 驗收：建立一般 view 和 manual mview 後無同步 job、無 blueprint／匯出／發布；
 若啟用受限 profile，直接呼叫範圍外工具或傳 scheduled 也必須被後端拒絕。
 
+## 已完成項目
+
+### B7 — 內網部署的權杖核發
+
+位置：`oauth_pat.go`（新增）、`oauth_pat_test.go`、`web/pat.html`、`web/consent.html`、
+`routes.go`、`module.go`、`oauth_jwt.go`、`render.go`、`models/oauth.go`。
+
+問題：MCP client 完成 OAuth 需要瀏覽器轉址，而內網 gateway 常沒有用戶端信任的
+HTTPS 憑證。ChatGPT 網頁版另有一層限制——它由 OpenAI 伺服器連出，連不到內網位址，
+與憑證無關，這條路徑無法用本項解決。
+
+作法：新增 `GET /oauth/pat`，重用既有的登入、workspace、同意三頁，只改最後一步——
+不簽發 authorization code 轉址回 client，而是建立 grant 並把長效 access token
+顯示在頁面上，由使用者貼進宿主設定。權杖以既有的 `verifyToken` 驗證，沒有第二條
+驗證路徑；grant 一樣綁 user、workspace 與 scopes，一樣存加密的 upstream refresh token，
+一樣能用 `/oauth/revoke` 立即撤銷。
+
+設定：
+
+```toml
+[mcp_gateway]
+pat_enabled = true          # 預設 false，未開啟時路由不存在
+pat_token_ttl = "2160h"     # 預設 90 天，上限 365 天
+```
+
+與 OAuth 的差異，開啟前要確認可以接受：
+
+- 沒有 PKCE、沒有一次性 code、沒有 refresh rotation 與重放偵測。
+- 權杖長效且靜態，存在使用者機器的環境變數或設定檔，有被 commit 或轉貼的風險。
+- `public_url` 仍是 `http://` 時，權杖與查詢內容在網路上是明文，只能靠網段隔離。
+- 過期沒有自動更新，要重走一次核發流程。
+
+未放寬的部分：身分仍由 plasma-backend 的 `/auth/login` 驗證，workspace 仍只能從
+`MyWorkspaces` 的結果選，權限仍要在同意頁逐項勾選。PAT 的 grant 使用保留的
+`client_id = "pat"`，不參與 OAuth 重新連結時的 scope 累積，因此新核發的權杖不會
+繼承舊權杖的權限；該 client 註冊的 redirect 清單是空的，無法被拿來走轉址流程。
+
+驗收：`go test ./pkg/mcp_gateway/ -run TestPAT` 涵蓋路由預設關閉、權杖可用於 `/mcp`、
+audience／workspace 綁定、TTL、錯誤密碼與非成員 workspace、CSRF、取消、
+profile 外 scope 被丟棄、不繼承舊權杖權限、撤銷後立即失效。
+尚未在真實 Claude Code 與 Codex CLI 上驗證：Codex 的 rmcp client 是否接受
+`http://` URL 未實測，若被擋則需在該機器以 loopback 轉發。
+
 ## 條件式項目與可用性改善
 
 ### B5 — 企業網域限制／正式發布的 identity 資訊

releases/v0.3.2.md

@@ -0,0 +1,13 @@
+# v0.3.2 — 改用存取權杖連線
+
+- 連線方式改為 gateway 的 `/oauth/pat` 核發存取權杖：使用者以 Plasma 帳號登入、
+  選 workspace、逐項勾選權限，再把權杖放進環境變數並設定用戶端。
+- `plasma-mcp-setup` 改寫為逐步引導流程，移除宿主 OAuth 登入與 HTTPS endpoint 說明。
+- 權限不足改為重新核發並勾選需要的 scope；新權杖不繼承舊權杖的權限。
+- 診斷改以權杖語彙描述：401、核發頁無法開啟、權杖過期或被撤銷。
+- README 對象改為 Claude Code 與 Codex CLI，移除 ChatGPT 網頁版連線與上架章節。
+- 後端待辦清單標示目前路徑為 B7，網頁版相關項目暫緩但保留紀錄。
+
+本版需要後端開啟 `pat_enabled`；未開啟時 `/oauth/pat` 不存在，沿用既有連線即可。
+ChatGPT 網頁版暫不支援：它由 OpenAI 伺服器連出，連不到內網 gateway 位址。
+更新後開新對話／session，避免沿用已載入的舊版流程。