Pairing
Check app.capabilities for feature support and app.access plus host permissions for authorization. Examples use synthetic values; replace paths, IDs, inputs and filters before calling.
plainapp://pair?request=<URL-encoded JSON>QR
signature = Base64(Ed25519-Sign(Device A private key, signed))Ed25519-Verify(Device A public key, signed, Base64Decode(signature))Open the JSON segment to inspect the full signed input for this synthetic example; the receiver verifies with the signer’s public key.verificationCode = 73939800digest = SHA256(request.signature encoded as UTF-8)digest (hex) = ff44f60497bc235899f050f272165ec094a2f2c685e776d153a0711424b85dc0number = first 8 digest bytes as an unsigned big-endian integerverificationCode = number mod 100000000, padded to 8 decimal digitsQR: A displays, B scans. LAN c-id identifies the sender; BLE uses its own transport. PAIR_CANCEL is optional.
Synthetic snapshot at a fixed time; signatures and requestIds match. 192.0.2.0/24 is reserved for documentation. 8443 is the default HTTPS port; use the discovered port in real requests. These time-limited requests cannot be replayed as-is.
In PlainApp Desktop, managing a device begins with an explicit Trust decision if the device is new or its public key has changed. This step shows no comparison code and warns you if the key has changed. Next, during passwordless approval, compare the single code shown on both devices before approving on the other device. If you authenticated with a password, the other device may still ask for approval without showing a code.
Type Definitions
type Subscription {
peersChanged: Boolean!
pairingRequested: PairingRequestNotice!
pairingCompleted: PairingCompletedNotice!
pairingStarted: PairingProgressNotice!
pairingFailed: PairingProgressNotice!
pairingCanceled: PairingProgressNotice!
}
type Mutation {
cancelPairing(peerId: ID!): Boolean!
deletePeer(peerId: ID!): Boolean!
pairPeer(peerId: ID!, input: PairPeerInput!): Boolean!
respondToPairing(peerId: ID!, accepted: Boolean!): Boolean!
unpairPeer(peerId: ID!): Boolean!
}
type Query {
peerFileUrl(peerId: ID!, fileId: String!): String!
peers: [Peer!]!
}
enum DeviceType {
COMPUTER
PHONE
TABLET
TV
NAS
OTHER
}
scalar Instant
input PairPeerInput {
mode: PairingMode!
password: String
}
type PairingCompletedNotice {
deviceId: ID!
deviceName: String!
ip: String!
port: Int
deviceType: DeviceType
requestId: String
}
enum PairingErrorCode {
TIMEOUT
REJECTED
PASSWORD_REQUIRED
INVALID_PASSWORD
PEER_IDENTITY_CHANGED
TOO_MANY_LOGIN_ATTEMPTS
INTERNAL_ERROR
}
enum PairingMode {
CHAT
MANAGE
}
type PairingProgressNotice {
verificationCode: String
deviceId: ID!
deviceName: String!
error: PairingErrorCode
}
type PairingRequestNotice {
fromIp: String!
fromId: ID!
fromName: String!
deviceType: DeviceType!
verificationCode: String!
identityChanged: Boolean!
}
type Peer {
id: ID!
name: String!
ip: String!
status: PeerStatus!
port: Int
deviceType: DeviceType!
createdAt: Instant!
updatedAt: Instant!
online: Boolean!
managed: Boolean!
key: String!
publicKey: String!
token: String!
}
enum PeerStatus {
PAIRED
UNPAIRED
CHANNEL
}Operations
peersChanged
Receive a change signal when peer records change.
subscription peersChanged {
peersChanged
}pairingRequested
Receive an incoming pairing request awaiting a decision.
subscription pairingRequested {
pairingRequested { fromIp fromId fromName deviceType verificationCode identityChanged }
}pairingCompleted
Receive notification that device pairing completed.
subscription pairingCompleted {
pairingCompleted { deviceId deviceName ip port deviceType requestId }
}pairingStarted
Receive notification that a pairing attempt started.
subscription pairingStarted {
pairingStarted { verificationCode deviceId deviceName error }
}pairingFailed
Receive notification that a pairing attempt failed.
subscription pairingFailed {
pairingFailed { verificationCode deviceId deviceName error }
}pairingCanceled
Receive notification that a pairing attempt was canceled.
subscription pairingCanceled {
pairingCanceled { verificationCode deviceId deviceName error }
}cancelPairing
Cancel the current pairing for the specified peer.
mutation cancelPairing($peerId: ID!) {
cancelPairing(peerId: $peerId)
}deletePeer
Delete a peer and its one-to-one chat history; retain a channel-only peer when a channel still references it.
mutation deletePeer($peerId: ID!) {
deletePeer(peerId: $peerId)
}pairPeer
Start chat pairing or management login with the specified peer; true acknowledges initiation.
mutation pairPeer($peerId: ID!, $input: PairPeerInput!) {
pairPeer(peerId: $peerId, input: $input)
}respondToPairing
Accept or reject the peer's pending pairing request or trust confirmation.
mutation respondToPairing($peerId: ID!, $accepted: Boolean!) {
respondToPairing(peerId: $peerId, accepted: $accepted)
}unpairPeer
Unpair a peer locally and clear its management access while retaining chat history.
mutation unpairPeer($peerId: ID!) {
unpairPeer(peerId: $peerId)
}peerFileUrl
Build a file download URL using the peer's current stored address.
query peerFileUrl($peerId: ID!, $fileId: String!) {
peerFileUrl(peerId: $peerId, fileId: $fileId)
}peers
List all saved peers, including paired, unpaired and channel-only records.
query peers {
peers { id name ip status port deviceType createdAt updatedAt }
}