Mote 是一套动作允许列表封闭的远程动作系统。它不是远程 shell,也绝不能变成远程 shell。
Mote for Mac 把 device_connection 凭据存放在钥匙串。Mote Relay 只保存设备凭据和快捷指令 token 的 SHA-256 哈希。
这是个人工具。它不是零信任,也不声称自己是密码学产品。
存在三种互不兼容的身份。服务器按存储位置强制角色,而不是由客户端自行声明角色。管理员会话不能使用 Shortcut token 或设备凭据。
权限:
send_command
仅供 Apple 快捷指令或未来的 Mote iOS 使用。iPhone 快捷指令见 shortcuts.md。个人 iOS 客户端见 ios.md。
请求头:
Authorization: Bearer <shortcut-token>不要把 token 放进查询字符串、URL fragment 或 cookie。
该凭据可以为已知设备创建命令。它不得用于认证设备 WebSocket。
权限:
device_connection
仅供 Mote Agent 认证其 WebSocket 连接。
该凭据可以把一台 Mac 挂到 Mote Relay,并接收发给该设备的命令。它不得被接受为快捷指令/命令客户端凭据。
在设备 WebSocket 上出示 send_command 密钥会被拒绝。在命令 HTTP 路径上出示 device_connection 密钥会被拒绝。这两种凭据都不能登录 Dashboard。
Dashboard 使用独立的 admins 表,而不是 Bearer token。
- 密码用 Argon2id 哈希(
@noble/hashes,编码串含盐与参数)。不使用单独的 SHA-256、明文或 MD5。 - 浏览器只收到随机会话 token,放在
mote_admin_sessionHttpOnly cookie 中。服务端只保存 SHA-256 哈希。 - Cookie:
HttpOnly、生产环境Secure、SameSite=Lax、Path=/,默认 7 天。 - 状态改变的
/admin/api/*请求还要校验 Origin / Referer,以及 JSONContent-Type。GET /admin/api/events(SSE)只读,不受该 CSRF 钩子限制,但仍要管理员 cookie。 - 登录按来源每分钟最多 5 次。
- 新设备凭据和 Shortcut token 只在创建或轮换时返回一次。Dashboard 不把它们写入
localStorage或sessionStorage。 - 管理员创建与密码恢复只通过 CLI。没有注册、邮件找回或 OAuth。
- 命令活动只保留最近 10,000 条。
duration_ms是命令从创建到完成的墙钟时间,不是心跳 RTT。
- 密钥是长的、密码学随机值(
crypto.randomBytes)。 - Relay 只持久化 SHA-256 十六进制摘要。
- 校验时对出示的密钥做哈希,再用
timingSafeEqual比较摘要。 - CLI 只打印一次密钥,且永不写入源文件。
- 日志使用
device_id、command_id、token_id和pair_request_id。不得包含 Bearer token、设备凭据、pair_secret或 Authorization 头。 - 配对请求只保存
pair_secret的 SHA-256 哈希。设备明文凭据在批准时生成,推给配对 WebSocket,不入库。 - 公开
POST /v1/pair/requests按 IP(默认 10 分钟 20 次)与device_id(默认 10 分钟 5 次)限流。错误的pair_secret不能领取凭据。 GET /s/:deviceId是公开安装页:只带 Device ID 和命令 URL,不带 token,也不展示设备是否在线。
- 生产环境仅使用 HTTPS 和 WSS。
- 文档示例公网主机名是
relay.example.com;生产换成自己的主机名,并用MOTE_PUBLIC_URL对齐。 - 客户端始终使用该 HTTPS 基址以及由其推导的
wss://…/v1/ws/device和wss://…/v1/ws/pair。Cloudflare Tunnel 不得改变这些安全 URL。 - Dashboard SSE(
GET /admin/api/events)与页面同源,走connect-src 'self';事件里只有 topic,没有凭据或实体。 - 开发可以使用
http://127.0.0.1:3000、ws://127.0.0.1:3000/v1/ws/device和ws://127.0.0.1:3000/v1/ws/pair。 - 不要把 Mac 或快捷指令改成访问
http://192.0.2.10:3000。该地址只是 PVE 宿主机上cloudflared的源站。 - Mac 生产代码永不关闭 TLS 校验。
- Relay 生成命令的
id、created_at、expires_at和nonce。快捷指令不提供这些字段。 - 默认 TTL 为 10 秒。
- 离线命令立即拒绝,永不排队。
- 重复命令 ID 由 Mac 的近期 ID 缓存拒绝。Relay 的 pending 条目只 resolve 一次。
- 未知以及已预留但未实现的动作会被拒绝。
- WebSocket 设备必须先认证才能接收命令。
- 未认证套接字会在认证超时后关闭(Relay 默认 5 秒)。超时关闭不发送
invalid_credentials,以便 Mac 重连。
Mote Agent 只能运行预定义的本地动作(当前为 lock)。
Mote Relay 转发允许列表中的命令。它不会替客户端执行操作系统命令。
禁止:
- 远程任意 shell 执行
- 客户端提供的可执行路径
- 客户端提供的 AppleScript
- 把 Mote Relay 当作通用远程代码执行系统
- JSON 正文上限(默认 16 KiB)
- 内存中的命令速率限制(默认每 token 每 10 秒 10 次)
- 没有宽松 CORS(未启用
Access-Control-Allow-Origin: *) - 机器 API 不使用浏览器会话 cookie
- Dashboard 使用 HttpOnly 管理员会话 cookie;
/admin/api/*响应为Cache-Control: no-store。SSE 另加X-Accel-Buffering: no,减少反向代理缓冲。 - 登录有独立的内存速率限制
- HTML 响应带有 CSP、
X-Content-Type-Options、Referrer-Policy和frame-ancestors 'none'
- 在家和外出都走同一条 Cloudflare Tunnel,终止在同一 Mote Relay 实例。当前不使用 Split DNS。
cloudflared运行在 PVE 宿主机上。Mote LXC / Compose 不持有 Tunnel token,也不调用 Cloudflare API。- 不要在 Mote 前面放交互式 Cloudflare Access。快捷指令 / 未来 iOS 的 Bearer
send_commandtoken、Mac 的device_connection凭据,以及 Dashboard 管理员会话已经负责认证。交互式登录会干扰快捷指令、未来的 iOS 客户端和持久 WebSocket。 - 把
192.0.2.10:3000发布到家庭 LAN 并不削弱 Relay 认证。Bearer、设备 WebSocket 认证、凭据角色分离、命令允许列表、速率限制、TTL、无命令队列和重复保护全部保留。健康检查可以保持当前的未认证设计。 - Compose 文件和文档只使用环境变量占位符。不要把 Cloudflare 密钥放进 Mote 部署。
- 管理 CLI 不得暴露到公网。