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.
@@ -0,0 +1,38 @@
1
+ # The MCP connector, configured for a self-hosted store.
2
+ # Build from the repository root:
3
+ # docker build -f store/deploy/connector.Dockerfile -t brain-connector .
4
+ #
5
+ # The connector runs the repository's own command-line tools (bin/, src/) against
6
+ # each user's working copy, so the image carries those alongside connector/.
7
+ FROM node:22-alpine
8
+
9
+ WORKDIR /app
10
+ COPY package.json ./
11
+ COPY bin/ ./bin/
12
+ COPY src/ ./src/
13
+ # The OpenID Connect token verifier is shared with the store.
14
+ COPY store/lib/ ./store/lib/
15
+
16
+ WORKDIR /app/connector
17
+ COPY connector/package.json connector/package-lock.json ./
18
+ # tsx runs the TypeScript sources directly and is a dev dependency.
19
+ RUN npm ci --include=dev && npm cache clean --force
20
+ COPY connector/tsconfig.json ./
21
+ COPY connector/src/ ./src/
22
+
23
+ RUN mkdir -p /var/lib/brain-connector && chown node:node /var/lib/brain-connector
24
+ USER node
25
+
26
+ ENV NODE_ENV=production \
27
+ PORT=8788 \
28
+ CONNECTOR_BIND_HOST=0.0.0.0 \
29
+ CONNECTOR_IDP=static \
30
+ CONNECTOR_BRAIN_BASE=/run/brain-connector \
31
+ CONNECTOR_STATE_DIR=/var/lib/brain-connector
32
+
33
+ EXPOSE 8788
34
+
35
+ HEALTHCHECK --interval=30s --timeout=3s --start-period=10s \
36
+ CMD wget -qO- http://127.0.0.1:8788/health >/dev/null || exit 1
37
+
38
+ CMD ["node", "--import", "tsx", "src/server.ts"]
@@ -0,0 +1,83 @@
1
+ # Self-hosted Brain: a store, a stateless MCP connector in front of it, and Caddy
2
+ # for TLS. See ../SELF-HOSTING.md.
3
+ #
4
+ # cp env.example .env # then fill it in
5
+ # docker compose up -d --build
6
+ # docker compose exec store node store/bin/brain-store.js user add <name>
7
+
8
+ name: brain
9
+
10
+ services:
11
+ store:
12
+ build:
13
+ context: ../..
14
+ dockerfile: store/Dockerfile
15
+ restart: unless-stopped
16
+ environment:
17
+ STORE_ENCRYPTION_KEY: ${STORE_ENCRYPTION_KEY:?set STORE_ENCRYPTION_KEY in .env}
18
+ STORE_MAX_UPLOAD_MB: ${STORE_MAX_UPLOAD_MB:-50}
19
+ STORE_MAX_USER_MB: ${STORE_MAX_USER_MB:-0}
20
+ STORE_TRUST_PROXY: "1"
21
+ volumes:
22
+ - store-data:/data
23
+ read_only: true
24
+ tmpfs:
25
+ - /tmp
26
+ cap_drop: [ALL]
27
+ security_opt:
28
+ - no-new-privileges:true
29
+ networks: [internal]
30
+
31
+ connector:
32
+ build:
33
+ context: ../..
34
+ dockerfile: store/deploy/connector.Dockerfile
35
+ restart: unless-stopped
36
+ depends_on:
37
+ store:
38
+ condition: service_healthy
39
+ environment:
40
+ CONNECTOR_IDP: static
41
+ # The connector talks to the store over the private network, never the internet.
42
+ BRAIN_CLOUD_API_URL: http://store:8787
43
+ CONNECTOR_STATE_KEY: ${CONNECTOR_STATE_KEY:?set CONNECTOR_STATE_KEY in .env}
44
+ # Caddy is another container on the private network, not loopback.
45
+ CONNECTOR_TRUST_PROXY: uniquelocal
46
+ volumes:
47
+ - connector-state:/var/lib/brain-connector
48
+ read_only: true
49
+ tmpfs:
50
+ - /tmp
51
+ # Users' working copies are plaintext. Keep them in memory only.
52
+ - /run/brain-connector:uid=1000,gid=1000,mode=0700
53
+ - /home/node/.npm
54
+ cap_drop: [ALL]
55
+ security_opt:
56
+ - no-new-privileges:true
57
+ networks: [internal]
58
+
59
+ caddy:
60
+ image: caddy:2-alpine
61
+ restart: unless-stopped
62
+ depends_on: [store, connector]
63
+ ports:
64
+ - "80:80"
65
+ - "443:443"
66
+ - "443:443/udp"
67
+ environment:
68
+ STORE_DOMAIN: ${STORE_DOMAIN:?set STORE_DOMAIN in .env}
69
+ MCP_DOMAIN: ${MCP_DOMAIN:?set MCP_DOMAIN in .env}
70
+ volumes:
71
+ - ./Caddyfile:/etc/caddy/Caddyfile:ro
72
+ - caddy-data:/data
73
+ - caddy-config:/config
74
+ networks: [internal]
75
+
76
+ volumes:
77
+ store-data:
78
+ connector-state:
79
+ caddy-data:
80
+ caddy-config:
81
+
82
+ networks:
83
+ internal:
@@ -0,0 +1,19 @@
1
+ # Copy to .env and fill in: cp env.example .env
2
+ # Never commit the real file.
3
+
4
+ # Two DNS names that point at this host. Caddy gets certificates for them.
5
+ STORE_DOMAIN=store.example.com
6
+ MCP_DOMAIN=mcp.example.com
7
+
8
+ # Encrypts archives at rest. Generate with:
9
+ # docker compose run --rm store keygen
10
+ # Keep a copy somewhere safe: without it the stored archives cannot be read.
11
+ STORE_ENCRYPTION_KEY=
12
+
13
+ # Encrypts the connector's saved logins (so users are not logged out on restart).
14
+ # Generate with: openssl rand -hex 32
15
+ CONNECTOR_STATE_KEY=
16
+
17
+ # Optional limits.
18
+ STORE_MAX_UPLOAD_MB=50
19
+ STORE_MAX_USER_MB=0
@@ -0,0 +1,174 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * brain-store — users and static bearer tokens
5
+ *
6
+ * Users live in `<dataDir>/users.json`. Tokens are 256 bits of randomness, shown
7
+ * once at creation and stored only as a SHA-256 hash. A fast hash is appropriate
8
+ * here because the input is high-entropy random data, not a human password.
9
+ *
10
+ * The file is re-read when it changes on disk, so `brain-store user add` takes
11
+ * effect on a running server without a restart.
12
+ */
13
+
14
+ const crypto = require('crypto');
15
+ const fs = require('fs');
16
+ const path = require('path');
17
+
18
+ const USERS_FILE = 'users.json';
19
+ const TOKEN_PREFIX = 'bst_';
20
+ const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
21
+
22
+ function sha256Hex(text) {
23
+ return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
24
+ }
25
+
26
+ function newToken() {
27
+ return TOKEN_PREFIX + crypto.randomBytes(32).toString('base64url');
28
+ }
29
+
30
+ function newUserId() {
31
+ return 'usr_' + crypto.randomBytes(9).toString('base64url');
32
+ }
33
+
34
+ class UserStore {
35
+ constructor(dataDir) {
36
+ this.file = path.join(dataDir, USERS_FILE);
37
+ this.users = [];
38
+ this.loadedSig = '';
39
+ fs.mkdirSync(dataDir, { recursive: true });
40
+ }
41
+
42
+ /** Re-read users.json if it changed since the last load. */
43
+ refresh() {
44
+ let stat;
45
+ try {
46
+ stat = fs.statSync(this.file);
47
+ } catch {
48
+ this.users = [];
49
+ this.loadedSig = '';
50
+ return;
51
+ }
52
+ const sig = stat.mtimeMs + ':' + stat.size;
53
+ if (sig === this.loadedSig) return;
54
+ const parsed = JSON.parse(fs.readFileSync(this.file, 'utf8'));
55
+ this.users = Array.isArray(parsed.users) ? parsed.users : [];
56
+ this.loadedSig = sig;
57
+ }
58
+
59
+ save() {
60
+ const tmp = this.file + '.' + crypto.randomBytes(6).toString('hex') + '.tmp';
61
+ fs.writeFileSync(tmp, JSON.stringify({ users: this.users }, null, 2) + '\n', { mode: 0o600 });
62
+ fs.renameSync(tmp, this.file);
63
+ const stat = fs.statSync(this.file);
64
+ this.loadedSig = stat.mtimeMs + ':' + stat.size;
65
+ }
66
+
67
+ list() {
68
+ this.refresh();
69
+ return this.users.map(publicUser);
70
+ }
71
+
72
+ find(nameOrId) {
73
+ this.refresh();
74
+ return this.users.find((u) => u.id === nameOrId || u.name === nameOrId) || null;
75
+ }
76
+
77
+ /**
78
+ * Create a user. Returns the public record and the token, which is never
79
+ * stored and cannot be shown again.
80
+ */
81
+ add(name, email) {
82
+ this.refresh();
83
+ if (!NAME_RE.test(name || '')) {
84
+ throw new Error('user name must be 1-64 characters: letters, digits, dot, dash, underscore');
85
+ }
86
+ if (this.users.some((u) => u.name === name)) throw new Error(`user "${name}" already exists`);
87
+ const token = newToken();
88
+ const user = {
89
+ id: newUserId(),
90
+ name,
91
+ email: email || '',
92
+ token_sha256: sha256Hex(token),
93
+ created_at: new Date().toISOString(),
94
+ };
95
+ this.users.push(user);
96
+ this.save();
97
+ return { user: publicUser(user), token };
98
+ }
99
+
100
+ /** Replace a user's token. The old token stops working immediately. */
101
+ rotate(nameOrId) {
102
+ const user = this.find(nameOrId);
103
+ if (!user) throw new Error(`no such user: ${nameOrId}`);
104
+ const token = newToken();
105
+ user.token_sha256 = sha256Hex(token);
106
+ user.rotated_at = new Date().toISOString();
107
+ this.save();
108
+ return { user: publicUser(user), token };
109
+ }
110
+
111
+ /**
112
+ * Find or create the user behind a verified OpenID Connect identity. The id is
113
+ * derived from issuer and subject, so the same person always maps to the same
114
+ * user, and two issuers can never collide. OIDC users have no static token
115
+ * unless the operator issues one with `user rotate`.
116
+ *
117
+ * @returns {{user: Object, created: boolean}}
118
+ */
119
+ upsertOidc(issuer, claims) {
120
+ this.refresh();
121
+ const id = 'oidc_' + crypto.createHash('sha256')
122
+ .update(issuer + '|' + claims.sub, 'utf8').digest('base64url').slice(0, 16);
123
+ const email = typeof claims.email === 'string' ? claims.email : '';
124
+ let user = this.users.find((u) => u.id === id);
125
+ if (user) {
126
+ if (email && user.email !== email) {
127
+ user.email = email;
128
+ this.save();
129
+ }
130
+ return { user: publicUser(user), created: false };
131
+ }
132
+ user = {
133
+ id,
134
+ name: id,
135
+ email,
136
+ oidc: { iss: issuer, sub: claims.sub },
137
+ created_at: new Date().toISOString(),
138
+ };
139
+ this.users.push(user);
140
+ this.save();
141
+ return { user: publicUser(user), created: true };
142
+ }
143
+
144
+ remove(nameOrId) {
145
+ const user = this.find(nameOrId);
146
+ if (!user) throw new Error(`no such user: ${nameOrId}`);
147
+ this.users = this.users.filter((u) => u.id !== user.id);
148
+ this.save();
149
+ return publicUser(user);
150
+ }
151
+
152
+ /**
153
+ * Resolve a bearer token to a user. Every stored hash is compared in constant
154
+ * time, and the loop never exits early, so timing reveals nothing about which
155
+ * user (if any) matched.
156
+ */
157
+ authenticate(token) {
158
+ if (typeof token !== 'string' || !token.startsWith(TOKEN_PREFIX) || token.length > 200) return null;
159
+ this.refresh();
160
+ const presented = Buffer.from(sha256Hex(token), 'hex');
161
+ let match = null;
162
+ for (const user of this.users) {
163
+ const stored = Buffer.from(String(user.token_sha256 || ''), 'hex');
164
+ if (stored.length === presented.length && crypto.timingSafeEqual(stored, presented)) match = user;
165
+ }
166
+ return match ? publicUser(match) : null;
167
+ }
168
+ }
169
+
170
+ function publicUser(user) {
171
+ return { id: user.id, name: user.name, email: user.email || '', created_at: user.created_at };
172
+ }
173
+
174
+ module.exports = { UserStore, TOKEN_PREFIX };
@@ -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 };