@minca/core 0.1.10 → 0.1.11

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 (157) hide show
  1. package/README.md +1 -1
  2. package/dist/identity/abilities.js +1 -1
  3. package/dist/identity/contact-key.d.ts +15 -15
  4. package/dist/identity/contact-key.d.ts.map +1 -1
  5. package/dist/identity/contact-key.js +21 -28
  6. package/dist/identity/contact-key.js.map +1 -1
  7. package/dist/inbox/inbox.d.ts +140 -0
  8. package/dist/inbox/inbox.d.ts.map +1 -0
  9. package/dist/inbox/inbox.js +212 -0
  10. package/dist/inbox/inbox.js.map +1 -0
  11. package/dist/inbox/index.d.ts +9 -0
  12. package/dist/inbox/index.d.ts.map +1 -0
  13. package/dist/inbox/index.js +7 -0
  14. package/dist/inbox/index.js.map +1 -0
  15. package/dist/index.d.ts +2 -2
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +1 -1
  18. package/dist/index.js.map +1 -1
  19. package/dist/network/mailbox.d.ts +4 -4
  20. package/dist/network/mailbox.d.ts.map +1 -1
  21. package/dist/network/mailbox.js +5 -5
  22. package/dist/network/mailbox.js.map +1 -1
  23. package/dist/node/actions.d.ts.map +1 -1
  24. package/dist/node/actions.js +28 -18
  25. package/dist/node/actions.js.map +1 -1
  26. package/dist/node/api.d.ts +11 -10
  27. package/dist/node/api.d.ts.map +1 -1
  28. package/dist/node/api.js +11 -10
  29. package/dist/node/api.js.map +1 -1
  30. package/dist/node/carrier.d.ts +11 -5
  31. package/dist/node/carrier.d.ts.map +1 -1
  32. package/dist/node/carrier.js +42 -1
  33. package/dist/node/carrier.js.map +1 -1
  34. package/dist/node/copy.d.ts +1 -1
  35. package/dist/node/copy.d.ts.map +1 -1
  36. package/dist/node/copy.js +10 -4
  37. package/dist/node/copy.js.map +1 -1
  38. package/dist/node/host.d.ts +2 -0
  39. package/dist/node/host.d.ts.map +1 -1
  40. package/dist/node/host.js +2 -0
  41. package/dist/node/host.js.map +1 -1
  42. package/dist/node/index.d.ts +1 -1
  43. package/dist/node/index.d.ts.map +1 -1
  44. package/dist/node/node.d.ts.map +1 -1
  45. package/dist/node/node.js +496 -295
  46. package/dist/node/node.js.map +1 -1
  47. package/dist/node/remote.d.ts.map +1 -1
  48. package/dist/node/remote.js +0 -2
  49. package/dist/node/remote.js.map +1 -1
  50. package/dist/node/space-runtime.d.ts +2 -1
  51. package/dist/node/space-runtime.d.ts.map +1 -1
  52. package/dist/node/space-runtime.js +2 -2
  53. package/dist/node/space-runtime.js.map +1 -1
  54. package/dist/node/types.d.ts +72 -43
  55. package/dist/node/types.d.ts.map +1 -1
  56. package/dist/react/use-invite-link.d.ts +1 -1
  57. package/dist/react/use-invite-link.d.ts.map +1 -1
  58. package/dist/react/use-invite-link.js +18 -11
  59. package/dist/react/use-invite-link.js.map +1 -1
  60. package/dist/records/loose.d.ts +52 -0
  61. package/dist/records/loose.d.ts.map +1 -0
  62. package/dist/records/loose.js +86 -0
  63. package/dist/records/loose.js.map +1 -0
  64. package/dist/schema/version.d.ts +2 -0
  65. package/dist/schema/version.d.ts.map +1 -1
  66. package/dist/schema/version.js +2 -1
  67. package/dist/schema/version.js.map +1 -1
  68. package/dist/schemas/choosing.d.ts +19 -0
  69. package/dist/schemas/choosing.d.ts.map +1 -0
  70. package/dist/schemas/choosing.js +69 -0
  71. package/dist/schemas/choosing.js.map +1 -0
  72. package/dist/schemas/contacts.d.ts +34 -87
  73. package/dist/schemas/contacts.d.ts.map +1 -1
  74. package/dist/schemas/contacts.js +32 -76
  75. package/dist/schemas/contacts.js.map +1 -1
  76. package/dist/schemas/index.d.ts +2 -2
  77. package/dist/schemas/index.d.ts.map +1 -1
  78. package/dist/schemas/index.js +1 -1
  79. package/dist/schemas/index.js.map +1 -1
  80. package/dist/schemas/library/annotations.d.ts +17 -285
  81. package/dist/schemas/library/annotations.d.ts.map +1 -1
  82. package/dist/schemas/library/annotations.js +9 -65
  83. package/dist/schemas/library/annotations.js.map +1 -1
  84. package/dist/schemas/library/community.d.ts +9 -17
  85. package/dist/schemas/library/community.d.ts.map +1 -1
  86. package/dist/schemas/library/community.js +5 -5
  87. package/dist/schemas/library/community.js.map +1 -1
  88. package/dist/schemas/library/life.d.ts +3 -3
  89. package/dist/schemas/library/life.d.ts.map +1 -1
  90. package/dist/schemas/library/life.js +2 -2
  91. package/dist/schemas/library/life.js.map +1 -1
  92. package/dist/schemas/library/media.d.ts +148 -541
  93. package/dist/schemas/library/media.d.ts.map +1 -1
  94. package/dist/schemas/library/media.js +28 -64
  95. package/dist/schemas/library/media.js.map +1 -1
  96. package/dist/schemas/library/money.d.ts +8 -8
  97. package/dist/schemas/library/money.d.ts.map +1 -1
  98. package/dist/schemas/library/money.js +4 -4
  99. package/dist/schemas/library/money.js.map +1 -1
  100. package/dist/schemas/library/planning.d.ts +23 -87
  101. package/dist/schemas/library/planning.d.ts.map +1 -1
  102. package/dist/schemas/library/planning.js +10 -26
  103. package/dist/schemas/library/planning.js.map +1 -1
  104. package/dist/schemas/library/publishing.d.ts +14 -14
  105. package/dist/schemas/library/publishing.d.ts.map +1 -1
  106. package/dist/schemas/library/publishing.js +7 -7
  107. package/dist/schemas/library/publishing.js.map +1 -1
  108. package/dist/schemas/library/social.d.ts +2 -2
  109. package/dist/schemas/library/social.d.ts.map +1 -1
  110. package/dist/schemas/library/social.js +1 -1
  111. package/dist/schemas/library/social.js.map +1 -1
  112. package/dist/schemas/standard.d.ts +1 -1
  113. package/dist/schemas/standard.d.ts.map +1 -1
  114. package/dist/schemas/standard.js +3 -3
  115. package/dist/schemas/standard.js.map +1 -1
  116. package/dist/session/auth.js +1 -1
  117. package/dist/session/auth.js.map +1 -1
  118. package/dist/space/account-registry.d.ts +22 -0
  119. package/dist/space/account-registry.d.ts.map +1 -1
  120. package/dist/space/account-registry.js +18 -0
  121. package/dist/space/account-registry.js.map +1 -1
  122. package/dist/space/invitation.d.ts +61 -0
  123. package/dist/space/invitation.d.ts.map +1 -0
  124. package/dist/space/invitation.js +84 -0
  125. package/dist/space/invitation.js.map +1 -0
  126. package/dist/space/invite-link.d.ts +64 -0
  127. package/dist/space/invite-link.d.ts.map +1 -0
  128. package/dist/space/invite-link.js +212 -0
  129. package/dist/space/invite-link.js.map +1 -0
  130. package/dist/space/space-manager.d.ts +21 -6
  131. package/dist/space/space-manager.d.ts.map +1 -1
  132. package/dist/space/space-manager.js +40 -23
  133. package/dist/space/space-manager.js.map +1 -1
  134. package/dist/types.d.ts +2 -0
  135. package/dist/types.d.ts.map +1 -1
  136. package/dist/types.js.map +1 -1
  137. package/docs/README.md +2 -2
  138. package/docs/actions.md +37 -37
  139. package/docs/automations.md +2 -2
  140. package/docs/blueprints-and-guides.md +44 -3
  141. package/docs/building-an-app.md +2 -2
  142. package/docs/contacts.md +48 -69
  143. package/docs/inbox.md +145 -0
  144. package/docs/node.md +36 -23
  145. package/docs/query-format.md +1 -1
  146. package/docs/spaces.md +33 -5
  147. package/docs/standard-library.md +111 -86
  148. package/package.json +5 -5
  149. package/dist/doors/doors.d.ts +0 -140
  150. package/dist/doors/doors.d.ts.map +0 -1
  151. package/dist/doors/doors.js +0 -226
  152. package/dist/doors/doors.js.map +0 -1
  153. package/dist/doors/index.d.ts +0 -9
  154. package/dist/doors/index.d.ts.map +0 -1
  155. package/dist/doors/index.js +0 -7
  156. package/dist/doors/index.js.map +0 -1
  157. package/docs/doors.md +0 -151
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/mailbox.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.
package/docs/node.md CHANGED
@@ -3,7 +3,7 @@
3
3
  `createNode` and what it returns: configuration, root signers and notes, renewing
4
4
  the session note, stores, holding spaces, following the account, events, live
5
5
  messages, the rest of its surface, the network, acting as an agent, the
6
- app-side client, carriers and hosting, doors, and the React and element
6
+ app-side client, carriers and hosting, the inbox, and the React and element
7
7
  conveniences.
8
8
 
9
9
  > Not protocol. This page describes the reference library, and another
@@ -18,7 +18,7 @@ conveniences.
18
18
  | ------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
19
19
  | `signer` | `RootSigner` | Who the node acts for. Asked only for session notes ([spec 06 §1.2](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)). |
20
20
  | `accountKey` | bytes, optional | The account key (`deriveAccountKey(seed)`). Enables the account registry and the contacts space ([spec 06 §1.3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)). |
21
- | `contactKey` | bytes, optional | The contact key's secret. Opens contact requests; published on profiles. |
21
+ | `contactKey` | bytes, optional | The contact key's secret. Opens knocks, in shared spaces and, through the keys derived from it, in the inbox; published on profiles. |
22
22
  | `contactsSpace` | string, optional | The contacts space's id, for a node given it without the account key (an app granted `contacts`, [spec 06 §2.5](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)). |
23
23
  | `stores` | `StoreFactory` | Where the registry and each space's store live ([stores](#stores)). |
24
24
  | `provider` | `CryptoProvider`, optional | Default: P-256 over WebCrypto. |
@@ -29,7 +29,7 @@ conveniences.
29
29
  | `writerKey` | `WriterKeySource`, optional | Keep a signing key across runs, so this device keeps one log in each space ([writer keys](#writer-keys)). Ignored with `sessionKey`. |
30
30
  | `watchIntervalMs` | number, optional | How often to look for writes another app, device or process made: a data folder's segments, a store file another process shares. `0` disables. Default `2000`. _Implementation detail._ |
31
31
  | `cache` | `CacheConfig`, optional | Hold only the collections used, in spaces that name a keeper ([holding part of a space](#holding-part-of-a-space)). |
32
- | `mailbox` | `MailboxClient`, optional | How doors reach relays' mailboxes ([07](https://github.com/leifriksheim/minca/blob/main/spec/07-doors.md)). Default: a WebSocket to each relay. |
32
+ | `mailbox` | `MailboxClient`, optional | How the inbox and short links reach mailboxes ([07](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md)). Default: a WebSocket to each relay. |
33
33
 
34
34
  _Source: `packages/core/src/node/types.ts` (`NodeConfig`, `NodeNetworkConfig`, `CacheConfig`). Tests: `packages/core/tests/node.test.ts`, `packages/core/tests/caches.test.ts`._
35
35
 
@@ -450,7 +450,8 @@ and never under a note that lacks `/account/write`, such as an agent's. The prof
450
450
  [03](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
451
451
 
452
452
  **Joining.** `spaces.join(invite)` accepts a bare invite or any link carrying
453
- `#invite=…`, `?invite=…` or `&invite=…`. It stores the space (and its key, for
453
+ `#invite=…`, `?invite=…` or `&invite=…`, long or short; a short one is
454
+ fetched from its mailboxes first ([spaces](spaces.md#invites)). It stores the space (and its key, for
454
455
  a private space), stores `memberKey` when given, writes the `sys.joined`
455
456
  record, then tries to use the invite's role secret at once. If the space's
456
457
  invite record has not reached this device yet, the space is held with
@@ -611,7 +612,7 @@ successors, mine, heads, key, relays, keepers, copies, forks, flagged }`
611
612
  account (whole-account access).
612
613
  - `node.direct` — [direct-messages.md](direct-messages.md): `reachable`, `send`
613
614
  and `list`. Needs the account's member key for the space.
614
- - `node.doors` — [doors.md](doors.md), [07](https://github.com/leifriksheim/minca/blob/main/spec/07-doors.md). Needs the contact key; knocking and
615
+ - `node.inbox` — [inbox.md](inbox.md), [07](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md). Needs the contact key; knocking and
615
616
  accepting also need whole-account access.
616
617
  - `node.carriers`, `node.hosting`, `node.notifications` — [carriers and hosting](#carriers-hosting-and-notifications), [spec 06 §4](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
617
618
  - `node.iceServers()` — the configured ICE servers plus TURN servers a relay
@@ -707,7 +708,7 @@ throws unless the note verifies, grants records only (its command is under
707
708
  or deleting collections; live messages (`send`, which a person's devices
708
709
  would take as theirs); renaming or revoking at the account level; adding or
709
710
  removing carriers; notifications; hosting; changing, blocking, asking or
710
- accepting contacts; everything about doors (its list of doors is empty);
711
+ accepting contacts; everything about the inbox (it has none);
711
712
  `delegate`; `asAgent`;
712
713
  - sees the contact list only if the contacts space is within its note.
713
714
 
@@ -718,8 +719,8 @@ an agent is started on the node itself.
718
719
  An agent granted `scope: account` gets a records-only note for every space
719
720
  (`/record`, about the whole account) and the account key in its
720
721
  grant ([spec 06 §2.8](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)), so the contact list is within its note to read. A home never
721
- gives a records-only key the contact key: with it, it could open contact
722
- requests and knocks on the account's doors ([doors.md](doors.md)).
722
+ gives a records-only key the contact key: with it, it could open the
723
+ account's knocks, in shared spaces and in its inbox ([inbox.md](inbox.md)).
723
724
 
724
725
  Which of these each method of the node is — passed through, held to the note's spaces, or refused — is one table, `API` in `packages/core/src/node/api.ts`; a new method does not type-check until it is decided there. The same table lists what `remoteNode` forwards.
725
726
 
@@ -887,6 +888,18 @@ for the carrier is not left with nobody (spec 06 §4.3). `node.carriers.remove(c
887
888
  writes `carry:closed` and marks the record removed; the node keeps the carry
888
889
  space open until it closes, so the carrier hears it.
889
890
 
891
+ **A space made just now.** Until a carrier opens it from its pass and syncs
892
+ it, a new space is only on the device that made it: an invite handed out and
893
+ the device closed can't be used. `node.spaces.carried(spaceId, { waitMs? })`
894
+ is a short loading step: when a carrier of the account is connected now, it
895
+ names it a keeper, writes its pass at once, and waits up to `waitMs`
896
+ (default 3 s) until it is level with this node in the space, so it holds the
897
+ genesis and any invite opened before the call. It says whether it was: false
898
+ at once when no carrier is connected. `contacts.ask` and `inbox.knock` wait on it before the knock goes
899
+ out, and pass what it said on as `carried`, for the app to tell the person.
900
+
901
+ _Source: `packages/core/src/node/node.ts` (`spaces.carried`, `makePair`). Tests: `packages/core/tests/carrier.test.ts` ("a space made just now, carried before its invite goes out…", "carried is false at once with no carrier…")._
902
+
890
903
  **The account's own automations.** `node.automations` (needs the account
891
904
  key) lists, adds, updates (`name`, `paused`) and removes the account's own
892
905
  automations, kept in its registry ([automations](automations.md#the-accounts-own)),
@@ -995,21 +1008,21 @@ paid, and what is in the fund stays there
995
1008
 
996
1009
  _Source: `packages/core/src/node/node.ts` (`keepSpaceHosts`, `askSpaceHost`, `hosting.space`), `packages/core/src/session/hosting.ts` (`describeHost`, `HostError`). Tests: `packages/cli/tests/host.test.ts` ("a space paying for itself", "an address that is not a host, or one that is down", "bots a host runs": the two on stopping a space's host)._
997
1010
 
998
- ## Doors
999
-
1000
- `node.doors` ([doors.md](doors.md), [spec 07](https://github.com/leifriksheim/minca/blob/main/spec/07-doors.md)):
1001
-
1002
- | Call | Does |
1003
- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1004
- | `list()` | Your open doors: `{ id, label?, name?, key, sign, relays, code, createdAt }` |
1005
- | `open({ relays?, name?, label? })` | Opens a door. Relays default to this node's relays (up to 3); name to the account's name |
1006
- | `close(id)` | Deletes the `std.door` |
1007
- | `clear(id)` | Purges every knock at the door, from every relay it names |
1008
- | `knock(code, { note? })` | [the exchange](doors.md#the-exchange), returns `{ space }` |
1009
- | `knocks()` | Fetches every open door's topic from every relay it names, opens and checks ([spec 07 §6](https://github.com/leifriksheim/minca/blob/main/spec/07-doors.md); opened results are cached by id), settles sent knocks and writes owed answers; returns `{ id, door, from, name, note?, pairSpace, at }`, newest first |
1010
- | `sent()` | Your unanswered knocks: `{ space, name, at }` |
1011
- | `accept(id)` | [the exchange](doors.md#the-exchange), returns the new `ContactView` |
1012
- | `dismiss(id)` | Purges one knock |
1011
+ ## The inbox
1012
+
1013
+ `node.inbox` ([inbox.md](inbox.md), [spec 07](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md)):
1014
+
1015
+ | Call | Does |
1016
+ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1017
+ | `get()` | Your inbox, or null until opened: `{ gen, name?, key, sign, places, code, updatedAt }`. `code` is signed afresh each time; what it says stays the same |
1018
+ | `open({ places?, name? })` | Opens your inbox, or changes where its knocks wait and the name it gives. Places default to the current ones, else this node's relays (up to 3); name to the current one, else the account's |
1019
+ | `rotate()` | Clears the inbox and replaces it with `gen + 1`: the old code leads nowhere |
1020
+ | `clear()` | Purges every knock waiting, from every mailbox it names |
1021
+ | `knock(code, { note? })` | [the exchange](inbox.md#the-exchange), returns `{ space, carried }` |
1022
+ | `knocks()` | Fetches the inbox's topic from every mailbox it names, opens and checks ([spec 07 §6](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md); opened results are cached by id), settles sent knocks; returns `{ id, from, name, note?, pairSpace, at }`, newest first |
1023
+ | `sent()` | Your knocks nobody has joined yet: `{ space, name, at }` |
1024
+ | `accept(id)` | [the exchange](inbox.md#the-exchange), returns the new `ContactView` |
1025
+ | `dismiss(id)` | Purges one knock |
1013
1026
 
1014
1027
  ## Client conveniences
1015
1028
 
@@ -98,7 +98,7 @@ never `null`.
98
98
  | `@updatedAt` | `createdAt` of this version |
99
99
  | `@seq` | `seq` |
100
100
  | `@collection` | `collection` |
101
- | `link:<rel>` | the `to` of the record's first link with that `rel`, as contracts' `link` and `onePer` read it; missing when it has none. `{ "link:channel": key }` finds a channel's messages, `{ "link:channel": { "$exists": false } }` those in no channel. |
101
+ | `link:<rel>` | the `to` of the record's first link with that `rel`, as contracts' `link` and `onePer` read it; missing when it has none. `{ "link:in": key }` finds a channel's messages, `{ "link:in": { "$exists": false } }` those in no channel. |
102
102
  | `include:<name>` | in an [automation](automations.md)'s `holds` only: what the query's `include` of that name found for the record, a number for a count |
103
103
  | path | When its first segment names one of the collection's [computed fields](computed.md), start from that field's value and walk the rest; otherwise walk the body. A body member with a computed field's name is never read: a writer can't stand in for what the node works out. Walking: at each segment, the current value must be a non-null object or array, and the segment one of its own member names, or of an array a position (`0`, `1`, …; nothing else, not `length`); otherwise the value is _missing_. |
104
104
 
package/docs/spaces.md CHANGED
@@ -144,22 +144,50 @@ _Source: `packages/core/src/node/node.ts` (`spaces.succeed`), `packages/core/src
144
144
  - Each role invite gets its own fresh secret and its own `sys.invite` record,
145
145
  so one can be closed without the others.
146
146
  - The invite names the space's relays, or the inviter's own when the space
147
- names none.
148
-
149
- `node.spaces.preview(invite)` decodes an invite without storing anything:
147
+ names none, and the always-on nodes that hold it: the account's hosts and
148
+ the space's own, at most 8, each pinned by its DID. A host that can't be
149
+ described within three seconds is left out rather than hold the invite up.
150
+ - `short: true` makes a short link (spec 03 §7.7), about 85 characters: the
151
+ invite is sealed and left in the mailbox of the account's first host and of
152
+ the first relay that takes it, and the link names those two. Where no
153
+ mailbox takes it, or the space's constitution is too large for one, the
154
+ long invite is returned instead; it works the same. `until` (ms) says when
155
+ to stop sharing it.
156
+
157
+ **Short links the account keeps.** Each short link's sealed invite is kept in
158
+ the account registry (`sys.link`), never its secret, and copied to every
159
+ carrier's carry space, so the account's host serves it while every device is
160
+ away. Every hour, and whenever the registry or a space's key changes, a
161
+ device holding the account key drops each one again where the space's members
162
+ meet. One past its `until`, or carrying a key the space has moved on from, is
163
+ ended: its role invite is closed and the record deleted. `closeInvite` by a
164
+ short link closes its invite and forgets the record. The device that made a
165
+ link holds its secret nowhere: copy the link when it is made.
166
+
167
+ `node.spaces.preview(invite)` reads an invite without storing anything, and
168
+ for a short link fetches it first, which is why it is async:
150
169
 
151
170
  ```
152
171
  { space: { id, name, visibility, founders, createdAt, succeeds? }, invitedBy,
153
- carriesKey, carriesWrite, role } // role is null for a view-only invite
172
+ carriesKey, carriesWrite, role, // role is null for a view-only invite
173
+ until? } // a short link's, when given
154
174
  ```
155
175
 
176
+ `invitedBy` is the account that signed the invitation: `preview` and `join`
177
+ both refuse an invite whose signature or note doesn't check out ([spec 03 §7.4](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)).
178
+ A short link is fetched once and remembered by the node, so a preview and the
179
+ join after it ask the mailboxes once. A link whose invite is nowhere fails
180
+ with "That invite was not found"; it may have expired or its places be down.
181
+ Invite nodes are dialled for the space alongside the hosts the account uses,
182
+ and kept like its invite relays.
183
+
156
184
  On `join`, relays carried by the invite are a hint: the node uses them only
157
185
  when they pass `checkRelays` and it holds no relay list for the space yet.
158
186
  While the invite's record has not reached this device, the space is held with
159
187
  `joining: true` and the node tries again as records arrive
160
188
  ([spec 06 §1.3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
161
189
 
162
- _Source: `packages/core/src/node/node.ts` (`spaces.invite`, `preview`, `join`), `packages/core/src/space/space-manager.ts` (`previewInvite`, `join`). Tests: `packages/core/tests/space.test.ts` ("invites"), `packages/core/tests/roles.test.ts` ("invites")._
190
+ _Source: `packages/core/src/node/node.ts` (`spaces.invite`, `preview`, `join`, `nodesOf`, `shortInvite`, `resolveInvite`, `keepLinks`), `packages/core/src/space/space-manager.ts` (`previewInvite`, `join`), `packages/core/src/space/invite-link.ts`. Tests: `packages/core/tests/space.test.ts` ("invites"), `packages/core/tests/roles.test.ts` ("invites"), `packages/core/tests/invite-link.test.ts`, `packages/cli/tests/host.test.ts` ("someone invited reaches the space through the inviter’s host…", "a short link: the host keeps it…")._
163
191
 
164
192
  ## Keeping a space's keys and relays
165
193