@tibame201020/queqiao-http 0.1.1 → 0.1.2

package/README.md

@@ -1,48 +1,202 @@
-# Queqiao HTTP
+# @tibame201020/queqiao-http
 
-Bounded outbound HTTP extension for [Queqiao](https://github.com/tibame201020/Queqiao).
+[English](https://github.com/tibame201020/queqiao-http/blob/main/README.md) | [繁體中文](https://github.com/tibame201020/queqiao-http/blob/main/README.zh-TW.md)
 
-It exposes one Worker-hosted capability, `http_request`, through Queqiao's stable `extension` proxy. It uses `context.runtime.http.request()`; it does not invoke `curl`, a shell, `child_process`, or unrestricted global `fetch`.
+Official bounded HTTP extension for [Queqiao](https://github.com/tibame201020/Queqiao).
 
-## MVP scope
+`@tibame201020/queqiao-http` lets a Queqiao Worker call explicitly authorized HTTP/HTTPS origins through Queqiao's managed Extension runtime. It exposes one capability, `http_request`, through Queqiao's stable public `extension` proxy instead of adding a new public connector tool.
 
-Allowed origins are intentionally fixed in the extension manifest:
+It uses `context.runtime.http.request()` directly. It does **not** invoke `curl`, a shell, `child_process`, or unrestricted global `fetch`.
 
-- `http://127.0.0.1:9889`
-- `http://localhost:9889`
+## Status
 
-Requests to other origins are rejected by Queqiao's Worker runtime with `extension_network_denied`. Redirects, request/response bounds, cancellation, and timeout behavior remain owned by Queqiao.
+v0.1 baseline for Queqiao 0.9.7. The canonical npm package is `@tibame201020/queqiao-http`. Starting with v0.1.1, releases are published automatically from GitHub Releases through npm Trusted Publishing with provenance.
 
-## Install locally
+The current v0.1 runtime policy is intentionally narrow and has been validated end-to-end against the local Personal Asset Manager API on port `9889`.
 
-```powershell
-npm install
-npm run check
-queqiao extension install . --worker <worker-name>
+Verified acceptance chain:
+
+```text
+MCP client / LLM
+→ Queqiao Gateway
+→ Queqiao Worker
+→ stable extension proxy
+→ queqiao-http
+→ Queqiao managed HTTP runtime
+→ authorized REST API
+```
+
+Verified behavior includes:
+
+- successful JSON GET requests;
+- automatic JSON response parsing;
+- backend HTTP 4xx responses preserved as normal HTTP responses;
+- unauthorized origins rejected with `extension_network_denied`;
+- no public Queqiao connector manifest expansion when the extension is installed or updated.
+
+## Install
+
+Install from npm and attach to every Worker:
+
+```bash
+queqiao extension install npm:@tibame201020/queqiao-http --attach-all
+```
+
+Or install into the Extension Hub first and attach a selected Worker later:
+
+```bash
+queqiao extension install npm:@tibame201020/queqiao-http
+queqiao extension attach dev.queqiao.http --worker windows
 ```
 
+`attach` is activation. There is no separate enable/disable state.
+
+Because Queqiao exposes extensions through the stable public `extension` proxy, installing or updating `queqiao-http` does not require rebuilding the ChatGPT / MCP connector manifest.
+
+## Allowed origins
+
+The v0.1 package deliberately grants only these exact origins:
+
+```text
+http://127.0.0.1:9889
+http://localhost:9889
+```
+
+Requests to any other origin are rejected by the Queqiao Worker runtime.
+
+This means v0.1 is a bounded HTTP extension for the current local service integration, **not** an unrestricted arbitrary-internet HTTP client. A future configurable-origin design should extend Queqiao's deployment/runtime grant model rather than bypassing it inside this extension.
+
 ## Capability
 
-`http_request` accepts:
+`queqiao-http` registers one capability:
 
-- `workspaceId`
-- `url`
-- `method`: `GET | POST | PUT | PATCH | DELETE | HEAD` (default `GET`)
-- `headers` (optional)
-- `body` or `json` (mutually exclusive)
-- `timeoutMs` (100-120000, default 30000)
+```text
+http_request
+```
 
-When `json` is supplied, it is serialized and `content-type: application/json` is added unless already present. JSON responses are returned with both the raw `body` and a parsed `json` field when parsing succeeds. Non-2xx HTTP responses are returned as responses rather than converted into transport errors.
+Input fields:
+
+- `workspaceId` — selected Queqiao Workspace;
+- `url` — full HTTP/HTTPS URL under an allowed origin;
+- `method` — `GET | POST | PUT | PATCH | DELETE | HEAD`, default `GET`;
+- `headers` — optional string header map;
+- `body` — optional raw string body;
+- `json` — optional JSON value, mutually exclusive with `body`;
+- `timeoutMs` — `100` to `120000`, default `30000`.
+
+When `json` is supplied, the extension serializes it and adds `content-type: application/json` unless the caller already supplied a Content-Type header.
+
+### Call through Queqiao's extension proxy
+
+A client using Queqiao's stable public `extension` tool can invoke the capability like this:
+
+```json
+{
+  "workspaceId": "codes",
+  "operation": "call",
+  "extensionId": "dev.queqiao.http",
+  "capability": "http_request",
+  "arguments": {
+    "url": "http://127.0.0.1:9889/api/meal/types",
+    "method": "GET"
+  }
+}
+```
+
+### JSON POST
+
+```json
+{
+  "workspaceId": "codes",
+  "operation": "call",
+  "extensionId": "dev.queqiao.http",
+  "capability": "http_request",
+  "arguments": {
+    "url": "http://127.0.0.1:9889/api/trans/save",
+    "method": "POST",
+    "json": {
+      "type": "支出",
+      "category": "食",
+      "name": "牛肉麵",
+      "value": 180,
+      "transDate": "2026-09-07T00:00:00"
+    }
+  }
+}
+```
+
+## Response contract
+
+Successful transport execution returns the downstream HTTP response without converting non-2xx status codes into transport failures:
+
+```json
+{
+  "status": 200,
+  "headers": {
+    "content-type": "application/json"
+  },
+  "body": "{\"ok\":true}",
+  "json": {
+    "ok": true
+  }
+}
+```
+
+`json` is included only when the response body can be parsed as JSON. `body` always preserves the raw response text.
+
+For example, an application-level `HTTP 400` validation response remains a response with `status: 400`. Runtime policy failures such as a denied origin remain Queqiao runtime errors instead.
+
+## Trust boundary
+
+Queqiao extensions are trusted plugin code. Installing and attaching `queqiao-http` grants this extension authority to issue requests only through the managed Worker HTTP surface declared by its manifest.
+
+Queqiao remains authoritative for:
+
+- explicit package install/attach intent;
+- Extension contract validation;
+- exact-origin authorization;
+- HTTP/HTTPS scheme validation;
+- redirect denial;
+- request/response bounds;
+- timeout and cancellation handling;
+- Gateway → Worker routing and ExtensionHost lifecycle.
+
+`queqiao-http` owns only the request-level adapter behavior: validating its input, serializing optional JSON, calling `context.runtime.http.request()`, and normalizing the returned response.
+
+The extension intentionally has:
+
+```text
+process allowlist: empty
+shell access: none
+curl execution: none
+child_process: none
+unrestricted global fetch: none
+```
 
 ## Development
 
-```powershell
-npm test
-npm run typecheck
-npm run build
+```bash
+npm ci
 npm run check
+npm pack --ignore-scripts --dry-run
+```
+
+The test suite covers request mapping, JSON serialization/parsing, body/JSON exclusivity, non-2xx preservation, runtime error propagation, manifest/schema parity, bilingual package documentation, and release workflow invariants.
+
+## Releasing
+
+Releases are tag-driven after the initial npm bootstrap:
+
+```text
+main CI passes
+→ tag v<package-version>
+→ publish matching GitHub Release
+→ Publish npm workflow
+→ npm Trusted Publishing + provenance
 ```
 
-## Publishing
+See [`docs/releasing.md`](docs/releasing.md).
+
+## License
 
-GitHub Releases publish matching `v<version>` tags to npm through OIDC trusted publishing. See [`docs/releasing.md`](docs/releasing.md) for the one-time bootstrap and trusted-publisher setup.
+MIT

package/README.zh-TW.md

@@ -0,0 +1,202 @@
+# @tibame201020/queqiao-http
+
+[English](https://github.com/tibame201020/queqiao-http/blob/main/README.md) | [繁體中文](https://github.com/tibame201020/queqiao-http/blob/main/README.zh-TW.md)
+
+[Queqiao](https://github.com/tibame201020/Queqiao) 的官方 bounded HTTP extension。
+
+`@tibame201020/queqiao-http` 讓 Queqiao Worker 能透過 Queqiao 管理的 Extension runtime，呼叫 manifest 明確授權的 HTTP/HTTPS origin。它只註冊一個 `http_request` capability，並透過 Queqiao 穩定的公開 `extension` proxy 使用，而不是為 HTTP 能力新增一個固定的 public connector tool。
+
+底層直接使用 `context.runtime.http.request()`；**不會**執行 `curl`、shell、`child_process`，也不使用 unrestricted global `fetch`。
+
+## 狀態
+
+v0.1 baseline 對應 Queqiao 0.9.7。Canonical npm package 為 `@tibame201020/queqiao-http`。自 v0.1.1 起，release 會在 GitHub Release 發布後，透過 npm Trusted Publishing + provenance 自動發布。
+
+目前 v0.1 runtime policy 刻意維持狹窄，並已對本機 `9889` port 的 Personal Asset Manager API 完成端到端驗證。
+
+已驗證的 acceptance chain：
+
+```text
+MCP client / LLM
+→ Queqiao Gateway
+→ Queqiao Worker
+→ stable extension proxy
+→ queqiao-http
+→ Queqiao managed HTTP runtime
+→ authorized REST API
+```
+
+已驗證行為包括：
+
+- JSON GET request 成功；
+- JSON response 自動解析；
+- backend HTTP 4xx 保留為正常 HTTP response；
+- 未授權 origin 會被 `extension_network_denied` 拒絕；
+- 安裝或更新 extension 不會擴張 Queqiao 公開 connector manifest。
+
+## 安裝
+
+從 npm 安裝並 attach 到所有 Worker：
+
+```bash
+queqiao extension install npm:@tibame201020/queqiao-http --attach-all
+```
+
+或先安裝到 Extension Hub，再 attach 到指定 Worker：
+
+```bash
+queqiao extension install npm:@tibame201020/queqiao-http
+queqiao extension attach dev.queqiao.http --worker windows
+```
+
+`attach` 即為 activation，沒有另外的 enable/disable 狀態。
+
+因為 Queqiao 使用固定的公開 `extension` proxy 暴露 extension，安裝或更新 `queqiao-http` 不需要重建 ChatGPT / MCP connector manifest。
+
+## 允許的 origins
+
+v0.1 package 只明確授權以下 exact origins：
+
+```text
+http://127.0.0.1:9889
+http://localhost:9889
+```
+
+任何其他 origin 都會由 Queqiao Worker runtime 拒絕。
+
+因此 v0.1 是針對目前本機服務整合的 bounded HTTP extension，**不是** unrestricted arbitrary-internet HTTP client。未來若要支援可配置 origin，應擴充 Queqiao 的 deployment/runtime grant model，而不是在 extension 內繞過安全邊界。
+
+## Capability
+
+`queqiao-http` 只註冊一個 capability：
+
+```text
+http_request
+```
+
+輸入欄位：
+
+- `workspaceId` — 選定的 Queqiao Workspace；
+- `url` — 位於允許 origin 下的完整 HTTP/HTTPS URL；
+- `method` — `GET | POST | PUT | PATCH | DELETE | HEAD`，預設 `GET`；
+- `headers` — optional string header map；
+- `body` — optional raw string body；
+- `json` — optional JSON value，與 `body` 互斥；
+- `timeoutMs` — `100` 到 `120000`，預設 `30000`。
+
+提供 `json` 時，extension 會自動 serialize，且在 caller 未提供 Content-Type 時補上 `content-type: application/json`。
+
+### 透過 Queqiao extension proxy 呼叫
+
+使用 Queqiao 穩定公開 `extension` tool 的 client，可以這樣呼叫：
+
+```json
+{
+  "workspaceId": "codes",
+  "operation": "call",
+  "extensionId": "dev.queqiao.http",
+  "capability": "http_request",
+  "arguments": {
+    "url": "http://127.0.0.1:9889/api/meal/types",
+    "method": "GET"
+  }
+}
+```
+
+### JSON POST
+
+```json
+{
+  "workspaceId": "codes",
+  "operation": "call",
+  "extensionId": "dev.queqiao.http",
+  "capability": "http_request",
+  "arguments": {
+    "url": "http://127.0.0.1:9889/api/trans/save",
+    "method": "POST",
+    "json": {
+      "type": "支出",
+      "category": "食",
+      "name": "牛肉麵",
+      "value": 180,
+      "transDate": "2026-09-07T00:00:00"
+    }
+  }
+}
+```
+
+## Response contract
+
+Transport 成功執行後會回傳 downstream HTTP response；非 2xx status 不會被轉成 transport failure：
+
+```json
+{
+  "status": 200,
+  "headers": {
+    "content-type": "application/json"
+  },
+  "body": "{\"ok\":true}",
+  "json": {
+    "ok": true
+  }
+}
+```
+
+只有 response body 可成功 parse 為 JSON 時才會提供 `json`；`body` 永遠保留原始 response text。
+
+例如 application validation 的 `HTTP 400` 仍會以 `status: 400` response 回傳。相對地，origin 未授權這類 runtime policy failure，會維持 Queqiao runtime error。
+
+## 信任邊界
+
+Queqiao extension 屬於 trusted plugin code。安裝並 attach `queqiao-http`，代表允許 extension 在自己的 manifest runtime policy 範圍內，透過 Worker managed HTTP surface 發出 request。
+
+Queqiao 仍負責：
+
+- 明確的 package install/attach intent；
+- Extension contract validation；
+- exact-origin authorization；
+- HTTP/HTTPS scheme validation；
+- redirect denial；
+- request/response bounds；
+- timeout 與 cancellation；
+- Gateway → Worker routing 與 ExtensionHost lifecycle。
+
+`queqiao-http` 只負責 request-level adapter：驗證 input、serialize optional JSON、呼叫 `context.runtime.http.request()`，以及 normalize response。
+
+Extension 刻意不具備：
+
+```text
+process allowlist: empty
+shell access: none
+curl execution: none
+child_process: none
+unrestricted global fetch: none
+```
+
+## 開發
+
+```bash
+npm ci
+npm run check
+npm pack --ignore-scripts --dry-run
+```
+
+Test suite 會驗證 request mapping、JSON serialization/parsing、body/JSON 互斥、non-2xx preservation、runtime error propagation、manifest/schema parity、中英文 package documentation，以及 release workflow invariants。
+
+## 發布
+
+首次 npm bootstrap 完成後，release 採 tag-driven：
+
+```text
+main CI passes
+→ tag v<package-version>
+→ publish matching GitHub Release
+→ Publish npm workflow
+→ npm Trusted Publishing + provenance
+```
+
+另見 [`docs/releasing.md`](docs/releasing.md)。
+
+## 授權
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tibame201020/queqiao-http",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Bounded outbound HTTP extension for Queqiao",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,6 +15,7 @@
   "files": [
     "dist/",
     "README.md",
+    "README.zh-TW.md",
     "LICENSE"
   ],
   "scripts": {
@@ -42,7 +43,7 @@
     "module": "./dist/index.js",
     "manifest": {
       "id": "dev.queqiao.http",
-      "version": "0.1.1",
+      "version": "0.1.2",
       "displayName": "Queqiao HTTP",
       "host": {
         "kind": "worker"