@minca/core 0.1.16 → 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.
- package/README.md +10 -9
- package/dist/elements/auth-styles.d.ts +1 -1
- package/dist/elements/auth-styles.d.ts.map +1 -1
- package/dist/elements/auth-styles.js +14 -5
- package/dist/elements/auth-styles.js.map +1 -1
- package/dist/elements/minca-auth.d.ts.map +1 -1
- package/dist/elements/minca-auth.js +18 -15
- package/dist/elements/minca-auth.js.map +1 -1
- package/dist/files/space-files.d.ts +2 -2
- package/dist/files/space-files.d.ts.map +1 -1
- package/dist/files/space-files.js +7 -5
- package/dist/files/space-files.js.map +1 -1
- package/dist/inbox/names.d.ts +1 -1
- package/dist/inbox/names.js +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/network/ws-transport.d.ts.map +1 -1
- package/dist/network/ws-transport.js +3 -0
- package/dist/network/ws-transport.js.map +1 -1
- package/dist/node/actions.d.ts +5 -0
- package/dist/node/actions.d.ts.map +1 -1
- package/dist/node/actions.js +39 -20
- package/dist/node/actions.js.map +1 -1
- package/dist/node/api.d.ts +2 -0
- package/dist/node/api.d.ts.map +1 -1
- package/dist/node/api.js +2 -0
- package/dist/node/api.js.map +1 -1
- package/dist/node/carrier.js +1 -1
- package/dist/node/carrier.js.map +1 -1
- package/dist/node/node-carriers.d.ts.map +1 -1
- package/dist/node/node-carriers.js +6 -1
- package/dist/node/node-carriers.js.map +1 -1
- package/dist/node/node-contacts.d.ts.map +1 -1
- package/dist/node/node-contacts.js +1 -0
- package/dist/node/node-contacts.js.map +1 -1
- package/dist/node/node-hosting.d.ts.map +1 -1
- package/dist/node/node-hosting.js +11 -4
- package/dist/node/node-hosting.js.map +1 -1
- package/dist/node/node-records.d.ts.map +1 -1
- package/dist/node/node-records.js +6 -1
- package/dist/node/node-records.js.map +1 -1
- package/dist/node/node.d.ts.map +1 -1
- package/dist/node/node.js +14 -1
- package/dist/node/node.js.map +1 -1
- package/dist/node/remote.d.ts.map +1 -1
- package/dist/node/remote.js +7 -1
- package/dist/node/remote.js.map +1 -1
- package/dist/node/space-holding.d.ts +7 -3
- package/dist/node/space-holding.d.ts.map +1 -1
- package/dist/node/space-holding.js +90 -18
- package/dist/node/space-holding.js.map +1 -1
- package/dist/node/space-peers.d.ts.map +1 -1
- package/dist/node/space-peers.js +58 -24
- package/dist/node/space-peers.js.map +1 -1
- package/dist/node/space-runtime.d.ts +11 -3
- package/dist/node/space-runtime.d.ts.map +1 -1
- package/dist/node/space-runtime.js +22 -1
- package/dist/node/space-runtime.js.map +1 -1
- package/dist/node/space-writing.d.ts +2 -0
- package/dist/node/space-writing.d.ts.map +1 -1
- package/dist/node/space-writing.js +2 -0
- package/dist/node/space-writing.js.map +1 -1
- package/dist/node/types.d.ts +130 -36
- package/dist/node/types.d.ts.map +1 -1
- package/dist/query/types.d.ts +1 -0
- package/dist/query/types.d.ts.map +1 -1
- package/dist/query/types.js.map +1 -1
- package/dist/records/contract-builder.d.ts +22 -6
- package/dist/records/contract-builder.d.ts.map +1 -1
- package/dist/records/contract-builder.js.map +1 -1
- package/dist/schemas/automations.d.ts +6 -2
- package/dist/schemas/automations.d.ts.map +1 -1
- package/dist/schemas/automations.js.map +1 -1
- package/dist/schemas/connectors.d.ts +4 -3
- package/dist/schemas/connectors.d.ts.map +1 -1
- package/dist/schemas/connectors.js +4 -3
- package/dist/schemas/connectors.js.map +1 -1
- package/dist/schemas/library/media.js +1 -1
- package/dist/schemas/library/media.js.map +1 -1
- package/dist/schemas/library/social.d.ts +258 -0
- package/dist/schemas/library/social.d.ts.map +1 -1
- package/dist/schemas/library/social.js +28 -1
- package/dist/schemas/library/social.js.map +1 -1
- package/dist/session/auth.d.ts +7 -3
- package/dist/session/auth.d.ts.map +1 -1
- package/dist/session/auth.js.map +1 -1
- package/dist/session/hosting.d.ts.map +1 -1
- package/dist/session/hosting.js +8 -2
- package/dist/session/hosting.js.map +1 -1
- package/dist/space/presets.d.ts +2 -2
- package/dist/space/presets.d.ts.map +1 -1
- package/dist/space/presets.js +3 -2
- package/dist/space/presets.js.map +1 -1
- package/dist/storage/blob-store.d.ts +3 -0
- package/dist/storage/blob-store.d.ts.map +1 -1
- package/dist/types.d.ts +11 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/docs/README.md +86 -93
- package/docs/actions.md +212 -144
- package/docs/agents.md +198 -155
- package/docs/automations.md +296 -204
- package/docs/blueprints-and-guides.md +405 -295
- package/docs/bots.md +208 -134
- package/docs/building-an-app.md +74 -163
- package/docs/collections.md +248 -328
- package/docs/computed.md +112 -89
- package/docs/contacts.md +151 -112
- package/docs/contracts.md +299 -120
- package/docs/direct-messages.md +80 -61
- package/docs/inbox.md +138 -93
- package/docs/node.md +1072 -972
- package/docs/permissions.md +142 -0
- package/docs/proposing-collections.md +74 -55
- package/docs/query-format.md +150 -126
- package/docs/records-and-queries.md +205 -126
- package/docs/sign-in.md +496 -418
- package/docs/spaces.md +261 -245
- package/docs/standard-library.md +473 -504
- package/docs/storage.md +325 -348
- package/docs/usernames.md +164 -97
- package/docs/warrants.md +100 -67
- package/package.json +1 -2
package/docs/direct-messages.md
CHANGED
|
@@ -1,28 +1,74 @@
|
|
|
1
1
|
# Direct messages
|
|
2
2
|
|
|
3
|
-
A direct message is text only some
|
|
4
|
-
it is for, and whoever wrote it.
|
|
5
|
-
|
|
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
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
direct
|
|
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
|
|
22
|
-
|
|
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
|
|
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
|
|
60
|
-
its own member key as it holds it, rather than as published,
|
|
61
|
-
devices can read what it sent before that key
|
|
62
|
-
must not write a direct message for someone with no member key in the
|
|
63
|
-
|
|
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
|
|
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,37 +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
|
|
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
|
|
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
|
|
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`. A bot is an account of its own and holds
|
|
101
|
-
one, so it reads and sends them like anyone: the actions `direct_list` and
|
|
102
|
-
`direct_send` ([actions](actions.md)) are offered to bots, not to agents,
|
|
103
|
-
and an automation set off by a direct message hands the bot the message opened.
|
|
104
|
-
|
|
105
|
-
_Source:_ `packages/core/src/node/actions.ts` (`direct_list`, `direct_send`),
|
|
106
|
-
`packages/core/src/node/actions.ts` (`offeredActions`), `packages/cli/src/agent-automations.ts`
|
|
107
|
-
(`openTrigger`, `ruleContext`). Tests: `packages/core/tests/direct.test.ts`
|
|
108
|
-
("the direct message actions"), `packages/cli/tests/agent-automations.test.ts`.
|
|
109
|
-
|
|
110
|
-
_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/Chat.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.
|
|
111
130
|
|
|
112
131
|
## Planned: direct messages in public spaces
|
|
113
132
|
|
|
114
133
|
Members publish member keys only in private spaces, so a public space has none
|
|
115
|
-
to seal to. Publishing them in every space would let members of a public
|
|
116
|
-
write to each other. The text would then be protected only by the
|
|
117
|
-
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
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
##
|
|
7
|
+
## Opening your inbox
|
|
16
8
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
9
|
+
```ts
|
|
10
|
+
const inbox = await node.inbox.open();
|
|
11
|
+
```
|
|
20
12
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
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
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
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
|
-
|
|
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
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
lose it
|
|
68
|
-
loses
|
|
69
|
-
5.
|
|
70
|
-
6.
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
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
|
|
91
|
-
owner passes it on, or a device
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
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
|
|
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
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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
|
-
|
|
110
|
-
|
|
111
|
-
|
|
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
|
-
|
|
117
|
-
|
|
118
|
-
|
|
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
|
-
|
|
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
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
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).
|