blockflow-bridge 0.0.0-stage → 1.0.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/LICENSE +21 -0
- package/README.md +49 -2
- package/cli.d.mts +1 -0
- package/cli.mjs +127 -0
- package/client.d.mts +23 -0
- package/client.mjs +158 -0
- package/framing.d.mts +17 -0
- package/framing.mjs +132 -0
- package/host.d.mts +13 -0
- package/host.mjs +377 -0
- package/index.d.mts +6 -0
- package/index.mjs +25 -0
- package/install.d.mts +31 -0
- package/install.mjs +309 -0
- package/package.json +37 -4
- package/paths.d.mts +7 -0
- package/paths.mjs +95 -0
- package/protocol.d.mts +22 -0
- package/protocol.mjs +24 -0
package/install.mjs
ADDED
|
@@ -0,0 +1,309 @@
|
|
|
1
|
+
// Installs the native messaging host: a launcher script that runs host.mjs with this Node, and a host
|
|
2
|
+
// manifest (`dev.akibh.blockflow.json`) where each browser looks for it.
|
|
3
|
+
//
|
|
4
|
+
// Linux/macOS: manifest files in each browser's NativeMessagingHosts folder.
|
|
5
|
+
// Windows: manifest files next to the launcher, plus an HKCU registry key per browser pointing at them.
|
|
6
|
+
//
|
|
7
|
+
// Chromium-family manifests list `allowed_origins` (chrome-extension://<id>/); Firefox's lists
|
|
8
|
+
// `allowed_extensions` (the gecko id from wxt.config.ts). `dirs` replaces the browser folders (CLI, e2e:
|
|
9
|
+
// <profile>/NativeMessagingHosts, which Chromium also reads).
|
|
10
|
+
import { createHash } from 'node:crypto';
|
|
11
|
+
import { execFileSync } from 'node:child_process';
|
|
12
|
+
import { chmodSync, existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
|
|
13
|
+
import os from 'node:os';
|
|
14
|
+
import path from 'node:path';
|
|
15
|
+
import { fileURLToPath } from 'node:url';
|
|
16
|
+
import { NATIVE_HOST_NAME } from './protocol.mjs';
|
|
17
|
+
|
|
18
|
+
export const FIREFOX_EXTENSION_ID = 'blockflow@akibh-dev';
|
|
19
|
+
export const MANIFEST_FILE = `${NATIVE_HOST_NAME}.json`;
|
|
20
|
+
export const CHROMIUM_BROWSERS = Object.freeze(['chrome', 'chromium', 'brave', 'brave-origin', 'edge']);
|
|
21
|
+
export const BROWSERS = Object.freeze([...CHROMIUM_BROWSERS, 'firefox']);
|
|
22
|
+
const DESCRIPTION = 'BlockFlow bridge: lets local programs (MCP server, CLI) drive the BlockFlow extension';
|
|
23
|
+
const HOST_SCRIPT = fileURLToPath(new URL('./host.mjs', import.meta.url));
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* @typedef {'chrome' | 'chromium' | 'brave' | 'brave-origin' | 'edge' | 'firefox'} Browser
|
|
27
|
+
* @typedef {string | { dir: string, kind?: 'chromium' | 'firefox' }} DirTarget
|
|
28
|
+
* @typedef {{ platform?: NodeJS.Platform, home?: string, localAppData?: string }} Where
|
|
29
|
+
* @typedef {{
|
|
30
|
+
* extensionIds?: string[],
|
|
31
|
+
* firefox?: boolean,
|
|
32
|
+
* browsers?: Browser[],
|
|
33
|
+
* dirs?: DirTarget[],
|
|
34
|
+
* hostScript?: string,
|
|
35
|
+
* launcherDir?: string,
|
|
36
|
+
* nodePath?: string,
|
|
37
|
+
* exec?: (file: string, args: string[]) => void,
|
|
38
|
+
* } & Where} InstallOptions
|
|
39
|
+
*/
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* The id Chromium gives an unpacked extension loaded from `absPath`: SHA-256 of the absolute path (bytes of
|
|
43
|
+
* the platform's path string: UTF-8 on Linux/macOS, UTF-16LE with an upper-case drive letter on Windows),
|
|
44
|
+
* first 32 hex digits, each mapped 0-f -> a-p. Symlinks are resolved first, as Chromium does.
|
|
45
|
+
* @param {string} absPath
|
|
46
|
+
* @param {{ platform?: NodeJS.Platform }} [options]
|
|
47
|
+
*/
|
|
48
|
+
export function chromiumExtensionId(absPath, options = {}) {
|
|
49
|
+
const platform = options.platform ?? process.platform;
|
|
50
|
+
let resolved = platform === 'win32' ? path.win32.resolve(absPath) : path.posix.resolve(absPath);
|
|
51
|
+
if (platform === process.platform) {
|
|
52
|
+
try {
|
|
53
|
+
resolved = realpathSync(resolved);
|
|
54
|
+
} catch {}
|
|
55
|
+
}
|
|
56
|
+
let bytes;
|
|
57
|
+
if (platform === 'win32') {
|
|
58
|
+
if (/^[a-z]:/.test(resolved)) resolved = resolved[0].toUpperCase() + resolved.slice(1);
|
|
59
|
+
bytes = Buffer.from(resolved, 'utf16le');
|
|
60
|
+
} else {
|
|
61
|
+
bytes = Buffer.from(resolved, 'utf8');
|
|
62
|
+
}
|
|
63
|
+
const hex = createHash('sha256').update(bytes).digest('hex').slice(0, 32);
|
|
64
|
+
return [...hex].map((digit) => String.fromCharCode(97 + parseInt(digit, 16))).join('');
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** @param {Where} where */
|
|
68
|
+
function homeOf(where) {
|
|
69
|
+
return where.home ?? os.homedir();
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Per-browser manifest folders (Linux, macOS) or registry keys (Windows).
|
|
74
|
+
* @param {Browser} browser
|
|
75
|
+
* @param {Where} [where]
|
|
76
|
+
* @returns {{ dir?: string, registryKey?: string }}
|
|
77
|
+
*/
|
|
78
|
+
export function browserTarget(browser, where = {}) {
|
|
79
|
+
const platform = where.platform ?? process.platform;
|
|
80
|
+
const home = homeOf(where);
|
|
81
|
+
if (platform === 'win32') {
|
|
82
|
+
const keys = {
|
|
83
|
+
chrome: 'HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts',
|
|
84
|
+
chromium: 'HKCU\\Software\\Chromium\\NativeMessagingHosts',
|
|
85
|
+
brave: 'HKCU\\Software\\BraveSoftware\\Brave-Browser\\NativeMessagingHosts',
|
|
86
|
+
'brave-origin': 'HKCU\\Software\\BraveSoftware\\Brave-Origin\\NativeMessagingHosts',
|
|
87
|
+
edge: 'HKCU\\Software\\Microsoft\\Edge\\NativeMessagingHosts',
|
|
88
|
+
firefox: 'HKCU\\Software\\Mozilla\\NativeMessagingHosts',
|
|
89
|
+
};
|
|
90
|
+
return { registryKey: `${keys[browser]}\\${NATIVE_HOST_NAME}` };
|
|
91
|
+
}
|
|
92
|
+
const join = path.posix.join;
|
|
93
|
+
if (platform === 'darwin') {
|
|
94
|
+
const support = join(home, 'Library', 'Application Support');
|
|
95
|
+
const dirs = {
|
|
96
|
+
chrome: join(support, 'Google', 'Chrome', 'NativeMessagingHosts'),
|
|
97
|
+
chromium: join(support, 'Chromium', 'NativeMessagingHosts'),
|
|
98
|
+
brave: join(support, 'BraveSoftware', 'Brave-Browser', 'NativeMessagingHosts'),
|
|
99
|
+
'brave-origin': join(support, 'BraveSoftware', 'Brave-Origin', 'NativeMessagingHosts'),
|
|
100
|
+
edge: join(support, 'Microsoft Edge', 'NativeMessagingHosts'),
|
|
101
|
+
firefox: join(support, 'Mozilla', 'NativeMessagingHosts'),
|
|
102
|
+
};
|
|
103
|
+
return { dir: dirs[browser] };
|
|
104
|
+
}
|
|
105
|
+
const config = join(home, '.config');
|
|
106
|
+
const dirs = {
|
|
107
|
+
chrome: join(config, 'google-chrome', 'NativeMessagingHosts'),
|
|
108
|
+
chromium: join(config, 'chromium', 'NativeMessagingHosts'),
|
|
109
|
+
brave: join(config, 'BraveSoftware', 'Brave-Browser', 'NativeMessagingHosts'),
|
|
110
|
+
'brave-origin': join(config, 'BraveSoftware', 'Brave-Origin', 'NativeMessagingHosts'),
|
|
111
|
+
edge: join(config, 'microsoft-edge', 'NativeMessagingHosts'),
|
|
112
|
+
firefox: join(home, '.mozilla', 'native-messaging-hosts'),
|
|
113
|
+
};
|
|
114
|
+
return { dir: dirs[browser] };
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Manifest folders for a throwaway browser (CLI, e2e) on Linux/macOS: `<profile>/NativeMessagingHosts`,
|
|
119
|
+
* which Chromium reads, plus every Chromium-family default folder under `home`, because some builds
|
|
120
|
+
* (Brave, verified with Brave Origin on Linux) ignore `--user-data-dir` here and only read the default folder.
|
|
121
|
+
* Start the browser with `HOME=home` so nothing is written to the real home folder.
|
|
122
|
+
* @param {string} profile @param {string} home @param {Where} [where]
|
|
123
|
+
* @returns {string[]}
|
|
124
|
+
*/
|
|
125
|
+
export function isolatedHostDirs(profile, home, where = {}) {
|
|
126
|
+
const defaults = CHROMIUM_BROWSERS.map((browser) => browserTarget(browser, { ...where, home }).dir).filter((dir) => typeof dir === 'string');
|
|
127
|
+
return [path.join(profile, 'NativeMessagingHosts'), ...defaults];
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Where the launcher (and, on Windows, the manifests) go by default.
|
|
132
|
+
* @param {Where} [where]
|
|
133
|
+
*/
|
|
134
|
+
export function defaultLauncherDir(where = {}) {
|
|
135
|
+
const platform = where.platform ?? process.platform;
|
|
136
|
+
const home = homeOf(where);
|
|
137
|
+
if (platform === 'win32') return path.win32.join(where.localAppData ?? process.env.LOCALAPPDATA ?? path.win32.join(home, 'AppData', 'Local'), 'BlockFlow');
|
|
138
|
+
if (platform === 'darwin') return path.posix.join(home, 'Library', 'Application Support', 'BlockFlow');
|
|
139
|
+
return path.posix.join(home, '.config', 'blockflow', 'bridge');
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** @param {NodeJS.Platform} platform @param {string} dir */
|
|
143
|
+
export function launcherPath(platform, dir) {
|
|
144
|
+
return platform === 'win32' ? path.win32.join(dir, 'blockflow-bridge-host.cmd') : path.posix.join(dir, 'blockflow-bridge-host');
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* The launcher text: runs host.mjs with this Node (the browser starts hosts with a minimal PATH, so the
|
|
149
|
+
* absolute `process.execPath` is written in).
|
|
150
|
+
* @param {{ platform?: NodeJS.Platform, nodePath?: string, hostScript?: string }} [options]
|
|
151
|
+
*/
|
|
152
|
+
export function launcherScript(options = {}) {
|
|
153
|
+
const platform = options.platform ?? process.platform;
|
|
154
|
+
const node = options.nodePath ?? process.execPath;
|
|
155
|
+
const script = options.hostScript ?? HOST_SCRIPT;
|
|
156
|
+
if (platform === 'win32') return `@echo off\r\n"${node}" "${script}" %*\r\n`;
|
|
157
|
+
const quote = (/** @type {string} */ text) => `'${text.replace(/'/g, `'\\''`)}'`;
|
|
158
|
+
return `#!/bin/sh\n# BlockFlow native messaging host (written by blockflow-bridge install)\nexec ${quote(node)} ${quote(script)} "$@"\n`;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Manifest content for one browser family.
|
|
163
|
+
* @param {'chromium' | 'firefox'} kind @param {string} launcher @param {string[]} [extensionIds]
|
|
164
|
+
*/
|
|
165
|
+
export function hostManifest(kind, launcher, extensionIds = []) {
|
|
166
|
+
const base = { name: NATIVE_HOST_NAME, description: DESCRIPTION, path: launcher, type: 'stdio' };
|
|
167
|
+
if (kind === 'firefox') return { ...base, allowed_extensions: [FIREFOX_EXTENSION_ID] };
|
|
168
|
+
return { ...base, allowed_origins: extensionIds.map((id) => `chrome-extension://${id}/`) };
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* `reg` arguments that register a manifest for one browser (Windows).
|
|
173
|
+
* @param {string} registryKey @param {string} manifestPath
|
|
174
|
+
*/
|
|
175
|
+
export function registryAddArgs(registryKey, manifestPath) {
|
|
176
|
+
return ['add', registryKey, '/ve', '/t', 'REG_SZ', '/d', manifestPath, '/f'];
|
|
177
|
+
}
|
|
178
|
+
/** @param {string} registryKey */
|
|
179
|
+
export function registryDeleteArgs(registryKey) {
|
|
180
|
+
return ['delete', registryKey, '/f'];
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/** @param {InstallOptions} options @returns {Browser[]} */
|
|
184
|
+
function selectedBrowsers(options) {
|
|
185
|
+
if (options.browsers?.length) return options.browsers;
|
|
186
|
+
const chromium = options.extensionIds?.length ? [...CHROMIUM_BROWSERS] : [];
|
|
187
|
+
return /** @type {Browser[]} */ ([...chromium, ...(options.firefox ? ['firefox'] : [])]);
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** @param {string} id */
|
|
191
|
+
function checkId(id) {
|
|
192
|
+
if (!/^[a-p]{32}$/.test(id)) throw new Error(`"${id}" is not a Chromium extension id (32 letters a-p; see BlockFlow Settings)`);
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/**
|
|
196
|
+
* Writes the launcher and the manifests. Returns what it wrote.
|
|
197
|
+
* @param {InstallOptions} options
|
|
198
|
+
* @returns {{ launcher: string, manifests: string[], registry: { key: string, manifest: string }[] }}
|
|
199
|
+
*/
|
|
200
|
+
export function installHost(options) {
|
|
201
|
+
const platform = options.platform ?? process.platform;
|
|
202
|
+
const extensionIds = options.extensionIds ?? [];
|
|
203
|
+
extensionIds.forEach(checkId);
|
|
204
|
+
/** @type {{ dir: string, kind: 'chromium' | 'firefox', registryKey?: string, file: string }[]} */
|
|
205
|
+
const targets = [];
|
|
206
|
+
if (options.dirs?.length) {
|
|
207
|
+
for (const target of options.dirs) {
|
|
208
|
+
const { dir, kind = 'chromium' } = typeof target === 'string' ? { dir: target } : target;
|
|
209
|
+
targets.push({ dir, kind, file: MANIFEST_FILE });
|
|
210
|
+
}
|
|
211
|
+
} else {
|
|
212
|
+
const launcherDir = options.launcherDir ?? defaultLauncherDir(options);
|
|
213
|
+
for (const browser of selectedBrowsers(options)) {
|
|
214
|
+
const kind = browser === 'firefox' ? 'firefox' : 'chromium';
|
|
215
|
+
const { dir, registryKey } = browserTarget(browser, options);
|
|
216
|
+
if (registryKey) targets.push({ dir: launcherDir, kind, registryKey, file: kind === 'firefox' ? `${NATIVE_HOST_NAME}.firefox.json` : MANIFEST_FILE });
|
|
217
|
+
else if (dir) targets.push({ dir, kind, file: MANIFEST_FILE });
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
if (!targets.length) throw new Error('Nothing to install: give --extension-id <id> (Chrome, Chromium, Brave, Edge) and/or --browser firefox');
|
|
221
|
+
if (targets.some((target) => target.kind === 'chromium') && !extensionIds.length) {
|
|
222
|
+
throw new Error('Chromium-family browsers need the extension id: --extension-id <id> (shown in BlockFlow Settings)');
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
const join = platform === 'win32' ? path.win32.join : path.posix.join;
|
|
226
|
+
const launcherDir = options.launcherDir ?? (options.dirs?.length ? targets[0].dir : defaultLauncherDir(options));
|
|
227
|
+
const launcher = launcherPath(platform, launcherDir);
|
|
228
|
+
mkdirSync(launcherDir, { recursive: true });
|
|
229
|
+
writeFileSync(launcher, launcherScript({ platform, nodePath: options.nodePath, hostScript: options.hostScript }), { mode: 0o755 });
|
|
230
|
+
if (platform !== 'win32') chmodSync(launcher, 0o755);
|
|
231
|
+
|
|
232
|
+
const manifests = [];
|
|
233
|
+
const registry = [];
|
|
234
|
+
const exec = options.exec ?? ((file, args) => void execFileSync(file, args, { stdio: 'ignore' }));
|
|
235
|
+
for (const target of targets) {
|
|
236
|
+
mkdirSync(target.dir, { recursive: true });
|
|
237
|
+
const file = join(target.dir, target.file);
|
|
238
|
+
writeFileSync(file, `${JSON.stringify(hostManifest(target.kind, launcher, extensionIds), null, 2)}\n`);
|
|
239
|
+
manifests.push(file);
|
|
240
|
+
if (target.registryKey) {
|
|
241
|
+
exec('reg', registryAddArgs(target.registryKey, file));
|
|
242
|
+
registry.push({ key: target.registryKey, manifest: file });
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
return { launcher, manifests: [...new Set(manifests)], registry };
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* Removes what `installHost` wrote (missing files are fine).
|
|
250
|
+
* @param {Omit<InstallOptions, 'extensionIds' | 'firefox' | 'hostScript' | 'nodePath'> & { browsers?: Browser[] }} [options]
|
|
251
|
+
* @returns {{ removed: string[], registry: string[] }}
|
|
252
|
+
*/
|
|
253
|
+
export function uninstallHost(options = {}) {
|
|
254
|
+
const platform = options.platform ?? process.platform;
|
|
255
|
+
const join = platform === 'win32' ? path.win32.join : path.posix.join;
|
|
256
|
+
const removed = [];
|
|
257
|
+
const registry = [];
|
|
258
|
+
const exec = options.exec ?? ((file, args) => void execFileSync(file, args, { stdio: 'ignore' }));
|
|
259
|
+
const remove = (/** @type {string} */ file) => {
|
|
260
|
+
if (!existsSync(file)) return;
|
|
261
|
+
rmSync(file, { force: true });
|
|
262
|
+
removed.push(file);
|
|
263
|
+
};
|
|
264
|
+
let launcherDir = options.launcherDir;
|
|
265
|
+
if (options.dirs?.length) {
|
|
266
|
+
for (const target of options.dirs) remove(join(typeof target === 'string' ? target : target.dir, MANIFEST_FILE));
|
|
267
|
+
launcherDir ??= typeof options.dirs[0] === 'string' ? options.dirs[0] : options.dirs[0].dir;
|
|
268
|
+
} else {
|
|
269
|
+
launcherDir ??= defaultLauncherDir(options);
|
|
270
|
+
for (const browser of options.browsers?.length ? options.browsers : BROWSERS) {
|
|
271
|
+
const { dir, registryKey } = browserTarget(browser, options);
|
|
272
|
+
if (dir) remove(join(dir, MANIFEST_FILE));
|
|
273
|
+
if (registryKey) {
|
|
274
|
+
try {
|
|
275
|
+
exec('reg', registryDeleteArgs(registryKey));
|
|
276
|
+
registry.push(registryKey);
|
|
277
|
+
} catch {}
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
if (platform === 'win32') {
|
|
281
|
+
remove(join(launcherDir, MANIFEST_FILE));
|
|
282
|
+
remove(join(launcherDir, `${NATIVE_HOST_NAME}.firefox.json`));
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
remove(launcherPath(platform, launcherDir));
|
|
286
|
+
return { removed, registry };
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* Manifests that exist now, per browser (for `status`).
|
|
291
|
+
* @param {Where} [where]
|
|
292
|
+
*/
|
|
293
|
+
export function findManifests(where = {}) {
|
|
294
|
+
const platform = where.platform ?? process.platform;
|
|
295
|
+
const join = platform === 'win32' ? path.win32.join : path.posix.join;
|
|
296
|
+
/** @type {{ browser: Browser, file: string }[]} */
|
|
297
|
+
const found = [];
|
|
298
|
+
for (const browser of BROWSERS) {
|
|
299
|
+
const { dir } = browserTarget(browser, where);
|
|
300
|
+
if (dir && existsSync(join(dir, MANIFEST_FILE))) found.push({ browser, file: join(dir, MANIFEST_FILE) });
|
|
301
|
+
}
|
|
302
|
+
if (platform === 'win32') {
|
|
303
|
+
const dir = defaultLauncherDir(where);
|
|
304
|
+
for (const [browser, file] of /** @type {[Browser, string][]} */ ([['chrome', MANIFEST_FILE], ['firefox', `${NATIVE_HOST_NAME}.firefox.json`]])) {
|
|
305
|
+
if (existsSync(join(dir, file))) found.push({ browser, file: join(dir, file) });
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
return found;
|
|
309
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,39 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "blockflow-bridge",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Native messaging host that lets local programs (MCP server, CLI) drive the BlockFlow browser extension.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"blockflow",
|
|
7
|
+
"native-messaging",
|
|
8
|
+
"browser-extension",
|
|
9
|
+
"bridge"
|
|
10
|
+
],
|
|
11
|
+
"homepage": "https://github.com/akibh-dev/blockflow#readme",
|
|
12
|
+
"bugs": {
|
|
13
|
+
"url": "https://github.com/akibh-dev/blockflow/issues"
|
|
14
|
+
},
|
|
15
|
+
"repository": {
|
|
16
|
+
"type": "git",
|
|
17
|
+
"url": "git+https://github.com/akibh-dev/blockflow.git",
|
|
18
|
+
"directory": "packages/bridge"
|
|
19
|
+
},
|
|
20
|
+
"license": "MIT",
|
|
21
|
+
"type": "module",
|
|
22
|
+
"bin": {
|
|
23
|
+
"blockflow-bridge": "./cli.mjs"
|
|
24
|
+
},
|
|
25
|
+
"exports": {
|
|
26
|
+
".": "./index.mjs",
|
|
27
|
+
"./client": "./client.mjs",
|
|
28
|
+
"./protocol": "./protocol.mjs"
|
|
29
|
+
},
|
|
30
|
+
"files": [
|
|
31
|
+
"*.mjs",
|
|
32
|
+
"*.d.mts",
|
|
33
|
+
"README.md",
|
|
34
|
+
"LICENSE"
|
|
35
|
+
],
|
|
36
|
+
"engines": {
|
|
37
|
+
"node": ">=20"
|
|
38
|
+
}
|
|
39
|
+
}
|
package/paths.d.mts
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export type Env = Record<string, string | undefined>;
|
|
2
|
+
export type PathOptions = { platform?: NodeJS.Platform; home?: string; username?: string };
|
|
3
|
+
export declare function configDir(env?: Env, options?: PathOptions): string;
|
|
4
|
+
export declare function socketPath(env?: Env, options?: PathOptions): string;
|
|
5
|
+
export declare function tokenFile(env?: Env, options?: PathOptions): string;
|
|
6
|
+
export declare function readOrCreateToken(file: string): string;
|
|
7
|
+
export declare function readToken(file: string): string;
|
package/paths.mjs
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
// Where the bridge socket and token live. Mirrors the "paths" comment in src/core/bridgeProtocol.ts:
|
|
2
|
+
//
|
|
3
|
+
// Socket: $BLOCKFLOW_SOCKET, else $XDG_RUNTIME_DIR/blockflow.sock, else ~/.config/blockflow/blockflow.sock;
|
|
4
|
+
// Windows: \\.\pipe\blockflow-<username>.
|
|
5
|
+
// Token: $BLOCKFLOW_TOKEN_FILE, else ~/.config/blockflow/token (0600, 32 random bytes hex).
|
|
6
|
+
import { randomBytes } from 'node:crypto';
|
|
7
|
+
import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
8
|
+
import os from 'node:os';
|
|
9
|
+
import path from 'node:path';
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* @typedef {Record<string, string | undefined>} Env
|
|
13
|
+
* @typedef {{ platform?: NodeJS.Platform, home?: string, username?: string }} PathOptions
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
/** @param {Env} env @param {PathOptions} options */
|
|
17
|
+
function homeOf(env, options) {
|
|
18
|
+
return options.home ?? env.HOME ?? env.USERPROFILE ?? os.homedir();
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** `~/.config/blockflow` (also on macOS and Windows: one place for the token, easy to find). */
|
|
22
|
+
export function configDir(env = process.env, options = {}) {
|
|
23
|
+
const platform = options.platform ?? process.platform;
|
|
24
|
+
const join = platform === 'win32' ? path.win32.join : path.posix.join;
|
|
25
|
+
return join(homeOf(env, options), '.config', 'blockflow');
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* The socket (unix) or named pipe (Windows) the native host listens on.
|
|
30
|
+
* @param {Env} [env]
|
|
31
|
+
* @param {PathOptions} [options]
|
|
32
|
+
*/
|
|
33
|
+
export function socketPath(env = process.env, options = {}) {
|
|
34
|
+
if (env.BLOCKFLOW_SOCKET) return env.BLOCKFLOW_SOCKET;
|
|
35
|
+
const platform = options.platform ?? process.platform;
|
|
36
|
+
if (platform === 'win32') {
|
|
37
|
+
const user = options.username ?? env.USERNAME ?? safeUsername();
|
|
38
|
+
return `\\\\.\\pipe\\blockflow-${user.replace(/[^A-Za-z0-9._-]/g, '_')}`;
|
|
39
|
+
}
|
|
40
|
+
if (env.XDG_RUNTIME_DIR) return path.posix.join(env.XDG_RUNTIME_DIR, 'blockflow.sock');
|
|
41
|
+
return path.posix.join(configDir(env, options), 'blockflow.sock');
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* The file holding the shared secret a socket client must send in `auth`.
|
|
46
|
+
* @param {Env} [env]
|
|
47
|
+
* @param {PathOptions} [options]
|
|
48
|
+
*/
|
|
49
|
+
export function tokenFile(env = process.env, options = {}) {
|
|
50
|
+
if (env.BLOCKFLOW_TOKEN_FILE) return env.BLOCKFLOW_TOKEN_FILE;
|
|
51
|
+
const platform = options.platform ?? process.platform;
|
|
52
|
+
return (platform === 'win32' ? path.win32.join : path.posix.join)(configDir(env, options), 'token');
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Reads the token, creating the file (mode 0600, parent folder 0700 when it is new) with 32 random bytes as
|
|
57
|
+
* hex if it does not exist yet. Two hosts racing to create it end up with the same token (`wx` flag).
|
|
58
|
+
* @param {string} file
|
|
59
|
+
* @returns {string}
|
|
60
|
+
*/
|
|
61
|
+
export function readOrCreateToken(file) {
|
|
62
|
+
try {
|
|
63
|
+
const token = readFileSync(file, 'utf8').trim();
|
|
64
|
+
if (token) return token;
|
|
65
|
+
} catch (error) {
|
|
66
|
+
if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'ENOENT') throw error;
|
|
67
|
+
}
|
|
68
|
+
mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
|
|
69
|
+
const token = randomBytes(32).toString('hex');
|
|
70
|
+
try {
|
|
71
|
+
writeFileSync(file, `${token}\n`, { mode: 0o600, flag: 'wx' });
|
|
72
|
+
} catch (error) {
|
|
73
|
+
const code = /** @type {NodeJS.ErrnoException} */ (error).code;
|
|
74
|
+
if (code !== 'EEXIST') throw error;
|
|
75
|
+
// An empty file, or another host won the race: use what is there, or fill the empty one.
|
|
76
|
+
const existing = readFileSync(file, 'utf8').trim();
|
|
77
|
+
if (existing) return existing;
|
|
78
|
+
writeFileSync(file, `${token}\n`, { mode: 0o600 });
|
|
79
|
+
}
|
|
80
|
+
if (process.platform !== 'win32') chmodSync(file, 0o600);
|
|
81
|
+
return token;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** Reads an existing token (clients never create one). @param {string} file */
|
|
85
|
+
export function readToken(file) {
|
|
86
|
+
return readFileSync(file, 'utf8').trim();
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
function safeUsername() {
|
|
90
|
+
try {
|
|
91
|
+
return os.userInfo().username;
|
|
92
|
+
} catch {
|
|
93
|
+
return 'user';
|
|
94
|
+
}
|
|
95
|
+
}
|
package/protocol.d.mts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
// Types for protocol.mjs (the runtime mirror of src/core/bridgeProtocol.ts).
|
|
2
|
+
export declare const BRIDGE_PROTOCOL_VERSION: 1;
|
|
3
|
+
export declare const NATIVE_HOST_NAME: 'dev.akibh.blockflow';
|
|
4
|
+
export declare const MAX_MESSAGE_BYTES: number;
|
|
5
|
+
export declare const BLOB_CHUNK_BYTES: number;
|
|
6
|
+
export declare const INLINE_RESULT_BYTES: number;
|
|
7
|
+
export declare const RPC_ERRORS: Readonly<{
|
|
8
|
+
parse: -32700;
|
|
9
|
+
invalidRequest: -32600;
|
|
10
|
+
methodNotFound: -32601;
|
|
11
|
+
invalidParams: -32602;
|
|
12
|
+
internal: -32603;
|
|
13
|
+
unauthorized: -32001;
|
|
14
|
+
disabled: -32002;
|
|
15
|
+
tooLarge: -32003;
|
|
16
|
+
notFound: -32004;
|
|
17
|
+
invalidWorkflow: -32005;
|
|
18
|
+
notConnected: -32006;
|
|
19
|
+
version: -32007;
|
|
20
|
+
}>;
|
|
21
|
+
export declare const BRIDGE_METHODS: readonly string[];
|
|
22
|
+
export declare const BRIDGE_NOTIFICATIONS: readonly string[];
|
package/protocol.mjs
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
// Mirror of the constants in src/core/bridgeProtocol.ts (the TypeScript source of truth for types).
|
|
2
|
+
// tests/bridge/protocol.test.ts fails if the two drift apart.
|
|
3
|
+
export const BRIDGE_PROTOCOL_VERSION = 1;
|
|
4
|
+
export const NATIVE_HOST_NAME = 'dev.akibh.blockflow';
|
|
5
|
+
export const MAX_MESSAGE_BYTES = 1_000_000;
|
|
6
|
+
export const BLOB_CHUNK_BYTES = 512 * 1024;
|
|
7
|
+
export const INLINE_RESULT_BYTES = 768 * 1024;
|
|
8
|
+
export const RPC_ERRORS = Object.freeze({
|
|
9
|
+
parse: -32700,
|
|
10
|
+
invalidRequest: -32600,
|
|
11
|
+
methodNotFound: -32601,
|
|
12
|
+
invalidParams: -32602,
|
|
13
|
+
internal: -32603,
|
|
14
|
+
unauthorized: -32001,
|
|
15
|
+
disabled: -32002,
|
|
16
|
+
tooLarge: -32003,
|
|
17
|
+
notFound: -32004,
|
|
18
|
+
invalidWorkflow: -32005,
|
|
19
|
+
notConnected: -32006,
|
|
20
|
+
version: -32007,
|
|
21
|
+
});
|
|
22
|
+
/** Methods a socket client may call (forwarded to the extension), plus `auth` (host only). */
|
|
23
|
+
export const BRIDGE_METHODS = Object.freeze(['auth', 'hello', 'validate', 'import', 'list', 'run', 'report', 'snapshot', 'stop', 'blob.get', 'suite.list', 'suite.run']);
|
|
24
|
+
export const BRIDGE_NOTIFICATIONS = Object.freeze(['run.started', 'run.step', 'suite.progress', 'bridge.disabled']);
|