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.2 KB
Raw Blame
import 'dart:async';
import 'dart:convert';
import 'dart:typed_data';

import 'package:web_socket_channel/web_socket_channel.dart';

import '../e2ee/bytes.dart';
import '../e2ee/cpace.dart';
import '../e2ee/envelope.dart';
import '../e2ee/keys.dart';
import '../e2ee/password_pake.dart';
import '../e2ee/primitives.dart';

/// How far a password link has got — the stages `harness link connect --json` reports, spelled the
/// same (see [wireName]) so the link form shows one progress for either build.
enum PasswordLinkStage {
  connecting('connecting'),
  derivingKey('deriving_key'),
  exchanging('exchanging'),
  verifying('verifying');

  const PasswordLinkStage(this.wireName);

  final String wireName;
}

sealed class PasswordLinkResult {
  const PasswordLinkResult();
}

final class PasswordLinked extends PasswordLinkResult {
  const PasswordLinked(this.peerPub, this.fingerprint);

  /// The machine's identity, to pin.
  final Uint8List peerPub;
  final String fingerprint;
}

final class PasswordLinkFailed extends PasswordLinkResult {
  const PasswordLinkFailed(this.code, {this.retryAt});

  /// The CLI's own code: `WRONG_PASSWORD`, `TIMEOUT`, or whatever the machine refused with.
  final String code;

  /// When a locked-out password may be tried again, if the machine said.
  final DateTime? retryAt;
}

typedef RelaySocketFactory = WebSocketChannel Function(
  Uri uri,
  Iterable<String> protocols,
);

WebSocketChannel defaultRelaySocket(Uri uri, Iterable<String> protocols) =>
    WebSocketChannel.connect(uri, protocols: protocols);

/// relayClient.ts `connectWithPassword`: over a short-lived relay socket, prove to [machineId] that
/// this device knows its `harness remote-password`, and learn the identity to pin for it. Nobody
/// approves anything on the machine — knowing the password is the approval.
///
/// [timeout] is twice the CLI's 15s: the stretch inside it is about a second on a laptop and can be
/// several on a phone, and a link that fails for being slow reads exactly like a wrong password.
Future<PasswordLinkResult> linkWithPassword({
  required String machineId,
  required String password,
  required E2eeIdentity identity,
  required String accessToken,
  required String wsBaseUrl,
  required String autonomousEnv,
  void Function(PasswordLinkStage stage)? onProgress,
  String? label,
  RelaySocketFactory socket = defaultRelaySocket,
  Duration timeout = const Duration(seconds: 30),
}) async {
  onProgress?.call(PasswordLinkStage.connecting);
  // It says what it is (`?client=`; backend lib/wsAttribution.ts, WebSocket roadmap Phase 0).
  final uri = Uri.parse('$wsBaseUrl/api/web-ws').replace(
    queryParameters: {'autonomousEnv': autonomousEnv, 'client': 'link'},
  );
  final channel = socket(uri, [accessToken]);
  final run = _PasswordLinkRun(
    machineId,
    password,
    identity,
    channel,
    onProgress,
    label,
  );
  try {
    // ⚠️ The dial is inside the timeout, not in front of it: a socket dialled into a network
    // that swallows packets waits out the OS's own TCP timeout — over a minute on iOS — and the
    // form said "connecting" for all of it.
    return await () async {
      await channel.ready;
      return run.drive();
    }().timeout(timeout, onTimeout: () => const PasswordLinkFailed('TIMEOUT'));
  } catch (_) {
    return const PasswordLinkFailed('CONNECTION_ERROR');
  } finally {
    unawaited(channel.sink.close());
  }
}

const _wrongPassword = PasswordLinkFailed('WRONG_PASSWORD');

/// The joiner ('b') side of the machine's `onPwPairIntent`/`onPwPake` state machine.
class _PasswordLinkRun {
  _PasswordLinkRun(
    this.machineId,
    this.password,
    this.identity,
    this.channel,
    this.onProgress,
    this.label,
  );

  final String machineId;
  final String password;
  final E2eeIdentity identity;
  final WebSocketChannel channel;
  final void Function(PasswordLinkStage stage)? onProgress;

  /// This phone's name for itself, sealed into round 4 beside its identity — as authenticated as
  /// the key it names — so the computer's list of paired devices reads "Dee's iPhone" rather than
  /// the "harness link" every password pairing used to be filed under. A machine that predates the
  /// field ignores it.
  final String? label;

  final Uint8List _sid = secureRandomBytes(16);
  late final String _sidB64 = b64e(_sid);
  final String _requestId = b64e(secureRandomBytes(16));
  late final String _ci = pwContext(machineId);
  bool _selected = false;
  Uint8List? _stretched;
  Uint8List? _isk;
  Uint8List? _transcript;
  Uint8List? _machinePub;

  Future<PasswordLinkResult> drive() async {
    _send('machine_select', {'machineId': machineId});
    await for (final raw in channel.stream) {
      final frame = raw is String ? jsonObjectOf(utf8Bytes(raw)) : null;
      if (frame == null) continue;
      final PasswordLinkResult? result;
      try {
        result = await _step(frame);
      } catch (_) {
        // Anything this side cannot parse or verify is the protocol failing, as in the CLI.
        return const PasswordLinkFailed('PROTOCOL_ERROR');
      }
      if (result != null) return result;
    }
    return PasswordLinkFailed('CONNECTION_CLOSED:${channel.closeCode}');
  }

  Future<PasswordLinkResult?> _step(Map<String, dynamic> frame) async {
    final type = frame['type'];
    final payload = frame['payload'] is Map<String, dynamic>
        ? frame['payload'] as Map<String, dynamic>
        : const <String, dynamic>{};
    if (!_selected) {
      if (payload['machineId'] != machineId) return null;
      if (type == 'connected') return _sendIntent();
      if (type == 'machine_select_error') {
        return PasswordLinkFailed(_codeOr(payload['error'], 'SELECT_FAILED'));
      }
      return null;
    }
    if (type == 'e2e_pw_pair_result' && payload['requestId'] == _requestId) {
      return payload['ok'] == true ? null : _refused(payload);
    }
    if (type != 'e2e_pw_pake' || payload['sid'] != _sidB64) return null;
    final error = payload['error'];
    return switch (payload['round']) {
      1 when error != null => PasswordLinkFailed('$error'),
      1 => _answerShare(payload),
      3 when error != null => PasswordLinkFailed('$error'),
      3 => await _answerIdentity(payload),
      5 => _finish(payload),
      _ => null,
    };
  }

  Future<PasswordLinkResult?> _sendIntent() async {
    _selected = true;
    onProgress?.call(PasswordLinkStage.derivingKey);
    try {
      _stretched = await stretchPassword(password, machineId);
    } catch (_) {
      return const PasswordLinkFailed('DERIVE_FAILED');
    }
    onProgress?.call(PasswordLinkStage.exchanging);
    _send('e2e_pw_pair_intent', {'requestId': _requestId, 'sid': _sidB64});
    return null;
  }

  /// Round 1 in, round 2 out: our CPace share, and a MAC only the right password could have made.
  PasswordLinkResult? _answerShare(Map<String, dynamic> payload) {
    final stretched = _stretched;
    if (stretched == null) return null;
    final theirs = b64d(payload['ya'] as String);
    final ours = cpaceStart(pwCpaceGenerator(stretched, _sid, _ci));
    final isk = _isk = cpaceIsk(
      _sid,
      cpaceShared(theirs, ours.scalar),
      theirs,
      ours.share,
    );
    final transcript = _transcript = transcriptHash(
      _sid,
      _ci,
      theirs,
      ours.share,
    );
    onProgress?.call(PasswordLinkStage.verifying);
    _send('e2e_pw_pake', {
      'sid': _sidB64,
      'round': 2,
      'yb': b64e(ours.share),
      'mac': b64e(macTag(kcKeys(isk, _ci).web, transcript)),
    });
    return null;
  }

  /// Round 3 in, round 4 out: the machine proves the password too and hands over its identity,
  /// bound to this transcript; ours goes back the same way.
  Future<PasswordLinkResult?> _answerIdentity(
    Map<String, dynamic> payload,
  ) async {
    final isk = _isk, transcript = _transcript;
    if (isk == null || transcript == null) {
      return const PasswordLinkFailed('PROTOCOL_ERROR');
    }
    final mac = b64d(payload['mac'] as String);
    if (!macVerify(kcKeys(isk, _ci).adapter, transcript, mac)) {
      return _wrongPassword;
    }
    final key = pairKey(isk, _ci);
    final opened = aeadOpen(
      key,
      3,
      utf8Bytes('e2e-id'),
      b64d(payload['enc'] as String),
    );
    final claim = opened == null ? null : jsonObjectOf(opened);
    final id = claim?['id'], sig = claim?['sig'];
    if (id is! String || sig is! String) return _wrongPassword;
    final machinePub = b64d(id);
    if (!await pairBindVerify(machinePub, transcript, b64d(sig))) {
      return _wrongPassword;
    }
    _machinePub = machinePub;
    final ours = jsonEncode({
      'id': b64e(identity.pub),
      'sig': b64e(await pairBindSig(identity, transcript)),
      if (label case final label? when label.trim().isNotEmpty) 'label': label,
      // A viewer, not a machine: it dials out and is never dialed, so the machine trusts it and
      // does not pin it back. A machine that predates the field ignores it.
      'kind': 'viewer',
    });
    _send('e2e_pw_pake', {
      'sid': _sidB64,
      'round': 4,
      'enc': b64e(aeadSeal(key, 4, utf8Bytes('e2e-id'), utf8Bytes(ours))),
    });
    return null;
  }

  /// The fingerprint is computed here rather than taken from the frame, unlike the CLI: round 5
  /// crosses the relay in the clear, and the pinned key is the thing it must describe.
  ///
  /// A refusal here carries its `retryAt` as one at the intent does: the machine judges its
  /// lockout again at round 2 (manager.ts `onPwPake`), and says until when on round 5.
  PasswordLinkResult _finish(Map<String, dynamic> payload) {
    final machinePub = _machinePub;
    if (payload['ok'] != true || machinePub == null) return _refused(payload);
    return PasswordLinked(machinePub, fingerprint(machinePub));
  }

  PasswordLinkFailed _refused(Map<String, dynamic> payload) {
    final retryAt = payload['retryAt'];
    return PasswordLinkFailed(
      _codeOr(payload['error'], 'PAIR_FAILED'),
      retryAt: retryAt is int
          ? DateTime.fromMillisecondsSinceEpoch(retryAt)
          : null,
    );
  }

  void _send(String type, Map<String, Object> payload) =>
      channel.sink.add(jsonEncode({'type': type, 'payload': payload}));
}

String _codeOr(Object? value, String fallback) =>
    value is String && value.isNotEmpty ? value : fallback;