# conex

> conex（connect + nexus）是一个可嵌入的双向能力路由内核。它把分散在各自内网、
> 浏览器无法直接访问的服务，连接成同源可调用的只读能力。

本文件是 conex 落地页的机器可读说明。落地页本身是一个真实运行的中心 Host：
访客无需凭据即可浏览被显式公开的内容，并可直接执行真实的读取调用。

## 这个站点是什么

落地页由一个 `conex-host` 进程提供，路径与仓库一致：

- `/` — 交互式落地页：产品说明、请求链路演示、真实只读控制台
- `/llms.txt` — 本文件
- `/web/session` — 同源会话（公开部署下自动签发只读匿名会话）
- `/tickets` — 一次性 WebSocket 连接票据
- `/wss` — 控制平面 WebSocket
- `/content` — 同源内容交付（Range / ETag / 流式）
- `/rpc` — 服务角色入站 JSON-RPC（不接受浏览器身份）

## 核心模型

**中心 Host 是唯一信任边界。** 浏览器只与 Host 通信，永远不连接内网 Agent，
也从不接触内网地址、凭据或文件路径。

**Agent 主动反连。** 私有侧主机上的 `conex-agent` 主动发起 WebSocket 连接到
Host，因此内网无需开放任何入站端口。Agent 注册只能激活 Host 预授权的配置，
不能创建端点、切换租户或扩大方法集合。

**授权逐次生效。** 目录、读取、范围读取共用同一套租户与资源策略。知道路径、
持有 CID 或 upload 标识符都不构成授权凭据。Host 的判定优先于 Agent 自报内容，
Agent 侧再独立校验一次根目录范围。

**目录是有损的。** `endpoint/list` 只投影端点 ID、显示名、地域标签、接入方式、
连接状态、可用方法与授权范围，绝不返回绝对路径、上游地址或凭据引用。

## 公开的读取方法

- `source/list` — 列出授权范围内的目录项
- `source/read` — 读取单个资源
- `source/search` — 在授权范围内搜索

页面刻意不提供 shell、写文件、blob 提交、Agent 注册或任意命令入口。
页面不会自动重放失败调用；离线、超时与权限拒绝保持可区分的错误语义。

## 内容交付

`GET /content?endpointId=…&resourceId=…` 提供同源字节流：单区间 `Range`
（`a-b`、`a-`、`-n`）、`200/206/416`、`ETag` 与 `If-Range` 降级、
始终 `nosniff`、非安全类型强制 `attachment`、浏览器停止读取即取消上游。

页面按格式展示：文本与 Markdown 直接渲染，图片与视频原生播放，
DOCX 与 ZIP 只做受限预览（清洗脚本与外链、拒绝目录穿越与压缩炸弹），
其余二进制只提供元数据与原文件下载。

## 可验证的事实

- 协议、类型与 JSON Schema 由 `schema/conex/*.proto` 单一来源生成
- 会话、票据、CSRF、Origin 校验与一次性票据消费均在 Host 侧强制
- 断开、重新注册与代次切换受代次 fence 保护，失败注册不会踢掉健康 Agent
- 存在公开的 Rust 与 TypeScript 测试套件，证据以实际运行结果为准

## 边界

conex 不提供：写入或删除远程内容、远程命令执行、跨主机凭据转发、
或绕过资源策略的访问方式。需要这些能力时，应通过受控的写入协议与审计路径实现。