brain-memory 0.3.0 → 0.4.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/CHANGELOG.md +54 -0
- package/SECURITY.md +44 -3
- package/bin/cloud-sync.js +49 -6
- package/commands/brain/sync.md +23 -0
- package/package.json +8 -4
- package/src/cloud-sync.js +121 -9
- package/store/CONTRACT.md +244 -0
- package/store/Dockerfile +24 -0
- package/store/README.md +43 -0
- package/store/SELF-HOSTING.md +200 -0
- package/store/bin/brain-store.js +189 -0
- package/store/conformance/conformance.test.js +341 -0
- package/store/conformance/helpers.js +145 -0
- package/store/deploy/Caddyfile +14 -0
- package/store/deploy/connector.Dockerfile +38 -0
- package/store/deploy/docker-compose.yml +83 -0
- package/store/deploy/env.example +19 -0
- package/store/lib/auth.js +174 -0
- package/store/lib/oidc.js +206 -0
- package/store/lib/storage.js +333 -0
- package/store/lib/tar.js +150 -0
- package/store/openapi.yaml +318 -0
- package/store/server.js +465 -0
- package/store/test/mock-issuer.js +104 -0
- package/store/test/oidc.test.js +217 -0
- package/store/test/store.test.js +445 -0
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,60 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
## [0.4.0] - 2026-09-18
|
|
10
|
+
|
|
11
|
+
Opens up sync. The HTTP interface between a Brain client and a remote store is
|
|
12
|
+
now a published contract with a conformance suite, and `brain-store` is a small
|
|
13
|
+
reference server you can run yourself, so a brain no longer has to live in Brain
|
|
14
|
+
Cloud to be shared between machines or reached from MCP-only hosts. Sync also
|
|
15
|
+
stops being last-writer-wins: clients name the archive they started from, and a
|
|
16
|
+
store that has moved on refuses the upload instead of overwriting another
|
|
17
|
+
device's memories. The contract is a **draft** and is open for comment in
|
|
18
|
+
[#6](https://github.com/omelas-tech/brain/issues/6) until at least 25 September
|
|
19
|
+
2026; it may still change. The project also gains a governance document, a
|
|
20
|
+
maintainers file and a code of conduct.
|
|
21
|
+
|
|
22
|
+
### Added
|
|
23
|
+
- **An open store contract and a self-hostable store.** `store/CONTRACT.md` (with
|
|
24
|
+
`store/openapi.yaml`) specifies the HTTP interface between a Brain client and a
|
|
25
|
+
remote store. `brain-store` is a reference server for it: Node.js, no
|
|
26
|
+
dependencies, files only, static bearer tokens stored as hashes, optional
|
|
27
|
+
AES-256-GCM encryption at rest. `store/conformance/` is a black-box suite that
|
|
28
|
+
checks any implementation over HTTP. See `store/SELF-HOSTING.md`.
|
|
29
|
+
- **Conditional sync (store contract 1.1).** `brain cloud push` now names the
|
|
30
|
+
archive it started from (`If-Match`). If another device pushed in the meantime
|
|
31
|
+
the store answers `412` and nothing is overwritten; pull, then push again, or
|
|
32
|
+
`brain cloud push --force`. Stores that predate 1.1 ignore the header, so
|
|
33
|
+
behaviour against them is unchanged.
|
|
34
|
+
- **Token login for self-hosted stores:** `brain cloud login --api-url URL
|
|
35
|
+
--token-stdin` (also `--token`, or `BRAIN_STORE_TOKEN`). The CLI refuses to send
|
|
36
|
+
a token over plain HTTP to another host unless `--allow-http` is given.
|
|
37
|
+
- **Connector: pluggable identity.** `CONNECTOR_IDP=static` lets the MCP connector
|
|
38
|
+
run in front of a self-hosted store with no Firebase: the sign-in page takes the
|
|
39
|
+
store token, and the store decides who the user is. Firebase remains the default
|
|
40
|
+
for the hosted service and its behaviour is unchanged.
|
|
41
|
+
`CONNECTOR_TRUST_PROXY` names the reverse proxy when it is not on loopback.
|
|
42
|
+
- **Sign-in through an organisation's identity provider (OpenID Connect).** The
|
|
43
|
+
store accepts ID tokens from a configured issuer (`STORE_OIDC_ISSUER`,
|
|
44
|
+
`STORE_OIDC_AUDIENCE`) and creates users on first sign-in; `CONNECTOR_IDP=oidc`
|
|
45
|
+
sends people to that issuer (authorization code, PKCE, nonce). RS256 and ES256
|
|
46
|
+
only; a public issuer such as Google requires an allow-list. Tested against a
|
|
47
|
+
mock issuer, not yet against each real provider.
|
|
48
|
+
- **Connector: no lost writes.** Sync-back is conditional. When another device
|
|
49
|
+
pushed first, the connector discards its working copy, starts again from the
|
|
50
|
+
store's brain, re-applies the write and pushes, so both sides' memories survive.
|
|
51
|
+
- Docker Compose for a store, a connector and Caddy (`store/deploy/`).
|
|
52
|
+
- `GOVERNANCE.md`, `MAINTAINERS.md`, `CODE_OF_CONDUCT.md`.
|
|
53
|
+
|
|
54
|
+
### Fixed
|
|
55
|
+
- `brain cloud push` on macOS no longer uploads an AppleDouble `._name` entry
|
|
56
|
+
beside every file with extended attributes (`COPYFILE_DISABLE`), which inflated
|
|
57
|
+
the archive and its reported file count.
|
|
58
|
+
- Connector: a user whose brain exists but has never been pushed to is treated as
|
|
59
|
+
new rather than as a store outage, so their session can be renewed.
|
|
60
|
+
- `CONTRIBUTING.md` described a project layout several releases old.
|
|
61
|
+
- `SECURITY.md` described the hosted service's retired key-derivation scheme.
|
|
62
|
+
|
|
9
63
|
## [0.3.0] - 2026-09-04
|
|
10
64
|
|
|
11
65
|
Ships brain as a plugin and moves its session behaviour from prompts into
|
package/SECURITY.md
CHANGED
|
@@ -64,8 +64,10 @@ connector** (a remote MCP server) are entirely optional. When you do use them, t
|
|
|
64
64
|
is how your data is protected:
|
|
65
65
|
|
|
66
66
|
- **Encrypted at rest.** Brains stored in Brain Cloud are encrypted on disk with
|
|
67
|
-
**AES-256-GCM**
|
|
68
|
-
|
|
67
|
+
**AES-256-GCM** envelope encryption: each user's data is encrypted with a
|
|
68
|
+
**per-user data key**, and that key is itself wrapped by a key held in a cloud
|
|
69
|
+
**key management service (KMS)**, not on the server's disk. A stolen disk,
|
|
70
|
+
backup, or snapshot yields no readable memories.
|
|
69
71
|
- **No plaintext on the connector.** The connector keeps each user's working copy
|
|
70
72
|
in **RAM only** (a tmpfs, wiped on restart) — it is never written to the
|
|
71
73
|
connector's disk.
|
|
@@ -87,11 +89,50 @@ your memories in memory. If you require that the server never sees plaintext, ke
|
|
|
87
89
|
your brain **local-only** (the default) or use Git/export sync with a passphrase
|
|
88
90
|
(below) instead of Brain Cloud.
|
|
89
91
|
|
|
92
|
+
## Self-hosted store (`brain-store`)
|
|
93
|
+
|
|
94
|
+
`store/` contains a reference store server you can run yourself
|
|
95
|
+
(`store/SELF-HOSTING.md`). What it does and does not protect:
|
|
96
|
+
|
|
97
|
+
- **Tokens are never stored.** A token is 256 random bits, shown once; the server
|
|
98
|
+
keeps its SHA-256 and compares in constant time. Tokens are never logged.
|
|
99
|
+
- **Failed logins are rate limited** per client address, and each user's request
|
|
100
|
+
and upload rates are bounded.
|
|
101
|
+
- **Uploads are untrusted input.** Size is bounded before and while reading. The
|
|
102
|
+
archive is inflated as a stream and only tar headers are examined, with bounds on
|
|
103
|
+
inflated size and entry count, so a compression bomb cannot exhaust memory. The
|
|
104
|
+
server never extracts an archive to disk.
|
|
105
|
+
- **Identifiers cannot leave the data directory.** User ids, brain ids and
|
|
106
|
+
snapshot names are matched against strict patterns before any path is built.
|
|
107
|
+
- **Tenant isolation.** Another user's brain is indistinguishable from one that
|
|
108
|
+
does not exist.
|
|
109
|
+
- **Optional encryption at rest** (AES-256-GCM, per-user key derived by
|
|
110
|
+
HKDF-SHA256 from `STORE_ENCRYPTION_KEY`). This protects a stolen disk or backup.
|
|
111
|
+
It is server-side encryption: the running server holds the key.
|
|
112
|
+
- **No TLS of its own.** The server speaks plain HTTP and binds to loopback by
|
|
113
|
+
default. Terminate TLS in a reverse proxy; the provided Compose setup does.
|
|
114
|
+
- **Conditional writes.** The precondition check and the replacement of an archive
|
|
115
|
+
happen under one in-process lock. Run one server process per data directory.
|
|
116
|
+
|
|
117
|
+
- **OpenID Connect sign-in is opt-in and narrow.** Only RS256 and ES256 are
|
|
118
|
+
accepted; `none` and HMAC algorithms are refused, and the key type must agree
|
|
119
|
+
with the algorithm named in the token. Issuer, audience, expiry and nonce are
|
|
120
|
+
checked, the issuer must be reached over HTTPS, and its discovery document must
|
|
121
|
+
name itself. A public issuer (Google) is refused unless an allow-list is set,
|
|
122
|
+
and allow-lists only honour addresses the issuer marks verified.
|
|
123
|
+
|
|
124
|
+
The connector's `static` identity provider sends the pasted store token only to
|
|
125
|
+
the store named in `BRAIN_CLOUD_API_URL`, and refuses to start unless that address
|
|
126
|
+
is set explicitly. Its sign-in page loads nothing from other hosts and cannot be
|
|
127
|
+
framed. The token is kept with the refresh grant encrypted under
|
|
128
|
+
`CONNECTOR_STATE_KEY`; without that key it is held in memory only.
|
|
129
|
+
|
|
90
130
|
## Supported Versions
|
|
91
131
|
|
|
92
132
|
| Version | Supported |
|
|
93
133
|
|---------|-----------|
|
|
94
|
-
| 0.
|
|
134
|
+
| 0.3.x | Yes |
|
|
135
|
+
| < 0.3 | No — please upgrade |
|
|
95
136
|
|
|
96
137
|
## Design Principles
|
|
97
138
|
|
package/bin/cloud-sync.js
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
|
-
* brain cloud — CLI for Brain Cloud
|
|
4
|
+
* brain cloud — CLI for syncing with Brain Cloud or a self-hosted brain-store
|
|
5
5
|
*
|
|
6
6
|
* Usage:
|
|
7
7
|
* brain cloud login [--api-url URL] Authenticate via device code flow
|
|
8
|
+
* brain cloud login --api-url URL --token-stdin
|
|
9
|
+
* Authenticate to a self-hosted store with a token
|
|
8
10
|
* brain cloud logout Clear stored credentials
|
|
9
|
-
* brain cloud push
|
|
11
|
+
* brain cloud push [--force] Upload ~/.brain/ to the cloud
|
|
10
12
|
* brain cloud pull Download from the cloud to ~/.brain/
|
|
11
13
|
* brain cloud status Show connection and sync status
|
|
12
14
|
*/
|
|
@@ -29,9 +31,18 @@ brain cloud — Brain Cloud sync CLI
|
|
|
29
31
|
Commands:
|
|
30
32
|
login [--api-url URL] Authenticate via device code flow
|
|
31
33
|
logout Clear stored credentials
|
|
32
|
-
push
|
|
34
|
+
push [--force] Upload ~/.brain/ to the cloud
|
|
33
35
|
pull Download from the cloud to ~/.brain/
|
|
34
36
|
status Show connection and sync status
|
|
37
|
+
|
|
38
|
+
Self-hosted store (brain-store):
|
|
39
|
+
login --api-url URL --token-stdin Read the token from standard input, e.g.
|
|
40
|
+
pbpaste | brain cloud login --api-url URL --token-stdin
|
|
41
|
+
login --api-url URL --token TOKEN Pass the token as an argument (it lands in shell history)
|
|
42
|
+
login --api-url URL With BRAIN_STORE_TOKEN set in the environment
|
|
43
|
+
--allow-http Permit plain HTTP to a host other than this machine
|
|
44
|
+
|
|
45
|
+
push refuses to overwrite changes it has not pulled. --force uploads anyway.
|
|
35
46
|
`.trim());
|
|
36
47
|
process.exit(0);
|
|
37
48
|
}
|
|
@@ -44,7 +55,7 @@ Commands:
|
|
|
44
55
|
cmdLogout();
|
|
45
56
|
break;
|
|
46
57
|
case 'push':
|
|
47
|
-
await cmdPush();
|
|
58
|
+
await cmdPush(args);
|
|
48
59
|
break;
|
|
49
60
|
case 'pull':
|
|
50
61
|
await cmdPull();
|
|
@@ -65,6 +76,17 @@ async function cmdLogin(args) {
|
|
|
65
76
|
apiUrl = args[urlIdx + 1];
|
|
66
77
|
}
|
|
67
78
|
|
|
79
|
+
const token = await readToken(args);
|
|
80
|
+
if (token) {
|
|
81
|
+
const result = await cloud.loginWithToken(BRAIN_DIR, apiUrl, token, {
|
|
82
|
+
allowHttp: args.includes('--allow-http'),
|
|
83
|
+
});
|
|
84
|
+
console.log(`✓ Logged in as ${result.user_email || 'unknown'}`);
|
|
85
|
+
console.log(` Brain ID: ${result.brain_id}`);
|
|
86
|
+
console.log(` API: ${result.api_url}`);
|
|
87
|
+
return;
|
|
88
|
+
}
|
|
89
|
+
|
|
68
90
|
console.log('Requesting device code...');
|
|
69
91
|
const loginInfo = await cloud.login(BRAIN_DIR, apiUrl);
|
|
70
92
|
|
|
@@ -88,14 +110,35 @@ async function cmdLogin(args) {
|
|
|
88
110
|
console.log(` API: ${config.api_url}`);
|
|
89
111
|
}
|
|
90
112
|
|
|
113
|
+
/**
|
|
114
|
+
* A store token from --token-stdin, --token, or BRAIN_STORE_TOKEN, in that order.
|
|
115
|
+
* Standard input is preferred: it keeps the token out of shell history and out of
|
|
116
|
+
* the process list.
|
|
117
|
+
*/
|
|
118
|
+
async function readToken(args) {
|
|
119
|
+
if (args.includes('--token-stdin')) {
|
|
120
|
+
const chunks = [];
|
|
121
|
+
for await (const chunk of process.stdin) chunks.push(chunk);
|
|
122
|
+
const token = Buffer.concat(chunks).toString('utf8').trim();
|
|
123
|
+
if (!token) throw new Error('--token-stdin was given but standard input was empty.');
|
|
124
|
+
return token;
|
|
125
|
+
}
|
|
126
|
+
const idx = args.indexOf('--token');
|
|
127
|
+
if (idx !== -1) {
|
|
128
|
+
if (!args[idx + 1]) throw new Error('--token needs a value.');
|
|
129
|
+
return args[idx + 1];
|
|
130
|
+
}
|
|
131
|
+
return process.env.BRAIN_STORE_TOKEN || null;
|
|
132
|
+
}
|
|
133
|
+
|
|
91
134
|
function cmdLogout() {
|
|
92
135
|
cloud.logout(BRAIN_DIR);
|
|
93
136
|
console.log('✓ Logged out. Credentials cleared.');
|
|
94
137
|
}
|
|
95
138
|
|
|
96
|
-
async function cmdPush() {
|
|
139
|
+
async function cmdPush(args) {
|
|
97
140
|
console.log('Packing ~/.brain/ ...');
|
|
98
|
-
const result = await cloud.push(BRAIN_DIR);
|
|
141
|
+
const result = await cloud.push(BRAIN_DIR, { force: args.includes('--force') });
|
|
99
142
|
console.log();
|
|
100
143
|
console.log('✓ Push complete!');
|
|
101
144
|
console.log(` Size: ${formatBytes(result.size_bytes)}`);
|
package/commands/brain/sync.md
CHANGED
|
@@ -46,6 +46,7 @@ Parse the user's input to determine the subcommand:
|
|
|
46
46
|
|
|
47
47
|
**Cloud Sync (Brain Cloud API):**
|
|
48
48
|
- `cloud login [--api-url URL]` → Authenticate via device code flow
|
|
49
|
+
- `cloud login --api-url URL --token-stdin` → Authenticate to a self-hosted `brain-store` with a token
|
|
49
50
|
- `cloud push` → Upload ~/.brain/ to Brain Cloud
|
|
50
51
|
- `cloud pull` → Download from Brain Cloud to ~/.brain/
|
|
51
52
|
- `cloud status` → Show cloud connection info
|
|
@@ -66,6 +67,20 @@ If no subcommand is given, show available subcommands.
|
|
|
66
67
|
|
|
67
68
|
## `/brain:sync cloud login [--api-url URL]`
|
|
68
69
|
|
|
70
|
+
### Self-hosted store
|
|
71
|
+
|
|
72
|
+
If the user names their own store (an `--api-url` that is not Brain Cloud) and has a
|
|
73
|
+
token from its operator, the login is a token login, not the device code flow:
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
pbpaste | brain cloud login --api-url <store URL> --token-stdin
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
**Never ask the user to paste the token into the conversation, and never echo it.**
|
|
80
|
+
Have them copy it to the clipboard and run the command above themselves (`! <command>`),
|
|
81
|
+
or set `BRAIN_STORE_TOKEN` in their own shell. The CLI refuses plain HTTP to a remote
|
|
82
|
+
host; do not add `--allow-http` unless the user says the network is trusted.
|
|
83
|
+
|
|
69
84
|
### Steps
|
|
70
85
|
|
|
71
86
|
1. **Check if already logged in:**
|
|
@@ -126,6 +141,14 @@ Then return — do not attempt the push.
|
|
|
126
141
|
Checksum: <checksum>
|
|
127
142
|
```
|
|
128
143
|
|
|
144
|
+
3. **If the push is refused because the store has changes that were not pulled**
|
|
145
|
+
(`The store has changes you have not pulled`): nothing was uploaded and nothing
|
|
146
|
+
was lost. Tell the user another device pushed first, then run `brain cloud pull`
|
|
147
|
+
followed by `brain cloud push`. Only use `brain cloud push --force` when the user
|
|
148
|
+
explicitly asks to overwrite what the store holds; it discards the other
|
|
149
|
+
device's changes (the store keeps a snapshot, so it can be undone with
|
|
150
|
+
`brain restore --from cloud`).
|
|
151
|
+
|
|
129
152
|
---
|
|
130
153
|
|
|
131
154
|
## `/brain:sync cloud pull`
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "brain-memory",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "A brain-inspired hierarchical memory system for AI coding agents. Deep nested file structure that mimics human memory with time-decay and strength-based recall.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude-code",
|
|
@@ -25,7 +25,8 @@
|
|
|
25
25
|
"url": "https://github.com/omelas-tech/brain/issues"
|
|
26
26
|
},
|
|
27
27
|
"bin": {
|
|
28
|
-
"brain": "bin/brain.js"
|
|
28
|
+
"brain": "bin/brain.js",
|
|
29
|
+
"brain-store": "store/bin/brain-store.js"
|
|
29
30
|
},
|
|
30
31
|
"files": [
|
|
31
32
|
"assets/",
|
|
@@ -35,6 +36,7 @@
|
|
|
35
36
|
"prompts/",
|
|
36
37
|
"templates/",
|
|
37
38
|
"src/",
|
|
39
|
+
"store/",
|
|
38
40
|
"integrations/agentskills/brain-memory/",
|
|
39
41
|
"README.md",
|
|
40
42
|
"SECURITY.md",
|
|
@@ -46,7 +48,7 @@
|
|
|
46
48
|
"url": "git+https://github.com/omelas-tech/brain.git"
|
|
47
49
|
},
|
|
48
50
|
"scripts": {
|
|
49
|
-
"test": "node --test test/index-manager.test.js test/scorer.test.js test/tfidf.test.js test/receipt.test.js test/recall.test.js test/recall-cli.test.js test/forget.test.js test/functional.test.js test/erasure.test.js test/stress.test.js test/crypto.test.js test/git-sync.test.js test/restore.test.js test/trust-recall.test.js test/cloud-sync.test.js test/export-import.test.js test/install.test.js test/prompts.test.js test/session-start.test.js test/memorize.test.js test/pinning.test.js test/skills.test.js test/contradiction.test.js test/harvest.test.js test/content-lint.test.js test/audit-log.test.js test/quarantine.test.js test/anomaly.test.js test/path-hardening.test.js test/supersede.test.js test/bitemporal.test.js test/integrity.test.js test/skill-verify.test.js test/decay-calibration.test.js test/recall-history.test.js test/plugin-manifests.test.js test/plugin-hooks.test.js test/sensitivity.test.js",
|
|
51
|
+
"test": "node --test test/index-manager.test.js test/scorer.test.js test/tfidf.test.js test/receipt.test.js test/recall.test.js test/recall-cli.test.js test/forget.test.js test/functional.test.js test/erasure.test.js test/stress.test.js test/crypto.test.js test/git-sync.test.js test/restore.test.js test/trust-recall.test.js test/cloud-sync.test.js test/export-import.test.js test/install.test.js test/prompts.test.js test/session-start.test.js test/memorize.test.js test/pinning.test.js test/skills.test.js test/contradiction.test.js test/harvest.test.js test/content-lint.test.js test/audit-log.test.js test/quarantine.test.js test/anomaly.test.js test/path-hardening.test.js test/supersede.test.js test/bitemporal.test.js test/integrity.test.js test/skill-verify.test.js test/decay-calibration.test.js test/recall-history.test.js test/plugin-manifests.test.js test/plugin-hooks.test.js test/sensitivity.test.js test/cloud-store.test.js store/test/store.test.js store/test/oidc.test.js store/conformance/conformance.test.js",
|
|
50
52
|
"test:integrations": "npm run test:integrations:agentskills && npm run test:integrations:openclaw && npm run test:integrations:copilot && npm run test:integrations:kilo && npm run test:integrations:hermes",
|
|
51
53
|
"test:integrations:agentskills": "node --test integrations/agentskills/test/*.test.mjs",
|
|
52
54
|
"test:integrations:openclaw": "node --test integrations/openclaw/test/*.test.mjs",
|
|
@@ -60,7 +62,9 @@
|
|
|
60
62
|
"release:patch": "npm version patch && npm publish",
|
|
61
63
|
"release:minor": "npm version minor && npm publish",
|
|
62
64
|
"release:major": "npm version major && npm publish",
|
|
63
|
-
"version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json .codex-plugin/plugin.json"
|
|
65
|
+
"version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json .codex-plugin/plugin.json",
|
|
66
|
+
"test:store": "node --test store/test/store.test.js store/test/oidc.test.js store/conformance/conformance.test.js",
|
|
67
|
+
"test:conformance": "node --test store/conformance/conformance.test.js"
|
|
64
68
|
},
|
|
65
69
|
"license": "MIT",
|
|
66
70
|
"engines": {
|
package/src/cloud-sync.js
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Brain Memory — Cloud Sync Engine
|
|
3
3
|
*
|
|
4
|
-
* Push/pull ~/.brain/ memories
|
|
5
|
-
*
|
|
4
|
+
* Push/pull ~/.brain/ memories to a store that implements the Brain store
|
|
5
|
+
* contract (store/CONTRACT.md): Brain Cloud at api.brainmemory.ai by default, or
|
|
6
|
+
* a self-hosted brain-store.
|
|
7
|
+
*
|
|
8
|
+
* Two ways to authenticate: the device-code flow (Brain Cloud), or a static
|
|
9
|
+
* bearer token issued by the store's operator (brain-store).
|
|
6
10
|
*
|
|
7
11
|
* Zero external dependencies — uses Node.js built-in https, fs, child_process.
|
|
8
12
|
*/
|
|
@@ -109,7 +113,7 @@ async function jsonRequest(url, method, data, token) {
|
|
|
109
113
|
/**
|
|
110
114
|
* Upload a file as multipart/form-data.
|
|
111
115
|
*/
|
|
112
|
-
async function uploadFile(url, filePath, token) {
|
|
116
|
+
async function uploadFile(url, filePath, token, extraHeaders) {
|
|
113
117
|
const boundary = '----BrainCloudUpload' + Date.now();
|
|
114
118
|
const fileContent = fs.readFileSync(filePath);
|
|
115
119
|
const header = Buffer.from(
|
|
@@ -126,6 +130,7 @@ async function uploadFile(url, filePath, token) {
|
|
|
126
130
|
'Content-Type': `multipart/form-data; boundary=${boundary}`,
|
|
127
131
|
'Content-Length': body.length.toString(),
|
|
128
132
|
'Authorization': `Bearer ${token}`,
|
|
133
|
+
...(extraHeaders || {}),
|
|
129
134
|
},
|
|
130
135
|
body,
|
|
131
136
|
});
|
|
@@ -224,6 +229,10 @@ async function getValidToken(brainDir) {
|
|
|
224
229
|
const config = readConfig(brainDir);
|
|
225
230
|
if (!config) throw new Error('Not logged in. Run cloud login first.');
|
|
226
231
|
|
|
232
|
+
// A static token never expires and has nothing to refresh; the store's
|
|
233
|
+
// operator revokes it by rotating it.
|
|
234
|
+
if (config.token_type === 'static') return config.access_token;
|
|
235
|
+
|
|
227
236
|
const now = Math.floor(Date.now() / 1000);
|
|
228
237
|
|
|
229
238
|
// Token still valid (with 30s buffer)
|
|
@@ -347,6 +356,66 @@ async function login(brainDir, apiUrl) {
|
|
|
347
356
|
};
|
|
348
357
|
}
|
|
349
358
|
|
|
359
|
+
/**
|
|
360
|
+
* True when `url` is safe to send a bearer token to: HTTPS, or plain HTTP to
|
|
361
|
+
* this machine only.
|
|
362
|
+
*/
|
|
363
|
+
function isSecureUrl(url) {
|
|
364
|
+
const parsed = new URL(url);
|
|
365
|
+
if (parsed.protocol === 'https:') return true;
|
|
366
|
+
return ['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname);
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
/**
|
|
370
|
+
* Log in to a store with a static bearer token (self-hosted brain-store).
|
|
371
|
+
*
|
|
372
|
+
* Verifies the token, links the user's first brain (creating one when the
|
|
373
|
+
* account has none), and saves the config. There is no refresh token.
|
|
374
|
+
*
|
|
375
|
+
* @param {string} brainDir
|
|
376
|
+
* @param {string} apiUrl
|
|
377
|
+
* @param {string} token
|
|
378
|
+
* @param {Object} [opts]
|
|
379
|
+
* @param {boolean} [opts.allowHttp] permit plain HTTP to a non-local host
|
|
380
|
+
* @returns {Promise<{user_email: string, brain_id: string, api_url: string}>}
|
|
381
|
+
*/
|
|
382
|
+
async function loginWithToken(brainDir, apiUrl, token, opts = {}) {
|
|
383
|
+
if (!apiUrl) throw new Error('A token login needs the store address: --api-url URL');
|
|
384
|
+
if (!token) throw new Error('No token given.');
|
|
385
|
+
const url = apiUrl.replace(/\/+$/, '');
|
|
386
|
+
if (!opts.allowHttp && !isSecureUrl(url)) {
|
|
387
|
+
throw new Error(
|
|
388
|
+
`Refusing to send a token over plain HTTP to ${new URL(url).host}. ` +
|
|
389
|
+
'Use an https:// address, or pass --allow-http if the network is trusted.'
|
|
390
|
+
);
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
const meRes = await jsonRequest(`${url}/auth/me`, 'GET', null, token);
|
|
394
|
+
if (meRes.status === 401) throw new Error('The store rejected this token.');
|
|
395
|
+
if (meRes.status !== 200) throw new Error(`Login failed (${meRes.status}): ${meRes.data.error || ''}`);
|
|
396
|
+
const user = meRes.data.user || {};
|
|
397
|
+
|
|
398
|
+
const brainsRes = await jsonRequest(`${url}/api/brains`, 'GET', null, token);
|
|
399
|
+
if (brainsRes.status !== 200) throw new Error(`Could not list brains (${brainsRes.status}).`);
|
|
400
|
+
let brainId = Array.isArray(brainsRes.data) && brainsRes.data.length > 0 ? brainsRes.data[0].id : null;
|
|
401
|
+
if (!brainId) {
|
|
402
|
+
const created = await jsonRequest(`${url}/api/brains`, 'POST', { name: 'default' }, token);
|
|
403
|
+
if (created.status !== 201) throw new Error(`Could not create a brain (${created.status}): ${created.data.error || ''}`);
|
|
404
|
+
brainId = created.data.id;
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
const config = {
|
|
408
|
+
api_url: url,
|
|
409
|
+
token_type: 'static',
|
|
410
|
+
access_token: token,
|
|
411
|
+
brain_id: brainId,
|
|
412
|
+
user_email: user.email || user.name || '',
|
|
413
|
+
connected_at: new Date().toISOString(),
|
|
414
|
+
};
|
|
415
|
+
writeConfig(brainDir, config);
|
|
416
|
+
return { user_email: config.user_email, brain_id: brainId, api_url: url };
|
|
417
|
+
}
|
|
418
|
+
|
|
350
419
|
/**
|
|
351
420
|
* Logout — clear stored tokens.
|
|
352
421
|
*
|
|
@@ -380,6 +449,9 @@ function packBrain(brainDir) {
|
|
|
380
449
|
execFileSync('tar', ['czf', tmpFile, ...excludeArgs, '-C', brainDir, '.'], {
|
|
381
450
|
stdio: 'pipe',
|
|
382
451
|
timeout: 120000,
|
|
452
|
+
// macOS tar otherwise adds an AppleDouble "._name" entry beside every file
|
|
453
|
+
// that has extended attributes, which bloats the archive and its file count.
|
|
454
|
+
env: { ...process.env, COPYFILE_DISABLE: '1' },
|
|
383
455
|
});
|
|
384
456
|
|
|
385
457
|
return tmpFile;
|
|
@@ -428,13 +500,38 @@ function copyExtracted(srcDir, destDir) {
|
|
|
428
500
|
// Push / Pull
|
|
429
501
|
// ---------------------------------------------------------------------------
|
|
430
502
|
|
|
503
|
+
/**
|
|
504
|
+
* Thrown when the store holds changes this brain has not pulled. Nothing was
|
|
505
|
+
* uploaded.
|
|
506
|
+
*/
|
|
507
|
+
class PushConflictError extends Error {
|
|
508
|
+
constructor(remoteChecksum, baseChecksum) {
|
|
509
|
+
super(
|
|
510
|
+
'The store has changes you have not pulled, so nothing was uploaded. ' +
|
|
511
|
+
'Run `brain cloud pull` and push again, or `brain cloud push --force` to overwrite the store.'
|
|
512
|
+
);
|
|
513
|
+
this.name = 'PushConflictError';
|
|
514
|
+
this.code = 'PUSH_CONFLICT';
|
|
515
|
+
this.remote_checksum = remoteChecksum || null;
|
|
516
|
+
this.base_checksum = baseChecksum || null;
|
|
517
|
+
}
|
|
518
|
+
}
|
|
519
|
+
|
|
431
520
|
/**
|
|
432
521
|
* Push ~/.brain/ to the cloud.
|
|
433
522
|
*
|
|
523
|
+
* When this brain knows the checksum of the archive it last pulled or pushed,
|
|
524
|
+
* the upload is conditional (`If-Match`): a store that has moved on answers 412
|
|
525
|
+
* and nothing is overwritten. Stores that predate contract 1.1 ignore the header
|
|
526
|
+
* and behave as before.
|
|
527
|
+
*
|
|
434
528
|
* @param {string} brainDir
|
|
529
|
+
* @param {Object} [opts]
|
|
530
|
+
* @param {boolean} [opts.force] upload unconditionally, replacing whatever the store holds
|
|
435
531
|
* @returns {Promise<{size_bytes: number, file_count: number, checksum: string}>}
|
|
532
|
+
* @throws {PushConflictError}
|
|
436
533
|
*/
|
|
437
|
-
async function push(brainDir) {
|
|
534
|
+
async function push(brainDir, opts = {}) {
|
|
438
535
|
const config = readConfig(brainDir);
|
|
439
536
|
if (!config) throw new Error('Not logged in. Run cloud login first.');
|
|
440
537
|
if (!config.brain_id) throw new Error('No brain linked. Run cloud login again.');
|
|
@@ -448,17 +545,28 @@ async function push(brainDir) {
|
|
|
448
545
|
const tarSize = fs.statSync(tarPath).size;
|
|
449
546
|
const url = `${config.api_url}/api/brains/${config.brain_id}/sync`;
|
|
450
547
|
|
|
451
|
-
const
|
|
548
|
+
const conditional = !opts.force && config.base_checksum
|
|
549
|
+
? { 'If-Match': `"${config.base_checksum}"` }
|
|
550
|
+
: null;
|
|
551
|
+
const res = await uploadFile(url, tarPath, token, conditional);
|
|
552
|
+
|
|
553
|
+
if (res.status === 412) {
|
|
554
|
+
let remote = null;
|
|
555
|
+
try { remote = JSON.parse(res.body).current_checksum; } catch { /* body is advisory */ }
|
|
556
|
+
throw new PushConflictError(remote, config.base_checksum);
|
|
557
|
+
}
|
|
452
558
|
|
|
453
559
|
if (res.status !== 200) {
|
|
454
|
-
|
|
455
|
-
|
|
560
|
+
let message = res.body;
|
|
561
|
+
try { message = JSON.parse(res.body).error || res.body; } catch { /* not JSON */ }
|
|
562
|
+
throw new Error(`Push failed (${res.status}): ${message}`);
|
|
456
563
|
}
|
|
457
564
|
|
|
458
565
|
const result = JSON.parse(res.body);
|
|
459
566
|
|
|
460
|
-
// Update config with last push time
|
|
567
|
+
// Update config with last push time, and remember what the store now holds.
|
|
461
568
|
config.last_push = new Date().toISOString();
|
|
569
|
+
if (result.checksum) config.base_checksum = result.checksum;
|
|
462
570
|
writeConfig(brainDir, config);
|
|
463
571
|
|
|
464
572
|
return { ...result, local_size: tarSize };
|
|
@@ -490,8 +598,9 @@ async function pull(brainDir) {
|
|
|
490
598
|
// Extract into ~/.brain/
|
|
491
599
|
unpackBrain(tmpFile, brainDir);
|
|
492
600
|
|
|
493
|
-
// Update config
|
|
601
|
+
// Update config, and remember which archive this brain is now based on.
|
|
494
602
|
config.last_pull = new Date().toISOString();
|
|
603
|
+
if (checksum) config.base_checksum = checksum;
|
|
495
604
|
writeConfig(brainDir, config);
|
|
496
605
|
|
|
497
606
|
return { size_bytes: size, checksum };
|
|
@@ -653,7 +762,9 @@ async function status(brainDir) {
|
|
|
653
762
|
|
|
654
763
|
module.exports = {
|
|
655
764
|
login,
|
|
765
|
+
loginWithToken,
|
|
656
766
|
logout,
|
|
767
|
+
PushConflictError,
|
|
657
768
|
push,
|
|
658
769
|
pull,
|
|
659
770
|
listVersions,
|
|
@@ -668,5 +779,6 @@ module.exports = {
|
|
|
668
779
|
packBrain,
|
|
669
780
|
unpackBrain,
|
|
670
781
|
resolvePaths,
|
|
782
|
+
isSecureUrl,
|
|
671
783
|
DEFAULT_API_URL,
|
|
672
784
|
};
|