@minca/core 0.1.10 → 0.1.12

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 (229) hide show
  1. package/README.md +1 -1
  2. package/dist/identity/abilities.js +1 -1
  3. package/dist/identity/channel.d.ts +1 -1
  4. package/dist/identity/channel.d.ts.map +1 -1
  5. package/dist/identity/channel.js +1 -1
  6. package/dist/identity/channel.js.map +1 -1
  7. package/dist/identity/contact-key.d.ts +15 -15
  8. package/dist/identity/contact-key.d.ts.map +1 -1
  9. package/dist/identity/contact-key.js +21 -28
  10. package/dist/identity/contact-key.js.map +1 -1
  11. package/dist/inbox/inbox.d.ts +132 -0
  12. package/dist/inbox/inbox.d.ts.map +1 -0
  13. package/dist/inbox/inbox.js +197 -0
  14. package/dist/inbox/inbox.js.map +1 -0
  15. package/dist/inbox/index.d.ts +9 -0
  16. package/dist/inbox/index.d.ts.map +1 -0
  17. package/dist/inbox/index.js +7 -0
  18. package/dist/inbox/index.js.map +1 -0
  19. package/dist/index.d.ts +8 -6
  20. package/dist/index.d.ts.map +1 -1
  21. package/dist/index.js +3 -3
  22. package/dist/index.js.map +1 -1
  23. package/dist/network/introductions.d.ts +1 -1
  24. package/dist/network/introductions.d.ts.map +1 -1
  25. package/dist/network/mesh.d.ts +4 -2
  26. package/dist/network/mesh.d.ts.map +1 -1
  27. package/dist/network/mesh.js +31 -45
  28. package/dist/network/mesh.js.map +1 -1
  29. package/dist/network/peer-auth.d.ts +4 -0
  30. package/dist/network/peer-auth.d.ts.map +1 -1
  31. package/dist/network/peer-auth.js +9 -7
  32. package/dist/network/peer-auth.js.map +1 -1
  33. package/dist/network/relay-minca.d.ts +6 -0
  34. package/dist/network/relay-minca.d.ts.map +1 -0
  35. package/dist/network/relay-minca.js +146 -0
  36. package/dist/network/relay-minca.js.map +1 -0
  37. package/dist/network/relay-nostr.d.ts +10 -0
  38. package/dist/network/relay-nostr.d.ts.map +1 -0
  39. package/dist/network/relay-nostr.js +247 -0
  40. package/dist/network/relay-nostr.js.map +1 -0
  41. package/dist/network/relay-socket.d.ts +87 -0
  42. package/dist/network/relay-socket.d.ts.map +1 -0
  43. package/dist/network/{signaling.js → relay-socket.js} +201 -167
  44. package/dist/network/relay-socket.js.map +1 -0
  45. package/dist/network/relays.d.ts +87 -0
  46. package/dist/network/relays.d.ts.map +1 -0
  47. package/dist/network/relays.js +43 -0
  48. package/dist/network/relays.js.map +1 -0
  49. package/dist/network/remote-transport.d.ts +1 -1
  50. package/dist/network/remote-transport.d.ts.map +1 -1
  51. package/dist/network/remote-transport.js +6 -31
  52. package/dist/network/remote-transport.js.map +1 -1
  53. package/dist/network/rendezvous.d.ts +59 -0
  54. package/dist/network/rendezvous.d.ts.map +1 -0
  55. package/dist/network/rendezvous.js +380 -0
  56. package/dist/network/rendezvous.js.map +1 -0
  57. package/dist/network/rtc-transport.d.ts.map +1 -1
  58. package/dist/network/rtc-transport.js +32 -17
  59. package/dist/network/rtc-transport.js.map +1 -1
  60. package/dist/network/transport.d.ts +7 -5
  61. package/dist/network/transport.d.ts.map +1 -1
  62. package/dist/node/actions.d.ts.map +1 -1
  63. package/dist/node/actions.js +28 -18
  64. package/dist/node/actions.js.map +1 -1
  65. package/dist/node/api.d.ts +11 -10
  66. package/dist/node/api.d.ts.map +1 -1
  67. package/dist/node/api.js +11 -10
  68. package/dist/node/api.js.map +1 -1
  69. package/dist/node/carrier.d.ts +11 -5
  70. package/dist/node/carrier.d.ts.map +1 -1
  71. package/dist/node/carrier.js +43 -2
  72. package/dist/node/carrier.js.map +1 -1
  73. package/dist/node/copy.d.ts +1 -1
  74. package/dist/node/copy.d.ts.map +1 -1
  75. package/dist/node/copy.js +10 -4
  76. package/dist/node/copy.js.map +1 -1
  77. package/dist/node/host.d.ts +2 -0
  78. package/dist/node/host.d.ts.map +1 -1
  79. package/dist/node/host.js +2 -0
  80. package/dist/node/host.js.map +1 -1
  81. package/dist/node/index.d.ts +1 -1
  82. package/dist/node/index.d.ts.map +1 -1
  83. package/dist/node/node.d.ts.map +1 -1
  84. package/dist/node/node.js +490 -298
  85. package/dist/node/node.js.map +1 -1
  86. package/dist/node/remote.d.ts.map +1 -1
  87. package/dist/node/remote.js +0 -2
  88. package/dist/node/remote.js.map +1 -1
  89. package/dist/node/space-runtime.d.ts +6 -2
  90. package/dist/node/space-runtime.d.ts.map +1 -1
  91. package/dist/node/space-runtime.js +5 -8
  92. package/dist/node/space-runtime.js.map +1 -1
  93. package/dist/node/types.d.ts +75 -46
  94. package/dist/node/types.d.ts.map +1 -1
  95. package/dist/react/use-invite-link.d.ts +1 -1
  96. package/dist/react/use-invite-link.d.ts.map +1 -1
  97. package/dist/react/use-invite-link.js +18 -11
  98. package/dist/react/use-invite-link.js.map +1 -1
  99. package/dist/records/loose.d.ts +52 -0
  100. package/dist/records/loose.d.ts.map +1 -0
  101. package/dist/records/loose.js +86 -0
  102. package/dist/records/loose.js.map +1 -0
  103. package/dist/schema/version.d.ts +2 -0
  104. package/dist/schema/version.d.ts.map +1 -1
  105. package/dist/schema/version.js +2 -1
  106. package/dist/schema/version.js.map +1 -1
  107. package/dist/schemas/choosing.d.ts +19 -0
  108. package/dist/schemas/choosing.d.ts.map +1 -0
  109. package/dist/schemas/choosing.js +69 -0
  110. package/dist/schemas/choosing.js.map +1 -0
  111. package/dist/schemas/contacts.d.ts +34 -87
  112. package/dist/schemas/contacts.d.ts.map +1 -1
  113. package/dist/schemas/contacts.js +32 -76
  114. package/dist/schemas/contacts.js.map +1 -1
  115. package/dist/schemas/index.d.ts +2 -2
  116. package/dist/schemas/index.d.ts.map +1 -1
  117. package/dist/schemas/index.js +1 -1
  118. package/dist/schemas/index.js.map +1 -1
  119. package/dist/schemas/library/annotations.d.ts +17 -285
  120. package/dist/schemas/library/annotations.d.ts.map +1 -1
  121. package/dist/schemas/library/annotations.js +9 -65
  122. package/dist/schemas/library/annotations.js.map +1 -1
  123. package/dist/schemas/library/community.d.ts +9 -17
  124. package/dist/schemas/library/community.d.ts.map +1 -1
  125. package/dist/schemas/library/community.js +5 -5
  126. package/dist/schemas/library/community.js.map +1 -1
  127. package/dist/schemas/library/life.d.ts +3 -3
  128. package/dist/schemas/library/life.d.ts.map +1 -1
  129. package/dist/schemas/library/life.js +2 -2
  130. package/dist/schemas/library/life.js.map +1 -1
  131. package/dist/schemas/library/media.d.ts +148 -541
  132. package/dist/schemas/library/media.d.ts.map +1 -1
  133. package/dist/schemas/library/media.js +28 -64
  134. package/dist/schemas/library/media.js.map +1 -1
  135. package/dist/schemas/library/money.d.ts +8 -8
  136. package/dist/schemas/library/money.d.ts.map +1 -1
  137. package/dist/schemas/library/money.js +4 -4
  138. package/dist/schemas/library/money.js.map +1 -1
  139. package/dist/schemas/library/planning.d.ts +23 -87
  140. package/dist/schemas/library/planning.d.ts.map +1 -1
  141. package/dist/schemas/library/planning.js +10 -26
  142. package/dist/schemas/library/planning.js.map +1 -1
  143. package/dist/schemas/library/publishing.d.ts +14 -14
  144. package/dist/schemas/library/publishing.d.ts.map +1 -1
  145. package/dist/schemas/library/publishing.js +7 -7
  146. package/dist/schemas/library/publishing.js.map +1 -1
  147. package/dist/schemas/library/social.d.ts +2 -2
  148. package/dist/schemas/library/social.d.ts.map +1 -1
  149. package/dist/schemas/library/social.js +1 -1
  150. package/dist/schemas/library/social.js.map +1 -1
  151. package/dist/schemas/standard.d.ts +1 -1
  152. package/dist/schemas/standard.d.ts.map +1 -1
  153. package/dist/schemas/standard.js +3 -3
  154. package/dist/schemas/standard.js.map +1 -1
  155. package/dist/session/auth.d.ts +5 -6
  156. package/dist/session/auth.d.ts.map +1 -1
  157. package/dist/session/auth.js +5 -6
  158. package/dist/session/auth.js.map +1 -1
  159. package/dist/session/channel-room.d.ts.map +1 -1
  160. package/dist/session/channel-room.js +3 -2
  161. package/dist/session/channel-room.js.map +1 -1
  162. package/dist/session/connect-code.d.ts +69 -55
  163. package/dist/session/connect-code.d.ts.map +1 -1
  164. package/dist/session/connect-code.js +189 -89
  165. package/dist/session/connect-code.js.map +1 -1
  166. package/dist/session/connect.d.ts +11 -15
  167. package/dist/session/connect.d.ts.map +1 -1
  168. package/dist/session/connect.js +8 -21
  169. package/dist/session/connect.js.map +1 -1
  170. package/dist/session/index.d.ts +2 -2
  171. package/dist/session/index.d.ts.map +1 -1
  172. package/dist/session/index.js +1 -1
  173. package/dist/session/index.js.map +1 -1
  174. package/dist/space/account-registry.d.ts +22 -0
  175. package/dist/space/account-registry.d.ts.map +1 -1
  176. package/dist/space/account-registry.js +18 -0
  177. package/dist/space/account-registry.js.map +1 -1
  178. package/dist/space/invitation.d.ts +61 -0
  179. package/dist/space/invitation.d.ts.map +1 -0
  180. package/dist/space/invitation.js +84 -0
  181. package/dist/space/invitation.js.map +1 -0
  182. package/dist/space/invite-link.d.ts +64 -0
  183. package/dist/space/invite-link.d.ts.map +1 -0
  184. package/dist/space/invite-link.js +212 -0
  185. package/dist/space/invite-link.js.map +1 -0
  186. package/dist/space/roles.d.ts.map +1 -1
  187. package/dist/space/roles.js +4 -2
  188. package/dist/space/roles.js.map +1 -1
  189. package/dist/space/space-manager.d.ts +21 -6
  190. package/dist/space/space-manager.d.ts.map +1 -1
  191. package/dist/space/space-manager.js +40 -23
  192. package/dist/space/space-manager.js.map +1 -1
  193. package/dist/types.d.ts +2 -0
  194. package/dist/types.d.ts.map +1 -1
  195. package/dist/types.js.map +1 -1
  196. package/docs/README.md +2 -2
  197. package/docs/actions.md +37 -37
  198. package/docs/agents.md +59 -37
  199. package/docs/automations.md +2 -2
  200. package/docs/blueprints-and-guides.md +44 -3
  201. package/docs/building-an-app.md +2 -2
  202. package/docs/contacts.md +48 -69
  203. package/docs/inbox.md +145 -0
  204. package/docs/node.md +68 -45
  205. package/docs/query-format.md +1 -1
  206. package/docs/sign-in.md +5 -7
  207. package/docs/spaces.md +33 -5
  208. package/docs/standard-library.md +111 -86
  209. package/package.json +6 -5
  210. package/dist/doors/doors.d.ts +0 -140
  211. package/dist/doors/doors.d.ts.map +0 -1
  212. package/dist/doors/doors.js +0 -226
  213. package/dist/doors/doors.js.map +0 -1
  214. package/dist/doors/index.d.ts +0 -9
  215. package/dist/doors/index.d.ts.map +0 -1
  216. package/dist/doors/index.js +0 -7
  217. package/dist/doors/index.js.map +0 -1
  218. package/dist/network/mailbox.d.ts +0 -45
  219. package/dist/network/mailbox.d.ts.map +0 -1
  220. package/dist/network/mailbox.js +0 -135
  221. package/dist/network/mailbox.js.map +0 -1
  222. package/dist/network/multi-signaling.d.ts +0 -41
  223. package/dist/network/multi-signaling.d.ts.map +0 -1
  224. package/dist/network/multi-signaling.js +0 -209
  225. package/dist/network/multi-signaling.js.map +0 -1
  226. package/dist/network/signaling.d.ts +0 -95
  227. package/dist/network/signaling.d.ts.map +0 -1
  228. package/dist/network/signaling.js.map +0 -1
  229. package/docs/doors.md +0 -151
package/docs/agents.md CHANGED
@@ -32,62 +32,84 @@ await runAction(node, 'records_put', { space, collection: 'app.todo.item', body:
32
32
  From `@minca/cli`, the `minca` command:
33
33
 
34
34
  ```bash
35
- npx @minca/cli connect mc_… # the code from "Connect an agent" in an app
35
+ npx @minca/cli connect
36
36
  ```
37
37
 
38
- It makes a key for this computer's agent, waits while the person allows it at
39
- their account home, and adds `minca mcp` to the agents it finds (Claude Code,
40
- Claude Desktop, Cursor, VS Code, Windsurf, Zed, Codex and more). The agent is then a node of its own: it follows
41
- the account's spaces and keeps working with every tab closed.
38
+ It makes a key for this computer's agent and opens the person's account home
39
+ in the browser, where they sign in, or make an account, and allow it. The
40
+ home then shows six digits, which the person types into the terminal: the
41
+ agent keeps its note only once they match. Then it
42
+ adds `minca mcp` to the agents it finds (Claude Code, Claude Desktop, Cursor,
43
+ VS Code, Windsurf, Zed, Codex and more). The agent is then a node of its own:
44
+ it follows the account's spaces and keeps working with every tab closed.
45
+
46
+ An agent can also start `minca mcp` before it is connected, from settings
47
+ added by hand. Until it is, the server offers one tool, which opens the
48
+ account home the same way, and gives the model the link only when no
49
+ browser opened. The model asks the person for the six digits the home shows
50
+ and gives them back to the same tool
51
+ ([the CLI's README](https://github.com/leifriksheim/minca/blob/main/packages/cli/README.md#agents)). Once the
52
+ person has allowed it, every tool arrives (`notifications/tools/list_changed`)
53
+ without a restart.
42
54
 
43
55
  `minca agent` runs the same agent without a chat client: it chats in the
44
56
  terminal and thinks with the person's own Anthropic API key, offering the model
45
57
  the same tools. See `packages/cli/README.md`.
46
58
 
47
- ## Connecting with a code
59
+ ## Connecting at your account home
48
60
 
49
61
  The code, the channel it opens and the messages the two sides trade are
50
62
  protocol, and know nothing of agents
51
63
  ([spec 06 §3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
52
- The library's two sides are `offerConnectCode` (the app) and `connectWithCode`
53
- (the program).
54
-
55
- - `offerConnectCode({ relays, account, origin? }, onStage)` makes a code that
56
- names `account`, the account the app is signed in to, and tells the
57
- program `origin` (default: the page's). On `asking` it hands the app the
58
- program's ask (`did`, `name`, `proof`, `recordsOnly`) and two answers,
59
- `allow(grant)` and `deny(reason?)`. What the program asked for is only a
60
- request: the app decides, and denies an ask it won't grant as asked.
61
- - `connectWithCode({ code, key, name, recordsOnly, network, onWaiting? })`
62
- signs the proof itself once it learns the app's origin
63
- (`keyProof(key, { via: 'code', recordsOnly, origin })`), tells
64
- `onWaiting({ origin })` when the app has heard, and refuses a grant from any
65
- account but the one the code names.
64
+ The library's two sides are `connectWithCode` (the program) and
65
+ `receiveConnectCode` (the account home).
66
+
67
+ - `newConnectCode()` makes a code, and `connectCodeUrl(home, code)` the link
68
+ to open: `https://home.minca.social/connect#mc_…`.
69
+ - `connectWithCode({ home, code, key, name, network, check, onWaiting? })`
70
+ waits in the code's room, signs the proof once it learns the home's origin
71
+ (`keyProof(key, { via: 'code', recordsOnly: true, origin })`), tells
72
+ `onWaiting({ origin })` when the home has heard, and keeps only a
73
+ records-only note made out to its key, once `check(matches)` has had the
74
+ person give the six digits the home showed.
75
+ - `receiveConnectCode({ code, relays, onAnswered? })`, on the home's connect
76
+ page, answers the program and gives back the same `IncomingRequest` an
77
+ app's popup does: records only, in the whole account, for 30 days, with
78
+ `check`, the six digits to show.
79
+ `connectCodeIn(location.hash)` finds the code. `answerConnectCode` is the
80
+ same exchange without the request around it.
66
81
 
67
82
  What the reference sides add:
68
83
 
69
- - The terminal (`minca connect`) asks for records only, and shows the app's
70
- origin while the person decides.
71
- - The app (`apps/example/src/components/ConnectAgent.tsx`) shows the code. It
72
- gives a program records only (`apps/example/src/program-terms.ts`): it
73
- denies an ask without `recordsOnly: true`, and otherwise shows the
74
- program's name and what it may do, and asks the person to allow it.
75
- - Allowing opens the account home (`connectToHome` with `audience` and
76
- `audienceProof`, which adds `via: 'code'`) with `access: write`,
77
- `scope: account`, `chooseSpaces: false`, `recordsOnly: true` and the
78
- lifetime the person chose. The home warns in red when a request by code asks
79
- for more than records.
80
- - The app shows the agent connected when `code:done` arrives.
81
- - The terminal waits 60 s to hear `code:heard`, then 10 minutes for the
82
- answer, and checks the grant with `checkGrant(grant, did, { recordsOnly: true })`
83
- before keeping it, and again each time it starts.
84
- - The terminal makes a new key for each code. Connecting again, after a
84
+ - The terminal asks which account home to open, with home.minca.social, or
85
+ the one it connected at last, filled in so Enter takes it.
86
+ `--account-home` or `MINCA_ACCOUNT_HOME` names it ahead. The MCP server's
87
+ connect tool takes no home: the model never chooses where the person signs
88
+ in. Anywhere nothing can be asked, it uses the usual one.
89
+ - It opens the link in the browser, and shows it only when none opens (a
90
+ server, a terminal over SSH), since whoever else holds it could answer as
91
+ the home. The link works from any device.
92
+ - `connectWithCode` asks only the home it opened, and keeps that home in the
93
+ grant, whatever the answer names; it prints the account's DID beside its
94
+ name.
95
+ - The home (`apps/home/src/components/ConnectPage.tsx`) takes the code out
96
+ of the address bar, shows the program's name and says to allow it only if
97
+ the person started it just now. Once answered it says so, and the tab can
98
+ be closed. When no program asks within a minute, it says the link was
99
+ used or has run out.
100
+ - The terminal waits 10 minutes for the home to open, since the person may
101
+ make an account first, then 30 minutes for the answer. It checks the grant
102
+ with `checkGrant(grant, did, { recordsOnly: true })` before keeping it, and
103
+ again each time it starts, and says whose account it joined.
104
+ - The terminal makes a new key for each connect. Connecting again, after a
85
105
  disconnect or to renew, gives a new key and note; a running `minca mcp`
86
106
  takes them up without a restart. The earlier connection stays in the
87
107
  account home until it is disconnected there, and nothing can use it: its
88
108
  key is gone from the computer.
109
+ - An app only says how: "Connect an agent" in the example app shows the
110
+ command (`apps/example/src/components/ConnectAgent.tsx`).
89
111
 
90
- _Source: `packages/core/src/session/connect-code.ts`, `packages/cli/src/agent.ts` (`connectAgent`, `startAgentNode`, `reloadOnConnect`), `apps/example/src/components/ConnectAgent.tsx`, `apps/example/src/program-terms.ts`, `apps/home/src/components/ConnectPage.tsx`. Tests: `packages/core/tests/connect-code.test.ts`, `packages/core/tests/records-only.test.ts` ("a program connected by code, through the account home"), `apps/example/tests/program-terms.test.ts`, `packages/cli/tests/agent-reconnect.test.ts`._
112
+ _Source: `packages/core/src/session/connect-code.ts`, `packages/cli/src/agent.ts` (`connectAgent`, `openInBrowser`, `startAgentNode`, `reloadOnConnect`), `packages/cli/src/main.ts` (`chooseAccountHome`), `packages/cli/src/mcp.ts` (`connectWaiting`, `waitingMcp`), `apps/home/src/components/ConnectPage.tsx`. Tests: `packages/core/tests/connect-code.test.ts`, `packages/core/tests/records-only.test.ts` ("a program connected by code, through the account home"), `packages/cli/tests/agent-reconnect.test.ts`, `packages/cli/tests/cli.test.ts` ("not connected yet, it offers agent_connect…")._
91
113
 
92
114
  ## Tools an agent gets
93
115
 
@@ -24,7 +24,7 @@ who made it:
24
24
  "when": {
25
25
  "query": {
26
26
  "collection": "std.channel",
27
- "include": { "messages": { "rel": "channel", "from": "std.message", "count": true } }
27
+ "include": { "messages": { "rel": "in", "from": "std.message", "count": true } }
28
28
  },
29
29
  "holds": { "include:messages": { "$gte": 100 } }
30
30
  },
@@ -32,7 +32,7 @@ who made it:
32
32
  "kind": "add",
33
33
  "collection": "std.message",
34
34
  "text": "#{title} just passed {messages} messages",
35
- "links": [{ "rel": "channel", "to": "$it" }]
35
+ "links": [{ "rel": "in", "to": "$it" }]
36
36
  },
37
37
  "since": "2026-09-29T12:00:00Z"
38
38
  }
@@ -167,12 +167,53 @@ A screen reaches the page around it only through `window.minca`, and only for
167
167
  its app's collections and the people in its space: it lists and writes
168
168
  records as the person looking, asks what they may do (`can`), gets someone's
169
169
  picture (`picture`), and asks the page to show a record or a person
170
- (`open`). What a sealed frame can't do, the page does for it when it asks,
170
+ (`open`), or the record one of its own links to (`open` with `link`: the
171
+ message a file was shared on). Following a link is the one way past its collections. The bridge answers the same whether or not the record is there, and never opens the space's own records (`sys.*`, `launcher.app`); but the page visibly opens a record that is there, for the person, who can see it anyway, so a screen that already knows a key could notice, from outside, that it exists. What a sealed frame can't do, the page does for it when it asks,
171
172
  after checking the request: it searches for places and asks where the person
172
173
  is (`places`), opens http and https pages (`link`), saves text files
173
174
  (`save`), keeps a few kilobytes per app on the device (`remember`, `recall`),
174
175
  and reads a picture that one of the app's own records refers to (`file`),
175
- taking its type from the record rather than from the screen. In front of every screen the example app also writes `@minca/ui`
176
+ or the whole file (`blob`), taking its type from the record rather than from
177
+ the screen.
178
+
179
+ **Opening a record where it belongs.** A `launcher.app` may name, among its
180
+ `collections`, the ones it `shows`: the ones whose records it is the place
181
+ to open (`shows: ["std.message"]` for a chat). Whatever asks the example app
182
+ to open a record, a screen's `open` or a link beside a record, goes to the
183
+ app that shows that record's collection, the one open first, and that app's
184
+ screen is handed the record's key (`minca.shown`, `minca.onShow`, the kit's
185
+ `useShown`) to scroll to or open, but only of a collection it shows, which
186
+ it could list anyway. That app does learn which of those records the person
187
+ opens from elsewhere, which is why only someone who may define collections
188
+ adds an app. With no app that shows it, the record
189
+ opens beside whatever is open. So the Files app opens a file's message in
190
+ the chat, and a chat's file in Files, without either knowing the other. An
191
+ app that names a collection in `shows` must do something with what it is
192
+ handed. The kit's `<Record>` draws any standard record as one line the same
193
+ way in every app, and opens it this way when clicked.
194
+
195
+ A screen also sends live messages, kept nowhere, to the other devices that
196
+ have the same app open in the space (`live.send`, `live.on`): for cursors,
197
+ typing, who is here, or a game. Each goes as a live message of the space
198
+ ([node](node.md#live-messages-and-status)) whose payload names the app by its
199
+ `launcher.app` key, and a screen hears only those naming its own app:
200
+
201
+ ```json
202
+ {
203
+ "type": "screen.live",
204
+ "app": "aj5pakqf52uftpgarut33aqxq4.ctzz2xssv7y3alqlcepfmkdks4",
205
+ "data": { "x": 120, "y": 48 }
206
+ }
207
+ ```
208
+
209
+ A screen is handed `{ from, device, data, viaAgent }`, `from` being the
210
+ sender's account as the node proved it; a message from a peer with no account
211
+ is not passed on. One screen may send a burst of 30, then 15 a second, below
212
+ what a peer takes from another across everything, so a busy screen leaves
213
+ room for calls and the rest. An edited copy of an app is another
214
+ `launcher.app` record, so its screens don't hear the original's.
215
+
216
+ In front of every screen the example app also writes `@minca/ui`
176
217
  (`packages/ui`): Preact with htm, hooks that keep records current, people's
177
218
  faces, and Minca's look, so a screen is mostly what it is about. It isn't
178
219
  part of the screen, so it doesn't count toward the 48 KB a screen may be.
@@ -182,7 +223,7 @@ defines its collections and writes a copy of it, naming where it came from
182
223
  (`template: "kanban"`), and from then on the space changes its copy like any
183
224
  other app.
184
225
 
185
- _Source: `apps/example/src/components/apps/launcher.ts` (`addTemplate`), `apps/example/src/components/apps/screens.ts`, `apps/example/src/components/apps/ScreenFrame.tsx`, `apps/example/src/components/apps/templates/`, `apps/example/public/screen.html`, `packages/ui/src/frame/`, `packages/ui/src/guide.ts`. Tests: `apps/example/tests/launcher.test.ts` ("adding a ready-made app copies it into the space once, with its collections and first records"), `apps/example/tests/screens.test.ts` ("a screen checks, shows faces and opens things only within its app and its space", "what the page does for a screen, it does only as asked properly")._
226
+ _Source: `apps/example/src/components/apps/launcher.ts` (`addTemplate`), `apps/example/src/components/apps/screens.ts`, `apps/example/src/components/apps/ScreenFrame.tsx`, `apps/example/src/components/apps/templates/`, `apps/example/public/screen.html`, `packages/ui/src/frame/`, `packages/ui/src/guide.ts`. Tests: `apps/example/tests/launcher.test.ts` ("adding a ready-made app copies it into the space once, with its collections and first records"), `apps/example/tests/screens.test.ts` ("a screen checks, shows faces and opens things only within its app and its space", "what the page does for a screen, it does only as asked properly", "a screen hears the same app's screens on other devices, as who sent it, and no other app's")._
186
227
 
187
228
  ## Describing a collection
188
229
 
@@ -114,7 +114,7 @@ Leave out `network` to stay offline. Call `node.close()` when done.
114
114
  ```typescript
115
115
  const space = await node.spaces.create({ name: 'Groceries', visibility: 'private', ...rolePresets.team });
116
116
 
117
- const invite = await node.spaces.invite(space.id); // a link-safe string; treat it as a secret
117
+ const invite = await node.spaces.invite(space.id, { short: true }); // ~85 characters; treat it as a secret
118
118
  const view = await node.spaces.invite(space.id, { write: false }); // read-only
119
119
  await node.spaces.join(invite); // on the friend's side
120
120
  await node.spaces.closeInvite(space.id, invite); // nobody else joins with it
@@ -179,7 +179,7 @@ page was opened with:
179
179
  ```tsx
180
180
  import { inviteLink, useInviteLink, useMyName, useNode } from '@minca/core/react';
181
181
 
182
- const link = inviteLink(await node.spaces.invite(space.id)); // https://app.example/#invite=…
182
+ const link = inviteLink(await node.spaces.invite(space.id, { short: true })); // https://app.example/#invite=…
183
183
 
184
184
  function Invited({ onJoin }: { onJoin: (invite: string) => Promise<unknown> }) {
185
185
  const { invite, preview, dismiss } = useInviteLink();
package/docs/contacts.md CHANGED
@@ -2,17 +2,17 @@
2
2
 
3
3
  A contact is someone you share a **private space for two** with. The account
4
4
  keeps its list of them in its contacts space, and asks someone to become a
5
- contact by posting a sealed invite in a space both belong to.
6
-
7
- This is a convention built on the protocol, not part of it. Peers that have
8
- never heard of `std.contact` or `std.contact-request` sync, store and judge
9
- them like any other record. Only apps that want to read each other's contact
10
- lists and requests have to agree on what follows. It uses these protocol
11
- parts: the contacts space ([spec 03 §13.1](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)),
12
- profiles (§11), invites (§7), and the contact key and sealing to it with HPKE
13
- ([spec 01 §10.1, §9.2](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md)).
14
- Asking someone you share **no** space with goes through a door
15
- ([spec 07](https://github.com/leifriksheim/minca/blob/main/spec/07-doors.md)).
5
+ contact by leaving a knock for them: in a space both belong to, or in their
6
+ inbox.
7
+
8
+ The list and the request are conventions built on the protocol, not part of
9
+ it. Peers that have never heard of `std.contact` or `std.contact-request`
10
+ sync, store and judge them like any other record. The knock they carry is
11
+ protocol: how it is signed and sealed, and what the person it is for checks,
12
+ is [spec 07 §6](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md),
13
+ the same however it is handed over.
14
+ Asking someone you share **no** space with goes through their inbox
15
+ ([inbox.md](inbox.md)).
16
16
 
17
17
  ## The list: `std.contact`
18
18
 
@@ -22,15 +22,15 @@ The list lives in the account's contacts space (derived with the label
22
22
  ```
23
23
  std.contact (rules: onePer ["did"])
24
24
  { did: string ≤256, name: string ≤200, space?: string ≤256, note?: string ≤2000,
25
- blocked?: boolean, door?: string ≤64 }
25
+ blocked?: boolean }
26
26
  record key = records.onePerKey(contactsSpace, "std.contact", { did })
27
27
  = "one:" + hex(HMAC(oneKey, "std.contact\ndid=" + canonical(did))[0..20))
28
28
  // a shared key, spec 02 §7.3: onePer without @author
29
29
  ```
30
30
 
31
31
  `name` is what you call them; they never see it. `space` is the id of the
32
- space for two. `blocked` hides that person's contact requests in every space.
33
- `door` is set while a knock's answer is still to be written ([spec 07](https://github.com/leifriksheim/minca/blob/main/spec/07-doors.md)).
32
+ space for two. `blocked` hides that person's knocks, in every space and in the
33
+ inbox.
34
34
 
35
35
  A reader must ignore a record whose key is not the one its `did` derives. It
36
36
  also ignores one whose root is not the account, as it does for every record in
@@ -38,52 +38,28 @@ the account's derived spaces (spec 03 §13.1).
38
38
 
39
39
  ## The contact key
40
40
 
41
- A request is sealed to the askee's contact key: the public half, published as
42
- `contactKey` on their profile in the space (spec 03 §11). How it is derived is
43
- in spec 01 §10.1. A node holds the private half only when it was given it
44
- (`config.contactKey`); an agent never is.
41
+ A knock left in a shared space is sealed to the askee's contact key: the
42
+ public half, published as `contactKey` on their profile in the space (spec 03
43
+ §11). How it is derived is in spec 01 §10.1. A node holds the private half
44
+ only when it was given it (`config.contactKey`); an agent never is.
45
45
 
46
- ## `std.contact-request`
46
+ ## Asking in a shared space
47
47
 
48
48
  ```
49
- std.contact-request (no rules; who may post one is the space's grants)
50
- { to: <askee account DID, ≤256>, sealed: string ≤16000 }
49
+ std.contact-request (no rules; who may write one is the space's grants)
50
+ { to: <the askee's contact key, as on their profile here, ≤64>, sealed: string ≤16000 }
51
51
  ```
52
52
 
53
- Posted in a space both people belong to. In a private space the body is also
54
- encrypted with the space key, so other members see that `to` was asked, not
55
- what.
53
+ `ask` leaves one in the space: `sealed` is a knock sealed to `to` (spec 07
54
+ §6), whose invite is to a new space for two. It defines the collection first
55
+ if the space lacks it, which needs `/collection/define`. In a private space
56
+ the body is sealed with the space key too, so other members see that someone
57
+ asked, not whom.
56
58
 
57
- ### Sealing
58
-
59
- ```
60
- value = { invite: <role invite to the space for two>, note?: string ≤2000 }
61
- bound = { space: <spaceId>, from: <askerAccountDid>, to: <askeeAccountDid> }
62
- sealed = HPKE(askee.contactKey, "minca/contact-request/v1", bound, JSON value)
63
- ```
64
-
65
- `HPKE` is sealing to a key, spec 01 §9.2. A sealed `{"invite":"x"}` is
66
- 1 + 65 + 14 + 16 = 96 bytes.
67
-
68
- Example: in space `bspace`, `did:key:zA` asking `did:key:zB` seals with bound
69
- `{"from":"did:key:zA","space":"bspace","to":"did:key:zB"}`.
70
-
71
- ### Opening
72
-
73
- The receiver must open a request only when the record verifies and stands, its
74
- current version was signed by the account itself or under a note that grants
75
- `/account/write` for the whole account (a note about the account, no policy
76
- on `.space`), as a knock needs (spec 01 §8;
77
- not one for some spaces, nor an agent's), is in `std.contact-request`, `to` is the
78
- receiver's account, and `from` (the record's root) equals the root of the
79
- record's first version and is not the receiver. It must use the bound built
80
- from the space the record is in and that `from`. It must then reject the value
81
- unless `invite` parses as an invite (spec 03 §7.4) to a **private** space whose
82
- constitution names `from` as its one founder, assigning no roles of its own
83
- (spec 03 §1), and which carries a `key`.
84
-
85
- Binding the seal to the space and to who asked whom means a request copied
86
- into another space, or re-posted by someone else, does not open.
59
+ The receiver opens a request only when `to` is its own contact key, the
60
+ knock checks out (spec 07 §6), and the knock's account is the record's root
61
+ and not its own. A knock copied into another record by someone else is not
62
+ theirs to leave, and opens as nothing.
87
63
 
88
64
  ## `node.contacts`
89
65
 
@@ -92,13 +68,16 @@ into another space, or re-posted by someone else, does not open.
92
68
  - `put({ did, name, space?, note? })`: adds someone, or changes what the list
93
69
  says about them.
94
70
  - `ask(space, did, { note? })` needs whole-account access and the askee's
95
- `contactKey` on their profile in that space. It defines
96
- `std.contact-request` in the space if missing (needs `/collection/define`), creates a
97
- private `team` space named `"<my name> & <their name>"`, opens an `editor`
98
- invite to it, writes a `std.contact` for them with that space, then posts
99
- the sealed request. It returns the space for two and the request's key.
100
- - `requests(space)` lists requests that open for this account, skipping
101
- blocked senders and requests whose space for two the account already holds.
71
+ `contactKey` on their profile in that space. It creates a private `team`
72
+ space named `"<my name> & <their name>"`, opens an `editor` invite to it,
73
+ waits up to 3 seconds for a carrier that is online to hold it (`spaces.carried`), writes a
74
+ `std.contact` for them with that space, then leaves the knock as
75
+ `std.contact-request`. It returns the space for two, the record's key, and `carried`:
76
+ false when no carrier held the space in time, so the askee can join only
77
+ while one of the asker's devices is online.
78
+ - `requests(space)` lists the knocks left there that open for this account,
79
+ skipping blocked senders and knocks whose space for two the account already
80
+ holds.
102
81
  - `accept(space, requestKey)` joins the invite (spec 03 §7.6) and writes a
103
82
  `std.contact` for the asker with the space for two. There is no reply
104
83
  record: joining is the answer.
@@ -111,25 +90,25 @@ into another space, or re-posted by someone else, does not open.
111
90
  (members, profiles, connected peers).
112
91
 
113
92
  `ask` and `accept` need a session note that grants `/account/write` for the
114
- whole account, as a knock does. An app granted
115
- `contacts` sees the list and requests, but may not ask or accept
93
+ whole account, as a knock does. An app granted `contacts` sees the list and
94
+ requests, but may not ask or accept
116
95
  ([spec 06 §2.5](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
117
96
 
118
- _Source: `packages/core/src/schemas/contacts.ts`, `packages/core/src/identity/contact-key.ts` (`deriveContactKeyBytes`), `packages/core/src/identity/hpke.ts` (`sealValueTo`, `openValueFrom`), `packages/core/src/node/node.ts` (contacts section: `REQUEST_LABEL`, `openRequest`, `contacts`), `packages/core/src/node/types.ts` (`NodeContacts`), `packages/core/src/space/account-registry.ts` (`deriveContactsSpace`). Tests: `packages/core/tests/contacts.test.ts`, `packages/core/tests/attacks.test.ts`._
97
+ _Source: `packages/core/src/schemas/contacts.ts` (`contact`), `packages/core/src/identity/contact-key.ts` (`deriveContactKeyBytes`), `packages/core/src/inbox/inbox.ts` (`sealKnock`, `openKnock`), `packages/core/src/node/node.ts` (contacts section: `openMail`, `makePair`, `contacts`), `packages/core/src/schemas/contacts.ts` (`contactRequest`), `packages/core/src/node/types.ts` (`NodeContacts`), `packages/core/src/space/account-registry.ts` (`deriveContactsSpace`). Tests: `packages/core/tests/contacts.test.ts`, `packages/core/tests/attacks.test.ts` ("a knock re-posted by someone else…")._
119
98
 
120
99
  ## Planned: requests that can be taken back
121
100
 
122
101
  A list that never names a space the account left, and requests that can be
123
- taken back. Today the `std.contact` does not record where `ask` posted the
124
- request, so `remove` and `block` leave it standing: the askee can still accept
102
+ taken back. Today the `std.contact` does not record where `ask` left the
103
+ knock, so `remove` and `block` leave it standing: the askee can still accept
125
104
  it, into a space nobody holds. And `spaces.leave` on a space for two leaves the
126
105
  `std.contact` naming it.
127
106
 
128
107
  - `std.contact` gains `asked?: { space: string ≤256, key: string ≤256 }`, the
129
108
  space and record key of the request. `ask` writes it.
130
- - `remove(did)` and `block(did)` delete the `std.contact-request` at `asked`
131
- when the space is still held and the record still stands, before leaving the
132
- space for two.
109
+ - `remove(did)` and `block(did)` delete the request at `asked` when the
110
+ space is still held and the record still stands, before leaving the space
111
+ for two.
133
112
  - `spaces.leave(id)` on a space a `std.contact` names does what `remove` does
134
113
  for that contact.
135
114
  - `ContactView` gains `waiting: boolean`, true while the other account has no
package/docs/inbox.md ADDED
@@ -0,0 +1,145 @@
1
+ # The inbox
2
+
3
+ An account's inbox is an address it hands out on purpose, so that someone it
4
+ shares no space with can ask to become a contact. The keys, the inbox code, the
5
+ topic, the relay mailbox and the sealed knock are protocol
6
+ ([spec 07](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md)):
7
+ a relay and the inbox's owner check them.
8
+
9
+ What this page covers is a convention built on them, not part of the protocol:
10
+ where an account keeps its inbox's settings, and how a knock becomes a space
11
+ for two and a contact. Peers that have never heard of `std.inbox` or
12
+ `std.knock` sync, store and judge them like any other record. Only the devices
13
+ of one account have to agree on what follows.
14
+
15
+ ## `std.inbox`
16
+
17
+ The inbox's settings are a `std.inbox` record in the account's **contacts
18
+ space** ([spec 03](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)),
19
+ which only the account can find and every one of its devices holds.
20
+
21
+ | Field | Type | |
22
+ | -------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
23
+ | `gen` | integer ≥ 0 | Which inbox: both keys are derived from it ([spec 07 §1](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md)) |
24
+ | `places` | string[], 1–3 | Mailbox URLs, each passing the inbox code's relay check |
25
+ | `name` | string ≤64, optional | The name the code gives whoever knocks |
26
+
27
+ A device treats as the inbox only a verified `std.inbox` whose root is the
28
+ account itself, and of those the one with the highest `gen`, then the newest.
29
+ Changing the places or the name writes the next version of that record: the
30
+ keys stay, so a code already handed out keeps working once it is read again.
31
+ **Replacing** the inbox (`rotate`) clears what waits in the old one and writes
32
+ `gen + 1`: the old code leads to a topic nobody reads, and nothing ties the
33
+ new keys to the old.
34
+
35
+ _Source: `packages/core/src/schemas/contacts.ts` (`inbox`), `packages/core/src/node/node.ts` (The inbox: `inboxRecord`, `writeInbox`, `inbox.rotate`). Tests: `packages/core/tests/inbox.test.ts` ("node.inbox")._
36
+
37
+ ## The exchange
38
+
39
+ ```
40
+ Anna mailbox(es) Leif
41
+ │ inbox.open() → std.inbox, code │
42
+ │ ── code, out of band (a link, a QR code, a bio) ─────────────────────────────▶ │
43
+ │ spaces.create(private), invite(editor) │
44
+ │ spaces.carried: a carrier holds it │
45
+ │ ◀── drop(topic, sealed knock) ── to each │
46
+ │ std.knock { space, invite } │
47
+ │ fetch(topic) ──▶ ◀── mail [knock] │
48
+ │ open + check (spec 07 §6) │
49
+ │ accept: spaces.join(invite); std.contact { did: Leif, space } │
50
+ │ purge(knock) ──▶ │
51
+ │ ═════════════════ the space for two syncs, through Leif's carrier if he's away ▶ │
52
+ │ Anna is a member: std.contact { did: Anna }, invite │
53
+ │ closed, std.knock deleted │
54
+ ```
55
+
56
+ **Knocking.** The knocker:
57
+
58
+ 1. reads the code and checks its signature, and refuses its own inbox;
59
+ 2. creates a private space named `"<own name> & <code name>"` with the `team`
60
+ role preset, and makes an editor invite;
61
+ 3. if one of the account's carriers is online, waits up to 3 seconds for it to hold the
62
+ space and its invite (`spaces.carried`), so the other person can join with
63
+ every device of the knocker's away. With no carrier, or none in time, it
64
+ goes on and says so: `knock` returns `carried: false`;
65
+ 4. seals the knock ([spec 07 §6](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md))
66
+ and drops it in **every** mailbox the code names, since any one of them may
67
+ lose it (the reference relay keeps its mailbox in memory, so a restart
68
+ loses what it held);
69
+ 5. if no mailbox answers `dropped`, leaves the space and fails;
70
+ 6. otherwise writes `std.knock { space, name, invite }` in its contacts space.
71
+
72
+ **Opening.** Besides the checks the protocol requires, the owner's devices
73
+ skip knocks from the account itself, from accounts its contact list marks
74
+ blocked, and whose space for two it already holds (accepted here or on
75
+ another device).
76
+
77
+ **Accepting.** The owner joins the invite and writes
78
+ `std.contact { did: <the knocker's account>, name, space }`, keeping a name it
79
+ already had for that account, and purges the knock from the mailboxes. There
80
+ is no answer record: joining is the answer.
81
+
82
+ **Settling.** For each `std.knock`, the knocker's devices look at the members
83
+ of its space for two. The first account other than its own that holds a place
84
+ there is whoever answered: only the holder of the inbox key could open the
85
+ invite. They write
86
+ `std.contact { did: <that account>, name: <their profile name, else the code's>, space }`,
87
+ close the invite, and delete the `std.knock`, so nobody joins after. Anyone
88
+ else who joined too shows up in `contacts.others`.
89
+
90
+ The invite is multi-use until then, so it must reach nobody else: if the
91
+ owner passes it on, or a device of theirs is lost before they accept, whoever
92
+ joins first is taken for them. The old door answer, signed with a key of the
93
+ door's, ruled that out; it cost a second record and a signing key, and the
94
+ person accepting can as well forward the knock itself.
95
+
96
+ A `std.knock` nobody joined within the knock TTL (14 days) plus a day is let
97
+ go: the knocker leaves the space and deletes the record. One whose space is no
98
+ longer held is deleted.
99
+
100
+ **Dismissing** a knock purges it from the mailboxes; nothing else is written,
101
+ and the knocker is not blocked. **Clearing** the inbox purges all of its
102
+ knocks and keeps it open.
103
+
104
+ | Collection | Fields | Rules | Where |
105
+ | ----------- | -------------------------------------------------------- | ------------------- | ------------------------ |
106
+ | `std.inbox` | `gen` ≥ 0 and `places` (1–3) required; `name` ≤64 | — | Owner's contacts space |
107
+ | `std.knock` | `space` ≤256, `name` ≤64, `invite` ≤12000 (all required) | `onePer: ['space']` | Knocker's contacts space |
108
+
109
+ **Who may.** Knocking and accepting create or join a space, so they need a note
110
+ that grants `/account/write` for the whole account, as `contacts.ask` does,
111
+ and the contact key. The inbox is the person's: a node whose note lacks
112
+ `/account/write`, such as an agent's, refuses to open, replace, clear, read,
113
+ knock, accept or dismiss. A home never gives an agent the contact key in the
114
+ first place ([spec 06 §2.8](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
115
+
116
+ _Source: `packages/core/src/node/node.ts` (The inbox: `makePair`, `settleSent`, `readKnocks`, `inbox`), `packages/core/src/node/types.ts` (`NodeInbox`), `packages/core/src/schemas/contacts.ts` (`inbox`, `knock`), `packages/core/src/inbox/inbox.ts`, `packages/core/src/session/auth.ts` (`grant`). Tests: `packages/core/tests/inbox.test.ts` ("node.inbox"), `packages/core/tests/carrier.test.ts` ("a space made just now, carried before its invite goes out…"), `packages/core/tests/records-only.test.ts`._
117
+
118
+ ## `node.inbox`
119
+
120
+ The calls are listed with the rest of the node, in [node.md](node.md#the-inbox).
121
+ `node.inbox.knocks()` fetches; it doesn't watch, though the mailbox supports
122
+ `watch`. The default mailbox client opens a fresh WebSocket to a relay for
123
+ each call.
124
+
125
+ _Source: `packages/core/src/network/relays.ts` (`createMailboxClient`)._
126
+
127
+ ## Not yet built
128
+
129
+ - **Live knocks.** Watching the inbox's topic, so a knock shows as it arrives.
130
+ - **Retrying a knock** that reached no mailbox, or whose mailboxes lost it
131
+ (restart), until someone joins or it expires. A retry is a fresh knock,
132
+ signed and dropped at once.
133
+ - **Mailboxes that last.** A host that keeps its accounts' inbox topics
134
+ across restarts, as it keeps short links.
135
+
136
+ ## Planned: names
137
+
138
+ The protocol side of names (a handle resolving to an inbox code) is planned in
139
+ [spec 07 §9](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md).
140
+ On this side:
141
+
142
+ - `node.inbox.knock` accepts a handle wherever it takes a code.
143
+ - **Who may knock.** The inbox gains a policy in its `std.inbox` record (never
144
+ published): `anyone` (default), `follows` or `mutuals` on the handle's
145
+ network. Knocks that don't match are kept but shown apart.