@minca/core 0.1.17 → 0.1.18

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 (86) hide show
  1. package/README.md +2 -1
  2. package/dist/files/space-files.d.ts +2 -2
  3. package/dist/files/space-files.d.ts.map +1 -1
  4. package/dist/files/space-files.js +7 -5
  5. package/dist/files/space-files.js.map +1 -1
  6. package/dist/inbox/names.d.ts +1 -1
  7. package/dist/inbox/names.js +1 -1
  8. package/dist/index.d.ts +2 -0
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.js +2 -0
  11. package/dist/index.js.map +1 -1
  12. package/dist/node/actions.d.ts +3 -0
  13. package/dist/node/actions.d.ts.map +1 -1
  14. package/dist/node/actions.js.map +1 -1
  15. package/dist/node/api.d.ts +1 -0
  16. package/dist/node/api.d.ts.map +1 -1
  17. package/dist/node/api.js +1 -0
  18. package/dist/node/api.js.map +1 -1
  19. package/dist/node/carrier.js +1 -1
  20. package/dist/node/carrier.js.map +1 -1
  21. package/dist/node/node-contacts.d.ts.map +1 -1
  22. package/dist/node/node-contacts.js +1 -0
  23. package/dist/node/node-contacts.js.map +1 -1
  24. package/dist/node/node-records.d.ts.map +1 -1
  25. package/dist/node/node-records.js +6 -1
  26. package/dist/node/node-records.js.map +1 -1
  27. package/dist/node/node.d.ts.map +1 -1
  28. package/dist/node/node.js +13 -1
  29. package/dist/node/node.js.map +1 -1
  30. package/dist/node/remote.d.ts.map +1 -1
  31. package/dist/node/remote.js +7 -1
  32. package/dist/node/remote.js.map +1 -1
  33. package/dist/node/space-runtime.d.ts +5 -3
  34. package/dist/node/space-runtime.d.ts.map +1 -1
  35. package/dist/node/space-runtime.js +3 -1
  36. package/dist/node/space-runtime.js.map +1 -1
  37. package/dist/node/types.d.ts +112 -36
  38. package/dist/node/types.d.ts.map +1 -1
  39. package/dist/query/types.d.ts +1 -0
  40. package/dist/query/types.d.ts.map +1 -1
  41. package/dist/query/types.js.map +1 -1
  42. package/dist/records/contract-builder.d.ts +22 -6
  43. package/dist/records/contract-builder.d.ts.map +1 -1
  44. package/dist/records/contract-builder.js.map +1 -1
  45. package/dist/schemas/automations.d.ts +6 -2
  46. package/dist/schemas/automations.d.ts.map +1 -1
  47. package/dist/schemas/automations.js.map +1 -1
  48. package/dist/schemas/connectors.d.ts +4 -3
  49. package/dist/schemas/connectors.d.ts.map +1 -1
  50. package/dist/schemas/connectors.js +4 -3
  51. package/dist/schemas/connectors.js.map +1 -1
  52. package/dist/schemas/library/media.js +1 -1
  53. package/dist/schemas/library/media.js.map +1 -1
  54. package/dist/session/auth.d.ts +7 -3
  55. package/dist/session/auth.d.ts.map +1 -1
  56. package/dist/session/auth.js.map +1 -1
  57. package/dist/storage/blob-store.d.ts +3 -0
  58. package/dist/storage/blob-store.d.ts.map +1 -1
  59. package/dist/types.d.ts +11 -2
  60. package/dist/types.d.ts.map +1 -1
  61. package/dist/types.js.map +1 -1
  62. package/docs/README.md +86 -93
  63. package/docs/actions.md +213 -152
  64. package/docs/agents.md +198 -167
  65. package/docs/automations.md +296 -204
  66. package/docs/blueprints-and-guides.md +405 -311
  67. package/docs/bots.md +208 -134
  68. package/docs/building-an-app.md +74 -163
  69. package/docs/collections.md +248 -328
  70. package/docs/computed.md +112 -89
  71. package/docs/contacts.md +151 -112
  72. package/docs/contracts.md +299 -120
  73. package/docs/direct-messages.md +80 -65
  74. package/docs/inbox.md +138 -93
  75. package/docs/node.md +1072 -996
  76. package/docs/permissions.md +142 -0
  77. package/docs/proposing-collections.md +74 -55
  78. package/docs/query-format.md +150 -126
  79. package/docs/records-and-queries.md +205 -126
  80. package/docs/sign-in.md +496 -418
  81. package/docs/spaces.md +261 -246
  82. package/docs/standard-library.md +473 -526
  83. package/docs/storage.md +325 -348
  84. package/docs/usernames.md +164 -97
  85. package/docs/warrants.md +100 -67
  86. package/package.json +1 -1
@@ -1,28 +1,74 @@
1
1
  # Direct messages
2
2
 
3
- A direct message is text only some members of a space can read: the people
4
- it is for, and whoever wrote it. It is a `std.direct` record in the space,
5
- so it syncs, is kept and is deleted like any other. Its text is sealed, so
6
- the space key alone does not open it.
7
-
8
- This is a convention built on the protocol, not part of it. Peers that have
9
- never heard of `std.direct` sync, store and judge it like any other record,
10
- and nothing about the space changes for them. Only apps that want to read each
11
- other's direct messages have to agree on what follows. It uses these protocol
12
- parts: member keys ([spec 03 §9.1](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)),
13
- the space key's derivations (§8.1), the envelope and sealing to a key with
14
- HPKE ([spec 01 §9](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md)).
3
+ A direct message is text in a space that only some of its members can read:
4
+ the people it is for, and whoever wrote it. Use it for a private word inside
5
+ a shared space. Today it needs a private space.
15
6
 
16
- One record serves every reader and every one of their devices. A fresh
17
- **message key** seals the text once, and that key is sealed to each reader's
18
- member key. Members publish member keys only in private spaces, so today
19
- direct messages need a private space.
7
+ ## Sending and reading
8
+
9
+ ```typescript
10
+ const people = await node.direct.reachable(space.id); // who you can write to
11
+ await node.direct.send(space.id, people.slice(0, 1), 'See you at eight?');
12
+
13
+ const messages = await node.direct.list(space.id);
14
+ messages[0]?.text; // null when this node can't open it
15
+ ```
16
+
17
+ The methods are on
18
+ [`NodeDirect`](https://minca.dev/api/core/interfaces/NodeDirect/), and each
19
+ message is a
20
+ [`DirectMessage`](https://minca.dev/api/core/interfaces/DirectMessage/).
21
+
22
+ A message is a record, so it syncs and is kept like any other. Delete its
23
+ `key` to take it back.
24
+
25
+ A message is for 1–16 people besides you, and you can only write to someone
26
+ who has a member key in the space.
27
+
28
+ ## Who can read them
29
+
30
+ `node.direct` needs the account's member key for the space. An agent isn't
31
+ given one, so it may only call `reachable`.
32
+
33
+ That is the library refusing, not the sealing. An app or program granted the
34
+ whole account holds the key every member key comes from. One granted a
35
+ private space holds its member key. Either can open the account's direct
36
+ messages there with code of its own
37
+ ([threat model §3.6](https://github.com/leifriksheim/minca/blob/main/spec/threat-model.md)).
38
+
39
+ A bot is an account of its own, with its own member key, so it reads and
40
+ sends them like anyone. The actions `direct_list` and `direct_send`
41
+ ([actions](actions.md)) are offered to bots, not to agents. An automation set
42
+ off by a direct message hands the bot the message already opened.
43
+
44
+ ## What others see
45
+
46
+ In a private space the whole body is also encrypted with the space key, so
47
+ peers outside the space see only the envelope. Other members see who wrote to
48
+ whom, and when, but not what.
49
+
50
+ `to` is a topic, so "direct messages to me" can be an automation of the
51
+ account's own, which a keeper can match without reading the message
52
+ ([automations](automations.md#the-accounts-own)).
20
53
 
21
- A reader can't tell that the others read the same text: AES-GCM does not
22
- commit to its key, so a writer can seal boxes that open to different message
23
- keys, each opening `data` to a different text
54
+ A reader can't tell that the others read the same text. A writer can seal
55
+ each reader's copy to open to a different text
24
56
  ([#214](https://github.com/leifriksheim/minca/issues/214)).
25
57
 
58
+ ## How it works
59
+
60
+ One record serves every reader and every one of their devices. A fresh
61
+ **message key** seals the text once. That key is then sealed to each reader's
62
+ member key, in a **box** of their own.
63
+
64
+ This is a convention on the protocol, not part of it. Peers that have never
65
+ heard of `std.direct` sync, store and judge it like any other record. Only
66
+ apps that read each other's direct messages must agree on the format below.
67
+ It uses member keys
68
+ ([spec 03 §9.1](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)),
69
+ the space key's derivations (spec 03 §8.1), and the envelope and HPKE sealing
70
+ ([spec 01 §9](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md)).
71
+
26
72
  ## `std.direct`
27
73
 
28
74
  ```
@@ -34,15 +80,9 @@ std.direct (topics: to; no rules; who may write one is the space's grants)
34
80
  }
35
81
  ```
36
82
 
37
- The **writer** (`from`) is the root of the record's first version. The
83
+ The **writer**, `from`, is the root of the record's first version. The
38
84
  **readers** are every DID in `to`, and `from`.
39
85
 
40
- In a private space the whole body is also encrypted with the space key, so
41
- peers outside the space see only the envelope. Other members see `to`, `from`
42
- and when: who wrote to whom, not what. `to` is a topic, so "direct messages to
43
- me" is an automation of the account's own whose wake a keeper can match
44
- without reading it ([automations](automations.md#the-accounts-own)).
45
-
46
86
  ## Sealing
47
87
 
48
88
  ```
@@ -53,14 +93,14 @@ box(r) = HPKE(memberKey(r), "minca/direct-box/v1", { ...bound, reader: r }, JSO
53
93
  boxes = [ box(r) for r in to, then box(from) ]
54
94
  ```
55
95
 
56
- `sealKey(k)` is `HKDF(k, "minca/space-seal/v1", 32)`, as for any space key;
96
+ `sealKey(k)` is `HKDF(k, "minca/space-seal/v1", 32)`, as for any space key.
57
97
  `envelope` and `HPKE` are spec 01 §9.1 and §9.2.
58
98
 
59
- `memberKey(r)` is the key `r` published in `sys.memberkey`. The writer may use
60
- its own member key as it holds it, rather than as published, so its other
61
- devices can read what it sent before that key has been published. A writer
62
- must not write a direct message for someone with no member key in the space.
63
- `text` is a string of 1–10000 characters.
99
+ `memberKey(r)` is the key `r` published in `sys.memberkey`. The writer may
100
+ seal its own box to its member key as it holds it, rather than as published,
101
+ so its other devices can read what it sent before that key is published. A
102
+ writer must not write a direct message for someone with no member key in the
103
+ space.
64
104
 
65
105
  Example: space `space-1`, from `did:a`, to `did:c` and `did:b`. The text is
66
106
  bound to `{"from":"did:a","space":"space-1","to":"did:b,did:c"}`, and the box
@@ -70,8 +110,8 @@ for `did:b` to `{"from":"did:a","reader":"did:b","space":"space-1","to":"did:b,d
70
110
 
71
111
  A reader `r` opens a direct message only when the record verifies and stands,
72
112
  its collection is `std.direct`, and `r` is `from` or is in `to`. It builds the
73
- bound from the space the record is in, `from` and `to` as the record gives
74
- them (sorted), then:
113
+ bound from the space the record is in, and `from` and `to` as the record gives
114
+ them, sorted. Then it:
75
115
 
76
116
  1. takes the box whose `to` is `r`;
77
117
  2. opens it with its own member key, label `minca/direct-box/v1` and the
@@ -81,41 +121,16 @@ them (sorted), then:
81
121
  the bound, giving an object whose `text` is a string.
82
122
 
83
123
  If any step fails, the message is unreadable to `r`. A chat must show it as
84
- unreadable, not drop it, the way a body a reader can't open is shown.
124
+ unreadable, not drop it, the same as a body a reader can't open.
85
125
 
86
- Binding the text to the space, the writer and who it is for means a copy
126
+ Binding the text to the space, the writer and the readers means a copy
87
127
  re-posted by another member, moved to another space, or with a reader added
88
128
  to `to` opens nothing. Binding each box to its reader means a box can't be
89
- moved to another reader's slot.
90
-
91
- ## `node.direct`
92
-
93
- - `reachable(space)`: the members who have published a member key, not you.
94
- - `send(space, to, text)`: seals and writes a `std.direct`, and defines the
95
- collection first when the space lacks it and you may.
96
- - `list(space)`: every direct message by or for the account, oldest first,
97
- with `text: null` for one this node can't open.
98
-
99
- They need the account's member key for the space. An agent isn't given it, so
100
- an agent may only ask `reachable` through `node.direct`. That is the library's
101
- refusal, not sealing: an app or program granted the whole account holds the
102
- account key every member key derives from, and one granted a private space
103
- holds its member key, so either can open the account's direct messages there
104
- with code of its own ([threat model §3.6](../../../spec/threat-model.md)). A bot is an account of its own and holds
105
- one, so it reads and sends them like anyone: the actions `direct_list` and
106
- `direct_send` ([actions](actions.md)) are offered to bots, not to agents,
107
- and an automation set off by a direct message hands the bot the message opened.
108
-
109
- _Source:_ `packages/core/src/node/actions.ts` (`direct_list`, `direct_send`),
110
- `packages/core/src/node/actions.ts` (`offeredActions`), `packages/cli/src/agent-automations.ts`
111
- (`openTrigger`, `ruleContext`). Tests: `packages/core/tests/direct.test.ts`
112
- ("the direct message actions"), `packages/cli/tests/agent-automations.test.ts`.
113
-
114
- _Source: `packages/core/src/privacy/direct.ts` (`sealDirect`, `openDirect`, `directBound`), `packages/core/src/schemas/library/publishing.ts` (`direct`), `packages/core/src/node/node-records.ts` (`createNodeDirect`, `directView`), `packages/core/src/node/space-profiles.ts` (`memberKeys`), `packages/core/src/node/space-runtime.ts` (`ownMemberKey`), `apps/example/src/components/apps/DirectMessages.tsx`. Tests: `packages/core/tests/direct.test.ts`, `packages/core/tests/records-only.test.ts` ("neither sends nor reads direct messages")._
129
+ moved into another reader's slot.
115
130
 
116
131
  ## Planned: direct messages in public spaces
117
132
 
118
133
  Members publish member keys only in private spaces, so a public space has none
119
- to seal to. Publishing them in every space would let members of a public space
120
- write to each other. The text would then be protected only by the sealing
121
- above, with `to` visible to anyone.
134
+ to seal to. Publishing them in every space would let members of a public
135
+ space write to each other. The text would then be protected only by the
136
+ sealing above, with `to` visible to anyone.
package/docs/inbox.md CHANGED
@@ -1,41 +1,84 @@
1
1
  # The inbox
2
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.
3
+ An inbox is an address you hand out on purpose, so that someone you share no
4
+ space with can ask to become your contact. They knock, you accept, and you
5
+ both end up in a private space for two.
14
6
 
15
- ## `std.inbox`
7
+ ## Opening your inbox
16
8
 
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.
9
+ ```ts
10
+ const inbox = await node.inbox.open();
11
+ ```
20
12
 
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 |
13
+ `inbox.code` is what you hand out: in a link (`#inbox=…`), a QR code or a
14
+ bio. Or claim a [username](usernames.md), so people can find you by a name
15
+ they can say aloud.
26
16
 
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.
17
+ ## Knocking
18
+
19
+ On the other side, knock with the code, a link with it, or a username:
20
+
21
+ ```ts
22
+ declare const code: string;
23
+ // ---cut---
24
+ const { space, carried } = await node.inbox.knock(code, { note: 'We met at the meetup' });
25
+ ```
26
+
27
+ `space` is the new space for two. `carried` is false when none of your
28
+ always-on carriers held it in time, so they can join only while one of your
29
+ devices is online.
30
+
31
+ `node.inbox.sent()` lists your knocks nobody has joined yet. Once they join,
32
+ they become a contact on your side by themselves.
33
+
34
+ ## Answering knocks
35
+
36
+ ```ts
37
+ const [knock] = await node.inbox.knocks();
38
+ if (knock) {
39
+ const contact = await node.inbox.accept(knock.id);
40
+ }
41
+ ```
42
+
43
+ `accept` joins the space for two and puts them on your list. There is no
44
+ reply: joining is the answer. `dismiss(id)` lets a knock go, without
45
+ blocking whoever knocked.
46
+
47
+ `knocks()` fetches what is waiting. It doesn't watch, though the mailbox
48
+ could. The default mailbox client opens a fresh WebSocket to a relay for each
49
+ call. Every call is listed in [node.md](node.md#the-inbox).
50
+
51
+ ## Changing your inbox
52
+
53
+ Call `open` again to change where knocks wait (1 to 3 mailboxes) or the name
54
+ the code gives:
55
+
56
+ ```ts
57
+ await node.inbox.open({ name: 'Leif', places: ['wss://relay.minca.social'] });
58
+ ```
59
+
60
+ The keys stay the same, so a code you already handed out keeps working.
61
+
62
+ `rotate()` replaces the inbox. It clears what waits in the old one, and the
63
+ old code leads nowhere. Nothing ties the new inbox to the old.
64
+
65
+ `clear()` purges every waiting knock and keeps the inbox open.
34
66
 
35
- _Source: `packages/core/src/schemas/contacts.ts` (`inbox`), `packages/core/src/node/node-contacts.ts` (`inboxRecord`, `writeInbox`, `inbox.rotate`). Tests: `packages/core/tests/inbox.test.ts` ("node.inbox")._
67
+ ## Who may
68
+
69
+ Knocking and accepting create or join a space, so they need a note that
70
+ grants `/account/write` for the whole account, as `contacts.ask` does, and
71
+ the contact key.
72
+
73
+ The inbox is the person's. A node whose note lacks `/account/write`, such as
74
+ an agent's, refuses to open, replace, clear, read, knock, accept or dismiss.
75
+ A home never gives an agent the contact key in the first place. See
76
+ [spec 06 §2.8](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
36
77
 
37
78
  ## The exchange
38
79
 
80
+ Here is what happens when Leif knocks on Anna's inbox:
81
+
39
82
  ```
40
83
  Anna mailbox(es) Leif
41
84
  │ inbox.open() → std.inbox, code │
@@ -53,87 +96,89 @@ _Source: `packages/core/src/schemas/contacts.ts` (`inbox`), `packages/core/src/n
53
96
  │ closed, std.knock deleted │
54
97
  ```
55
98
 
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
99
+ ### Knocking
100
+
101
+ The knocker:
102
+
103
+ 1. Reads the code, checks its signature, and refuses its own inbox.
104
+ 2. Creates a private space named `"<own name> & <code name>"` with the
105
+ `team` preset, and makes an editor invite.
106
+ 3. If one of its carriers is online, waits up to 3 seconds for it to hold the
107
+ space and invite (`spaces.carried`). With no carrier, or none in time, it
108
+ goes on and returns `carried: false`.
109
+ 4. Seals the knock and drops it in **every** mailbox the code names. Any one
110
+ of them may lose it: the reference relay keeps its mailbox in memory, so a
111
+ restart loses it.
112
+ 5. If no mailbox answers `dropped`, leaves the space and fails.
113
+ 6. Otherwise writes `std.knock { space, name, invite }` in its contacts
114
+ space.
115
+
116
+ ### Opening
117
+
118
+ Besides the checks the protocol requires, the owner's devices skip knocks
119
+ from the account itself, from anyone blocked on its contact list, and whose
120
+ space for two it already holds, accepted here or on another device.
121
+
122
+ ### Accepting
123
+
124
+ The owner joins the invite and writes
125
+ `std.contact { did: <the knocker's account>, name, space }`. It keeps a name
126
+ it already had for that account. Then it purges the knock from the
127
+ mailboxes.
128
+
129
+ ### Settling
130
+
131
+ For each `std.knock`, the knocker's devices look at the members of its space
132
+ for two. The first other account with a place there is whoever answered,
133
+ since only the holder of the inbox key could open the invite. They write
86
134
  `std.contact { did: <that account>, name: <their profile name, else the code's>, space }`,
87
135
  close the invite, and delete the `std.knock`, so nobody joins after. Anyone
88
136
  else who joined too shows up in `contacts.others`.
89
137
 
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.
138
+ The invite works for anyone until then, so it must reach nobody else. If the
139
+ owner passes it on, or loses a device before accepting, whoever joins first
140
+ is taken for them. The owner could just as well forward the knock itself.
141
+
142
+ ### Expiry
95
143
 
96
144
  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.
145
+ go: the knocker leaves the space and deletes the record. One whose space is
146
+ no longer held is deleted.
147
+
148
+ The keys, the inbox code, the topic, the mailbox and the sealed knock are
149
+ protocol. See [spec 07](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md).
150
+
151
+ ## `std.inbox`
99
152
 
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.
153
+ The inbox's settings are a `std.inbox` record in the account's contacts
154
+ space, which only the account can find and every one of its devices holds.
155
+ The knocker keeps a `std.knock` in its own.
103
156
 
104
157
  | Collection | Fields | Rules | Where |
105
158
  | ----------- | -------------------------------------------------------- | ------------------- | ------------------------ |
106
159
  | `std.inbox` | `gen` ≥ 0 and `places` (1–3) required; `name` ≤64 | — | Owner's contacts space |
107
160
  | `std.knock` | `space` ≤256, `name` ≤64, `invite` ≤12000 (all required) | `onePer: ['space']` | Knocker's contacts space |
108
161
 
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)).
162
+ - `gen` says which inbox: both keys are derived from it.
163
+ - `places` are mailbox URLs, each passing the inbox code's relay check.
164
+ - `name` is the name the code gives whoever knocks.
115
165
 
116
- _Source: `packages/core/src/node/node-contacts.ts` (`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.
166
+ A device takes as the inbox only a verified `std.inbox` whose root is the
167
+ account itself, and of those the one with the highest `gen`, then the newest.
168
+ Changing the places or the name writes a new version of that record. `rotate`
169
+ writes `gen + 1`.
124
170
 
125
- _Source: `packages/core/src/network/relays.ts` (`createMailboxClient`)._
171
+ These records are conventions: peers that have never heard of them sync and
172
+ judge them like any other record. Only one account's devices need to agree
173
+ on them. See
174
+ [spec 07 §1](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md).
126
175
 
127
176
  ## Not yet built
128
177
 
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
178
+ - **Live knocks:** watching the inbox's topic, so a knock shows as it
179
+ arrives.
180
+ - **Retrying a knock** that reached no mailbox, or whose mailboxes lost it,
181
+ until someone joins or it expires. A retry is a fresh knock, signed and
182
+ dropped at once.
183
+ - **Mailboxes that last:** a host that keeps its accounts' inbox topics
134
184
  across restarts, as it keeps short links.
135
-
136
- ## Usernames
137
-
138
- A username (`leif@minca.social`) leads to an inbox code: see
139
- [usernames.md](usernames.md).