@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/computed.md CHANGED
@@ -1,16 +1,23 @@
1
1
  # Computed fields
2
2
 
3
- "A todo is done once two people have reacted 👍." A collection's definition
4
- can say this once, as a computed field, and every app that reads the
5
- collection works it out the same way, from the records its node holds. No
6
- one writes `done`, and no one signs a claim.
3
+ A computed field is a value every app works out from the records it holds,
4
+ instead of one somebody writes. Use one for counts, tallies and flags that
5
+ follow from other records, like "a to-do is done once two people have
6
+ reacted 👍".
7
7
 
8
- > Not protocol. Peers keep the definition's `computed` member and never read
9
- > it, as they keep `contract`: a peer that has never heard of computed fields
10
- > syncs, stores and judges every record the same way
11
- > ([#247](https://github.com/leifriksheim/minca/issues/247)).
8
+ Computed fields are a library convention. Peers store a definition's
9
+ `computed` member and never read it
10
+ ([#247](https://github.com/leifriksheim/minca/issues/247)).
11
+
12
+ ## An example
13
+
14
+ Say it once, in the collection's definition, then query on it like any
15
+ field:
12
16
 
13
17
  ```ts
18
+ import * as z from 'zod';
19
+ import { collection } from '@minca/core';
20
+
14
21
  const reaction = collection({
15
22
  name: 'app.reaction',
16
23
  schema: z.object({ emoji: z.string() }),
@@ -30,7 +37,7 @@ const todo = collection({
30
37
  },
31
38
  });
32
39
 
33
- const { records } = await node.records.query(space, {
40
+ const { records } = await node.records.query(space.id, {
34
41
  collection: todo,
35
42
  where: { done: false },
36
43
  sort: { thumbs: 'desc' },
@@ -39,58 +46,57 @@ records[0]?.body.text; // what was written
39
46
  records[0]?.computed.done; // what this node works out: boolean | null
40
47
  ```
41
48
 
49
+ No one writes `done`, and no one signs a claim about it.
50
+
42
51
  ## A view, not a verdict
43
52
 
44
53
  Each node works computed fields out from what it holds. Two nodes holding
45
- different records read different values until they have synced: Bob reads
46
- `done` as soon as he has reacted, and Alice only once his reaction reaches
47
- her. A withdrawn reaction turns `done` back, as does a removed member's,
48
- where the removal keeps nothing of theirs (spec 03 §6.3). A node
49
- holding only some collections counts only what it holds.
54
+ different records see different values until they have synced. Bob sees
55
+ `done` as soon as he reacts. Alice sees it once his reaction reaches her.
56
+
57
+ Withdraw a reaction and `done` turns back. The same happens when a member is
58
+ removed and the removal keeps nothing of theirs. A node that holds only some
59
+ collections counts only what it holds.
50
60
 
51
61
  That is right for what an app shows: done flags, like counts, tallies,
52
- leaderboards. It is wrong for what something else builds on or can't take
53
- back: a payment, a proposal that moves money, a move the next move depends
54
- on. Those need a verdict that is the same on every node and stays fixed,
55
- which is what a [contract](contracts.md) gives: the writer cites the
56
- evidence, and every reader judges exactly that.
62
+ leaderboards. It is wrong for anything that can't be taken back, like a
63
+ payment, or a move the next move depends on. Those need a verdict that is the
64
+ same on every node and stays fixed. That is what a [contract](contracts.md)
65
+ gives: the writer cites the evidence, and every reader judges exactly that.
57
66
 
58
67
  The two are written the same way. Where a computed field searches with
59
- `linked(reaction, 'on')`, a contract's condition reads what a claim cites with
60
- `cited(body.reactions, reaction)`; the rest of the expression is the same.
68
+ `linked(reaction, 'on')`, a contract reads what a claim cites with
69
+ `cited(body.reactions, reaction)`. The rest of the expression is the same.
61
70
 
62
71
  ## Writing them
63
72
 
64
- `computed` is a function that gets the record's names and gives an object:
65
- each field, and how it is worked out. It is built into CEL, the language
66
- contracts use, when the collection is defined.
67
-
68
- - **`linked(collection, rel)`**: the records of `collection` that link to
69
- this one with role `rel`, current and readable here, as versions: `key`,
70
- `author` (the account), `createdAt`, `body`, `links`. Pass the definition,
71
- and `rel` completes from its link roles that may point at this collection;
72
- a role it lacks, or one that points elsewhere, is a type error. Each
73
- record's `body` is typed from its schema.
74
- - **What else it reads:** `body`, `links`, `key`, `seq`, `collection`,
75
- `author`, `creator`, `createdAt`, `updatedAt`, and `link(rel)`, `hash(x)`,
76
- `has(field)`, `when(test, then, otherwise)` and `raw(cel)`. Not `prev`,
77
- `versions` or `member`: those are a contract's.
78
- - **Methods** are a contract's ([contracts.md](contracts.md#writing-one-in-typescript)):
79
- `where`, `map`, `distinct`, `count`, `sum`, `exists`, `all`, comparisons and
80
- arithmetic. A balance is `linked(payment, 'to').map((p) => p.body.amount).sum()`.
81
- - **One field from another**: give one a name with `const`, and use it in the
82
- next, as `done` uses `thumbs`. Each lookup of what links here is done once
83
- per record, however many fields use it.
73
+ `computed` is a function that gets the record's names and returns an object
74
+ of fields. It is turned into CEL, the language contracts use, when you define
75
+ the collection.
76
+
77
+ What it can read and call is on
78
+ [`ComputedContext`](https://minca.dev/api/core/interfaces/ComputedContext/).
79
+ The one a contract lacks is `linked(collection, rel)`, the records that link
80
+ to this one. Pass the definition, and a role it lacks, or one that points
81
+ elsewhere, is a type error.
82
+
83
+ - **Methods** are a contract's
84
+ ([Contracts](contracts.md#writing-one-in-typescript)): `where`, `map`,
85
+ `distinct`, `count`, `sum`, `exists`, `all`, comparisons and arithmetic. A
86
+ balance is `linked(payment, 'to').map((p) => p.body.amount).sum()`.
87
+ - **One field can use another.** Name it with `const` and use it in the next,
88
+ as `done` uses `thumbs`. Each `linked()` lookup runs once per record,
89
+ however many fields use it.
84
90
 
85
91
  A field's type follows from its expression: a count is a `number`, a
86
- comparison a `boolean`. Each is `null` for a record it can't be worked out
87
- for, as when a body lacks a field it reads, or it runs past the limits
92
+ comparison a `boolean`. A field is `null` for a record it can't be worked out
93
+ for, such as when the body lacks a field it reads, or it runs past the limits
88
94
  contracts have.
89
95
 
90
96
  ## As data
91
97
 
92
- A definition stores each field's CEL, and an agent or another language
93
- writes the same:
98
+ A definition stores each field as CEL, so an agent or another language can
99
+ write the same thing:
94
100
 
95
101
  ```json
96
102
  "computed": {
@@ -99,60 +105,77 @@ writes the same:
99
105
  }
100
106
  ```
101
107
 
102
- `collections.define` refuses, saying where:
108
+ ## What `define` refuses
103
109
 
104
- - more than 16 fields, a name that isn't lower camel case, or an expression
105
- over 4,000 characters or 2,000 parts in all;
106
- - anything outside the subset contracts have (spec 09 §5), and `prev`,
107
- `versions` and `member`;
110
+ `collections.define` refuses these, saying where:
111
+
112
+ - more than 16 fields;
113
+ - a name that isn't lower camel case;
114
+ - an expression over 4,000 characters, or over 2,000 parts in all;
115
+ - anything outside the CEL subset contracts have
116
+ ([spec 09 §5](https://github.com/leifriksheim/minca/blob/main/spec/09-contracts.md)),
117
+ or `prev`, `versions` or `member`;
108
118
  - `linked()` with anything but a literal collection name and link role;
109
119
  - a field named like a field of the body's schema;
110
120
  - a field that misreads the schemas: a body field that isn't there, a string
111
- compared with a number, `linked()` of a collection that isn't defined in
112
- the space, doesn't declare that role, or whose role points at other
113
- collections. A `std.*` collection the space doesn't define is read untyped.
121
+ compared with a number, or `linked()` of a collection the space doesn't
122
+ define, that doesn't declare that role, or whose role points at other
123
+ collections.
114
124
 
115
- A contract can't call `linked()`: what it reads must be the same on every
125
+ A `std.*` collection the space doesn't define is read untyped. A contract
126
+ can't call `linked()`, since what a contract reads must be the same on every
116
127
  node.
117
128
 
118
- Whatever reads them reads a definition another implementation wrote, or one
119
- written by hand, as having none when its `computed` is malformed, too large,
120
- or names a field the body's schema declares. A body member the schema
121
- doesn't declare can still share a computed field's name, and a query reads
122
- the computed field: whoever defines the collection decides both anyway.
129
+ A definition may come from another implementation, or be written by hand.
130
+ When its `computed` is malformed, too large, or names a field the body's
131
+ schema declares, readers treat it as having no computed fields.
123
132
 
124
133
  ## Reading them
125
134
 
126
- - **Every record a query gives** has `computed` beside `body`: its
127
- collection's fields, or `{}` without any. Included records have theirs too.
128
- `body` stays what its author signed, so writing `{ ...record.body, text }`
129
- back never writes a computed value.
130
- - **`where` and `sort` name a computed field as they name a body field**:
131
- `{ done: false }`. A computed field may not share a name with a field of
132
- the body's schema, so a name means one thing, and a body member with a
133
- computed field's name (in a schema that lets bodies hold more) is never
134
- read in its place. With a typed collection, a name it has neither of is a
135
- type error. An include's `where` reads the computed fields of what it
136
- finds.
137
- - **Whatever watches a filter on them watches what they read.** A record
138
- comes to match `{ done: true }` when it is written, or when a record its
139
- computed fields read is: Bob's 👍 makes the todo done without changing
140
- it. So an [automation](automations.md) sets off when that 👍 is written
141
- (after its `since`), an app's own notifications say so then, once, and a
142
- carrier wakes the app on a new 👍 as well as on a new todo. Every one of
143
- them filters query results, so they read what a query works out.
144
- - Filtering or sorting on one works it out for every candidate; otherwise only
145
- for the page returned. A `linked()` lookup follows the link index, once per
146
- record, so keep fields to what a screen shows.
147
- - Worked out by the definition as it is now, not as of each record.
148
-
149
- An app that shows records from their definitions, as the example's data
150
- view does, gets each computed field as JSON Schema from
151
- `computedSchemas(definition, definitionOf)`: a count is an `integer`, a
152
- comparison a `boolean`, each marked `readOnly`. Show them beside the
135
+ Every record a query gives has `computed` beside `body`, with its
136
+ collection's fields, or `{}` without any. Included records have theirs too.
137
+ `body` stays what its author signed, so writing `{ ...record.body, text }`
138
+ back never writes a computed value.
139
+
140
+ `where` and `sort` name a computed field the way they name a body field:
141
+ `{ done: false }`. An include's `where` reads the computed fields of what it
142
+ finds. With a typed collection, a name that is neither a body field nor a
143
+ computed field is a type error.
144
+
145
+ A computed field always wins over a body member of the same name. A schema
146
+ that lets bodies hold extra members can't make a query read one in its place.
147
+ Whoever defines the collection decides both anyway.
148
+
149
+ Fields are worked out by the definition as it is now, not as it was when each
150
+ record was written.
151
+
152
+ ## Watching them
153
+
154
+ A record can come to match `{ done: true }` without changing. Bob's 👍 makes
155
+ the to-do done, so anything that watches a filter on a computed field also
156
+ watches what it reads:
157
+
158
+ - an [automation](automations.md) sets off when the 👍 is written (after its
159
+ `since`);
160
+ - an app's own notifications say so then, once;
161
+ - a carrier wakes the app on a new 👍 as well as on a new to-do.
162
+
163
+ ## Cost
164
+
165
+ Filtering or sorting on a computed field works it out for every candidate.
166
+ Otherwise it is worked out only for the page returned. A `linked()` lookup
167
+ follows the link index once per record, so keep fields to what a screen
168
+ shows.
169
+
170
+ ## Showing them in a form
171
+
172
+ An app that draws records from their definitions, as the example's data view
173
+ does, gets each computed field as JSON Schema from
174
+ `computedSchemas(definition, definitionOf)`. A count is an `integer`, a
175
+ comparison a `boolean`, and each is marked `readOnly`. Show them beside the
153
176
  body's fields, marked as worked out here, and leave them out of forms.
154
177
 
155
- Not yet: computed fields on `records.get` and `list`, and a `linked()` that
156
- follows a record's own links out.
178
+ ## Not yet
157
179
 
158
- _Source: `packages/core/src/query/computed.ts` (`checkComputed`, `checkComputedTypes`, `computedSchemas`, `computeValues`, `readsComputed`), `packages/core/src/query/filter.ts` (`fieldValue`), `packages/core/src/records/contract-builder.ts` (`buildComputed`, `storedComputed`, `ComputedContext`), `packages/core/src/records/cel.ts` (`checkCel`, `evaluateCel`: `linked`), `packages/core/src/records/cel-types.ts` (`typeOfCel`), `packages/core/src/query/engine.ts` (`runQuery`), `packages/core/src/query/types.ts` (`FilterOf`, `ComputedIn`), `packages/core/src/node/space-runtime.ts` (`define`, `computed`). Tests: `packages/core/tests/computed.test.ts`, `packages/core/tests/typed-query.test.ts`._
180
+ - Computed fields on `records.get` and `records.list`.
181
+ - A `linked()` that follows a record's own links out.
package/docs/contacts.md CHANGED
@@ -1,23 +1,117 @@
1
1
  # Contacts
2
2
 
3
- A contact is someone you share a **private space for two** with. The account
4
- keeps its list of them in its contacts space, and asks someone to become a
5
- contact by leaving a knock for them: in a space both belong to, or in their
6
- inbox.
3
+ A contact is someone you share a private **space for two** with. Use this
4
+ page to ask someone you already share a space with to become a contact. For
5
+ someone you share no space with, use their [inbox](inbox.md).
7
6
 
8
- The list and the request are conventions built on the protocol, not part of
9
- it. Peers that have never heard of `std.contact` or `std.contact-request`
10
- sync, store and judge them like any other record. The knock they carry is
11
- protocol: how it is signed and sealed, and what the person it is for checks,
12
- is [spec 07 §6](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md),
13
- the same however it is handed over.
14
- Asking someone you share **no** space with goes through their inbox
15
- ([inbox.md](inbox.md)).
7
+ ## Asking someone
16
8
 
17
- ## The list: `std.contact`
9
+ Pick a space you both belong to, and the person to ask:
18
10
 
19
- The list lives in the account's contacts space (derived with the label
20
- `minca/contacts`), one record per person:
11
+ ```ts
12
+ const { space: pairSpace, carried } = await node.contacts.ask(space.id, did, { note: 'Hi from the co-op!' });
13
+ ```
14
+
15
+ This makes a new private space for two, puts them on your list with it, and
16
+ leaves a request for them in the shared space. `space`, here `pairSpace`, is
17
+ the space for two.
18
+
19
+ `carried` is false when none of your always-on carriers held the space in
20
+ time. Then they can join only while one of your devices is online.
21
+
22
+ ## Answering a request
23
+
24
+ On their side, `requests` lists what was left for them, and `accept` joins:
25
+
26
+ ```ts
27
+ const [request] = await node.contacts.requests(space.id);
28
+ if (request) {
29
+ const contact = await node.contacts.accept(space.id, request.key);
30
+ }
31
+ ```
32
+
33
+ There is no reply. Joining the space for two is the answer, and you each
34
+ have the other on your list.
35
+
36
+ ## The list
37
+
38
+ ```ts
39
+ const contacts = await node.contacts.list();
40
+ ```
41
+
42
+ `get`, `put`, `remove`, `block` and the rest are in
43
+ [`NodeContacts`](https://minca.dev/api/core/interfaces/NodeContacts/), and
44
+ each contact is a
45
+ [`ContactView`](https://minca.dev/api/core/interfaces/ContactView/). Its
46
+ `name` is what you call them. They never see it.
47
+
48
+ `remove` and `block` leave the space for two, giving up your place there,
49
+ unless another contact names the same space. `block` keeps them on the list
50
+ with `blocked: true`, and hides their requests in every space and in your
51
+ inbox. `others` lists accounts in the space for two besides the two of you,
52
+ from its members, profiles and connected peers.
53
+
54
+ A contact's `username` is what their domain answered when you found them by
55
+ it. Nothing checks it again: once a name lapses and someone else claims it,
56
+ a lookup leads to them, and your contact keeps the old one.
57
+
58
+ ## Inviting a contact into a space
59
+
60
+ ```ts
61
+ await node.contacts.invite(did, space.id, { role: 'member' });
62
+ ```
63
+
64
+ This leaves an invite for them in your space for two. They must have joined
65
+ that space first. A request nobody has answered yet is refused, so you never
66
+ open a space to whoever a username led to before you have seen who they are.
67
+ A blocked contact is refused too.
68
+
69
+ On their side, `invites()` lists what contacts left for them, newest first,
70
+ and `join` takes them in:
71
+
72
+ ```ts
73
+ const [invite] = await node.contacts.invites();
74
+ if (invite) await node.contacts.join(invite.pairSpace, invite.key);
75
+ ```
76
+
77
+ Each item is a
78
+ [`SpaceInviteView`](https://minca.dev/api/core/interfaces/SpaceInviteView/).
79
+ Only invites to spaces you don't hold yet are listed. Only the contact's own
80
+ records count, and each invite is checked as joining checks it: signed by
81
+ the contact, for the space whose constitution it carries. That is where
82
+ `space` and `name` come from. Invites from someone blocked are not shown.
83
+
84
+ `invites()` also closes and deletes your own invites that the contact has
85
+ joined with.
86
+
87
+ ## Who may ask
88
+
89
+ `ask` and `accept` need a session note that grants `/account/write` for the
90
+ whole account. An app granted `contacts` can see the list and the requests,
91
+ but can't ask or accept. See
92
+ [spec 06 §2.5](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
93
+
94
+ ## How `ask` works
95
+
96
+ 1. It creates a private `team` space named `"<my name> & <their name>"`, and
97
+ opens an `editor` invite to it.
98
+ 2. It waits up to 3 seconds for an online carrier to hold the space
99
+ (`spaces.carried`).
100
+ 3. It writes a `std.contact` for them, with that space.
101
+ 4. It leaves the request, a sealed knock, as a `std.contact-request`.
102
+
103
+ It returns `{ space, request, carried }`: the space for two, the request's
104
+ record key, and whether a carrier held it. It needs the other person's
105
+ `contactKey` on their profile in that space. `accept` joins the invite, and
106
+ writes a `std.contact` for the asker with the space for two.
107
+
108
+ `requests(space)` skips blocked senders, and knocks whose space for two you
109
+ already hold.
110
+
111
+ ## `std.contact`
112
+
113
+ The list lives in the account's contacts space, derived with the label
114
+ `minca/contacts`, one record per person:
21
115
 
22
116
  ```
23
117
  std.contact (rules: onePer ["did"])
@@ -28,123 +122,68 @@ record key = records.onePerKey(contactsSpace, "std.contact", { did })
28
122
  // a shared key, spec 02 §7.3: onePer without @author
29
123
  ```
30
124
 
31
- `name` is what you call them; they never see it. `space` is the id of the
32
- space for two. `blocked` hides that person's knocks, in every space and in the
33
- inbox.
34
-
35
- A reader must ignore a record whose key is not the one its `did` derives. It
36
- also ignores one whose root is not the account, as it does for every record in
37
- the account's derived spaces (spec 03 §13.1).
125
+ `space` is the id of the space for two. A reader ignores a record whose key
126
+ is not the one its `did` derives. It also ignores one whose root is not the
127
+ account, as for every record in the account's derived spaces (spec 03
128
+ §13.1).
38
129
 
39
130
  ## The contact key
40
131
 
41
- A knock left in a shared space is sealed to the askee's contact key: the
42
- public half, published as `contactKey` on their profile in the space (spec 03
43
- §11). How it is derived is in spec 01 §10.1. A node holds the private half
44
- only when it was given it (`config.contactKey`); an agent never is.
132
+ A request is sealed to the other person's contact key: the public half,
133
+ published as `contactKey` on their profile in the space. A node holds the
134
+ private half only when it was given it (`config.contactKey`). An agent never
135
+ is. See spec 01 §10.1 for how it is derived, and spec 03 §11 for the
136
+ profile.
45
137
 
46
- ## Asking in a shared space
138
+ ## `std.contact-request`
47
139
 
48
140
  ```
49
141
  std.contact-request (no rules; who may write one is the space's grants)
50
142
  { to: <the askee's contact key, as on their profile here, ≤64>, sealed: string ≤16000 }
51
143
  ```
52
144
 
53
- `ask` leaves one in the space: `sealed` is a knock sealed to `to` (spec 07
54
- §6), whose invite is to a new space for two. It defines the collection first
55
- if the space lacks it, which needs `/collection/define`. In a private space
56
- the body is sealed with the space key too, so other members see that someone
57
- asked, not whom.
145
+ `sealed` is a knock sealed to `to`, whose invite is to the new space for two.
146
+ `ask` defines the collection first if the space lacks it, which needs
147
+ `/collection/define`. In a private space the body is sealed with the space
148
+ key too, so other members see that someone asked, not whom.
58
149
 
59
150
  The receiver opens a request only when `to` is its own contact key, the
60
- knock checks out (spec 07 §6), and the knock's account is the record's root
61
- and not its own. A knock copied into another record by someone else is not
62
- theirs to leave, and opens as nothing.
63
-
64
- ## `node.contacts`
65
-
66
- - `space()`: the contacts space's id, or null for a node not given it.
67
- - `list()`, `get(did)`: the list, blocked people too, by name.
68
- - `put({ did, name, space?, note? })`: adds someone, or changes what the list
69
- says about them.
70
- - `ask(space, did, { note? })` needs whole-account access and the askee's
71
- `contactKey` on their profile in that space. It creates a private `team`
72
- space named `"<my name> & <their name>"`, opens an `editor` invite to it,
73
- waits up to 3 seconds for a carrier that is online to hold it (`spaces.carried`), writes a
74
- `std.contact` for them with that space, then leaves the knock as
75
- `std.contact-request`. It returns the space for two, the record's key, and `carried`:
76
- false when no carrier held the space in time, so the askee can join only
77
- while one of the asker's devices is online.
78
- - `requests(space)` lists the knocks left there that open for this account,
79
- skipping blocked senders and knocks whose space for two the account already
80
- holds.
81
- - `accept(space, requestKey)` joins the invite (spec 03 §7.6) and writes a
82
- `std.contact` for the asker with the space for two. There is no reply
83
- record: joining is the answer.
84
- - `remove(did)` leaves the space for two (spec 03 §6.2), giving up the
85
- account's place there, unless another contact names it, and deletes the
86
- `std.contact`.
87
- - `block(did)` leaves the space for two likewise and writes the contact with
88
- `blocked: true`.
89
- - `others(did)` lists accounts other than the two seen in the space for two
90
- (members, profiles, connected peers).
91
- - `invite(did, spaceId, { role? })` invites a contact into a space you hold:
92
- it makes an invite for `role` and leaves it as a `std.space-invite` in your
93
- space for two with them. The contact must have joined the space for two: a
94
- knock nobody answered yet is refused, so a space is never opened to whoever
95
- a username happens to lead to before you have seen who they are. A blocked
96
- contact is refused.
97
- - `invites()` lists the invites a contact left for you in your space for two
98
- with them, to spaces you don't hold yet, newest first:
99
- `{ from, space, name, invite, pairSpace, key, createdAt }`. Only the
100
- contact's own records count, and each invite is checked as joining checks
101
- it: signed by the contact, for the space whose constitution it carries,
102
- which is where `space` and `name` come from. Invites from someone blocked are
103
- not shown. It also closes, and deletes, invites of yours the contact has
104
- joined with.
105
- - `join(pairSpace, key)` joins the space an invite from that contact is for.
151
+ knock checks out, and the knock's account is the record's root and not its
152
+ own. A knock someone else copied into another record is not theirs to leave,
153
+ and opens as nothing.
154
+
155
+ The list and the request are conventions: peers that have never heard of
156
+ them sync and judge them like any other record. The knock inside is
157
+ protocol, the same however it is handed over. See
158
+ [spec 07 §6](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md).
106
159
 
107
160
  ## `std.space-invite`
108
161
 
109
- An invite to a space, left in a space for two: `{ space, invite }`,
162
+ An invite to a space, left in a space for two: `{ space, invite }`, with
110
163
  `onePer: ['space']`, so inviting again to the same space replaces it.
111
164
 
112
- It is open until its maker's node sees the contact in the space and closes
113
- it, the next time it reads `invites()`. A contact removed before then can
114
- rejoin with it, as with any open role invite
115
- ([#170](https://github.com/leifriksheim/minca/issues/170)), and whoever else
116
- holds a place in the space for two reads it
117
- ([#313](https://github.com/leifriksheim/minca/issues/313)). An invite with no
118
- role, to view, carries the space key and can't be closed
119
- ([#172](https://github.com/leifriksheim/minca/issues/172)).
120
-
121
- A contact's `username` is what their domain answered when you found them by
122
- it. Nothing checks it again: once a name lapses and someone else claims it, a
123
- lookup leads to them, and the contact keeps the old one.
165
+ It stays open until its maker's node sees the contact in the space and
166
+ closes it, the next time it reads `invites()`.
124
167
 
125
- `ask` and `accept` need a session note that grants `/account/write` for the
126
- whole account, as a knock does. An app granted `contacts` sees the list and
127
- requests, but may not ask or accept
128
- ([spec 06 §2.5](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
129
-
130
- _Source: `packages/core/src/schemas/contacts.ts` (`contact`), `packages/core/src/identity/contact-key.ts` (`deriveContactKeyBytes`), `packages/core/src/inbox/inbox.ts` (`sealKnock`, `openKnock`), `packages/core/src/node/node-contacts.ts` (`openMail`, `makePair`, `contacts`), `packages/core/src/schemas/contacts.ts` (`contactRequest`), `packages/core/src/node/types.ts` (`NodeContacts`), `packages/core/src/space/account-registry.ts` (`deriveContactsSpace`). Tests: `packages/core/tests/contacts.test.ts`, `packages/core/tests/attacks.test.ts` ("a knock re-posted by someone else…"), `packages/core/tests/usernames.test.ts` ("node.contacts.invite")._
168
+ Until then, a contact removed from the space can rejoin with it, as with
169
+ any open role invite ([#170](https://github.com/leifriksheim/minca/issues/170)).
170
+ Anyone else with a place in the space for two can read it
171
+ ([#313](https://github.com/leifriksheim/minca/issues/313)). A view-only
172
+ invite carries the space key and can't be closed
173
+ ([#172](https://github.com/leifriksheim/minca/issues/172)).
131
174
 
132
175
  ## Planned: requests that can be taken back
133
176
 
134
- A list that never names a space the account left, and requests that can be
135
- taken back. Today the `std.contact` does not record where `ask` left the
136
- knock, so `remove` and `block` leave it standing: the askee can still accept
137
- it, into a space nobody holds. And `spaces.leave` on a space for two leaves the
138
- `std.contact` naming it.
139
-
140
- - `std.contact` gains `asked?: { space: string ≤256, key: string ≤256 }`, the
141
- space and record key of the request. `ask` writes it.
142
- - `remove(did)` and `block(did)` delete the request at `asked` when the
143
- space is still held and the record still stands, before leaving the space
144
- for two.
145
- - `spaces.leave(id)` on a space a `std.contact` names does what `remove` does
146
- for that contact.
147
- - `ContactView` gains `waiting: boolean`, true while the other account has no
148
- member record in the space for two.
177
+ Today `remove` and `block` leave your request standing, so they can still
178
+ accept it, into a space nobody holds. And `spaces.leave` on a space for two
179
+ leaves the `std.contact` that names it. The plan:
180
+
181
+ - `std.contact` gains `asked?: { space: string ≤256, key: string ≤256 }`,
182
+ where `ask` left the request.
183
+ - `remove` and `block` delete that request, when the space is still held and
184
+ the record still stands, before leaving the space for two.
185
+ - `spaces.leave` on a space a `std.contact` names does what `remove` does.
186
+ - `ContactView` gains `waiting: boolean`, true while the other account has
187
+ no member record in the space for two.
149
188
 
150
189
  Tracked in [#40](https://github.com/leifriksheim/minca/issues/40).