wimotek-edge-agent 1.0.5 → 1.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wimotek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include pyproject.toml
+include setup.py
+recursive-include wimotek_edge_agent *.py py.typed

package/README.md

@@ -1,14 +1,14 @@
-# edge_agent commercial module
+# Wimotek Edge Agent
 
-Commercial-grade edge agent with explicit access policy, TOFU quarantine,
-Edge Agent token verification, session fast re-auth, and NAT4 reverse tunnel.
+Commercial-grade edge access control, service bridge, and tunnel agent featuring a 3-layer decision policy engine, TOFU quarantine, single-use HMAC token verification, session fast re-auth, and NAT4 reverse tunneling.
 
 ## Table of contents
 
 - [Design goals](#design-goals)
 - [Architecture](#architecture)
 - [Decision matrix](#decision-matrix)
-- [Install](#install)
+- [Installation & Quickstart](#installation--quickstart)
+  - [PyPI 安装与 ModuleNotFoundError 深度排查](#pypi-安装与-modulenotfounderror-深度排查)
 - [Environment variables](#environment-variables)
 - [CLI usage](#cli-usage)
 - [Programmatic usage](#programmatic-usage)
@@ -16,52 +16,44 @@ Edge Agent token verification, session fast re-auth, and NAT4 reverse tunnel.
 - [Audit log](#audit-log)
 - [Security model](#security-model)
 - [Commercial deployment checklist](#commercial-deployment-checklist)
-- [Publishing](#publishing)
 - [License](#license)
 
 ## Design goals
 
-1. **Local connections default allow**, gated by a `local_bypass_token`
-   written with mode `0600`, so other processes on the same host cannot
-   trivially reuse `127.0.0.1`.
-2. **External connections default TOFU**. A node without a token is
-   placed in a quarantine that only exchanges heartbeats. No business
-   data is relayed until an administrator approves the node.
-3. **External connections with token use Edge Agent mode**. The token is
-   verified for signature, TTL, audience, issuer, `node_uuid` binding,
-   optional source IP CIDR binding, and single-use replay protection.
-4. **NAT4 / no public IP uses reverse tunnel**. Authentication strength
-   does not downgrade when the network profile is `nat4_reverse`.
-5. **Trusted nodes re-auth with short-lived session tickets**. A trusted
-   node without token or session is denied, preventing downgrade to TOFU.
+1. **Local connections default allow**, gated by `local_bypass_token` (mode `0600`), preventing unauthorized local processes from abusing `127.0.0.1`.
+2. **External connections default TOFU**. Unauthenticated nodes are quarantined to heartbeats only. No business data is relayed until approved by an administrator.
+3. **External connections with token use Edge Agent mode**. Single-use HMAC-SHA256 tokens verify signature, TTL, audience, issuer, optional node UUID, IP CIDR binding, and replay prevention.
+4. **NAT4 / no public IP uses reverse tunnel**. Authentication strength remains identical under `nat4_reverse` network profiles.
+5. **Trusted nodes re-auth with short-lived session tickets**. Trusted nodes without token or session are denied, strictly preventing downgrade attacks to TOFU.
 
 ## Architecture
 
 ```text
                  +---------------------------+
    loopback ---> |  AccessPolicyEngine       | ---> ALLOW_LOCAL
-                 |  (single decision point)  |
+                 |  (Single Decision Point)  |
    external ---> |                           | ---> ALLOW_TOKEN
-   + token       |  1. local bypass token    |
-                 |  2. join token verify     | ---> ALLOW_SESSION
-   external ---> |  3. session ticket        |
-   no token      |  4. TOFU pending          | ---> PENDING_TOFU
-                 |  5. revoked / mismatch    |
+   + token       |  1. Local bypass token    |
+                 |  2. Join token verify     | ---> ALLOW_SESSION
+   external ---> |  3. Session ticket        |
+   no token      |  4. TOFU quarantine       | ---> PENDING_TOFU
+                 |  5. Revoked / mismatch    |
    nat4_rev ---> |                           | ---> DENY
                  +---------------------------+
-                              |
-                              v
-                    +-------------------+
-                    | TrustStore        |
-                    | pending/trusted/  |
-                    | revoked + jti     |
-                    +-------------------+
-                              |
-                              v
-                    +-------------------+
-                    | AuditLogger       |
-                    | JSON Lines        |
-                    +-------------------+
+                               |
+                               v
+                     +-------------------+
+                     | TrustStore        |
+                     | SQLite WAL        |
+                     | pending/trusted/  |
+                     | revoked + jti     |
+                     +-------------------+
+                               |
+                               v
+                     +-------------------+
+                     | AuditLogger       |
+                     | JSON Lines        |
+                     +-------------------+
 ```
 
 ## Decision matrix
@@ -70,98 +62,260 @@ Edge Agent token verification, session fast re-auth, and NAT4 reverse tunnel.
 |--------|----------|------------|----------------|----------------|----------|
 | direct | yes | - | - | any | `ALLOW_LOCAL` if bypass token ok, else `DENY` |
 | direct | no | valid | - | any | `ALLOW_TOKEN`, bind trust |
-| direct | no | invalid | - | any | `DENY` |
+| direct | no | invalid/replay | - | any | `DENY` |
 | direct | no | - | valid | trusted | `ALLOW_SESSION` |
-| direct | no | - | - | trusted | `DENY` (no downgrade) |
-| direct | no | - | - | pending, same fp | `PENDING_TOFU` |
-| direct | no | - | - | pending, diff fp | `DENY` |
-| direct | no | - | - | none | `PENDING_TOFU` |
+| direct | no | - | - | trusted | `DENY` (no downgrade to TOFU) |
+| direct | no | - | - | pending, same fp | `PENDING_TOFU` (heartbeat only) |
+| direct | no | - | - | pending, diff fp | `DENY` (fingerprint tamper prevention) |
+| direct | no | - | - | none | `PENDING_TOFU` (quarantine) |
 | direct | no | - | - | revoked | `DENY` |
 | nat4_reverse | no | valid | - | any | `ALLOW_TOKEN` |
 | nat4_reverse | no | - | - | none | `PENDING_TOFU` |
 
-## Install
+## Installation & Quickstart
+
+### 1. PyPI 安装与导入规则
+
+> 📌 **关键名称区别**：
+> - **PyPI 仓库包名（用于 pip 安装）**：`wimotek-edge-agent`（中划线 `-`）
+> - **Python 导入包名（用于代码 import）**：`wimotek_edge_agent`（下划线 `_`）
+
+在终端中使用当前 Python 运行环境安装：
+
+```bash
+# 推荐做法：使用当前 Python 解释器执行，避免装错环境
+python -m pip install --upgrade wimotek-edge-agent
+```
+
+在 Python 代码中使用标准导入：
+
+```python
+from wimotek_edge_agent import EdgeAgent, Config, AccessPolicyEngine
+```
+
+---
+
+### PyPI 安装与 ModuleNotFoundError 深度排查
+
+如果在上传 PyPI 后本地执行 `from wimotek_edge_agent ...` 报 `ModuleNotFoundError: No module named 'wimotek_edge_agent'`，请按以下 4 种最常见情况逐一排查：
+
+#### 🔴 原因 1：Python 运行环境不一致（最常见，占 80%）
+- **根因分析**：
+  在终端中执行的 `pip install` 将包安装到了全局 Python、系统 Python 或 Conda 的 base 环境；而你在 IDE（VS Code、PyCharm、Cursor）或者运行代码时，使用的是项目独立的虚拟环境（例如 `.venv`）。
+- **一键自查命令**：
+  在运行报错的代码同级终端中执行：
+  ```bash
+  python -c "import sys; print('当前 Python 解释器路径:', sys.executable); print('模块搜索路径:', sys.path)"
+  ```
+- **解决方法**：
+  确保使用**执行代码的同一个 Python 解释器**进行安装：
+  ```bash
+  python -m pip install --upgrade wimotek-edge-agent
+  ```
+  如果使用了虚拟环境，先激活虚拟环境再安装：
+  ```bash
+  # Linux / macOS:
+  source .venv/bin/activate
+  python -m pip install --upgrade wimotek-edge-agent
+
+  # Windows (PowerShell / CMD):
+  .venv\Scripts\activate
+  python -m pip install --upgrade wimotek-edge-agent
+  ```
+
+---
+
+#### 🔴 原因 2：PyPI 全球 CDN 刷新延迟 或 国内镜像源未同步
+- **根因分析**：
+  1. 上传到 PyPI（通过 `twine upload dist/*`）后，PyPI 主站的全球 Fastly CDN 边缘节点通常需要 1~5 分钟同步刷新。
+  2. 如果你的本地 pip 配置了国内镜像源（如清华源、阿里源、腾讯源），镜像源通常会有几十分钟到数小时的同步周期。如果刚上传就立刻通过镜像源安装，镜像源尚未同步，会提示找不到包或匹配不到版本。
+  3. `pip` 本地存在 HTTP 缓存，可能命中了上传前的 404 记录。
+- **解决方法**：
+  直连 PyPI 官方源，并跳过本地缓存强制安装：
+  ```bash
+  python -m pip install -i https://pypi.org/simple/ --no-cache-dir --upgrade wimotek-edge-agent
+  ```
+
+---
+
+#### 🔴 原因 3：打包时生成了“空包”（Empty Wheel 陷阱）
+- **根因分析**：
+  打包工具在执行 `python -m build` 或 `python setup.py bdist_wheel` 时，如果打包配置中未显式声明包路径，生成的 `.whl` 文件可能**只包含元数据 `wimotek_edge_agent-1.0.0.dist-info/`，而漏掉了 `wimotek_edge_agent/` 源码目录**。
+  安装时 pip 会显示安装成功，但 `site-packages` 里其实没有代码目录，因此运行时必然报错 `ModuleNotFoundError`。
+- **一键自查本地构建产物**：
+  在执行打包的机器上检查生成的 `.whl` 和 `.tar.gz` 内容：
+  ```bash
+  # 检查 wheel 文件内容列表
+  unzip -l dist/wimotek_edge_agent-*.whl
+
+  # 或检查源码 tar 包
+  tar -ztvf dist/wimotek_edge_agent-*.tar.gz
+  ```
+  **正常的文件列表**必须包含以下源码文件：
+  ```text
+  wimotek_edge_agent/__init__.py
+  wimotek_edge_agent/agent.py
+  wimotek_edge_agent/config.py
+  wimotek_edge_agent/policy.py
+  wimotek_edge_agent/trust_store.py
+  ...
+  wimotek_edge_agent/py.typed
+  ```
+  如果列表里全都是 `dist-info/` 开头的文件，而**没有** `wimotek_edge_agent/`，则说明上传的是空包！
+- **彻底根治与重新发布**：
+  本项目已在 `pyproject.toml` 中配置了明确的 setuptools 规则：
+  ```toml
+  [tool.setuptools]
+  packages = ["wimotek_edge_agent"]
+
+  [tool.setuptools.package-data]
+  wimotek_edge_agent = ["py.typed"]
+  ```
+  并配备了 `MANIFEST.in` 与 `setup.py` 双重保障。重新打包与发布：
+  ```bash
+  # 1. 清理所有历史缓存构建目录
+  rm -rf dist build *.egg-info
+
+  # 2. 安装/升级标准构建工具
+  python -m pip install --upgrade build twine
+
+  # 3. 规范打包
+  python -m build
+
+  # 4. 验证 wheel 是否包含代码
+  unzip -l dist/*.whl | grep "wimotek_edge_agent/__init__.py"
+
+  # 5. 上传到 PyPI（注意修改 pyproject.toml 递增版本号，如 1.0.1）
+  twine upload dist/*
+  ```
+
+---
+
+#### 🔴 原因 4：当前工作目录文件遮蔽（Shadowing）
+- **根因分析**：
+  Python 会把执行命令的当前目录（`sys.path[0]`）作为最高优先级的模块搜索路径。如果当前目录下碰巧有一个名为 `wimotek_edge_agent.py` 的测试脚本，或者一个空的同名文件夹，Python 会直接加载该文件，导致无法找到内部类和函数。
+- **排查验证**：
+  ```bash
+  python -c "import wimotek_edge_agent; print('实际加载的文件路径:', wimotek_edge_agent.__file__)"
+  ```
+  如果路径指向了当前临时目录而非 `site-packages`，说明发生了路径遮蔽。
+
+---
+
+### 2. 本地源码免上传开发（推荐）
+
+在日常开发、测试或修改功能时，建议在本地项目根目录下使用可编辑模式（Editable Mode）直接安装，无需频繁上传 PyPI：
+
+```bash
+cd wimotek-edge-agent
+pip install -e .
+```
+
+安装后，本地对 `wimotek_edge_agent/` 目录中代码的任何改动会立即反映在 Python 环境中。验证：
 
 ```bash
-pip install edge-agent-commercial
+python -c "import wimotek_edge_agent; print('版本:', wimotek_edge_agent.__version__, '路径:', wimotek_edge_agent.__file__)"
 ```
 
-From source:
+---
+
+### 3. Node.js CLI Runner
+
+除了 Python CLI 外，还可通过 npm / npx 直接运行：
 
 ```bash
-git clone https://github.com/yourorg/edge-agent.git
-cd edge-agent
-pip install -e ".[dev]"
+npm install -g wimotek-edge-agent
+# 或者直接免安装执行：
+npx wimotek-edge-agent --help
 ```
 
 ## Environment variables
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `EDGE_AGENT_DATA_DIR` | no | `./edge_agent_data` | Data directory for trust DB, audit log, local bypass token |
+| `EDGE_AGENT_DATA_DIR` | no | `./edge_agent_data` | Persistent data directory for trust DB, audit log, local bypass token |
 | `EDGE_AGENT_TOKEN_SECRET` | yes | - | HMAC secret, >= 32 bytes |
-| `EDGE_AGENT_TOKEN_AUDIENCE` | no | `edge-agent` | Token audience |
-| `EDGE_AGENT_TOKEN_ISSUER` | no | `central` | Token issuer |
-| `EDGE_AGENT_TOKEN_MAX_TTL_SECONDS` | no | `600` | Max token TTL |
-| `EDGE_AGENT_SESSION_TICKET_TTL_SECONDS` | no | `300` | Session ticket TTL |
+| `EDGE_AGENT_TOKEN_AUDIENCE` | no | `edge-agent` | Token audience claim |
+| `EDGE_AGENT_TOKEN_ISSUER` | no | `central` | Token issuer claim |
+| `EDGE_AGENT_TOKEN_MAX_TTL_SECONDS` | no | `600` | Max token TTL (seconds) |
+| `EDGE_AGENT_SESSION_TICKET_TTL_SECONDS` | no | `300` | Session ticket TTL (seconds) |
 | `EDGE_AGENT_TOFU_HEARTBEAT_SECONDS` | no | `10` | TOFU quarantine heartbeat interval |
 | `EDGE_AGENT_REQUIRE_LOCAL_BYPASS_TOKEN` | no | `true` | Require local bypass token for loopback |
-| `EDGE_AGENT_REVERSE_TUNNEL` | no | auto | `true` / `false` / unset |
-| `EDGE_AGENT_NAT_TYPE` | no | `unknown` | `nat4`, `symmetric`, etc. |
+| `EDGE_AGENT_REVERSE_TUNNEL` | no | auto | Force reverse tunnel (`true`/`false`) |
+| `EDGE_AGENT_NAT_TYPE` | no | `unknown` | Network NAT type (`nat4`, `symmetric`, etc.) |
 | `EDGE_AGENT_NODE_UUID` | reverse only | - | Agent node UUID |
 | `EDGE_AGENT_PUBLIC_KEY_FINGERPRINT` | reverse only | - | Agent public key fingerprint |
-| `EDGE_AGENT_JOIN_TOKEN` | reverse only | - | Join token for Edge Agent mode |
-| `EDGE_AGENT_TLS_SERVER_NAME` | no | - | TLS SNI |
-| `EDGE_AGENT_CERTIFICATE_PIN_SHA256` | no | - | TLS certificate pin |
+| `EDGE_AGENT_JOIN_TOKEN` | reverse only | - | Join token for reverse tunnel connection |
+| `EDGE_AGENT_TLS_SERVER_NAME` | no | - | TLS SNI hostname |
+| `EDGE_AGENT_CERTIFICATE_PIN_SHA256` | no | - | TLS certificate SHA-256 pin |
 
-Generate a secret:
+Generate a high-entropy secret:
 
 ```bash
-python -c "import secrets; print(secrets.token_urlsafe(48))"
+wimotek-edge-agent generate-secret
 ```
 
 ## CLI usage
 
-Start a direct TLS JSON-line server:
+Start a direct TLS / TCP JSON-line server:
 
 ```bash
-edge-agent listen --host 0.0.0.0 --port 8443 \
+wimotek-edge-agent listen --host 0.0.0.0 --port 8443 \
   --cert /path/server.crt --key /path/server.key
 ```
 
-Approve a pending TOFU node (admin, out-of-band):
+Approve a pending TOFU node (admin out-of-band verification):
+
+```bash
+wimotek-edge-agent approve --node-uuid node-xxx --fingerprint sha256:...
+```
+
+Revoke a compromised or decommissioned node:
 
 ```bash
-edge-agent approve --node-uuid node-xxx --fingerprint sha256:...
+wimotek-edge-agent revoke --node-uuid node-xxx
 ```
 
-Revoke a trusted node:
+List all managed nodes in trust store:
 
 ```bash
-edge-agent revoke --node-uuid node-xxx
+wimotek-edge-agent list-nodes --status trusted
 ```
 
-Show a node record:
+Inspect a specific node record:
 
 ```bash
-edge-agent show-node --node-uuid node-xxx
+wimotek-edge-agent show-node --node-uuid node-xxx
 ```
 
 Issue a single-use Edge Agent join token:
 
 ```bash
-edge-agent issue-token \
-  --node-group group-a \
+wimotek-edge-agent issue-token \
+  --node-group fleet-a \
   --ttl 300 \
   --node-uuid node-xxx \
   --allowed-ip-cidr 203.0.113.0/24
 ```
 
+Verify a token directly:
+
+```bash
+wimotek-edge-agent verify-token --token <token_string> --source-ip 203.0.113.10
+```
+
+Read or generate the local bypass token:
+
+```bash
+wimotek-edge-agent bypass-token
+```
+
 ## Programmatic usage
 
 ```python
 import asyncio
-from edge_agent import Config, EdgeAgent
+from wimotek_edge_agent import Config, EdgeAgent
+from wimotek_edge_agent.transport import JsonLineTransport
 
 async def main() -> None:
     config = Config.from_env()
@@ -177,7 +331,7 @@ async def main() -> None:
 
     server = await asyncio.start_server(
         lambda r, w: agent.handle_connection(
-            __import__("edge_agent.transport", fromlist=["JsonLineTransport"]).JsonLineTransport(r, w),
+            JsonLineTransport(r, w),
             w.get_extra_info("peername")[0],
         ),
         host="0.0.0.0",
@@ -186,13 +340,13 @@ async def main() -> None:
     async with server:
         await server.serve_forever()
 
-asyncio.run(main())
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
 
 ## Reverse tunnel / NAT4
 
-`transport.TunnelDialer` is a protocol. Implement it with your existing
-WebSocket stack, then call:
+Implement `TunnelDialer` with your WebSocket stack, then launch:
 
 ```python
 await agent.run_reverse_tunnel(
@@ -203,19 +357,10 @@ await agent.run_reverse_tunnel(
 )
 ```
 
-The reverse tunnel:
-
-- uses TLS and supports certificate pinning via
-  `EDGE_AGENT_CERTIFICATE_PIN_SHA256`;
-- sends the same handshake fields as direct mode (`node_uuid`,
-  `public_key_fingerprint`, `join_token`, `nat_type`, `reverse_tunnel`);
-- keeps waiting on `pending_tofu` until the central side sends
-  `approved` or `denied`;
-- applies exponential backoff on reconnect.
-
-Authentication is performed by the central side using the same
-`AccessPolicyEngine`. The network profile is `nat4_reverse`; the auth
-strength is identical to direct mode.
+- Sends handshake fields (`node_uuid`, `public_key_fingerprint`, `join_token`, `nat_type`, `reverse_tunnel`);
+- Supports TLS pinning via `EDGE_AGENT_CERTIFICATE_PIN_SHA256`;
+- Quarantines in `pending_tofu` until approved by central administrator;
+- Exponential backoff on reconnection attempts.
 
 ## Audit log
 
@@ -225,60 +370,29 @@ Every `AccessDecision` is written to `EDGE_AGENT_DATA_DIR/audit.jsonl`:
 {"ts":"2026-11-06T12:00:00+00:00","event":"access_decision","node_uuid":"node-xxx","source_ip":"203.0.113.10","is_loopback":false,"decision":"allow_token","reason":"edge_agent_token_verified","network_profile":"direct","nat_type":"unknown","fingerprint":"sha256:...","node_status":"trusted"}
 ```
 
-Ship this file to your central log platform (Loki, ELK, CloudWatch, etc.).
-Do not store the raw join token in the audit log; only record the decision.
+Ship this structured log file to your central logging pipeline (Loki, ELK, CloudWatch, OpenTelemetry). Raw join tokens are never logged.
 
 ## Security model
 
-- **Token secret**: >= 32 bytes. Rotate by restarting with a new secret;
-  old tokens become invalid immediately.
-- **Token single use**: `jti` is stored in `used_tokens` until `exp`.
-- **Token binding**: optional `node_uuid` and `allowed_ip_cidr`.
-- **TOFU quarantine**: pending nodes exchange heartbeat only. No data
-  relay, no business messages.
-- **Fingerprint mismatch**: pending node presenting a different
-  fingerprint is denied; trusted node presenting a different fingerprint
-  is denied.
-- **No downgrade**: trusted node without token or session is denied.
-- **Local bypass**: `local_bypass.token` is written with mode `0600`.
-  Set `EDGE_AGENT_REQUIRE_LOCAL_BYPASS_TOKEN=false` only if you fully
-  trust every process on the host.
-- **TLS pinning**: optional SHA-256 pin of the peer certificate.
-- **Audit**: every decision is logged. Revocation is immediate on the
-  next handshake.
+- **Token Secret**: >= 32 bytes HMAC secret.
+- **Single-Use Replay Protection**: `jti` is stored in SQLite `used_tokens` until expiration. Subsequent attempts are rejected with `token replay detected`.
+- **Identity & Network Binding**: Tokens can be bound to specific `node_uuid` and `allowed_ip_cidr` networks.
+- **TOFU Quarantine**: Unapproved nodes only exchange heartbeats; business data relay is strictly forbidden.
+- **No Downgrade**: Trusted nodes presenting without credentials cannot downgrade to TOFU.
+- **Local Bypass Hardening**: `local_bypass.token` is generated with POSIX `0600` permissions.
+- **Immediate Revocation**: Revoked nodes are denied on the next handshake packet across all network profiles.
 
 ## Commercial deployment checklist
 
-- [ ] Rotate `EDGE_AGENT_TOKEN_SECRET` per environment.
-- [ ] Store `EDGE_AGENT_DATA_DIR` on persistent, encrypted storage.
-- [ ] Ship `audit.jsonl` to central logging with retention policy.
-- [ ] Enable TLS with a valid certificate; set
-      `EDGE_AGENT_CERTIFICATE_PIN_SHA256` for reverse tunnel.
-- [ ] Restrict `edge-agent approve` to an admin-only host or CI job.
-- [ ] Monitor `tofu_pending_queue_size`, `token_replay_rejections`,
-      `reverse_tunnel_reconnect_count`.
-- [ ] Run `edge-agent revoke` on node decommission.
-- [ ] Back up `trust_store.sqlite3` before upgrades.
-- [ ] Pin Python and Node versions in CI.
-- [ ] Publish PyPI and npm from tagged releases only.
-
-## Publishing
-
-PyPI:
-
-```bash
-python -m build
-python -m twine check dist/*
-python -m twine upload dist/*
-```
-
-npm (CLI wrapper):
-
-```bash
-cd npm
-npm pack --dry-run
-npm publish --access public
-```
+- [ ] Set unique `EDGE_AGENT_TOKEN_SECRET` (>= 32 bytes) per environment.
+- [ ] Mount `EDGE_AGENT_DATA_DIR` on persistent, encrypted storage.
+- [ ] Verify `local_bypass.token` POSIX permissions (`0600`).
+- [ ] Ship `audit.jsonl` to central security SIEM.
+- [ ] Enable TLS; configure `EDGE_AGENT_CERTIFICATE_PIN_SHA256` for reverse tunnels.
+- [ ] Restrict `wimotek-edge-agent approve` to admin-only bastion hosts or CI pipelines.
+- [ ] Monitor `tofu_pending_queue_size` and `token_replay_rejections`.
+- [ ] Execute `wimotek-edge-agent revoke` upon node decommissioning.
+- [ ] Back up `trust_store.sqlite3` prior to upgrades.
 
 ## License
 

package/bin/cli.js

@@ -1,14 +1,19 @@
 #!/usr/bin/env node
 const { spawn } = require('child_process');
 
-const args = ['-m', 'wimotek_edge_agent.agent', ...process.argv.slice(2)];
-const py = spawn('python3', args, { stdio: 'inherit', env: process.env });
+const path = require('path');
+const packageDir = path.resolve(__dirname, '..');
+const env = { ...process.env };
+env.PYTHONPATH = env.PYTHONPATH ? `${packageDir}:${env.PYTHONPATH}` : packageDir;
+
+const args = ['-m', 'wimotek_edge_agent', ...process.argv.slice(2)];
+const py = spawn('python3', args, { stdio: 'inherit', env });
 
 py.on('error', () => {
-  console.error('❌ 请确保宿主机已安装 Python 3 和 wimotek-edge-agent: pip install wimotek-edge-agent');
+  console.error('❌ 请确保宿主机已安装 Python 3 环境与 wimotek-edge-agent 依赖。');
   process.exit(1);
 });
 
 py.on('close', (code) => {
-  process.exit(code);
+  process.exit(code ?? 0);
 });

package/package.json

@@ -1,19 +1,25 @@
 {
   "name": "wimotek-edge-agent",
-  "version": "1.0.5",
-  "description": "Universal Edge Tunnel Agent CLI Runner",
-  "main": "index.js",
+  "version": "1.0.7",
+  "description": "Universal Edge Reverse Proxy & Service Bridge Agent CLI Runner",
   "bin": {
+    "wimotek-edge-agent": "./bin/cli.js",
+    "wimotek-agent": "./bin/cli.js",
     "edge-agent": "./bin/cli.js"
   },
   "keywords": [
+    "wimotek",
     "edge",
     "agent",
     "tunnel",
     "reverse-proxy",
-    "cdp",
-    "vnc"
+    "zero-trust",
+    "tofu",
+    "hmac-token"
   ],
-  "author": "wimotek",
-  "license": "MIT"
+  "author": "Wimotek <wimotek@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.0.0"
+  }
 }

package/pyproject.toml

@@ -6,15 +6,48 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wimotek-edge-agent"
-version = "1.0.5"
+version = "1.0.0.7"
 description = "Universal Edge Reverse Proxy & Service Bridge Agent"
 readme = "README.md"
 requires-python = ">=3.9"
+authors = [
+    { name = "Wimotek", email = "wimotek@gmail.com" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Internet :: Proxy Servers",
+    "Topic :: Security :: Cryptography",
+]
 dependencies = [
     "httpx>=0.24.0",
     "websockets>=11.0",
 ]
 
+[project.license]
+text = "MIT"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+
 [project.scripts]
-edge-agent = "wimotek_edge_agent.agent:main"
+wimotek-edge-agent = "wimotek_edge_agent.agent:main"
 wimotek-agent = "wimotek_edge_agent.agent:main"
+edge-agent = "wimotek_edge_agent.agent:main"
+
+[tool.setuptools]
+packages = [
+    "wimotek_edge_agent",
+]
+
+[tool.setuptools.package-data]
+wimotek_edge_agent = [
+    "py.typed",
+]

package/setup.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python3
+"""Standard setup.py shim for backward compatibility with older build tools and editable installs."""
+from setuptools import setup, find_packages
+
+setup(
+    packages=find_packages(include=["wimotek_edge_agent", "wimotek_edge_agent.*"]),
+    package_data={
+        "wimotek_edge_agent": ["py.typed"],
+    },
+)

package/wimotek_edge_agent/__main__.py

@@ -0,0 +1,5 @@
+from .agent import main
+import sys
+
+if __name__ == "__main__":
+    sys.exit(main())

package/{edge_agent → wimotek_edge_agent}/agent.py

@@ -4,6 +4,7 @@ import asyncio
 import ipaddress
 import ssl
 import time
+from pathlib import Path
 from typing import Awaitable, Callable, Optional
 
 from .audit import AuditLogger
@@ -358,4 +359,275 @@ class EdgeAgent:
                 if transport is not None:
                     await transport.close()
                 await asyncio.sleep(backoff)
-                backoff = min(backoff * 2, 60)
+                backoff = min(backoff * 2, 60)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="wimotek-edge-agent",
+        description="Universal Edge Tunnel & Access Policy Agent",
+    )
+    parser.add_argument(
+        "--data-dir",
+        type=str,
+        default=None,
+        help="Custom path for edge agent data directory",
+    )
+    parser.add_argument(
+        "--secret",
+        type=str,
+        default=None,
+        help="HMAC secret key (min 32 bytes) or env EDGE_AGENT_TOKEN_SECRET",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # 1. listen
+    p_listen = subparsers.add_parser("listen", help="Start direct TLS/TCP listener")
+    p_listen.add_argument("--host", default="0.0.0.0", help="Listen host (default 0.0.0.0)")
+    p_listen.add_argument("--port", type=int, default=8443, help="Listen port (default 8443)")
+    p_listen.add_argument("--cert", default=None, help="Path to TLS certificate file")
+    p_listen.add_argument("--key", default=None, help="Path to TLS private key file")
+
+    # 2. approve
+    p_app = subparsers.add_parser("approve", help="Approve a pending TOFU node")
+    p_app.add_argument("--node-uuid", required=True, help="Target node UUID")
+    p_app.add_argument("--fingerprint", default=None, help="Expected public key fingerprint")
+
+    # 3. revoke
+    p_rev = subparsers.add_parser("revoke", help="Revoke a trusted node")
+    p_rev.add_argument("--node-uuid", required=True, help="Target node UUID")
+
+    # 4. show-node
+    p_show = subparsers.add_parser("show-node", help="Inspect a node record")
+    p_show.add_argument("--node-uuid", required=True, help="Target node UUID")
+
+    # 5. list-nodes
+    p_list = subparsers.add_parser("list-nodes", help="List nodes in Trust Store")
+    p_list.add_argument(
+        "--status",
+        choices=["pending", "trusted", "revoked", "all"],
+        default="all",
+        help="Filter by trust status",
+    )
+    p_list.add_argument("--json", action="store_true", help="Output JSON lines")
+
+    # 6. delete-node
+    p_del = subparsers.add_parser("delete-node", help="Delete a node record")
+    p_del.add_argument("--node-uuid", required=True, help="Target node UUID")
+
+    # 7. issue-token
+    p_iss = subparsers.add_parser("issue-token", help="Issue single-use HMAC join token")
+    p_iss.add_argument("--node-group", default="default", help="Node group tag")
+    p_iss.add_argument("--ttl", type=int, default=300, help="TTL in seconds (default 300)")
+    p_iss.add_argument("--node-uuid", default=None, help="Bind token to specific node UUID")
+    p_iss.add_argument("--allowed-ip-cidr", default=None, help="Bind token to source IP/CIDR")
+
+    # 8. verify-token
+    p_ver = subparsers.add_parser("verify-token", help="Verify a join token")
+    p_ver.add_argument("--token", required=True, help="Join token string")
+    p_ver.add_argument("--source-ip", default="127.0.0.1", help="Source IP to test against")
+    p_ver.add_argument("--node-uuid", default="", help="Node UUID to test against")
+
+    # 9. generate-secret
+    subparsers.add_parser("generate-secret", help="Generate a high-entropy 48-byte secret")
+
+    # 10. bypass-token
+    subparsers.add_parser("bypass-token", help="Ensure and show local bypass token")
+
+    # 11. stats
+    subparsers.add_parser("stats", help="Show summary statistics of Trust Store")
+
+    # 12. simulate
+    p_sim = subparsers.add_parser("simulate", help="Simulate Access Policy handshake")
+    p_sim.add_argument("--source-ip", default="127.0.0.1")
+    p_sim.add_argument("--node-uuid", default="sim-node-1")
+    p_sim.add_argument("--fingerprint", default="sha256:simulated")
+    p_sim.add_argument("--join-token", default=None)
+    p_sim.add_argument("--local-bypass-token", default=None)
+    p_sim.add_argument("--session-ticket", default=None)
+    p_sim.add_argument("--reverse-tunnel", action="store_true")
+    p_sim.add_argument("--nat-type", default="unknown")
+
+    return parser
+
+
+def _init_agent_for_cli(args: argparse.Namespace) -> EdgeAgent:
+    config = Config.from_env()
+    if args.data_dir:
+        config.data_dir = Path(args.data_dir)
+    if args.secret:
+        config.token_secret = args.secret.encode("utf-8")
+    elif not config.token_secret:
+        # Default fallback secret for CLI inspection if not configured
+        config.token_secret = b"edge-agent-commercial-default-hmac-secret-32b"
+    return EdgeAgent(config)
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    import json
+    import sys
+    from dataclasses import asdict
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "generate-secret":
+        import secrets
+        secret = secrets.token_urlsafe(48)
+        print(secret)
+        return 0
+
+    agent = _init_agent_for_cli(args)
+
+    if args.command == "bypass-token":
+        token = agent.local_bypass.ensure_token()
+        print(json.dumps({
+            "token": token,
+            "path": str(agent.config.local_bypass_token_path),
+            "required": agent.config.require_local_bypass_token,
+        }, indent=2))
+        return 0
+
+    if args.command == "stats":
+        stats = agent.trust_store.get_stats()
+        print(json.dumps(stats, indent=2))
+        return 0
+
+    if args.command == "show-node":
+        node = agent.trust_store.get_node(args.node_uuid)
+        if node is None:
+            sys.stderr.write(f"Node '{args.node_uuid}' not found in trust store.\n")
+            return 1
+        print(json.dumps(asdict(node), indent=2, ensure_ascii=False))
+        return 0
+
+    if args.command == "list-nodes":
+        status_filter = None
+        if args.status and args.status != "all":
+            status_filter = TrustStatus(args.status)
+        nodes = agent.trust_store.list_nodes(status_filter)
+        if args.json:
+            for n in nodes:
+                print(json.dumps(asdict(n), ensure_ascii=False))
+        else:
+            print(json.dumps([asdict(n) for n in nodes], indent=2, ensure_ascii=False))
+        return 0
+
+    if args.command == "approve":
+        ok = agent.trust_store.approve_tofu(args.node_uuid, args.fingerprint)
+        if ok:
+            agent.audit.emit("node_approved", node_uuid=args.node_uuid, fingerprint=args.fingerprint)
+            print(json.dumps({"status": "ok", "message": f"Node '{args.node_uuid}' approved as TRUSTED"}, indent=2))
+            return 0
+        else:
+            sys.stderr.write(f"Failed to approve node '{args.node_uuid}' (not found or fingerprint mismatch).\n")
+            return 1
+
+    if args.command == "revoke":
+        ok = agent.trust_store.revoke(args.node_uuid)
+        if ok:
+            agent.audit.emit("node_revoked", node_uuid=args.node_uuid)
+            print(json.dumps({"status": "ok", "message": f"Node '{args.node_uuid}' marked as REVOKED"}, indent=2))
+            return 0
+        else:
+            sys.stderr.write(f"Node '{args.node_uuid}' not found.\n")
+            return 1
+
+    if args.command == "delete-node":
+        ok = agent.trust_store.delete_node(args.node_uuid)
+        if ok:
+            agent.audit.emit("node_deleted", node_uuid=args.node_uuid)
+            print(json.dumps({"status": "ok", "message": f"Node '{args.node_uuid}' deleted"}, indent=2))
+            return 0
+        else:
+            sys.stderr.write(f"Node '{args.node_uuid}' not found.\n")
+            return 1
+
+    if args.command == "issue-token":
+        try:
+            token = agent.token_issuer.issue(
+                node_group=args.node_group,
+                ttl_seconds=args.ttl,
+                node_uuid=args.node_uuid,
+                allowed_ip_cidr=args.allowed_ip_cidr,
+            )
+            print(token)
+            return 0
+        except Exception as e:
+            sys.stderr.write(f"Failed to issue token: {e}\n")
+            return 1
+
+    if args.command == "verify-token":
+        try:
+            claims = agent.token_verifier.verify(
+                token=args.token,
+                source_ip=args.source_ip,
+                node_uuid=args.node_uuid,
+            )
+            print(json.dumps(asdict(claims), indent=2))
+            return 0
+        except Exception as e:
+            sys.stderr.write(f"Token verification failed: {e}\n")
+            return 1
+
+    if args.command == "simulate":
+        is_loop = agent._is_loopback(args.source_ip)
+        ctx = ConnectionContext(
+            source_ip=args.source_ip,
+            is_loopback=is_loop,
+            node_uuid=args.node_uuid,
+            public_key_fingerprint=args.fingerprint,
+            join_token=args.join_token,
+            local_bypass_token=args.local_bypass_token,
+            session_ticket=args.session_ticket,
+            nat_type=args.nat_type,
+            reverse_tunnel=args.reverse_tunnel,
+        )
+        res = agent.authenticate(ctx)
+        out = {
+            "decision": res.decision.value,
+            "reason": res.reason,
+            "network_profile": res.network_profile,
+            "node_status": res.node_status.value if res.node_status else None,
+        }
+        print(json.dumps(out, indent=2))
+        return 0
+
+    if args.command == "listen":
+        ssl_ctx = None
+        if args.cert and args.key:
+            import ssl
+            ssl_ctx = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
+            ssl_ctx.load_cert_chain(certfile=args.cert, keyfile=args.key)
+
+        async def _run_server():
+            server = await asyncio.start_server(
+                lambda r, w: agent.handle_connection(
+                    JsonLineTransport(r, w),
+                    w.get_extra_info("peername")[0] if w.get_extra_info("peername") else "unknown",
+                ),
+                host=args.host,
+                port=args.port,
+                ssl=ssl_ctx,
+            )
+            proto = "TLS" if ssl_ctx else "Plain TCP"
+            sys.stderr.write(f"[edge-agent] Listening on {args.host}:{args.port} ({proto})\n")
+            async with server:
+                await server.serve_forever()
+
+        try:
+            asyncio.run(_run_server())
+        except KeyboardInterrupt:
+            sys.stderr.write("[edge-agent] Server stopped by user\n")
+            return 0
+
+    return 0
+
+
+if __name__ == "__main__":
+    import argparse
+    import sys
+    sys.exit(main())
+else:
+    import argparse

package/{edge_agent → wimotek_edge_agent}/trust_store.py

@@ -185,6 +185,53 @@ class TrustStore:
             return False
         return True
 
+    def list_nodes(self, status: Optional[TrustStatus] = None) -> list[NodeRecord]:
+        with self._connect() as conn:
+            if status is not None:
+                rows = conn.execute(
+                    "SELECT * FROM nodes WHERE status = ? ORDER BY first_seen DESC",
+                    (status.value,),
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT * FROM nodes ORDER BY first_seen DESC"
+                ).fetchall()
+        return [
+            NodeRecord(
+                node_uuid=r["node_uuid"],
+                fingerprint=r["fingerprint"],
+                status=TrustStatus(r["status"]),
+                first_seen=r["first_seen"],
+                approved_at=r["approved_at"],
+                network_profile=r["network_profile"],
+                metadata=json.loads(r["metadata"] or "{}"),
+            )
+            for r in rows
+        ]
+
+    def delete_node(self, node_uuid: str) -> bool:
+        with self._connect() as conn:
+            cur = conn.execute("DELETE FROM nodes WHERE node_uuid = ?", (node_uuid,))
+            return cur.rowcount > 0
+
+    def get_stats(self) -> dict[str, int]:
+        with self._connect() as conn:
+            nodes_rows = conn.execute(
+                "SELECT status, COUNT(*) as cnt FROM nodes GROUP BY status"
+            ).fetchall()
+            status_counts = {r["status"]: r["cnt"] for r in nodes_rows}
+            used_tokens_count = conn.execute(
+                "SELECT COUNT(*) as cnt FROM used_tokens"
+            ).fetchone()["cnt"]
+
+        return {
+            "total_nodes": sum(status_counts.values()),
+            "trusted_nodes": status_counts.get(TrustStatus.TRUSTED.value, 0),
+            "pending_nodes": status_counts.get(TrustStatus.PENDING.value, 0),
+            "revoked_nodes": status_counts.get(TrustStatus.REVOKED.value, 0),
+            "used_tokens_count": used_tokens_count,
+        }
+
     def consume_token(self, jti: str, expires_at: int) -> bool:
         """
         返回 True 表示首次使用；False 表示重放。