@minca/core 0.1.8 → 0.1.10
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 +1 -1
- package/dist/files/file-id.d.ts +51 -0
- package/dist/files/file-id.d.ts.map +1 -0
- package/dist/files/file-id.js +97 -0
- package/dist/files/file-id.js.map +1 -0
- package/dist/files/seal.d.ts +20 -0
- package/dist/files/seal.d.ts.map +1 -0
- package/dist/files/seal.js +77 -0
- package/dist/files/seal.js.map +1 -0
- package/dist/files/space-files.d.ts +51 -0
- package/dist/files/space-files.d.ts.map +1 -0
- package/dist/files/space-files.js +476 -0
- package/dist/files/space-files.js.map +1 -0
- package/dist/identity/abilities.d.ts +3 -3
- package/dist/identity/abilities.d.ts.map +1 -1
- package/dist/identity/abilities.js +9 -11
- package/dist/identity/abilities.js.map +1 -1
- package/dist/identity/root-signer.d.ts +0 -5
- package/dist/identity/root-signer.d.ts.map +1 -1
- package/dist/identity/root-signer.js +0 -1
- package/dist/identity/root-signer.js.map +1 -1
- package/dist/index.d.ts +5 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -2
- package/dist/index.js.map +1 -1
- package/dist/node/api.d.ts +5 -1
- package/dist/node/api.d.ts.map +1 -1
- package/dist/node/api.js +10 -2
- package/dist/node/api.js.map +1 -1
- package/dist/node/carrier.d.ts +17 -2
- package/dist/node/carrier.d.ts.map +1 -1
- package/dist/node/carrier.js +26 -4
- package/dist/node/carrier.js.map +1 -1
- package/dist/node/copy.d.ts +0 -4
- package/dist/node/copy.d.ts.map +1 -1
- package/dist/node/copy.js +26 -0
- package/dist/node/copy.js.map +1 -1
- package/dist/node/host.d.ts +66 -1
- package/dist/node/host.d.ts.map +1 -1
- package/dist/node/host.js +571 -5
- package/dist/node/host.js.map +1 -1
- package/dist/node/index.d.ts +2 -2
- package/dist/node/index.d.ts.map +1 -1
- package/dist/node/index.js +1 -1
- package/dist/node/index.js.map +1 -1
- package/dist/node/node.d.ts.map +1 -1
- package/dist/node/node.js +328 -269
- package/dist/node/node.js.map +1 -1
- package/dist/node/remote.d.ts +6 -5
- package/dist/node/remote.d.ts.map +1 -1
- package/dist/node/remote.js +141 -194
- package/dist/node/remote.js.map +1 -1
- package/dist/node/space-runtime.d.ts +9 -0
- package/dist/node/space-runtime.d.ts.map +1 -1
- package/dist/node/space-runtime.js +194 -98
- package/dist/node/space-runtime.js.map +1 -1
- package/dist/node/stores.d.ts +44 -8
- package/dist/node/stores.d.ts.map +1 -1
- package/dist/node/stores.js +44 -7
- package/dist/node/stores.js.map +1 -1
- package/dist/node/types.d.ts +77 -10
- package/dist/node/types.d.ts.map +1 -1
- package/dist/node/usage.d.ts +54 -0
- package/dist/node/usage.d.ts.map +1 -0
- package/dist/node/usage.js +201 -0
- package/dist/node/usage.js.map +1 -0
- package/dist/node/worker.d.ts +1 -1
- package/dist/node/worker.d.ts.map +1 -1
- package/dist/node/worker.js +10 -6
- package/dist/node/worker.js.map +1 -1
- package/dist/schema/version.d.ts +5 -0
- package/dist/schema/version.d.ts.map +1 -1
- package/dist/schema/version.js +1 -0
- package/dist/schema/version.js.map +1 -1
- package/dist/schemas/fragments.d.ts +23 -2
- package/dist/schemas/fragments.d.ts.map +1 -1
- package/dist/schemas/fragments.js +5 -2
- package/dist/schemas/fragments.js.map +1 -1
- package/dist/schemas/library/annotations.d.ts +24 -0
- package/dist/schemas/library/annotations.d.ts.map +1 -1
- package/dist/schemas/library/community.d.ts +24 -0
- package/dist/schemas/library/community.d.ts.map +1 -1
- package/dist/schemas/library/life.d.ts +72 -0
- package/dist/schemas/library/life.d.ts.map +1 -1
- package/dist/schemas/library/media.d.ts +144 -0
- package/dist/schemas/library/media.d.ts.map +1 -1
- package/dist/schemas/library/money.d.ts +24 -0
- package/dist/schemas/library/money.d.ts.map +1 -1
- package/dist/schemas/library/publishing.d.ts +96 -0
- package/dist/schemas/library/publishing.d.ts.map +1 -1
- package/dist/schemas/library/social.d.ts +72 -0
- package/dist/schemas/library/social.d.ts.map +1 -1
- package/dist/session/auth.d.ts +20 -0
- package/dist/session/auth.d.ts.map +1 -1
- package/dist/session/auth.js +88 -64
- package/dist/session/auth.js.map +1 -1
- package/dist/session/connect.d.ts +50 -8
- package/dist/session/connect.d.ts.map +1 -1
- package/dist/session/connect.js +91 -27
- package/dist/session/connect.js.map +1 -1
- package/dist/session/connection.d.ts +39 -6
- package/dist/session/connection.d.ts.map +1 -1
- package/dist/session/connection.js +107 -38
- package/dist/session/connection.js.map +1 -1
- package/dist/session/hosting.d.ts +88 -28
- package/dist/session/hosting.d.ts.map +1 -1
- package/dist/session/hosting.js +137 -6
- package/dist/session/hosting.js.map +1 -1
- package/dist/session/index.d.ts +5 -5
- package/dist/session/index.d.ts.map +1 -1
- package/dist/session/index.js +2 -2
- package/dist/session/index.js.map +1 -1
- package/dist/session/places.d.ts +2 -0
- package/dist/session/places.d.ts.map +1 -1
- package/dist/session/places.js +8 -2
- package/dist/session/places.js.map +1 -1
- package/dist/space/account-registry.d.ts +27 -4
- package/dist/space/account-registry.d.ts.map +1 -1
- package/dist/space/account-registry.js +25 -3
- package/dist/space/account-registry.js.map +1 -1
- package/dist/space/roles.d.ts +59 -140
- package/dist/space/roles.d.ts.map +1 -1
- package/dist/space/roles.js +328 -427
- package/dist/space/roles.js.map +1 -1
- package/dist/storage/blob/directory.d.ts +14 -0
- package/dist/storage/blob/directory.d.ts.map +1 -0
- package/dist/storage/blob/directory.js +80 -0
- package/dist/storage/blob/directory.js.map +1 -0
- package/dist/storage/folder-adapter.d.ts +22 -0
- package/dist/storage/folder-adapter.d.ts.map +1 -1
- package/dist/storage/folder-adapter.js +5 -5
- package/dist/storage/folder-adapter.js.map +1 -1
- package/dist/storage/mirror.d.ts +9 -2
- package/dist/storage/mirror.d.ts.map +1 -1
- package/dist/storage/mirror.js +60 -35
- package/dist/storage/mirror.js.map +1 -1
- package/dist/storage/segment.d.ts +7 -2
- package/dist/storage/segment.d.ts.map +1 -1
- package/dist/storage/segment.js +25 -3
- package/dist/storage/segment.js.map +1 -1
- package/dist/sync/sync-engine.d.ts +2 -0
- package/dist/sync/sync-engine.d.ts.map +1 -1
- package/dist/sync/sync-engine.js +5 -0
- package/dist/sync/sync-engine.js.map +1 -1
- package/dist/sync/sync-messages.d.ts +24 -0
- package/dist/sync/sync-messages.d.ts.map +1 -1
- package/dist/sync/sync-messages.js.map +1 -1
- package/docs/actions.md +3 -3
- package/docs/agents.md +2 -2
- package/docs/blueprints-and-guides.md +20 -1
- package/docs/bots.md +1 -1
- package/docs/node.md +138 -75
- package/docs/sign-in.md +16 -9
- package/docs/spaces.md +18 -10
- package/docs/standard-library.md +16 -20
- package/docs/storage.md +121 -16
- package/package.json +1 -1
package/docs/node.md
CHANGED
|
@@ -27,7 +27,7 @@ conveniences.
|
|
|
27
27
|
| `sessionTtlSeconds` | number, optional | Lifetime of each session note. Default `3600`. |
|
|
28
28
|
| `sessionKey` | `CryptoKeyPair`, optional | Sign with this key instead of a fresh one. Used when the signer's note names a specific key (an app's key, an agent's key, [spec 06 §2](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md), [spec 06 §3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)). |
|
|
29
29
|
| `writerKey` | `WriterKeySource`, optional | Keep a signing key across runs, so this device keeps one log in each space ([writer keys](#writer-keys)). Ignored with `sessionKey`. |
|
|
30
|
-
| `watchIntervalMs` | number, optional | How often to look for writes another process made
|
|
30
|
+
| `watchIntervalMs` | number, optional | How often to look for writes another app, device or process made: a data folder's segments, a store file another process shares. `0` disables. Default `2000`. _Implementation detail._ |
|
|
31
31
|
| `cache` | `CacheConfig`, optional | Hold only the collections used, in spaces that name a keeper ([holding part of a space](#holding-part-of-a-space)). |
|
|
32
32
|
| `mailbox` | `MailboxClient`, optional | How doors reach relays' mailboxes ([07](https://github.com/leifriksheim/minca/blob/main/spec/07-doors.md)). Default: a WebSocket to each relay. |
|
|
33
33
|
|
|
@@ -55,12 +55,16 @@ A node acts for one account (`node.did`) and signs with one session key
|
|
|
55
55
|
(`node.sessionDid`) for its whole lifetime. To act for another account, start
|
|
56
56
|
another node.
|
|
57
57
|
|
|
58
|
-
`
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
58
|
+
`revokeKey(key, { spaces?, waitMs? })` revokes a key of the account, each
|
|
59
|
+
revoke with a cutoff at what the key wrote: in `spaces`, or by default
|
|
60
|
+
wherever the account writes (every space it lists, its carry spaces, the
|
|
61
|
+
contacts space and the account registry). It says whether a peer took each in
|
|
62
|
+
within `waitMs`. The account home's disconnect calls it for an app's key.
|
|
63
|
+
`revokeSelf()` does the same for the node's own session key, and forgets a
|
|
64
|
+
lasting key at once; the account home's sign-out calls it
|
|
65
|
+
([spec 01 §7.4](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md)).
|
|
66
|
+
A record is judged with no time, so a revoke, not the note running out, is
|
|
67
|
+
what ends what a key can write. An agent's view refuses both.
|
|
64
68
|
|
|
65
69
|
`close()` stops renewal, closes every open space (flushing what each keeps,
|
|
66
70
|
stopping sync and disconnecting its transports), closes the registry store,
|
|
@@ -76,11 +80,10 @@ which hides where the key lives and is asked only for notes. This is an
|
|
|
76
80
|
in-process interface, not a wire format; what a note must be is
|
|
77
81
|
[spec 01 §7](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md).
|
|
78
82
|
|
|
79
|
-
| Member | Type
|
|
80
|
-
| -------------------------------------------------------------- |
|
|
81
|
-
| `did` | string
|
|
82
|
-
| `
|
|
83
|
-
| `delegate({audience, command, subject?, policy?, expiration})` | → `Delegation` | Issue a note from the account to `audience` |
|
|
83
|
+
| Member | Type | Meaning |
|
|
84
|
+
| -------------------------------------------------------------- | -------------- | ------------------------------------------- |
|
|
85
|
+
| `did` | string | The account DID |
|
|
86
|
+
| `delegate({audience, command, subject?, policy?, expiration})` | → `Delegation` | Issue a note from the account to `audience` |
|
|
84
87
|
|
|
85
88
|
- The **local** signer (`createLocalRootSigner`) calls `issueDelegation` with
|
|
86
89
|
the root key. `subject` defaults to the account's own DID (the whole
|
|
@@ -89,6 +92,12 @@ in-process interface, not a wire format; what a note must be is
|
|
|
89
92
|
already issued to the app's key, unchanged, and refuses once the grant's
|
|
90
93
|
`expiresAt` has passed. It cannot mint new notes
|
|
91
94
|
([spec 06 §2](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
95
|
+
- A signer **across a port** (`serveSigner` on the side that holds the key,
|
|
96
|
+
`remoteSigner` on the node's, as a page signs for its worker's node) signs
|
|
97
|
+
only notes of the session note's shape below: `command` `/`, no `subject`,
|
|
98
|
+
no `policy`. It refuses anything else without asking the signer behind it.
|
|
99
|
+
The audience and expiration are the far end's to pick, so it bounds
|
|
100
|
+
neither.
|
|
92
101
|
|
|
93
102
|
The **session note** a node asks for when it starts:
|
|
94
103
|
|
|
@@ -124,7 +133,7 @@ policy statement it can't read that way, so it never offers more than the
|
|
|
124
133
|
note grants; peers judge each use against the note itself
|
|
125
134
|
([spec 06 §2.5](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
126
135
|
|
|
127
|
-
_Source: `packages/core/src/identity/root-signer.ts`, `packages/core/src/identity/ucan.ts` (`issueDelegation`, `verifyNote`), `packages/core/src/identity/abilities.ts` (`noteTerms`, `noteSpaces`), `packages/core/src/node/node.ts` (`SESSION_COMMAND`, `delegate`), `packages/core/src/session/connect.ts` (`grantSigner`, `grantTerms`). Tests: `packages/core/tests/ucan.test.ts`, `packages/core/tests/node.test.ts`, `packages/core/tests/connect.test.ts`._
|
|
136
|
+
_Source: `packages/core/src/identity/root-signer.ts`, `packages/core/src/node/remote.ts` (`serveSigner`, `remoteSigner`), `packages/core/src/identity/ucan.ts` (`issueDelegation`, `verifyNote`), `packages/core/src/identity/abilities.ts` (`noteTerms`, `noteSpaces`), `packages/core/src/node/node.ts` (`SESSION_COMMAND`, `delegate`), `packages/core/src/session/connect.ts` (`grantSigner`, `grantTerms`). Tests: `packages/core/tests/ucan.test.ts`, `packages/core/tests/remote.test.ts` ("the page's signer, from a worker"), `packages/core/tests/node.test.ts`, `packages/core/tests/connect.test.ts`._
|
|
128
137
|
|
|
129
138
|
## Renewing the session note
|
|
130
139
|
|
|
@@ -142,7 +151,9 @@ The note format, and that every record carries it, are protocol
|
|
|
142
151
|
|
|
143
152
|
A signer need not be able to sign. `grantSigner(grant)` answers every
|
|
144
153
|
`delegate` call with the one note an account home granted, unchanged, and
|
|
145
|
-
refuses once `grant.expiresAt` has passed.
|
|
154
|
+
refuses once `grant.expiresAt` has passed. `grantSigner(() => grant)` answers
|
|
155
|
+
with whichever grant the getter returns, as the desktop app's node does when
|
|
156
|
+
a renewed grant replaces the last. A node started from a grant
|
|
146
157
|
therefore never gets a fresh note: its "renewal" returns the same note, and when
|
|
147
158
|
it runs out the app must connect again ([spec 06 §2.9](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
148
159
|
|
|
@@ -165,9 +176,13 @@ What a path means is the factory's choice:
|
|
|
165
176
|
- `indexedDBStores(prefix)` — one IndexedDB database per path, named
|
|
166
177
|
`<prefix>:<path with / replaced by :>`. Never sealed: the browser profile
|
|
167
178
|
already guards it.
|
|
168
|
-
- `folderStores(directory, { basePath?, localKey? })` — a
|
|
169
|
-
|
|
170
|
-
when one
|
|
179
|
+
- `folderStores(directory, { basePath?, localKey?, local? })` — a data folder
|
|
180
|
+
([sync and storage](storage.md#data-folders)): the `registry` in the folder
|
|
181
|
+
under `basePath`, sealed under `localKey` (`deriveLocalKey(seed)`) when one
|
|
182
|
+
is given; every other path in `local`; and each space mirrored to the
|
|
183
|
+
folder's segments, which the factory names as `folder`.
|
|
184
|
+
- `directoryStores(directory, { localKey? })` — a directory on this device,
|
|
185
|
+
one file per entry and per version; the `registry` sealed as above.
|
|
171
186
|
|
|
172
187
|
Every version a node signs in a space takes the next place in its key's line
|
|
173
188
|
for that collection there ([spec 02 §4.10](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)).
|
|
@@ -224,7 +239,7 @@ node makes a key for this run as it would without a source.
|
|
|
224
239
|
write fails until the page reloads, since signing on would fork the line
|
|
225
240
|
and withdraw what the key wrote. A slot whose connection the browser
|
|
226
241
|
closed opens again only while it still holds the key.
|
|
227
|
-
- The CLI keeps them in
|
|
242
|
+
- The CLI keeps them outside its home, in `<local>/writers/slot-<n>/` (`localPath` in `packages/cli/src/home.ts`, [sync and storage](storage.md#data-folders)): the key as
|
|
228
243
|
JWK in an envelope (spec 01 §9.1) under the account's local key, with label
|
|
229
244
|
`minca/writer-key/v1` and bound `{ did: <account DID>, slot: <n> }`
|
|
230
245
|
(`key.sealed`, mode 600), so a copy of the files can't sign, and a key file
|
|
@@ -242,7 +257,8 @@ by default. These names are _implementation details_ ([sync and storage](storage
|
|
|
242
257
|
a pod's layout is in
|
|
243
258
|
[05](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md).
|
|
244
259
|
A node also opens `mirrors/<spaceId>/<n>` for a mirror's writer state
|
|
245
|
-
([mirrors](storage.md#mirrors)),
|
|
260
|
+
([mirrors](storage.md#mirrors)), `folder/<spaceId>` for a data folder's, and
|
|
261
|
+
a host `host` for its subscriptions.
|
|
246
262
|
|
|
247
263
|
`copyAccountData({ from, to, did, accountKey? })` copies every space an
|
|
248
264
|
account holds, with its key and records, from one set of stores to another —
|
|
@@ -296,8 +312,8 @@ needs no grant. A founder who leaves is a founder no more, for good; to stay
|
|
|
296
312
|
without being one, `spaces.stepDown`
|
|
297
313
|
([spaces](spaces.md#the-top-and-founders)). Then it deletes
|
|
298
314
|
the space's `sys.joined` record in the account registry, closes the space and
|
|
299
|
-
forgets it with its keys. The account registry
|
|
300
|
-
be left.
|
|
315
|
+
forgets it with its keys. The account registry, the contacts space and carry
|
|
316
|
+
spaces cannot be left.
|
|
301
317
|
|
|
302
318
|
- The removal goes out only while the space is open, so `leave` waits up to
|
|
303
319
|
5 s for a peer of another account to say it has it. With nobody reachable,
|
|
@@ -312,7 +328,7 @@ be left.
|
|
|
312
328
|
|
|
313
329
|
`contacts.remove` and `contacts.block` leave the space for two this way.
|
|
314
330
|
|
|
315
|
-
_Source: `packages/core/src/node/node.ts` (`spaces.leave`, `giveUpPlace`, `forget`, `LEAVE_WAIT_MS`), `packages/core/src/node/space-runtime.ts` (`giveUpPlace`). Tests: `packages/core/tests/key-change.test.ts` ("leaving a private space"), `packages/core/tests/contacts.test.ts` ("removing a contact gives up your place"), `packages/core/tests/node.test.ts` ("the account registry")._
|
|
331
|
+
_Source: `packages/core/src/node/node.ts` (`spaces.leave`, `giveUpPlace`, `forget`, `LEAVE_WAIT_MS`), `packages/core/src/node/space-runtime.ts` (`giveUpPlace`). Tests: `packages/core/tests/key-change.test.ts` ("leaving a private space"), `packages/core/tests/contacts.test.ts` ("removing a contact gives up your place"), `packages/core/tests/node.test.ts` ("the account registry"), `packages/core/tests/carrier.test.ts` ("its carry space cannot be left…")._
|
|
316
332
|
|
|
317
333
|
## Holding part of a space
|
|
318
334
|
|
|
@@ -402,26 +418,23 @@ Three kinds of space are the account's own machinery and are hidden from
|
|
|
402
418
|
| -------------------- | ------------------------------------------ | -------------------------------------------------------------- |
|
|
403
419
|
| The account registry | the account key | Never in the node's registry; opened directly. Cannot be left. |
|
|
404
420
|
| The contacts space | the account key, or `config.contactsSpace` | Held in the registry, hidden. Cannot be left. |
|
|
405
|
-
| Carry spaces |
|
|
421
|
+
| Carry spaces | the account key and the carrier's key | Never in the node's registry; opened directly. Cannot be left. |
|
|
406
422
|
|
|
407
423
|
**Reconciling.** With an account key, the node makes its spaces match the
|
|
408
424
|
account's list of `sys.joined` records. This runs at start and whenever
|
|
409
425
|
records change in the account registry, one run at a time. It:
|
|
410
426
|
|
|
411
|
-
1. joins every
|
|
412
|
-
forgets one whose carrier was removed more than 30 days ago (kept open until
|
|
413
|
-
then, so an offline carrier still hears it was removed);
|
|
414
|
-
2. joins every space a live `sys.joined` record names that the node does not
|
|
427
|
+
1. joins every space a live `sys.joined` record names that the node does not
|
|
415
428
|
hold, using the view-only invite in the record;
|
|
416
|
-
|
|
417
|
-
|
|
429
|
+
2. leaves every space whose `sys.joined` record is deleted;
|
|
430
|
+
3. writes a `sys.joined` record for any space held here that the account
|
|
418
431
|
registry has never heard of (joined before the registry existed, or on a
|
|
419
432
|
node without the account key);
|
|
420
|
-
|
|
433
|
+
4. brings every carrier's passes and wakes up to date
|
|
421
434
|
([spec 06 §4.2](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md));
|
|
422
|
-
|
|
435
|
+
5. names the account's carriers as keepers of the open spaces it manages
|
|
423
436
|
(also whenever a space opens);
|
|
424
|
-
|
|
437
|
+
6. asks every host the account uses how it stands, handing it the spaces if it
|
|
425
438
|
has been paid since ([carriers and hosting](#carriers-hosting-and-notifications)),
|
|
426
439
|
without waiting for the answer.
|
|
427
440
|
|
|
@@ -586,7 +599,8 @@ successors, mine, heads, key, relays, keepers, copies, forks, flagged }`
|
|
|
586
599
|
with at most one more queued.
|
|
587
600
|
- `node.account` — `profile()`, `setName(name)` (writes `sys.profile`, key
|
|
588
601
|
`profile`, in the account registry, then republishes the profile in every
|
|
589
|
-
open space), `
|
|
602
|
+
open space), `setAvatar({ bytes, mime } | null, { name? })` and `picture()`
|
|
603
|
+
(the account's picture, likewise; see [spaces](spaces.md)), `revoke(key, { waitMs? })` (one of the account's keys, by DID, in the account registry). All need the account
|
|
590
604
|
key.
|
|
591
605
|
- `spaces.revoke(space, key, { waitMs? })` and `account.revoke` resolve once the revoke is written; with
|
|
592
606
|
`waitMs`, once a peer says it has taken it in, or that long has passed (`true` when one did). A node
|
|
@@ -697,7 +711,9 @@ throws unless the note verifies, grants records only (its command is under
|
|
|
697
711
|
`delegate`; `asAgent`;
|
|
698
712
|
- sees the contact list only if the contacts space is within its note.
|
|
699
713
|
|
|
700
|
-
Closing the agent leaves the underlying node running.
|
|
714
|
+
Closing the agent leaves the underlying node running. A node used across a
|
|
715
|
+
port (`remoteNode`) starts no agent: the agent's keys would have to cross, so
|
|
716
|
+
an agent is started on the node itself.
|
|
701
717
|
|
|
702
718
|
An agent granted `scope: account` gets a records-only note for every space
|
|
703
719
|
(`/record`, about the whole account) and the account key in its
|
|
@@ -707,7 +723,7 @@ requests and knocks on the account's doors ([doors.md](doors.md)).
|
|
|
707
723
|
|
|
708
724
|
Which of these each method of the node is — passed through, held to the note's spaces, or refused — is one table, `API` in `packages/core/src/node/api.ts`; a new method does not type-check until it is decided there. The same table lists what `remoteNode` forwards.
|
|
709
725
|
|
|
710
|
-
_Source: `packages/core/src/node/node.ts` (`asAgent`), `packages/core/src/node/api.ts` (`API`). Tests: `packages/core/tests/records-only.test.ts` ("an agent acting for a person"), `packages/core/tests/remote.test.ts
|
|
726
|
+
_Source: `packages/core/src/node/node.ts` (`asAgent`), `packages/core/src/node/api.ts` (`API`). Tests: `packages/core/tests/records-only.test.ts` ("an agent acting for a person"), `packages/core/tests/remote.test.ts` ("no agent is started across the port…")._
|
|
711
727
|
|
|
712
728
|
## The app-side client
|
|
713
729
|
|
|
@@ -736,8 +752,7 @@ account: connecting as another account deletes the last one's, so its
|
|
|
736
752
|
spaces never reach the new one's registry. Copied without the keychain, the
|
|
737
753
|
folder yields no key, grant or private body, only what a carrier sees; a
|
|
738
754
|
program running as the person can ask the keychain, as it can read a
|
|
739
|
-
browser profile. Renewing keeps the key
|
|
740
|
-
revoke the last, withdrawing what the app wrote that the home hadn't seen.
|
|
755
|
+
browser profile. Renewing keeps the key (a page's app asks with a new one each time, below).
|
|
741
756
|
The key changes only when the app leaves an account: disconnecting, from the
|
|
742
757
|
app or at the home, forgets it (`forgetAppKey` in a page), so a revoked key
|
|
743
758
|
stays revoked. A home that answers as another account than the one connected
|
|
@@ -772,29 +787,67 @@ closed it, and gives up after 10 minutes by default.
|
|
|
772
787
|
starts a node with:
|
|
773
788
|
|
|
774
789
|
- `signer = grantSigner(grant)` ([renewing the session note](#renewing-the-session-note)):
|
|
775
|
-
`did` = `grant.did
|
|
790
|
+
`did` = `grant.did`;
|
|
776
791
|
- `sessionKey` = the app's key;
|
|
777
792
|
- stores `indexedDBStores('minca-app:<grant.did>')` unless given;
|
|
778
793
|
- `cache: {}` unless `cache: false` ([holding part of a space](#holding-part-of-a-space));
|
|
779
|
-
- `accountKey`, `contactKey`, `contactsSpace` from the grant when present
|
|
780
|
-
|
|
794
|
+
- `accountKey`, `contactKey`, `contactsSpace` from the grant when present (never `contactKey` under a records-only note), and
|
|
795
|
+
relays = the app's relays ∪ `grant.relays` (`nodeOptionsFromGrant`).
|
|
781
796
|
|
|
782
|
-
It then joins each granted space it does not hold yet, passing its `memberKey
|
|
797
|
+
It then joins each granted space it does not hold yet, passing its `memberKey`
|
|
798
|
+
(`joinGranted`). The desktop app's node (`minca app-node`) and the agent on a
|
|
799
|
+
computer start theirs from a grant the same way, from their own folders.
|
|
783
800
|
|
|
784
|
-
**The connection.** `createMincaConnection({ home, request, network?, storage?, stores? })`
|
|
801
|
+
**The connection.** `createMincaConnection({ home, request, network?, storage?, stores?, worker?, keys?, account? })`
|
|
785
802
|
is the app's twin of [sign-in](sign-in.md): statuses `starting`, `disconnected`,
|
|
786
803
|
`connecting`, `ready`, `expired`. With `worker`, it runs the node there
|
|
787
804
|
(`startNodeInWorker`); a worker that reports a load error, or does not say the
|
|
788
805
|
node started within 30 s (`WorkerNotStarted`), is given up on and the node
|
|
789
|
-
runs in the page. A worker that started and refused passes its reason on.
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
a space it emits `revoked` ([events](#events)), and the connection forgets the
|
|
795
|
-
grant and the app key. `propose(automations)` sends a proposal to the grant's home
|
|
806
|
+
runs in the page. A worker that started and refused passes its reason on.
|
|
807
|
+
It switches to `expired` at `expiresAt` (`watchGrant`). When the node sees its
|
|
808
|
+
own note revoked in a space it emits `revoked` ([events](#events)), and the
|
|
809
|
+
connection forgets that account's grant and key. `propose(automations)` sends
|
|
810
|
+
a proposal to the grant's home
|
|
796
811
|
([spec 06 §2.11](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
797
812
|
|
|
813
|
+
**Several accounts.** The connection keeps a grant for every account the
|
|
814
|
+
person connects, and acts for one at a time; `state.accounts` lists them
|
|
815
|
+
(`did`, the `name` the home gave, `expiresAt`), in the order they were first
|
|
816
|
+
connected. Each grant is made out to a key of its own, named
|
|
817
|
+
`account-<uuid>` in `appKey`'s store (or `keys`, given), so peers never see
|
|
818
|
+
one key act for two accounts. They are kept in `localStorage` under
|
|
819
|
+
`minca.grants` (`[{ grant, keyName }]`), the account acted for last under
|
|
820
|
+
`minca.account`, and the person's chosen home under `minca.home` (`home` in
|
|
821
|
+
the config is only a default). A grant of another format (`v` other than
|
|
822
|
+
`GRANT_VERSION`, 2) is dropped when read; one that ran out stays, and opens
|
|
823
|
+
as `expired`.
|
|
824
|
+
|
|
825
|
+
- `start()` acts for the account `account(accounts)` names, else the one used
|
|
826
|
+
last, else the first.
|
|
827
|
+
- `use(did)` acts for another connected account. Its grant is here, so the
|
|
828
|
+
home is not asked; the node acting for the last one closes, and one for
|
|
829
|
+
this one starts, with its own stores.
|
|
830
|
+
- `connect(home?)` asks with a new key, and acts for whichever account the
|
|
831
|
+
person chooses at the home: a new one, or one connected already, whose grant
|
|
832
|
+
it renews. A key that asked once may hold a note from whatever account the
|
|
833
|
+
home was signed in as, so no key is asked with twice. An account connected
|
|
834
|
+
again gets the new key and the app forgets the old one; the home revokes
|
|
835
|
+
nothing, and what the old key wrote stands
|
|
836
|
+
([spec 06 §2.10](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
837
|
+
While it waits, an app acting for an account stays `ready`; a grant whose
|
|
838
|
+
node won't start is kept, and the connection says `disconnected` with why.
|
|
839
|
+
- `disconnect(did?)` forgets an account's grant and key (default the one
|
|
840
|
+
acted for) and acts for the next connected account, or none. Disconnected
|
|
841
|
+
at the home instead, it acts for none, with `error` saying why, rather than
|
|
842
|
+
another account the person didn't choose.
|
|
843
|
+
|
|
844
|
+
Another tab's changes reach `state.accounts` by `storage` events; each tab
|
|
845
|
+
acts for its own account. A tab whose account another tab connected again
|
|
846
|
+
goes on with its key until it starts again, then takes the newer grant; one
|
|
847
|
+
whose key is revoked takes up a newer grant rather than forgetting it. A
|
|
848
|
+
shared worker runs a node per key, not only per account, so tabs on two keys
|
|
849
|
+
never share one. Switching again before a node has started closes it.
|
|
850
|
+
|
|
798
851
|
**Showing notifications.** The app shows its own notifications.
|
|
799
852
|
`watchNotifications(node, { origin?, onNotify })` needs the account key (an
|
|
800
853
|
app with `scope: account`): it reads the account's own automations naming the
|
|
@@ -808,20 +861,19 @@ held the first time an automation made it look there; anything arriving after th
|
|
|
808
861
|
is, even while the account or the list of spaces changes. How the app shows a match is its own
|
|
809
862
|
to decide; a "Notify me" button is where a proposal usually starts.
|
|
810
863
|
|
|
811
|
-
_Source: `packages/core/src/session/connect.ts` (`appKey`, `forgetAppKey`, `homeAddress`, `connectToHome`, `proposeToHome`, `startConnectedNode`, `grantSigner`), `packages/core/src/session/connection.ts`, `packages/core/src/node/watch-notifications.ts`, `packages/core/src/space/own-automations.ts` (`matchesRecord`). Tests: `packages/core/tests/connect.test.ts` ("an account home typed by a person", "an app showing its own notifications"), `packages/core/tests/topics.test.ts` ("an automation of the account’s own: its where"), `packages/core/tests/watch-notifications.test.ts`._
|
|
864
|
+
_Source: `packages/core/src/session/connect.ts` (`appKey`, `forgetAppKey`, `homeAddress`, `connectToHome`, `proposeToHome`, `startConnectedNode`, `nodeOptionsFromGrant`, `joinGranted`, `grantSigner`, `usableGrant`, `watchGrant`, `grantStore`), `packages/cli/src/app-node.ts` (`startDesktopNode`), `packages/core/src/session/connection.ts`, `packages/core/src/node/watch-notifications.ts`, `packages/core/src/space/own-automations.ts` (`matchesRecord`). Tests: `packages/core/tests/connect.test.ts` ("an account home typed by a person", "watching a grant", "an app connected to several accounts", "an app showing its own notifications"), `packages/core/tests/topics.test.ts` ("an automation of the account’s own: its where"), `packages/core/tests/watch-notifications.test.ts`._
|
|
812
865
|
|
|
813
866
|
## Carriers, hosting and notifications
|
|
814
867
|
|
|
815
868
|
What goes into a carry space, what a carrier checks and the host's HTTP API
|
|
816
869
|
are protocol ([spec 06 §4](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)). The reference node's side:
|
|
817
870
|
|
|
818
|
-
**Carriers.** `node.carriers.add({ did, name })` (needs the account key)
|
|
819
|
-
the carry space,
|
|
820
|
-
`Carrier`),
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
a space the account uses. A node that starts, or hears the registry change,
|
|
871
|
+
**Carriers.** `node.carriers.add({ did, name })` (needs the account key)
|
|
872
|
+
derives the carry space, writes the `sys.carrier` record (name trimmed to 80,
|
|
873
|
+
default `Carrier`), fills the carry space, and returns `{ space, invite }` for
|
|
874
|
+
the carrier to join with; for a carrier it already has, by `did`, it returns
|
|
875
|
+
that one's. Carry spaces are never kept in the node's own list: each is
|
|
876
|
+
derived again from its record. A node that starts, or hears the registry change,
|
|
825
877
|
refills every carrier's carry space in the background: it opens every space
|
|
826
878
|
the account holds, which from a data folder is slow, and signing in doesn't
|
|
827
879
|
wait for it. Adding an automation doesn't either (adding a carrier writes that
|
|
@@ -832,8 +884,8 @@ waits up to `waitMs` for the node to be level with the carrier in the carry
|
|
|
832
884
|
space and then the account registry, and says whether it was: a node about to
|
|
833
885
|
close (the home's window, once it has answered) waits on it, so what it wrote
|
|
834
886
|
for the carrier is not left with nobody (spec 06 §4.3). `node.carriers.remove(carrySpace)`
|
|
835
|
-
writes `carry:closed` and
|
|
836
|
-
open
|
|
887
|
+
writes `carry:closed` and marks the record removed; the node keeps the carry
|
|
888
|
+
space open until it closes, so the carrier hears it.
|
|
837
889
|
|
|
838
890
|
**The account's own automations.** `node.automations` (needs the account
|
|
839
891
|
key) lists, adds, updates (`name`, `paused`) and removes the account's own
|
|
@@ -845,22 +897,22 @@ person to pause or remove ([sign-in](sign-in.md#the-account-homes-side)).
|
|
|
845
897
|
**A carrier's matches.** `CarrierNode` reports a version that wakes one of
|
|
846
898
|
the account's wakes through a `wake` event, with only the wake, the space and
|
|
847
899
|
the record's key, collection and `createdAt`; `wakes()` lists the wakes it
|
|
848
|
-
holds.
|
|
900
|
+
holds. The desktop app shows them as notifications (`apps/desktop/src/bun/notify.ts`); the browser extension shows none yet.
|
|
849
901
|
|
|
850
902
|
**Hosting.** `node.hosting`:
|
|
851
903
|
|
|
852
|
-
| Call | Does
|
|
853
|
-
| -------------------------------------------------------------------------------------- |
|
|
854
|
-
| `use(url)` | Reads the host's description, makes the subscription key and writes the `sys.hosting` record.
|
|
855
|
-
| `list()` | Asks each host for its status and hands over the carry space when paid and not carrying, making the carrier first if needed (named after the host's address). At most once a minute per host; a second look waits for a handover in flight.
|
|
856
|
-
| `pay(url,
|
|
857
|
-
| `
|
|
858
|
-
| `
|
|
859
|
-
| `
|
|
860
|
-
| `
|
|
861
|
-
| `payForSpace(id, url, { amount, method, monthly? })`, `remindForSpace(id, url, email)` | Adds to a space's fund at a host it names (dollars, by `checkout` or `request`, monthly by card), and asks for reminders before it runs out. Anyone in it may. `space(id)` gives each host's `fund` offer, and in its status the `balance`, `daily` spend and `bots`.
|
|
862
|
-
| `startBot(id, url, { name, role? })` | Asks a host the space names to run a bot there ([spec 08 §3](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md)): makes an invite for `role` (by default as `spaces.invite` picks one) and hands it over. The host holds the bot's keys, so an app says so first.
|
|
863
|
-
| `stopForSpace(id, url)` | Stops a space using a host it names: deletes its `std.host` record, removes the host's bots and changes the key (below).
|
|
904
|
+
| Call | Does |
|
|
905
|
+
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
906
|
+
| `use(url)` | Reads the host's description, makes the subscription key and writes the `sys.hosting` record. |
|
|
907
|
+
| `list()` | Asks each host for its status and hands over the carry space when paid and not carrying, making the carrier first if needed (named after the host's address). At most once a minute per host; a second look waits for a handover in flight. |
|
|
908
|
+
| `pay(url, { amount, method, monthly? })` | Adds to the account's balance at the host (dollars, by `checkout` or `request`, monthly by card, as its `HostingView.fund` says): a pay answer, `checkout` (a page to open in a new tab with no opener) or `request` (a payment for a wallet, shown by the app). Call `list()` until the balance moves. |
|
|
909
|
+
| `remind(url, email)` | Asks the host to email a reminder before paid time runs out; it mails a link to confirm first. |
|
|
910
|
+
| `stop(url)` | Sends `DELETE …/carry` (ignoring failure), removes the carrier and deletes the `sys.hosting` record. |
|
|
911
|
+
| `space(id)` | The hosts a space names in `std.host`, each asked how the space's own subscription stands, with how its fund is paid into (below). |
|
|
912
|
+
| `over(id)` | The account's hosts whose last status says the space is over their free line, each `{ url, name, over }` (`over.until`, `over.reasons`), from the receipts in `sys.hosting`: asks no host. An agent may call it for a space it was given. |
|
|
913
|
+
| `payForSpace(id, url, { amount, method, monthly? })`, `remindForSpace(id, url, email)` | Adds to a space's fund at a host it names (dollars, by `checkout` or `request`, monthly by card), and asks for reminders before it runs out. Anyone in it may. `space(id)` gives each host's `fund` offer, and in its status the `balance`, `daily` spend and `bots`. |
|
|
914
|
+
| `startBot(id, url, { name, role? })` | Asks a host the space names to run a bot there ([spec 08 §3](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md)): makes an invite for `role` (by default as `spaces.invite` picks one) and hands it over. The host holds the bot's keys, so an app says so first. |
|
|
915
|
+
| `stopForSpace(id, url)` | Stops a space using a host it names: deletes its `std.host` record, removes the host's bots and changes the key (below). |
|
|
864
916
|
|
|
865
917
|
Every device runs `list()` after each reconciliation ([following the account](#following-the-account)).
|
|
866
918
|
A device reaches a host at the socket its description names (`peer`,
|
|
@@ -882,13 +934,24 @@ The reference host (`minca host`, `packages/cli/src/host.ts`) keeps a lapsed
|
|
|
882
934
|
subscription for `graceDays` (default 30) after `paidUntil`, and drops lapsed
|
|
883
935
|
ones in a sweep every hour (`sweepMs`). It measures each carried space's
|
|
884
936
|
folder at most every ten minutes, and each status gives the sum as `bytes`,
|
|
885
|
-
with `quotaBytes` as `quota` (`MINCA_HOST_QUOTA_GB
|
|
886
|
-
|
|
937
|
+
with `quotaBytes` as `quota` (`MINCA_HOST_QUOTA_GB`, none unless set, at a
|
|
938
|
+
host without limits). At its quota, an account's carry space takes no new space
|
|
887
939
|
(`full`, in `createCarryCore`): what it carries stays and keeps syncing, and a
|
|
888
940
|
space that waited is taken once a later measure finds room. All of this is the
|
|
889
941
|
host's own policy.
|
|
890
942
|
|
|
891
|
-
|
|
943
|
+
With `limits` ([spec 08 §1.1](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md),
|
|
944
|
+
`MINCA_HOST_FREE_GB`), an account's subscription is active with nothing paid,
|
|
945
|
+
its `plan` `free` until it pays, and its quota by plan; a device hands such a
|
|
946
|
+
host its carry space as it would a free one. A space its own fund pays for
|
|
947
|
+
takes none of its members' room. The host counts each carried space's writers
|
|
948
|
+
as versions arrive (`onArrived`, in `createCarryCore`) and its readers as
|
|
949
|
+
sockets prove themselves (`onPeer`, `packages/cli/src/serve.ts`), and once an
|
|
950
|
+
hour (`evaluate`) holds each to the free line. Past a space's `until`, every
|
|
951
|
+
account's carry space stops carrying it (`skip`, in `createCarryCore`), while
|
|
952
|
+
its own subscription still may. Each change is a line in the host's log.
|
|
953
|
+
|
|
954
|
+
_Source: `packages/core/src/node/node.ts` (`carriers`, `notifications`, `hosting`), `packages/core/src/node/carrier.ts` (`arrived`, `skip`, `onArrived`), `packages/core/src/node/host.ts` (`evaluate`), `packages/core/src/session/hosting.ts`, `packages/cli/src/host.ts`. Tests: `packages/core/tests/carrier.test.ts`, `packages/core/tests/host-limits.test.ts`, `packages/cli/tests/host.test.ts`._
|
|
892
955
|
|
|
893
956
|
### A space paying for itself
|
|
894
957
|
|
package/docs/sign-in.md
CHANGED
|
@@ -386,22 +386,27 @@ lifetime, clamped to [1/24, 365].
|
|
|
386
386
|
**Connections.** The home remembers each connection per account in
|
|
387
387
|
`localStorage` under `<prefix>.connections:<accountId>` (`Connection`:
|
|
388
388
|
`origin`, `name`, `audience`, `access`, `scope`, `carrySpace?`, `spaces`,
|
|
389
|
-
`grantedAt`, `expiresAt`, `via?`, `recordsOnly?`). It keeps no note:
|
|
389
|
+
`grantedAt`, `expiresAt`, `via?`, `recordsOnly?`, `retired?`). It keeps no note:
|
|
390
390
|
disconnecting revokes the `audience` key, which is all a revoke names. A kept
|
|
391
391
|
connection with any other field (a `token` from before notes were
|
|
392
392
|
delegations in the UCAN 1.0 profile, say), or one of these in another
|
|
393
393
|
shape, is dropped when read, not read in part: its app or program connects
|
|
394
394
|
again.
|
|
395
|
-
Connecting the same origin again replaces its connection
|
|
395
|
+
Connecting the same origin again replaces its connection, revoking nothing:
|
|
396
|
+
the keys it replaced go in `retired`, for disconnecting to revoke. Nothing
|
|
397
|
+
revokes an app on its own, not even once its time has passed: a revoke keeps
|
|
398
|
+
only what this home has seen of the key, and a home that is seldom open has
|
|
399
|
+
seen little ([spec 06 §2.9](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)). A connection with `via: 'code'` (a
|
|
396
400
|
program connected by code through the app) is keyed by its audience instead,
|
|
397
|
-
so each such program is its own. A carrier is kept apart from the app at its
|
|
401
|
+
so each such program is its own (`connectionKey`). A carrier is kept apart from the app at its
|
|
398
402
|
origin: connecting either replaces only its own kind, and one key is never
|
|
399
403
|
both. `auth.connections()` lists them.
|
|
400
404
|
|
|
401
405
|
**Disconnecting.** `auth.disconnect(origin, { byCode?, audience? })` removes
|
|
402
406
|
the app's connections (by default the app and every program connected through
|
|
403
407
|
it by code; `byCode: true` only those programs; `audience` only that key),
|
|
404
|
-
revokes the keys of those with `access: write
|
|
408
|
+
revokes the keys of those with `access: write` and every key in their
|
|
409
|
+
`retired`, and, unless only programs
|
|
405
410
|
connected by code go, removes the automations the app proposed. A carrier at
|
|
406
411
|
that origin stays: it goes by its key alone (`audience`), and takes nothing of
|
|
407
412
|
the app's with it. The app hears of it when the revokes reach it,
|
|
@@ -413,10 +418,12 @@ they are still only here, and the app keeps working until this home is next
|
|
|
413
418
|
online with another of the account's devices or apps. The account home waits
|
|
414
419
|
5 s, and says so when nobody took them in.
|
|
415
420
|
|
|
416
|
-
**Signing out.** `auth.signOut()` forgets the unlocked account on this device
|
|
417
|
-
|
|
421
|
+
**Signing out.** `auth.signOut()` forgets the unlocked account on this device
|
|
422
|
+
and revokes the home's own session key, with a cutoff at what it wrote, so
|
|
423
|
+
nothing it wrote is lost. An
|
|
418
424
|
app's note doesn't need the home signed in, so the apps connected from here
|
|
419
|
-
keep working
|
|
425
|
+
keep working; a note running out stops only their live use, and what they
|
|
426
|
+
write counts until they are disconnected. `auth.signOut({ disconnect: true })`
|
|
420
427
|
disconnects them first, and the programs connected through them, with the
|
|
421
428
|
automations they proposed; carriers stay. The node sends nothing once it has
|
|
422
429
|
stopped, so it waits, up to 5 s for them all (`signOutGraceMs` in
|
|
@@ -426,7 +433,7 @@ open space as signing out starts, so signing out with nobody else online is
|
|
|
426
433
|
quick; `state.signingOut` is true meanwhile. A node with no network
|
|
427
434
|
configured doesn't wait. With nobody reachable, they leave the next time the account signs in here. A read-only app has no key to revoke: it loses
|
|
428
435
|
access when its time runs out. The account home asks each time, with
|
|
429
|
-
disconnecting
|
|
436
|
+
disconnecting unticked, since revoking is for when something is wrong, and is not ready to grant anything from the moment
|
|
430
437
|
signing out starts. Choosing another account on the connect page signs out
|
|
431
438
|
without disconnecting: switching accounts disconnects nothing.
|
|
432
439
|
|
|
@@ -441,4 +448,4 @@ carrier from the same origin (never an app there), adds the carrier with `node.c
|
|
|
441
448
|
returns the `CarryGrant`. Its connection is kept with `expiresAt: 0`, since a
|
|
442
449
|
carry connection never expires.
|
|
443
450
|
|
|
444
|
-
_Source: `packages/core/src/session/auth.ts` (`grant`, `grantCarry`, `propose`, `connections`, `disconnect`, `signOut`, `isConnection`), `packages/core/src/session/connect.ts` (`receiveConnectRequest`). Tests: `packages/core/tests/connect.test.ts` ("the home receiving a request", "connecting an app to an account home", "disconnecting …", "connecting a carrier to an account home", "signing out and disconnecting…", "signing out alone…"), `packages/core/tests/records-only.test.ts` ("a connection kept in an older shape is dropped, not read as the app’s own")._
|
|
451
|
+
_Source: `packages/core/src/session/auth.ts` (`grant`, `grantCarry`, `propose`, `connections`, `disconnect`, `signOut`, `isConnection`, `connectionKey`), `apps/home/src/components/Settings.tsx`, `packages/core/src/session/connect.ts` (`receiveConnectRequest`). Tests: `packages/core/tests/connect.test.ts` ("the home receiving a request", "connecting an app to an account home", "disconnecting …", "connecting a carrier to an account home", "signing out and disconnecting…", "signing out alone…"), `packages/core/tests/records-only.test.ts` ("a connection kept in an older shape is dropped, not read as the app’s own")._
|
package/docs/spaces.md
CHANGED
|
@@ -196,17 +196,29 @@ whose root's `hex40` is not the record key:
|
|
|
196
196
|
empty means no profile), `did` (its root) and `updatedAt` (its `createdAt`);
|
|
197
197
|
- `contactKey` comes from the newest remaining version that carries a valid
|
|
198
198
|
P-256 point, so a newer version written without one does not hide it.
|
|
199
|
+
- `avatar` comes from the newest version only (one without it has taken it
|
|
200
|
+
away): a file reference (`records.addFile`) whose `mime` is an image.
|
|
199
201
|
|
|
200
202
|
**Writing.** Profiles are written with `retain`, so older versions stay. A
|
|
201
203
|
writer that does not hold the contact key must carry forward the
|
|
202
204
|
`contactKey` of its current profile.
|
|
203
205
|
|
|
204
|
-
**The account's name.** The account keeps its name in the
|
|
205
|
-
as `sys.profile` at key `profile` with body
|
|
206
|
-
wins. `node.account.setName` writes
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
206
|
+
**The account's name and picture.** The account keeps its name in the
|
|
207
|
+
account registry, as `sys.profile` at key `profile` with body
|
|
208
|
+
`{ name, avatar? }`; the newest version wins. `node.account.setName` writes
|
|
209
|
+
the name, `setAvatar({ bytes, mime })` the picture (a file in the registry;
|
|
210
|
+
the app resizes it first), and `picture()` reads it back. The node publishes
|
|
211
|
+
both into every space it opens, and again on a change. A space's members
|
|
212
|
+
can't read the registry, so the picture is copied into each space once, as a
|
|
213
|
+
file of that space, and its reference names the registry file it copies
|
|
214
|
+
(`source`), so opening the space again makes no second copy. A picture that
|
|
215
|
+
can't be copied now (its bytes on a device that is away) leaves the space's
|
|
216
|
+
copy as it was, and never holds back the name. Profiles are retained, so a
|
|
217
|
+
picture once shared stays with the members who hold it: taking it away
|
|
218
|
+
shows none from then on, and withdraws nothing. It publishes
|
|
219
|
+
in every space but the registry and the contacts space, and not at all from
|
|
220
|
+
a node whose note lacks `/account/write` (an agent's); a non-member
|
|
221
|
+
publishes nothing
|
|
210
222
|
([spec 06 §1.3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
211
223
|
|
|
212
224
|
> **Planned:** profiles, round two.
|
|
@@ -215,10 +227,6 @@ non-member publishes nothing
|
|
|
215
227
|
> per space; what is missing is a way to say the name was chosen for this
|
|
216
228
|
> space, so publishing the account name on the next rename does not
|
|
217
229
|
> overwrite it.
|
|
218
|
-
> - **An avatar**, as a reference to an image on the profile. Depends on a
|
|
219
|
-
> way for a record to carry a file, which is not specified yet (the blob
|
|
220
|
-
> stores of [spec 05](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md) hold mirrors, not files records
|
|
221
|
-
> point to).
|
|
222
230
|
> - **Private nicknames for others**: a name you give someone, seen only by
|
|
223
231
|
> you. It belongs in the account's own spaces, not in the shared one;
|
|
224
232
|
> `std.contact`'s `name` already does this for contacts.
|
package/docs/standard-library.md
CHANGED
|
@@ -57,23 +57,24 @@ _Source: `packages/core/src/schemas/blueprints.ts` (`standardCollections`), `pac
|
|
|
57
57
|
out in each definition, built by the library's `fragments` so they are
|
|
58
58
|
identical everywhere:
|
|
59
59
|
|
|
60
|
-
| Fragment | Shape
|
|
61
|
-
| ---------- |
|
|
62
|
-
| `when` | string 10–64: RFC 3339 date-time (`2026-03-01T18:30:00+01:00`), or `YYYY-MM-DD` for a whole day
|
|
63
|
-
| `day` | string of 10: `YYYY-MM-DD`
|
|
64
|
-
| `timeZone` | string 1–64: an IANA zone, `Europe/Oslo`
|
|
65
|
-
| DID | string 1–256: an account DID (built by `person`)
|
|
66
|
-
| `money` | `{ amount, currency }`, both required: `amount` a decimal string 1–32 (`"12.50"`), never a number; `currency` ISO 4217, 3 characters
|
|
67
|
-
| `address` | `{ street, locality, region, postcode, country }`, each optional; `country` ISO 3166-1 alpha-2
|
|
68
|
-
| `place` | `{ name, address, lat, lon, cells }` (built by `placeRef`), each optional; `lat` −90–90, `lon` −180–180, WGS 84; `cells` string 1–12[] (≤ 8), the geohash cells of `lat` and `lon` (see Places and areas)
|
|
69
|
-
| `blob` | `{ hash, size, mime, name? }`: `
|
|
70
|
-
| `image` | `{ blob, alt? }`: `alt` ≤ 2000, what it shows
|
|
71
|
-
| `position` | string 1–200 that sorts where a record goes (Positions, below)
|
|
60
|
+
| Fragment | Shape |
|
|
61
|
+
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
62
|
+
| `when` | string 10–64: RFC 3339 date-time (`2026-03-01T18:30:00+01:00`), or `YYYY-MM-DD` for a whole day |
|
|
63
|
+
| `day` | string of 10: `YYYY-MM-DD` |
|
|
64
|
+
| `timeZone` | string 1–64: an IANA zone, `Europe/Oslo` |
|
|
65
|
+
| DID | string 1–256: an account DID (built by `person`) |
|
|
66
|
+
| `money` | `{ amount, currency }`, both required: `amount` a decimal string 1–32 (`"12.50"`), never a number; `currency` ISO 4217, 3 characters |
|
|
67
|
+
| `address` | `{ street, locality, region, postcode, country }`, each optional; `country` ISO 3166-1 alpha-2 |
|
|
68
|
+
| `place` | `{ name, address, lat, lon, cells }` (built by `placeRef`), each optional; `lat` −90–90, `lon` −180–180, WGS 84; `cells` string 1–12[] (≤ 8), the geohash cells of `lat` and `lon` (see Places and areas) |
|
|
69
|
+
| `blob` | `{ hash, size, mime, name?, key?, salt? }`: what `records.addFile` gives: `hash` the file's id (64 hex characters), `size` bytes as stored, `mime` required; `key` and `salt` open it (22 base64url characters each) |
|
|
70
|
+
| `image` | `{ blob, alt? }`: `alt` ≤ 2000, what it shows |
|
|
71
|
+
| `position` | string 1–200 that sorts where a record goes (Positions, below) |
|
|
72
72
|
|
|
73
73
|
Until the dialect has `format` ([spec 02 §6.2](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)), `when` and `day` are checked only for
|
|
74
|
-
length.
|
|
75
|
-
([
|
|
76
|
-
the
|
|
74
|
+
length. A `blob` is what `records.addFile` gives
|
|
75
|
+
([storage](storage.md#files)): its `hash` is the file's id, and it carries
|
|
76
|
+
the `key` and `salt` that open it
|
|
77
|
+
([spec 05 §16.6](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md)).
|
|
77
78
|
|
|
78
79
|
## The definitions
|
|
79
80
|
|
|
@@ -485,11 +486,6 @@ _Source: `packages/core/src/schemas/geo.ts` (`geohash`, `cellsOf`, `cellsAround`
|
|
|
485
486
|
|
|
486
487
|
> **Planned.** Not normative. Each item names its own issue.
|
|
487
488
|
>
|
|
488
|
-
> - **File bytes** ([spec 05 §16.6](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md),
|
|
489
|
-
> [#37](https://github.com/leifriksheim/minca/issues/37)). The `blob`
|
|
490
|
-
> fragment names bytes by hash, but a space cannot yet store or send them,
|
|
491
|
-
> so `std.file`, `std.photo`, `std.video` and the images elsewhere point at
|
|
492
|
-
> bytes a reader may not be able to fetch.
|
|
493
489
|
> - **References to other spaces** ([spec 02 §5.3](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md),
|
|
494
490
|
> [#38](https://github.com/leifriksheim/minca/issues/38)). `std.follow`'s
|
|
495
491
|
> `space` is a plain space id, and a repost or a list item can point only
|