brain-memory 0.3.0 → 0.5.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.
Files changed (62) hide show
  1. package/CHANGELOG.md +153 -0
  2. package/README.md +4 -0
  3. package/SECURITY.md +61 -9
  4. package/bin/brain.js +24 -3
  5. package/bin/cloud-sync.js +49 -6
  6. package/bin/install.js +72 -14
  7. package/bin/memorize.js +50 -6
  8. package/bin/port.js +174 -0
  9. package/bin/recall.js +16 -6
  10. package/bin/reinforce.js +5 -0
  11. package/bin/session-start.js +30 -4
  12. package/bin/verify.js +42 -4
  13. package/commands/brain/memorize.md +8 -0
  14. package/commands/brain/sync.md +23 -0
  15. package/commands/brain/verify.md +10 -2
  16. package/hooks/citation-check.mjs +94 -0
  17. package/hooks/hooks.json +11 -0
  18. package/hooks/lib.mjs +6 -0
  19. package/hooks/prompt-recall.mjs +24 -3
  20. package/hooks/session-start.mjs +4 -2
  21. package/integrations/README.md +4 -0
  22. package/integrations/agentskills/brain-memory/SKILL.md +9 -5
  23. package/package.json +10 -5
  24. package/prompts/antigravity.md +4 -2
  25. package/prompts/claude.md +4 -2
  26. package/prompts/copilot.md +4 -2
  27. package/prompts/kilo.md +4 -2
  28. package/prompts/openai.md +4 -2
  29. package/prompts/opencode.md +4 -2
  30. package/src/adapters.js +240 -0
  31. package/src/anomaly.js +41 -1
  32. package/src/cloud-sync.js +123 -11
  33. package/src/content-lint.js +55 -2
  34. package/src/export-import.js +1 -1
  35. package/src/git-sync.js +1 -1
  36. package/src/index-manager.js +9 -5
  37. package/src/installer.js +35 -1
  38. package/src/pinning.js +20 -1
  39. package/src/provenance.js +34 -0
  40. package/src/quarantine.js +82 -5
  41. package/src/receipt.js +9 -4
  42. package/src/surfaced.js +188 -0
  43. package/store/CONTRACT.md +244 -0
  44. package/store/Dockerfile +24 -0
  45. package/store/README.md +43 -0
  46. package/store/SELF-HOSTING.md +200 -0
  47. package/store/bin/brain-store.js +189 -0
  48. package/store/conformance/conformance.test.js +341 -0
  49. package/store/conformance/helpers.js +199 -0
  50. package/store/deploy/Caddyfile +14 -0
  51. package/store/deploy/connector.Dockerfile +38 -0
  52. package/store/deploy/docker-compose.yml +83 -0
  53. package/store/deploy/env.example +19 -0
  54. package/store/lib/auth.js +174 -0
  55. package/store/lib/oidc.js +206 -0
  56. package/store/lib/storage.js +333 -0
  57. package/store/lib/tar.js +150 -0
  58. package/store/openapi.yaml +318 -0
  59. package/store/server.js +465 -0
  60. package/store/test/mock-issuer.js +104 -0
  61. package/store/test/oidc.test.js +222 -0
  62. package/store/test/store.test.js +445 -0
@@ -0,0 +1,206 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * brain-store — OpenID Connect ID-token verification
5
+ *
6
+ * Verifies an ID token against an issuer's published keys: discovery document,
7
+ * JWKS, signature, then the claims. No dependencies. Shared by the store (which
8
+ * accepts ID tokens as bearer credentials) and the MCP connector (which obtains
9
+ * them), so there is exactly one implementation to get right.
10
+ *
11
+ * Deliberately narrow:
12
+ * - RS256 and ES256 only. `none` and every HMAC algorithm are refused outright,
13
+ * which closes the classic "sign with the public key as an HMAC secret" hole.
14
+ * - The key type must agree with the algorithm in the token header.
15
+ * - `iss` must equal the issuer in the discovery document, exactly.
16
+ * - HTTPS only, except for loopback addresses (tests, local development).
17
+ */
18
+
19
+ const crypto = require('crypto');
20
+
21
+ const ALGS = {
22
+ RS256: { kty: 'RSA', verify: (key, data, sig) => crypto.verify('sha256', data, key, sig) },
23
+ ES256: {
24
+ kty: 'EC',
25
+ crv: 'P-256',
26
+ // JOSE signatures are the raw r||s pair, not DER.
27
+ verify: (key, data, sig) => crypto.verify('sha256', data, { key, dsaEncoding: 'ieee-p1363' }, sig),
28
+ },
29
+ };
30
+
31
+ const JWKS_TTL_MS = 60 * 60 * 1000;
32
+ const JWKS_MIN_REFETCH_MS = 60 * 1000;
33
+ const PUBLIC_ISSUERS = new Set(['accounts.google.com']);
34
+
35
+ class OidcError extends Error {
36
+ constructor(message) {
37
+ super(message);
38
+ this.name = 'OidcError';
39
+ }
40
+ }
41
+
42
+ function isLoopback(hostname) {
43
+ return ['localhost', '127.0.0.1', '[::1]', '::1'].includes(hostname);
44
+ }
45
+
46
+ function requireSecure(url, what) {
47
+ let parsed;
48
+ try { parsed = new URL(url); } catch { throw new OidcError(`${what} is not a URL: ${url}`); }
49
+ if (parsed.protocol === 'https:') return parsed;
50
+ if (parsed.protocol === 'http:' && isLoopback(parsed.hostname)) return parsed;
51
+ throw new OidcError(`${what} must use https: ${url}`);
52
+ }
53
+
54
+ const stripSlash = (s) => String(s).replace(/\/+$/, '');
55
+
56
+ function decodePart(part, what) {
57
+ try {
58
+ return JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
59
+ } catch {
60
+ throw new OidcError(`malformed token ${what}`);
61
+ }
62
+ }
63
+
64
+ function list(value) {
65
+ if (Array.isArray(value)) return value.map((v) => String(v).trim().toLowerCase()).filter(Boolean);
66
+ return String(value || '').split(',').map((v) => v.trim().toLowerCase()).filter(Boolean);
67
+ }
68
+
69
+ /**
70
+ * @param {Object} opts
71
+ * @param {string} opts.issuer e.g. https://login.microsoftonline.com/<tenant>/v2.0
72
+ * @param {string} opts.audience the client id the tokens are issued to
73
+ * @param {string|string[]} [opts.allowedDomains] email / Google `hd` domains allowed in
74
+ * @param {string|string[]} [opts.allowedEmails] exact addresses allowed in
75
+ * @param {number} [opts.clockSkewSec=60]
76
+ * @param {Function} [opts.fetch] defaults to the global fetch
77
+ */
78
+ function createVerifier(opts) {
79
+ if (!opts || !opts.issuer || !opts.audience) throw new OidcError('issuer and audience are required');
80
+ const issuerUrl = requireSecure(opts.issuer, 'issuer');
81
+ const audience = String(opts.audience);
82
+ const allowedDomains = list(opts.allowedDomains);
83
+ const allowedEmails = list(opts.allowedEmails);
84
+ const skew = opts.clockSkewSec == null ? 60 : opts.clockSkewSec;
85
+ const doFetch = opts.fetch || globalThis.fetch;
86
+
87
+ // Anyone on the internet can get a token from a public issuer. Without an
88
+ // allow-list, "signed by Google" would mean "anybody".
89
+ if (PUBLIC_ISSUERS.has(issuerUrl.hostname) && !allowedDomains.length && !allowedEmails.length) {
90
+ throw new OidcError(
91
+ `${issuerUrl.hostname} issues tokens to anyone: set an allow-list of domains or email addresses`
92
+ );
93
+ }
94
+
95
+ let discoveryDoc = null;
96
+ let keys = new Map();
97
+ let keysFetchedAt = 0;
98
+
99
+ async function getJson(url, what) {
100
+ let res;
101
+ try {
102
+ res = await doFetch(url, { headers: { accept: 'application/json' } });
103
+ } catch (err) {
104
+ throw new OidcError(`${what} unreachable: ${err.message}`);
105
+ }
106
+ if (!res.ok) throw new OidcError(`${what} answered ${res.status}`);
107
+ try { return await res.json(); } catch { throw new OidcError(`${what} is not JSON`); }
108
+ }
109
+
110
+ async function discovery() {
111
+ if (discoveryDoc) return discoveryDoc;
112
+ const doc = await getJson(stripSlash(opts.issuer) + '/.well-known/openid-configuration', 'discovery document');
113
+ if (typeof doc.issuer !== 'string' || stripSlash(doc.issuer) !== stripSlash(opts.issuer)) {
114
+ throw new OidcError('discovery document names a different issuer');
115
+ }
116
+ requireSecure(doc.jwks_uri, 'jwks_uri');
117
+ discoveryDoc = doc;
118
+ return doc;
119
+ }
120
+
121
+ async function loadKeys() {
122
+ const doc = await discovery();
123
+ const jwks = await getJson(doc.jwks_uri, 'JWKS');
124
+ const next = new Map();
125
+ for (const jwk of Array.isArray(jwks.keys) ? jwks.keys : []) {
126
+ if (!jwk || typeof jwk.kid !== 'string') continue;
127
+ if (jwk.use && jwk.use !== 'sig') continue;
128
+ next.set(jwk.kid, jwk);
129
+ }
130
+ keys = next;
131
+ keysFetchedAt = Date.now();
132
+ }
133
+
134
+ async function keyFor(kid) {
135
+ const now = Date.now();
136
+ if (!keysFetchedAt || now - keysFetchedAt > JWKS_TTL_MS) await loadKeys();
137
+ // An unknown key id usually means the issuer rotated its keys. Refetch, but
138
+ // not more than once a minute, so garbage tokens cannot be used to hammer it.
139
+ if (!keys.has(kid) && now - keysFetchedAt > JWKS_MIN_REFETCH_MS) await loadKeys();
140
+ return keys.get(kid) || null;
141
+ }
142
+
143
+ function checkAllowList(claims) {
144
+ if (!allowedDomains.length && !allowedEmails.length) return;
145
+ const email = typeof claims.email === 'string' ? claims.email.toLowerCase() : '';
146
+ const verified = claims.email_verified === true;
147
+ if (verified && email && allowedEmails.includes(email)) return;
148
+ if (typeof claims.hd === 'string' && allowedDomains.includes(claims.hd.toLowerCase())) return;
149
+ if (verified && email.includes('@') && allowedDomains.includes(email.slice(email.lastIndexOf('@') + 1))) return;
150
+ throw new OidcError('this account is not on the allow-list');
151
+ }
152
+
153
+ /**
154
+ * Verify an ID token. Resolves with its claims, or rejects with OidcError.
155
+ * @param {string} token
156
+ * @param {Object} [expect]
157
+ * @param {string} [expect.nonce] required to match when given
158
+ */
159
+ async function verify(token, expect = {}) {
160
+ if (typeof token !== 'string' || token.length > 16384) throw new OidcError('malformed token');
161
+ const parts = token.split('.');
162
+ if (parts.length !== 3) throw new OidcError('malformed token');
163
+ const [h, p, s] = parts;
164
+ const header = decodePart(h, 'header');
165
+ const claims = decodePart(p, 'payload');
166
+
167
+ const alg = Object.prototype.hasOwnProperty.call(ALGS, header.alg) ? ALGS[header.alg] : null;
168
+ if (!alg) throw new OidcError(`unsupported algorithm: ${String(header.alg)}`);
169
+ if (typeof header.kid !== 'string' || !header.kid) throw new OidcError('token names no key');
170
+
171
+ const jwk = await keyFor(header.kid);
172
+ if (!jwk) throw new OidcError('unknown signing key');
173
+ if (jwk.kty !== alg.kty || (alg.crv && jwk.crv !== alg.crv)) throw new OidcError('key does not match the algorithm');
174
+ if (jwk.alg && jwk.alg !== header.alg) throw new OidcError('key does not match the algorithm');
175
+
176
+ let key;
177
+ try { key = crypto.createPublicKey({ key: jwk, format: 'jwk' }); } catch { throw new OidcError('unusable signing key'); }
178
+ let ok = false;
179
+ try { ok = alg.verify(key, Buffer.from(`${h}.${p}`), Buffer.from(s, 'base64url')); } catch { ok = false; }
180
+ if (!ok) throw new OidcError('invalid signature');
181
+
182
+ const doc = await discovery();
183
+ const now = Math.floor(Date.now() / 1000);
184
+ if (claims.iss !== doc.issuer) throw new OidcError('issuer mismatch');
185
+ const auds = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
186
+ if (!auds.includes(audience)) throw new OidcError('audience mismatch');
187
+ if (auds.length > 1 && claims.azp !== audience) throw new OidcError('authorized party mismatch');
188
+ if (typeof claims.exp !== 'number' || claims.exp + skew < now) throw new OidcError('token expired');
189
+ if (typeof claims.iat === 'number' && claims.iat - skew > now) throw new OidcError('token issued in the future');
190
+ if (typeof claims.nbf === 'number' && claims.nbf - skew > now) throw new OidcError('token not yet valid');
191
+ if (typeof claims.sub !== 'string' || !claims.sub || claims.sub.length > 255) throw new OidcError('no subject');
192
+ if (expect.nonce !== undefined && claims.nonce !== expect.nonce) throw new OidcError('nonce mismatch');
193
+
194
+ checkAllowList(claims);
195
+ return claims;
196
+ }
197
+
198
+ return { verify, discovery };
199
+ }
200
+
201
+ /** True when a bearer token has the shape of a JWT (and so might be an ID token). */
202
+ function looksLikeJwt(token) {
203
+ return typeof token === 'string' && /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(token);
204
+ }
205
+
206
+ module.exports = { createVerifier, looksLikeJwt, OidcError };
@@ -0,0 +1,333 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * brain-store — file-only storage
5
+ *
6
+ * <dataDir>/brains/<userId>/<brainId>/
7
+ * meta.json brain record
8
+ * current.bin the live archive (plain or encrypted)
9
+ * versions/<name> snapshots taken before each overwrite
10
+ *
11
+ * There is no database. A brain's record is its meta.json, and listing a user's
12
+ * brains is a directory listing.
13
+ *
14
+ * Encryption at rest is optional. With a master key, each file is sealed with
15
+ * AES-256-GCM under a per-user key derived by HKDF-SHA256, so one user's data
16
+ * cannot be opened with another user's key. Plain files written before the key
17
+ * was set remain readable and are sealed the next time they are rewritten.
18
+ *
19
+ * Checksums, sizes and file counts always describe the PLAINTEXT archive, so
20
+ * what a client verifies does not depend on how the store keeps the bytes.
21
+ */
22
+
23
+ const crypto = require('crypto');
24
+ const fs = require('fs');
25
+ const path = require('path');
26
+
27
+ const MAGIC = Buffer.from('BSTORE1\0', 'latin1');
28
+ const NONCE_LEN = 12;
29
+ const TAG_LEN = 16;
30
+
31
+ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
32
+ const USER_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
33
+ const VERSION_RE = /^\d{8}T\d{6}\.\d{9}\.tar\.gz$/;
34
+
35
+ class PreconditionFailed extends Error {
36
+ constructor(currentChecksum) {
37
+ super('the stored archive has changed');
38
+ this.name = 'PreconditionFailed';
39
+ this.currentChecksum = currentChecksum;
40
+ }
41
+ }
42
+
43
+ class NotFound extends Error {
44
+ constructor(message) {
45
+ super(message);
46
+ this.name = 'NotFound';
47
+ }
48
+ }
49
+
50
+ /** Accept a 32-byte key as 64 hex characters or as base64. */
51
+ function parseKey(text) {
52
+ if (!text) return null;
53
+ const trimmed = String(text).trim();
54
+ const key = /^[0-9a-fA-F]{64}$/.test(trimmed)
55
+ ? Buffer.from(trimmed, 'hex')
56
+ : Buffer.from(trimmed, 'base64');
57
+ if (key.length !== 32) throw new Error('encryption key must be 32 bytes (64 hex characters, or base64)');
58
+ return key;
59
+ }
60
+
61
+ function versionName(date) {
62
+ const p = (n, w = 2) => String(n).padStart(w, '0');
63
+ return (
64
+ `${date.getUTCFullYear()}${p(date.getUTCMonth() + 1)}${p(date.getUTCDate())}` +
65
+ `T${p(date.getUTCHours())}${p(date.getUTCMinutes())}${p(date.getUTCSeconds())}` +
66
+ `.${p(date.getUTCMilliseconds(), 3)}000000.tar.gz`
67
+ );
68
+ }
69
+
70
+ function versionDate(name) {
71
+ const m = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})\.(\d{3})/.exec(name);
72
+ if (!m) return null;
73
+ const d = new Date(Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6], +m[7]));
74
+ return Number.isNaN(d.getTime()) ? null : d.toISOString();
75
+ }
76
+
77
+ class Storage {
78
+ /**
79
+ * @param {string} dataDir
80
+ * @param {Object} [opts]
81
+ * @param {Buffer|null} [opts.encryptionKey] 32-byte master key
82
+ * @param {number} [opts.versionRetention=5] snapshots kept per brain
83
+ */
84
+ constructor(dataDir, opts = {}) {
85
+ this.root = path.join(dataDir, 'brains');
86
+ this.masterKey = opts.encryptionKey || null;
87
+ this.versionRetention = opts.versionRetention == null ? 5 : opts.versionRetention;
88
+ this.locks = new Map();
89
+ fs.mkdirSync(this.root, { recursive: true });
90
+ }
91
+
92
+ // -- paths ---------------------------------------------------------------
93
+
94
+ userDir(userId) {
95
+ if (!USER_ID_RE.test(userId)) throw new NotFound('user not found');
96
+ return path.join(this.root, userId);
97
+ }
98
+
99
+ brainDir(userId, brainId) {
100
+ if (!UUID_RE.test(brainId)) throw new NotFound('brain not found');
101
+ return path.join(this.userDir(userId), brainId.toLowerCase());
102
+ }
103
+
104
+ // -- sealing -------------------------------------------------------------
105
+
106
+ userKey(userId) {
107
+ return Buffer.from(
108
+ crypto.hkdfSync('sha256', this.masterKey, Buffer.alloc(0), 'brain-store:' + userId, 32)
109
+ );
110
+ }
111
+
112
+ seal(userId, plaintext) {
113
+ if (!this.masterKey) return plaintext;
114
+ const nonce = crypto.randomBytes(NONCE_LEN);
115
+ const cipher = crypto.createCipheriv('aes-256-gcm', this.userKey(userId), nonce);
116
+ const body = Buffer.concat([cipher.update(plaintext), cipher.final()]);
117
+ return Buffer.concat([MAGIC, nonce, body, cipher.getAuthTag()]);
118
+ }
119
+
120
+ open(userId, stored) {
121
+ if (stored.length < MAGIC.length || !stored.subarray(0, MAGIC.length).equals(MAGIC)) return stored;
122
+ if (!this.masterKey) throw new Error('archive is encrypted but no encryption key is configured');
123
+ const nonce = stored.subarray(MAGIC.length, MAGIC.length + NONCE_LEN);
124
+ const tag = stored.subarray(stored.length - TAG_LEN);
125
+ const body = stored.subarray(MAGIC.length + NONCE_LEN, stored.length - TAG_LEN);
126
+ const decipher = crypto.createDecipheriv('aes-256-gcm', this.userKey(userId), nonce);
127
+ decipher.setAuthTag(tag);
128
+ return Buffer.concat([decipher.update(body), decipher.final()]);
129
+ }
130
+
131
+ // -- serialising writes --------------------------------------------------
132
+
133
+ /**
134
+ * Run `fn` with exclusive access to one brain. The precondition check and the
135
+ * swap must not interleave with another upload to the same brain, or two
136
+ * clients could both pass an `If-Match` against the same checksum. The lock is
137
+ * in-process: run one server process per data directory.
138
+ */
139
+ async withLock(key, fn) {
140
+ const previous = this.locks.get(key) || Promise.resolve();
141
+ let release;
142
+ const gate = new Promise((r) => { release = r; });
143
+ const tail = previous.then(() => gate);
144
+ this.locks.set(key, tail);
145
+ await previous;
146
+ try {
147
+ return await fn();
148
+ } finally {
149
+ release();
150
+ if (this.locks.get(key) === tail) this.locks.delete(key);
151
+ }
152
+ }
153
+
154
+ // -- brain records -------------------------------------------------------
155
+
156
+ writeAtomic(file, data, mode = 0o600) {
157
+ const tmp = file + '.' + crypto.randomBytes(6).toString('hex') + '.tmp';
158
+ fs.writeFileSync(tmp, data, { mode });
159
+ fs.renameSync(tmp, file);
160
+ }
161
+
162
+ readMeta(userId, brainId) {
163
+ try {
164
+ return JSON.parse(fs.readFileSync(path.join(this.brainDir(userId, brainId), 'meta.json'), 'utf8'));
165
+ } catch (err) {
166
+ if (err instanceof NotFound || err.code === 'ENOENT') return null;
167
+ throw err;
168
+ }
169
+ }
170
+
171
+ writeMeta(meta) {
172
+ this.writeAtomic(
173
+ path.join(this.brainDir(meta.user_id, meta.id), 'meta.json'),
174
+ JSON.stringify(meta, null, 2) + '\n'
175
+ );
176
+ }
177
+
178
+ listBrains(userId) {
179
+ let names;
180
+ try {
181
+ names = fs.readdirSync(this.userDir(userId));
182
+ } catch {
183
+ return [];
184
+ }
185
+ return names
186
+ .filter((n) => UUID_RE.test(n))
187
+ .map((n) => this.readMeta(userId, n))
188
+ .filter(Boolean)
189
+ .sort((a, b) => a.created_at.localeCompare(b.created_at));
190
+ }
191
+
192
+ createBrain(userId, name) {
193
+ const meta = {
194
+ id: crypto.randomUUID(),
195
+ user_id: userId,
196
+ name: String(name || 'default').slice(0, 100),
197
+ size_bytes: 0,
198
+ file_count: 0,
199
+ last_synced_at: null,
200
+ checksum: null,
201
+ created_at: new Date().toISOString(),
202
+ };
203
+ fs.mkdirSync(path.join(this.brainDir(userId, meta.id), 'versions'), { recursive: true, mode: 0o700 });
204
+ this.writeMeta(meta);
205
+ return meta;
206
+ }
207
+
208
+ deleteBrain(userId, brainId) {
209
+ const dir = this.brainDir(userId, brainId);
210
+ if (!fs.existsSync(path.join(dir, 'meta.json'))) return false;
211
+ fs.rmSync(dir, { recursive: true, force: true });
212
+ return true;
213
+ }
214
+
215
+ deleteUser(userId) {
216
+ fs.rmSync(this.userDir(userId), { recursive: true, force: true });
217
+ }
218
+
219
+ /** Bytes on disk for one user, across live archives and snapshots. */
220
+ userBytes(userId) {
221
+ let total = 0;
222
+ const walk = (dir) => {
223
+ let entries;
224
+ try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
225
+ for (const e of entries) {
226
+ const p = path.join(dir, e.name);
227
+ if (e.isDirectory()) walk(p);
228
+ else if (e.isFile()) total += fs.statSync(p).size;
229
+ }
230
+ };
231
+ walk(this.userDir(userId));
232
+ return total;
233
+ }
234
+
235
+ // -- archives ------------------------------------------------------------
236
+
237
+ readArchive(userId, brainId) {
238
+ const file = path.join(this.brainDir(userId, brainId), 'current.bin');
239
+ let stored;
240
+ try {
241
+ stored = fs.readFileSync(file);
242
+ } catch (err) {
243
+ if (err.code === 'ENOENT') throw new NotFound('brain archive not found');
244
+ throw err;
245
+ }
246
+ return this.open(userId, stored);
247
+ }
248
+
249
+ /**
250
+ * Replace a brain's archive.
251
+ *
252
+ * @param {Object} args
253
+ * @param {Buffer} args.archive plaintext tar.gz
254
+ * @param {number} args.fileCount
255
+ * @param {string[]|null} args.ifMatch acceptable current checksums, or ['*']
256
+ * @param {boolean} args.ifNoneMatchAny true for `If-None-Match: *`
257
+ * @param {(meta: Object) => void} [args.guard] throws to refuse; runs under the lock
258
+ */
259
+ commitArchive(userId, brainId, args) {
260
+ return this.withLock(userId + '/' + brainId, () => {
261
+ const meta = this.readMeta(userId, brainId);
262
+ if (!meta) throw new NotFound('brain not found');
263
+
264
+ const current = meta.checksum || null;
265
+ if (args.ifNoneMatchAny && current) throw new PreconditionFailed(current);
266
+ if (args.ifMatch) {
267
+ const ok = current && (args.ifMatch.includes('*') || args.ifMatch.includes(current));
268
+ if (!ok) throw new PreconditionFailed(current);
269
+ }
270
+ if (args.guard) args.guard(meta);
271
+
272
+ const dir = this.brainDir(userId, brainId);
273
+ const live = path.join(dir, 'current.bin');
274
+ this.snapshot(dir, live);
275
+
276
+ this.writeAtomic(live, this.seal(userId, args.archive));
277
+
278
+ meta.size_bytes = args.archive.length;
279
+ meta.file_count = args.fileCount;
280
+ meta.checksum = crypto.createHash('sha256').update(args.archive).digest('hex');
281
+ meta.last_synced_at = new Date().toISOString();
282
+ this.writeMeta(meta);
283
+ return meta;
284
+ });
285
+ }
286
+
287
+ /** Move the live archive into versions/ under a fresh timestamped name, then prune. */
288
+ snapshot(dir, live) {
289
+ if (!fs.existsSync(live)) return;
290
+ const versions = path.join(dir, 'versions');
291
+ fs.mkdirSync(versions, { recursive: true, mode: 0o700 });
292
+ let when = new Date();
293
+ let name = versionName(when);
294
+ while (fs.existsSync(path.join(versions, name))) {
295
+ when = new Date(when.getTime() + 1);
296
+ name = versionName(when);
297
+ }
298
+ fs.copyFileSync(live, path.join(versions, name));
299
+ const names = fs.readdirSync(versions).filter((n) => VERSION_RE.test(n)).sort();
300
+ while (names.length > this.versionRetention) {
301
+ fs.rmSync(path.join(versions, names.shift()), { force: true });
302
+ }
303
+ }
304
+
305
+ listVersions(userId, brainId) {
306
+ let names;
307
+ try {
308
+ names = fs.readdirSync(path.join(this.brainDir(userId, brainId), 'versions'));
309
+ } catch {
310
+ return [];
311
+ }
312
+ return names
313
+ .filter((n) => VERSION_RE.test(n))
314
+ .sort()
315
+ .reverse()
316
+ .map((version) => ({ version, date: versionDate(version) || undefined }));
317
+ }
318
+
319
+ readVersion(userId, brainId, version) {
320
+ if (!VERSION_RE.test(version)) throw new NotFound('version not found');
321
+ const file = path.join(this.brainDir(userId, brainId), 'versions', version);
322
+ let stored;
323
+ try {
324
+ stored = fs.readFileSync(file);
325
+ } catch (err) {
326
+ if (err.code === 'ENOENT') throw new NotFound('version not found');
327
+ throw err;
328
+ }
329
+ return this.open(userId, stored);
330
+ }
331
+ }
332
+
333
+ module.exports = { Storage, PreconditionFailed, NotFound, parseKey, UUID_RE, VERSION_RE };
@@ -0,0 +1,150 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * brain-store — archive inspection
5
+ *
6
+ * The store treats a brain as an opaque gzip-compressed tar archive. It never
7
+ * extracts one to disk. The only thing it needs from the contents is the number
8
+ * of regular files, which drives the empty-push guard and the `file_count`
9
+ * reported to clients.
10
+ *
11
+ * The archive is inflated as a stream and only tar headers are examined, so a
12
+ * hostile upload cannot exhaust memory: inflated size and entry count are both
13
+ * bounded.
14
+ */
15
+
16
+ const zlib = require('zlib');
17
+
18
+ const BLOCK = 512;
19
+ const DEFAULT_MAX_INFLATED = 1024 * 1024 * 1024; // 1 GiB
20
+ const DEFAULT_MAX_ENTRIES = 500000;
21
+
22
+ class ArchiveError extends Error {
23
+ constructor(message) {
24
+ super(message);
25
+ this.name = 'ArchiveError';
26
+ }
27
+ }
28
+
29
+ function isGzip(buf) {
30
+ return buf.length >= 3 && buf[0] === 0x1f && buf[1] === 0x8b && buf[2] === 0x08;
31
+ }
32
+
33
+ /** Parse a tar numeric field: octal text, or GNU base-256 when the high bit is set. */
34
+ function parseNumber(field) {
35
+ if (field[0] & 0x80) {
36
+ let n = 0;
37
+ for (let i = 1; i < field.length; i++) n = n * 256 + field[i];
38
+ return n;
39
+ }
40
+ const text = field.toString('latin1').replace(/\0.*$/, '').trim();
41
+ if (text === '') return 0;
42
+ if (!/^[0-7]+$/.test(text)) return NaN;
43
+ return parseInt(text, 8);
44
+ }
45
+
46
+ /** A tar header's checksum is the byte sum of the block with the checksum field read as spaces. */
47
+ function headerChecksumOk(block) {
48
+ const stored = parseNumber(block.subarray(148, 156));
49
+ if (!Number.isFinite(stored)) return false;
50
+ let sum = 0;
51
+ for (let i = 0; i < BLOCK; i++) sum += (i >= 148 && i < 156) ? 0x20 : block[i];
52
+ return sum === stored;
53
+ }
54
+
55
+ function isZeroBlock(block) {
56
+ for (let i = 0; i < BLOCK; i++) if (block[i] !== 0) return false;
57
+ return true;
58
+ }
59
+
60
+ /**
61
+ * Count the regular files in a gzip-compressed tar archive.
62
+ *
63
+ * @param {Buffer} gz
64
+ * @param {Object} [opts]
65
+ * @param {number} [opts.maxInflatedBytes]
66
+ * @param {number} [opts.maxEntries]
67
+ * @returns {Promise<{fileCount: number}>}
68
+ */
69
+ function inspectArchive(gz, opts = {}) {
70
+ const maxInflated = opts.maxInflatedBytes || DEFAULT_MAX_INFLATED;
71
+ const maxEntries = opts.maxEntries || DEFAULT_MAX_ENTRIES;
72
+
73
+ return new Promise((resolve, reject) => {
74
+ if (!Buffer.isBuffer(gz) || !isGzip(gz)) {
75
+ return reject(new ArchiveError('not a gzip archive'));
76
+ }
77
+
78
+ const gunzip = zlib.createGunzip();
79
+ const header = Buffer.alloc(BLOCK);
80
+ let headerFill = 0;
81
+ let skip = 0;
82
+ let inflated = 0;
83
+ let entries = 0;
84
+ let fileCount = 0;
85
+ let sawHeader = false;
86
+ let ended = false;
87
+ let settled = false;
88
+
89
+ const fail = (err) => {
90
+ if (settled) return;
91
+ settled = true;
92
+ gunzip.destroy();
93
+ reject(err instanceof ArchiveError ? err : new ArchiveError(err.message));
94
+ };
95
+
96
+ gunzip.on('data', (chunk) => {
97
+ if (settled) return;
98
+ inflated += chunk.length;
99
+ if (inflated > maxInflated) return fail(new ArchiveError('archive inflates beyond the allowed size'));
100
+
101
+ let off = 0;
102
+ while (off < chunk.length && !ended) {
103
+ if (skip > 0) {
104
+ const n = Math.min(skip, chunk.length - off);
105
+ skip -= n;
106
+ off += n;
107
+ continue;
108
+ }
109
+ const n = Math.min(BLOCK - headerFill, chunk.length - off);
110
+ chunk.copy(header, headerFill, off, off + n);
111
+ headerFill += n;
112
+ off += n;
113
+ if (headerFill < BLOCK) break;
114
+ headerFill = 0;
115
+
116
+ if (isZeroBlock(header)) {
117
+ // End-of-archive marker. Anything after it is padding.
118
+ ended = true;
119
+ break;
120
+ }
121
+ if (!headerChecksumOk(header)) return fail(new ArchiveError('not a tar archive'));
122
+ sawHeader = true;
123
+
124
+ if (++entries > maxEntries) return fail(new ArchiveError('archive has too many entries'));
125
+
126
+ const size = parseNumber(header.subarray(124, 136));
127
+ if (!Number.isFinite(size) || size < 0) return fail(new ArchiveError('corrupt tar header'));
128
+
129
+ const type = header[156];
130
+ if (type === 0x30 /* '0' */ || type === 0x00) fileCount++;
131
+
132
+ skip = Math.ceil(size / BLOCK) * BLOCK;
133
+ }
134
+ });
135
+
136
+ gunzip.on('error', (err) => fail(new ArchiveError('corrupt gzip stream: ' + err.message)));
137
+
138
+ gunzip.on('end', () => {
139
+ if (settled) return;
140
+ if (!ended && (skip > 0 || headerFill > 0)) return fail(new ArchiveError('truncated tar archive'));
141
+ if (!sawHeader && inflated > 0 && !ended) return fail(new ArchiveError('not a tar archive'));
142
+ settled = true;
143
+ resolve({ fileCount });
144
+ });
145
+
146
+ gunzip.end(gz);
147
+ });
148
+ }
149
+
150
+ module.exports = { inspectArchive, ArchiveError, isGzip };