@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
package/docs/usernames.md CHANGED
@@ -1,80 +1,126 @@
1
1
  # Usernames
2
2
 
3
- A username, `leif@minca.social`, is a name at a domain that leads to an
4
- inbox code, so someone can find you by a name they can say aloud. What a
5
- username is, how it is looked up and what a reader checks are protocol
6
- ([spec 07 §9](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md)):
7
- every reader must agree on them.
8
-
9
- How a name is claimed at a domain is not. A domain can answer from a file it
10
- edits by hand, or from anything else. This page describes the **Minca name
11
- service** (`packages/names`), which minca.social runs and anyone can run for a
12
- domain of their own, and how the library claims a name on one.
3
+ A username, like `leif@minca.social`, is a name at a domain that leads to an
4
+ inbox code. It lets someone find you by a name they can say aloud. This page
5
+ shows how to look one up and claim one, and how to run the Minca name service
6
+ for a domain of your own.
13
7
 
14
8
  ## Looking a name up
15
9
 
16
10
  ```ts
11
+ import { createP256Provider } from '@minca/core';
17
12
  import { resolveUsername } from '@minca/core/inbox';
18
13
 
19
- const { code, inbox } = await resolveUsername('leif@minca.social', provider);
14
+ const { code, inbox } = await resolveUsername('leif@minca.social', createP256Provider());
20
15
  ```
21
16
 
22
- It asks `https://minca.social/.well-known/minca.json?name=leif`, refuses a
23
- redirect, and checks the code it gets as any other. The code then works
24
- wherever one does: knock on it.
17
+ This asks `https://minca.social/.well-known/minca.json?name=leif`. It refuses
18
+ a redirect, and checks the code it gets like any other. The code then works
19
+ wherever a code does, so you can knock on it.
20
+
21
+ It throws when the text isn't a username, the domain doesn't know the name,
22
+ or the code doesn't check out.
23
+
24
+ How a name is looked up and checked is protocol, the same for every reader:
25
+ [spec 07 §9](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md).
25
26
 
26
27
  ## On the node
27
28
 
28
- `node.inbox.claim('leif@minca.social')` does all of the below for the
29
- account's inbox, and keeps the name in `std.inbox` so every device knows it:
30
- replacing the inbox, or changing its name or mailboxes, points the name at
31
- the new code, and reading knocks renews it a month before its year is up.
32
- `node.inbox.release()` gives it up. `node.inbox.knock('anna@minca.social')`
33
- knocks by username, and the contact it becomes keeps the username
34
- (`ContactView.username`). See [node.md](node.md#the-inbox).
35
-
36
- **At sign-up.** `createMincaAuth({ usernames: 'minca.social' })` makes the
37
- create screen of `<minca-auth>` one field: the username, with a tick once the
38
- service says it is free and a cross once it is taken. A bare name is at that
39
- domain, and is how it is shown and handed out (`leif`); a whole username,
40
- `leif@example.org`, is checked and claimed at its own domain, and one that
41
- gives out no Minca usernames says so, with a link to running a service. The account's name
42
- starts as the username's (`nameFromUsername`: `leif.r` is Leif R) and is
43
- changed on the account page. "Continue without a username" makes the account with none, so nobody
44
- finds it by one, and a made-up name to show until it is given one
45
- (`adHocName`: Swift Otter). `createAccount(name,
46
- { username })` claims it in the background while the recovery code and
47
- password screens are up, and those screens say how it went: `state.username`
48
- is `claiming`, `claimed`, or `failed` with an `error`, when it was taken
49
- meanwhile or the service was down. The account is made either way.
29
+ Most apps never call the functions on this page directly. The node does it
30
+ for the account's inbox:
31
+
32
+ ```ts
33
+ await node.inbox.claim('leif@minca.social');
34
+ await node.inbox.knock('anna@minca.social');
35
+ await node.inbox.release();
36
+ ```
37
+
38
+ `claim` keeps the name in `std.inbox`, so every device knows it. After that,
39
+ the node keeps the name pointing at the right place:
40
+
41
+ - Replacing the inbox, or changing its name or mailboxes, points the name at
42
+ the new code.
43
+ - Reading knocks renews the name a month before its year is up.
44
+
45
+ `knock` knocks by username, and the contact it becomes keeps the username
46
+ (`ContactView.username`). `release` gives the name up. See
47
+ [the inbox](node.md#the-inbox).
48
+
49
+ Renewal claims the code of the inbox this device knows. If another device
50
+ replaced the inbox and this one hasn't synced that yet, renewing points the
51
+ name back at the old inbox until the inbox next changes. Renewal starts only
52
+ within a month of the name lapsing, so this is rare.
53
+
54
+ ## At sign-up
55
+
56
+ Pass `usernames` to `createMincaAuth`, and the create screen of
57
+ `<minca-auth>` becomes one field: the username.
58
+
59
+ ```ts
60
+ import { createMincaAuth } from '@minca/core/session';
61
+
62
+ const auth = createMincaAuth({ usernames: 'minca.social' });
63
+ ```
64
+
65
+ The field shows a tick once the service says the name is free, and a cross
66
+ once it's taken. A bare name like `leif` is at that domain, and is how it is
67
+ shown. A whole username like `leif@example.org` is checked and claimed at its
68
+ own domain. A domain that gives out no Minca usernames says so, with a link to
69
+ [running a service](#running-one-for-your-domain).
70
+
71
+ The account's name starts as the username's (`nameFromUsername`: `leif.r`
72
+ becomes Leif R), and can be changed on the account page.
73
+
74
+ "Continue without a username" makes an account with none, so nobody finds it
75
+ by one. It gets a made-up name to show until it is given one (`adHocName`:
76
+ Swift Otter).
77
+
78
+ ### The claim runs in the background
79
+
80
+ `createAccount(name, { username })` claims the name while the recovery code
81
+ and password screens are up. Those screens say how it went, in
82
+ `state.username`: its `status` goes from `claiming` to `claimed`, or to
83
+ `failed` with an `error` (the name was taken meanwhile, or the service was
84
+ down).
85
+
86
+ The account is made either way. If the claim failed, the app's contacts
87
+ screen asks for a name again.
88
+
89
+ ### Handing over to the app
50
90
 
51
91
  The claim is made on the home's node, which may be the only one holding the
52
- inbox: a connect page that closes once it answers keeps the window open
53
- until the app's node holds the contacts space too (`spaces.reached`, keyed
54
- by the app's key from its request), or else the app would read no knocks
55
- until the two next met. The account home waits for what setup began in
56
- the background (`auth.settled()`: the claim, and the host's handover) to
57
- finish, however long, so neither is cut off halfway; then up to 30 s for the app,
58
- and only for an account that claimed a name there. If the claim failed, the
59
- app's contacts screen asks for a name again.
60
-
61
- _Source: `packages/core/src/session/auth.ts` (`createAccount`, `claimInBackground`), `packages/core/src/elements/minca-auth.ts` (`#create`), `packages/core/src/inbox/names.ts` (`adHocName`, `nameFromUsername`, `usernameFree`), `apps/home/src/components/ConnectPage.tsx` (`handOver`). Tests: `packages/core/tests/usernames.test.ts` ("a username at sign-up")._
62
-
63
- Renewing claims the code of the inbox this device knows. A device that
64
- hasn't yet synced a replacement made on another one points the name back at
65
- the old inbox until the inbox next changes; renewal starts only within a
66
- month of the name lapsing, so this is rare.
92
+ inbox. So a connect page that closes once it answers stays open until the
93
+ app's node holds the contacts space too (`spaces.reached`, keyed by the app's
94
+ key from its request). Otherwise the app would read no knocks until the two
95
+ next met.
96
+
97
+ The account home first waits for what setup began in the background to
98
+ finish, however long that takes (`auth.settled()`: the claim, and the host's
99
+ handover). Then it waits up to 30 s for the app, and only for an account that
100
+ claimed a name there.
67
101
 
68
102
  ## Claiming a name
69
103
 
104
+ To claim a name without a node, call `claimUsername` with the contact key and
105
+ the inbox code. Pass `null` as the code to give the name up.
106
+
70
107
  ```ts
108
+ declare const contactKey: Uint8Array;
109
+ declare const inboxCode: string;
110
+ // ---cut---
71
111
  import { claimUsername } from '@minca/core/inbox';
72
112
 
73
113
  const until = await claimUsername('leif@minca.social', contactKey, inboxCode);
74
114
  ```
75
115
 
76
- `claimUsername` looks the name up first. A Minca name service says, in every
77
- answer, where claims go and how much work one needs:
116
+ It returns when the name lapses, in ms, unless claimed again. It throws when
117
+ the code isn't this account's, the domain names no name service, or the
118
+ service refuses.
119
+
120
+ ### What goes over the wire
121
+
122
+ `claimUsername` looks the name up first. In every answer, a Minca name
123
+ service says where claims go and how much work one needs:
78
124
 
79
125
  ```json
80
126
  { "names": {}, "claim": "https://usernames.minca.social/.well-known/minca.json", "work": 20 }
@@ -94,51 +140,74 @@ Then it posts the claim there:
94
140
  }
95
141
  ```
96
142
 
97
- | Field | |
98
- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
99
- | `key` | The **name key**'s public half, compressed P-256, base64url |
100
- | `at` | When the claim was made, ms. It must be within 10 minutes of the service's clock, and later than the claim it follows |
101
- | `work` | A counter: SHA-256 of `minca/name-work/v1\|<name>@<domain>\|<key>\|<at>\|<work>` starts with `work` zero bits |
102
- | `code` | The inbox code, at most 4,096 characters. None gives the name up |
103
- | `bind` | With a code: the inbox signing key's signature over `minca/name-bind/v1\|<name>@<domain>`, so a name leads only to an inbox whose owner chose it |
104
- | `sig` | The name key's ECDSA P-256 signature over `minca/name-claim/v1\|<name>@<domain>\|<at>\|<code, or empty>` |
143
+ | Field | |
144
+ | ------ | ------------------------------------------------------------------------------------------------------------- |
145
+ | `key` | The name key's public half: compressed P-256, base64url |
146
+ | `at` | When the claim was made, ms. Within 10 minutes of the service's clock, and later than the last claim |
147
+ | `work` | A counter: SHA-256 of `minca/name-work/v1\|<name>@<domain>\|<key>\|<at>\|<work>` starts with `work` zero bits |
148
+ | `code` | The inbox code, at most 4,096 characters. Leave it out to give the name up |
149
+ | `bind` | With a code: the inbox signing key's signature over `minca/name-bind/v1\|<name>@<domain>` |
150
+ | `sig` | The name key's ECDSA P-256 signature over `minca/name-claim/v1\|<name>@<domain>\|<at>\|<code, or empty>` |
151
+
152
+ `bind` makes sure a name leads only to an inbox whose owner chose it.
105
153
 
106
- The answer is `{ "until": <ms> }`, when the name lapses, or
154
+ The service answers `{ "until": <ms> }`, when the name lapses, or
107
155
  `{ "error": "…" }` with a 4xx status.
108
156
 
109
- **The name key** is derived from the contact key, one per username:
110
- `HKDF-SHA-256(contact key, info = "minca/p256-name-key/v1|" + name@domain)`,
111
- with the username as `formatUsername` writes it, so every spelling a reader takes gives one key. `claimUsername` derives it itself. Every device that holds the contact key
112
- derives the same one; it is not an inbox key, so replacing the inbox keeps
113
- the name, and nothing ties it to the account. Only the key that holds a name
114
- can point it elsewhere, renew it or give it up.
157
+ ### The name key
158
+
159
+ Each username has its own name key, derived from the contact key:
160
+
161
+ ```
162
+ HKDF-SHA-256(contact key, info = "minca/p256-name-key/v1|" + name@domain)
163
+ ```
164
+
165
+ The username is written as `formatUsername` writes it, so every spelling a
166
+ reader accepts gives the same key. `claimUsername` derives it for you.
167
+
168
+ Every device that holds the contact key derives the same name key. It isn't
169
+ an inbox key, so replacing the inbox keeps the name. Nothing ties it to the
170
+ account. Only the key that holds a name can point it elsewhere, renew it or
171
+ give it up.
172
+
173
+ ### Who may claim
174
+
175
+ A name leads to the account's inbox, so only what may run the inbox may claim
176
+ one. That's a node whose note grants `/account/write` for the whole account,
177
+ holding the contact key.
115
178
 
116
- **Who may.** A name leads to the account's inbox, so only what may run the
117
- inbox may claim one: a node whose note grants `/account/write` for the whole
118
- account, holding the contact key. An app given the contact key could claim
119
- the account's names too, and its hold outlasts revoking it, since a name key
120
- has no generation to move on to
121
- ([#313](https://github.com/leifriksheim/minca/issues/313)).
179
+ An app given the contact key could claim the account's names too. It keeps
180
+ that power after it's revoked, since a name key has no generation to move on
181
+ to ([#313](https://github.com/leifriksheim/minca/issues/313)).
122
182
 
123
183
  ## What the service keeps to
124
184
 
125
- | Rule | On minca.social |
126
- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
127
- | How long a claim holds | A year. Claiming again, with the same code or a new one, renews it |
128
- | New names from one address | 3 a day (an IPv4 address, or an IPv6 /48). Changing or renewing a name is free |
129
- | Work | 18 bits: a fraction of a second on a laptop, about a second on a phone |
130
- | Names held | 50,000: each is a file of up to 8 KB, so a 1 GB volume holds them, inodes included |
131
- | Reserved | `admin`, `support`, `security`, `minca` and a few more that pass for the service. A lookup of one answers `"reserved": true`, so `usernameFree` says it isn't |
132
- | Given up | Free again after 10 minutes, so no earlier claim can be replayed to take it back |
133
-
134
- The work is a speed bump for bots, not a gate: a server does it ten times
135
- faster than a phone. The address budget and the year are what keep squatting
136
- in check; a name nobody renews comes back. The budget is kept in memory, so a
137
- restart forgets it; nothing a client sends can make the service stop, since
138
- whatever goes wrong with one request answers that request.
139
-
140
- Each name is a file of its own on the service's disk, so nothing grows in
141
- memory and no large file is rewritten. Lookups are open to any page
185
+ How a name is claimed isn't protocol. A domain can answer lookups from a file
186
+ it edits by hand, or from anything else. The **Minca name service**
187
+ (`packages/names`) is what minca.social runs, and anyone can run it.
188
+
189
+ | Rule | On minca.social |
190
+ | -------------------------- | -------------------------------------------------------------------------------- |
191
+ | How long a claim holds | A year. Claiming again, with the same code or a new one, renews it |
192
+ | New names from one address | 3 a day, per IPv4 address or IPv6 /48. Changing or renewing a name is free |
193
+ | Work | 18 bits: a fraction of a second on a laptop, about a second on a phone |
194
+ | Names held | 50,000, each a file of up to 8 KB, so a 1 GB volume holds them, inodes included |
195
+ | Reserved | `admin`, `support`, `security`, `minca` and a few more that pass for the service |
196
+ | Given up | Free again after 10 minutes, so no earlier claim can be replayed to take it back |
197
+
198
+ A lookup of a reserved name answers `"reserved": true`, so `usernameFree`
199
+ says it isn't free.
200
+
201
+ The work is a speed bump for bots, not a gate. A server does it ten times
202
+ faster than a phone. What keeps squatting in check is the address budget and
203
+ the year: a name nobody renews comes back.
204
+
205
+ The address budget is kept in memory, so a restart forgets it. Nothing a
206
+ client sends can stop the service, since whatever goes wrong with one request
207
+ only fails that request.
208
+
209
+ Each name is its own file on disk, so nothing grows in memory and no large
210
+ file is rewritten. Lookups are open to any page
142
211
  (`Access-Control-Allow-Origin: *`).
143
212
 
144
213
  ## Running one for your domain
@@ -152,10 +221,8 @@ NAMES_DIR=/data/names \
152
221
  node packages/names/server.mjs 8080
153
222
  ```
154
223
 
155
- Then answer `https://example.org/.well-known/minca.json` from it, by serving
156
- the domain from it or proxying that one path (minca.social's site does this,
157
- in `apps/site/public/_redirects`). Claims go to `NAMES_CLAIM_URL` directly, so
158
- the service sees each client's address. `packages/names/fly.toml` deploys it
159
- on Fly.
224
+ Then answer `https://example.org/.well-known/minca.json` from it. Either serve
225
+ the domain from it, or proxy that one path, as minca.social's site does.
160
226
 
161
- _Source: `packages/core/src/inbox/names.ts` (`claimUsername`, `claimMessage`), `packages/core/src/identity/contact-key.ts` (`deriveNameKeyBytes`), `packages/names/names.mjs` (`createNames`, `NAMES_LIMITS`), `packages/names/server.mjs`, `apps/site/public/_redirects`. Tests: `packages/names/tests/names.test.ts`._
227
+ Claims go to `NAMES_CLAIM_URL` directly, so the service sees each client's
228
+ address. `packages/names/fly.toml` deploys it on Fly.
package/docs/warrants.md CHANGED
@@ -1,15 +1,57 @@
1
1
  # Warrants
2
2
 
3
- A **warrant** is proof that an account's key signed something every peer
4
- refuses and no honest app would sign. Members write it down, and every member's
5
- node checks the proof itself before it shows the account as flagged. Nothing
6
- is done to the account automatically: what to do about it is up to whoever
7
- may remove members there.
3
+ A **warrant** (`std.warrant`) is proof that an account's key signed something
4
+ every peer refuses and no honest app would sign. Your app uses warrants to
5
+ show the members of a space that someone broke the rules, so whoever may
6
+ remove members can decide what to do.
8
7
 
9
- Warrants are a standard collection, not protocol. A `std.warrant` record stands
10
- like any record its author may write, and syncs like one. A peer that has never
11
- heard of warrants stores and judges everything the same; it just shows no
12
- flags.
8
+ Nodes write warrants for you, and every member's node checks the proof itself
9
+ before it shows an account as flagged. Nothing happens to the account
10
+ automatically. A peer that has never heard of warrants syncs and judges
11
+ everything the same. It just shows no flags.
12
+
13
+ ## Showing who is flagged
14
+
15
+ `spaces.access(id).flagged` lists every account this node has checked proof
16
+ against:
17
+
18
+ ```ts
19
+ const { flagged } = await node.spaces.access(space.id);
20
+ // [{ account, key, kind, by, offence }]
21
+ ```
22
+
23
+ Each entry is one warrant:
24
+
25
+ | Field | |
26
+ | --------- | --------------------------------------------------- |
27
+ | `account` | The account accused |
28
+ | `key` | The key that signed it: one device or app of theirs |
29
+ | `kind` | What it broke: `chain`, `standing` or `access` |
30
+ | `by` | The account that brought the proof |
31
+ | `offence` | The id of the offending version |
32
+
33
+ Several members may bring proof against one account, so an account can appear
34
+ more than once.
35
+
36
+ Show the flag to the space's members. One granted `/member/remove` may remove
37
+ the person with `spaces.removeMember(id, did)`.
38
+
39
+ Show it to the account itself too. A flag against your own account usually
40
+ means one of your keys is being used somewhere it shouldn't be. Revoking that
41
+ key with `spaces.revoke` takes back what it signed.
42
+
43
+ ## When a warrant counts
44
+
45
+ A warrant flags someone only when it:
46
+
47
+ - is a first version, standing as a record;
48
+ - is in `std.warrant`, and not against its own writer;
49
+ - has evidence that is exactly what its ids name, envelope and body;
50
+ - proves its kind's check.
51
+
52
+ Anything else flags nobody. That covers false, malformed and unknown kinds,
53
+ and it earns the writer nothing either. Each warrant is judged once, whether
54
+ it holds or not, so a false one costs a node one check.
13
55
 
14
56
  ## The record
15
57
 
@@ -18,62 +60,53 @@ std.warrant at a fresh key of its writer's
18
60
  { kind, evidence: [<version>, <version>?] } retain: true
19
61
  ```
20
62
 
21
- `evidence[0]` is the offending version, and its signer's root is the accused
22
- account. The key is the writer's own
23
- ([spec 02 §4.1](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)),
24
- so nobody, the accused least of all, can write its first version: what a
25
- warrant proves is in its body. Only
26
- the warrant's first version counts as proof, and one offence counts once per
27
- writer, however many records say it. Whoever the space's grants let change
28
- it may write a later version or a delete of it, as for any record, and
29
- neither takes the proof back.
30
- The writer sets `retain`, so the first version is kept whole whatever comes
31
- after it.
32
-
33
- | `kind` | `evidence` | Proves |
34
- | ---------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
35
- | `chain` | `[v, p]`, both without bodies | `p.id = v.prev`, and `v` does not follow `p` (spec 02 §4.7) |
36
- | `standing` | `[v]`, without its body; not an access collection | in `v`'s own view, `v`'s root was no member, or the rules said `final`, or, for a first version, its root held no grant to write it (policies on its body left out) |
37
- | `access` | `[v]`, whole; an access collection | in its own view, `v`'s event is refused by its author's power (spec 03 §4.5) |
38
-
39
- A version's **own view** is the access changes its `seen` names and everything
40
- they saw, replayed alone. That is what its writer's node had when it signed.
41
- Nothing outside it can alter the verdict, so an honest writer never fails it.
42
-
43
- ## Who is flagged
44
-
45
- `spaces.access(id).flagged` lists `{ account, key, kind, by }` for every
46
- warrant whose proof this node checked and found to hold. To count, a warrant
47
- must:
48
-
49
- - be a first version, standing as a record;
50
- - be in `std.warrant`, and not against its own writer;
51
- - have every piece of evidence be what its id names, envelope and body;
52
- - prove its kind's check.
53
-
54
- Anything else, whether false, malformed, or of an unknown kind, flags nobody,
55
- and earns its writer nothing either. Each warrant is judged once, whether it
56
- holds or fails, so false ones cost a node one check each. Several members may bring proof against
57
- one account, so an account can appear more than once.
58
-
59
- ## Writing one
60
-
61
- When the node refuses a version that is proof of a kind above, it writes a
62
- warrant of its own, unless one of its own against that account stands
63
- already. So one account's misconduct costs each member one warrant at a time.
64
- It looks through the cheap global view first, and replays the own view only
65
- for what that finds broken: a flag can be missed, but is never false. A race,
66
- such as a write that crossed a removal it hadn't seen, is withdrawn, never
67
- refused, so it earns no warrant.
68
-
69
- An app shows the flag to the space's members; one granted `/member/remove`
70
- may remove the person (`spaces.removeMember(id, did)`). It also shows it to the account itself: a
71
- flag against your own account usually means one of your keys is being used
72
- somewhere it shouldn't be, and revoking that key (`spaces.revoke`) takes
73
- back what it signed.
74
-
75
- Like any record, a warrant is withdrawn when its writer is removed by a
76
- change whose cutoff doesn't cover it, or revokes the key that signed it ([#166](https://github.com/leifriksheim/minca/issues/166)). More kinds are planned after v1, in
77
- [#148](https://github.com/leifriksheim/minca/issues/148).
63
+ `evidence[0]` is the offending version. Its signer's root is the accused
64
+ account.
78
65
 
79
- _Source: `packages/core/src/records/warrant.ts` (`readWarrant`, `knownKind`), `packages/core/src/node/space-history.ts` (`ownView`), `packages/core/src/node/space-warrants.ts` (`warrantShape`, `warrantVerdict`, `evidenceHolds`, `violationIn`, `warrantIfDue`, `flagged`), `packages/core/src/space/space-access.ts` (`WARRANT_COLLECTION`). Tests: `packages/core/tests/warrants.test.ts`._
66
+ The record's key is the writer's own, so nobody can write its first version
67
+ but the writer, the accused least of all. Only that first version counts as
68
+ proof. Whoever the space's grants allow may write a later version or delete
69
+ it, as for any record, but neither takes the proof back. The writer sets
70
+ `retain`, so the first version is kept whole.
71
+
72
+ One offence counts once per writer, however many records say it.
73
+
74
+ ## Kinds
75
+
76
+ | `kind` | `evidence` | Proves |
77
+ | ---------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
78
+ | `chain` | `[v, p]`, both without bodies | `p.id = v.prev`, and `v` doesn't follow `p` |
79
+ | `standing` | `[v]`, without its body; not an access collection | In `v`'s own view: its root was no member, the rules said `final`, or a first version's root had no grant to write it |
80
+ | `access` | `[v]`, whole; an access collection | In its own view, `v`'s event is refused by its author's power |
81
+
82
+ For `standing`, policies on the body are left out of the grant check.
83
+
84
+ A version's **own view** is the access changes its `seen` names, and
85
+ everything they saw, replayed alone. That's what its writer's node had when
86
+ it signed. Nothing outside it can change the verdict, so an honest writer
87
+ never fails it.
88
+
89
+ See [spec 02 §4](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)
90
+ and [spec 03 §4.5](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)
91
+ for the checks themselves.
92
+
93
+ ## How a node writes one
94
+
95
+ When your node refuses a version that proves one of the kinds above, it
96
+ writes a warrant of its own. It skips this if one of its own warrants against
97
+ that account already stands. So one account's misconduct costs each member
98
+ one warrant at a time.
99
+
100
+ The node looks through the cheap global view first, and replays the own view
101
+ only for what that finds broken. A flag can be missed, but is never false. A
102
+ race, like a write that crossed a removal it hadn't seen, is withdrawn rather
103
+ than refused, so it earns no warrant.
104
+
105
+ ## When a warrant goes away
106
+
107
+ Like any record, a warrant is withdrawn when its writer is removed by a change
108
+ whose cutoff doesn't cover it, or revokes the key that signed it
109
+ ([#166](https://github.com/leifriksheim/minca/issues/166)).
110
+
111
+ More kinds are planned after v1, in
112
+ [#148](https://github.com/leifriksheim/minca/issues/148).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@minca/core",
3
- "version": "0.1.17",
3
+ "version": "0.1.18",
4
4
  "type": "module",
5
5
  "description": "Self-sovereign P2P protocol for the browser — identity, schemas, storage, networking, and gossip sync",
6
6
  "repository": {