fufu-cloud-cli 0.5.0__tar.gz

fufu_cloud_cli-0.5.0/LICENSE

@@ -0,0 +1,6 @@
+All rights reserved.
+
+This distribution is not offered under an open-source license. No permission
+to redistribute, modify, or sublicense the FUFU Cloud CLI source is granted
+by publication of this package. Third-party components retain their own
+licenses, as stated in THIRD_PARTY_NOTICES.md when bundled.

fufu_cloud_cli-0.5.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md LICENSE
+recursive-include src *.py *.json Dockerfile

fufu_cloud_cli-0.5.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: fufu-cloud-cli
+Version: 0.5.0
+Summary: FUFU Cloud CLI for tenant-scoped mock cloud development and deployment
+License-Expression: LicenseRef-Proprietary
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML==6.0.3
+Provides-Extra: yaml
+Requires-Dist: PyYAML==6.0.3; extra == "yaml"
+Dynamic: license-file
+
+# FUFU Cloud CLI
+
+以四個指令操作 FUFU Cloud 的租戶隔離開發環境：`fufu`、`aws-fufu`、
+`gcloud-fufu`、`az-fufu`。這是 AWS、Google Cloud 與 Azure 的**明確子集**，
+只供 FUFU mock 環境使用；不會把部署轉送到正式雲端。
+
+## 安裝
+
+需要 Python 3.10 以上。Python 套件預設包含 YAML 相依套件：
+
+```bash
+pip install fufu-cloud-cli
+fufu --version
+```
+
+npm 版本需要 Node.js 18 以上，以及已安裝的 Python 3.10 以上；四個入口
+呼叫相同的 Python CLI。npm 包內附純 Python YAML parser，沒有安裝腳本，
+不會自行下載 Python 或執行 pip。
+
+```bash
+npm install fufu-cloud-cli
+npx --no-install fufu --version
+npx --no-install aws-fufu --help
+```
+
+全域安裝可使用 `npm install -g fufu-cloud-cli`。預設 Python 指令為 `python3`；
+若名稱不同，將 `FUFU_PYTHON` 設成可信 Python 執行檔的路徑。
+本機 Docker backend 只支援 Linux 與本機 Unix socket。API backend
+不需要安裝 Docker；其他作業系統仍須另外驗證其 Python 與網路環境。
+
+## 憑證與 CI
+
+向 FUFU Cloud 管理者取得該租戶、該 provider 的專用 credential JSON。
+CLI 不附預設帳號、共用金鑰或可用的租戶憑證，也不讀取 `.env`、瀏覽器
+Cookie 或正式雲端登入工作階段。
+
+在 CI 的秘密管理功能中注入 credential 檔案，並設定：
+
+```bash
+export FUFU_BACKEND=api
+export FUFU_AWS_CREDENTIAL_FILE=/run/secrets/fufu-aws.json
+export FUFU_GCP_CREDENTIAL_FILE=/run/secrets/fufu-gcp.json
+export FUFU_AZURE_CREDENTIAL_FILE=/run/secrets/fufu-azure.json
+
+fufu auth whoami --provider aws
+aws-fufu sts get-caller-identity
+gcloud-fufu auth list
+az-fufu account show
+```
+
+credential 內含 FUFU endpoint。`FUFU_ENDPOINT` 可明確覆寫目的地：僅限
+你信任且獲授權接收 credential 的 FUFU 服務。正式網路需使用 HTTPS；
+只有 loopback 允許 HTTP。TLS 憑證驗證保持開啟，不跟隨重新導向，
+不繼承系統 HTTP proxy。
+
+一般命令交換短期權杖並在結束時嘗試撤銷。`fufu auth assume-role`
+可建立受限 session 檔，檔案以排他方式建立且權限為 `0600`；請勿提交。
+FUFU credential 與 session 檔仍屬秘密，必須由作業系統和 CI 控制存取。
+原生雲端的 GitHub auth actions、OIDC、SigV4 和 OAuth 不直接相容。
+
+## 部署與支援範圍
+
+```bash
+fufu capabilities
+fufu capabilities --remote --provider gcp --require cloud-run-http
+gcloud-fufu run deploy example --image approved-image:tag
+gcloud-fufu functions deploy example-function --gen2 \
+  --runtime python312 --source ./function --entry-point handler --trigger-http
+aws-fufu lambda list-functions
+```
+
+映像需先由 FUFU 管理者準備及核准。Function 來源會上傳指定目錄中的
+Python 與 requirements 檔；Lambda 會上傳指定的 ZIP。請使用只含必要程式碼的
+目錄或 ZIP，先移除硬編碼秘密、個人資料與不需要的檔案。
+CLI 無法判斷任意原始碼或 ZIP 內的資料是否可以分享。
+
+| 服務 | 可用範圍與主要限制 |
+| --- | --- |
+| Cloud Run | 單一已核准 HTTP 容器；無 autoscaling、traffic splitting、Jobs 或公開 ingress |
+| Cloud Run functions / Functions Gen 1 | Python 3.12 HTTP 函式；Gen 1 為相同 HTTP runtime 的模擬子集，無背景事件 |
+| AWS Lambda | Python 3.10 / 3.12 ZIP、同步 invoke、程式碼更新；遠端 ZIP 上限 6 MiB |
+| GCS / S3 | bucket 與 object 操作子集；單一 object 上限 6 MiB，無 versioning / signed URL |
+| DynamoDB / SQS / SSM | 明列資料操作；無完整交易、Streams、FIFO 或 KMS / SecureString |
+| AWS IAM / GCP IAM | 租戶內 role / service account / policy 子集；default deny、限定 session；無原生雲端全量 IAM 語義 |
+| API Gateway / Serverless profile | 簡化 HTTP Lambda proxy 和明確來源清單；不執行 plugins / CloudFormation |
+| Azure | account 與資源群組目錄；尚無 Azure Functions 或其他 Azure runtime |
+| EC2 / ECS / App Engine 等 | 部分只有 mock 目錄；不能視為執行中的 VM、Task 或應用 |
+
+`fufu capabilities` 是隨版支援清單；`--remote` 另外查詢服務端能力。
+`implemented` 代表明列子集已接入，`partial`、`mock-only`、`unsupported`
+均不代表完整服務可用。未支援命令、旗標、YAML 欄位會拒絕，CI 應檢查退出碼。
+
+## YAML / JSON
+
+Cloud Run manifest 支援 `serving.knative.dev/v1`、`kind: Service`、
+`metadata.name`、單一 container 的 image / port / env，以及明列的 service account。
+`fufu plan --file service.yaml` 可在不部署的情況下檢查設定；plan 僅列出環境變數名稱。
+相同設定可用 JSON。其他正式雲端欄位需要顯式調整，不能宣稱所有設定無痛相容。
+
+## 隱私與執行邊界
+
+- 套件沒有遙測、廣告、背景更新或安裝時網路腳本。
+- API 請求只使用明確提供的 FUFU endpoint 和 credential；不掃描使用者家目錄。
+- `whoami` 會輸出目前租戶、provider 與 scope；查詢／invoke 會輸出所要求的資料。
+  請將 CI 日誌視為可能包含應用資料，不把敏感查詢結果公開。
+- 本機部署會操作 Docker。明確執行 runtime prepare 或 function build 時，
+  可能下載固定映像或安裝應用 requirements；不可信 requirements 仍可執行建置程式。
+- FUFU 服務端的租戶隔離、IAM、日誌保存與資料保護由服務端負責。
+  CLI 的本機檢查不等於對任何遠端部署作永久安全保證。
+
+本套件目前保留著作權，未授予開源授權。套件公開可下載與原始碼採用開源授權
+是不同事項；第三方 YAML parser 依其 MIT 授權散布。

fufu_cloud_cli-0.5.0/README.md

@@ -0,0 +1,112 @@
+# FUFU Cloud CLI
+
+以四個指令操作 FUFU Cloud 的租戶隔離開發環境：`fufu`、`aws-fufu`、
+`gcloud-fufu`、`az-fufu`。這是 AWS、Google Cloud 與 Azure 的**明確子集**，
+只供 FUFU mock 環境使用；不會把部署轉送到正式雲端。
+
+## 安裝
+
+需要 Python 3.10 以上。Python 套件預設包含 YAML 相依套件：
+
+```bash
+pip install fufu-cloud-cli
+fufu --version
+```
+
+npm 版本需要 Node.js 18 以上，以及已安裝的 Python 3.10 以上；四個入口
+呼叫相同的 Python CLI。npm 包內附純 Python YAML parser，沒有安裝腳本，
+不會自行下載 Python 或執行 pip。
+
+```bash
+npm install fufu-cloud-cli
+npx --no-install fufu --version
+npx --no-install aws-fufu --help
+```
+
+全域安裝可使用 `npm install -g fufu-cloud-cli`。預設 Python 指令為 `python3`；
+若名稱不同，將 `FUFU_PYTHON` 設成可信 Python 執行檔的路徑。
+本機 Docker backend 只支援 Linux 與本機 Unix socket。API backend
+不需要安裝 Docker；其他作業系統仍須另外驗證其 Python 與網路環境。
+
+## 憑證與 CI
+
+向 FUFU Cloud 管理者取得該租戶、該 provider 的專用 credential JSON。
+CLI 不附預設帳號、共用金鑰或可用的租戶憑證，也不讀取 `.env`、瀏覽器
+Cookie 或正式雲端登入工作階段。
+
+在 CI 的秘密管理功能中注入 credential 檔案，並設定：
+
+```bash
+export FUFU_BACKEND=api
+export FUFU_AWS_CREDENTIAL_FILE=/run/secrets/fufu-aws.json
+export FUFU_GCP_CREDENTIAL_FILE=/run/secrets/fufu-gcp.json
+export FUFU_AZURE_CREDENTIAL_FILE=/run/secrets/fufu-azure.json
+
+fufu auth whoami --provider aws
+aws-fufu sts get-caller-identity
+gcloud-fufu auth list
+az-fufu account show
+```
+
+credential 內含 FUFU endpoint。`FUFU_ENDPOINT` 可明確覆寫目的地：僅限
+你信任且獲授權接收 credential 的 FUFU 服務。正式網路需使用 HTTPS；
+只有 loopback 允許 HTTP。TLS 憑證驗證保持開啟，不跟隨重新導向，
+不繼承系統 HTTP proxy。
+
+一般命令交換短期權杖並在結束時嘗試撤銷。`fufu auth assume-role`
+可建立受限 session 檔，檔案以排他方式建立且權限為 `0600`；請勿提交。
+FUFU credential 與 session 檔仍屬秘密，必須由作業系統和 CI 控制存取。
+原生雲端的 GitHub auth actions、OIDC、SigV4 和 OAuth 不直接相容。
+
+## 部署與支援範圍
+
+```bash
+fufu capabilities
+fufu capabilities --remote --provider gcp --require cloud-run-http
+gcloud-fufu run deploy example --image approved-image:tag
+gcloud-fufu functions deploy example-function --gen2 \
+  --runtime python312 --source ./function --entry-point handler --trigger-http
+aws-fufu lambda list-functions
+```
+
+映像需先由 FUFU 管理者準備及核准。Function 來源會上傳指定目錄中的
+Python 與 requirements 檔；Lambda 會上傳指定的 ZIP。請使用只含必要程式碼的
+目錄或 ZIP，先移除硬編碼秘密、個人資料與不需要的檔案。
+CLI 無法判斷任意原始碼或 ZIP 內的資料是否可以分享。
+
+| 服務 | 可用範圍與主要限制 |
+| --- | --- |
+| Cloud Run | 單一已核准 HTTP 容器；無 autoscaling、traffic splitting、Jobs 或公開 ingress |
+| Cloud Run functions / Functions Gen 1 | Python 3.12 HTTP 函式；Gen 1 為相同 HTTP runtime 的模擬子集，無背景事件 |
+| AWS Lambda | Python 3.10 / 3.12 ZIP、同步 invoke、程式碼更新；遠端 ZIP 上限 6 MiB |
+| GCS / S3 | bucket 與 object 操作子集；單一 object 上限 6 MiB，無 versioning / signed URL |
+| DynamoDB / SQS / SSM | 明列資料操作；無完整交易、Streams、FIFO 或 KMS / SecureString |
+| AWS IAM / GCP IAM | 租戶內 role / service account / policy 子集；default deny、限定 session；無原生雲端全量 IAM 語義 |
+| API Gateway / Serverless profile | 簡化 HTTP Lambda proxy 和明確來源清單；不執行 plugins / CloudFormation |
+| Azure | account 與資源群組目錄；尚無 Azure Functions 或其他 Azure runtime |
+| EC2 / ECS / App Engine 等 | 部分只有 mock 目錄；不能視為執行中的 VM、Task 或應用 |
+
+`fufu capabilities` 是隨版支援清單；`--remote` 另外查詢服務端能力。
+`implemented` 代表明列子集已接入，`partial`、`mock-only`、`unsupported`
+均不代表完整服務可用。未支援命令、旗標、YAML 欄位會拒絕，CI 應檢查退出碼。
+
+## YAML / JSON
+
+Cloud Run manifest 支援 `serving.knative.dev/v1`、`kind: Service`、
+`metadata.name`、單一 container 的 image / port / env，以及明列的 service account。
+`fufu plan --file service.yaml` 可在不部署的情況下檢查設定；plan 僅列出環境變數名稱。
+相同設定可用 JSON。其他正式雲端欄位需要顯式調整，不能宣稱所有設定無痛相容。
+
+## 隱私與執行邊界
+
+- 套件沒有遙測、廣告、背景更新或安裝時網路腳本。
+- API 請求只使用明確提供的 FUFU endpoint 和 credential；不掃描使用者家目錄。
+- `whoami` 會輸出目前租戶、provider 與 scope；查詢／invoke 會輸出所要求的資料。
+  請將 CI 日誌視為可能包含應用資料，不把敏感查詢結果公開。
+- 本機部署會操作 Docker。明確執行 runtime prepare 或 function build 時，
+  可能下載固定映像或安裝應用 requirements；不可信 requirements 仍可執行建置程式。
+- FUFU 服務端的租戶隔離、IAM、日誌保存與資料保護由服務端負責。
+  CLI 的本機檢查不等於對任何遠端部署作永久安全保證。
+
+本套件目前保留著作權，未授予開源授權。套件公開可下載與原始碼採用開源授權
+是不同事項；第三方 YAML parser 依其 MIT 授權散布。

fufu_cloud_cli-0.5.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=77,<81"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fufu-cloud-cli"
+version = "0.5.0"
+description = "FUFU Cloud CLI for tenant-scoped mock cloud development and deployment"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["PyYAML==6.0.3"]
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+
+[project.optional-dependencies]
+yaml = ["PyYAML==6.0.3"]
+
+[project.scripts]
+fufu = "fufu_cloud_cli.cli:main"
+aws-fufu = "fufu_cloud_cli.cli:aws_main"
+gcloud-fufu = "fufu_cloud_cli.cli:gcloud_main"
+az-fufu = "fufu_cloud_cli.cli:az_main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+fufu_cloud_cli = ["capabilities.json", "runtime/*/Dockerfile", "runtime/ingress/proxy.py"]

fufu_cloud_cli-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fufu_cloud_cli-0.5.0/src/fufu_cloud_cli/__init__.py

@@ -0,0 +1,3 @@
+"""FUFU CLI 與本機部署工具；相容範圍見 capabilities.json。"""
+
+__version__ = "0.5.0"

fufu_cloud_cli-0.5.0/src/fufu_cloud_cli/__main__.py

@@ -0,0 +1,9 @@
+import sys
+
+from .cli import entry
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1 and sys.argv[1] in {"fufu", "aws-fufu", "gcloud-fufu", "az-fufu"}:
+        entry(sys.argv[1], sys.argv[2:])
+    else:
+        entry("fufu", sys.argv[1:])

fufu_cloud_cli-0.5.0/src/fufu_cloud_cli/api_backend.py

@@ -0,0 +1,302 @@
+"""FUFU credential exchange and tenant-bound API transport (standard library only)."""
+import ipaddress
+import json
+import os
+import re
+import ssl
+import signal
+import threading
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlsplit, urlencode
+from urllib.request import HTTPRedirectHandler, HTTPSHandler, ProxyHandler, Request, build_opener
+
+from .errors import FufuError, require
+
+PROVIDERS = {"aws", "gcp", "azure"}
+MAX_RESPONSE = 2 * 1024 * 1024
+
+
+@contextmanager
+def request_deadline(seconds=20):
+    # Linux CLI 的總期限包含 DNS、連線及持續傳送的小分段回應。
+    enabled = hasattr(signal, 'setitimer') and threading.current_thread() is threading.main_thread()
+    if not enabled:
+        yield
+        return
+    started = time.monotonic()
+    previous_handler = signal.getsignal(signal.SIGALRM)
+    previous_timer = signal.getitimer(signal.ITIMER_REAL)
+    def expired(*args):
+        raise FufuError("API_TIMEOUT", "FUFU API 請求超過總執行期限。")
+    signal.signal(signal.SIGALRM, expired)
+    signal.setitimer(signal.ITIMER_REAL, min(seconds, previous_timer[0]) if previous_timer[0] else seconds)
+    try:
+        yield
+    finally:
+        signal.setitimer(signal.ITIMER_REAL, 0)
+        signal.signal(signal.SIGALRM, previous_handler)
+        if previous_timer[0]:
+            signal.setitimer(signal.ITIMER_REAL, max(0.001, previous_timer[0] - (time.monotonic() - started)), previous_timer[1])
+
+
+class NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def endpoint_url(value):
+    require(isinstance(value, str) and value == value.strip(), "INVALID_ENDPOINT", "請提供有效的 FUFU API endpoint。")
+    parsed = urlsplit(value)
+    loopback = parsed.hostname == "localhost"
+    try:
+        loopback = loopback or ipaddress.ip_address(parsed.hostname).is_loopback
+    except ValueError:
+        pass
+    require(parsed.hostname and not parsed.username and not parsed.password
+            and not parsed.query and not parsed.fragment and parsed.path in {"", "/"}
+            and not any(c.isspace() for c in value) and "\\" not in value
+            and (parsed.scheme == "https" or (parsed.scheme == "http" and loopback)),
+            "INVALID_ENDPOINT", "FUFU endpoint 必須使用 HTTPS；本機 loopback 可使用 HTTP。")
+    _ = parsed.port
+    return value.rstrip("/")
+
+
+def api_selected():
+    mode = os.environ.get("FUFU_BACKEND")
+    require(mode in {None, "api", "local-docker", "docker"}, "INVALID_BACKEND", "FUFU_BACKEND 必須是 api 或 local-docker。")
+    if mode in {"local-docker", "docker"}:
+        return False
+    return mode == "api" or any(os.environ.get(k) for k in (
+        "FUFU_ENDPOINT", "FUFU_CREDENTIAL_FILE", "FUFU_AWS_CREDENTIAL_FILE",
+        "FUFU_GCP_CREDENTIAL_FILE", "FUFU_AZURE_CREDENTIAL_FILE", 'FUFU_SESSION_FILE')) or os.environ.get("AWS_ACCESS_KEY_ID", "").startswith("FUFU")
+
+
+def load_credential(provider=None, filename=None):
+    require(provider is None or provider in PROVIDERS, "INVALID_PROVIDER", "未知的 provider。")
+    filename = filename or (os.environ.get(f"FUFU_{provider.upper()}_CREDENTIAL_FILE") if provider else None) or os.environ.get("FUFU_CREDENTIAL_FILE")
+    if not filename and provider == "gcp":
+        filename = os.environ.get("GOOGLE_APPLICATION_CREDENTIALS")
+    if filename:
+        p = Path(filename).expanduser()
+        require(p.is_file() and p.stat().st_size <= 16384, "INVALID_CREDENTIAL", "憑證檔案不存在或格式無效。")
+        data = json.loads(p.read_text(encoding="utf-8"))
+    elif provider == "aws" and os.environ.get("AWS_ACCESS_KEY_ID", "").startswith("FUFUAWS"):
+        data = {"fufu_version": 1, "fufu_provider": "aws", "fufu_endpoint": os.environ.get("FUFU_ENDPOINT"),
+                "fufu_tenant_id": os.environ.get("FUFU_TENANT_ID"), "aws_access_key_id": os.environ["AWS_ACCESS_KEY_ID"],
+                "aws_secret_access_key": os.environ.get("AWS_SECRET_ACCESS_KEY")}
+    else:
+        raise FufuError("CREDENTIAL_REQUIRED", "請透過 FUFU_CREDENTIAL_FILE 或各 provider 的 FUFU_*_CREDENTIAL_FILE 注入憑證檔案。")
+    require(isinstance(data, dict) and data.get("fufu_version") == 1
+            and data.get("fufu_provider") in PROVIDERS, "INVALID_CREDENTIAL", "需要 FUFU 專用憑證；不接受正式雲端金鑰。")
+    actual = data["fufu_provider"]
+    require(provider is None or actual == provider, "PROVIDER_MISMATCH", "憑證所屬 provider 不符。")
+    fields = {"aws": ("aws_access_key_id", "aws_secret_access_key"), "gcp": ("client_id", "client_secret"), "azure": ("clientId", "clientSecret")}
+    key, secret = (data.get(k) for k in fields[actual])
+    require(isinstance(key, str) and re.fullmatch(r"FUFU" + actual.upper() + r"[A-Za-z0-9_-]{12,100}", key)
+            and isinstance(secret, str) and 24 <= len(secret) <= 1024,
+            "INVALID_CREDENTIAL", "FUFU 憑證欄位無效。")
+    if actual == "gcp":
+        require(data.get("type") == "fufu_service_account", "INVALID_CREDENTIAL", "需要 FUFU service account JSON。")
+    tenant = data.get("fufu_tenant_id")
+    require(isinstance(tenant, str) and re.fullmatch(r"tenant-[a-z0-9]{8,32}", tenant), "INVALID_CREDENTIAL", "憑證缺少有效的 tenant。")
+    require(not os.environ.get("FUFU_TENANT_ID") or os.environ["FUFU_TENANT_ID"] == tenant,
+            "TENANT_MISMATCH", "環境指定的 tenant 與憑證不符。")
+    endpoint = endpoint_url(os.environ.get("FUFU_ENDPOINT") or data.get("fufu_endpoint"))
+    return {"provider": actual, "credential_id": key, "credential_secret": secret, "tenant_id": tenant}, endpoint
+
+
+class ApiClient:
+    def __init__(self, provider=None, filename=None, read_only=False):
+        self.owns_token = True
+        self.opener = build_opener(ProxyHandler({}), NoRedirect(), HTTPSHandler(context=ssl.create_default_context()))
+        if os.environ.get('FUFU_SESSION_FILE') and not filename:
+            p = Path(os.environ['FUFU_SESSION_FILE'])
+            require(p.is_file() and p.stat().st_size <= 16384, 'INVALID_SESSION', 'Session 檔案無效。')
+            session = json.loads(p.read_text())
+            self.endpoint = endpoint_url(session.get('endpoint'))
+            self.provider, self.token = session.get('provider'), session.get('access_token')
+            require(self.provider in PROVIDERS and (provider is None or provider == self.provider)
+                    and isinstance(self.token, str) and re.fullmatch(r'fufu_at_[A-Za-z0-9_-]{43}', self.token)
+                    and session.get('expires_at', 0) > time.time(), 'INVALID_SESSION', 'Session 已過期或 provider 不符。')
+            self.owns_token = False
+            who = self.whoami()
+            require((who.get('role') or (session.get('session_kind') == 'terminal' and who.get('sessionKind') == 'terminal'))
+                    and who.get('kind') == 'cli' and who.get('tenantId') == session.get('tenant_id') and who.get('provider') == self.provider,
+                    'INVALID_SESSION', 'Session 的租戶與 role 無效。')
+            self.check_selectors(who)
+            return
+        credential, self.endpoint = load_credential(provider, filename)
+        self.provider = credential["provider"]
+        self.token = None
+        self.opener = build_opener(ProxyHandler({}), NoRedirect(), HTTPSHandler(context=ssl.create_default_context()))
+        scopes = [f"{self.provider}:read"] + ([] if read_only else [f"{self.provider}:write"])
+        issued = self._request("POST", "/api/auth/token", {**credential, "scopes": scopes,
+            **({'assume_role': os.environ['FUFU_ASSUME_ROLE']} if os.environ.get('FUFU_ASSUME_ROLE') else {})})
+        token = issued.get("access_token")
+        require(isinstance(token, str) and re.fullmatch(r"fufu_at_[A-Za-z0-9_-]{43}", token),
+                "INVALID_RESPONSE", "API 回傳的權杖格式無效。")
+        self.token = token
+        p = issued.get("principal", {})
+        if p.get("provider") != self.provider or p.get("tenantId") != credential["tenant_id"] or p.get("kind") != "cli":
+            self.close()
+            raise FufuError("TENANT_MISMATCH", "API 回覆的身分與憑證不符。")
+        if os.environ.get('FUFU_SELECTED_REGION') or os.environ.get('FUFU_SELECTED_PROJECT'):
+            try: self.check_selectors(self.whoami())
+            except Exception:
+                self.close(); raise
+
+    def check_selectors(self, who):
+        for env, field in [('FUFU_SELECTED_REGION', 'region'), ('FUFU_SELECTED_PROJECT', 'projectId')]:
+            require(not os.environ.get(env) or os.environ[env] == who.get(field), 'RESOURCE_SCOPE_MISMATCH', 'region／project 必須符合目前憑證的 FUFU scope。')
+
+    def _request(self, method, path, body=None, *, large=False):
+        require(path.startswith("/api/") and "\r" not in path and "\n" not in path,
+                "INVALID_REQUEST", "API 路徑無效。")
+        headers = {"Accept": "application/json", "User-Agent": "fufu-cloud-cli"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        data = None if body is None else json.dumps(body).encode("utf-8")
+        if data is not None:
+            require(len(data) <= (12 * 1024**2 if large else 65536), "PAYLOAD_LIMIT", "API JSON payload 超過上限。")
+            headers["Content-Type"] = "application/json"
+        req = Request(self.endpoint + path, data=data, headers=headers, method=method)
+        try:
+            with request_deadline(), self.opener.open(req, timeout=15) as response:
+                limit = 9 * 1024**2 if large else MAX_RESPONSE
+                raw = response.read(limit + 1)
+                require(len(raw) <= limit, "RESPONSE_LIMIT", "API 回覆超過大小限制。")
+                return json.loads(raw)
+        except HTTPError as exc:
+            status = exc.code
+            exc.close()
+            codes = {401: "AUTHENTICATION_FAILED", 403: "ACCESS_DENIED", 404: "RESOURCE_NOT_FOUND", 409: "RESOURCE_CONFLICT", 429: "RATE_LIMITED"}
+            raise FufuError(codes.get(status, "API_REQUEST_FAILED"), f"FUFU API 拒絕請求（HTTP {status}）；未輸出憑證或原始回應。") from None
+        except (URLError, TimeoutError, ConnectionError) as exc:
+            raise FufuError("API_UNREACHABLE", "無法在時限內安全連線至 FUFU API。") from None
+
+    def request(self, method, path, body=None):
+        return self._request(method, f"/api/cloud/{self.provider}" + path, body, large=path.startswith(('/compute/', '/s3/', '/storage/', '/control/native')))
+
+    def whoami(self):
+        data = self._request("GET", "/api/auth/whoami")
+        return {k: v for k, v in data.items() if k != "credentialId"}
+
+    def close(self):
+        if self.token and self.owns_token:
+            try:
+                self._request("POST", "/api/auth/revoke", {})
+            except (FufuError, ValueError, OSError):
+                pass
+            finally:
+                self.token = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+def segment(value):
+    require(isinstance(value, str) and value not in {"", ".", ".."} and "/" not in value,
+            "INVALID_RESOURCE", "資源名稱無效。")
+    return quote(value, safe="")
+
+
+def storage_path(value):
+    parsed = urlsplit(value)
+    require(parsed.scheme == "gs" and parsed.netloc and not parsed.query and not parsed.fragment
+            and not parsed.username and not parsed.password, "INVALID_RESOURCE", "請使用 gs://bucket 或 gs://bucket/object。")
+    return segment(parsed.netloc), parsed.path.lstrip("/")
+
+
+def remote_command(provider, argv, Parser):
+    p = Parser(prog={"aws": "aws-fufu", "gcp": "gcloud-fufu", "azure": "az-fufu"}[provider],
+               description="FUFU API 憑證與租戶資源操作子集；無原生雲端 IAM／部署相容承諾。")
+    roots = p.add_subparsers(dest="service", required=True)
+    if provider == "aws":
+        roots.add_parser("sts").add_subparsers(dest="action", required=True).add_parser("get-caller-identity")
+        sub = roots.add_parser("dynamodb").add_subparsers(dest="action", required=True)
+        sub.add_parser("list-tables")
+        for action in ("create-table", "delete-table", "put-item", "scan"):
+            q = sub.add_parser(action)
+            q.add_argument("--table-name", required=True)
+            if action == "create-table":
+                q.add_argument("--partition-key", default="id", help="FUFU 字串 HASH key；預設 id")
+            if action == "put-item":
+                q.add_argument("--item", required=True, help="DynamoDB AttributeValue JSON，建議 file:// 路徑")
+    elif provider == "gcp":
+        roots.add_parser("auth").add_subparsers(dest="action", required=True).add_parser("list")
+        sub = roots.add_parser("storage").add_subparsers(dest="action", required=True)
+        buckets = sub.add_parser("buckets").add_subparsers(dest="bucket_action", required=True)
+        buckets.add_parser("list")
+        for action in ("create", "delete"):
+            buckets.add_parser(action).add_argument("url")
+        sub.add_parser("ls").add_argument("url")
+        sub.add_parser("cat").add_argument("url")
+        cp = sub.add_parser("cp")
+        cp.add_argument("source")
+        cp.add_argument("destination")
+        sub.add_parser("rm").add_argument("url")
+    else:
+        roots.add_parser("account").add_subparsers(dest="action", required=True).add_parser("show")
+        for group in ("group", "resource"):
+            sub = roots.add_parser(group).add_subparsers(dest="action", required=True)
+            sub.add_parser("list")
+            for action in ("show", "delete"):
+                sub.add_parser(action).add_argument("--name", required=True)
+            if group == "group":
+                q = sub.add_parser("create")
+                q.add_argument("--name", required=True)
+                q.add_argument("--location", default="eastasia")
+    a = p.parse_args(argv)
+    read_only = a.service in {"sts", "auth", "account"} or a.action in {"list", "list-tables", "scan", "show", "ls", "cat"} or getattr(a, "bucket_action", None) == "list" or (a.action == 'cp' and a.source.startswith('gs://'))
+    with ApiClient(provider, read_only=read_only) as api:
+        if a.service in {"sts", "auth", "account"}:
+            return api.whoami()
+        if provider == "aws":
+            if a.action == "list-tables":
+                return api.request("GET", "/dynamodb/tables")
+            path = "/dynamodb/tables/" + segment(a.table_name)
+            if a.action == "create-table":
+                return api.request("POST", "/dynamodb/tables", {"TableName": a.table_name, "PartitionKey": a.partition_key})
+            if a.action == "delete-table":
+                return api.request("DELETE", path)
+            if a.action == "scan":
+                return api.request("GET", path + "/items")
+            from .cli import payload
+            return api.request("POST", path + "/items", {"Item": json.loads(payload(a.item))})
+        if provider == "azure":
+            if a.action == "list":
+                result = api.request("GET", "/resources")
+                return {"value": [r for r in result["value"] if r.get("kind") == "resource-groups"]} if a.service == "group" else result
+            if a.action == "create":
+                return api.request("POST", "/resources", {"name": a.name, "location": a.location})
+            return api.request("GET" if a.action == "show" else "DELETE", "/resources/" + segment(a.name))
+        if a.action == "buckets" and a.bucket_action == "list":
+            return api.request("GET", "/storage/buckets")
+        if a.action == 'cp' and a.source.startswith('gs://'):
+            from .cloud_data import download_bytes
+            require(not a.destination.startswith('gs://'), 'UNSUPPORTED_ARGUMENT', 'cp 目前只支援本機與 Storage 之間傳輸。')
+            bucket, key = storage_path(a.source)
+            require(bool(key), 'INVALID_RESOURCE', '請指定 object 名稱。')
+            result = api.request('GET', '/storage/buckets/' + bucket + '/object?' + urlencode({'name': key, 'encoding': 'base64'}))
+            return download_bytes(a.destination, result['contentBase64'])
+        bucket, key = storage_path(a.destination if a.action == "cp" else a.url)
+        path = "/storage/buckets/" + bucket
+        if a.action == "buckets":
+            require(not key, "INVALID_RESOURCE", "Bucket 操作不接受 object 路徑。")
+            return api.request("POST", "/storage/buckets", {"name": bucket}) if a.bucket_action == "create" else api.request("DELETE", path)
+        if a.action == "ls":
+            require(not key, "UNSUPPORTED_ARGUMENT", "ls 目前只支援 bucket 根目錄。")
+            return api.request("GET", path + "/objects")
+        require(bool(key), "INVALID_RESOURCE", "請指定 object 名稱。")
+        if a.action == "cat":
+            return api.request("GET", path + "/object?" + urlencode({"name": key}))
+        if a.action == "rm":
+            return api.request("DELETE", path + "/object?" + urlencode({"name": key}))
+        from .cloud_data import upload_bytes
+        return api.request("POST", path + "/objects", {"name": key, "contentBase64": upload_bytes(a.source)})