Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

10.6 KB
Raw Blame
import 'dart:typed_data';

import '../terminal/terminal_binary.dart';
import 'bytes.dart';
import 'envelope.dart';
import 'keys.dart';
import 'primitives.dart';
import 'replay_window.dart';
import 'terminal_cipher.dart';

/// The client end of one E2EE session with a remote machine — relayClient.ts `RelaySessionCrypto`.
///
/// On macOS and Linux the harness CLI runs this role for the app and hands it plaintext. Where
/// there is no CLI (iOS, Windows) the app runs it itself, against the same machine code that
/// answers the CLI and the web client — to the machine, this app IS such a client.
///
/// One per connection: `e2e_hello` → `e2e_welcome` sets up the keys, and a reconnect is a new
/// ephemeral, new keys and fresh counters.
class RelaySessionCrypto {
  RelaySessionCrypto._(
    this.machineId,
    this._identity,
    this._peerPub,
    this._eph,
    this._helloSig,
  );

  /// Signs the hello up front, so [helloFrame] is ready the moment the relay acks the select.
  /// [ephemeral] is for tests; production mints a fresh one per connection.
  static Future<RelaySessionCrypto> start({
    required String machineId,
    required E2eeIdentity identity,
    required List<int> peerPub,
    Ephemeral? ephemeral,
  }) async {
    if (ephemeral != null) {
      return RelaySessionCrypto._(
        machineId,
        identity,
        Uint8List.fromList(peerPub),
        ephemeral,
        await helloSig(identity, machineId, ephemeral.pub),
      );
    }
    // The key and its signature on a background isolate — see [mintHello].
    final minted = await mintHello(identity, machineId);
    return RelaySessionCrypto._(
      machineId,
      identity,
      Uint8List.fromList(peerPub),
      minted.eph,
      minted.sig,
    );
  }

  final String machineId;
  final E2eeIdentity _identity;
  final Uint8List _peerPub;
  final Ephemeral _eph;
  final Uint8List _helloSig;

  Uint8List? _c2s;
  Uint8List? _s2c;
  Uint8List? _terminalC2s;
  Uint8List? _terminalS2c;
  int _c2sCounter = 0;
  int _terminalC2sCounter = 0;
  final _s2cRecv = ReplayWindow();
  final _terminalS2cRecv = ReplayWindow();
  Uint8List? _groupKey;
  String _epoch = '';
  final Map<String, int> _groupRecv = {};
  int _terminalP2pVersion = 0;
  bool _strictDown = false;

  bool get ready => _c2s != null && _s2c != null;

  /// The machine's `features.strictDown`: it opens a sealed request of any type and refuses
  /// [strictDownTypes] unsealed, so those go sealed to it.
  bool get strictDown => _strictDown;

  /// The machine's `features.terminalP2p` — 0 when it offers no P2P terminal channel.
  int get terminalP2pVersion => _terminalP2pVersion;

  Map<String, dynamic> helloFrame() => {
    'type': 'e2e_hello',
    'payload': {
      'identityPub': b64e(_identity.pub),
      'ephPub': b64e(_eph.pub),
      'sig': b64e(_helloSig),
    },
  };

  /// Takes the machine's `e2e_welcome`; true once the session is usable. False means the machine
  /// did not prove it holds the identity this app pinned for it, or the welcome did not open.
  ///
  /// ⚠️ **One welcome per session.** Once one has made the session usable, any other is refused
  /// and changes nothing. A welcome is signed but not fresh: the relay can hand the same one back
  /// at any time, and taking it again reset the group key to the one it carried — undoing every
  /// `e2e_rekey` since, which is how the machine locks out a client it revoked. That client still
  /// holds the old key, and could then write into this session's view.
  Future<bool> handleWelcome(Map<String, dynamic> payload) async {
    if (ready) return false;
    try {
      final adapterEphPub = _bytesField(payload, 'ephPub');
      final sig = _bytesField(payload, 'sig');
      final enc = _bytesField(payload, 'enc');
      if (adapterEphPub == null || sig == null || enc == null) return false;
      // Verified, keyed and opened on a background isolate — see [openWelcome].
      final keys = await openWelcome(
        eph: _eph,
        peerPub: _peerPub,
        machineId: machineId,
        adapterEphPub: adapterEphPub,
        sig: sig,
        enc: enc,
      );
      if (keys == null) return false;
      // Still the one welcome: nothing else can have made the session while that was away.
      if (ready) return false;
      final opened = keys.initial;
      final initial = opened == null ? null : jsonObjectOf(opened);
      final groupKey = initial?['groupKey'], epoch = initial?['epoch'];
      if (groupKey is! String || groupKey.isEmpty || epoch is! String || epoch.isEmpty) {
        return false;
      }
      _groupKey = b64d(groupKey);
      _epoch = epoch;
      _c2s = keys.c2s;
      _s2c = keys.s2c;
      _terminalC2s = deriveTerminalBinaryKey(keys.c2s);
      _terminalS2c = deriveTerminalBinaryKey(keys.s2c);
      final features = initial!['features'];
      final p2p = features is Map ? features['terminalP2p'] : null;
      _terminalP2pVersion = p2p is int ? p2p : 0;
      _strictDown = features is Map && features['strictDown'] == 1;
      return true;
    } on FormatException {
      return false;
    } on ArgumentError {
      return false;
    }
  }

  /// Takes an `e2e_rekey` — the machine rotated its group key, which it does when it revokes a
  /// client. False when it does not open.
  ///
  /// ⚠️ Held to the same replay window as every other frame under [_s2c]: the machine seals a
  /// rekey with the very counter its pairwise frames take (manager.ts `rotateGroupKey`), so one
  /// seen before is one replayed. Unchecked, the relay could hand back an OLD rekey after a newer
  /// one and roll the group key back to one a revoked client still holds.
  bool handleRekey(Map<String, dynamic> payload) {
    final s2c = _s2c;
    final n = payload['n'], enc = payload['enc'];
    if (s2c == null || n is! int || enc is! String || enc.isEmpty) return false;
    if (!_s2cRecv.allows(n)) return false;
    try {
      final opened = aeadOpen(s2c, n, utf8Bytes('e2e-rekey'), b64d(enc));
      final next = opened == null ? null : jsonObjectOf(opened);
      final groupKey = next?['groupKey'], epoch = next?['epoch'];
      if (groupKey is! String || groupKey.isEmpty || epoch is! String || epoch.isEmpty) {
        return false;
      }
      _groupKey = b64d(groupKey);
      _epoch = epoch;
      _s2cRecv.commit(n);
      return true;
    } on FormatException {
      return false;
    }
  }

  /// Seals the payload of a frame whose type must not cross the relay in the clear; any other
  /// frame goes as it is.
  Map<String, dynamic> wrapOutgoing(Map<String, dynamic> frame) {
    final type = frame['type'], c2s = _c2s;
    if (type is! String ||
        c2s == null ||
        !sealsDown(type, strictDown: _strictDown)) {
      return frame;
    }
    final payload = wrapPayload(c2s, 'p', _c2sCounter++, type, null, frame['payload']);
    return {...frame, 'payload': payload};
  }

  /// The frame with its payload opened; a frame that was never sealed passes as it is. Null means
  /// drop it — stale, replayed or not authentic — and never hand it on.
  Map<String, dynamic>? unwrapIncoming(Map<String, dynamic> frame) {
    final payload = frame['payload'];
    if (payload is! Map || !isWrapped(payload)) return frame;
    final env = payload['__e2e'], type = frame['type'];
    if (env is! Map<String, dynamic> || type is! String) return null;
    final n = env['n'];
    if (n is! int) return null;
    final dbSessionId = frame['dbSessionId'] as String?;
    if (env['k'] == 'g') {
      final groupKey = _groupKey, epoch = env['epoch'];
      if (groupKey == null || epoch != _epoch) return null;
      if (n <= (_groupRecv[_epoch] ?? -1)) return null;
      final clear = unwrapPayload(groupKey, env, type, dbSessionId);
      if (clear == null) return null;
      _groupRecv[_epoch] = n;
      return {...frame, 'payload': clear};
    }
    final s2c = _s2c;
    if (s2c == null || !_s2cRecv.allows(n)) return null;
    final clear = unwrapPayload(s2c, env, type, dbSessionId);
    if (clear == null) return null;
    _s2cRecv.commit(n);
    return {...frame, 'payload': clear};
  }

  /// [unwrapIncoming], with a large envelope opened on a background isolate
  /// ([unwrapPayloadOffThread]) — a machine's agent list, a transcript. Anything smaller is
  /// [unwrapIncoming] itself.
  ///
  /// ⚠️ **The replay window is checked before and again after.** Before, so a stale or replayed
  /// frame is not worth an isolate; after, because only an opened frame may be committed. Frames
  /// reach this one at a time (`WsConn`'s inbound chain awaits each), so nothing else moves the
  /// window or the epoch in between — the second check is a guard, not a race being won.
  Future<Map<String, dynamic>?> unwrapIncomingOffThread(
    Map<String, dynamic> frame,
  ) async {
    final payload = frame['payload'];
    if (payload is! Map || !isWrapped(payload)) return frame;
    final env = payload['__e2e'], type = frame['type'];
    if (!opensOffThread(env)) return unwrapIncoming(frame);
    if (env is! Map<String, dynamic> || type is! String) return null;
    final n = env['n'];
    if (n is! int) return null;
    final dbSessionId = frame['dbSessionId'] as String?;
    if (env['k'] == 'g') {
      final groupKey = _groupKey, epoch = env['epoch'];
      if (groupKey == null || epoch != _epoch) return null;
      if (n <= (_groupRecv[_epoch] ?? -1)) return null;
      final clear = await unwrapPayloadOffThread(
        groupKey,
        env,
        type,
        dbSessionId,
      );
      if (clear == null || epoch != _epoch) return null;
      if (n <= (_groupRecv[_epoch] ?? -1)) return null;
      _groupRecv[_epoch] = n;
      return {...frame, 'payload': clear};
    }
    final s2c = _s2c;
    if (s2c == null || !_s2cRecv.allows(n)) return null;
    final clear = await unwrapPayloadOffThread(s2c, env, type, dbSessionId);
    if (clear == null || !_s2cRecv.allows(n)) return null;
    _s2cRecv.commit(n);
    return {...frame, 'payload': clear};
  }

  Uint8List? encryptTerminal(TerminalBinaryFrame frame) {
    final key = _terminalC2s;
    if (key == null) return null;
    final sealed = sealTerminalBinary(key, _terminalC2sCounter, frame);
    if (sealed != null) _terminalC2sCounter++;
    return sealed;
  }

  /// Null means drop — stale, replayed or not authentic.
  TerminalBinaryFrame? decryptTerminal(Uint8List raw) {
    final key = _terminalS2c;
    if (key == null) return null;
    final opened = openTerminalBinary(key, raw);
    if (opened == null || !_terminalS2cRecv.allows(opened.counter)) return null;
    _terminalS2cRecv.commit(opened.counter);
    return opened.frame;
  }
}

Uint8List? _bytesField(Map<String, dynamic> payload, String key) {
  final value = payload[key];
  return value is String && value.isNotEmpty ? b64d(value) : null;
}