diff --git a/DEPLOYMENT_DELIVERY.md b/DEPLOYMENT_DELIVERY.md index a121078..673d2f6 100644 --- a/DEPLOYMENT_DELIVERY.md +++ b/DEPLOYMENT_DELIVERY.md @@ -1,5 +1,7 @@ # 本地部署项目交付说明 +2026-10-28 补充:主动通知与授权卡片功能使用单独的 ECS/PC 增量包交付。下面的完整 ARM64 离线包是 2026-10-27 版本,不包含本次新增功能;新环境使用时应换入最新源码并重新构建,或按新增功能文档叠加更新。 + 日期:2026-10-27。 - 新环境部署代码入口:`deployable/README.md`。 diff --git a/deployable/NOTIFICATIONS.md b/deployable/NOTIFICATIONS.md new file mode 100644 index 0000000..d372f72 --- /dev/null +++ b/deployable/NOTIFICATIONS.md @@ -0,0 +1,89 @@ +# 客户端主动消息与授权卡片 + +2026-10-28:本地功能实现。ECS 现网与 Windows 客户端尚未部署本次更新,真实消息卡片尚待验收。 + +## 实现内容 + +- 新接口 `POST /device/notifications`:文本消息、固定通知卡片、固定 OAuth 授权卡片。 +- 新工具 `work_notification`:Agent 按用户要求向本人机器人私聊发文本/通知卡片。 +- WorkClient 首次发起本人授权时,自动请求 ECS 给本人发送授权卡片;一笔授权事务仅自动尝试一次。 +- 发卡失败时保留原授权 URL,用户仍可直接打开授权,不阻断现有授权流程。 +- 现有机器人下发任务及回复原消息链路保持不变。 + +## 身份与隔离 + +请求包含 `host_id`、`request_id`、`binding_owner`、`kind`、`text`、`title`、`oauth_state`、`proof`。 + +`proof` 由设备私钥签名,覆盖设备、purpose=`work-notify-v1`、90 秒有效时间、随机 nonce、全部业务字段的 SHA256。nonce 在 Redis 中一次性消费,防止原包重放。 + +`binding_owner` 是本机保存的绑定身份声明,不是收件人参数。ECS 要求它与数据库中当前绑定用户完全一致,然后只使用数据库 owner 作为平台 `receive_id`。接口拒绝额外的 `receive_id`、`owner`、`url`、原始卡片 JSON 等参数。没有绑定、已解绑、吊销、过期或被篡改的请求拒绝处理。 + +应用凭据获取完成后,发请求前再次核对绑定。飞书发消息是外部操作,无法与数据库解绑做跨系统原子事务;已提交或已送达的消息不能因随后解绑而撤回。本功能不声称可以撤回在途消息。 + +授权卡片只引用 ECS 内存中“当前设备 + 当前用户”发起、尚未完成且未过期的 OAuth state;链接由 ECS 使用配置生成。卡片不包含 claim secret、user token 或 refresh token。回调沿用已有授权人匹配校验。 + +## 去重、限流与状态 + +数据库新增 `notifications` 表,主键 `(host_id, request_id)`,保存 owner、请求哈希、状态、平台 message_id 和创建时间,不保存正文、授权链接或 token。 + +- 同一请求用新的签名/nonce、相同 request_id 查询,返回 duplicate 与 previous_status,不重复发消息。 +- 同一 ID 换正文、换类型或换绑定用户,返回 409。 +- 每设备、每用户每分钟固定窗口最多 10 次新推送。 +- 发送使用稳定平台 uuid,额外利用平台幂等能力;本地数据库是主要去重依据,不依赖平台永久记住 uuid。 +- `sent`:平台明确返回 message_id;不等于用户已阅读或点击卡片。 +- `unknown`:平台没有给出明确结果,可能已经发送;不得换新 request_id 重发。 +- `inflight`:已有调用正在进行或上次进程在处理中退出;不自动重发。 +- `binding_changed`:发送前绑定变化,未调用发送接口。 + +服务重启后去重记录仍在;OAuth 待授权事务仍为原有内存设计,重启会丢失,用户需要重新发起授权。 + +## 新环境部署 + +使用本目录最新版源码按 README 初始化部署,connector 启动时自动创建新增表。应用需要允许机器人向可用范围内用户发送消息/卡片,平台可用范围和实际权限应单独验收。通知由机器人应用身份发送;日历/文档业务仍使用本人 user token。 + +现有 ECS 更新包只重建应用镜像并重启 connector,保留数据库、设备 CA、连接器密钥和 Compose override。先更新 ECS,再更新 PC。connector 重启会中断在途等待和内存 OAuth 事务,升级窗口先等待任务结束;不要自动重发执行状态未知的任务。当前更新包只接受与导出基线或本补丁一致的源码,版本不符会停止,不能强行覆盖。 + +```bash +# 解压更新包后,在 ECS 执行;项目目录显式指定,不自动猜路径。 +sudo bash scripts/update-notifications-ecs.sh /实际部署目录/hainuo-relay +``` + +若镜像构建或重启失败,保留脚本打印的镜像标签及源文件备份;不要继续应用 PC 补丁。恢复时先将备份的 connector.py/platform.py/oauth.py 放回源码目录,保留新增表不删;使用打印的旧镜像标签恢复 `hainuo-relay:0.1.0` 后,用相同 Compose override 重新创建 connector。新增 notifications.py 留在源码目录但旧入口不引用时不影响旧镜像;正式回滚应一并按备份及变更清单清理。 + +## PC 增量安装 + +PC 包不替换整份 work_client.py/work_tools.py,安装脚本只在已知入口中插入通知调用,并增加两个新模块。先退出本地原生 Agent;在安装包解压目录使用当前客户端 Python 执行: + +```powershell +& '客户端Python的绝对路径' .\scripts\apply_notification_client.py --relay-dir '当前客户端relay目录的绝对路径' +# 上条仅检查;兼容后执行备份和写入: +& '客户端Python的绝对路径' .\scripts\apply_notification_client.py --relay-dir '当前客户端relay目录的绝对路径' --apply +``` + +脚本备份修改前文件,遇到未知实现停止;保留已安装的 TLS、日历和文档修复。完成后重启 Agent。设备目录和平台地址沿用现有配置,不需要重新注册或重新配对。 + +## 验收命令 + +在客户端当前 Python/代码环境执行(示例中的目录、地址按实际填写): + +```powershell +& '客户端Python的绝对路径' -m relay.notification_cli ` + --directory '设备目录的绝对路径' --url 'https://中继服务地址' ` + --request-id notify-test-a-20261028-001 --kind text --text 'A电脑主动通知测试' +``` + +同一命令再次执行,应返回 duplicate,机器人只收到一次。使用 `--kind notice --title '测试通知' --text '通知内容'` 验收固定卡片。 + +授权卡片:运行 `--kind authorization`(其他参数仍填写);沿用当前有效待授权事务或新建事务,自动发卡一次,不输出领取密钥。该模式使用事务派生的稳定 ID,命令行 request-id 不参与授权卡片去重。CLI 不常驻轮询,授权后在客户端再调用 `work_authorization` 领取;原生 Agent 工具沿用已有后台轮询领取逻辑。 + +Agent 文本测试:让本机海诺调用 `work_notification`,传 `request_id`、`kind=text`、`text`,确认只进入本人机器人私聊。 + +两人两机分别测试:消息不交叉;相同 ID 不重复;A 解绑/吊销后拒绝;旧绑定客户端拒绝;B 正常使用不受影响。没有实际重新授权需求时,不删除用户 token 来强行触发授权卡片,可用独立测试设备或已有待授权事务验收。 + +## 当前验证边界 + +自动化覆盖了私有平台发送请求格式、两用户路由、签名篡改、证书身份、nonce 重放、过期、重复/并发、持久去重、限流、解绑/吊销、绑定变更、跨用户 OAuth、授权链接不含领取密钥、客户端自动发卡和旧服务回退。使用本地 HTTP/ASGI、FakeRedis 和平台桩,不代表私有化平台已完成真实卡片验收。 + +本轮完整回归:**79 passed,1 skipped**;其中新增 19 项通知及增量安装测试。跳过项为缺少真实 PostgreSQL 测试连接,其他测试没有连接真实 Work 平台。Shell 更新脚本通过 Bash 语法检查;PC 安装脚本已对当前开发源码做只读兼容检查,未修改正在运行的本机客户端。 + +ECS 升级、PC 安装、真实卡片兼容性及真实 PostgreSQL 验收均待执行。自动通知不包含定时任务、后台扫描或持续推送;仅在既有授权动作触发,或客户端/工具明确调用时发送。 diff --git a/deployable/README.md b/deployable/README.md index bf7e0f1..af7894a 100644 --- a/deployable/README.md +++ b/deployable/README.md @@ -1,5 +1,7 @@ # 海诺中继服务部署项目 +2026-10-28 新增[客户端主动消息与授权卡片](NOTIFICATIONS.md),本地代码已实现,现网部署和卡片验收待完成。 + 本目录用于新环境部署,源码对应 2026-10-27 ECS connector/router/longconn 导出版本。协议和业务源码保持原样。仓库其他快照目录用于追溯,不需要手工合并。 ## 环境要求 diff --git a/deployable/SOURCE_ORIGIN.md b/deployable/SOURCE_ORIGIN.md index 9d610e7..f6e9037 100644 --- a/deployable/SOURCE_ORIGIN.md +++ b/deployable/SOURCE_ORIGIN.md @@ -2,5 +2,5 @@ 应用源码来自本仓库 host-code/relay,与导出的 connector、router、longconn 源码逐文件一致。 enrollment-signer 使用同一版本:其入口及签发所需 crypto/enrollment/common 模块与导出签发容器一致,旧签发镜像中的其他业务模块不作为版本基线。 -应用协议及业务模块没有修改。新增内容仅为部署配置、初始化和运维工具。 +初次整理仅新增部署配置、初始化和运维工具。2026-10-28 在 deployable 中新增设备主动通知、客户端授权发卡和消息发送能力,connector/platform/oauth/work_client/work_tools 有针对性扩展;其余原有协议保持不变。新增功能不代表已更新 ECS。 原始归档及各目录继续保留用于核对;具体已部署记录见仓库根目录 deployed-services.tsv。 diff --git a/deployable/VALIDATION_REPORT.md b/deployable/VALIDATION_REPORT.md index 347c4ea..e0df1e4 100644 --- a/deployable/VALIDATION_REPORT.md +++ b/deployable/VALIDATION_REPORT.md @@ -1,5 +1,7 @@ # 部署项目整理与检查报告 +本报告记录 2026-10-27 首次部署整理。2026-10-28 新增主动通知业务的变化、79 项通过的回归结果及未部署边界,见 [NOTIFICATIONS.md](NOTIFICATIONS.md),不包含在下面的历史“业务源码未改”结论中。 + 日期:2026-10-27。范围:本地 Git 仓库新增 `deployable/`,不修改原始导出源码及当前 ECS 服务。 ## 已完成 diff --git a/deployable/relay/connector.py b/deployable/relay/connector.py index c01f3b6..c6218e8 100644 --- a/deployable/relay/connector.py +++ b/deployable/relay/connector.py @@ -144,6 +144,7 @@ def create_app(settings=None, redis=None, platform=None): broker = Broker(s, r, store) oauth = OAuth(s, r, f) oauth.store = store + from .notifications import router as notification_router background = set() def spawn(coro): @@ -185,6 +186,7 @@ def create_app(settings=None, redis=None, platform=None): app = FastAPI(title="Hainuo B1 connector", lifespan=lifespan, docs_url=None, redoc_url=None) app.add_middleware(BodyLimitMiddleware, max_body=s.max_body) app.include_router(oauth.router) + app.include_router(notification_router(s, r, store, f, oauth)) from .web_session import WebSessions web_sessions = WebSessions(s, r, store, broker, f) app.include_router(web_sessions.router) diff --git a/deployable/relay/notification_cli.py b/deployable/relay/notification_cli.py new file mode 100644 index 0000000..987a29f --- /dev/null +++ b/deployable/relay/notification_cli.py @@ -0,0 +1,34 @@ +"""Explicit local notification CLI; never accepts a recipient or arbitrary card JSON.""" +import argparse +import json +from pathlib import Path +from .work_client import WorkClient, WorkError +from .notification_client import push + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument('--directory', type=Path, required=True) + parser.add_argument('--url', required=True) + parser.add_argument('--request-id', required=True) + parser.add_argument('--kind', choices=['text', 'notice', 'authorization'], default='text') + parser.add_argument('--text', default='') + parser.add_argument('--title', default='') + args = parser.parse_args() + client = WorkClient(args.directory, args.url) + try: + if args.kind == 'authorization': + client.authorize() # Auto-pushes once; claim secret and OAuth URL are not printed. + result = {'status': client.read(client.pending).get('notification_status', 'unknown')} + else: + result = push(client, request_id=args.request_id, kind=args.kind, + text=args.text, title=args.title) + print(json.dumps(result, ensure_ascii=False)) + except WorkError as error: + parser.exit(1, str(error) + '\n') + finally: + client.close() + + +if __name__ == '__main__': + main() diff --git a/deployable/relay/notification_client.py b/deployable/relay/notification_client.py new file mode 100644 index 0000000..a740e64 --- /dev/null +++ b/deployable/relay/notification_client.py @@ -0,0 +1,69 @@ +"""Small add-on compatible with existing WorkClient; never stores or sends recipient IDs.""" +import hashlib +import httpx + + +def push(client, *, request_id, kind='text', text='', title='', oauth_state=''): + from .work_client import WorkError + payload = {'request_id': request_id, 'kind': kind, 'text': text, + 'title': title, 'oauth_state': oauth_state, 'binding_owner': client.owner} + try: + response = client.http.post('/device/notifications', json={ + **payload, 'host_id': client.config['host_id'], + 'proof': client.proof('work-notify-v1', payload)}) + except httpx.HTTPError: + raise WorkError('通知发送状态未知;未自动重试。请核对机器人消息,勿换新request_id重发。') from None + if response.status_code != 200: + raise WorkError(f'通知请求失败(HTTP {response.status_code}),未自动重试。') + return response.json() + + +def notify_authorization(client, data): + """Best effort once per local OAuth transaction. Local authorization remains usable.""" + from .work_client import atomic_secret, WorkError + if data.get('notification_attempted'): + return + data['notification_attempted'] = True + data['notification_status'] = 'unknown' + atomic_secret(client.pending, data) + try: + result = push(client, request_id='oauth_' + hashlib.sha256(data['state'].encode()).hexdigest(), + kind='authorization', oauth_state=data['state']) + data['notification_status'] = result.get('previous_status', result['status']) + except (WorkError, ValueError): + # Older ECS returns 404; direct user authorization URL remains the fallback. + data['notification_status'] = 'unconfirmed' + atomic_secret(client.pending, data) + + +def register_notification_tool(directory): + import json + import os + from tools.registry import registry + import toolsets + name = 'work_notification' + description = '按用户要求向本机绑定用户的Work机器人私聊发送文本或通知卡片;不能指定其他收件人。request_id须稳定,状态未知不得换ID重试。' + parameters = {'type': 'object', 'additionalProperties': False, + 'properties': {'request_id': {'type':'string'}, 'kind': {'type':'string', 'enum':['text','notice']}, + 'text': {'type':'string'}, 'title': {'type':'string'}}, + 'required': ['request_id','text']} + def handle(args, **kwargs): + from .work_client import WorkClient, WorkError + client = None + try: + if set(args) - {'request_id','kind','text','title'}: + raise WorkError('不支持指定收件人或自定义卡片。') + client = WorkClient(directory, os.environ.get('HN_WORK_RELAY_URL','https://10.77.76.13')) + return json.dumps(push(client, **args), ensure_ascii=False) + except WorkError as error: + return json.dumps({'status':'unconfirmed','message':str(error)},ensure_ascii=False) + except Exception: + return json.dumps({'status':'unknown','message':'通知状态未确认,未自动重试。'},ensure_ascii=False) + finally: + if client:client.close() + registry.register(name=name,toolset='hainuo_work',schema={'name':name,'description':description,'parameters':parameters}, + handler=handle,description=description) + if name not in toolsets.TOOLSETS['hainuo_work']['tools']: + toolsets.TOOLSETS['hainuo_work']['tools'].append(name) + if name not in toolsets._HERMES_CORE_TOOLS: + toolsets._HERMES_CORE_TOOLS.append(name) diff --git a/deployable/relay/notifications.py b/deployable/relay/notifications.py new file mode 100644 index 0000000..7cc2553 --- /dev/null +++ b/deployable/relay/notifications.py @@ -0,0 +1,127 @@ +"""Device-authenticated outbound messages. Recipient and OAuth links are server-owned.""" +import hashlib +import json +import time +import uuid +from urllib.parse import urlencode + +from fastapi import APIRouter, HTTPException +from fastapi.responses import JSONResponse +from pydantic import BaseModel, ConfigDict, Field + +from .common import no_cache, rate_limit +from .crypto import canonical +from .store import INTEGRITY_ERRORS +from .work_api import device_owner + + +class Notification(BaseModel): + model_config = ConfigDict(extra='forbid') + host_id: str = Field(pattern=r'^[a-f0-9]{32}$') + proof: dict + request_id: str = Field(pattern=r'^[A-Za-z0-9_-]{8,100}$') + binding_owner: str = Field(min_length=1, max_length=128) + kind: str = Field(pattern=r'^(text|notice|authorization)$') + title: str = Field(default='', max_length=80) + text: str = Field(default='', max_length=2000) + oauth_state: str = Field(default='', max_length=100) + + +def router(settings, redis, store, platform, oauth): + routes = APIRouter() + store.db.execute('''CREATE TABLE IF NOT EXISTS notifications( + host_id TEXT NOT NULL, request_id TEXT NOT NULL, owner TEXT NOT NULL, + request_hash TEXT NOT NULL, status TEXT NOT NULL, message_id TEXT NOT NULL, + created DOUBLE PRECISION NOT NULL, PRIMARY KEY(host_id,request_id))''') + if not settings.database_url: + store.db.commit() + + @routes.post('/device/notifications') + async def notify(body: Notification): + if not settings.feishu_enabled: + raise HTTPException(503, 'platform disabled') + payload = body.model_dump(exclude={'host_id', 'proof'}) + owner = await device_owner(settings, redis, store, body.host_id, body.proof, + 'work-notify-v1', payload) + if body.binding_owner != owner: + raise HTTPException(403, 'local binding is stale; pair the client again') + digest = hashlib.sha256(canonical(payload)).hexdigest() + previous = store.db.execute('SELECT * FROM notifications WHERE host_id=? AND request_id=?', + (body.host_id, body.request_id)).fetchone() + if previous: + return duplicate(dict(previous), owner, digest) + await rate_limit(redis, 'notify-device:' + body.host_id, 10) + await rate_limit(redis, 'notify-owner:' + owner, 10) + + if body.kind == 'authorization': + if body.text or body.title or not body.oauth_state: + raise HTTPException(422, 'authorization requires only a pending OAuth state') + oauth.prune() + item = oauth.pending.get(body.oauth_state) + if (not settings.oauth_enabled or not item or item.status != 'waiting' + or item.owner != owner or item.host_id != body.host_id): + raise HTTPException(403, 'active device-owned authorization required') + params = {'app_id': settings.feishu_app_id, + 'redirect_uri': settings.public_url.rstrip('/') + '/oauth/cb', + 'state': body.oauth_state} + if settings.feishu_oauth_scopes: + params['scope'] = settings.feishu_oauth_scopes + url = settings.feishu_authorize_url + '?' + urlencode(params) + if not url.startswith('https://'): + raise HTTPException(503, 'HTTPS authorization URL required') + content = {'config': {'wide_screen_mode': True}, + 'header': {'title': {'tag': 'plain_text', 'content': '海能Work 用户授权'}}, + 'elements': [ + {'tag': 'div', 'text': {'tag': 'plain_text', 'content': '本机海诺需要本人授权。请使用与电脑绑定一致的账号完成授权;链接短时有效,过期请重新发起。'}}, + {'tag': 'action', 'actions': [{'tag': 'button', 'type': 'primary', + 'text': {'tag': 'plain_text', 'content': '前往授权'}, 'url': url}]}]} + msg_type = 'interactive' + else: + if body.oauth_state or not body.text.strip(): + raise HTTPException(422, 'notification text required; OAuth state is not allowed') + if body.kind == 'text': + if body.title: + raise HTTPException(422, 'text messages do not accept title') + msg_type, content = 'text', {'text': body.text} + else: + msg_type = 'interactive' + content = {'header': {'title': {'tag': 'plain_text', 'content': body.title or '海诺通知'}}, + 'elements': [{'tag': 'div', 'text': {'tag': 'plain_text', 'content': body.text}}]} + try: + with store.db: + store.db.execute('INSERT INTO notifications VALUES(?,?,?,?,?,?,?)', + (body.host_id, body.request_id, owner, digest, 'inflight', '', time.time())) + except INTEGRITY_ERRORS: + row = store.db.execute('SELECT * FROM notifications WHERE host_id=? AND request_id=?', + (body.host_id, body.request_id)).fetchone() + return duplicate(dict(row), owner, digest) + status, message_id = 'unknown', '' + try: + # Complete credential acquisition before the last synchronous binding check. + token = await platform.tenant_token() + device = store.device(body.host_id) + if not device or device['revoked'] or device['owner'] != owner: + status = 'binding_changed' + else: + delivery_id = uuid.uuid5(uuid.NAMESPACE_URL, body.host_id + ':' + body.request_id).hex + result = await platform.send(owner, msg_type, content, delivery_id, token=token) + message_id = result.get('message_id', '') + status = 'sent' if message_id else 'unknown' + except Exception: + # A timeout may follow successful delivery. Do not retry or expose upstream secrets. + status = 'unknown' + with store.db: + store.db.execute('UPDATE notifications SET status=?,message_id=? WHERE host_id=? AND request_id=?', + (status, message_id, body.host_id, body.request_id)) + store.audit(owner, 'device_notification', body.request_id, status) + return no_cache(JSONResponse({'status': status, 'request_id': body.request_id, + 'message_id': message_id})) + + return routes + + +def duplicate(row, owner, digest): + if row['owner'] != owner or row['request_hash'] != digest: + raise HTTPException(409, 'request_id reused across owner or content') + return no_cache(JSONResponse({'status': 'duplicate', 'previous_status': row['status'], + 'request_id': row['request_id'], 'message_id': row['message_id']})) diff --git a/deployable/relay/oauth.py b/deployable/relay/oauth.py index 1b35a14..53905f6 100644 --- a/deployable/relay/oauth.py +++ b/deployable/relay/oauth.py @@ -20,6 +20,7 @@ class Transaction: status: str = "waiting" result: dict | None = None owner: str = "" + host_id: str = "" class Empty(BaseModel): @@ -72,7 +73,8 @@ class OAuth: if len(self.pending) >= self.settings.max_pending: raise HTTPException(503, "too many pending transactions") state, secret = secrets.token_urlsafe(32), secrets.token_urlsafe(32) - self.pending[state] = Transaction(hashlib.sha256(secret.encode()).hexdigest(), time.monotonic() + 600, owner=owner) + self.pending[state] = Transaction(hashlib.sha256(secret.encode()).hexdigest(), time.monotonic() + 600, + owner=owner, host_id=body.host_id) redirect = self.settings.public_url.rstrip("/") + "/oauth/cb" parameters = {"app_id": self.settings.feishu_app_id, "redirect_uri": redirect, "state": state} if self.settings.feishu_oauth_scopes: diff --git a/deployable/relay/platform.py b/deployable/relay/platform.py index a43a181..4e4dc83 100644 --- a/deployable/relay/platform.py +++ b/deployable/relay/platform.py @@ -90,3 +90,12 @@ class Feishu: await self._json("POST", f"/open-apis/im/v1/messages/{message_id}/reply", headers={"Authorization": f"Bearer {token}"}, json={"msg_type": "text", "content": json.dumps({"text": text}, ensure_ascii=False)}) + + async def send(self, owner, msg_type, content, delivery_id, *, token=None): + token = token or await self.tenant_token() + data = await self._json('POST', '/open-apis/im/v1/messages', + params={'receive_id_type': 'open_id'}, + headers={'Authorization': 'Bearer ' + token}, + json={'receive_id': owner, 'msg_type': msg_type, + 'content': json.dumps(content, ensure_ascii=False), 'uuid': delivery_id}) + return data.get('data', {}) diff --git a/deployable/relay/work_client.py b/deployable/relay/work_client.py index 4cc90b3..330d3e9 100644 --- a/deployable/relay/work_client.py +++ b/deployable/relay/work_client.py @@ -58,6 +58,8 @@ class WorkClient: if self.pending.exists(): data = self.read(self.pending) if data.get("owner") == self.owner and data["deadline"] > time.time(): + from .notification_client import notify_authorization + notify_authorization(self, data) return data["authorization_url"] response = self.http.post("/oauth/start", json={"host_id": self.config["host_id"], "proof": self.proof("work-oauth-v1", {})}) @@ -68,6 +70,8 @@ class WorkClient: raise WorkError("授权地址必须使用HTTPS。") data.update(owner=self.owner, deadline=time.time() + data["expires_in"]) atomic_secret(self.pending, data) + from .notification_client import notify_authorization + notify_authorization(self, data) return data["authorization_url"] def save_tokens(self, data): diff --git a/deployable/relay/work_tools.py b/deployable/relay/work_tools.py index b1c6da4..b748e20 100644 --- a/deployable/relay/work_tools.py +++ b/deployable/relay/work_tools.py @@ -115,6 +115,10 @@ def register(directory): toolsets._HERMES_CORE_TOOLS.append(name) + from .notification_client import register_notification_tool + register_notification_tool(directory) + + def calendar(client, args): from urllib.parse import quote action = args["action"] diff --git a/deployable/scripts/apply_notification_client.py b/deployable/scripts/apply_notification_client.py new file mode 100644 index 0000000..d8af602 --- /dev/null +++ b/deployable/scripts/apply_notification_client.py @@ -0,0 +1,64 @@ +"""Apply only the notification integration, preserving installed TLS/document fixes.""" +import argparse +import shutil +from datetime import datetime, timezone +from pathlib import Path + + +def prepare(relay_dir, source_root=None): + relay_dir=Path(relay_dir) + source_root=Path(source_root or Path(__file__).resolve().parents[1]) + client=(relay_dir/'work_client.py').read_text(encoding='utf-8-sig') + tools=(relay_dir/'work_tools.py').read_text(encoding='utf-8-sig') + if 'from .notification_client import notify_authorization' not in client: + start=client.index(' def authorize(self):') + end=client.index(' def save_tokens(',start) + block=client[start:end] + old1=' return data["authorization_url"]' + old2=' return data["authorization_url"]' + if block.count(old1)!=1 or block.count('\n'+old2)!=1: + raise ValueError('Unknown authorize implementation; stopped without modifying files') + block=block.replace(old1,' from .notification_client import notify_authorization\n' + ' notify_authorization(self, data)\n'+old1) + block=block.replace('\n'+old2,'\n from .notification_client import notify_authorization\n' + ' notify_authorization(self, data)\n'+old2) + client=client[:start]+block+client[end:] + if 'register_notification_tool(directory)' not in tools: + marker='\ndef calendar(client, args):' + if tools.count(marker)!=1 or 'def register(directory):' not in tools: + raise ValueError('Unknown tool registration implementation; stopped without modifying files') + tools=tools.replace(marker,' from .notification_client import register_notification_tool\n' + ' register_notification_tool(directory)\n\n'+marker) + updates={'work_client.py':client,'work_tools.py':tools} + for name in ['notification_client.py','notification_cli.py']: + updates[name]=(source_root/'relay'/name).read_text(encoding='utf-8-sig') + for name,text in updates.items():compile(text,name,'exec') + return updates + + +def apply(relay_dir, source_root=None): + relay_dir=Path(relay_dir) + updates=prepare(relay_dir,source_root) + backup=relay_dir.parent/('notification-backup-'+datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S-%f')) + backup.mkdir() + for name in updates: + target=relay_dir/name + if target.exists():shutil.copy2(target,backup/name) + for name,text in updates.items(): + target=relay_dir/name + temporary=target.with_suffix('.notification-tmp') + temporary.write_text(text,encoding='utf-8') + temporary.replace(target) + print('Client integration applied. Backup:',backup) + print('Restart the native Agent after the ECS upgrade. No credentials were read or printed.') + + +if __name__=='__main__': + parser=argparse.ArgumentParser() + parser.add_argument('--relay-dir',type=Path,required=True) + parser.add_argument('--apply',action='store_true') + args=parser.parse_args() + if args.apply:apply(args.relay_dir) + else: + prepare(args.relay_dir) + print('Compatible client source detected; dry run only. Use --apply to write with backup.') diff --git a/deployable/scripts/apply_notification_server.py b/deployable/scripts/apply_notification_server.py new file mode 100644 index 0000000..ee779fa --- /dev/null +++ b/deployable/scripts/apply_notification_server.py @@ -0,0 +1,35 @@ +"""Install server source only after verifying it matches the exported baseline.""" +import argparse +import hashlib +import json +import shutil +from datetime import datetime, timezone +from pathlib import Path + + +def install(root, package): + root,package=Path(root),Path(package) + manifest=json.loads((package/'manifest.json').read_text(encoding='utf-8')) + for name,entry in manifest.items(): + incoming=package/'relay'/name + assert hashlib.sha256(incoming.read_bytes()).hexdigest()==entry['new'], 'Package checksum mismatch' + target=root/'relay'/name + current=hashlib.sha256(target.read_bytes()).hexdigest() if target.exists() else None + if current not in {entry['old'],entry['new']}: + raise ValueError('Server source differs from reviewed baseline: '+name+'; nothing modified') + backup=root/'backups'/('before-notifications-'+datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S-%f')) + backup.mkdir(parents=True) + for name in manifest: + target=root/'relay'/name + if target.exists():shutil.copy2(target,backup/name) + shutil.copy2(package/'relay'/name,target) + print('Server source backup:',backup) + print('Source updated; running containers are unchanged until image rebuild/recreation.') + + +if __name__=='__main__': + parser=argparse.ArgumentParser() + parser.add_argument('--root',type=Path,required=True) + parser.add_argument('--package',type=Path,required=True) + args=parser.parse_args() + install(args.root,args.package) diff --git a/deployable/scripts/update-notifications-ecs.sh b/deployable/scripts/update-notifications-ecs.sh new file mode 100755 index 0000000..7dbeff8 --- /dev/null +++ b/deployable/scripts/update-notifications-ecs.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +set -euo pipefail +umask 077 +package=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +root=$(cd "${1:?Provide the existing ECS project directory}" && pwd) +cd "$root" +test -f .env && test -f Dockerfile.offline && test -d wheelhouse +image=hainuo-relay:0.1.0 +rollback="hainuo-relay:before-notifications-$(date +%Y%m%d-%H%M%S)" +docker image tag "$image" "$rollback" +echo "Rollback image: $rollback" +docker run --rm --user 0:0 --entrypoint python \ + -v "$root:/work" -v "$package:/patch:ro" "$image" \ + /patch/scripts/apply_notification_server.py --root /work --package /patch +docker build --network none --pull=false -f Dockerfile.offline -t "$image" . +args=(-f compose.yaml) +for extra in compose.offline.yaml compose.edge-fix.yaml compose.h5.yaml compose.work.yaml compose.feishu.yaml compose.autoreg.yaml compose.userapi.yaml; do + if [[ -f "$extra" ]]; then args+=(-f "$extra"); fi +done +# Keep existing overrides, key material, binding database and container networking. +docker compose "${args[@]}" up -d --no-build --pull never --no-deps --force-recreate connector +docker compose "${args[@]}" exec -T connector python -c 'import time,urllib.request +for _ in range(30): + try: + urllib.request.urlopen("http://127.0.0.1:8000/ready",timeout=2) + print("Connector ready; proceed with notification business acceptance.") + break + except Exception: time.sleep(1) +else: raise SystemExit("Connector not ready; preserve logs and use the recorded rollback image.")' +echo 'Only connector was recreated. Ready is not proof that the platform accepted a card.' diff --git a/deployable/tests/test_notification_client.py b/deployable/tests/test_notification_client.py new file mode 100644 index 0000000..47adcb7 --- /dev/null +++ b/deployable/tests/test_notification_client.py @@ -0,0 +1,83 @@ +import hashlib +import json +import sys +import time +import types +from pathlib import Path + +import httpx +import pytest + +sys.path.insert(0,str(Path(__file__).resolve().parents[1])) +from relay import work_client +from relay.crypto import pem_private, verified, canonical +from relay.notification_client import push, register_notification_tool +from relay.work_client import WorkClient, WorkError +from test_notifications import channel + + +@pytest.mark.asyncio +async def test_client_auto_authorization_card_once(channel, tmp_path, monkeypatch): + # DPAPI is separately implemented; keep the test independent of OS account keys. + monkeypatch.setattr(work_client,'protect',lambda b:b) + monkeypatch.setattr(work_client,'unprotect',lambda b:b) + (tmp_path/'device.json').write_text(json.dumps({'host_id':'a'*32,'owner':'ou_a'})) + (tmp_path/'device.key').write_bytes(pem_private(channel['keys']['a'*32])) + (tmp_path/'server.pem').write_bytes(channel['settings'].ca_cert.read_bytes()) + calls=[] + def handler(request): + payload=json.loads(request.content) + calls.append((request.url.path,payload)) + if request.url.path=='/oauth/start': + return httpx.Response(201,json={'state':'fake-state','claim_secret':'fake-claim-secret', + 'authorization_url':'https://work.example.test/authorize?state=fake-state','expires_in':600}) + plain={k:v for k,v in payload.items() if k not in {'host_id','proof'}} + signed=verified(payload['proof'],channel['keys']['a'*32].public_key()) + assert signed['payload_hash']==hashlib.sha256(canonical(plain)).hexdigest() + assert 'fake-claim-secret' not in json.dumps(payload) + return httpx.Response(200,json={'status':'sent','message_id':'om_test'}) + client=WorkClient(tmp_path,'https://relay.example.test',transport=httpx.MockTransport(handler)) + try: + url=client.authorize() + assert client.authorize()==url + assert [c[0] for c in calls]==['/oauth/start','/device/notifications'] + assert client.read(client.pending)['notification_status']=='sent' + finally:client.close() + + +@pytest.mark.asyncio +async def test_old_ecs_failure_keeps_local_authorization(channel,tmp_path,monkeypatch): + monkeypatch.setattr(work_client,'protect',lambda b:b) + monkeypatch.setattr(work_client,'unprotect',lambda b:b) + (tmp_path/'device.json').write_text(json.dumps({'host_id':'a'*32,'owner':'ou_a'})) + (tmp_path/'device.key').write_bytes(pem_private(channel['keys']['a'*32])) + (tmp_path/'server.pem').write_bytes(channel['settings'].ca_cert.read_bytes()) + attempts=[] + def handler(request): + if request.url.path=='/oauth/start': + return httpx.Response(201,json={'state':'fake-state','claim_secret':'private-claim', + 'authorization_url':'https://work.example.test/authorize','expires_in':600}) + attempts.append(1) + return httpx.Response(404) + client=WorkClient(tmp_path,'https://relay.example.test',transport=httpx.MockTransport(handler)) + try: + assert client.authorize()=='https://work.example.test/authorize' + assert client.authorize()=='https://work.example.test/authorize' + assert len(attempts)==1 + assert client.read(client.pending)['notification_status']=='unconfirmed' + finally:client.close() + + +def test_native_notification_tool_has_no_recipient(monkeypatch): + found={} + registry=types.SimpleNamespace(register=lambda **kw:found.update(kw)) + monkeypatch.setitem(sys.modules,'tools',types.ModuleType('tools')) + monkeypatch.setitem(sys.modules,'tools.registry',types.SimpleNamespace(registry=registry)) + toolsets=types.SimpleNamespace(TOOLSETS={'hainuo_work':{'tools':[]}},_HERMES_CORE_TOOLS=[]) + monkeypatch.setitem(sys.modules,'toolsets',toolsets) + register_notification_tool('not-used') + assert found['name']=='work_notification' + assert set(found['schema']['parameters']['properties'])=={'request_id','kind','text','title'} + result=json.loads(found['handler']({'request_id':'request_0001','text':'hi','receive_id':'ou_b'})) + assert result['status']=='unconfirmed' + assert 'work_notification' in toolsets._HERMES_CORE_TOOLS diff --git a/deployable/tests/test_notification_installers.py b/deployable/tests/test_notification_installers.py new file mode 100644 index 0000000..a078904 --- /dev/null +++ b/deployable/tests/test_notification_installers.py @@ -0,0 +1,28 @@ +import importlib.util +from pathlib import Path +import pytest + +ROOT=Path(__file__).resolve().parents[1] +spec=importlib.util.spec_from_file_location('notification_installer',ROOT/'scripts/apply_notification_client.py') +installer=importlib.util.module_from_spec(spec) +spec.loader.exec_module(installer) + + +def test_client_patch_preserves_other_fixes_and_is_repeatable(tmp_path): + baseline=ROOT.parent/'host-code/relay' + marker='\n# Existing TLS and cloud-document fixes must stay.\n' + for name in ['work_client.py','work_tools.py']: + (tmp_path/name).write_text((baseline/name).read_text(encoding='utf-8')+marker,encoding='utf-8') + updates=installer.prepare(tmp_path) + assert all(marker in updates[name] for name in ['work_client.py','work_tools.py']) + installer.apply(tmp_path) + assert (tmp_path/'work_client.py').read_text(encoding='utf-8').count('notify_authorization(self, data)')==2 + assert (tmp_path/'work_tools.py').read_text(encoding='utf-8').count('register_notification_tool(directory)')==1 + again=installer.prepare(tmp_path) + assert again['work_client.py']==(tmp_path/'work_client.py').read_text(encoding='utf-8') + + +def test_unknown_client_version_is_not_modified(tmp_path): + for name in ['work_client.py','work_tools.py']:(tmp_path/name).write_text('# unknown version\n') + with pytest.raises(ValueError):installer.prepare(tmp_path) + assert (tmp_path/'work_client.py').read_text()=='# unknown version\n' diff --git a/deployable/tests/test_notifications.py b/deployable/tests/test_notifications.py new file mode 100644 index 0000000..46cf53a --- /dev/null +++ b/deployable/tests/test_notifications.py @@ -0,0 +1,249 @@ +import asyncio +import hashlib +import json +import secrets +import sys +import time +from pathlib import Path + +import fakeredis.aioredis +import httpx +import pytest +import pytest_asyncio +from cryptography.hazmat.primitives import serialization +from cryptography.hazmat.primitives.asymmetric import ed25519 +from fastapi import FastAPI + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +from relay.config import Settings +from relay.crypto import canonical, issue_ca, issue_device, sign +from relay.notifications import router +from relay.oauth import OAuth +from relay.platform import Feishu +from relay.store import Store + + +class Platform: + def __init__(self): + self.sent = [] + self.fail = False + self.before_token = None + + async def tenant_token(self): + if self.before_token: + await self.before_token() + return 'fake-tenant-token' + + async def send(self, owner, kind, content, delivery_id, *, token): + self.sent.append((owner, kind, content, delivery_id)) + if self.fail: + raise httpx.ReadTimeout('ambiguous') + return {'message_id': 'om_' + delivery_id} + + async def exchange(self, code): + return {'user_access_token': 'fake-user-token', 'expires_in': 3600} + + async def user_info(self, token): + return {'open_id': 'ou_b'} + + +@pytest_asyncio.fixture +async def channel(tmp_path): + ca_key, ca = issue_ca() + cert_path = tmp_path/'ca.pem' + cert_path.write_bytes(ca.public_bytes(serialization.Encoding.PEM)) + settings = Settings(environment='test', admin_secret='a'*40, internal_secret='b'*40, + ca_cert=cert_path, data_dir=tmp_path, feishu_enabled=True, + feishu_app_id='cli_test', feishu_app_secret='fake-secret', + public_url='https://relay.example.test', + feishu_api_base='https://work.example.test', + feishu_authorize_url='https://work.example.test/authorize') + store = Store(tmp_path/'metadata.sqlite') + redis = fakeredis.aioredis.FakeRedis(decode_responses=True) + platform = Platform() + oauth = OAuth(settings, redis, platform) + oauth.store = store + keys = {} + for host, owner in [('a'*32,'ou_a'),('b'*32,'ou_b')]: + key = ed25519.Ed25519PrivateKey.generate() + cert = issue_device(ca_key, ca, host, key.public_key()).public_bytes(serialization.Encoding.PEM).decode() + from relay.crypto import fingerprint + store.add_device(host, cert, fingerprint(cert)) + store.bind(host, owner) + keys[host] = key + app = FastAPI() + app.include_router(oauth.router) + app.include_router(router(settings, redis, store, platform, oauth)) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app), base_url='https://relay.example.test') as client: + yield {'client':client, 'store':store, 'platform':platform, 'oauth':oauth, 'keys':keys, + 'settings':settings, 'redis':redis, 'app':app} + await redis.aclose() + store.close() + + +def proof(env, host, purpose, payload, **override): + return sign({'host_id':host, 'purpose':purpose, 'ts':int(time.time()), + 'nonce':secrets.token_hex(16), 'payload_hash':hashlib.sha256(canonical(payload)).hexdigest(), + **override}, env['keys'][host]) + + +def wire(env, host='a'*32, request_id='request_0001', **fields): + payload={'request_id':request_id,'kind':'text','text':'hello','title':'','oauth_state':'', + 'binding_owner':'ou_a' if host=='a'*32 else 'ou_b',**fields} + return {**payload, 'host_id':host, 'proof':proof(env,host,'work-notify-v1',payload)} + + +@pytest.mark.asyncio +async def test_two_devices_route_to_own_users(channel): + for host,owner in [('a'*32,'ou_a'),('b'*32,'ou_b')]: + response=await channel['client'].post('/device/notifications',json=wire(channel,host)) + assert response.json()['status']=='sent' + assert channel['platform'].sent[-1][0]==owner + + +@pytest.mark.asyncio +async def test_recipient_and_arbitrary_url_are_rejected(channel): + for field in ['receive_id','owner','url','card']: + response=await channel['client'].post('/device/notifications',json={**wire(channel),field:'ou_b'}) + assert response.status_code==422 + assert not channel['platform'].sent + + +@pytest.mark.asyncio +async def test_tampering_wrong_device_and_expired_proof(channel): + for variant in ['content','host','expired']: + data=wire(channel) + if variant=='content':data['text']='tampered' + if variant=='host':data['host_id']='b'*32 + if variant=='expired': + payload={k:v for k,v in data.items() if k not in {'host_id','proof'}} + data['proof']=proof(channel,'a'*32,'work-notify-v1',payload,ts=int(time.time())-200) + assert (await channel['client'].post('/device/notifications',json=data)).status_code==403 + assert not channel['platform'].sent + + +@pytest.mark.asyncio +async def test_proof_replay_and_idempotent_payload(channel): + data=wire(channel) + assert (await channel['client'].post('/device/notifications',json=data)).json()['status']=='sent' + assert (await channel['client'].post('/device/notifications',json=data)).status_code==409 + result=await channel['client'].post('/device/notifications',json=wire(channel)) + assert result.json()['previous_status']=='sent' + changed=await channel['client'].post('/device/notifications',json=wire(channel,text='different')) + assert changed.status_code==409 + assert len(channel['platform'].sent)==1 + + +@pytest.mark.asyncio +async def test_dedupe_survives_new_router(channel): + await channel['client'].post('/device/notifications',json=wire(channel)) + app=FastAPI() + app.include_router(router(channel['settings'],channel['redis'],channel['store'],channel['platform'],channel['oauth'])) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app),base_url='https://relay.example.test') as client: + assert (await client.post('/device/notifications',json=wire(channel))).json()['status']=='duplicate' + assert len(channel['platform'].sent)==1 + + +@pytest.mark.asyncio +async def test_revoked_and_unbound_rejected(channel): + channel['store'].revoke('a'*32) + channel['store'].unbind('ou_b') + for host in ['a'*32,'b'*32]: + assert (await channel['client'].post('/device/notifications',json=wire(channel,host))).status_code==403 + + +@pytest.mark.asyncio +async def test_binding_rechecked_after_token_acquisition(channel): + async def change():channel['store'].unbind('ou_a') + channel['platform'].before_token=change + result=await channel['client'].post('/device/notifications',json=wire(channel)) + assert result.json()['status']=='binding_changed' + assert not channel['platform'].sent + + +@pytest.mark.asyncio +async def test_request_id_cannot_migrate_to_rebound_owner(channel): + await channel['client'].post('/device/notifications',json=wire(channel)) + channel['store'].unbind('ou_a') + channel['store'].bind('a'*32,'ou_new') + assert (await channel['client'].post('/device/notifications',json=wire(channel))).status_code==403 + assert (await channel['client'].post('/device/notifications',json=wire(channel,binding_owner='ou_new'))).status_code==409 + assert len(channel['platform'].sent)==1 + + +@pytest.mark.asyncio +async def test_unknown_delivery_is_not_retried(channel): + channel['platform'].fail=True + assert (await channel['client'].post('/device/notifications',json=wire(channel))).json()['status']=='unknown' + again=await channel['client'].post('/device/notifications',json=wire(channel)) + assert again.json()['previous_status']=='unknown' + assert len(channel['platform'].sent)==1 + + +@pytest.mark.asyncio +async def test_concurrent_same_request_delivered_once(channel): + entered,release=asyncio.Event(),asyncio.Event() + async def pause():entered.set();await release.wait() + channel['platform'].before_token=pause + task=asyncio.create_task(channel['client'].post('/device/notifications',json=wire(channel))) + await entered.wait() + second=await channel['client'].post('/device/notifications',json=wire(channel)) + assert second.json()['previous_status']=='inflight' + release.set() + assert (await task).json()['status']=='sent' + assert len(channel['platform'].sent)==1 + + +@pytest.mark.asyncio +async def test_rate_limit(channel): + for i in range(10): + assert (await channel['client'].post('/device/notifications',json=wire(channel,request_id=f'request_{i:04d}'))).status_code==200 + assert (await channel['client'].post('/device/notifications',json=wire(channel,request_id='request_extra'))).status_code==429 + assert len(channel['platform'].sent)==10 + + +async def start_oauth(channel,host='a'*32): + response=await channel['client'].post('/oauth/start',json={'host_id':host,'proof':proof(channel,host,'work-oauth-v1',{})}) + assert response.status_code==201 + return response.json() + + +@pytest.mark.asyncio +async def test_authorization_card_server_owned_and_no_claim_secret(channel): + data=await start_oauth(channel) + result=await channel['client'].post('/device/notifications',json=wire(channel,kind='authorization',text='',oauth_state=data['state'])) + assert result.json()['status']=='sent' + owner,kind,card,_=channel['platform'].sent[-1] + assert owner=='ou_a' and kind=='interactive' + assert card['elements'][1]['actions'][0]['url']==data['authorization_url'] + assert data['claim_secret'] not in json.dumps(card) + assert 'user_access_token' not in json.dumps(card) + # Wrong Work user completing this OAuth transaction is rejected by existing callback validation. + response=await channel['client'].get('/oauth/cb',params={'state':data['state'],'code':'fake-code'}) + assert response.status_code==502 + + +@pytest.mark.asyncio +async def test_cross_user_and_expired_oauth_cards_rejected(channel): + data=await start_oauth(channel,'b'*32) + response=await channel['client'].post('/device/notifications',json=wire(channel,kind='authorization',text='',oauth_state=data['state'])) + assert response.status_code==403 + channel['oauth'].pending[data['state']].expires=0 + response=await channel['client'].post('/device/notifications',json=wire(channel,'b'*32,kind='authorization',text='',oauth_state=data['state'])) + assert response.status_code==403 + assert not channel['platform'].sent + + +@pytest.mark.asyncio +async def test_platform_send_wire_format(channel): + captured=[] + def handler(request): + captured.append(request) + return httpx.Response(200,json={'code':0,'data':{'message_id':'om_real'}}) + api=Feishu(channel['settings'],transport=httpx.MockTransport(handler)) + try: + assert (await api.send('ou_a','text',{'text':'hello'},'stable-id',token='fake-token'))['message_id']=='om_real' + finally:await api.close() + request=captured[0] + assert str(request.url)=='https://work.example.test/open-apis/im/v1/messages?receive_id_type=open_id' + assert json.loads(request.content)=={'receive_id':'ou_a','msg_type':'text','content':'{"text": "hello"}','uuid':'stable-id'}