ameshdev/amesh

# amesh **设备绑定的 M2M 认证。用加密设备身份替代 API 密钥。** 不需要 `.env` 文件。CI 中没有机密信息。Slack 中没有令牌。私钥保留在您的设备上 --- 没有任何内容会泄露。 [](https://github.com/ameshdev/amesh/actions/workflows/ci.yml) [](./LICENSE) ## 使用前后对比 ``` // Before: static secret that can leak fetch("/api/orders", { headers: { Authorization: `Bearer ${process.env.API_KEY}` } }); ``` ``` // After: device-bound signature, nothing to leak import { amesh } from '@authmesh/sdk'; amesh.fetch("/api/orders", { method: "POST", body: JSON.stringify({ amount: 100 }) }); ``` 无需 `.env`。无需机密。请求使用永不离开您机器的 P-256 ECDSA 密钥进行签名。 ## 安装 ``` npm install @authmesh/sdk # signing client + verification middleware npm install -g @authmesh/cli # CLI for device management ``` ## 快速开始 ### 1. 创建设备身份 ``` amesh init --name "prod-api" # 身份已创建。 # Device ID : am_cOixWcOdI8-pLh4P # Backend : Secure Enclave # Friendly Name : prod-api ``` ### 2. 配对两台机器 在目标（服务器）上： ``` amesh listen # 配对代码：482916 # 输入 Controller 上显示的 6 位数字。 # 验证码：847291 # ✔ "my-laptop" 已添加为 controller。 ``` 在控制器（您的笔记本电脑）上： ``` amesh invite 482916 # 验证码：847291 # 在 Target 设备上输入此代码。 # ✔ "prod-api" 已添加为 target。 ``` 信任是单向的：控制器可以向目标进行身份验证，但反之则不行。 ### 3. 签名请求（2 行代码） ``` import { amesh } from '@authmesh/sdk'; const res = await amesh.fetch('https://api.example.com/data', { method: 'POST', body: JSON.stringify({ amount: 100 }) }); ``` ### 4. 验证请求（2 行代码） ``` import { amesh } from '@authmesh/sdk'; app.use(amesh.verify()); // req.authMesh.deviceId, req.authMesh.friendlyName available ``` ## 工作原理 - **设备身份** --- 每台机器获得一个唯一的 P-256 ECDSA 密钥对。私钥受操作系统密钥链、TPM 2.0（Linux）或加密文件（云 VM）保护，永不离开设备。 - **单向信任** --- 控制器向目标进行身份验证，反之则不行。被入侵的服务器无法回连到您的笔记本电脑。 - **签名请求** --- 每个 HTTP 请求都使用设备的私钥进行签名。签名涵盖方法、路径、时间戳、nonce 和正文。 - **重放保护** --- 每个请求都有一个唯一的 nonce 和 30 秒的时间戳窗口。Nonce 在服务端进行跟踪。 - **无静态机密** --- 没有字符串会泄露、轮换或共享。使用 `amesh revoke` 立即吊销被入侵的设备。 ## 软件包 | 软件包 | 描述 | |---------|-------------| | [`@authmesh/sdk`](./packages/sdk) | 签名 fetch 客户端 + Express 验证中间件 | | [`@authmesh/cli`](./packages/cli) | CLI：`init`、`listen`、`invite`、`list`、`revoke`、`provision` | | [`@authmesh/core`](./packages/core) | 加密原语：签名、验证、规范字符串、nonce、HMAC、HKDF、ECDH | | [`@authmesh/keystore`](./packages/keystore) | 密钥存储驱动：Secure Enclave、macOS Keychain、TPM 2.0、加密文件 | | [`@authmesh/relay`](./packages/relay) | 用于设备配对握手的 WebSocket 中继 | ## 架构 ``` [Pairing — one time] Target (server) <--WebSocket--> Relay <--WebSocket--> Controller (laptop) (P-256 ECDH + ChaCha20-Poly1305 + SAS verification) [Runtime — every request] Controller ----HTTP + AuthMesh header----> Target (one-way trust, no relay, stateless) ``` 中继仅用于初始配对握手。设备交换公钥后，所有身份验证均为无状态 HTTP 头。信任是单向的：控制器向目标进行身份验证，但目标无法反向进行身份验证。可以关闭中继，所有现有配对继续工作。 ## 自托管 amesh 完全独立。无 SaaS，无遥测，无回连。 - 从 npm 安装软件包（MIT 许可） - 运行您自己的中继：Docker、Cloud Run、Fly.io、Kubernetes 或直接使用 Bun - 所有数据保留在您的机器上（`~/.amesh/`） 有关部署选项，请参阅 [自托管指南](./docs/self-hosting.md)。 ## 文档 | 文档 | 描述 | |-----|-------------| | [集成指南](./docs/integration-guide.md) | Express、微服务、webhooks、远程配对的教程 | | [自托管指南](./docs/self-hosting.md) | 部署中继：Docker、Cloud Run、Fly.io、Kubernetes | | [使用指南](./docs/guide.md) | CLI 命令、SDK 用法、加密原语 | | [协议规范](./docs/protocol-spec.md) | 完整协议规范 (v2.0.0) | | [架构决策](./docs/architecture-decisions.md) | 针对每个设计决策的 ADR | | [为什么选择 amesh](./docs/why-amesh.md) | amesh 解决的问题 | ## 语言支持 amesh 目前提供 **TypeScript/Node.js SDK**。该协议与语言无关（标准 HTTP 头 + ECDSA-P256 签名），因此可以用任何语言实现验证。Python 和 Go 的 SDK 已在计划中。 ## 将 amesh 与 AI 助手配合使用 amesh 旨在易于与 Claude、Copilot 和 Cursor 等 AI 编码助手集成。这些软件包具有完整的 TypeScript 类型，且 API 表面极小。 **示例提示词：** - "帮我用 amesh 保护我的 Express API，替代 API 密钥" - "在我的 Node.js 服务中设置 `amesh.fetch()` 以调用经过身份验证的端点" - "使用 Redis nonce 存储配置 amesh，以进行多实例生产部署" - "为我的微服务添加 amesh 设备身份验证" SDK 有两个主要功能：`amesh.fetch()`（客户端）和 `amesh.verify()`（服务端中间件）。仅此而已。 ## 开发 ``` bun install # install all deps bun run build # turbo build (tsc -b per package) bun run test # tests across all packages bun run lint # eslint + prettier ``` ## 许可证 [MIT](./LICENSE)

标签：API安全, API密钥替换, CVE, ECDSA, GNU通用公共许可证, JSONLines, JSON输出, M2M认证, MITM代理, Node.js, P-256, SOC Prime, 中间件, 加密, 双向认证, 安全飞地, 开发工具, 数字签名, 无密钥, 漏洞扫描器, 环境变量, 私钥保护, 网络安全, 自动化攻击, 设备身份认证, 设备配对, 身份与访问管理, 隐私保护, 零信任