@streamorchard/grapevine 0.0.0-stage → 0.1.1

package/src/handshake.js

@@ -0,0 +1,134 @@
+// The hello: checking what an app says about itself, agreeing versions, and the pairing proofs.
+// PROTOCOL.md, "Connecting and pairing" and "Versions".
+'use strict';
+
+const crypto = require('crypto');
+const { SLUG_RE } = require('./paths');
+
+const PROTOCOL = { min: 1, max: 1 }; // the protocol versions this library speaks
+const ID_RE = /^[a-z0-9][a-z0-9.-]{2,99}$/;
+const VERSION_RE = /^(\d+)\.(\d+)$/;
+const NONCE_BYTES = 32;
+const KEY_BYTES = 32;
+const MAX_ICON = 256 * 1024;
+
+/** "1.2" -> { major: 1, minor: 2 }, or null. */
+function parseVersion(v) {
+  const m = typeof v === 'string' ? VERSION_RE.exec(v) : null;
+  return m ? { major: Number(m[1]), minor: Number(m[2]) } : null;
+}
+
+/**
+ * { cap: '1.0' | ['1.0', '2.1'] } -> { cap: ['1.0', ...] }, checking every version.
+ * @param {Record<string, string | string[]>} [list]
+ * @returns {Record<string, string[]>}
+ */
+function normalizeList(list = {}) {
+  /** @type {Record<string, string[]>} */
+  const out = {};
+  for (const [cap, versions] of Object.entries(list)) {
+    /** @type {string[]} */
+    const all = [].concat(versions);
+    if (!all.length || !all.every(parseVersion)) throw new Error(`Bad versions for ${cap}: use "major.minor", like "1.0"`);
+    out[cap] = all;
+  }
+  return out;
+}
+
+/** What goes in the hello's "capabilities": { cap: { provides: [...], uses: [...] } }. */
+function helloCapabilities(provides, uses) {
+  const out = {};
+  for (const [cap, v] of Object.entries(provides)) out[cap] = { ...out[cap], provides: v };
+  for (const [cap, v] of Object.entries(uses)) out[cap] = { ...out[cap], uses: v };
+  return out;
+}
+
+const majors = (versions) =>
+  new Map(
+    (versions ?? [])
+      .map(parseVersion)
+      .filter(Boolean)
+      .map((v) => [v.major, v.minor]),
+  );
+
+/**
+ * Agrees, per capability, the highest major both apps support.
+ * - incoming: capabilities this app uses that the other provides
+ * - outgoing: capabilities this app provides that the other uses
+ * - missing: ones one side wants and can't get (for the compatibility report)
+ */
+function agree(mine, theirs) {
+  const incoming = new Map();
+  const outgoing = new Map();
+  const missing = [];
+  const pick = (want, have) => {
+    const common = [...majors(want).keys()].filter((m) => majors(have).has(m));
+    return common.length ? Math.max(...common) : null;
+  };
+  for (const [cap, want] of Object.entries(mine.uses)) {
+    const have = theirs?.[cap]?.provides;
+    const major = pick(want, have);
+    if (major !== null) incoming.set(cap, { major, minor: majors(have).get(major) });
+    else missing.push({ capability: cap, direction: 'incoming', mine: [...majors(want).keys()], theirs: [...majors(have).keys()] });
+  }
+  for (const [cap, have] of Object.entries(mine.provides)) {
+    const want = theirs?.[cap]?.uses;
+    if (!want) continue; // they don't use it: nothing to send
+    const major = pick(want, have);
+    if (major !== null) outgoing.set(cap, { major, minor: majors(have).get(major) });
+    else missing.push({ capability: cap, direction: 'outgoing', mine: [...majors(have).keys()], theirs: [...majors(want).keys()] });
+  }
+  return { incoming, outgoing, missing };
+}
+
+/** The highest protocol version both ranges include, or null. */
+function agreeProtocol(a, b) {
+  const top = Math.min(a.max, b.max);
+  return top >= Math.max(a.min, b.min) ? top : null;
+}
+
+const nonce = () => crypto.randomBytes(NONCE_BYTES).toString('base64');
+const newKey = () => crypto.randomBytes(KEY_BYTES).toString('base64');
+
+/** HMAC-SHA256 of "<role>:<nonce>" with the pairing key: proves an app knows the key without sending it. */
+function proof(keyB64, role, n) {
+  return crypto.createHmac('sha256', Buffer.from(keyB64, 'base64')).update(`${role}:${n}`).digest('base64');
+}
+
+function proofOk(keyB64, role, n, given) {
+  if (typeof given !== 'string') return false;
+  const want = Buffer.from(proof(keyB64, role, n), 'base64');
+  const got = Buffer.from(given, 'base64');
+  return got.length === want.length && crypto.timingSafeEqual(got, want);
+}
+
+const isHttps = (u) => typeof u === 'string' && /^https:\/\/[^\s]+$/.test(u) && u.length <= 500;
+
+/** Problems with an app's description in a hello ("app.id: …"), empty when it's fine. */
+function checkApp(app) {
+  const p = [];
+  if (!app || typeof app !== 'object') return ['app: missing'];
+  if (typeof app.id !== 'string' || !ID_RE.test(app.id)) p.push('app.id: lowercase letters, digits, dots and dashes, like com.example.app');
+  if (typeof app.slug !== 'string' || !SLUG_RE.test(app.slug)) p.push('app.slug: lowercase letters, digits and dashes');
+  if (typeof app.name !== 'string' || !app.name || app.name.length > 100) p.push('app.name: 1 to 100 characters');
+  if (typeof app.version !== 'string' || !app.version || app.version.length > 40) p.push('app.version: 1 to 40 characters');
+  if (app.summary !== undefined && (typeof app.summary !== 'string' || app.summary.length > 300)) p.push('app.summary: up to 300 characters');
+  if (app.icon !== undefined && (typeof app.icon !== 'string' || !app.icon.startsWith('data:image/png;base64,') || app.icon.length > MAX_ICON))
+    p.push('app.icon: a PNG data URL, up to 256 KB');
+  for (const k of ['homepage', 'download']) if (app[k] !== undefined && !isHttps(app[k])) p.push(`app.${k}: an https address`);
+  return p;
+}
+
+/** Problems with a hello's params, empty when it's fine. */
+function checkHello(params) {
+  const p = checkApp(params?.app);
+  const pr = params?.protocol;
+  if (!pr || !Number.isInteger(pr.min) || !Number.isInteger(pr.max) || pr.min < 1 || pr.max < pr.min) p.push('protocol: { min, max } whole numbers');
+  if (!params?.capabilities || typeof params.capabilities !== 'object' || Array.isArray(params.capabilities)) p.push('capabilities: an object');
+  const auth = params?.auth;
+  if (!auth || typeof auth.nonce !== 'string' || Buffer.from(auth.nonce, 'base64').length !== NONCE_BYTES) p.push('auth.nonce: 32 random bytes, base64');
+  if (auth && auth.pair !== undefined && typeof auth.pair !== 'boolean') p.push('auth.pair: true or false');
+  return p;
+}
+
+module.exports = { PROTOCOL, ID_RE, parseVersion, normalizeList, helloCapabilities, agree, agreeProtocol, nonce, newKey, proof, proofOk, checkApp, checkHello };

package/src/index.js

@@ -0,0 +1,421 @@
+// Grapevine: lets desktop apps on the same computer find each other and talk, privately.
+// createLink() is all an app uses: start it, publish what it provides, listen for what it uses,
+// and show peers() on its Connected apps page. PROTOCOL.md describes what goes over the wire.
+'use strict';
+
+const fs = require('fs');
+const net = require('net');
+const { EventEmitter } = require('events');
+const paths = require('./paths');
+const hs = require('./handshake');
+const { Connection, TIMING } = require('./connection');
+const { Schemas } = require('./schema');
+const { CODES, GrapevineError } = require('./errors');
+const { KNOWN_APPS, isInstalled, iconDataUrl } = require('./known-apps');
+const { compatibility, incompatible } = require('./report');
+const { fileKeyStore, memoryKeyStore } = require('./keys');
+
+const BACKOFF_MS = [1000, 2000, 5000, 10_000, 30_000];
+const POLL_MS = 5000;
+
+/**
+ * @typedef {object} LinkOptions
+ * @property {{id: string, slug: string, name: string, version: string, summary?: string, icon?: string, homepage?: string, download?: string}} app
+ *   This app, as other apps will see it. `icon` may be a PNG data URL or a file path.
+ * @property {Record<string, string | string[]>} [provides] capabilities this app provides, e.g. { 'drops.farming': '1.0' }
+ * @property {Record<string, string | string[]>} [uses] capabilities it uses, e.g. { players: '1.0' }
+ * @property {(appId: string) => boolean} allowed whether its Connected apps switch for that app is on
+ * @property {ReturnType<typeof fileKeyStore>} [keys] where pairing keys are kept (fileKeyStore(); in memory if left out)
+ * @property {string} [appDataDir] the OS's app data folder (Electron's app.getPath('appData')), to tell whether known apps are installed
+ * @property {import('./paths').Place} [place] for tests: the platform and environment to work out paths from
+ * @property {string[]} [schemaDirs] extra schema folders, for capabilities that aren't in this package yet
+ * @property {typeof KNOWN_APPS} [knownApps]
+ * @property {Partial<typeof TIMING> & {pollMs?: number, backoffMs?: number[]}} [timing]
+ * @property {boolean} [strict] throw on a message that doesn't match its schema (default: when NODE_ENV is "test")
+ * @property {(level: 'info' | 'warn' | 'error', text: string) => void} [log]
+ */
+
+class Link extends EventEmitter {
+  /** @param {LinkOptions} opts */
+  constructor(opts) {
+    super();
+    const icon = opts.app.icon && !opts.app.icon.startsWith('data:') ? iconDataUrl(opts.app.icon) : opts.app.icon;
+    this.self = { ...opts.app, ...(icon ? { icon } : {}) };
+    const problems = hs.checkApp(this.self);
+    if (problems.length) throw new Error(`createLink: ${problems.join('; ')}`);
+    this.mine = { provides: hs.normalizeList(opts.provides), uses: hs.normalizeList(opts.uses) };
+    this.allowedFn = opts.allowed;
+    this.keys = opts.keys ?? memoryKeyStore();
+    this.appDataDir = opts.appDataDir ?? null;
+    this.place = opts.place ?? {};
+    this.schemas = Schemas.load(opts.schemaDirs);
+    this.knownApps = (opts.knownApps ?? KNOWN_APPS).filter((a) => a.id !== this.self.id);
+    this.timing = { ...TIMING, pollMs: POLL_MS, backoffMs: BACKOFF_MS, ...opts.timing };
+    this.strict = opts.strict ?? process.env.NODE_ENV === 'test';
+    this.logFn = opts.log ?? (() => {});
+    for (const cap of [...Object.keys(this.mine.provides), ...Object.keys(this.mine.uses)]) {
+      const listed = [...(this.mine.provides[cap] ?? []), ...(this.mine.uses[cap] ?? [])];
+      for (const v of listed) if (!this.schemas.get(cap, hs.parseVersion(v).major)) throw new Error(`createLink: no schema for ${cap} ${v}`);
+    }
+    /** @type {Map<string, Connection>} ready connections, by the other app's id */
+    this.conns = new Map();
+    /** @type {Set<Connection>} connections still saying hello */
+    this.opening = new Set();
+    /** @type {Map<string, {status: string, keyHeldBy?: string, theirProtocol?: any, reason?: string, theirApp?: any}>} why an app isn't connected */
+    this.why = new Map();
+    this.retry = new Map(); // app id -> { attempts, at }
+    this.latest = new Map(); // event -> its last params
+    this.seq = new Map();
+    this.handlers = new Map();
+    this.running = false;
+  }
+
+  // ------------------------------------------------------------------ starting and stopping
+
+  /** Listens for other apps and starts looking for them. */
+  async start() {
+    if (this.running) return;
+    paths.ensureDir(this.place);
+    this.socketPath = paths.socketPath(this.self.slug, this.place);
+    await this.listen();
+    this.running = true;
+    const platform = this.place.platform ?? process.platform;
+    if (platform !== 'win32') {
+      try {
+        this.watcher = fs.watch(paths.socketDir(this.place), () => this.pollSoon());
+        this.watcher.on('error', () => {});
+      } catch {}
+    }
+    this.pollTimer = setInterval(() => this.poll(), this.timing.pollMs);
+    this.pollTimer.unref?.();
+    this.poll();
+  }
+
+  listen() {
+    const platform = this.place.platform ?? process.platform;
+    return new Promise((resolve, reject) => {
+      const server = net.createServer((socket) => this.accept(socket));
+      const go = () =>
+        server.listen(this.socketPath, () => {
+          if (platform !== 'win32') fs.chmodSync(this.socketPath, 0o600);
+          this.server = server;
+          resolve();
+        });
+      server.on('error', (/** @type {NodeJS.ErrnoException} */ err) => {
+        if (err.code !== 'EADDRINUSE' || platform === 'win32') return reject(err);
+        // A socket file is there already. If nothing answers, a crash left it: replace it.
+        const probe = net.createConnection(this.socketPath);
+        probe.once('connect', () => {
+          probe.destroy();
+          reject(new GrapevineError(CODES.INTERNAL_ERROR, `Another copy of ${this.self.name} is already using Grapevine`));
+        });
+        probe.once('error', () => {
+          try {
+            fs.unlinkSync(this.socketPath);
+          } catch {}
+          go();
+        });
+      });
+      go();
+    });
+  }
+
+  /** Says goodbye to every app and stops listening. */
+  async stop() {
+    if (!this.running) return;
+    this.running = false;
+    clearInterval(this.pollTimer);
+    clearTimeout(this.pollSoonTimer);
+    this.watcher?.close();
+    for (const c of [...this.opening, ...this.conns.values()]) c.bye(`${this.self.name} quit`);
+    await new Promise((resolve) => this.server.close(() => resolve()));
+    if ((this.place.platform ?? process.platform) !== 'win32') {
+      try {
+        fs.unlinkSync(this.socketPath);
+      } catch {}
+    }
+  }
+
+  /** Call after a Connected apps switch changes: closes connections switched off, looks for ones switched on. */
+  refresh() {
+    for (const [id, c] of this.conns) if (!this.allowed(id)) c.bye(`Switched off in ${this.self.name}`);
+    for (const c of this.opening) if (c.peerId && !this.allowed(c.peerId)) c.close('Switched off');
+    for (const a of this.knownApps) if (this.allowed(a.id)) this.retry.delete(a.id);
+    this.poll();
+    this.changed();
+  }
+
+  allowed(id) {
+    try {
+      return !!this.allowedFn(id);
+    } catch {
+      return false;
+    }
+  }
+
+  // ------------------------------------------------------------------ finding apps
+
+  pollSoon() {
+    clearTimeout(this.pollSoonTimer);
+    this.pollSoonTimer = setTimeout(() => this.poll(), 100);
+    this.pollSoonTimer.unref?.();
+  }
+
+  /**
+   * Connects to apps that are running and switched on. Of two apps, the one whose id sorts first
+   * connects and the other waits, so they don't both connect at once.
+   */
+  poll() {
+    if (!this.running) return;
+    const slugs = new Set(paths.listSlugs(this.place));
+    for (const app of this.knownApps) {
+      if (!slugs.has(app.slug) || !this.allowed(app.id) || this.conns.has(app.id) || this.self.id > app.id) continue;
+      if ([...this.opening].some((c) => (c.expectedId ?? c.peerId) === app.id)) continue;
+      const r = this.retry.get(app.id);
+      if (r && Date.now() < r.at) continue;
+      this.connect(app);
+    }
+  }
+
+  connect(app) {
+    const socket = net.createConnection(paths.socketPath(app.slug, this.place));
+    const conn = new Connection(socket, this.host(), { initiator: true, expectedId: app.id });
+    this.track(conn);
+    socket.once('connect', () => conn.start());
+  }
+
+  accept(socket) {
+    this.track(new Connection(socket, this.host(), { initiator: false }));
+  }
+
+  track(conn) {
+    this.opening.add(conn);
+    conn.on('status', (s) => {
+      const id = conn.expectedId ?? s.peer?.id ?? conn.peerId;
+      if (!id) return;
+      this.why.set(id, { ...s, peer: undefined, theirApp: s.peer });
+      this.changed();
+    });
+    conn.on('ready', () => this.onReady(conn));
+    conn.on('event', (name, params) => this.emit('event', conn.peerId, name, params));
+    conn.on('unpaired', () => {
+      this.why.set(conn.peerId, { status: 'waiting', reason: 'disconnected-there' });
+      this.emit('unpaired', conn.peerId);
+    });
+    conn.on('close', (reason, wasReady) => this.onClose(conn, reason, wasReady));
+  }
+
+  onReady(conn) {
+    this.opening.delete(conn);
+    const id = conn.peerId;
+    const other = this.conns.get(id);
+    if (other) {
+      // Both connected at once: keep the one made by the app whose id sorts first.
+      const firstOf = (c) => (c.initiator ? this.self.id : c.peerId);
+      const [keep, drop] = firstOf(conn) <= firstOf(other) ? [conn, other] : [other, conn];
+      this.conns.set(id, keep);
+      drop.bye('duplicate');
+      return;
+    }
+    this.conns.set(id, conn);
+    this.why.delete(id);
+    this.retry.delete(id);
+    this.log('info', `Connected to ${conn.peer.name}`);
+    this.emit('connected', id);
+    this.changed();
+  }
+
+  onClose(conn, reason, wasReady) {
+    this.opening.delete(conn);
+    const id = conn.peerId ?? conn.expectedId;
+    if (id && this.conns.get(id) === conn) {
+      this.conns.delete(id);
+      this.emit('disconnected', id, reason);
+    }
+    if (conn.initiator && id) {
+      const attempts = wasReady ? 0 : (this.retry.get(id)?.attempts ?? 0) + 1;
+      const wait = this.timing.backoffMs[Math.min(Math.max(attempts - 1, 0), this.timing.backoffMs.length - 1)];
+      this.retry.set(id, { attempts, at: Date.now() + (wasReady ? this.timing.backoffMs[0] : wait) });
+    }
+    this.changed();
+  }
+
+  // ------------------------------------------------------------------ what connections ask of the link
+
+  host() {
+    return {
+      self: this.self,
+      mine: this.mine,
+      keys: this.keys,
+      allowed: (id) => this.allowed(id),
+      schemas: this.schemas,
+      timing: this.timing,
+      log: (level, text) => this.log(level, text),
+      call: (conn, method, params) => this.call(conn, method, params),
+      subscribe: (conn, events) => {
+        const offered = new Set();
+        for (const [cap, { major }] of conn.agreed.outgoing) for (const e of Object.keys(this.schemas.get(cap, major)?.events ?? {})) offered.add(e);
+        conn.subscribed = new Set(events.filter((e) => offered.has(e)));
+        return [...conn.subscribed];
+      },
+      afterSubscribe: (conn) => {
+        for (const e of conn.subscribed) if (this.latest.has(e)) this.sendEvent(conn, e, this.latest.get(e));
+      },
+    };
+  }
+
+  async call(conn, method, params) {
+    const cap = this.schemas.capabilityOf(method);
+    if (!cap) throw new GrapevineError(CODES.METHOD_NOT_FOUND, `No such method: ${method}`);
+    const agreed = conn.agreed.outgoing.get(cap);
+    if (!agreed) throw new GrapevineError(CODES.NOT_AGREED, `${cap} wasn't agreed on this connection`);
+    const bad = this.schemas.validate(cap, agreed.major, 'params', method, params);
+    if (bad.length)
+      throw new GrapevineError(bad[0].includes("isn't part of") ? CODES.METHOD_NOT_FOUND : CODES.INVALID_PARAMS, `Invalid params: ${bad.join('; ')}`, {
+        problems: bad,
+      });
+    let result;
+    const fn = this.handlers.get(method);
+    if (fn) result = await fn(params, { appId: conn.peerId, app: conn.peer, major: agreed.major });
+    else {
+      // A "<capability>.get" with no handler answers with the last "<capability>.changed".
+      const latest = method === `${cap}.get` ? this.latest.get(`${cap}.changed`) : undefined;
+      if (!latest) throw new GrapevineError(CODES.METHOD_NOT_FOUND, `${this.self.name} doesn't answer ${method} yet`);
+      result = latest;
+    }
+    const wrong = this.schemas.validate(cap, agreed.major, 'result', method, result);
+    if (wrong.length) {
+      this.log('error', `${method} answered with an invalid result: ${wrong.join('; ')}`);
+      if (this.strict) throw new Error(`${method} returned an invalid result: ${wrong.join('; ')}`);
+      throw new GrapevineError(CODES.INTERNAL_ERROR, `${this.self.name} gave an invalid answer`);
+    }
+    return result;
+  }
+
+  sendEvent(conn, event, params) {
+    const cap = this.schemas.capabilityOf(event);
+    const { major } = conn.agreed.outgoing.get(cap) ?? {};
+    if (major === undefined) return;
+    const problems = this.schemas.validate(cap, major, 'event', event, params);
+    if (problems.length) return this.log('error', `Not sent: ${event} doesn't fit ${cap} ${major}: ${problems.join('; ')}`);
+    conn.rpc.notify(event, params);
+  }
+
+  // ------------------------------------------------------------------ what apps call
+
+  /**
+   * Tells every subscribed app something changed. `data` is the event's fields; `seq` and `at` are
+   * added. The last one is kept, for apps that subscribe later and for "<capability>.get".
+   * @returns {object} the params as sent
+   */
+  publish(event, data) {
+    const cap = this.schemas.capabilityOf(event);
+    if (!cap || !this.mine.provides[cap]) throw new Error(`${event} isn't part of a capability ${this.self.name} provides`);
+    const seq = (this.seq.get(event) ?? 0) + 1;
+    this.seq.set(event, seq);
+    const params = { ...data, seq, at: new Date().toISOString() };
+    const top = Math.max(...this.mine.provides[cap].map((v) => hs.parseVersion(v).major));
+    const problems = this.schemas.validate(cap, top, 'event', event, params);
+    if (problems.length) {
+      this.log('error', `${event} doesn't fit ${cap} ${top}: ${problems.join('; ')}`);
+      if (this.strict) throw new Error(`${event} doesn't fit its schema: ${problems.join('; ')}`);
+    }
+    this.latest.set(event, params);
+    for (const c of this.conns.values()) if (c.subscribed.has(event)) this.sendEvent(c, event, params);
+    return params;
+  }
+
+  /** Answers a method of a capability this app provides: fn(params, { appId, app, major }) -> result. */
+  handle(method, fn) {
+    this.handlers.set(method, fn);
+  }
+
+  /** Asks a connected app something. Rejects with a GrapevineError (CLOSED if it isn't connected). */
+  async request(appId, method, params = {}, opts) {
+    const conn = this.conns.get(appId);
+    if (!conn) throw new GrapevineError(CODES.CLOSED, `Not connected to ${appId}`);
+    const cap = this.schemas.capabilityOf(method);
+    const agreed = cap && conn.agreed.incoming.get(cap);
+    if (!agreed) throw new GrapevineError(CODES.NOT_AGREED, `${method} isn't agreed with ${conn.peer.name}`);
+    const bad = this.schemas.validate(cap, agreed.major, 'params', method, params);
+    if (bad.length) throw new GrapevineError(CODES.INVALID_PARAMS, `Invalid params: ${bad.join('; ')}`, { problems: bad });
+    const result = await conn.rpc.request(method, params, opts);
+    const wrong = this.schemas.validate(cap, agreed.major, 'result', method, result);
+    if (wrong.length) throw new GrapevineError(CODES.INTERNAL_ERROR, `${conn.peer.name} gave an invalid answer: ${wrong.join('; ')}`);
+    return result;
+  }
+
+  /** Disconnect on a card: tells the other app to forget the pairing, and forgets it here. Switch this app's own setting off too. */
+  async disconnect(appId) {
+    const conn = this.conns.get(appId);
+    if (conn) {
+      await conn.rpc.request('link.unpair', {}, { timeout: 2000 }).catch(() => {});
+      conn.close('Disconnected');
+    }
+    this.keys.delete(appId);
+    this.why.delete(appId);
+    this.changed();
+  }
+
+  /** "Pair again" on a card: forgets this app's old key, so the next connection pairs afresh. */
+  pairAgain(appId) {
+    this.keys.delete(appId);
+    this.why.delete(appId);
+    this.retry.delete(appId);
+    this.poll();
+    this.changed();
+  }
+
+  isConnected(appId) {
+    return this.conns.has(appId);
+  }
+
+  /**
+   * Every known app, for the Connected apps page:
+   * status 'off' (its switch is off) | 'waiting' | 'connected' | 'pair-again' | 'incompatible'.
+   */
+  peers() {
+    return this.knownApps.map((app) => {
+      const conn = this.conns.get(app.id);
+      const why = this.why.get(app.id);
+      const enabled = this.allowed(app.id);
+      const paired = this.keys.get(app.id);
+      let status = !enabled ? 'off' : conn ? 'connected' : (why?.status ?? 'waiting');
+      if (status === 'connected' && !conn) status = 'waiting';
+      let report = null;
+      if (conn) report = compatibility(this.self, conn.peer, conn.agreed);
+      else if (status === 'incompatible' && why?.theirProtocol) report = incompatible(this.self, why.theirApp ?? app, hs.PROTOCOL, why.theirProtocol);
+      return {
+        id: app.id,
+        name: app.name,
+        summary: app.summary,
+        icon: app.icon,
+        homepage: app.homepage,
+        download: app.download,
+        installed: this.appDataDir ? isInstalled(app, this.appDataDir) : null,
+        enabled,
+        status,
+        reason: why?.reason ?? null,
+        keyHeldBy: status === 'pair-again' ? (why?.keyHeldBy ?? null) : null,
+        version: conn?.peer.version ?? null,
+        report,
+        pairedAt: paired?.pairedAt ?? null,
+        keysEncrypted: !!this.keys.encrypted,
+      };
+    });
+  }
+
+  changed() {
+    this.emit('change');
+  }
+
+  log(level, text) {
+    this.logFn(level, text);
+    this.emit('log', level, text);
+  }
+}
+
+/** @param {LinkOptions} opts */
+const createLink = (opts) => new Link(opts);
+
+module.exports = { createLink, Link, CODES, GrapevineError, KNOWN_APPS, fileKeyStore, memoryKeyStore, isInstalled, iconDataUrl, PROTOCOL: hs.PROTOCOL, paths };

package/src/keys.js

@@ -0,0 +1,71 @@
+// Where an app keeps its pairing keys: one small file in its own data folder, private to the user,
+// encrypted with the app's own encrypt/decrypt (Electron's safeStorage) when it has them.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * @typedef {object} KeyStore
+ * @property {boolean} [encrypted] whether keys are encrypted at rest
+ * @property {(id: string) => {key: string, pairedAt?: string} | null} get
+ * @property {(id: string, key: string) => void} set
+ * @property {(id: string) => void} delete
+ */
+
+/**
+ * @param {string} file e.g. <userData>/grapevine.json
+ * @param {{encrypt?: (text: string) => string, decrypt?: (stored: string) => string}} [crypt]
+ *   encrypt returns text to store (base64, say) and decrypt reverses it. Without them, keys are stored as they are.
+ * @returns {KeyStore}
+ */
+function fileKeyStore(file, { encrypt, decrypt } = {}) {
+  /** @type {Record<string, {key: string, pairedAt: string, encrypted?: boolean}>} */
+  let peers = {};
+  try {
+    peers = JSON.parse(fs.readFileSync(file, 'utf8')).peers ?? {};
+  } catch {}
+
+  const save = () => {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ peers }, null, 2), { mode: 0o600 });
+    fs.renameSync(tmp, file); // all at once: a crash never leaves half a file
+  };
+
+  return {
+    /** Whether keys are encrypted at rest, for the card to say so if not. */
+    encrypted: !!(encrypt && decrypt),
+    get(id) {
+      const p = peers[id];
+      if (!p) return null;
+      try {
+        return { key: p.encrypted && decrypt ? decrypt(p.key) : p.key, pairedAt: p.pairedAt };
+      } catch {
+        return null; // can't decrypt (another user, a new keychain): as good as not paired
+      }
+    },
+    set(id, key) {
+      peers[id] = encrypt && decrypt ? { key: encrypt(key), encrypted: true, pairedAt: new Date().toISOString() } : { key, pairedAt: new Date().toISOString() };
+      save();
+    },
+    delete(id) {
+      if (!(id in peers)) return;
+      delete peers[id];
+      save();
+    },
+  };
+}
+
+/** Keys kept in memory only: for tests and the stand-in peer. @returns {KeyStore} */
+function memoryKeyStore() {
+  const peers = new Map();
+  return {
+    encrypted: false,
+    get: (id) => peers.get(id) ?? null,
+    set: (id, key) => void peers.set(id, { key, pairedAt: new Date().toISOString() }),
+    delete: (id) => void peers.delete(id),
+  };
+}
+
+module.exports = { fileKeyStore, memoryKeyStore };