@minca/core 0.1.2 → 0.1.4

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 (66) hide show
  1. package/README.md +17 -5
  2. package/dist/elements/minca-auth.d.ts.map +1 -1
  3. package/dist/elements/minca-auth.js +12 -4
  4. package/dist/elements/minca-auth.js.map +1 -1
  5. package/dist/index.d.ts +1 -1
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js.map +1 -1
  8. package/dist/network/signaling.d.ts +1 -1
  9. package/dist/network/signaling.d.ts.map +1 -1
  10. package/dist/network/signaling.js +73 -3
  11. package/dist/network/signaling.js.map +1 -1
  12. package/dist/node/api.d.ts +1 -0
  13. package/dist/node/api.d.ts.map +1 -1
  14. package/dist/node/api.js +1 -1
  15. package/dist/node/api.js.map +1 -1
  16. package/dist/node/node.d.ts.map +1 -1
  17. package/dist/node/node.js +19 -1
  18. package/dist/node/node.js.map +1 -1
  19. package/dist/node/space-runtime.d.ts +6 -0
  20. package/dist/node/space-runtime.d.ts.map +1 -1
  21. package/dist/node/space-runtime.js +24 -0
  22. package/dist/node/space-runtime.js.map +1 -1
  23. package/dist/node/types.d.ts +14 -1
  24. package/dist/node/types.d.ts.map +1 -1
  25. package/dist/schemas/connectors.d.ts +189 -0
  26. package/dist/schemas/connectors.d.ts.map +1 -0
  27. package/dist/schemas/connectors.js +134 -0
  28. package/dist/schemas/connectors.js.map +1 -0
  29. package/dist/schemas/index.d.ts +2 -0
  30. package/dist/schemas/index.d.ts.map +1 -1
  31. package/dist/schemas/index.js +1 -0
  32. package/dist/schemas/index.js.map +1 -1
  33. package/dist/schemas/standard.d.ts.map +1 -1
  34. package/dist/schemas/standard.js +2 -0
  35. package/dist/schemas/standard.js.map +1 -1
  36. package/dist/session/auth.d.ts.map +1 -1
  37. package/dist/session/auth.js +89 -5
  38. package/dist/session/auth.js.map +1 -1
  39. package/dist/session/connect.d.ts +6 -2
  40. package/dist/session/connect.d.ts.map +1 -1
  41. package/dist/session/connect.js +4 -3
  42. package/dist/session/connect.js.map +1 -1
  43. package/dist/session/hosting.d.ts +9 -0
  44. package/dist/session/hosting.d.ts.map +1 -1
  45. package/dist/session/hosting.js +16 -0
  46. package/dist/session/hosting.js.map +1 -1
  47. package/dist/session/pairing.d.ts +9 -1
  48. package/dist/session/pairing.d.ts.map +1 -1
  49. package/dist/session/pairing.js.map +1 -1
  50. package/dist/session/stay-signed-in.d.ts +2 -0
  51. package/dist/session/stay-signed-in.d.ts.map +1 -1
  52. package/dist/session/stay-signed-in.js +3 -1
  53. package/dist/session/stay-signed-in.js.map +1 -1
  54. package/dist/sync/sync-engine.d.ts +2 -0
  55. package/dist/sync/sync-engine.d.ts.map +1 -1
  56. package/dist/sync/sync-engine.js +15 -3
  57. package/dist/sync/sync-engine.js.map +1 -1
  58. package/docs/README.md +1 -0
  59. package/docs/actions.md +18 -10
  60. package/docs/agents.md +6 -1
  61. package/docs/bots.md +210 -0
  62. package/docs/node.md +14 -4
  63. package/docs/sign-in.md +16 -2
  64. package/docs/standard-library.md +7 -0
  65. package/docs/storage.md +4 -3
  66. package/package.json +1 -1
package/docs/bots.md ADDED
@@ -0,0 +1,210 @@
1
+ # Bots and their connectors
2
+
3
+ A bot is an account of its own in a space: one a host runs
4
+ ([spec 08](../../../spec/08-hosting.md) §3), or one a member runs with
5
+ `minca agent --bot`. What it does is the space's automations naming it
6
+ ([automations.md](automations.md)). This page covers who may configure a bot,
7
+ the instructions it follows, and how one is connected to a service outside
8
+ the space, GitHub first.
9
+
10
+ ## Who may configure a bot
11
+
12
+ Someone who holds `/std.automation/instruct` in the space and every role the
13
+ bot holds there: `mayConfigure(node, space, bot, who)`. The second half means
14
+ nobody reaches past their own grants through the bot. In the community
15
+ preset, founders, admins and moderators hold the grant.
16
+
17
+ A bot never passes for itself: steered once, it could otherwise leave
18
+ itself instructions that count. Nor does another bot, as no chat app lets
19
+ one integration reprogram the next: a host never counts a bot it runs
20
+ (`isBot` in `runAutomations`), and the add-bot dialog offers a bot no role
21
+ that grants `/std.automation/instruct`. The bot, its host and the app all ask this
22
+ one function, of whoever wrote the version in question (`root`):
23
+
24
+ - a bot follows what a record asks only when its writer passes;
25
+ - a bot follows instructions (`std.bot`) only from someone who passes;
26
+ - a bot acts on GitHub only for an automation whose current words were
27
+ written by someone who passes, whoever sets it off;
28
+ - a host connects or disconnects a bot only for someone who passes.
29
+
30
+ ## Instructions
31
+
32
+ `std.bot` is how a community wants its bot to be: a name to go by, a tone,
33
+ what to know. Each person keeps their own (`onePer: [@author, bot]`), so
34
+ nobody's words overwrite another's. The bot reads the newest whose current
35
+ version was written by someone who may configure it, as a person and not an
36
+ agent, and adds it to its system prompt after its own rules, saying whose
37
+ words they are. They can't undo those rules: what set an automation off is
38
+ still data, and deleting is still refused. Everyone in the space can read
39
+ them. An app showing a bot's instructions must pick them the same way
40
+ (`personaIn` in `packages/cli/src/bot-runner.ts`).
41
+
42
+ | Collection | Body | Rules |
43
+ | ---------- | ----------------------------------------------- | ------------------------ |
44
+ | `std.bot` | **`bot`** DID; **`instructions`** string ≤ 2000 | `onePer: [@author, bot]` |
45
+
46
+ ```json
47
+ {
48
+ "bot": "did:key:zDnaeYffVz7N…",
49
+ "instructions": "You are Ferris, the team's helper. Answer briefly, and link issues as #N."
50
+ }
51
+ ```
52
+
53
+ ## Connecting a bot
54
+
55
+ A host whose description names `connectors` can connect its bots to those
56
+ services: whichever it offers, GitHub, a calendar, a drive. The person never
57
+ handles a key: they go through the service's own consent screen, and the host
58
+ keeps what reaches the service. An app needs to know nothing about a service
59
+ but its id and name.
60
+
61
+ 1. The app reads what the host offers from its view of the space
62
+ (`node.hosting.space(space)`, each view's `connectors`: `{ id, name }`).
63
+ 2. It calls `askToConnect(node, space, bot, id)`: that makes a random 32-byte
64
+ secret, keeps it, and writes a `std.connect` naming the bot, the service
65
+ and the secret's hash, valid for nine minutes.
66
+ 3. It opens `connectPage(hostUrl, ask)` in a window of its own, opened in the
67
+ click so the browser doesn't block it. The host checks the request through
68
+ the bot (spec 08 §3.1) and sends the window to the service.
69
+ 4. When the service sends it back, the bot writes its own `std.connector`
70
+ saying what it is connected to, and the window tells the app (a
71
+ `postMessage` of `{ minca: 'connected' }`) and closes.
72
+
73
+ Disconnecting is `askToConnect(node, space, bot, id, { disconnect: true })`,
74
+ then `askToDisconnect(hostUrl, ask)`: the host checks it the same way,
75
+ forgets the connection, and the bot deletes its `std.connector`.
76
+
77
+ An app must show a `std.connector` only when its writer is the bot it names,
78
+ and must define the collections before it writes a request.
79
+
80
+ | Collection | Body | Rules |
81
+ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
82
+ | `std.connect` | **`bot`** DID; **`kind`** the service's id, string 1–40; `verifier` base64url(SHA-256(secret)), 43–64 chars; **`expires`** date-time; `disconnect` boolean | |
83
+ | `std.connector` | **`bot`** DID; **`kind`** string 1–40; **`account`** string ≤ 100, whose account at the service; `reaches` strings ≤ 200, what it reaches, ≤ 100; **`by`** DID; **`since`** date-time | `onePer: [@author, kind]` |
84
+
85
+ Example request, for the secret `AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA` (43 `A`s):
86
+
87
+ ```json
88
+ {
89
+ "bot": "did:key:zDnaeYffVz7N…",
90
+ "kind": "github",
91
+ "verifier": "DwBzhbb51LfusnSGBa_hqYSgo7-j8BTQnip4TOnlzRo",
92
+ "expires": "2026-10-15T12:09:00Z"
93
+ }
94
+ ```
95
+
96
+ ## Writing a connector
97
+
98
+ Each host decides which services it connects its bots to. In the reference
99
+ host a service is one module implementing `HostConnector`
100
+ (`packages/cli/src/connectors/connector.ts`), passed to `startHost` as
101
+ `connectors`:
102
+
103
+ - `id` and `name`: what the host's description names.
104
+ - `consentUrl(state, callback)`: where the browser goes to consent. It must
105
+ come back to `callback`, `<host>/host/connect/<id>/callback`, with `state`.
106
+ - `complete(query, callback)`: the browser back, with the callback's query.
107
+ It answers what was connected (`account`, `reaches`, and `data` the host
108
+ keeps and never shows, such as a refresh token), or why not. The host has
109
+ already checked the state, the browser and the request; the connector checks
110
+ what only the service can say, such as whether this person may give that
111
+ account to a bot.
112
+ - `tools(connection, { mayWrite, budget })`: what the bot may do on a
113
+ connection. Tools that write must refuse without `mayWrite`, and each call
114
+ to the service takes one from `budget`. What the service returns is someone
115
+ else's words: mark it as data, as the GitHub tools do.
116
+ - Set the host's public address (`MINCA_HOST_URL`) when a connector sends a
117
+ `redirect_uri`: otherwise `callback` is worked out from each request.
118
+ - `hook(body, headers)`, optional: calls from the service itself, at
119
+ `<host>/host/connect/<id>/hook`. It answers `unsigned` for a call that isn't
120
+ the service's, or which connections are gone (`forget`), or what they now
121
+ reach at most (`reaches`): the host only narrows what a connection reaches,
122
+ since one account at a service may serve several communities.
123
+
124
+ Whatever the connector, the reference host stops acting through a
125
+ connection, and forgets it, once the bot holds no role in the space or
126
+ whoever made it may no longer configure the bot; it only ever narrows what a
127
+ connection reaches; and it refuses two connectors with one id.
128
+
129
+ A Google Calendar connector, say, would send the browser to Google's consent
130
+ screen, exchange the code for tokens in `complete`, keep the refresh token in
131
+ `data`, and offer `calendar_events` and, with `mayWrite`, `calendar_add`.
132
+
133
+ ## GitHub, in the reference host
134
+
135
+ The reference host's GitHub connector
136
+ (`packages/cli/src/connectors/github-connector.ts`) is a GitHub App. Its
137
+ operator registers it once, with:
138
+
139
+ - Callback URL `<host>/host/connect/github/callback`, and "Request user
140
+ authorization (OAuth) during installation" ticked.
141
+ - Webhook URL `<host>/host/connect/github/hook`, with a secret, subscribed to
142
+ installation events.
143
+ - Permissions: Issues and Pull requests read and write; Contents and Metadata
144
+ read.
145
+ - `MINCA_GITHUB_APP_ID`, `MINCA_GITHUB_APP_SLUG`, `MINCA_GITHUB_CLIENT_ID`,
146
+ `MINCA_GITHUB_CLIENT_SECRET`, `MINCA_GITHUB_PRIVATE_KEY` (the PEM, or a
147
+ path to it) and `MINCA_GITHUB_WEBHOOK_SECRET` in the host's environment,
148
+ with `MINCA_HOST_BOTS=1`. Without the webhook secret the host takes no
149
+ webhook calls, and learns of an uninstall only when a call fails.
150
+
151
+ The person picks the organisation and its repositories on GitHub's install
152
+ screen. GitHub doesn't vouch for the installation id it sends back, and lists
153
+ an installation to anyone with access to one of its repositories, so the
154
+ connector exchanges GitHub's code for the user's own token and keeps the
155
+ installation only if it is on that user's account, or an organisation they
156
+ are an active admin of. The bot then acts on GitHub as the App,
157
+ `<slug>[bot]`, with tokens that last an hour, on those repositories only.
158
+ When the App is uninstalled or suspended, the host forgets every connection
159
+ through it. One installation may serve several communities of the same
160
+ account, so a connection keeps the repositories it was made with: when GitHub
161
+ says they changed, the host only narrows them, and each bot says so in its
162
+ `std.connector`. Reaching a repository added later means connecting again.
163
+ Repositories are kept by name: one renamed away, and another made under its
164
+ old name in an installation for all repositories, is reached in its place.
165
+ The App stays installed on GitHub after a disconnect, where whoever installed
166
+ it can remove it.
167
+
168
+ ### The bot's tools
169
+
170
+ A bot connected in a space has these there, beside its node actions:
171
+
172
+ | Tool | Does |
173
+ | ---------------- | -------------------------------------------------------------------------------- |
174
+ | `github_search` | Issues and pull requests in its repositories, in GitHub's search syntax |
175
+ | `github_get` | One issue or pull request: text, labels, latest comments, a pull request's files |
176
+ | `github_file` | A file at a branch, tag or commit |
177
+ | `github_comment` | Comments on an issue or pull request |
178
+ | `github_issue` | Opens an issue |
179
+
180
+ - Every call names a repository the installation reaches, checked in code;
181
+ a search is scoped to them.
182
+ - It works like a chat app a workspace installs. The two that write run for
183
+ an automation someone who may configure the bot made, whoever sets it off;
184
+ what sets it off reaches the model as data, and can still steer it. An
185
+ automation whose current words are by someone who may not instruct the bot
186
+ isn't run at all.
187
+ - The three that read run for anyone whose record sets an automation off. A
188
+ member can ask the bot what is in the connected repositories, private ones
189
+ included, so connect only what everyone in the space may read.
190
+ - A search shows only results in the connection's repositories, checked by
191
+ each result's own repository, whatever the query says; an issue moved out
192
+ of them isn't read at its old address.
193
+ - Repositories are kept by name. A run keeps the tools it started with until
194
+ it ends, a disconnect or uninstall notwithstanding.
195
+ - Of several people's instructions, the bot takes the one written last as
196
+ its writer's clock says; whoever may configure the bot is trusted with
197
+ that, as with editing a bot's settings in any chat app.
198
+ - The model never sees a token: each call adds one.
199
+ - What GitHub returns was written by people, possibly outside the space, and
200
+ reaches the model marked as data.
201
+ - 200 calls a bot a day, across its connectors, so a loop can't use up a
202
+ service's limits.
203
+
204
+ _Source: `packages/core/src/schemas/connectors.ts` (`connect`, `connector`, `botSettings`, `mayConfigure`, `askToConnect`, `connectPage`, `askToDisconnect`), `packages/core/src/session/hosting.ts` (`connectorOffers`), `packages/cli/src/host-connect.ts` (`createBotConnect`), `packages/cli/src/connectors/connector.ts` (`HostConnector`), `packages/cli/src/connectors/github-connector.ts` (`githubConnector`), `packages/cli/src/connectors/github.ts` (`createGitHubApp`), `packages/cli/src/connectors/github-tools.ts` (`githubTools`), `packages/cli/src/bot-runner.ts` (`runAutomations`, `personaIn`), `packages/cli/src/host-setup.ts` (`githubFromEnv`), `apps/shared/src/BotConnectors.tsx`. Tests: `packages/cli/tests/host.test.ts` ("connecting a bot to GitHub"), `packages/cli/tests/host-connect.test.ts` ("a host’s own connectors"), `packages/cli/tests/github.test.ts`, `packages/cli/tests/agent-automations.test.ts` ("a bot’s connectors", "a bot’s instructions", "takes instructions only from someone holding every grant of its roles")._
205
+
206
+ ## Planned
207
+
208
+ - GitHub events as records ("PR #12 opened"), so automations can answer them.
209
+ - Connectors for a bot a member runs, which has no public address for a
210
+ service to send people back to.
package/docs/node.md CHANGED
@@ -608,9 +608,14 @@ meet this one.
608
608
  then 30 s between attempts, each ±25% so peers that dropped together do not
609
609
  return together, and never stops until `disconnect`. After a `4009` it emits
610
610
  `refused` and waits 10 s, doubling with each refusal in a row up to 60 s. It
611
- tries at once when the browser reports `online` or the page becomes visible
612
- again, since both follow a network change or a sleep, and when asked
613
- (`reconnect`). A successful open resets the count. Each relay's state
611
+ tries at once when the page becomes visible again, and when asked
612
+ (`reconnect`). A successful open resets the count. A socket can die without
613
+ closing, and after a sleep it has: so the client looks at the clock every
614
+ 5 s, and a look more than 30 s after the last means the device slept; it
615
+ then lets go of its socket and dials again at once, as it does when the
616
+ browser reports `online`. An open socket that has heard nothing for 30 s
617
+ also sends `ping`; once its relay has answered one, two going unanswered end
618
+ the socket ("The relay stopped answering.") and it redials. Each relay's state
614
619
  (`connecting`, `open`, `waiting` with the time of the next attempt and why the
615
620
  last one failed, `stopped`) is readable as `RelayStatus`, and through a node
616
621
  as `network.status()`.
@@ -799,7 +804,12 @@ are protocol ([spec 06 §4](https://github.com/leifriksheim/minca/blob/main/spec
799
804
  **Carriers.** `node.carriers.add({ did, name })` (needs the account key) makes
800
805
  the carry space, named `Carried by <name>` (name trimmed to 80, default
801
806
  `Carrier`), writes the `sys.carrier` record, fills the carry space, and returns
802
- `{ space, invite }` for the carrier to join with. `node.carriers.remove(carrySpace)`
807
+ `{ space, invite }` for the carrier to join with; for a carrier it already
808
+ has, by `did`, it returns that one's. `node.carriers.reached(carrySpace, waitMs)`
809
+ waits up to `waitMs` for the node to be level with the carrier in the carry
810
+ space and then the account registry, and says whether it was: a node about to
811
+ close (the home's window, once it has answered) waits on it, so what it wrote
812
+ for the carrier is not left with nobody (spec 06 §4.3). `node.carriers.remove(carrySpace)`
803
813
  writes `carry:closed` and deletes the record; the node keeps the carry space
804
814
  open for 30 days after, so a carrier that is offline still hears it.
805
815
 
package/docs/sign-in.md CHANGED
@@ -249,13 +249,27 @@ options.
249
249
  On the phone, the `pair` stage waits for a tap, then meets the computer
250
250
  (`receiveFromDesktop`) and shows the same code (`pairingStage` is `{ kind:
251
251
  'confirm', code }`). Only when the person confirms on the computer does the
252
- seed arrive; the phone then signs in with it and joins each space, ending on
252
+ seed arrive; the phone then signs in with it (`sending`), joins each space in
253
+ turn (`{ kind: 'joining', joined, total }`, before each one), and ends on
253
254
  `received`. It waits 60 seconds for the computer to answer, and 10 minutes for
254
255
  the person to confirm. Where accounts are already kept here, `<minca-auth>`
255
256
  warns before going on: a link someone else sent would put the phone in their
256
257
  account.
257
258
 
258
- _Source: `packages/core/src/session/pairing.ts` (`offerToPhone`, `receiveFromDesktop`), `packages/core/src/session/auth.ts` (`offerToPhone`, `acceptPairing`), `packages/core/src/elements/minca-auth.ts`. Tests: `packages/core/tests/pairing.test.ts`._
259
+ The camera opens the link in a new tab, so an app that sent the person to
260
+ sign in is still waiting in another. A flow that is signed out picks up a
261
+ sign-in another tab keeps (`storage` events on the remembered session), as a
262
+ refresh would, so that tab is signed in when the person goes back to it.
263
+
264
+ A tab takes one up only once `start()` has finished, and only at `welcome`,
265
+ `existing`, or `signIn` with no account picked or the same one picked: a tab
266
+ where the person chose another account is left alone. It holds `busy`
267
+ meanwhile, so a sign-in by hand waits for it and two nodes never start in one
268
+ tab. It keeps the remembered key as it is, and gives up if the kept sign-in
269
+ changed meanwhile. When the kept sign-in goes, because the person signed out
270
+ in another tab, a tab that took it up signs out too, revoking its own key.
271
+
272
+ _Source: `packages/core/src/session/pairing.ts` (`offerToPhone`, `receiveFromDesktop`), `packages/core/src/session/auth.ts` (`offerToPhone`, `acceptPairing`), `packages/core/src/elements/minca-auth.ts`. Tests: `packages/core/tests/pairing.test.ts`, `packages/core/tests/take-up.test.ts`._
259
273
 
260
274
  ## The account home's side
261
275
 
@@ -266,6 +266,13 @@ to be a certain way, or at set times, and what each automation did. An
266
266
  account keeps automations of its own in its registry too, which notify it. Described in
267
267
  [automations.md](automations.md).
268
268
 
269
+ **Bots**
270
+
271
+ `std.bot`, `std.connect` and `std.connector`: how a community wants its bot
272
+ to be, someone asking a bot's host to connect the bot to a service such as
273
+ GitHub, and the bot saying what it is connected to. Described in
274
+ [bots.md](bots.md).
275
+
269
276
  **Activity.** `std.activity` is someone at work on a record, for apps to show
270
277
  while it lasts: "My bot is working on it…" under a message, a spinner on a
271
278
  task. Anyone may write one, only about their own work, and apps show it as
package/docs/storage.md CHANGED
@@ -54,9 +54,10 @@ a change was landing is not kept.
54
54
  When another writer changed the same store, the node re-reads all of it
55
55
  (`invalidate`). Other tabs of one browser are told through a
56
56
  `BroadcastChannel` named `minca-node:<root DID>:<space id>`. Where a browser
57
- has shared workers, the apps in this repository run one node for all of a
58
- site's tabs in a `SharedWorker`, so those tabs share one store and have
59
- nothing to tell each other; the channel remains for browsers without them,
57
+ has shared workers that work, the apps in this repository run one node for all
58
+ of a site's tabs in a `SharedWorker`, so those tabs share one store and have
59
+ nothing to tell each other; the channel remains for the rest (Chrome on
60
+ Android has none; WebKit drops a message to one that holds a `CryptoKey`),
60
61
  where each tab's node runs in a worker of its own
61
62
  (`packages/core/src/node/worker.ts`). Writers on a shared folder are found by
62
63
  re-reading it ([data folders](#data-folders)).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@minca/core",
3
- "version": "0.1.2",
3
+ "version": "0.1.4",
4
4
  "type": "module",
5
5
  "description": "Self-sovereign P2P protocol for the browser — identity, schemas, storage, networking, and gossip sync",
6
6
  "repository": {