@celljs/ta-relay 4.9.1 → 4.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/README.en.md +29 -2
  2. package/README.md +29 -2
  3. package/esm/common/index.d.ts +10 -0
  4. package/esm/common/index.js +10 -0
  5. package/esm/common/relay-blobs.d.ts +54 -0
  6. package/esm/common/relay-blobs.js +153 -0
  7. package/esm/common/relay-card.d.ts +23 -0
  8. package/esm/common/relay-card.js +30 -0
  9. package/esm/common/relay-cipher.d.ts +15 -0
  10. package/esm/common/relay-cipher.js +62 -2
  11. package/esm/common/relay-content.d.ts +104 -0
  12. package/esm/common/relay-content.js +316 -0
  13. package/esm/common/relay-conversation.d.ts +59 -0
  14. package/esm/common/relay-conversation.js +9 -0
  15. package/esm/common/relay-files.d.ts +108 -0
  16. package/esm/common/relay-files.js +170 -0
  17. package/esm/common/relay-hub-util.d.ts +91 -0
  18. package/esm/common/relay-hub-util.js +164 -0
  19. package/esm/common/relay-hub.d.ts +125 -0
  20. package/esm/common/relay-hub.js +438 -0
  21. package/esm/common/relay-hubs.d.ts +271 -0
  22. package/esm/common/relay-hubs.js +844 -0
  23. package/esm/common/relay-identity.d.ts +46 -0
  24. package/esm/common/relay-identity.js +126 -0
  25. package/esm/common/relay-protocol.d.ts +217 -2
  26. package/esm/common/relay-protocol.js +53 -0
  27. package/esm/common/relay-room-chat.d.ts +80 -0
  28. package/esm/common/relay-room-chat.js +152 -0
  29. package/esm/common/relay-socket.d.ts +8 -0
  30. package/esm/common/relay-socket.js +33 -4
  31. package/esm/guest/guest-i18n.d.ts +47 -0
  32. package/esm/guest/guest-i18n.js +97 -0
  33. package/esm/guest/guest-style.d.ts +1 -0
  34. package/esm/guest/guest-style.js +78 -0
  35. package/esm/guest/guest.d.ts +1 -0
  36. package/esm/guest/guest.js +371 -0
  37. package/esm/node/index.d.ts +3 -0
  38. package/esm/node/index.js +3 -0
  39. package/esm/node/relay-files-host.d.ts +27 -0
  40. package/esm/node/relay-files-host.js +130 -0
  41. package/esm/node/relay-host.d.ts +35 -2
  42. package/esm/node/relay-host.js +150 -13
  43. package/esm/node/relay-hub-files.d.ts +12 -0
  44. package/esm/node/relay-hub-files.js +39 -0
  45. package/esm/node/relay-server.d.ts +46 -1
  46. package/esm/node/relay-server.js +227 -1
  47. package/esm/node/relay-store.d.ts +72 -0
  48. package/esm/node/relay-store.js +123 -2
  49. package/esm/node/relay-viewer.d.ts +7 -0
  50. package/esm/node/relay-viewer.js +33 -0
  51. package/esm/viewer/viewer-i18n.d.ts +56 -0
  52. package/esm/viewer/viewer-i18n.js +117 -0
  53. package/esm/viewer/viewer-markdown.d.ts +7 -0
  54. package/esm/viewer/viewer-markdown.js +198 -0
  55. package/esm/viewer/viewer-style.d.ts +1 -0
  56. package/esm/viewer/viewer-style.js +72 -0
  57. package/esm/viewer/viewer.d.ts +8 -0
  58. package/esm/viewer/viewer.js +378 -0
  59. package/lib/common/index.d.ts +10 -0
  60. package/lib/common/index.js +10 -0
  61. package/lib/common/relay-blobs.d.ts +55 -0
  62. package/lib/common/relay-blobs.js +157 -0
  63. package/lib/common/relay-card.d.ts +24 -0
  64. package/lib/common/relay-card.js +33 -0
  65. package/lib/common/relay-cipher.d.ts +15 -0
  66. package/lib/common/relay-cipher.js +63 -3
  67. package/lib/common/relay-content.d.ts +105 -0
  68. package/lib/common/relay-content.js +320 -0
  69. package/lib/common/relay-conversation.d.ts +60 -0
  70. package/lib/common/relay-conversation.js +12 -0
  71. package/lib/common/relay-files.d.ts +109 -0
  72. package/lib/common/relay-files.js +174 -0
  73. package/lib/common/relay-hub-util.d.ts +92 -0
  74. package/lib/common/relay-hub-util.js +167 -0
  75. package/lib/common/relay-hub.d.ts +126 -0
  76. package/lib/common/relay-hub.js +442 -0
  77. package/lib/common/relay-hubs.d.ts +272 -0
  78. package/lib/common/relay-hubs.js +848 -0
  79. package/lib/common/relay-identity.d.ts +47 -0
  80. package/lib/common/relay-identity.js +129 -0
  81. package/lib/common/relay-protocol.d.ts +217 -2
  82. package/lib/common/relay-protocol.js +54 -1
  83. package/lib/common/relay-room-chat.d.ts +81 -0
  84. package/lib/common/relay-room-chat.js +156 -0
  85. package/lib/common/relay-socket.d.ts +8 -0
  86. package/lib/common/relay-socket.js +32 -3
  87. package/lib/guest/guest-i18n.d.ts +48 -0
  88. package/lib/guest/guest-i18n.js +100 -0
  89. package/lib/guest/guest-style.d.ts +2 -0
  90. package/lib/guest/guest-style.js +81 -0
  91. package/lib/guest/guest.d.ts +2 -0
  92. package/lib/guest/guest.js +373 -0
  93. package/lib/node/index.d.ts +3 -0
  94. package/lib/node/index.js +3 -0
  95. package/lib/node/relay-files-host.d.ts +28 -0
  96. package/lib/node/relay-files-host.js +134 -0
  97. package/lib/node/relay-host.d.ts +35 -2
  98. package/lib/node/relay-host.js +149 -12
  99. package/lib/node/relay-hub-files.d.ts +13 -0
  100. package/lib/node/relay-hub-files.js +43 -0
  101. package/lib/node/relay-server.d.ts +46 -1
  102. package/lib/node/relay-server.js +226 -0
  103. package/lib/node/relay-store.d.ts +72 -0
  104. package/lib/node/relay-store.js +121 -0
  105. package/lib/node/relay-viewer.d.ts +8 -0
  106. package/lib/node/relay-viewer.js +32 -0
  107. package/lib/viewer/viewer-i18n.d.ts +57 -0
  108. package/lib/viewer/viewer-i18n.js +120 -0
  109. package/lib/viewer/viewer-markdown.d.ts +8 -0
  110. package/lib/viewer/viewer-markdown.js +201 -0
  111. package/lib/viewer/viewer-style.d.ts +2 -0
  112. package/lib/viewer/viewer-style.js +75 -0
  113. package/lib/viewer/viewer.d.ts +9 -0
  114. package/lib/viewer/viewer.js +381 -0
  115. package/package.json +5 -4
  116. package/viewer/frame.html +1 -0
  117. package/viewer/page.html +80 -0
  118. package/viewer/room.html +87 -0
package/README.en.md CHANGED
@@ -24,8 +24,23 @@ Pairing links look like `https://<relay>/pair#v=1&h=<host-id>&d=<device-id>&k=<k
24
24
  - `/v1/connect/<host-id>`: devices connect here. Relay assigns each a channel and forwards it to the host (`{t:'open'|'data'|'close', ch, d}`).
25
25
  - Handshake: the device sends first `{t:'hello', v:1, device, nonce}`; the host finds the device's key and replies `{t:'ready', nonce, proof}`. Both sides use HKDF-SHA-256 (device key, salt is both nonces) to derive one AES-256-GCM key for each direction, ensuring every connection has a different key. `proof` is the host's first encrypted message, proving it has this device's key. After that, every message is encrypted with the IV set to the message sequence number, so Relay's replay, drop, or reorder attempts all fail decryption.
26
26
  - The host opens one connection per device to localhost's `/api/ws`, including the localhost token. Devices never receive or need the token.
27
+ - Files (see below) take a channel of the device's own: after the handshake, the device's first sealed message is `{t:'files', v:1}`, and the host opens no `/api/ws` for it but answers `{t:'get', id, url}` on that channel with `{t:'head', id, status, type, size}`, chunks `{t:'chunk', id, d}` of 192 KB, and `{t:'end', id}`, or `{t:'error', id, message}` — sealed all the same.
27
28
  - Heartbeat: the host and devices send `ping` to Relay every 25 seconds (outside the channels), and Relay answers `pong` itself (without waking the Durable Object). A connection can be gone while it still looks open (common behind proxies, after a network change, or after the computer sleeps). So when `pong` stops coming, or the computer wakes, the host reconnects to Relay and a device drops its connection and reconnects (close code 4408). An older Relay that has never answered `pong` is left alone. Relay closes connections with no heartbeat for 80 seconds. When a host reconnects, Relay closes the devices on its old connection (4404) so that they connect again. A device with no handshake reply within 15 seconds also drops the connection and retries (4408).
28
29
 
30
+ ## Previewing files
31
+
32
+ A page on a phone (the Ta app through Relay, or a browser through Relay) cannot load `/api/files` of `ta serve`: that address exists only where the server runs, and through Relay only the calls on the WebSocket get there. So a device opens a channel of its own and asks the host for the bytes of a file (`RelayFiles` on the device, `RelayFilesHost` on the host): pictures, videos, sounds and PDFs become `blob:` URLs the page shows, and an HTML report is shown from the text of the file in a sandboxed frame.
33
+
34
+ Only that one thing is allowed, for the sake of safety:
35
+
36
+ - Only paths under `/api/files/`, only GET, and the path is taken from the parsed URL, never from the text a device sent: a device cannot make the host reach another address (`RelayFilesHost.target`).
37
+ - Only `127.0.0.1:<the port of ta serve>`, with the `Host` written by the host itself: devices reach no other port, no other machine, and no other `/api/*` call.
38
+ - The requests carry no Cookie and no Authorization; a device already has the whole RPC of the machine, so this widens nothing — it hands it `/api/files` too.
39
+ - At most 4 files at once on a channel, 128 MB for one and 30 seconds.
40
+ - The bytes stay sealed end to end: the relay reads neither the request nor the file.
41
+
42
+ A web extension can tell and read it with `pi.files` (`read(url)` while `byUrl` is false); the previews of `@celljs/ta-workspace` do.
43
+
29
44
  ## Sharing extensions
30
45
 
31
46
  A Ta service can also hand an extension of its computer to another through the relay (`RelayStore.shareRoot`, `RelayShareUtil`): a link `https://<relay>/share#v=1&h=<host id>&s=<share id>&k=<key>&n=<name>`, good for 7 days. The other side connects with the handshake of a device (the share id as its device id); instead of a connection to the local `/api/ws`, the host sends `{t:'package', name, size}`, chunks `{t:'chunk', d}` of 192 KB and `{t:'end'}`, then closes the channel, all sealed; the relay keeps nothing, and a package is at most 8 MB. With a share and no device, the host connects to the relay too.
@@ -37,5 +52,17 @@ A Ta service can also hand an extension of its computer to another through the r
37
52
 
38
53
  ## Known Limitations
39
54
 
40
- - When going through Relay, only WebSocket calls work. Local file preview in the Web client (`/api/files`) is not available.
41
- - Device keys are long-term with no forward secrecy: if a key leaks, old traffic in recordings can be decrypted. Unpairing invalidates the key.
55
+ - When going through Relay, only WebSocket calls work: local file preview goes through the channel of `RelayFiles` (above), while other uses of `/api/files` (an address put together for a phone) still do not.
56
+ - Device keys are long-term with no forward secrecy: if a key leaks, old traffic in recordings can be decrypted. Unpairing invalidates the key.
57
+
58
+ ## Content shared (conversations, pages, files)
59
+
60
+ `RelayContentUtil` (common) and the `content` mode of `RelayHost`: links `https://<relay>/s#v=1&h=<host>&s=<share>&k=<key>` (`p=1` asks a password, `m=self` only for its owner and without a key, `o=1` a copy on the relay). The viewer comes with the share as its device id, but **proves first** that it has the key (the host's `ready` has no `proof`), else one with the link could try passwords offline; the host counts wrong keys of each share, refuses it 10 minutes after 10 in 10 minutes, and says a wrong key in the clear (`{t:'refused', reason:'key'}`). Shares are `contents` of `relay.json`, their bytes in `shares/<id>` of the agent directory.
61
+
62
+ "Opens while this computer is off": the host seals the content with a key derived from its own and `PUT /v1/blob/<share>` (`RelayBlobs`; on the Worker a `RelayBlobObject` for each share, deleted by its alarm when it runs out; in memory in `ta relay`). It is read with `x-ta-auth`, derived from the key of the content, of which the relay keeps the SHA-256; 20 wrong ones answer 429.
63
+
64
+ `/s` is the viewer for a browser (`src/viewer/`, built by `scripts/build-viewer.ts` into `viewer/page.html`, its script allowed by its hash), which decrypts on the page; a shared HTML page runs in the sandboxed frame of `/s/frame` (no `allow-same-origin`, no `connect-src`). Design notes: [docs/design/ta-link.md](../../docs/design/ta-link.md).
65
+
66
+ ## Rooms (`/v1/hub/<room>`)
67
+
68
+ Rooms several Ta share ([docs/design/ta-link.md](../../docs/design/ta-link.md), section 3): `RelayHub` keeps on the relay the hashes of the members' tokens, the asks to join till the owner answers, the roster signed by the owner and the shared state, all sealed; it passes messages between members and sets the state on its version. On the Worker each room is a Durable Object (`RelayHubObject`); in `ta relay`, memory. On the side of Ta, `RelayHubs` (its identity in `identity.json`, rooms in `rooms.json`, friends in `friends.json`): making a room, links that invite (`/r#…`, `RelayHubUtil`), asks and the owner's answers (the key of the room sealed by ECDH and signed), and the signatures and sealing of messages and the state. `RelayHubs` is in `common/`, its store its own: `RelayHubFiles` for Ta, localStorage in a browser. A link that invites opens the page of web guests in a browser (`src/guest` → `viewer/room.html`, its script allowed by its hash, connecting to this relay alone): one without Ta asks there and, let in, only chats (`RelayRoomChat`); the Ta of the others take no other state it sets and none of its messages.
package/README.md CHANGED
@@ -24,8 +24,23 @@ ta pair --remove <设备 id> # 取消配对,立即生效
24
24
  - `/v1/connect/<主机 id>`:设备连这里,Relay 给它分一个通道,转给主机(`{t:'open'|'data'|'close', ch, d}`)。
25
25
  - 握手:设备先发 `{t:'hello', v:1, device, nonce}`;主机找到设备的密钥后回 `{t:'ready', nonce, proof}`。两边用 HKDF-SHA-256(设备密钥,盐是两个 nonce)给每个方向各派生一个 AES-256-GCM 密钥,所以每次连接的密钥都不同。`proof` 是主机加密的第一条消息,证明对方有这台设备的密钥;之后每条消息都加密,IV 就是消息序号,Relay 重放、丢弃或调换顺序的消息都会解密失败。
26
26
  - 主机给每台设备单独开一条到本机 `/api/ws` 的连接,带上本机 token。设备拿不到 token,也不需要。
27
+ - 文件(见下节)走设备自己的另一个通道:握手之后,设备的第一条加密消息是 `{t:'files', v:1}`,主机就不开 `/api/ws`,而在这个通道上收 `{t:'get', id, url}`、回 `{t:'head', id, status, type, size}`、若干 `{t:'chunk', id, d}`(每块 192 KB)和 `{t:'end', id}`,出错回 `{t:'error', id, message}`,同样全程加密。
27
28
  - 心跳:主机和设备每 25 秒给 Relay 发一次 `ping`(不经过通道),Relay 自己回 `pong`(Durable Object 不会因此唤醒)。连接可能已经断了却仍显示为打开(经过代理、换了网络、电脑睡眠后常见),所以收不到 `pong` 或电脑睡醒时,主机会重新连 Relay,设备会断开重连(关闭码 4408)。从没回过 `pong` 的旧 Relay 不受影响。Relay 会关掉 80 秒没有心跳的连接。主机重新连上时,Relay 会关掉旧连接上的设备(4404),让它们重新连。设备 15 秒内没收到握手应答,也会断开重试(4408)。
28
29
 
30
+ ## 预览文件
31
+
32
+ 手机上(Ta 应用经 Relay,或浏览器经 Relay)的页面拿不到 `ta serve` 的 `/api/files`:那道地址只在服务本机存在,经 Relay 时只有 WebSocket 上的调用能到。所以设备另开一个通道,请主机把文件的字节读来(`RelayFiles` 在设备一侧、`RelayFilesHost` 在主机一侧):图片、视频、声音、PDF 由页面做成 `blob:` 直接显示,HTML 报告以文件的文本放进沙框的 iframe 里显示。
33
+
34
+ 安全上只放行这一件事:
35
+
36
+ - 只认 `/api/files/` 开头的路径,只发 GET,并且把 URL 解析后再取路径,绝不按设备给的字符串去连别的地址(`RelayFilesHost.target`)。
37
+ - 只连 `127.0.0.1:<ta serve 的端口>`,并且由主机自己写 `Host`,设备碰不到别的端口、别的机器,也碰不到 `/api/*` 的其他接口。
38
+ - 主机发的请求不带 Cookie、不带 Authorization;设备本来就有整台机器的 RPC 权限,这里不扩大它的权力,只是把 `/api/files` 也给它。
39
+ - 一个通道最多同时读 4 个文件,单个文件 128 MB、30 秒为限。
40
+ - 字节仍然端到端加密:Relay 读不到请求,也读不到文件。
41
+
42
+ `web-src` 一侧的扩展用 `pi.files` 判断与读取(`byUrl` 为 false 时用 `pi.files.read(url)`),`@celljs/ta-workspace` 的预览就是这么做的。
43
+
29
44
  ## 分享扩展
30
45
 
31
46
  Ta 服务也能经中继把本机的一个扩展交给另一台电脑(`RelayStore.shareRoot`、`RelayShareUtil`):链接形如 `https://<relay>/share#v=1&h=<主机 id>&s=<分享 id>&k=<密钥>&n=<名字>`,7 天有效。对方用和设备相同的握手连进来(分享 id 当设备 id),主机不接本机的 `/api/ws`,而是发 `{t:'package', name, size}`、若干 `{t:'chunk', d}`(每块 192 KB)和 `{t:'end'}` 后关闭通道,全程加密;中继不存储,包最大 8 MB。只有分享、没有设备时主机也会连中继。
@@ -37,5 +52,17 @@ Ta 服务也能经中继把本机的一个扩展交给另一台电脑(`RelaySt
37
52
 
38
53
  ## 已知限制
39
54
 
40
- - 经 Relay 时,只有 WebSocket 上的调用可用;Web 客户端里本地文件的预览(`/api/files`)用不了。
41
- - 设备密钥是长期的,没有前向保密:密钥泄露后,录下的旧流量也能解开。取消配对即可让它失效。
55
+ - 经 Relay 时只有 WebSocket 上的调用可用:本地文件的预览走 `RelayFiles` 的通道(见上),`/api/files` 的其他用法(比如自己拼一个地址给手机)仍然不行。
56
+ - 设备密钥是长期的,没有前向保密:密钥泄露后,录下的旧流量也能解开。取消配对即可让它失效。
57
+
58
+ ## 分享内容(对话、网页、文件)
59
+
60
+ `RelayContentUtil`(common)与 `RelayHost` 的 `content` 模式:链接 `https://<relay>/s#v=1&h=<主机>&s=<分享>&k=<密钥>`(`p=1` 要口令,`m=self` 仅自己、没有密钥,`o=1` 中继上有副本)。查看方用分享 id 当设备 id 握手,但**由查看方先证明**有密钥(主机的 `ready` 不带 `proof`),否则拿到链接的人能离线猜口令;主机按分享计数,10 分钟内错 10 次暂停 10 分钟,口令错时先发明文 `{t:'refused', reason:'key'}`。内容记在 `relay.json` 的 `contents`,字节在 agent 目录的 `shares/<id>`。
61
+
62
+ "电脑关机也能打开":主机把内容用派生密钥加封后 `PUT /v1/blob/<分享 id>`(`RelayBlobs`,Worker 里是每个分享一个 `RelayBlobObject`,到期由 alarm 删除;`ta relay` 存在内存里)。读要带 `x-ta-auth`(由内容密钥派生,中继只存它的 SHA-256),错 20 次返回 429。
63
+
64
+ `/s` 是浏览器里的查看页(`src/viewer/`,`scripts/build-viewer.ts` 打成 `viewer/page.html`,脚本按哈希放行),在页面里解密后显示;分享的 HTML 放进 `/s/frame` 的沙箱 iframe(无 `allow-same-origin`,禁止 `connect-src`)。设计记录见 [docs/design/ta-link.md](../../docs/design/ta-link.md)。
65
+
66
+ ## 房间(`/v1/hub/<房间>`)
67
+
68
+ 几台 Ta 共用的房间([docs/design/ta-link.md](../../docs/design/ta-link.md) 第 3 节):`RelayHub` 在中继上保存成员令牌的哈希、未处理的加入申请、房主签名的成员名单和共享状态(都是密文),转发成员之间的消息,按版本号写入状态;Worker 上每个房间一个 Durable Object(`RelayHubObject`),`ta relay` 里在内存。Ta 一侧是 `RelayHubs`(身份 `identity.json`、房间 `rooms.json`、好友 `friends.json`):建房、邀请链接(`/r#…`,`RelayHubUtil`)、申请与房主答复(ECDH 加密房间密钥并签名)、消息与状态的签名和加密。`RelayHubs` 在 `common/`,存储可换:Ta 用 `RelayHubFiles`,浏览器用 localStorage。邀请链接在浏览器里打开的是网页访客页(`src/guest` → `viewer/room.html`,脚本按哈希放行,只连本中继):没装 Ta 的人在网页里申请,房主同意后只能聊天(`RelayRoomChat`),其他成员的 Ta 不采用访客写的其他状态和发的消息。
@@ -1,8 +1,18 @@
1
1
  export * from './qr-code.js';
2
+ export * from './relay-blobs.js';
2
3
  export * from './relay-bytes.js';
4
+ export * from './relay-card.js';
3
5
  export * from './relay-cipher.js';
6
+ export * from './relay-content.js';
7
+ export * from './relay-conversation.js';
8
+ export * from './relay-files.js';
9
+ export * from './relay-hub.js';
10
+ export * from './relay-hub-util.js';
11
+ export * from './relay-hubs.js';
12
+ export * from './relay-identity.js';
4
13
  export * from './relay-pairing.js';
5
14
  export * from './relay-protocol.js';
6
15
  export * from './relay-room.js';
16
+ export * from './relay-room-chat.js';
7
17
  export * from './relay-share.js';
8
18
  export * from './relay-socket.js';
@@ -1,9 +1,19 @@
1
1
  export * from './qr-code.js';
2
+ export * from './relay-blobs.js';
2
3
  export * from './relay-bytes.js';
4
+ export * from './relay-card.js';
3
5
  export * from './relay-cipher.js';
6
+ export * from './relay-content.js';
7
+ export * from './relay-conversation.js';
8
+ export * from './relay-files.js';
9
+ export * from './relay-hub.js';
10
+ export * from './relay-hub-util.js';
11
+ export * from './relay-hubs.js';
12
+ export * from './relay-identity.js';
4
13
  export * from './relay-pairing.js';
5
14
  export * from './relay-protocol.js';
6
15
  export * from './relay-room.js';
16
+ export * from './relay-room-chat.js';
7
17
  export * from './relay-share.js';
8
18
  export * from './relay-socket.js';
9
19
  //# sourceMappingURL=index.js.map
@@ -0,0 +1,54 @@
1
+ /** Where a copy is kept: a Durable Object's storage, or a map in `ta relay`. Values are structured-cloned. */
2
+ export interface RelayBlobStorage {
3
+ get<T>(key: string): Promise<T | undefined>;
4
+ put(key: string, value: unknown): Promise<void>;
5
+ deleteAll(): Promise<void>;
6
+ /** When the copy runs out: the storage deletes it then (an alarm), or the relay finds it so on the next request. */
7
+ setAlarm?(at: number): Promise<void>;
8
+ }
9
+ interface BlobMeta {
10
+ /** SHA-256 of the token of the host that wrote it first, who alone writes or deletes it. */
11
+ writeHash: string;
12
+ /** SHA-256 of what reads it (RelayContentUtil.authToken). */
13
+ authHash: string;
14
+ expiresAt: number;
15
+ size: number;
16
+ chunks: number;
17
+ }
18
+ /**
19
+ * One copy of content shared, sealed, on the relay (docs/design/ta-link.md 2.5): the host that shared it puts and
20
+ * deletes it with its token; a viewer reads it with the token of its key. The relay can read neither the copy
21
+ * nor what opens it. Runs the same in a Durable Object (one for each share) and in `ta relay`.
22
+ */
23
+ export declare class RelayBlobs {
24
+ protected readonly storage: RelayBlobStorage;
25
+ protected readonly now: () => number;
26
+ /** The bytes of a copy at most, sealed. */
27
+ static readonly MAX_BYTES: number;
28
+ constructor(storage: RelayBlobStorage, now?: () => number);
29
+ handle(request: Request): Promise<Response>;
30
+ protected read(request: Request): Promise<Response>;
31
+ protected write(request: Request): Promise<Response>;
32
+ protected remove(request: Request): Promise<Response>;
33
+ /** The copy while it lasts; past its time it is deleted, should the alarm not have run. */
34
+ protected meta(): Promise<BlobMeta | undefined>;
35
+ protected static bearer(request: Request): string;
36
+ protected static hash(text: string): Promise<string>;
37
+ protected static answer(status: number, text: string, headers?: Record<string, string>): Response;
38
+ }
39
+ /** What the host that shared content does with its copy on the relay. */
40
+ export declare namespace RelayBlobClient {
41
+ interface Copy {
42
+ relay: string;
43
+ share: string;
44
+ /** The host's token of the copy. */
45
+ token: string;
46
+ /** SHA-256 of the token that reads it. */
47
+ authHash: string;
48
+ expiresAt: number;
49
+ bytes: Uint8Array;
50
+ }
51
+ function put(copy: Copy): Promise<void>;
52
+ function remove(relay: string, share: string, token: string): Promise<void>;
53
+ }
54
+ export {};
@@ -0,0 +1,153 @@
1
+ import { RelayBytes } from './relay-bytes.js';
2
+ import { RELAY_BLOB_MAX_DAYS, RELAY_BLOB_PATH, RELAY_CONTENT_MAX_BYTES } from './relay-protocol.js';
3
+ /** Below the 2 MiB of a value of a Durable Object. */
4
+ const CHUNK_BYTES = 1024 * 1024;
5
+ /** The sealing adds an IV, a tag and the header of the content. */
6
+ const MAX_BYTES = RELAY_CONTENT_MAX_BYTES + 64 * 1024;
7
+ const FAIL_WINDOW_MS = 10 * 60 * 1000;
8
+ const MAX_FAILS = 20;
9
+ const DAY_MS = 24 * 60 * 60 * 1000;
10
+ const READ_HEADERS = { 'access-control-allow-origin': '*', 'access-control-allow-headers': 'x-ta-auth', 'access-control-allow-methods': 'GET, OPTIONS' };
11
+ /**
12
+ * One copy of content shared, sealed, on the relay (docs/design/ta-link.md 2.5): the host that shared it puts and
13
+ * deletes it with its token; a viewer reads it with the token of its key. The relay can read neither the copy
14
+ * nor what opens it. Runs the same in a Durable Object (one for each share) and in `ta relay`.
15
+ */
16
+ export class RelayBlobs {
17
+ constructor(storage, now = Date.now) {
18
+ this.storage = storage;
19
+ this.now = now;
20
+ }
21
+ async handle(request) {
22
+ switch (request.method) {
23
+ case 'OPTIONS':
24
+ return new Response(null, { status: 204, headers: READ_HEADERS });
25
+ case 'GET':
26
+ return this.read(request);
27
+ case 'PUT':
28
+ return this.write(request);
29
+ case 'DELETE':
30
+ return this.remove(request);
31
+ default:
32
+ return RelayBlobs.answer(405, 'Not allowed.');
33
+ }
34
+ }
35
+ async read(request) {
36
+ var _a, _b;
37
+ const meta = await this.meta();
38
+ if (!meta) {
39
+ return RelayBlobs.answer(404, 'No copy.', READ_HEADERS);
40
+ }
41
+ const fails = (_a = (await this.storage.get('fails'))) !== null && _a !== void 0 ? _a : { count: 0, since: 0 };
42
+ const now = this.now();
43
+ const recent = now - fails.since < FAIL_WINDOW_MS ? fails : { count: 0, since: now };
44
+ if (recent.count >= MAX_FAILS) {
45
+ return RelayBlobs.answer(429, 'Too many tries.', READ_HEADERS);
46
+ }
47
+ if ((await RelayBlobs.hash((_b = request.headers.get('x-ta-auth')) !== null && _b !== void 0 ? _b : '')) !== meta.authHash) {
48
+ await this.storage.put('fails', { count: recent.count + 1, since: recent.since });
49
+ return RelayBlobs.answer(403, 'Refused.', READ_HEADERS);
50
+ }
51
+ const parts = [];
52
+ for (let index = 0; index < meta.chunks; index++) {
53
+ const part = await this.storage.get(`c${index}`);
54
+ if (!part) {
55
+ return RelayBlobs.answer(404, 'No copy.', READ_HEADERS);
56
+ }
57
+ parts.push(new Uint8Array(part));
58
+ }
59
+ return new Response(RelayBytes.concat(...parts), {
60
+ headers: { ...READ_HEADERS, 'content-type': 'application/octet-stream', 'cache-control': 'no-store' },
61
+ });
62
+ }
63
+ async write(request) {
64
+ var _a, _b;
65
+ var _c;
66
+ const writeHash = await RelayBlobs.hash(RelayBlobs.bearer(request));
67
+ const before = await this.storage.get('meta');
68
+ if (before && before.writeHash !== writeHash && before.expiresAt > this.now()) {
69
+ return RelayBlobs.answer(403, 'Another host keeps this copy.');
70
+ }
71
+ const authHash = (_c = request.headers.get('x-ta-auth-hash')) !== null && _c !== void 0 ? _c : '';
72
+ const expiresAt = Number(request.headers.get('x-ta-expires'));
73
+ const now = this.now();
74
+ if (RelayBlobs.bearer(request).length < 32 ||
75
+ !/^[A-Za-z0-9_-]{43}$/.test(authHash) ||
76
+ !(expiresAt > now) ||
77
+ expiresAt > now + RELAY_BLOB_MAX_DAYS * DAY_MS + DAY_MS) {
78
+ return RelayBlobs.answer(400, 'A token, the hash of what reads it and when it runs out are needed.');
79
+ }
80
+ const length = Number(request.headers.get('content-length'));
81
+ if (length > MAX_BYTES) {
82
+ return RelayBlobs.answer(413, 'Too large.');
83
+ }
84
+ const bytes = new Uint8Array(await request.arrayBuffer());
85
+ if (bytes.length === 0 || bytes.length > MAX_BYTES) {
86
+ return RelayBlobs.answer(bytes.length === 0 ? 400 : 413, bytes.length === 0 ? 'Empty.' : 'Too large.');
87
+ }
88
+ await this.storage.deleteAll();
89
+ const chunks = Math.ceil(bytes.length / CHUNK_BYTES);
90
+ for (let index = 0; index < chunks; index++) {
91
+ await this.storage.put(`c${index}`, bytes.slice(index * CHUNK_BYTES, (index + 1) * CHUNK_BYTES));
92
+ }
93
+ await this.storage.put('meta', { writeHash, authHash, expiresAt, size: bytes.length, chunks });
94
+ await ((_b = (_a = this.storage).setAlarm) === null || _b === void 0 ? void 0 : _b.call(_a, expiresAt));
95
+ return RelayBlobs.answer(201, 'Kept.');
96
+ }
97
+ async remove(request) {
98
+ const meta = await this.storage.get('meta');
99
+ if (meta && meta.writeHash !== (await RelayBlobs.hash(RelayBlobs.bearer(request)))) {
100
+ return RelayBlobs.answer(403, 'Refused.');
101
+ }
102
+ await this.storage.deleteAll();
103
+ return RelayBlobs.answer(200, 'Deleted.');
104
+ }
105
+ /** The copy while it lasts; past its time it is deleted, should the alarm not have run. */
106
+ async meta() {
107
+ const meta = await this.storage.get('meta');
108
+ if (meta && meta.expiresAt <= this.now()) {
109
+ await this.storage.deleteAll();
110
+ return undefined;
111
+ }
112
+ return meta;
113
+ }
114
+ static bearer(request) {
115
+ var _a;
116
+ var _b, _c;
117
+ return (_c = (_a = /^Bearer (\S+)$/.exec((_b = request.headers.get('authorization')) !== null && _b !== void 0 ? _b : '')) === null || _a === void 0 ? void 0 : _a[1]) !== null && _c !== void 0 ? _c : '';
118
+ }
119
+ static async hash(text) {
120
+ const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
121
+ return RelayBytes.toBase64(new Uint8Array(digest));
122
+ }
123
+ static answer(status, text, headers = {}) {
124
+ return new Response(`${text}\n`, { status, headers: { ...headers, 'content-type': 'text/plain; charset=utf-8' } });
125
+ }
126
+ }
127
+ /** The bytes of a copy at most, sealed. */
128
+ RelayBlobs.MAX_BYTES = MAX_BYTES;
129
+ /** What the host that shared content does with its copy on the relay. */
130
+ export var RelayBlobClient;
131
+ (function (RelayBlobClient) {
132
+ async function put(copy) {
133
+ const response = await fetch(`${copy.relay}${RELAY_BLOB_PATH}${copy.share}`, {
134
+ method: 'PUT',
135
+ headers: {
136
+ authorization: `Bearer ${copy.token}`,
137
+ 'x-ta-auth-hash': copy.authHash,
138
+ 'x-ta-expires': String(copy.expiresAt),
139
+ 'content-type': 'application/octet-stream',
140
+ },
141
+ body: copy.bytes,
142
+ });
143
+ if (!response.ok) {
144
+ throw new Error(`The relay did not keep the copy: ${response.status} ${(await response.text()).trim()}`);
145
+ }
146
+ }
147
+ RelayBlobClient.put = put;
148
+ async function remove(relay, share, token) {
149
+ await fetch(`${relay}${RELAY_BLOB_PATH}${share}`, { method: 'DELETE', headers: { authorization: `Bearer ${token}` } });
150
+ }
151
+ RelayBlobClient.remove = remove;
152
+ })(RelayBlobClient || (RelayBlobClient = {}));
153
+ //# sourceMappingURL=relay-blobs.js.map
@@ -0,0 +1,23 @@
1
+ /** The kind of an agent's card shared by a link (docs/design/ta-social.md): JSON of {@link RelayAgentCard}. */
2
+ export declare const RELAY_AGENT_KIND = "ta-agent";
3
+ /**
4
+ * An agent of Ta as its card shares it: who it is and its role, what its secrets taken out (Redactor), not where it
5
+ * works nor what it said. The Ta that adds it fits the role to the project it is added for.
6
+ */
7
+ export interface RelayAgentCard {
8
+ v: 1;
9
+ name: string;
10
+ role: string;
11
+ /** One or two characters on its avatar. */
12
+ mark: string;
13
+ /** Which of the faces of ta-channels it has. */
14
+ face?: number;
15
+ /** The colour of its face, for a page that does not draw the faces (the viewer of the relay). */
16
+ color?: string;
17
+ /** How many places of the role were hidden as secrets. */
18
+ redacted?: number;
19
+ }
20
+ export declare namespace RelayAgentCards {
21
+ /** A card read from what a link shares; undefined for what is none. */
22
+ function parse(data: Uint8Array | string): RelayAgentCard | undefined;
23
+ }
@@ -0,0 +1,30 @@
1
+ /** The kind of an agent's card shared by a link (docs/design/ta-social.md): JSON of {@link RelayAgentCard}. */
2
+ export const RELAY_AGENT_KIND = 'ta-agent';
3
+ export var RelayAgentCards;
4
+ (function (RelayAgentCards) {
5
+ const MAX_ROLE = 8000;
6
+ /** A card read from what a link shares; undefined for what is none. */
7
+ function parse(data) {
8
+ try {
9
+ const card = JSON.parse(typeof data === 'string' ? data : new TextDecoder().decode(data));
10
+ if ((card === null || card === void 0 ? void 0 : card.v) !== 1 || typeof card.name !== 'string' || !card.name.trim() || typeof card.role !== 'string' || !card.role.trim()) {
11
+ return undefined;
12
+ }
13
+ const color = typeof card.color === 'string' && /^#[0-9a-fA-F]{6}$/.test(card.color) ? card.color : undefined;
14
+ return {
15
+ v: 1,
16
+ name: card.name.trim().slice(0, 32),
17
+ role: card.role.trim().slice(0, MAX_ROLE),
18
+ mark: typeof card.mark === 'string' && card.mark.trim() ? card.mark.trim().slice(0, 2) : card.name.trim().slice(0, 1).toUpperCase(),
19
+ ...(Number.isInteger(card.face) ? { face: card.face } : {}),
20
+ ...(color ? { color } : {}),
21
+ ...(typeof card.redacted === 'number' && card.redacted > 0 ? { redacted: card.redacted } : {}),
22
+ };
23
+ }
24
+ catch (_a) {
25
+ return undefined;
26
+ }
27
+ }
28
+ RelayAgentCards.parse = parse;
29
+ })(RelayAgentCards || (RelayAgentCards = {}));
30
+ //# sourceMappingURL=relay-card.js.map
@@ -4,10 +4,16 @@ export type RelaySide = 'client' | 'host';
4
4
  * each direction, derived (HKDF-SHA-256) from the device's key and a nonce of each side, so that every
5
5
  * connection has keys of its own. The IV is the number of the message, which must arrive in order: a
6
6
  * message replayed, dropped or reordered by the relay fails to open.
7
+ *
8
+ * Encrypted bytes do not compress, so a message is compressed before it is sealed, once both sides said
9
+ * they can (`RelayHello.z`, `RelayWelcome.z`, then `compress`): JSON shrinks to a third or less, which
10
+ * is what a phone on a slow network waits for.
7
11
  */
8
12
  export declare class RelayCipher {
9
13
  protected readonly sendKey: CryptoKey;
10
14
  protected readonly receiveKey: CryptoKey;
15
+ /** Messages sealed from now are compressed when large, and those opened may be: both sides set it at the same message. */
16
+ compress: boolean;
11
17
  protected sent: number;
12
18
  protected received: number;
13
19
  protected sealing: Promise<unknown>;
@@ -18,5 +24,14 @@ export declare class RelayCipher {
18
24
  seal(text: string): Promise<string>;
19
25
  /** Rejects what this side's peer did not seal, or not as the next message. */
20
26
  open(frame: string): Promise<string>;
27
+ /** The bytes of a message to seal: as they are until compression is agreed, then behind the byte that says how. */
28
+ protected pack(text: string): Promise<Uint8Array>;
29
+ protected unpack(bytes: Uint8Array): Promise<string>;
21
30
  protected static iv(counter: number): Uint8Array;
22
31
  }
32
+ /** deflate-raw of the platform (CompressionStream), where it has it: browsers, Node.js 21.2 and later, Bun, Deno. */
33
+ export declare namespace RelayDeflate {
34
+ function supported(): boolean;
35
+ function compress(bytes: Uint8Array): Promise<Uint8Array>;
36
+ function decompress(bytes: Uint8Array): Promise<Uint8Array>;
37
+ }
@@ -2,16 +2,27 @@ import { RelayBytes } from './relay-bytes.js';
2
2
  const encoder = new TextEncoder();
3
3
  const decoder = new TextDecoder();
4
4
  const IV_LENGTH = 12;
5
+ /** The first byte of a message once compression is agreed: what follows. */
6
+ const PLAIN = 0;
7
+ const DEFLATED = 1;
8
+ /** Smaller messages go as they are: they are about as small compressed. */
9
+ const DEFLATE_MIN_BYTES = 1024;
5
10
  /**
6
11
  * The encryption of one connection between a paired device and ta serve: AES-256-GCM with a key for
7
12
  * each direction, derived (HKDF-SHA-256) from the device's key and a nonce of each side, so that every
8
13
  * connection has keys of its own. The IV is the number of the message, which must arrive in order: a
9
14
  * message replayed, dropped or reordered by the relay fails to open.
15
+ *
16
+ * Encrypted bytes do not compress, so a message is compressed before it is sealed, once both sides said
17
+ * they can (`RelayHello.z`, `RelayWelcome.z`, then `compress`): JSON shrinks to a third or less, which
18
+ * is what a phone on a slow network waits for.
10
19
  */
11
20
  export class RelayCipher {
12
21
  constructor(sendKey, receiveKey) {
13
22
  this.sendKey = sendKey;
14
23
  this.receiveKey = receiveKey;
24
+ /** Messages sealed from now are compressed when large, and those opened may be: both sides set it at the same message. */
25
+ this.compress = false;
15
26
  this.sent = 0;
16
27
  this.received = 0;
17
28
  this.sealing = Promise.resolve();
@@ -29,7 +40,7 @@ export class RelayCipher {
29
40
  seal(text) {
30
41
  const iv = RelayCipher.iv(this.sent++);
31
42
  const sealed = this.sealing.then(async () => {
32
- const data = await globalThis.crypto.subtle.encrypt({ name: 'AES-GCM', iv: iv }, this.sendKey, encoder.encode(text));
43
+ const data = await globalThis.crypto.subtle.encrypt({ name: 'AES-GCM', iv: iv }, this.sendKey, (await this.pack(text)));
33
44
  return RelayBytes.toBase64(new Uint8Array(data));
34
45
  });
35
46
  this.sealing = sealed.catch(() => undefined);
@@ -40,11 +51,29 @@ export class RelayCipher {
40
51
  const iv = RelayCipher.iv(this.received++);
41
52
  const opened = this.opening.then(async () => {
42
53
  const data = await globalThis.crypto.subtle.decrypt({ name: 'AES-GCM', iv: iv }, this.receiveKey, RelayBytes.fromBase64(frame));
43
- return decoder.decode(data);
54
+ return this.unpack(new Uint8Array(data));
44
55
  });
45
56
  this.opening = opened.catch(() => undefined);
46
57
  return opened;
47
58
  }
59
+ /** The bytes of a message to seal: as they are until compression is agreed, then behind the byte that says how. */
60
+ async pack(text) {
61
+ const bytes = encoder.encode(text);
62
+ if (!this.compress) {
63
+ return bytes;
64
+ }
65
+ const deflated = bytes.length >= DEFLATE_MIN_BYTES ? await RelayDeflate.compress(bytes) : undefined;
66
+ return deflated && deflated.length < bytes.length
67
+ ? RelayBytes.concat(Uint8Array.of(DEFLATED), deflated)
68
+ : RelayBytes.concat(Uint8Array.of(PLAIN), bytes);
69
+ }
70
+ async unpack(bytes) {
71
+ if (!this.compress) {
72
+ return decoder.decode(bytes);
73
+ }
74
+ const body = bytes.subarray(1);
75
+ return decoder.decode(bytes[0] === DEFLATED ? await RelayDeflate.decompress(body) : body);
76
+ }
48
77
  static iv(counter) {
49
78
  const iv = new Uint8Array(IV_LENGTH);
50
79
  new DataView(iv.buffer).setUint32(IV_LENGTH - 8, Math.floor(counter / 2 ** 32));
@@ -52,4 +81,35 @@ export class RelayCipher {
52
81
  return iv;
53
82
  }
54
83
  }
84
+ /** deflate-raw of the platform (CompressionStream), where it has it: browsers, Node.js 21.2 and later, Bun, Deno. */
85
+ export var RelayDeflate;
86
+ (function (RelayDeflate) {
87
+ let support;
88
+ function supported() {
89
+ if (support === undefined) {
90
+ try {
91
+ new CompressionStream('deflate-raw');
92
+ new DecompressionStream('deflate-raw');
93
+ support = true;
94
+ }
95
+ catch (_a) {
96
+ support = false;
97
+ }
98
+ }
99
+ return support;
100
+ }
101
+ RelayDeflate.supported = supported;
102
+ function compress(bytes) {
103
+ return through(bytes, new CompressionStream('deflate-raw'));
104
+ }
105
+ RelayDeflate.compress = compress;
106
+ function decompress(bytes) {
107
+ return through(bytes, new DecompressionStream('deflate-raw'));
108
+ }
109
+ RelayDeflate.decompress = decompress;
110
+ async function through(bytes, stream) {
111
+ const piped = new Blob([bytes]).stream().pipeThrough(stream);
112
+ return new Uint8Array(await new Response(piped).arrayBuffer());
113
+ }
114
+ })(RelayDeflate || (RelayDeflate = {}));
55
115
  //# sourceMappingURL=relay-cipher.js.map
@@ -0,0 +1,104 @@
1
+ import { type RelayIdentity } from './relay-identity.js';
2
+ /**
3
+ * Who may open a link of content: anyone with it, anyone with it and its password, the one who shared it, or Ta friends
4
+ * the one who shared it chose (`people`), in their own Ta (docs/design/ta-link.md 3.6).
5
+ */
6
+ export type RelayContentAccess = 'link' | 'password' | 'self' | 'people';
7
+ /** What a link of content shared names. The key is in the fragment, which a browser does not send. */
8
+ export interface RelayContentLink {
9
+ relay: string;
10
+ host: string;
11
+ /** The id of the share, as a device's on the relay. */
12
+ share: string;
13
+ /** base64url, 32 bytes; none for `self` and `people`. */
14
+ key?: string;
15
+ access: RelayContentAccess;
16
+ /** For `people`: the identity of the one who shared it, whose key the key of a friend is agreed with. */
17
+ owner?: string;
18
+ /** A copy is kept on the relay, sealed: it opens while the computer that shared it is off. */
19
+ offline?: boolean;
20
+ /**
21
+ * What it shares, in the link (`c`) for kinds other than a conversation or a file (an agent's card), so that the
22
+ * package that opens it claims the link before it is fetched. Not secret.
23
+ */
24
+ kind?: string;
25
+ }
26
+ /** What is shared: a conversation (`ta-conversation`, JSON), a file or a page (its bytes). */
27
+ export interface RelayContentHeader {
28
+ kind: string;
29
+ title: string;
30
+ createdAt: number;
31
+ /** The media type of a file. */
32
+ type?: string;
33
+ }
34
+ export interface RelayContentItem extends RelayContentHeader {
35
+ data: Uint8Array;
36
+ }
37
+ export type RelayContentFailure =
38
+ /** A password is needed, or the one given is wrong (`wrong`). */
39
+ 'password' | 'wrong'
40
+ /** Too many wrong passwords of late: try again later. */
41
+ | 'busy'
42
+ /** Stopped, or past its time. */
43
+ | 'gone'
44
+ /** The computer that shared it does not run Ta now, and there is no copy on the relay. */
45
+ | 'offline'
46
+ /** Only the one who shared it opens it, in their own Ta. */
47
+ | 'self'
48
+ /** Only the Ta friends it was shared with open it, in their own Ta. */
49
+ | 'people' | 'invalid' | 'timeout' | 'large';
50
+ export declare class RelayContentError extends Error {
51
+ readonly reason: RelayContentFailure;
52
+ constructor(reason: RelayContentFailure, message: string);
53
+ }
54
+ export interface RelayContentFetchOptions {
55
+ password?: string;
56
+ /** For `people`: this Ta, and the key the one who shared it agrees keys with (of its friends). */
57
+ people?: {
58
+ identity: RelayIdentity;
59
+ ownerBox: string;
60
+ };
61
+ maxBytes?: number;
62
+ /** For all of it. Default 60 seconds. */
63
+ timeoutMs?: number;
64
+ }
65
+ /**
66
+ * Content shared by a link (docs/design/ta-link.md): its link, its keys, and how it is fetched, from the
67
+ * computer that shared it through the relay, or from the copy the relay keeps sealed. Runs the same in a
68
+ * browser (the viewer of the relay), in ta serve and in a Worker: WebCrypto, fetch and WebSocket only.
69
+ */
70
+ export declare namespace RelayContentUtil {
71
+ /**
72
+ * `https://<relay>/s#v=1&h=<host>&s=<share>&k=<key>`, with `p=1` for a password, `m=self`, `o=1` for a copy on the relay,
73
+ * `c=<kind>` for what is no conversation or file.
74
+ */
75
+ function link(content: RelayContentLink): string;
76
+ function is(text: string): boolean;
77
+ /** Throws on what is not a link of {@link link}. */
78
+ function parse(text: string): RelayContentLink;
79
+ /**
80
+ * The key the content is sealed with: the key of the link, or with a password, one derived from both
81
+ * (PBKDF2 of the password, then HKDF with the key of the link), so that neither alone opens it.
82
+ */
83
+ function contentKey(linkKey: Uint8Array, share: string, password?: string): Promise<Uint8Array>;
84
+ /**
85
+ * The key of content shared with a Ta friend (`people`): only the two make it, each with its own private key and the
86
+ * other's public one, for this share alone.
87
+ */
88
+ function peopleKey(identity: RelayIdentity, otherBox: string, share: string): Promise<Uint8Array>;
89
+ /** What reads the copy on the relay, which keeps only its SHA-256 (`x-ta-auth`). */
90
+ function authToken(key: Uint8Array): Promise<string>;
91
+ function sha256(text: string): Promise<string>;
92
+ /** The bytes of the copy on the relay: a random IV, then AES-256-GCM of {@link encode}. */
93
+ function seal(key: Uint8Array, item: RelayContentItem): Promise<Uint8Array>;
94
+ /** Throws when it was not sealed with this key. */
95
+ function open(key: Uint8Array, bytes: Uint8Array): Promise<RelayContentItem>;
96
+ /** The header as JSON behind its length (4 bytes), then the data. */
97
+ function encode(item: RelayContentItem): Uint8Array;
98
+ function decode(bytes: Uint8Array): RelayContentItem;
99
+ /**
100
+ * What a link shares: from the copy on the relay when it has one, else from the computer that shared it,
101
+ * end to end through the relay. Rejects with a RelayContentError that says why it cannot.
102
+ */
103
+ function fetch(text: string | RelayContentLink, options?: RelayContentFetchOptions): Promise<RelayContentItem>;
104
+ }