Référence de l'API

GraphQL entre appareils

Requêtes signées et chiffrées entre appareils appairés.

key = Base64Decode(peer.key)Pair associé ; c-id = senderClientId

Client
https://<host>:<port>/peer_graphql
Serveur

POST /peer_graphql

c-id: 706c6169-3b80-8f42-9a61-4e312e54d001

HTTP · binary

JSON({ signature, requestId, query, variables })

Vérifiez la signature de l’appareil avant d’exécuter la requête. UUIDv7 : ±60 secondes, avec déduplication persistante.

XChaCha20-Poly1305 · Survoler ou toucher un champ
1 / 2

Protection anti-rejeu

requestId = UUIDv7()JSON { signature, requestId, query, variables } → authenticated encryption
↓ POST /peer_graphql
Authentifier et déchiffrerpeer.key / channel.key + Ed25519✕ → Rejeter
↓
Vérifier la date UUIDv7|serverTime − requestId timestamp| ≤ 60 s✕ → Rejeter
↓
Enregistrer requestId avant exécutionSQLite: peer_graphql:channelId + senderClientId + requestId
✓ ↓Exécuter GraphQL
✕ ↓Rejeter les requestId réutilisés
Appels de bibliothèque

Extraits du noyau, mode direct entre pairs associés (sans c-cid).

text
// plain-rs/src/infrastructure/transport/contract.rs
let payload = contract::signed_request(&signing_keypair, query, variables, "")?;
let request_body = http_request::encrypt_raw(
    &peer_key, "POST", "/peer_graphql", payload.as_bytes(),
).ok_or("encrypt failed")?;
let response = transport.post(url, &client_id, None, &request_body).await?;
let plaintext = http_response::Context::new(&request_body)
    .decrypt(&peer_key, &response).ok_or("invalid response")?;

HTTP 403 : pair non associé. 401 : pair inconnu, échec du déchiffrement ou de la signature. 400 : enveloppe mal formée, expirée ou répétée.

Définitions de types

graphql
enum ChannelSystemMessageType {
	INVITE
	INVITE_ACCEPT
	INVITE_DECLINE
	UPDATE
	KICK
	LEAVE
}

type ChatAttachment {
	id: ID!
	uri: String!
	size: Long!
	durationMs: Long!
	width: Int!
	height: Int!
	summary: String!
	fileName: String!
}

enum ChatAttachmentType {
	IMAGE
	FILE
}

union ChatContent = ChatMessageContent | ChatShareContent

type ChatDeliveryResult {
	peerId: ID!
	peerName: String!
	error: String
}

type ChatItem {
	"""
	`me` when this device created the item, otherwise the client id of
	the originating peer.
	"""
	fromId: ID!
	"""
	Peer id for direct messages; empty for channel messages —
	`channelId` is authoritative there.
	"""
	toId: ID!
	"""
	Null for direct messages: the store keeps "" and the contract says
	null, because "" is not a channel a client can query.
	"""
	channelId: ID
	id: ID!
	content: ChatContent!
	createdAt: Instant!
	updatedAt: Instant!
	status: ChatStatus!
	deliveryResults: [ChatDeliveryResult!]!
}

type ChatLinkPreview {
	url: String!
	title: String
	description: String
	image: String
	imageWidth: Int!
	imageHeight: Int!
	siteName: String
	domain: String
	createdAt: Instant!
}

type ChatMessageAttachment {
	type: ChatAttachmentType!
	attachment: ChatAttachment!
}

type ChatMessageContent {
	text: String
	format: ChatTextFormat!
	items: [ChatMessageAttachment!]!
	linkPreviews: [ChatLinkPreview!]!
}

type ChatShareContent {
	shareId: ID!
	urlToken: String!
	peerInfo: ChatSharePeer!
	name: String!
	itemCount: Long!
	totalSize: Long!
	expiresAt: Instant
}

type ChatSharePeer {
	id: ID!
	ip: String!
	port: Int!
}

enum ChatStatus {
	SENT
	FAILED
	PARTIAL
	PENDING
}

enum ChatTextFormat {
	PLAIN
	MARKDOWN
}

scalar Instant

scalar Long

type Mutation {
	createChatItem(content: String!): [ChatItem!]!
	channelSystemMessage(type: ChannelSystemMessageType!, payload: String!): Boolean!
	startAware: Boolean!
}

enum PeerStatus {
	PAIRED
	UNPAIRED
	CHANNEL
}

type Query {
}

"""
Directs the executor to include this field or fragment only when the `if` argument is true.
"""
directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
"""
Directs the executor to skip this field or fragment when the `if` argument is true.
"""
directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
schema {
	query: Query
	mutation: Mutation
}