Metadata-Version: 2.4
Name: braid-jumpkit
Version: 1.5.3rc2
Summary: Direct-first, relay-capable authenticated WAN sidecar for Intersignal Braid
Author: Intersignal LLC
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: cryptography<50,>=46

# BRAID 1.5.3 — JUMP (RC2)

**Local by default. Remote when invited.**

Jump Kit is an optional sidecar for Braid Core. Core remains local-first, independently usable, and the sole authority for Braid Trust, signed-state validation, quarantine, replay policy, Phase A, Phase B, acceptance, and finality.

RC2 adds a direct-first WAN decision path, deterministic relay fallback, ten-minute Jump Codes, explicit approval, optional authorization expiry, live revocation, end-to-end authenticated encryption, reconnect behavior, and unambiguous `DIRECT`, `RELAYED`, `REJECTED`, and `EXPIRED` receipts. It also replaces the UAT-only equal timeout patches with configurable, hierarchical production defaults.

## Authority boundary

```text
Braid sender
  -> Jump Kit transport envelope
  -> DIRECT candidate when reachable
       or pinned TLS 1.3 relay fallback
  -> receiving Jump Kit agent
  -> exact BTP1 packet on 127.0.0.1:8745
  -> Braid Core validates and decides
  -> exact Braid ACK returns end to end
```

The relay routes opaque ciphertext. It cannot inspect a `.brad` payload, manufacture a valid device envelope, mint an acceptance ACK, enroll a Braid signer, or acquire model authority. A transport success is never a Braid acceptance.

## Path behavior

The receiving agent advertises its relay-observed IP and direct listener port after proving its device identity. The sender tries that candidate first. If the direct connection is unreachable, it repeats the full pinned relay authentication and sends through the relay.

`DIRECT` in RC2 means an authenticated end-to-end direct socket was reached. It does **not** claim automatic ICE/QUIC hole punching or router mapping. Ordinary unrelated NATs will generally select `RELAYED` unless a usable mapping already exists. The public relay path has completed a physical macOS → public relay → Windows UAT; broader topology and cross-platform coverage remains a release gate for GA.

## Timeout model

The defaults are deliberately nested so receiver-side semantic work can finish before an outer transport layer expires:

| Budget | Default | CLI control |
|---|---:|---|
| TCP/TLS connection and relay authentication | 15 s | `--connect-timeout` / relay `--connection-timeout` |
| Direct-path attempt | 3 s | `--direct-timeout` |
| Local Braid receiver processing | 90 s | agent `--upstream-timeout` |
| Relay wait for the agent response | 120 s | relay `--response-timeout` |
| Sender wait for the complete relayed round trip | 150 s | send-peer `--response-timeout` |

If you override these, preserve `upstream < relay response < sender response`. Expiry still fails closed; increasing a transport budget never weakens Braid validation or semantic admission.

## Quick start

Requires Python 3.12 and `cryptography>=46,<50`.

Create relay TLS material, keep the CA key offline after issuance, and run the relay:

```powershell
braid-jumpkit init-ca --out-dir .\relay-certs
braid-jumpkit issue --out-dir .\relay-certs --ca-key .\relay-certs\jumpkit-ca.key.pem --ca-cert .\relay-certs\jumpkit-ca.crt.pem --name relay.example.com --role server --dns relay.example.com
braid-jumpkit relay --bind 0.0.0.0 --port 8750 --cert .\relay-certs\jumpkit-server-relay.example.com.crt.pem --key .\relay-certs\jumpkit-server-relay.example.com.key.pem --relay-token-file .\relay-token.txt --response-timeout 120
```

Create a device and a short-lived Jump Code:

```powershell
braid-jumpkit init-device --name "Studio PC" --identity-file .\studio-device.json
braid-jumpkit pair-code --identity-file .\studio-device.json --ttl-seconds 600
```

Exchange codes through a trusted channel, compare the four groups, then approve each direction. An optional authorization lifetime can be set independently of the code lifetime:

```powershell
braid-jumpkit pair-approve <jump-code> --identity-file .\studio-device.json --access-seconds 86400
```

Start Braid Core on IPv4 loopback port 8745, then keep the sidecar online:

```powershell
braid-jumpkit doctor --upstream-host 127.0.0.1 --upstream-port 8745
braid-jumpkit agent --identity-file .\studio-device.json --relay-host relay.example.com --relay-ca .\jumpkit-ca.crt.pem --relay-server-name relay.example.com --relay-fingerprint <sha256> --relay-token-file .\relay-token.txt
```

Send by approved device name:

```powershell
braid-jumpkit send-peer state.brad --to "Studio PC" --identity-file .\laptop-device.json --relay-host relay.example.com --relay-ca .\jumpkit-ca.crt.pem --relay-server-name relay.example.com --relay-fingerprint <sha256> --relay-token-file .\relay-token.txt
```

Revoke without restarting the receiving agent:

```powershell
braid-jumpkit pair-revoke "Laptop" --identity-file .\studio-device.json
```

## Receipts

- `DIRECT`: authenticated direct delivery; the returned Braid ACK was valid.
- `RELAYED`: authenticated relay delivery; the returned Braid ACK was valid.
- `REJECTED`: policy, transport authentication, or Braid Core rejected the operation.
- `EXPIRED`: the Jump Code or approved authorization has expired.
- `CODE ACCEPTED`: the restrained confirmation shown after explicit pairing approval.

## Feedback

Send compatibility reports, failure receipts, and security observations to `hello@intersignal.ai` or use the Braid feedback form:

https://docs.google.com/forms/d/1IGL22mCIlwPTh82KB1Crc69fxrYh-lq1lEsL3lltrHA/

Include the operating system, Python version, Jump Kit version, and redacted logs. Never include relay tokens, private keys, Jump Codes, or sensitive `.brad` objects.

## Release status

This tree is a **public-testing release candidate**, not the `v1.5.3` GA tag. Source distributions are portable Python packages, not native signed installers. Local protocol/integration gates and one physical macOS → public relay → Windows acceptance path pass. Broader WAN interruption, reverse-direction, Linux WAN, native packaging, and public-relay operational gates remain open.
