---
name: cybsin
description: Connect two devices of the same application through CybSin (accounts, 6-digit/QR pairing, blind end-to-end encrypted relay). Use whenever an app must exchange data between a phone and a desktop, two phones, a tablet and a kiosk, etc., without the developer running a server. Covers registering the app, the X-App-Key, the client API, the relay protocol, the byte-exact crypto recipe, device identity reporting, and the 402 payment state. Platform code in references/.
---

# CybSin — multi-device connectivity for vibe-coded apps

CybSin (https://cybsin.com) is a rendezvous + blind relay. Two instances of the
**same application**, signed in as the **same end user**, pair with a 6-digit
code (or QR) and then exchange frames through a WebSocket relay. The relay
forwards ciphertext only; the apps encrypt end-to-end with a fixed recipe.

Use this skill when the user's app needs device-to-device communication and
they do not want to build or host a server, NAT traversal or crypto.

## Step 0 — register the application (once)

Every application has its own key and its own plan (14-day trial, then
10 USD/month billed yearly = 120 USD/year per application).

- With the MCP (preferred): call `cybsin_create_app` with `name`, `platforms`
  and the app's **bundle identifiers** (iOS bundle id, Android package, desktop
  app id). It returns `app_key` (`cs_app_…`).
- Without the MCP: ask the user to register at https://cybsin.com/apps/new and
  paste the key, or to create a developer token (Console → Account) so you can
  use the MCP / developer API.

Store the key in the app's configuration. It is **public** (fine to ship in a
binary); it identifies the application, not a user.

## Step 1 — client API (every call carries `X-App-Key`)

Base URL `https://cybsin.com`. Full reference: `references/api.md`.

| Call | Purpose |
|---|---|
| `GET /api/v1/app/status` | plan state — show a message if `active=false` |
| `POST /api/v1/register` / `login` `{email,password,device}` | end-user account scoped to this app → `{token, device_id}` |
| `POST /api/v1/devices` | register/refresh the device identity (see Step 4) |
| `POST /api/v1/pair/new` | host side → `{code, session_id, expires_in, qr}` |
| `POST /api/v1/pair/join {code}` | guest side → `{session_id}` |
| `WS /ws/relay/{session_id}?token=&role=host|guest&app_key=&device_id=` | the relay |

Authenticated calls add `Authorization: Bearer <token>`.

## Step 2 — relay protocol

1. Host connects with `role=host`, guest with `role=guest`.
2. Server sends `{"t":"joined"}` to both when both are present.
3. From then on every frame (binary or text) is forwarded verbatim.
4. Control frames to handle: `{"t":"joined"}`, `{"t":"expired"}`,
   `{"t":"peer_left"}`, `{"t":"error","code":"payment_required"}`.
5. Close codes: 4401 auth, 4402 payment required, 4404 unknown/expired session,
   4408 timed out waiting for peer, 4409 slot taken.
6. Binary frames ≤ 4 MiB; chunk larger payloads. Nothing is stored server-side.

## Step 3 — end-to-end encryption (MUST be byte-exact)

See `references/crypto.md` for the recipe and test vectors. Summary:

- On `joined`: ephemeral X25519 key pair, send the 32-byte public key as one
  binary frame.
- `key = HKDF-SHA256(ikm=X25519(our_priv, their_pub), salt=code_ascii, info="cybsin-v1", len=32)`
- ChaCha20-Poly1305 (IETF), implicit nonce `[dir,0,0,0,u64_be counter]`,
  host dir=1, guest dir=2, counter from 0 per direction. Wire = `ciphertext||tag`.
- SAS = first 4 bytes of `SHA-256(host_pub||guest_pub)` shown as `A7F3 · 9C21`
  on both screens.
- Any decryption failure is fatal: close the socket.

Your own application protocol (JSON messages, file chunks, commands…) goes
**inside** the encrypted frames.

## Step 4 — report device identity

On `register`/`login`/`devices` send what the platform exposes: `name`,
`platform`, `model`, `os_version`, `vendor_id` (iOS `identifierForVendor`),
`android_id`, `mac` (desktop only; mobile does not expose it), `hostname`,
`os_user`, `bundle_id` (**required** when the app uses strict identity),
`app_version`, `locale`. The developer sees devices and a connection log
(who paired with whom, when, from which IPs, how many bytes) in the console.

## Step 5 — handle the 402 state

When the developer's plan lapsed, `pair/new`/`pair/join` return HTTP 402
`{"detail":{"code":"payment_required",…}}` and the relay closes with 4402.
Sign-in keeps working. Show a human message ("the connection service for this
app needs renewal") and do not retry in a loop. Check `GET /api/v1/app/status`
at launch.

## Step 6 — test

- `cybsin_create_test_user` (MCP) or Console → application → "Create a test
  user" gives credentials + token. Sign in from both builds with them.
- Pair with the code; verify the SAS matches on both screens; send a frame
  each way; disconnect one side and confirm the other gets `peer_left`.
- Look at Console → application → Connection log: the session must appear
  with both devices, IPs, frames and bytes.

## Platform references

- Swift / iOS / macOS (CryptoKit, URLSessionWebSocketTask): `references/swift.md`
- Rust (tungstenite, x25519-dalek, chacha20poly1305, hkdf): `references/rust.md`
- Python (websockets, cryptography): `references/python.md`
- TypeScript / Node / browser (WebCrypto has no X25519 everywhere → @noble): `references/typescript.md`
- Kotlin / Android (OkHttp, Tink or BouncyCastle): `references/kotlin.md`
- Flutter / Dart (web_socket_channel, cryptography package): `references/flutter.md`

## Rules

- Never log tokens, keys or plaintext.
- Never share one app key between two products; register each one.
- Same user on both devices is a feature: do not add cross-account pairing.
- Keep the crypto recipe identical across all your clients; if two clients
  cannot decrypt each other, compare nonce direction and counters first.
- The MCP endpoint is `https://cybsin.com/mcp` (Streamable HTTP) with
  `Authorization: Bearer cs_dev_…`; `cybsin_integration_guide` works without a token.
