@minca/core 0.1.5 → 0.1.7
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 +247 -215
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,256 +1,288 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://github.com/leifriksheim/minca/raw/main/.github/assets/mark.svg" width="96" alt="">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<h1 align="center">Minca</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<strong>A local-first protocol for groups.</strong><br>
|
|
9
|
+
Your account is a code you keep. Your group's data lives in signed spaces that sync<br>
|
|
10
|
+
straight between devices. Every app is a view onto that data, never its owner.
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
<p align="center">
|
|
14
|
+
<a href="https://minca.social">Website</a> ·
|
|
15
|
+
<a href="https://app.minca.social">Open the app</a> ·
|
|
16
|
+
<a href="https://github.com/leifriksheim/minca/blob/main/packages/core/docs/README.md">Docs</a> ·
|
|
17
|
+
<a href="https://github.com/leifriksheim/minca/blob/main/spec/README.md">Spec</a> ·
|
|
18
|
+
<a href="https://github.com/leifriksheim/minca/blob/main/spec/threat-model.md">Threat model</a>
|
|
19
|
+
</p>
|
|
20
|
+
|
|
21
|
+
<p align="center">
|
|
22
|
+
<a href="https://www.npmjs.com/package/@minca/core"><img src="https://img.shields.io/npm/v/@minca/core?color=2340d6&label=%40minca%2Fcore" alt="npm"></a>
|
|
23
|
+
<a href="https://github.com/leifriksheim/minca/actions/workflows/check.yml"><img src="https://github.com/leifriksheim/minca/actions/workflows/check.yml/badge.svg" alt="Check"></a>
|
|
24
|
+
<a href="https://github.com/leifriksheim/minca/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-4e8f6c" alt="MIT license"></a>
|
|
25
|
+
</p>
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
A minca (minka) is the Andean custom of everyone turning out to build what
|
|
30
|
+
serves them all. Minca gives a club, a street or a crew a place to talk, plan
|
|
31
|
+
and get things done that belongs to them: no company in the middle, no server
|
|
32
|
+
that holds the truth, and no app that can lock their data in.
|
|
33
|
+
|
|
34
|
+
- **You hold your account.** It's a 16-byte seed, written down as a recovery
|
|
35
|
+
code. The same code is the same person on any device, in any app.
|
|
36
|
+
- **Every record is signed, and every device checks it.** A space's roles and
|
|
37
|
+
rules live in the space. Each peer applies them the same way, so there is no
|
|
38
|
+
server to trust and none to write.
|
|
39
|
+
- **Private means encrypted before it leaves.** Private spaces are sealed end
|
|
40
|
+
to end. An invite link carries the key, so sharing never goes through a
|
|
41
|
+
server.
|
|
42
|
+
- **Works offline.** Devices sync directly over WebRTC when they can reach each
|
|
43
|
+
other. Relays only introduce them.
|
|
44
|
+
- **Apps get a pass, not your keys.** An app or an AI agent writes under a
|
|
45
|
+
short note from your account, for the spaces you pick, and you can revoke it.
|
|
46
|
+
|
|
47
|
+
> [!WARNING]
|
|
48
|
+
> Minca is early. It works, and it's still changing: the wire format and the
|
|
49
|
+
> APIs may break before v1. It has had no external security audit yet, and a
|
|
50
|
+
> leaked seed can't be rotated. [The threat model](https://github.com/leifriksheim/minca/blob/main/spec/threat-model.md) says
|
|
51
|
+
> what holds today and what doesn't.
|
|
52
|
+
|
|
53
|
+
## Start here
|
|
54
|
+
|
|
55
|
+
| I want to… | Go to |
|
|
56
|
+
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
57
|
+
| **Use it** with my group | [app.minca.social](https://app.minca.social) in the browser, or [the desktop app and the Chrome extension](https://minca.social/download) |
|
|
58
|
+
| **Build an app** on it | [`@minca/core`](#build-an-app) and [its guides](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/README.md) |
|
|
59
|
+
| **Connect an AI agent** or a bot | [`@minca/cli`](https://github.com/leifriksheim/minca/blob/main/packages/cli/README.md): `minca connect`, then Claude Code, Cursor or any MCP client reads and writes as you |
|
|
60
|
+
| **Keep spaces online** on a server | [`minca run`](https://github.com/leifriksheim/minca/blob/main/packages/cli/README.md#the-always-on-node), an always-on node that adds uptime, never authority |
|
|
61
|
+
| **Implement the protocol** | [The spec](https://github.com/leifriksheim/minca/blob/main/spec/README.md): bytes on the wire, what is signed, what every peer checks |
|
|
62
|
+
| **Contribute** | [CONTRIBUTING.md](https://github.com/leifriksheim/minca/blob/main/CONTRIBUTING.md) |
|
|
63
|
+
|
|
64
|
+
## Build an app
|
|
2
65
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
devices, and every app is a view onto that data rather than its owner.
|
|
6
|
-
|
|
7
|
-
> **Building an app?** Short guides — sign-in, collections and rules, automations,
|
|
8
|
-
> queries, blueprints, agents — are in [packages/core/docs](packages/core/docs/README.md),
|
|
9
|
-
> and ship in the package as `node_modules/@minca/core/docs/`, so a
|
|
10
|
-
> coding agent finds the ones that match the installed version.
|
|
11
|
-
>
|
|
12
|
-
> **Building a client, or an agent that needs the architecture?** The
|
|
13
|
-
> protocol is specified in [spec](spec/README.md): wire formats,
|
|
14
|
-
> what is signed, and what every peer must check. The tests are its
|
|
15
|
-
> executable half.
|
|
16
|
-
|
|
17
|
-
## Architecture
|
|
18
|
-
|
|
19
|
-
```
|
|
20
|
-
┌──────────────────────────────────────────────────────────────┐
|
|
21
|
-
│ Applications │
|
|
22
|
-
├──────────────┬───────────┬────────────┬──────────┬───────────┤
|
|
23
|
-
│ Accounts │ Spaces │ Validation │ Privacy │ Sync │
|
|
24
|
-
│ seed, vault, │ founders, │ crypto → │ envelope │ Negentropy│
|
|
25
|
-
│ root signer, │ roles × │ structural │ + HPKE, │ per │
|
|
26
|
-
│ UCAN, pairing│ grants │ → UCAN │ per space│ collection│
|
|
27
|
-
├──────────────┴───────────┴────────────┴──────────┴───────────┤
|
|
28
|
-
│ Storage: signed versions + plain index over an adapter │
|
|
29
|
-
│ IndexedDB (per origin) · data folder (shared by origins) │
|
|
30
|
-
├──────────────────────────────────────────────────────────────┤
|
|
31
|
-
│ Network: WebRTC data channels │
|
|
32
|
-
│ several relays at once · peers introduce peers │
|
|
33
|
-
├──────────────────────────────────────────────────────────────┤
|
|
34
|
-
│ Web Crypto · WebAuthn · IndexedDB · File System Access · │
|
|
35
|
-
│ WebRTC · @noble/curves · @scure/base │
|
|
36
|
-
└──────────────────────────────────────────────────────────────┘
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
## Key Principles
|
|
40
|
-
|
|
41
|
-
- **No authority.** No server issues identities or holds the truth. Relays only
|
|
42
|
-
introduce peers; an always-on node adds availability, never authority.
|
|
43
|
-
- **Apps are views.** Data lives in spaces the user owns, as signed records any
|
|
44
|
-
app can read and verify.
|
|
45
|
-
- **Local-first.** Works offline, syncs when peers are reachable.
|
|
46
|
-
- **Few, boring dependencies.** Native browser APIs first. Where a problem is
|
|
47
|
-
hard and already solved — elliptic-curve arithmetic, for one — a very stable,
|
|
48
|
-
widely used library instead of our own. See [CLAUDE.md](CLAUDE.md#dependencies).
|
|
49
|
-
- **Isomorphic.** Runs in browsers, Node and Bun via `globalThis`.
|
|
50
|
-
- **Functional.** Plain functions and frozen data, no class hierarchies.
|
|
51
|
-
- **Standard Schema.** Bring your own validator (Zod, Valibot, ArkType, …).
|
|
52
|
-
|
|
53
|
-
## Quick Start
|
|
54
|
-
|
|
55
|
-
```typescript
|
|
56
|
-
import {
|
|
57
|
-
generateSeed,
|
|
58
|
-
seedToRecoveryCode,
|
|
59
|
-
createIdentityManager,
|
|
60
|
-
createLocalRootSigner,
|
|
61
|
-
publicKeyToDid,
|
|
62
|
-
P256_MULTICODEC,
|
|
63
|
-
createSigner,
|
|
64
|
-
createVersion,
|
|
65
|
-
createIndexedDBAdapter,
|
|
66
|
-
createStorageProvider,
|
|
67
|
-
createSpaceManager,
|
|
68
|
-
} from '@minca/core';
|
|
69
|
-
|
|
70
|
-
// 1. An account is a 16-byte seed. Show the code once; the user keeps it.
|
|
71
|
-
const seed = generateSeed();
|
|
72
|
-
console.log(seedToRecoveryCode(seed)); // 'K7N6-ERYP-68TZ-A7HN-VJW3-QWKN-CG'
|
|
73
|
-
|
|
74
|
-
const manager = createIdentityManager();
|
|
75
|
-
const me = await manager.fromSeed(seed); // same seed → same DID, anywhere
|
|
76
|
-
const provider = manager.getProvider();
|
|
77
|
-
|
|
78
|
-
// 2. The root key signs one thing: permission for a session key to write.
|
|
79
|
-
const root = createLocalRootSigner(me, provider);
|
|
80
|
-
const session = await provider.generateKeyPair();
|
|
81
|
-
const sessionDid = publicKeyToDid(await provider.exportPublicKey(session.publicKey), P256_MULTICODEC);
|
|
82
|
-
const note = await root.delegate({
|
|
83
|
-
audience: sessionDid,
|
|
84
|
-
command: '/', // everything the account may do
|
|
85
|
-
expiration: Math.floor(Date.now() / 1000) + 3600,
|
|
86
|
-
});
|
|
87
|
-
|
|
88
|
-
// 3. A space to put things in
|
|
89
|
-
const spaces = createSpaceManager(await createIndexedDBAdapter('my-app/registry'));
|
|
90
|
-
const { space } = await spaces.create({ name: 'Notes', visibility: 'public', creator: me.did });
|
|
91
|
-
|
|
92
|
-
// 4. A signed record, stored in that space's own store
|
|
93
|
-
const storage = createStorageProvider(await createIndexedDBAdapter(`my-app/space/${space.id}`));
|
|
94
|
-
const signed = await createSigner(provider).sign(
|
|
95
|
-
createVersion({
|
|
96
|
-
author: sessionDid,
|
|
97
|
-
collection: 'app.example.note',
|
|
98
|
-
space: space.id,
|
|
99
|
-
body: { text: 'Hello, decentralized world!' },
|
|
100
|
-
proof: note, // the note from the account to this key: one token
|
|
101
|
-
// This key's first version in this collection: its place in its line (spec 02 §4.10). A node keeps count for you.
|
|
102
|
-
log: { n: 0 },
|
|
103
|
-
}),
|
|
104
|
-
session.privateKey,
|
|
105
|
-
);
|
|
106
|
-
await storage.addVersion(signed);
|
|
66
|
+
```bash
|
|
67
|
+
npm install @minca/core
|
|
107
68
|
```
|
|
108
69
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
API is plain data in and out:
|
|
70
|
+
A node is the whole stack in one object: it signs, stores, encrypts, checks
|
|
71
|
+
and syncs. Its API is plain data in and out.
|
|
112
72
|
|
|
113
73
|
```typescript
|
|
114
74
|
import {
|
|
115
75
|
createNode,
|
|
116
76
|
createIdentityManager,
|
|
117
77
|
createLocalRootSigner,
|
|
78
|
+
generateSeed,
|
|
79
|
+
seedToRecoveryCode,
|
|
118
80
|
indexedDBStores,
|
|
119
81
|
rolePresets,
|
|
120
82
|
} from '@minca/core';
|
|
121
83
|
|
|
84
|
+
// 1. An account is a seed. Show its recovery code once; the person keeps it.
|
|
85
|
+
const seed = generateSeed();
|
|
86
|
+
console.log(seedToRecoveryCode(seed)); // 'K7N6-ERYP-68TZ-A7HN-VJW3-QWKN-CG'
|
|
122
87
|
const manager = createIdentityManager();
|
|
123
|
-
const me = await manager.
|
|
88
|
+
const me = await manager.fromSeed(seed);
|
|
124
89
|
|
|
90
|
+
// 2. A node for that account, syncing through a relay.
|
|
125
91
|
const node = await createNode({
|
|
126
|
-
signer: createLocalRootSigner(me, manager.getProvider()),
|
|
127
|
-
stores: indexedDBStores('
|
|
128
|
-
network: { relays: ['wss://
|
|
92
|
+
signer: createLocalRootSigner(me, manager.getProvider()),
|
|
93
|
+
stores: indexedDBStores('groceries'),
|
|
94
|
+
network: { relays: ['wss://minca.fly.dev'] },
|
|
129
95
|
});
|
|
130
96
|
|
|
97
|
+
// 3. A private space, encrypted end to end, with a team's roles.
|
|
131
98
|
const space = await node.spaces.create({ name: 'Groceries', visibility: 'private', ...rolePresets.team });
|
|
132
|
-
const milk = await node.records.put(space.id, 'app.todo.item', { text: 'milk', done: false });
|
|
133
|
-
await node.records.update(space.id, milk.key, { text: 'milk', done: true }); // same key, next version
|
|
134
|
-
node.subscribe((event) => {
|
|
135
|
-
if (event.type === 'records') redraw();
|
|
136
|
-
});
|
|
137
99
|
|
|
138
|
-
|
|
139
|
-
const
|
|
140
|
-
await node.
|
|
141
|
-
```
|
|
100
|
+
// 4. Signed records. An edit is the next version of the same key.
|
|
101
|
+
const milk = await node.records.put(space.id, 'app.todo.item', { text: 'Milk', done: false });
|
|
102
|
+
await node.records.update(space.id, milk.key, { text: 'Milk', done: true });
|
|
142
103
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
| Topic | Library (how to call it) | Protocol (what peers agree on) |
|
|
146
|
-
| ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
147
|
-
| The node: records and versions, live messages, holding spaces, actions | [node](packages/core/docs/node.md), [records and queries](packages/core/docs/records-and-queries.md), [actions](packages/core/docs/actions.md) | [02 Records](spec/02-records.md), [06 Nodes and sessions](spec/06-nodes-and-sessions.md) |
|
|
148
|
-
| Signing in, `<minca-auth>`, React hooks | [building an app](packages/core/docs/building-an-app.md), [sign-in](packages/core/docs/sign-in.md) | [01 Identity](spec/01-identity.md) |
|
|
149
|
-
| The account home, app grants, keepers, topic tags, notifications | [building an app](packages/core/docs/building-an-app.md), [node](packages/core/docs/node.md), [apps/home](apps/home/README.md) | [06 Nodes and sessions](spec/06-nodes-and-sessions.md), [03 Spaces](spec/03-spaces.md) |
|
|
150
|
-
| Identity: the seed, recovery code, wraps, passkeys, UCAN, root signers | [sign-in](packages/core/docs/sign-in.md), [node](packages/core/docs/node.md#root-signers-and-notes) | [01 Identity](spec/01-identity.md) |
|
|
151
|
-
| Spaces: the constitution, founders, roles and their grants, invites, successors, key changes, profiles, the account registry | [spaces](packages/core/docs/spaces.md) | [03 Spaces](spec/03-spaces.md) |
|
|
152
|
-
| Collections, schemas, rules, contracts and computed fields, links, queries, the standard library | [collections](packages/core/docs/collections.md), [contracts](packages/core/docs/contracts.md), [computed fields](packages/core/docs/computed.md), [query format](packages/core/docs/query-format.md), [standard library](packages/core/docs/standard-library.md), [blueprints and guides](packages/core/docs/blueprints-and-guides.md) | [02 Records](spec/02-records.md), [09 Contracts](spec/09-contracts.md) |
|
|
153
|
-
| Calls, contacts, doors, direct messages | [calls](packages/core/docs/calls.md), [contacts](packages/core/docs/contacts.md), [doors](packages/core/docs/doors.md), [direct messages](packages/core/docs/direct-messages.md) | [07 Doors](spec/07-doors.md), [04 Network](spec/04-network.md) |
|
|
154
|
-
| Network: the relay, TURN, meeting peers, introductions, pairing a phone | [node](packages/core/docs/node.md#the-network), [packages/relay](packages/relay/README.md) | [04 Network](spec/04-network.md) |
|
|
155
|
-
| Sync, storage adapters, data folders and locking them, mirrors | [storage](packages/core/docs/storage.md) | [05 Sync and storage](spec/05-sync-and-storage.md) |
|
|
156
|
-
| The CLI, the always-on node, hosting, agents and MCP | [packages/cli](packages/cli/README.md), [agents](packages/core/docs/agents.md) | [06 Nodes and sessions](spec/06-nodes-and-sessions.md) |
|
|
157
|
-
| The app, Liquid and mini apps | [apps/example](apps/example/README.md) | — |
|
|
158
|
-
| Planned work | [docs](packages/core/docs/README.md#planned-in-the-library) | [spec](spec/README.md) |
|
|
159
|
-
|
|
160
|
-
## Running it locally
|
|
104
|
+
// 5. A live query: it runs again whenever a change arrives, from here or a friend's phone.
|
|
105
|
+
node.records.watch(space.id, { collection: 'app.todo.item' }, (result) => render(result.records));
|
|
161
106
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
npm run dev
|
|
107
|
+
// 6. The invite is the key. A friend calls node.spaces.join(invite) and joins as an editor.
|
|
108
|
+
const invite = await node.spaces.invite(space.id);
|
|
165
109
|
```
|
|
166
110
|
|
|
167
|
-
|
|
111
|
+
Most apps never hold the seed at all. They ask the person's account home,
|
|
112
|
+
which signs a note for the app's own key, for the spaces the person picks:
|
|
168
113
|
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
| home | http://localhost:5174 | The account home it connects to |
|
|
173
|
-
| site | http://localhost:5185 | The website (minca.social) |
|
|
174
|
-
| node | port 8787 | An always-on node that is also the relay; a throwaway identity on first run (`packages/cli/.env.dev`, data in `.minca-dev/`) |
|
|
175
|
-
| host | http://localhost:8788 | `minca host`, what "Keep my spaces online" uses and what spaces chip in for; settings in `packages/cli/.env.host.dev` |
|
|
176
|
-
| stripe | — | Only when you add a Stripe test key: forwards Stripe's webhooks to the host |
|
|
114
|
+
```tsx
|
|
115
|
+
import { createMincaConnection } from '@minca/core/session';
|
|
116
|
+
import { MincaProvider, useConnection } from '@minca/core/react';
|
|
177
117
|
|
|
178
|
-
|
|
179
|
-
|
|
118
|
+
const connection = createMincaConnection({
|
|
119
|
+
home: 'https://home.minca.social/connect', // a suggestion: the person may use their own
|
|
120
|
+
request: { name: 'Todo', access: 'write', scope: 'spaces' },
|
|
121
|
+
network: { relays: ['wss://minca.fly.dev'] },
|
|
122
|
+
});
|
|
180
123
|
|
|
181
|
-
|
|
124
|
+
function App() {
|
|
125
|
+
const { connection, state } = useConnection();
|
|
126
|
+
if (state.status !== 'ready')
|
|
127
|
+
return <button onClick={() => connection.connect()}>Connect with Minca</button>;
|
|
128
|
+
return <Todos />; // useQuery(space, { collection: 'app.todo.item' }) keeps it live
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
createRoot(root).render(
|
|
132
|
+
<MincaProvider connection={connection}>
|
|
133
|
+
<App />
|
|
134
|
+
</MincaProvider>,
|
|
135
|
+
);
|
|
136
|
+
```
|
|
182
137
|
|
|
183
|
-
|
|
138
|
+
[Building an app](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/building-an-app.md) goes on from there:
|
|
139
|
+
signing in, collections and their rules, queries, React hooks. The guides ship
|
|
140
|
+
in the package, so a coding agent finds the ones for the installed version in
|
|
141
|
+
`node_modules/@minca/core/docs/`.
|
|
184
142
|
|
|
185
|
-
|
|
186
|
-
| ---------------- | ----------------------------- | --------------------------------------------------------------------------- |
|
|
187
|
-
| `packages/core` | `@minca/core` (published) | The protocol library, and its tests |
|
|
188
|
-
| `packages/cli` | `@minca/cli` (published) | `minca`: the always-on node, hosting, agents, MCP |
|
|
189
|
-
| `packages/relay` | `@minca/relay` (private) | The signaling relay and its mailbox, run alone on Fly and inside every node |
|
|
190
|
-
| `apps/home` | — | The account home, at home.minca.social |
|
|
191
|
-
| `apps/example` | — | The app, at app.minca.social |
|
|
192
|
-
| `apps/site` | — | The website, at minca.social |
|
|
193
|
-
| `apps/extension` | — | The Chrome extension |
|
|
194
|
-
| `apps/shared` | `@minca/app-shared` (private) | Styles, relay settings and components the apps and the website share |
|
|
195
|
-
| `spec` | — | The protocol specification |
|
|
143
|
+
## How it works
|
|
196
144
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
145
|
+
```
|
|
146
|
+
┌──────────────────────────────────────────────────────────────┐
|
|
147
|
+
│ Applications │
|
|
148
|
+
├──────────────┬───────────┬────────────┬──────────┬───────────┤
|
|
149
|
+
│ Accounts │ Spaces │ Validation │ Privacy │ Sync │
|
|
150
|
+
│ seed, vault, │ founders, │ crypto → │ envelope │ Negentropy│
|
|
151
|
+
│ root signer, │ roles × │ structural │ + HPKE, │ per │
|
|
152
|
+
│ UCAN, pairing│ grants │ → UCAN │ per space│ collection│
|
|
153
|
+
├──────────────┴───────────┴────────────┴──────────┴───────────┤
|
|
154
|
+
│ Storage: signed versions + plain index over an adapter │
|
|
155
|
+
│ IndexedDB (per origin) · data folder (shared by origins) │
|
|
156
|
+
├──────────────────────────────────────────────────────────────┤
|
|
157
|
+
│ Network: WebRTC data channels │
|
|
158
|
+
│ several relays at once · peers introduce peers │
|
|
159
|
+
├──────────────────────────────────────────────────────────────┤
|
|
160
|
+
│ Web Crypto · WebAuthn · IndexedDB · File System Access · │
|
|
161
|
+
│ WebRTC · @noble/curves · @scure/base │
|
|
162
|
+
└──────────────────────────────────────────────────────────────┘
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
**Keys sign.** The seed derives a root key, a `did:key`. The root key never
|
|
166
|
+
signs data: it signs an hour-long note (a UCAN 1.0 delegation) for a session
|
|
167
|
+
key, and the session key signs everything else.
|
|
168
|
+
→ [01 Identity](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md)
|
|
169
|
+
|
|
170
|
+
**Records carry their history.** A record is a JSON body with a key that stays
|
|
171
|
+
the same across edits; each edit is a new signed version over canonical JSON,
|
|
172
|
+
so two implementations sign the same bytes. A collection's schema and rules
|
|
173
|
+
are records in the space too.
|
|
174
|
+
→ [02 Records](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)
|
|
175
|
+
|
|
176
|
+
**Spaces hold.** A space starts from a constitution whose hash is its id. Its
|
|
177
|
+
roles, grants, members and removals are records every device replays the same
|
|
178
|
+
way, so devices that heard things in a different order reach the same verdict.
|
|
179
|
+
Removing someone changes the key.
|
|
180
|
+
→ [03 Spaces](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)
|
|
181
|
+
|
|
182
|
+
**Devices check.** Every version that arrives, from a peer, a folder or your
|
|
183
|
+
own app, goes through the same gates: shape, signature, the note from the
|
|
184
|
+
account, then the space's grants and rules.
|
|
185
|
+
→ [02 Records §9](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md#9-validation-what-a-peer-checks-before-keeping-a-version)
|
|
186
|
+
|
|
187
|
+
**Relays introduce, they don't decide.** A relay holds no data and has no say;
|
|
188
|
+
the handshake catches a lying one. Peers then sync each collection with
|
|
189
|
+
Negentropy, so syncing costs about as much as what changed.
|
|
190
|
+
→ [04 Network](https://github.com/leifriksheim/minca/blob/main/spec/04-network.md), [05 Sync and storage](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md)
|
|
191
|
+
|
|
192
|
+
The [protocol page](https://minca.social/protocol) walks through the same
|
|
193
|
+
design with pictures.
|
|
194
|
+
|
|
195
|
+
### What it's for, and what it isn't
|
|
196
|
+
|
|
197
|
+
Minca is for data that's private, shared by a few people, and works offline.
|
|
198
|
+
It isn't for public feeds at the scale of a social network. There's no server
|
|
199
|
+
to reset an account: lose the seed and the account is gone. And reading can't
|
|
200
|
+
be undone: whoever had a space's key keeps what they read. The
|
|
201
|
+
[threat model](https://github.com/leifriksheim/minca/blob/main/spec/threat-model.md) lists every such limit, with its issue.
|
|
202
|
+
|
|
203
|
+
## In this repository
|
|
204
|
+
|
|
205
|
+
One npm workspace. Everything imports the protocol as `@minca/core`.
|
|
206
|
+
|
|
207
|
+
| Folder | |
|
|
208
|
+
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
209
|
+
| [`spec/`](https://github.com/leifriksheim/minca/blob/main/spec/README.md) | The protocol specification and its threat model |
|
|
210
|
+
| [`packages/core`](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/README.md) | **`@minca/core`**, the reference implementation. Start here |
|
|
211
|
+
| [`packages/cli`](https://github.com/leifriksheim/minca/blob/main/packages/cli/README.md) | **`@minca/cli`**: `minca`, the always-on node, hosting, agents and MCP |
|
|
212
|
+
| [`packages/relay`](https://github.com/leifriksheim/minca/blob/main/packages/relay/README.md) | The signaling relay and its mailbox |
|
|
213
|
+
| [`apps/example`](https://github.com/leifriksheim/minca/blob/main/apps/example/README.md) | The Minca app, at [app.minca.social](https://app.minca.social) |
|
|
214
|
+
| [`apps/home`](https://github.com/leifriksheim/minca/blob/main/apps/home/README.md) | The account home, at [home.minca.social](https://home.minca.social) |
|
|
215
|
+
| [`apps/desktop`](https://github.com/leifriksheim/minca/blob/main/apps/desktop/README.md), [`apps/extension`](https://github.com/leifriksheim/minca/blob/main/apps/extension/README.md) | The desktop app and the Chrome extension |
|
|
216
|
+
| [`apps/site`](https://github.com/leifriksheim/minca/blob/main/apps/site/README.md) | The website, [minca.social](https://minca.social) |
|
|
217
|
+
| [`scenarios/`](https://github.com/leifriksheim/minca/blob/main/scenarios/README.md) | Kinds of community written as tests: a chess club, a co-op, mutual credit, and attacks on each |
|
|
218
|
+
|
|
219
|
+
<details>
|
|
220
|
+
<summary><strong>Where each topic is described</strong>: the library's docs and the spec, side by side</summary>
|
|
221
|
+
|
|
222
|
+
<br>
|
|
223
|
+
|
|
224
|
+
| Topic | Library (how to call it) | Protocol (what peers agree on) |
|
|
225
|
+
| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
226
|
+
| The node: records and versions, live messages, holding spaces, actions | [node](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/node.md), [records and queries](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/records-and-queries.md), [actions](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/actions.md) | [02 Records](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md), [06 Nodes and sessions](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md) |
|
|
227
|
+
| Signing in, `<minca-auth>`, React hooks | [building an app](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/building-an-app.md), [sign-in](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/sign-in.md) | [01 Identity](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md) |
|
|
228
|
+
| The account home, app grants, keepers, topic tags, notifications | [building an app](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/building-an-app.md), [node](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/node.md), [apps/home](https://github.com/leifriksheim/minca/blob/main/apps/home/README.md) | [06 Nodes and sessions](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md), [03 Spaces](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md) |
|
|
229
|
+
| Identity: the seed, recovery code, wraps, passkeys, UCAN, root signers | [sign-in](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/sign-in.md), [node](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/node.md#root-signers-and-notes) | [01 Identity](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md) |
|
|
230
|
+
| Spaces: the constitution, founders, roles and grants, invites, successors, key changes, profiles | [spaces](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/spaces.md) | [03 Spaces](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md) |
|
|
231
|
+
| Collections, schemas, rules, contracts and computed fields, links, queries, the standard library | [collections](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/collections.md), [contracts](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/contracts.md), [computed fields](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/computed.md), [query format](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/query-format.md), [standard library](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/standard-library.md), [blueprints and guides](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/blueprints-and-guides.md) | [02 Records](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md), [09 Contracts](https://github.com/leifriksheim/minca/blob/main/spec/09-contracts.md) |
|
|
232
|
+
| Calls, contacts, doors, direct messages | [calls](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/calls.md), [contacts](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/contacts.md), [doors](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/doors.md), [direct messages](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/direct-messages.md) | [07 Doors](https://github.com/leifriksheim/minca/blob/main/spec/07-doors.md), [04 Network](https://github.com/leifriksheim/minca/blob/main/spec/04-network.md) |
|
|
233
|
+
| Network: the relay, TURN, meeting peers, introductions, pairing a phone | [node](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/node.md#the-network), [packages/relay](https://github.com/leifriksheim/minca/blob/main/packages/relay/README.md) | [04 Network](https://github.com/leifriksheim/minca/blob/main/spec/04-network.md) |
|
|
234
|
+
| Sync, storage adapters, data folders and locking them, mirrors | [storage](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/storage.md) | [05 Sync and storage](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md) |
|
|
235
|
+
| Hosting: keeping spaces online, payment, bots a host runs | [packages/cli](https://github.com/leifriksheim/minca/blob/main/packages/cli/README.md) | [08 Hosting](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md) |
|
|
236
|
+
| The CLI, the always-on node, agents and MCP | [packages/cli](https://github.com/leifriksheim/minca/blob/main/packages/cli/README.md), [agents](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/agents.md) | [06 Nodes and sessions](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md) |
|
|
237
|
+
| The app, Liquid and mini apps | [apps/example](https://github.com/leifriksheim/minca/blob/main/apps/example/README.md) | — |
|
|
238
|
+
| Planned work | [docs](https://github.com/leifriksheim/minca/blob/main/packages/core/docs/README.md#planned-in-the-library) | [spec](https://github.com/leifriksheim/minca/blob/main/spec/README.md) |
|
|
239
|
+
|
|
240
|
+
</details>
|
|
241
|
+
|
|
242
|
+
## Principles
|
|
243
|
+
|
|
244
|
+
- **No authority.** No server issues identities or holds the truth. An
|
|
245
|
+
always-on node adds availability, never authority.
|
|
246
|
+
- **Apps are views.** Data lives in spaces people own, as signed records any
|
|
247
|
+
app can read and verify.
|
|
248
|
+
- **The spec is the product.** It holds only what two implementations must
|
|
249
|
+
agree on, and the tests are its executable half: every rule a peer checks
|
|
250
|
+
has a test of a peer refusing what breaks it.
|
|
251
|
+
- **Few, boring dependencies.** Native Web APIs first; a library only where
|
|
252
|
+
the problem is hard and already solved, like elliptic curves
|
|
253
|
+
([the list, and why](https://github.com/leifriksheim/minca/blob/main/CLAUDE.md#dependencies)).
|
|
254
|
+
- **Isomorphic.** Browsers, Node and Bun, via `globalThis`.
|
|
255
|
+
- **Plain functions and frozen data.** No class hierarchies. Bring your own
|
|
256
|
+
validator through Standard Schema (Zod, Valibot, ArkType, …).
|
|
203
257
|
|
|
204
|
-
##
|
|
258
|
+
## Contributing
|
|
205
259
|
|
|
206
|
-
|
|
207
|
-
(`packages/cli/`) are released together, always with the same version:
|
|
260
|
+
Run everything locally with one install:
|
|
208
261
|
|
|
209
262
|
```bash
|
|
210
|
-
npm
|
|
263
|
+
npm install
|
|
264
|
+
npm run dev # the app, the account home, the website, a node and a host
|
|
211
265
|
```
|
|
212
266
|
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
it (`v0.1.2`), locally. Both are published (each builds itself first: `dist/`
|
|
217
|
-
for the core, one bundled file for the CLI), and only then are the commit and
|
|
218
|
-
tag pushed.
|
|
219
|
-
|
|
220
|
-
If a release stops partway — npm login, a one-time password, the network —
|
|
221
|
-
fix it and run `npm run release` again. It sees the version isn't fully on npm
|
|
222
|
-
yet and publishes what's missing, instead of bumping again. `npm run release
|
|
223
|
-
-- --dry-run` does everything but publish and push. The script is
|
|
224
|
-
`scripts/release.mjs`; bumpp's settings are in `bump.config.ts`.
|
|
225
|
-
|
|
226
|
-
The desktop app (`apps/desktop`) and the Chrome extension (`apps/extension`)
|
|
227
|
-
carry the same version, and the tag builds them: `.github/workflows/release.yml`
|
|
228
|
-
puts the Mac `.dmg`, the Windows installer (a preview), the extension's zip and
|
|
229
|
-
`SHA256SUMS` on a GitHub Release, each with a build attestation. Their names
|
|
230
|
-
don't change between releases, so the site's `/download` page links to
|
|
231
|
-
`releases/latest/download/<file>`. A tag with a `-` (`v0.2.0-rc.1`) makes a
|
|
232
|
-
pre-release, which those links skip. None of them is signed yet. Every PR
|
|
233
|
-
builds them too (`.github/workflows/build.yml`), the desktop app only when
|
|
234
|
-
something in it changes, and the Actions tab runs that workflow by hand.
|
|
235
|
-
|
|
236
|
-
## Tests
|
|
267
|
+
[CONTRIBUTING.md](https://github.com/leifriksheim/minca/blob/main/CONTRIBUTING.md) covers the rest: what runs where, the tests
|
|
268
|
+
and scenarios, how a protocol change is reviewed, and releasing. Bugs and
|
|
269
|
+
planned work are in [the issues](https://github.com/leifriksheim/minca/issues).
|
|
237
270
|
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
271
|
+
## Security
|
|
272
|
+
|
|
273
|
+
Please report a vulnerability privately, through
|
|
274
|
+
[GitHub's security advisories](https://github.com/leifriksheim/minca/security/advisories/new),
|
|
275
|
+
not in a public issue. What Minca defends, against whom, and where it doesn't
|
|
276
|
+
yet, is in [the threat model](https://github.com/leifriksheim/minca/blob/main/spec/threat-model.md).
|
|
277
|
+
|
|
278
|
+
## Thanks
|
|
242
279
|
|
|
243
|
-
|
|
244
|
-
for
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
pairing; peer introductions; Negentropy, checked against the reference
|
|
249
|
-
implementation; the validation gates; and two peers reconciling, including the forged, stolen,
|
|
250
|
-
unauthorized and malformed versions their gatekeepers reject. Above those:
|
|
251
|
-
the node API — versioned records, links, queries, collection definitions,
|
|
252
|
-
profiles, the account registry, moving and merging accounts — and the CLI.
|
|
280
|
+
Minca stands on [UCAN](https://github.com/ucan-wg/spec) for delegation,
|
|
281
|
+
[Negentropy](https://github.com/hoytech/negentropy) for set reconciliation,
|
|
282
|
+
[HPKE (RFC 9180)](https://www.rfc-editor.org/rfc/rfc9180) for sealing keys,
|
|
283
|
+
[CEL](https://cel.dev) for contracts, and Paul Miller's audited
|
|
284
|
+
[noble](https://paulmillr.com/noble/) cryptography.
|
|
253
285
|
|
|
254
286
|
## License
|
|
255
287
|
|
|
256
|
-
MIT
|
|
288
|
+
[MIT](https://github.com/leifriksheim/minca/blob/main/LICENSE)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@minca/core",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.7",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Self-sovereign P2P protocol for the browser — identity, schemas, storage, networking, and gossip sync",
|
|
6
6
|
"repository": {
|
|
@@ -71,7 +71,7 @@
|
|
|
71
71
|
"build": "rm -rf dist && tsc",
|
|
72
72
|
"typecheck": "tsc --noEmit && tsc -p tests",
|
|
73
73
|
"test": "node --experimental-vm-modules --import tsx --test --test-concurrency=4 --test-timeout=60000 --test-force-exit tests/*.test.ts",
|
|
74
|
-
"prepack": "
|
|
74
|
+
"prepack": "node ../../scripts/npm-readme.mjs",
|
|
75
75
|
"postpack": "rm -f README.md",
|
|
76
76
|
"prepublishOnly": "npm run build"
|
|
77
77
|
},
|