@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.
- package/README.md +1 -1
- package/dist/identity/abilities.js +1 -1
- package/dist/identity/contact-key.d.ts +15 -15
- package/dist/identity/contact-key.d.ts.map +1 -1
- package/dist/identity/contact-key.js +21 -28
- package/dist/identity/contact-key.js.map +1 -1
- package/dist/inbox/inbox.d.ts +140 -0
- package/dist/inbox/inbox.d.ts.map +1 -0
- package/dist/inbox/inbox.js +212 -0
- package/dist/inbox/inbox.js.map +1 -0
- package/dist/inbox/index.d.ts +9 -0
- package/dist/inbox/index.d.ts.map +1 -0
- package/dist/inbox/index.js +7 -0
- package/dist/inbox/index.js.map +1 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/network/mailbox.d.ts +4 -4
- package/dist/network/mailbox.d.ts.map +1 -1
- package/dist/network/mailbox.js +5 -5
- package/dist/network/mailbox.js.map +1 -1
- package/dist/node/actions.d.ts.map +1 -1
- package/dist/node/actions.js +28 -18
- package/dist/node/actions.js.map +1 -1
- package/dist/node/api.d.ts +11 -10
- package/dist/node/api.d.ts.map +1 -1
- package/dist/node/api.js +11 -10
- package/dist/node/api.js.map +1 -1
- package/dist/node/carrier.d.ts +11 -5
- package/dist/node/carrier.d.ts.map +1 -1
- package/dist/node/carrier.js +42 -1
- package/dist/node/carrier.js.map +1 -1
- package/dist/node/copy.d.ts +1 -1
- package/dist/node/copy.d.ts.map +1 -1
- package/dist/node/copy.js +10 -4
- package/dist/node/copy.js.map +1 -1
- package/dist/node/host.d.ts +2 -0
- package/dist/node/host.d.ts.map +1 -1
- package/dist/node/host.js +2 -0
- package/dist/node/host.js.map +1 -1
- package/dist/node/index.d.ts +1 -1
- package/dist/node/index.d.ts.map +1 -1
- package/dist/node/node.d.ts.map +1 -1
- package/dist/node/node.js +496 -295
- package/dist/node/node.js.map +1 -1
- package/dist/node/remote.d.ts.map +1 -1
- package/dist/node/remote.js +0 -2
- package/dist/node/remote.js.map +1 -1
- package/dist/node/space-runtime.d.ts +2 -1
- package/dist/node/space-runtime.d.ts.map +1 -1
- package/dist/node/space-runtime.js +2 -2
- package/dist/node/space-runtime.js.map +1 -1
- package/dist/node/types.d.ts +72 -43
- package/dist/node/types.d.ts.map +1 -1
- package/dist/react/use-invite-link.d.ts +1 -1
- package/dist/react/use-invite-link.d.ts.map +1 -1
- package/dist/react/use-invite-link.js +18 -11
- package/dist/react/use-invite-link.js.map +1 -1
- package/dist/records/loose.d.ts +52 -0
- package/dist/records/loose.d.ts.map +1 -0
- package/dist/records/loose.js +86 -0
- package/dist/records/loose.js.map +1 -0
- package/dist/schema/version.d.ts +2 -0
- package/dist/schema/version.d.ts.map +1 -1
- package/dist/schema/version.js +2 -1
- package/dist/schema/version.js.map +1 -1
- package/dist/schemas/choosing.d.ts +19 -0
- package/dist/schemas/choosing.d.ts.map +1 -0
- package/dist/schemas/choosing.js +69 -0
- package/dist/schemas/choosing.js.map +1 -0
- package/dist/schemas/contacts.d.ts +34 -87
- package/dist/schemas/contacts.d.ts.map +1 -1
- package/dist/schemas/contacts.js +32 -76
- package/dist/schemas/contacts.js.map +1 -1
- package/dist/schemas/index.d.ts +2 -2
- package/dist/schemas/index.d.ts.map +1 -1
- package/dist/schemas/index.js +1 -1
- package/dist/schemas/index.js.map +1 -1
- package/dist/schemas/library/annotations.d.ts +17 -285
- package/dist/schemas/library/annotations.d.ts.map +1 -1
- package/dist/schemas/library/annotations.js +9 -65
- package/dist/schemas/library/annotations.js.map +1 -1
- package/dist/schemas/library/community.d.ts +9 -17
- package/dist/schemas/library/community.d.ts.map +1 -1
- package/dist/schemas/library/community.js +5 -5
- package/dist/schemas/library/community.js.map +1 -1
- package/dist/schemas/library/life.d.ts +3 -3
- package/dist/schemas/library/life.d.ts.map +1 -1
- package/dist/schemas/library/life.js +2 -2
- package/dist/schemas/library/life.js.map +1 -1
- package/dist/schemas/library/media.d.ts +148 -541
- package/dist/schemas/library/media.d.ts.map +1 -1
- package/dist/schemas/library/media.js +28 -64
- package/dist/schemas/library/media.js.map +1 -1
- package/dist/schemas/library/money.d.ts +8 -8
- package/dist/schemas/library/money.d.ts.map +1 -1
- package/dist/schemas/library/money.js +4 -4
- package/dist/schemas/library/money.js.map +1 -1
- package/dist/schemas/library/planning.d.ts +23 -87
- package/dist/schemas/library/planning.d.ts.map +1 -1
- package/dist/schemas/library/planning.js +10 -26
- package/dist/schemas/library/planning.js.map +1 -1
- package/dist/schemas/library/publishing.d.ts +14 -14
- package/dist/schemas/library/publishing.d.ts.map +1 -1
- package/dist/schemas/library/publishing.js +7 -7
- package/dist/schemas/library/publishing.js.map +1 -1
- package/dist/schemas/library/social.d.ts +2 -2
- package/dist/schemas/library/social.d.ts.map +1 -1
- package/dist/schemas/library/social.js +1 -1
- package/dist/schemas/library/social.js.map +1 -1
- package/dist/schemas/standard.d.ts +1 -1
- package/dist/schemas/standard.d.ts.map +1 -1
- package/dist/schemas/standard.js +3 -3
- package/dist/schemas/standard.js.map +1 -1
- package/dist/session/auth.js +1 -1
- package/dist/session/auth.js.map +1 -1
- package/dist/space/account-registry.d.ts +22 -0
- package/dist/space/account-registry.d.ts.map +1 -1
- package/dist/space/account-registry.js +18 -0
- package/dist/space/account-registry.js.map +1 -1
- package/dist/space/invitation.d.ts +61 -0
- package/dist/space/invitation.d.ts.map +1 -0
- package/dist/space/invitation.js +84 -0
- package/dist/space/invitation.js.map +1 -0
- package/dist/space/invite-link.d.ts +64 -0
- package/dist/space/invite-link.d.ts.map +1 -0
- package/dist/space/invite-link.js +212 -0
- package/dist/space/invite-link.js.map +1 -0
- package/dist/space/space-manager.d.ts +21 -6
- package/dist/space/space-manager.d.ts.map +1 -1
- package/dist/space/space-manager.js +40 -23
- package/dist/space/space-manager.js.map +1 -1
- package/dist/types.d.ts +2 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/docs/README.md +2 -2
- package/docs/actions.md +37 -37
- package/docs/automations.md +2 -2
- package/docs/blueprints-and-guides.md +44 -3
- package/docs/building-an-app.md +2 -2
- package/docs/contacts.md +48 -69
- package/docs/inbox.md +145 -0
- package/docs/node.md +36 -23
- package/docs/query-format.md +1 -1
- package/docs/spaces.md +33 -5
- package/docs/standard-library.md +111 -86
- package/package.json +5 -5
- package/dist/doors/doors.d.ts +0 -140
- package/dist/doors/doors.d.ts.map +0 -1
- package/dist/doors/doors.js +0 -226
- package/dist/doors/doors.js.map +0 -1
- package/dist/doors/index.d.ts +0 -9
- package/dist/doors/index.d.ts.map +0 -1
- package/dist/doors/index.js +0 -7
- package/dist/doors/index.js.map +0 -1
- 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,
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
722
|
-
|
|
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
|
-
##
|
|
999
|
-
|
|
1000
|
-
`node.
|
|
1001
|
-
|
|
1002
|
-
| Call
|
|
1003
|
-
|
|
|
1004
|
-
| `
|
|
1005
|
-
| `open({
|
|
1006
|
-
| `
|
|
1007
|
-
| `clear(
|
|
1008
|
-
| `knock(code, { note? })`
|
|
1009
|
-
| `knocks()`
|
|
1010
|
-
| `sent()`
|
|
1011
|
-
| `accept(id)`
|
|
1012
|
-
| `dismiss(id)`
|
|
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
|
|
package/docs/query-format.md
CHANGED
|
@@ -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:
|
|
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
|
-
|
|
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
|
|
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
|
|