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 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** using a **per-user key** (HKDF-derived from a server master key).
68
- A stolen disk, backup, or snapshot yields no readable memories.
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.1.x (beta) | Yes |
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 sync
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 Upload ~/.brain/ to the cloud
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 Upload ~/.brain/ to the cloud
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)}`);
@@ -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.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 via the Brain Cloud API (api.brainmemory.ai).
5
- * Uses the device code OAuth flow for CLI authentication.
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 res = await uploadFile(url, tarPath, token);
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
- const data = JSON.parse(res.body);
455
- throw new Error(`Push failed (${res.status}): ${data.error || res.body}`);
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
  };