peekinside 0.0.0-stage → 1.2.1

package/src/crypto.js

@@ -0,0 +1,189 @@
+/**
+ * End-to-end encryption for PeekInside Cloud, format v1.
+ *
+ * Mirrors the dashboard's implementation: ephemeral ECDH P-256, HKDF-SHA-256 and AES-256-GCM,
+ * all from Node's Web Crypto. Events are sealed to the project's public key, so only browsers
+ * holding the project's private key can read them; this process can encrypt but never decrypt.
+ *
+ * Output: "v1.<ephemeral public key>.<iv>.<ciphertext>" (base64url parts). Any change here must
+ * stay byte-compatible with the dashboard, or existing projects can no longer read their events.
+ */
+
+import { createCipheriv, createECDH, hkdfSync, randomBytes, webcrypto } from 'crypto';
+
+const subtle = webcrypto.subtle;
+const ECDH = { name: 'ECDH', namedCurve: 'P-256' };
+const encoder = new TextEncoder();
+
+const PROJECT_ID = /^p[0-9a-z]{12}$/;
+const SECRET = /^[A-Za-z0-9_-]{43}$/;
+const PUBLIC_KEY = /^[A-Za-z0-9_-]{87}$/;
+
+/**
+ * @param {Uint8Array|ArrayBuffer} bytes
+ * @returns {string} Base64url without padding
+ */
+export function toBase64Url(bytes) {
+  return Buffer.from(bytes).toString('base64url');
+}
+
+/**
+ * @param {string} text - Base64url
+ * @returns {Uint8Array}
+ */
+export function fromBase64Url(text) {
+  return new Uint8Array(Buffer.from(text, 'base64url'));
+}
+
+/**
+ * Encrypts messages to one recipient public key, with one ephemeral key pair.
+ *
+ * The key agreement is the expensive part, so one sealer serves a whole batch: each message
+ * still gets its own random IV. Create a new sealer per batch, so ephemeral keys are not reused
+ * for long.
+ */
+export class Sealer {
+  /**
+   * Use Sealer.create(): the key agreement is asynchronous.
+   *
+   * @param {CryptoKey} key - AES-256-GCM key derived for this sealer
+   * @param {Uint8Array} ephemeralPublicKey - Raw ephemeral public key, sent with every message so
+   *   the recipient can derive the same key
+   */
+  constructor(key, ephemeralPublicKey) {
+    this._key = key;
+    this._prefix = `v1.${toBase64Url(ephemeralPublicKey)}.`;
+  }
+
+  /**
+   * Agrees on a key with the recipient: ECDH with a fresh ephemeral key, then HKDF-SHA-256 with
+   * both public keys as salt and "peekinside/v1/<purpose>" as info, so keys derived for one
+   * purpose never decrypt another.
+   *
+   * @param {string} recipientPublicKey - Project public key (base64url, uncompressed P-256 point)
+   * @param {string} purpose - "event"
+   * @returns {Promise<Sealer>}
+   */
+  static async create(recipientPublicKey, purpose) {
+    const recipientRaw = fromBase64Url(recipientPublicKey);
+    const recipient = await subtle.importKey('raw', recipientRaw, ECDH, false, []);
+    const ephemeral = await subtle.generateKey(ECDH, true, ['deriveBits']);
+    const ephemeralRaw = new Uint8Array(await subtle.exportKey('raw', ephemeral.publicKey));
+
+    const shared = await subtle.deriveBits({ name: 'ECDH', public: recipient }, ephemeral.privateKey, 256);
+    const material = await subtle.importKey('raw', shared, 'HKDF', false, ['deriveKey']);
+    const salt = new Uint8Array(ephemeralRaw.length + recipientRaw.length);
+    salt.set(ephemeralRaw, 0);
+    salt.set(recipientRaw, ephemeralRaw.length);
+    const key = await subtle.deriveKey(
+      { name: 'HKDF', hash: 'SHA-256', salt, info: encoder.encode(`peekinside/v1/${purpose}`) },
+      material,
+      { name: 'AES-GCM', length: 256 },
+      false,
+      ['encrypt']
+    );
+    return new Sealer(key, ephemeralRaw);
+  }
+
+  /**
+   * Encrypts one message with AES-256-GCM and a random 12-byte IV.
+   *
+   * @param {string|Uint8Array} plaintext
+   * @param {string} aad - Additional authenticated data, such as "detail:<request id>": decryption
+   *   fails unless the reader expects the same value, which binds the message to its context
+   * @returns {Promise<string>} "v1.<ephemeral public key>.<iv>.<ciphertext>"
+   */
+  async seal(plaintext, aad) {
+    const iv = webcrypto.getRandomValues(new Uint8Array(12));
+    const data = typeof plaintext === 'string' ? encoder.encode(plaintext) : plaintext;
+    const ciphertext = await subtle.encrypt({ name: 'AES-GCM', iv, additionalData: encoder.encode(aad) }, this._key, data);
+    return `${this._prefix}${toBase64Url(iv)}.${toBase64Url(new Uint8Array(ciphertext))}`;
+  }
+}
+
+/**
+ * Sealer for a process that is crashing: the same key agreement and format as Sealer, but
+ * synchronous (node:crypto instead of Web Crypto), because nothing asynchronous runs once the
+ * process has started to exit.
+ *
+ * ECDH on P-256 yields the x-coordinate of the shared point in both APIs, HKDF and AES-GCM are the
+ * same algorithms, and Web Crypto appends the 16-byte GCM tag to the ciphertext: output is
+ * interchangeable with Sealer's, and opens with the dashboard's Opener.
+ */
+export class SyncSealer {
+  /**
+   * Use SyncSealer.create().
+   *
+   * @param {Buffer} key - AES-256-GCM key derived for this sealer
+   * @param {Buffer} ephemeralPublicKey - Raw (uncompressed) ephemeral public key
+   */
+  constructor(key, ephemeralPublicKey) {
+    this._key = key;
+    this._prefix = `v1.${toBase64Url(ephemeralPublicKey)}.`;
+  }
+
+  /**
+   * Agrees on a key with the recipient, exactly like Sealer.create().
+   *
+   * @param {string} recipientPublicKey - Project public key (base64url, uncompressed P-256 point)
+   * @param {string} purpose - "event"
+   * @returns {SyncSealer}
+   * @throws {Error} When the public key is not a valid P-256 point
+   */
+  static create(recipientPublicKey, purpose) {
+    const recipientRaw = Buffer.from(recipientPublicKey, 'base64url');
+    const ecdh = createECDH('prime256v1');
+    const ephemeralRaw = ecdh.generateKeys();
+    const shared = ecdh.computeSecret(recipientRaw);
+    const salt = Buffer.concat([ephemeralRaw, recipientRaw]);
+    const key = Buffer.from(hkdfSync('sha256', shared, salt, Buffer.from(`peekinside/v1/${purpose}`), 32));
+    return new SyncSealer(key, ephemeralRaw);
+  }
+
+  /**
+   * Encrypts one message with AES-256-GCM and a random 12-byte IV.
+   *
+   * @param {string|Uint8Array} plaintext
+   * @param {string} aad - Additional authenticated data (see Sealer#seal())
+   * @returns {string} "v1.<ephemeral public key>.<iv>.<ciphertext and tag>"
+   */
+  seal(plaintext, aad) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', this._key, iv);
+    cipher.setAAD(Buffer.from(aad, 'utf8'));
+    const data = typeof plaintext === 'string' ? Buffer.from(plaintext, 'utf8') : plaintext;
+    const ciphertext = Buffer.concat([cipher.update(data), cipher.final(), cipher.getAuthTag()]);
+    return `${this._prefix}${toBase64Url(iv)}.${toBase64Url(ciphertext)}`;
+  }
+}
+
+/**
+ * A PeekInside Cloud API key: "pik1.<projectId>.<secret>.<projectPublicKey>".
+ *
+ * The secret authorizes sending events; the public key lets the SDK encrypt them. The key never
+ * contains anything that can decrypt events.
+ */
+export class ApiKey {
+  /**
+   * @param {Object} parts
+   * @param {string} parts.projectId - Project id, such as "p0123456789ab"
+   * @param {string} parts.secret - Ingest secret (base64url)
+   * @param {string} parts.publicKey - Project public key (base64url, uncompressed P-256 point)
+   */
+  constructor({ projectId, secret, publicKey }) {
+    this.projectId = projectId;
+    this.secret = secret;
+    this.publicKey = publicKey;
+  }
+
+  /**
+   * @param {string} apiKey
+   * @returns {ApiKey|null} The key's parts, or null when it isn't a well-formed v1 key
+   */
+  static parse(apiKey) {
+    const [version, projectId, secret, publicKey, ...rest] = String(apiKey).trim().split('.');
+    if (version !== 'pik1' || rest.length) return null;
+    if (!PROJECT_ID.test(projectId) || !SECRET.test(secret) || !PUBLIC_KEY.test(publicKey)) return null;
+    return new ApiKey({ projectId, secret, publicKey });
+  }
+}

package/src/deployment.js

@@ -0,0 +1,183 @@
+/**
+ * Tells local development apart from a deployed server, request by request.
+ *
+ * The free local dashboard records local development only. A request that reached the app
+ * through a public domain or IP address, or that a proxy forwarded from a public client, means
+ * the app runs on a server: those requests need PeekInside Cloud and are not recorded locally.
+ *
+ * Local means: localhost and *.localhost, reserved and LAN names (*.test, *.local, *.internal...),
+ * single-label names (Docker services, machine names), loopback and private addresses, the
+ * networks this machine is on, and development tunnels such as ngrok (webhooks to a laptop).
+ */
+
+import net from 'net';
+import os from 'os';
+
+const LOCAL_SUFFIXES = ['.localhost', '.test', '.local', '.localdomain', '.internal', '.lan', '.home.arpa', '.example', '.invalid'];
+const TUNNEL_SUFFIXES = [
+  '.ngrok.io', '.ngrok.app', '.ngrok.dev', '.ngrok-free.app', '.ngrok-free.dev',
+  '.trycloudflare.com', '.loca.lt', '.sharedwithexpose.com', '.lhr.life', '.app.github.dev', '.gitpod.io'
+];
+const PRIVATE_SUBNETS = [
+  ['0.0.0.0', 8, 'ipv4'], ['10.0.0.0', 8, 'ipv4'], ['100.64.0.0', 10, 'ipv4'], ['127.0.0.0', 8, 'ipv4'],
+  ['169.254.0.0', 16, 'ipv4'], ['172.16.0.0', 12, 'ipv4'], ['192.168.0.0', 16, 'ipv4'],
+  ['::', 128, 'ipv6'], ['::1', 128, 'ipv6'], ['fc00::', 7, 'ipv6'], ['fe80::', 10, 'ipv6']
+];
+// Network interfaces change (Wi-Fi, VPN), but reading them on every request would be wasteful.
+const NETWORKS_TTL_MS = 60_000;
+
+/**
+ * @typedef {Object} ServerSignal
+ * @property {'host'|'client'} kind - What gave the server away: the public host name the request
+ *   was sent to, or the public client address behind a proxy
+ * @property {string} value - That host name or address
+ */
+
+/**
+ * Classifies requests as local development or server traffic.
+ *
+ * Keeps the networks this machine is on (refreshed every minute), since addresses on them are
+ * local too.
+ */
+export class TrafficClassifier {
+  /**
+   * The machine's networks are read on first use, not here.
+   */
+  constructor() {
+    this._networks = null;
+    this._networksAt = 0;
+  }
+
+  /**
+   * @param {import('http').IncomingMessage} req
+   * @returns {ServerSignal|null} What shows the request came to a server, or null when it is local
+   */
+  serverSignal(req) {
+    const headers = req.headers || {};
+    const hosts = [headers.host, first(headers['x-forwarded-host']), ...forwardedValues(headers.forwarded, 'host')]
+      .map(hostnameOf)
+      .filter(Boolean);
+
+    // A tunnel brings outside requests (webhooks, a shared link) to a developer's machine.
+    if (hosts.some(isTunnel)) return null;
+
+    const publicHost = hosts.find((host) => !this.isLocalHostname(host));
+    if (publicHost) return { kind: 'host', value: publicHost };
+
+    // Proxies often rewrite Host (nginx sends the upstream address by default), but the client
+    // address still shows where the request came from.
+    const clients = [
+      req.socket && req.socket.remoteAddress,
+      ...list(headers['x-forwarded-for']),
+      first(headers['x-real-ip']),
+      ...forwardedValues(headers.forwarded, 'for')
+    ];
+    for (const client of clients) {
+      const ip = ipOf(client);
+      if (ip && !this.isLocalAddress(ip)) return { kind: 'client', value: ip };
+    }
+    return null;
+  }
+
+  /**
+   * @param {string} hostname - Host name or address, without the port
+   * @returns {boolean} Whether the name only makes sense in local development
+   */
+  isLocalHostname(hostname) {
+    const host = String(hostname).toLowerCase().replace(/\.$/, '');
+    if (!host || host === 'localhost') return true;
+    if (net.isIP(host)) return this.isLocalAddress(host);
+    if (!host.includes('.')) return true;
+    return LOCAL_SUFFIXES.some((suffix) => host.endsWith(suffix)) || isTunnel(host);
+  }
+
+  /**
+   * @param {string} address - IPv4 or IPv6 address
+   * @returns {boolean} Whether the address is private, loopback, or on one of this machine's networks
+   */
+  isLocalAddress(address) {
+    const ip = unmapIPv4(address);
+    const family = net.isIP(ip);
+    if (!family) return false;
+    return this._localNetworks().check(ip, family === 6 ? 'ipv6' : 'ipv4');
+  }
+
+  // Private ranges plus the networks this machine is on (e.g. public IPv6 addresses on home Wi-Fi).
+  _localNetworks() {
+    if (this._networks && Date.now() - this._networksAt < NETWORKS_TTL_MS) return this._networks;
+    const list = new net.BlockList();
+    for (const [address, prefix, type] of PRIVATE_SUBNETS) list.addSubnet(address, prefix, type);
+    try {
+      for (const iface of Object.values(os.networkInterfaces()).flat()) {
+        if (!iface || !iface.cidr) continue;
+        const [address, prefix] = iface.cidr.split('/');
+        const type = net.isIP(address) === 6 ? 'ipv6' : 'ipv4';
+        list.addSubnet(address.split('%')[0], Number(prefix), type);
+      }
+    } catch (error) {
+      // Interface details are optional: private ranges still apply.
+    }
+    this._networks = list;
+    this._networksAt = Date.now();
+    return list;
+  }
+}
+
+function isTunnel(host) {
+  return TUNNEL_SUFFIXES.some((suffix) => host.endsWith(suffix));
+}
+
+// "host:port", "[::1]:port" or a bare host -> host name or address, without the port.
+function hostnameOf(value) {
+  if (typeof value !== 'string') return '';
+  const host = value.trim().toLowerCase();
+  if (host.startsWith('[')) {
+    const end = host.indexOf(']');
+    return end > 0 ? host.slice(1, end) : '';
+  }
+  const colons = host.split(':').length - 1;
+  if (colons === 1) return host.slice(0, host.indexOf(':'));
+  return host; // a bare name, or an IPv6 address without brackets
+}
+
+// Client addresses as proxies write them: "203.0.113.7", "203.0.113.7:51234", "[2001:db8::1]:443".
+function ipOf(value) {
+  if (typeof value !== 'string') return '';
+  let address = value.trim().replace(/^"|"$/g, '');
+  if (address.startsWith('[')) address = address.slice(1, address.indexOf(']'));
+  else if (address.split(':').length === 2) address = address.slice(0, address.indexOf(':'));
+  address = unmapIPv4(address.split('%')[0]);
+  return net.isIP(address) ? address : '';
+}
+
+// "::ffff:192.168.1.7" (IPv4 on a dual-stack socket) -> "192.168.1.7"
+function unmapIPv4(address) {
+  const match = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address);
+  return match ? match[1] : address;
+}
+
+// First value of a header that may be repeated or comma-separated.
+function first(value) {
+  const text = Array.isArray(value) ? value[0] : value;
+  return typeof text === 'string' ? text.split(',')[0].trim() : undefined;
+}
+
+// All values of a header that may be repeated or comma-separated.
+function list(value) {
+  const text = Array.isArray(value) ? value.join(',') : value;
+  return typeof text === 'string' ? text.split(',').map((item) => item.trim()).filter(Boolean) : [];
+}
+
+// RFC 7239: Forwarded: for=192.0.2.60;proto=http;host=example.com, for=198.51.100.17
+function forwardedValues(value, key) {
+  const values = [];
+  for (const element of list(value)) {
+    for (const pair of element.split(';')) {
+      const index = pair.indexOf('=');
+      if (index > 0 && pair.slice(0, index).trim().toLowerCase() === key) {
+        values.push(pair.slice(index + 1).trim().replace(/^"|"$/g, ''));
+      }
+    }
+  }
+  return values;
+}