@minca/core 0.1.17 → 0.2.0
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 +2 -1
- package/dist/files/space-files.d.ts +2 -2
- package/dist/files/space-files.d.ts.map +1 -1
- package/dist/files/space-files.js +7 -5
- package/dist/files/space-files.js.map +1 -1
- package/dist/inbox/names.d.ts +1 -1
- package/dist/inbox/names.js +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/node/actions.d.ts +3 -0
- package/dist/node/actions.d.ts.map +1 -1
- package/dist/node/actions.js.map +1 -1
- package/dist/node/api.d.ts +1 -0
- package/dist/node/api.d.ts.map +1 -1
- package/dist/node/api.js +1 -0
- package/dist/node/api.js.map +1 -1
- package/dist/node/carrier.js +1 -1
- package/dist/node/carrier.js.map +1 -1
- package/dist/node/index.d.ts +1 -1
- package/dist/node/index.d.ts.map +1 -1
- package/dist/node/node-contacts.d.ts.map +1 -1
- package/dist/node/node-contacts.js +1 -0
- package/dist/node/node-contacts.js.map +1 -1
- package/dist/node/node-records.d.ts.map +1 -1
- package/dist/node/node-records.js +6 -1
- package/dist/node/node-records.js.map +1 -1
- package/dist/node/node.d.ts.map +1 -1
- package/dist/node/node.js +13 -1
- package/dist/node/node.js.map +1 -1
- package/dist/node/remote.d.ts.map +1 -1
- package/dist/node/remote.js +7 -1
- package/dist/node/remote.js.map +1 -1
- package/dist/node/space-runtime.d.ts +5 -3
- package/dist/node/space-runtime.d.ts.map +1 -1
- package/dist/node/space-runtime.js +3 -1
- package/dist/node/space-runtime.js.map +1 -1
- package/dist/node/types.d.ts +112 -36
- package/dist/node/types.d.ts.map +1 -1
- package/dist/node/watch-notifications.d.ts +6 -0
- package/dist/node/watch-notifications.d.ts.map +1 -1
- package/dist/node/watch-notifications.js +47 -9
- package/dist/node/watch-notifications.js.map +1 -1
- package/dist/query/types.d.ts +1 -0
- package/dist/query/types.d.ts.map +1 -1
- package/dist/query/types.js.map +1 -1
- package/dist/records/contract-builder.d.ts +22 -6
- package/dist/records/contract-builder.d.ts.map +1 -1
- package/dist/records/contract-builder.js.map +1 -1
- package/dist/schemas/automations.d.ts +6 -2
- package/dist/schemas/automations.d.ts.map +1 -1
- package/dist/schemas/automations.js.map +1 -1
- package/dist/schemas/connectors.d.ts +4 -3
- package/dist/schemas/connectors.d.ts.map +1 -1
- package/dist/schemas/connectors.js +4 -3
- package/dist/schemas/connectors.js.map +1 -1
- package/dist/schemas/library/media.js +1 -1
- package/dist/schemas/library/media.js.map +1 -1
- package/dist/session/account-hint.d.ts +2 -2
- package/dist/session/account-hint.d.ts.map +1 -1
- package/dist/session/account-hint.js +3 -3
- package/dist/session/account-hint.js.map +1 -1
- package/dist/session/auth.d.ts +7 -3
- package/dist/session/auth.d.ts.map +1 -1
- package/dist/session/auth.js.map +1 -1
- package/dist/session/connection.d.ts +18 -0
- package/dist/session/connection.d.ts.map +1 -1
- package/dist/session/connection.js +11 -0
- package/dist/session/connection.js.map +1 -1
- package/dist/session/index.d.ts +2 -2
- 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/storage/blob-store.d.ts +3 -0
- package/dist/storage/blob-store.d.ts.map +1 -1
- package/dist/types.d.ts +11 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/docs/README.md +86 -93
- package/docs/actions.md +213 -152
- package/docs/agents.md +198 -167
- package/docs/automations.md +296 -204
- package/docs/blueprints-and-guides.md +405 -311
- package/docs/bots.md +208 -134
- package/docs/building-an-app.md +86 -159
- package/docs/collections.md +248 -328
- package/docs/computed.md +112 -89
- package/docs/contacts.md +151 -112
- package/docs/contracts.md +299 -120
- package/docs/direct-messages.md +80 -65
- package/docs/inbox.md +138 -93
- package/docs/node.md +1081 -996
- package/docs/permissions.md +142 -0
- package/docs/proposing-collections.md +74 -55
- package/docs/query-format.md +150 -126
- package/docs/records-and-queries.md +205 -126
- package/docs/sign-in.md +487 -416
- package/docs/spaces.md +261 -246
- package/docs/standard-library.md +487 -526
- package/docs/storage.md +325 -348
- package/docs/usernames.md +164 -97
- package/docs/warrants.md +100 -67
- package/package.json +1 -6
- package/dist/elements/auth-styles.d.ts +0 -18
- package/dist/elements/auth-styles.d.ts.map +0 -1
- package/dist/elements/auth-styles.js +0 -206
- package/dist/elements/auth-styles.js.map +0 -1
- package/dist/elements/dom.d.ts +0 -29
- package/dist/elements/dom.d.ts.map +0 -1
- package/dist/elements/dom.js +0 -91
- package/dist/elements/dom.js.map +0 -1
- package/dist/elements/index.d.ts +0 -13
- package/dist/elements/index.d.ts.map +0 -1
- package/dist/elements/index.js +0 -11
- package/dist/elements/index.js.map +0 -1
- package/dist/elements/minca-auth.d.ts +0 -55
- package/dist/elements/minca-auth.d.ts.map +0 -1
- package/dist/elements/minca-auth.js +0 -768
- package/dist/elements/minca-auth.js.map +0 -1
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# Permissions
|
|
2
|
+
|
|
3
|
+
Every space decides who may do what in it, and every device enforces it.
|
|
4
|
+
There's no server to ask and no admin panel to trust: a change that breaks
|
|
5
|
+
the space's rules is refused by everyone, wherever it was written.
|
|
6
|
+
|
|
7
|
+
## Roles
|
|
8
|
+
|
|
9
|
+
Who may write lives in the space, not in your code or in a definition. A
|
|
10
|
+
role holds grants, and each grant is a command with a policy over its
|
|
11
|
+
arguments. "Hosts may delete any poll" is:
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
import { RECORD_DELETE } from '@minca/core';
|
|
15
|
+
|
|
16
|
+
await node.spaces.defineRole(space.id, {
|
|
17
|
+
name: 'host',
|
|
18
|
+
title: 'Host',
|
|
19
|
+
grants: [{ cmd: RECORD_DELETE, pol: [['==', '.collection', 'app.poll']] }],
|
|
20
|
+
nests: ['member'], // a host holds what a member holds too
|
|
21
|
+
});
|
|
22
|
+
await node.spaces.assign(space.id, did, 'host');
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
- `/record/write` and `/record/delete` see `collection` and `byCreator`, and
|
|
26
|
+
a write also sees `body`. `byCreator` is whether the writer's account made
|
|
27
|
+
the record's first version, and is true for a new record. So
|
|
28
|
+
`['==', '.byCreator', true]` means "only your own".
|
|
29
|
+
- `/collection/define` adds or changes collections. It also needs a note that
|
|
30
|
+
grants `/collection/define`, and an agent's note doesn't.
|
|
31
|
+
- You can't grant what you don't hold.
|
|
32
|
+
- The space's founders, if it has any, hold every command.
|
|
33
|
+
|
|
34
|
+
To ask before acting, `node.spaces.may(space.id, cmd, args)` says whether
|
|
35
|
+
this account may do something now, and `node.records.can(space, action, target)`
|
|
36
|
+
asks it for a record. Assigning, removing and roles that define roles are
|
|
37
|
+
covered in [spec 03](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
|
|
38
|
+
|
|
39
|
+
## Presets
|
|
40
|
+
|
|
41
|
+
A preset is a starting constitution: who sits at the top, the roles the space
|
|
42
|
+
is founded with and what each may do, and the roles you start with. Spread
|
|
43
|
+
one into `spaces.create`, change it, or write your own. Nothing checks a
|
|
44
|
+
preset's name.
|
|
45
|
+
|
|
46
|
+
| Preset | `top` | Roles |
|
|
47
|
+
| ----------- | ---------- | ------------------------------------------ |
|
|
48
|
+
| `solo` | `founders` | none: the founder alone |
|
|
49
|
+
| `team` | `founders` | editor |
|
|
50
|
+
| `community` | `founders` | admin, moderator, member |
|
|
51
|
+
| `coop` | `none` | steward (yours), member; no founder at all |
|
|
52
|
+
|
|
53
|
+
What each role may do:
|
|
54
|
+
|
|
55
|
+
| Role | Grants |
|
|
56
|
+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
57
|
+
| `team` editor | `/record`, `/collection/define`, `/role/assign` with `.role == "editor"` |
|
|
58
|
+
| `community` admin | `/record`, `/collection/define`, `/role/assign`, `/role/define` for every role but admin, `/role/unassign` and `/member/remove` of anyone not an admin, `/std.automation/instruct`, `/space/succeed`, `/key/change`, `/space/relays`, `/space/keepers` |
|
|
59
|
+
| `community` moderator | `/record`, `/role/assign` with `.role == "member"`, `/std.automation/instruct` |
|
|
60
|
+
| `community` member | `/record/write` and `/record/delete` where `.byCreator` is true, outside `STAFF_COLLECTIONS` |
|
|
61
|
+
| `coop` steward | `/record`, `/collection/define`, `/role/define` for member, `/role/assign` and `/role/unassign` of member or steward, `/member/remove` of anyone, `/std.automation/instruct`, `/space/succeed`, `/key/change`, `/space/relays`, `/space/keepers` |
|
|
62
|
+
| `coop` member | as `community` member, and `/space/succeed` |
|
|
63
|
+
|
|
64
|
+
### Founders or no top
|
|
65
|
+
|
|
66
|
+
Under `top: founders` you are the founder, and hold every command whatever
|
|
67
|
+
the roles say. So no `founders` preset needs a role for you. Name others who
|
|
68
|
+
found it with you in `cofounders`.
|
|
69
|
+
|
|
70
|
+
Under `top: none`, as in `coop`, there is no founder. You hold only your
|
|
71
|
+
`creatorRoles`, here `steward`, and another steward can remove you.
|
|
72
|
+
|
|
73
|
+
### Changing each other's records
|
|
74
|
+
|
|
75
|
+
Every preset says whether members may change each other's records. A grant
|
|
76
|
+
of `/record/write` with no policy on `.byCreator` lets them. In `community`
|
|
77
|
+
and `coop`, members change only what they made, and moderators or stewards
|
|
78
|
+
change anything.
|
|
79
|
+
|
|
80
|
+
`STAFF_COLLECTIONS` are the standard collections only moderators start in a
|
|
81
|
+
community: announcements, badges, awards, pins, labels, channels, hosts and
|
|
82
|
+
the space's own profile (`std.space-profile`).
|
|
83
|
+
|
|
84
|
+
### What "anyone not an admin" protects
|
|
85
|
+
|
|
86
|
+
The policy on removing "anyone not an admin" reads the target's roles as the
|
|
87
|
+
remover sees them. It stops an admin who has seen another's promotion. It
|
|
88
|
+
doesn't stop one who acts on an older view, or at the same moment. So
|
|
89
|
+
`community` admins can still remove or demote each other that way. Where that
|
|
90
|
+
matters, give removal to fewer people, or to the founders alone.
|
|
91
|
+
|
|
92
|
+
See [spec 03 §2.3 and §3.2](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
|
|
93
|
+
|
|
94
|
+
### Who defines a role
|
|
95
|
+
|
|
96
|
+
A role that may define itself can get stuck. If two of its holders rewrite
|
|
97
|
+
it differently, it keeps only what both versions share. If that drops
|
|
98
|
+
`/role/define`, nobody in the role can settle it.
|
|
99
|
+
|
|
100
|
+
So a preset gives `/role/define` for a role to another role, or to the
|
|
101
|
+
founders alone. In `community` the founders define admin, and admins define
|
|
102
|
+
the rest. In `coop` stewards define member, and nobody defines steward:
|
|
103
|
+
changing it takes a successor.
|
|
104
|
+
|
|
105
|
+
### `solo` never changes
|
|
106
|
+
|
|
107
|
+
The account's own derived spaces, the registry and the contacts space, use
|
|
108
|
+
`solo`'s roles byte for byte, and their ids depend on it. So `solo` must not
|
|
109
|
+
change. See
|
|
110
|
+
[spec 03 §13.1](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
|
|
111
|
+
|
|
112
|
+
## The top and founders
|
|
113
|
+
|
|
114
|
+
`spaces.access(id)` says who is at the top: `top` (`founders` or `none`),
|
|
115
|
+
`founder` on each member, and `founder` for this account.
|
|
116
|
+
|
|
117
|
+
Nobody removes or demotes a founder but the founder itself. So show no
|
|
118
|
+
remove button on a founder, and a "Step down" button on your own row when you
|
|
119
|
+
are one.
|
|
120
|
+
|
|
121
|
+
### Stepping down
|
|
122
|
+
|
|
123
|
+
```ts
|
|
124
|
+
await node.spaces.stepDown(space.id, { keep: 'admin' });
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
You stay, with the roles you hold, and are a founder no more. `keep` assigns
|
|
128
|
+
you that role first. With no role at all you would not be a member, so the
|
|
129
|
+
library refuses. To go altogether, `leave`.
|
|
130
|
+
|
|
131
|
+
Stepping down undoes whatever this account did elsewhere that hadn't seen it,
|
|
132
|
+
as leaving does. So step down from a device that has synced.
|
|
133
|
+
|
|
134
|
+
### Headless spaces
|
|
135
|
+
|
|
136
|
+
`access.headless` is true when no founder is left and no member may define
|
|
137
|
+
or assign any role. Members keep what their roles allow, but nobody can
|
|
138
|
+
change roles, and nothing in the constitution can change.
|
|
139
|
+
|
|
140
|
+
Say so plainly ("No one can change roles here any more"), and offer the way
|
|
141
|
+
on: naming a successor. Any member may do that once no member holds
|
|
142
|
+
`/space/succeed`.
|
|
@@ -1,12 +1,17 @@
|
|
|
1
1
|
# Proposing collections
|
|
2
2
|
|
|
3
|
-
A space can grow new collections without anyone deploying anything.
|
|
4
|
-
|
|
5
|
-
applies
|
|
6
|
-
let them define collections.
|
|
3
|
+
A space can grow new collections without anyone deploying anything. Anyone
|
|
4
|
+
in the space can propose them, and someone who may define collections
|
|
5
|
+
applies the proposal. This is how agents add new things, and people whose
|
|
6
|
+
role doesn't let them define collections.
|
|
7
|
+
|
|
8
|
+
## Proposing
|
|
9
|
+
|
|
10
|
+
A proposal is a **blueprint**: one `std.blueprint` record listing the
|
|
11
|
+
collections. Nothing is defined yet, so it can't break anything.
|
|
7
12
|
|
|
8
13
|
```typescript
|
|
9
|
-
import { proposeCollections
|
|
14
|
+
import { proposeCollections } from '@minca/core/schemas';
|
|
10
15
|
|
|
11
16
|
const proposal = await proposeCollections(node, space.id, {
|
|
12
17
|
title: 'Chores',
|
|
@@ -24,38 +29,47 @@ const proposal = await proposeCollections(node, space.id, {
|
|
|
24
29
|
},
|
|
25
30
|
],
|
|
26
31
|
});
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Through the `collections_propose` tool, a standard collection can be given by
|
|
35
|
+
name alone, like `"std.task"`. `standardCollections` puts the library's
|
|
36
|
+
definition in its place.
|
|
27
37
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
38
|
+
## Reviewing and applying
|
|
39
|
+
|
|
40
|
+
Before applying a blueprint, show the person what it would do.
|
|
41
|
+
`reviewBlueprint` says, for each collection, whether it is new, a change, or
|
|
42
|
+
the same, with a summary in sentences worked out from its rules:
|
|
43
|
+
|
|
44
|
+
```typescript
|
|
45
|
+
import type { NodeRecord } from '@minca/core';
|
|
46
|
+
import { reviewBlueprint, applyBlueprint, type Blueprint } from '@minca/core/schemas';
|
|
47
|
+
|
|
48
|
+
async function apply(proposal: NodeRecord<Blueprint>) {
|
|
49
|
+
const review = reviewBlueprint(proposal.body!, await node.collections.list(space.id));
|
|
50
|
+
// Show the review to the person, and apply only if they agree
|
|
51
|
+
await applyBlueprint(node, space.id, proposal.key);
|
|
52
|
+
}
|
|
31
53
|
```
|
|
32
54
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
- `reviewBlueprint` says, per collection, whether it is new, a change, or the
|
|
36
|
-
same, with a summary in sentences worked out from its rules. Show that to
|
|
37
|
-
the person before they apply it.
|
|
38
|
-
- `applyBlueprint` defines each collection, signed by whoever applies it.
|
|
39
|
-
They need a grant of `/collection/define` in the space, and a note that
|
|
40
|
-
grants it.
|
|
41
|
-
- To change it, propose a new one with `updates: <its key>`.
|
|
55
|
+
`applyBlueprint` defines each collection, signed by whoever applies it. They
|
|
56
|
+
need a grant of `/collection/define` in the space, and a note that grants it.
|
|
42
57
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
58
|
+
## Updating a proposal
|
|
59
|
+
|
|
60
|
+
To change a blueprint, propose a new one with `updates: <its key>`.
|
|
46
61
|
|
|
47
62
|
## Trying a contract before proposing it
|
|
48
63
|
|
|
49
|
-
Anyone in a space can write records directly, not only through
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
which every reader judges.
|
|
64
|
+
Anyone in a space can write records directly, not only through your app. So
|
|
65
|
+
your app's own checks stop nobody. What records must keep to for your app to
|
|
66
|
+
mean anything, like whose turn it is or a legal move, belongs in the
|
|
67
|
+
collection's [contract](collections.md#contracts), which every reader checks.
|
|
54
68
|
|
|
55
|
-
A contract written wrong refuses fair moves
|
|
69
|
+
A contract written wrong refuses fair moves or lets a cheat count, and
|
|
56
70
|
nothing shows it until someone plays. So `collections_propose` takes
|
|
57
|
-
`examples
|
|
58
|
-
before writing anything
|
|
71
|
+
`examples`. It runs each one through its collection's schema and contract
|
|
72
|
+
before writing anything:
|
|
59
73
|
|
|
60
74
|
```json
|
|
61
75
|
"examples": [
|
|
@@ -66,30 +80,37 @@ before writing anything, so the proposer sees a mistake first.
|
|
|
66
80
|
]
|
|
67
81
|
```
|
|
68
82
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
83
|
+
If any example comes out other than expected, nothing is proposed, and the
|
|
84
|
+
error says which one and why.
|
|
85
|
+
|
|
86
|
+
### What an example can say
|
|
87
|
+
|
|
88
|
+
| Field | Meaning |
|
|
89
|
+
| --------- | ---------------------------------------------------------------------------------- |
|
|
90
|
+
| `author` | The account DID that writes it. The proposer's when left out. |
|
|
91
|
+
| `prev` | The version before: `{ body, author?, links? }`. Leave it out for a first version. |
|
|
92
|
+
| `creator` | Who wrote the first version. Defaults to `prev`'s author, or this one's. |
|
|
93
|
+
| `expect` | `"pass"` or `"fail"`. |
|
|
94
|
+
|
|
95
|
+
`prev`'s author is this example's unless it names another, so to try
|
|
96
|
+
turn-taking, name both. An example expected to pass must fit its
|
|
97
|
+
collection's schema too.
|
|
98
|
+
|
|
99
|
+
### What examples don't try
|
|
100
|
+
|
|
101
|
+
- Rules (`onePer`, `fixed`, `final`), who may write, and a contract's `line`.
|
|
102
|
+
- `member(did)` asks about the space as it is now, not as the version saw it.
|
|
103
|
+
- A cited version can't be given, so an example whose contract cites one
|
|
104
|
+
never passes.
|
|
105
|
+
|
|
106
|
+
A collection with a contract that no example names is still proposed, with a
|
|
107
|
+
warning. Only the proposer sees the warning. The person applying the
|
|
108
|
+
blueprint sees the contract's conditions, not whether anyone tried them.
|
|
88
109
|
|
|
89
110
|
## Saying how they are meant to be used
|
|
90
111
|
|
|
91
112
|
A definition can't say "write one rota for each week, and say in it who does
|
|
92
|
-
what". A guide can, and an agent finds it
|
|
113
|
+
what". A guide can, and an agent finds it through `collections_list`:
|
|
93
114
|
|
|
94
115
|
```typescript
|
|
95
116
|
import { writeGuide } from '@minca/core/schemas';
|
|
@@ -102,14 +123,12 @@ await writeGuide(node, space.id, {
|
|
|
102
123
|
});
|
|
103
124
|
```
|
|
104
125
|
|
|
105
|
-
## An app's own
|
|
126
|
+
## An app's own screen
|
|
106
127
|
|
|
107
128
|
Core runs no app's code. The example app lets a space add apps with a screen
|
|
108
129
|
of their own: a `launcher.app` record that points at its blueprint and holds
|
|
109
|
-
one HTML document
|
|
110
|
-
once someone who may define collections has written the record
|
|
111
|
-
that isn't records-only.
|
|
112
|
-
are in the repository: `apps/example/src/components/apps/launcher.ts`,
|
|
113
|
-
`screens.ts` and `ScreenFrame.tsx`, and `apps/example/public/screen.html`.
|
|
130
|
+
one HTML document. It runs in a sealed frame, as the person looking, and only
|
|
131
|
+
once someone who may define collections has written the record under a note
|
|
132
|
+
that isn't records-only.
|
|
114
133
|
|
|
115
|
-
The details
|
|
134
|
+
The full details are in [Blueprints and guides](blueprints-and-guides.md).
|