@minca/core 0.1.9 → 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 +2 -2
- package/dist/identity/abilities.d.ts +3 -3
- package/dist/identity/abilities.d.ts.map +1 -1
- package/dist/identity/abilities.js +9 -11
- package/dist/identity/abilities.js.map +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/identity/root-signer.d.ts +0 -5
- package/dist/identity/root-signer.d.ts.map +1 -1
- package/dist/identity/root-signer.js +0 -1
- package/dist/identity/root-signer.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 +3 -3
- 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 +720 -542
- package/dist/node/node.js.map +1 -1
- package/dist/node/remote.d.ts +6 -5
- package/dist/node/remote.d.ts.map +1 -1
- package/dist/node/remote.js +140 -195
- 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 +71 -84
- package/dist/node/space-runtime.js.map +1 -1
- package/dist/node/types.d.ts +84 -47
- package/dist/node/types.d.ts.map +1 -1
- package/dist/node/worker.d.ts +1 -1
- package/dist/node/worker.d.ts.map +1 -1
- package/dist/node/worker.js +10 -6
- package/dist/node/worker.js.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.d.ts +20 -0
- package/dist/session/auth.d.ts.map +1 -1
- package/dist/session/auth.js +81 -64
- package/dist/session/auth.js.map +1 -1
- package/dist/session/connect.d.ts +50 -8
- package/dist/session/connect.d.ts.map +1 -1
- package/dist/session/connect.js +91 -27
- package/dist/session/connect.js.map +1 -1
- package/dist/session/connection.d.ts +39 -6
- package/dist/session/connection.d.ts.map +1 -1
- package/dist/session/connection.js +107 -38
- package/dist/session/connection.js.map +1 -1
- package/dist/session/hosting.d.ts +15 -0
- package/dist/session/hosting.d.ts.map +1 -1
- package/dist/session/hosting.js +55 -4
- package/dist/session/hosting.js.map +1 -1
- package/dist/session/index.d.ts +5 -5
- package/dist/session/index.d.ts.map +1 -1
- package/dist/session/index.js +2 -2
- package/dist/session/index.js.map +1 -1
- package/dist/space/account-registry.d.ts +36 -4
- package/dist/space/account-registry.d.ts.map +1 -1
- package/dist/space/account-registry.js +30 -3
- 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/roles.d.ts +59 -140
- package/dist/space/roles.d.ts.map +1 -1
- package/dist/space/roles.js +328 -427
- package/dist/space/roles.js.map +1 -1
- 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 +40 -40
- package/docs/agents.md +2 -2
- package/docs/automations.md +2 -2
- package/docs/blueprints-and-guides.md +61 -1
- package/docs/bots.md +1 -1
- package/docs/building-an-app.md +2 -2
- package/docs/contacts.md +48 -69
- package/docs/inbox.md +145 -0
- package/docs/node.md +135 -76
- package/docs/query-format.md +1 -1
- package/docs/sign-in.md +16 -9
- package/docs/spaces.md +33 -5
- package/docs/standard-library.md +111 -86
- package/docs/storage.md +1 -1
- 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
|
|
|
@@ -55,12 +55,16 @@ A node acts for one account (`node.did`) and signs with one session key
|
|
|
55
55
|
(`node.sessionDid`) for its whole lifetime. To act for another account, start
|
|
56
56
|
another node.
|
|
57
57
|
|
|
58
|
-
`
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
58
|
+
`revokeKey(key, { spaces?, waitMs? })` revokes a key of the account, each
|
|
59
|
+
revoke with a cutoff at what the key wrote: in `spaces`, or by default
|
|
60
|
+
wherever the account writes (every space it lists, its carry spaces, the
|
|
61
|
+
contacts space and the account registry). It says whether a peer took each in
|
|
62
|
+
within `waitMs`. The account home's disconnect calls it for an app's key.
|
|
63
|
+
`revokeSelf()` does the same for the node's own session key, and forgets a
|
|
64
|
+
lasting key at once; the account home's sign-out calls it
|
|
65
|
+
([spec 01 §7.4](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md)).
|
|
66
|
+
A record is judged with no time, so a revoke, not the note running out, is
|
|
67
|
+
what ends what a key can write. An agent's view refuses both.
|
|
64
68
|
|
|
65
69
|
`close()` stops renewal, closes every open space (flushing what each keeps,
|
|
66
70
|
stopping sync and disconnecting its transports), closes the registry store,
|
|
@@ -76,11 +80,10 @@ which hides where the key lives and is asked only for notes. This is an
|
|
|
76
80
|
in-process interface, not a wire format; what a note must be is
|
|
77
81
|
[spec 01 §7](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md).
|
|
78
82
|
|
|
79
|
-
| Member | Type
|
|
80
|
-
| -------------------------------------------------------------- |
|
|
81
|
-
| `did` | string
|
|
82
|
-
| `
|
|
83
|
-
| `delegate({audience, command, subject?, policy?, expiration})` | → `Delegation` | Issue a note from the account to `audience` |
|
|
83
|
+
| Member | Type | Meaning |
|
|
84
|
+
| -------------------------------------------------------------- | -------------- | ------------------------------------------- |
|
|
85
|
+
| `did` | string | The account DID |
|
|
86
|
+
| `delegate({audience, command, subject?, policy?, expiration})` | → `Delegation` | Issue a note from the account to `audience` |
|
|
84
87
|
|
|
85
88
|
- The **local** signer (`createLocalRootSigner`) calls `issueDelegation` with
|
|
86
89
|
the root key. `subject` defaults to the account's own DID (the whole
|
|
@@ -89,6 +92,12 @@ in-process interface, not a wire format; what a note must be is
|
|
|
89
92
|
already issued to the app's key, unchanged, and refuses once the grant's
|
|
90
93
|
`expiresAt` has passed. It cannot mint new notes
|
|
91
94
|
([spec 06 §2](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
95
|
+
- A signer **across a port** (`serveSigner` on the side that holds the key,
|
|
96
|
+
`remoteSigner` on the node's, as a page signs for its worker's node) signs
|
|
97
|
+
only notes of the session note's shape below: `command` `/`, no `subject`,
|
|
98
|
+
no `policy`. It refuses anything else without asking the signer behind it.
|
|
99
|
+
The audience and expiration are the far end's to pick, so it bounds
|
|
100
|
+
neither.
|
|
92
101
|
|
|
93
102
|
The **session note** a node asks for when it starts:
|
|
94
103
|
|
|
@@ -124,7 +133,7 @@ policy statement it can't read that way, so it never offers more than the
|
|
|
124
133
|
note grants; peers judge each use against the note itself
|
|
125
134
|
([spec 06 §2.5](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
126
135
|
|
|
127
|
-
_Source: `packages/core/src/identity/root-signer.ts`, `packages/core/src/identity/ucan.ts` (`issueDelegation`, `verifyNote`), `packages/core/src/identity/abilities.ts` (`noteTerms`, `noteSpaces`), `packages/core/src/node/node.ts` (`SESSION_COMMAND`, `delegate`), `packages/core/src/session/connect.ts` (`grantSigner`, `grantTerms`). Tests: `packages/core/tests/ucan.test.ts`, `packages/core/tests/node.test.ts`, `packages/core/tests/connect.test.ts`._
|
|
136
|
+
_Source: `packages/core/src/identity/root-signer.ts`, `packages/core/src/node/remote.ts` (`serveSigner`, `remoteSigner`), `packages/core/src/identity/ucan.ts` (`issueDelegation`, `verifyNote`), `packages/core/src/identity/abilities.ts` (`noteTerms`, `noteSpaces`), `packages/core/src/node/node.ts` (`SESSION_COMMAND`, `delegate`), `packages/core/src/session/connect.ts` (`grantSigner`, `grantTerms`). Tests: `packages/core/tests/ucan.test.ts`, `packages/core/tests/remote.test.ts` ("the page's signer, from a worker"), `packages/core/tests/node.test.ts`, `packages/core/tests/connect.test.ts`._
|
|
128
137
|
|
|
129
138
|
## Renewing the session note
|
|
130
139
|
|
|
@@ -142,7 +151,9 @@ The note format, and that every record carries it, are protocol
|
|
|
142
151
|
|
|
143
152
|
A signer need not be able to sign. `grantSigner(grant)` answers every
|
|
144
153
|
`delegate` call with the one note an account home granted, unchanged, and
|
|
145
|
-
refuses once `grant.expiresAt` has passed.
|
|
154
|
+
refuses once `grant.expiresAt` has passed. `grantSigner(() => grant)` answers
|
|
155
|
+
with whichever grant the getter returns, as the desktop app's node does when
|
|
156
|
+
a renewed grant replaces the last. A node started from a grant
|
|
146
157
|
therefore never gets a fresh note: its "renewal" returns the same note, and when
|
|
147
158
|
it runs out the app must connect again ([spec 06 §2.9](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
148
159
|
|
|
@@ -301,8 +312,8 @@ needs no grant. A founder who leaves is a founder no more, for good; to stay
|
|
|
301
312
|
without being one, `spaces.stepDown`
|
|
302
313
|
([spaces](spaces.md#the-top-and-founders)). Then it deletes
|
|
303
314
|
the space's `sys.joined` record in the account registry, closes the space and
|
|
304
|
-
forgets it with its keys. The account registry
|
|
305
|
-
be left.
|
|
315
|
+
forgets it with its keys. The account registry, the contacts space and carry
|
|
316
|
+
spaces cannot be left.
|
|
306
317
|
|
|
307
318
|
- The removal goes out only while the space is open, so `leave` waits up to
|
|
308
319
|
5 s for a peer of another account to say it has it. With nobody reachable,
|
|
@@ -317,7 +328,7 @@ be left.
|
|
|
317
328
|
|
|
318
329
|
`contacts.remove` and `contacts.block` leave the space for two this way.
|
|
319
330
|
|
|
320
|
-
_Source: `packages/core/src/node/node.ts` (`spaces.leave`, `giveUpPlace`, `forget`, `LEAVE_WAIT_MS`), `packages/core/src/node/space-runtime.ts` (`giveUpPlace`). Tests: `packages/core/tests/key-change.test.ts` ("leaving a private space"), `packages/core/tests/contacts.test.ts` ("removing a contact gives up your place"), `packages/core/tests/node.test.ts` ("the account registry")._
|
|
331
|
+
_Source: `packages/core/src/node/node.ts` (`spaces.leave`, `giveUpPlace`, `forget`, `LEAVE_WAIT_MS`), `packages/core/src/node/space-runtime.ts` (`giveUpPlace`). Tests: `packages/core/tests/key-change.test.ts` ("leaving a private space"), `packages/core/tests/contacts.test.ts` ("removing a contact gives up your place"), `packages/core/tests/node.test.ts` ("the account registry"), `packages/core/tests/carrier.test.ts` ("its carry space cannot be left…")._
|
|
321
332
|
|
|
322
333
|
## Holding part of a space
|
|
323
334
|
|
|
@@ -407,26 +418,23 @@ Three kinds of space are the account's own machinery and are hidden from
|
|
|
407
418
|
| -------------------- | ------------------------------------------ | -------------------------------------------------------------- |
|
|
408
419
|
| The account registry | the account key | Never in the node's registry; opened directly. Cannot be left. |
|
|
409
420
|
| The contacts space | the account key, or `config.contactsSpace` | Held in the registry, hidden. Cannot be left. |
|
|
410
|
-
| Carry spaces |
|
|
421
|
+
| Carry spaces | the account key and the carrier's key | Never in the node's registry; opened directly. Cannot be left. |
|
|
411
422
|
|
|
412
423
|
**Reconciling.** With an account key, the node makes its spaces match the
|
|
413
424
|
account's list of `sys.joined` records. This runs at start and whenever
|
|
414
425
|
records change in the account registry, one run at a time. It:
|
|
415
426
|
|
|
416
|
-
1. joins every
|
|
417
|
-
forgets one whose carrier was removed more than 30 days ago (kept open until
|
|
418
|
-
then, so an offline carrier still hears it was removed);
|
|
419
|
-
2. joins every space a live `sys.joined` record names that the node does not
|
|
427
|
+
1. joins every space a live `sys.joined` record names that the node does not
|
|
420
428
|
hold, using the view-only invite in the record;
|
|
421
|
-
|
|
422
|
-
|
|
429
|
+
2. leaves every space whose `sys.joined` record is deleted;
|
|
430
|
+
3. writes a `sys.joined` record for any space held here that the account
|
|
423
431
|
registry has never heard of (joined before the registry existed, or on a
|
|
424
432
|
node without the account key);
|
|
425
|
-
|
|
433
|
+
4. brings every carrier's passes and wakes up to date
|
|
426
434
|
([spec 06 §4.2](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md));
|
|
427
|
-
|
|
435
|
+
5. names the account's carriers as keepers of the open spaces it manages
|
|
428
436
|
(also whenever a space opens);
|
|
429
|
-
|
|
437
|
+
6. asks every host the account uses how it stands, handing it the spaces if it
|
|
430
438
|
has been paid since ([carriers and hosting](#carriers-hosting-and-notifications)),
|
|
431
439
|
without waiting for the answer.
|
|
432
440
|
|
|
@@ -442,7 +450,8 @@ and never under a note that lacks `/account/write`, such as an agent's. The prof
|
|
|
442
450
|
[03](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
|
|
443
451
|
|
|
444
452
|
**Joining.** `spaces.join(invite)` accepts a bare invite or any link carrying
|
|
445
|
-
`#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
|
|
446
455
|
a private space), stores `memberKey` when given, writes the `sys.joined`
|
|
447
456
|
record, then tries to use the invite's role secret at once. If the space's
|
|
448
457
|
invite record has not reached this device yet, the space is held with
|
|
@@ -603,7 +612,7 @@ successors, mine, heads, key, relays, keepers, copies, forks, flagged }`
|
|
|
603
612
|
account (whole-account access).
|
|
604
613
|
- `node.direct` — [direct-messages.md](direct-messages.md): `reachable`, `send`
|
|
605
614
|
and `list`. Needs the account's member key for the space.
|
|
606
|
-
- `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
|
|
607
616
|
accepting also need whole-account access.
|
|
608
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).
|
|
609
618
|
- `node.iceServers()` — the configured ICE servers plus TURN servers a relay
|
|
@@ -699,21 +708,23 @@ throws unless the note verifies, grants records only (its command is under
|
|
|
699
708
|
or deleting collections; live messages (`send`, which a person's devices
|
|
700
709
|
would take as theirs); renaming or revoking at the account level; adding or
|
|
701
710
|
removing carriers; notifications; hosting; changing, blocking, asking or
|
|
702
|
-
accepting contacts; everything about
|
|
711
|
+
accepting contacts; everything about the inbox (it has none);
|
|
703
712
|
`delegate`; `asAgent`;
|
|
704
713
|
- sees the contact list only if the contacts space is within its note.
|
|
705
714
|
|
|
706
|
-
Closing the agent leaves the underlying node running.
|
|
715
|
+
Closing the agent leaves the underlying node running. A node used across a
|
|
716
|
+
port (`remoteNode`) starts no agent: the agent's keys would have to cross, so
|
|
717
|
+
an agent is started on the node itself.
|
|
707
718
|
|
|
708
719
|
An agent granted `scope: account` gets a records-only note for every space
|
|
709
720
|
(`/record`, about the whole account) and the account key in its
|
|
710
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
|
|
711
|
-
gives a records-only key the contact key: with it, it could open
|
|
712
|
-
|
|
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)).
|
|
713
724
|
|
|
714
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.
|
|
715
726
|
|
|
716
|
-
_Source: `packages/core/src/node/node.ts` (`asAgent`), `packages/core/src/node/api.ts` (`API`). Tests: `packages/core/tests/records-only.test.ts` ("an agent acting for a person"), `packages/core/tests/remote.test.ts
|
|
727
|
+
_Source: `packages/core/src/node/node.ts` (`asAgent`), `packages/core/src/node/api.ts` (`API`). Tests: `packages/core/tests/records-only.test.ts` ("an agent acting for a person"), `packages/core/tests/remote.test.ts` ("no agent is started across the port…")._
|
|
717
728
|
|
|
718
729
|
## The app-side client
|
|
719
730
|
|
|
@@ -742,8 +753,7 @@ account: connecting as another account deletes the last one's, so its
|
|
|
742
753
|
spaces never reach the new one's registry. Copied without the keychain, the
|
|
743
754
|
folder yields no key, grant or private body, only what a carrier sees; a
|
|
744
755
|
program running as the person can ask the keychain, as it can read a
|
|
745
|
-
browser profile. Renewing keeps the key
|
|
746
|
-
revoke the last, withdrawing what the app wrote that the home hadn't seen.
|
|
756
|
+
browser profile. Renewing keeps the key (a page's app asks with a new one each time, below).
|
|
747
757
|
The key changes only when the app leaves an account: disconnecting, from the
|
|
748
758
|
app or at the home, forgets it (`forgetAppKey` in a page), so a revoked key
|
|
749
759
|
stays revoked. A home that answers as another account than the one connected
|
|
@@ -778,29 +788,67 @@ closed it, and gives up after 10 minutes by default.
|
|
|
778
788
|
starts a node with:
|
|
779
789
|
|
|
780
790
|
- `signer = grantSigner(grant)` ([renewing the session note](#renewing-the-session-note)):
|
|
781
|
-
`did` = `grant.did
|
|
791
|
+
`did` = `grant.did`;
|
|
782
792
|
- `sessionKey` = the app's key;
|
|
783
793
|
- stores `indexedDBStores('minca-app:<grant.did>')` unless given;
|
|
784
794
|
- `cache: {}` unless `cache: false` ([holding part of a space](#holding-part-of-a-space));
|
|
785
|
-
- `accountKey`, `contactKey`, `contactsSpace` from the grant when present
|
|
786
|
-
|
|
795
|
+
- `accountKey`, `contactKey`, `contactsSpace` from the grant when present (never `contactKey` under a records-only note), and
|
|
796
|
+
relays = the app's relays ∪ `grant.relays` (`nodeOptionsFromGrant`).
|
|
787
797
|
|
|
788
|
-
It then joins each granted space it does not hold yet, passing its `memberKey
|
|
798
|
+
It then joins each granted space it does not hold yet, passing its `memberKey`
|
|
799
|
+
(`joinGranted`). The desktop app's node (`minca app-node`) and the agent on a
|
|
800
|
+
computer start theirs from a grant the same way, from their own folders.
|
|
789
801
|
|
|
790
|
-
**The connection.** `createMincaConnection({ home, request, network?, storage?, stores? })`
|
|
802
|
+
**The connection.** `createMincaConnection({ home, request, network?, storage?, stores?, worker?, keys?, account? })`
|
|
791
803
|
is the app's twin of [sign-in](sign-in.md): statuses `starting`, `disconnected`,
|
|
792
804
|
`connecting`, `ready`, `expired`. With `worker`, it runs the node there
|
|
793
805
|
(`startNodeInWorker`); a worker that reports a load error, or does not say the
|
|
794
806
|
node started within 30 s (`WorkerNotStarted`), is given up on and the node
|
|
795
|
-
runs in the page. A worker that started and refused passes its reason on.
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
a space it emits `revoked` ([events](#events)), and the connection forgets the
|
|
801
|
-
grant and the app key. `propose(automations)` sends a proposal to the grant's home
|
|
807
|
+
runs in the page. A worker that started and refused passes its reason on.
|
|
808
|
+
It switches to `expired` at `expiresAt` (`watchGrant`). When the node sees its
|
|
809
|
+
own note revoked in a space it emits `revoked` ([events](#events)), and the
|
|
810
|
+
connection forgets that account's grant and key. `propose(automations)` sends
|
|
811
|
+
a proposal to the grant's home
|
|
802
812
|
([spec 06 §2.11](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
803
813
|
|
|
814
|
+
**Several accounts.** The connection keeps a grant for every account the
|
|
815
|
+
person connects, and acts for one at a time; `state.accounts` lists them
|
|
816
|
+
(`did`, the `name` the home gave, `expiresAt`), in the order they were first
|
|
817
|
+
connected. Each grant is made out to a key of its own, named
|
|
818
|
+
`account-<uuid>` in `appKey`'s store (or `keys`, given), so peers never see
|
|
819
|
+
one key act for two accounts. They are kept in `localStorage` under
|
|
820
|
+
`minca.grants` (`[{ grant, keyName }]`), the account acted for last under
|
|
821
|
+
`minca.account`, and the person's chosen home under `minca.home` (`home` in
|
|
822
|
+
the config is only a default). A grant of another format (`v` other than
|
|
823
|
+
`GRANT_VERSION`, 2) is dropped when read; one that ran out stays, and opens
|
|
824
|
+
as `expired`.
|
|
825
|
+
|
|
826
|
+
- `start()` acts for the account `account(accounts)` names, else the one used
|
|
827
|
+
last, else the first.
|
|
828
|
+
- `use(did)` acts for another connected account. Its grant is here, so the
|
|
829
|
+
home is not asked; the node acting for the last one closes, and one for
|
|
830
|
+
this one starts, with its own stores.
|
|
831
|
+
- `connect(home?)` asks with a new key, and acts for whichever account the
|
|
832
|
+
person chooses at the home: a new one, or one connected already, whose grant
|
|
833
|
+
it renews. A key that asked once may hold a note from whatever account the
|
|
834
|
+
home was signed in as, so no key is asked with twice. An account connected
|
|
835
|
+
again gets the new key and the app forgets the old one; the home revokes
|
|
836
|
+
nothing, and what the old key wrote stands
|
|
837
|
+
([spec 06 §2.10](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
838
|
+
While it waits, an app acting for an account stays `ready`; a grant whose
|
|
839
|
+
node won't start is kept, and the connection says `disconnected` with why.
|
|
840
|
+
- `disconnect(did?)` forgets an account's grant and key (default the one
|
|
841
|
+
acted for) and acts for the next connected account, or none. Disconnected
|
|
842
|
+
at the home instead, it acts for none, with `error` saying why, rather than
|
|
843
|
+
another account the person didn't choose.
|
|
844
|
+
|
|
845
|
+
Another tab's changes reach `state.accounts` by `storage` events; each tab
|
|
846
|
+
acts for its own account. A tab whose account another tab connected again
|
|
847
|
+
goes on with its key until it starts again, then takes the newer grant; one
|
|
848
|
+
whose key is revoked takes up a newer grant rather than forgetting it. A
|
|
849
|
+
shared worker runs a node per key, not only per account, so tabs on two keys
|
|
850
|
+
never share one. Switching again before a node has started closes it.
|
|
851
|
+
|
|
804
852
|
**Showing notifications.** The app shows its own notifications.
|
|
805
853
|
`watchNotifications(node, { origin?, onNotify })` needs the account key (an
|
|
806
854
|
app with `scope: account`): it reads the account's own automations naming the
|
|
@@ -814,20 +862,19 @@ held the first time an automation made it look there; anything arriving after th
|
|
|
814
862
|
is, even while the account or the list of spaces changes. How the app shows a match is its own
|
|
815
863
|
to decide; a "Notify me" button is where a proposal usually starts.
|
|
816
864
|
|
|
817
|
-
_Source: `packages/core/src/session/connect.ts` (`appKey`, `forgetAppKey`, `homeAddress`, `connectToHome`, `proposeToHome`, `startConnectedNode`, `grantSigner`), `packages/core/src/session/connection.ts`, `packages/core/src/node/watch-notifications.ts`, `packages/core/src/space/own-automations.ts` (`matchesRecord`). Tests: `packages/core/tests/connect.test.ts` ("an account home typed by a person", "an app showing its own notifications"), `packages/core/tests/topics.test.ts` ("an automation of the account’s own: its where"), `packages/core/tests/watch-notifications.test.ts`._
|
|
865
|
+
_Source: `packages/core/src/session/connect.ts` (`appKey`, `forgetAppKey`, `homeAddress`, `connectToHome`, `proposeToHome`, `startConnectedNode`, `nodeOptionsFromGrant`, `joinGranted`, `grantSigner`, `usableGrant`, `watchGrant`, `grantStore`), `packages/cli/src/app-node.ts` (`startDesktopNode`), `packages/core/src/session/connection.ts`, `packages/core/src/node/watch-notifications.ts`, `packages/core/src/space/own-automations.ts` (`matchesRecord`). Tests: `packages/core/tests/connect.test.ts` ("an account home typed by a person", "watching a grant", "an app connected to several accounts", "an app showing its own notifications"), `packages/core/tests/topics.test.ts` ("an automation of the account’s own: its where"), `packages/core/tests/watch-notifications.test.ts`._
|
|
818
866
|
|
|
819
867
|
## Carriers, hosting and notifications
|
|
820
868
|
|
|
821
869
|
What goes into a carry space, what a carrier checks and the host's HTTP API
|
|
822
870
|
are protocol ([spec 06 §4](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)). The reference node's side:
|
|
823
871
|
|
|
824
|
-
**Carriers.** `node.carriers.add({ did, name })` (needs the account key)
|
|
825
|
-
the carry space,
|
|
826
|
-
`Carrier`),
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
a space the account uses. A node that starts, or hears the registry change,
|
|
872
|
+
**Carriers.** `node.carriers.add({ did, name })` (needs the account key)
|
|
873
|
+
derives the carry space, writes the `sys.carrier` record (name trimmed to 80,
|
|
874
|
+
default `Carrier`), fills the carry space, and returns `{ space, invite }` for
|
|
875
|
+
the carrier to join with; for a carrier it already has, by `did`, it returns
|
|
876
|
+
that one's. Carry spaces are never kept in the node's own list: each is
|
|
877
|
+
derived again from its record. A node that starts, or hears the registry change,
|
|
831
878
|
refills every carrier's carry space in the background: it opens every space
|
|
832
879
|
the account holds, which from a data folder is slow, and signing in doesn't
|
|
833
880
|
wait for it. Adding an automation doesn't either (adding a carrier writes that
|
|
@@ -838,8 +885,20 @@ waits up to `waitMs` for the node to be level with the carrier in the carry
|
|
|
838
885
|
space and then the account registry, and says whether it was: a node about to
|
|
839
886
|
close (the home's window, once it has answered) waits on it, so what it wrote
|
|
840
887
|
for the carrier is not left with nobody (spec 06 §4.3). `node.carriers.remove(carrySpace)`
|
|
841
|
-
writes `carry:closed` and
|
|
842
|
-
open
|
|
888
|
+
writes `carry:closed` and marks the record removed; the node keeps the carry
|
|
889
|
+
space open until it closes, so the carrier hears it.
|
|
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…")._
|
|
843
902
|
|
|
844
903
|
**The account's own automations.** `node.automations` (needs the account
|
|
845
904
|
key) lists, adds, updates (`name`, `paused`) and removes the account's own
|
|
@@ -851,7 +910,7 @@ person to pause or remove ([sign-in](sign-in.md#the-account-homes-side)).
|
|
|
851
910
|
**A carrier's matches.** `CarrierNode` reports a version that wakes one of
|
|
852
911
|
the account's wakes through a `wake` event, with only the wake, the space and
|
|
853
912
|
the record's key, collection and `createdAt`; `wakes()` lists the wakes it
|
|
854
|
-
holds.
|
|
913
|
+
holds. The desktop app shows them as notifications (`apps/desktop/src/bun/notify.ts`); the browser extension shows none yet.
|
|
855
914
|
|
|
856
915
|
**Hosting.** `node.hosting`:
|
|
857
916
|
|
|
@@ -949,21 +1008,21 @@ paid, and what is in the fund stays there
|
|
|
949
1008
|
|
|
950
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)._
|
|
951
1010
|
|
|
952
|
-
##
|
|
953
|
-
|
|
954
|
-
`node.
|
|
955
|
-
|
|
956
|
-
| Call
|
|
957
|
-
|
|
|
958
|
-
| `
|
|
959
|
-
| `open({
|
|
960
|
-
| `
|
|
961
|
-
| `clear(
|
|
962
|
-
| `knock(code, { note? })`
|
|
963
|
-
| `knocks()`
|
|
964
|
-
| `sent()`
|
|
965
|
-
| `accept(id)`
|
|
966
|
-
| `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 |
|
|
967
1026
|
|
|
968
1027
|
## Client conveniences
|
|
969
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
|
|