# KPartage — moteur de partage Berkios

Source : https://docs.berkios.online/modules/kpartage/ · Section : Modules · Documentation officielle BERKIOS (https://docs.berkios.online)


KPartage est la bibliothèque **principale** de la famille de partage Berkios. Elle fournit, une fois pour toutes, ce que
toute application de partage (comme KIROSIS SENDER) doit réimplémenter sinon : identité des appareils, appairage sûr,
favoris, mode de réception, offres, boîte de réception, historique, vérification d'intégrité.

| Bibliothèque | Rôle | État |
|---|---|---|
| **KPartage** | Moteur et commandes `partage-*` | ✅ cette livraison |
| KConnect | Découverte et transport IP (Wi-Fi, Ethernet, hotspot / Wi-Fi Direct une fois établis par le système) ; Bluetooth : hôte requis | ✅ livré, voir `../kconnect/` |
| KTransfer | Transfert multi-fichiers, reprise, SHA-256 (fournit `fetch`) | à venir |

> **Limite à connaître** : KPartage seul ne fait circuler aucun octet sur un réseau. Il décide *qui* peut envoyer *quoi* à
> *qui*, signe et vérifie les messages, et suit l'état de chaque partage. Le texte et le presse-papiers passent
> directement dans les messages ; les fichiers, dossiers et applications sont **décrits** (nom, taille, SHA-256) puis
> transférés par KTransfer. En attendant, un transport en mémoire (`MemoryHub`) et des **appareils simulés** (ou KConnect pour de vrais appareils d'un même réseau) permettent de
> développer et tester une application complète sur une seule machine.

## Concepts

- **Appareil** : paire X25519 ; identifiant auto-certifiant `kp_…` = hachage de la clé publique (impossible à usurper).
- **Appairage** : on échange les *cartes* (`partage-identite`), puis chaque écran affiche le même **code à 6 chiffres**
  (dérivé de la clé commune). L'utilisateur le compare et le confirme (`partage-appareil-confirmer`) ; un intermédiaire
  ne peut pas produire le même code. 5 essais, puis blocage de 10 min.
- **Confiance** : `verifie` (code confirmé, messages signés HMAC-SHA256), `non-verifie`, `inconnu` (jamais vu : accepté
  seulement en mode `tous`, toujours signalé).
- **Mode de réception** : `inactif` (rien n'entre), `favoris` (seulement les appareils vérifiés *et* favoris), `tous`.
  L'acceptation reste **toujours explicite** : aucune offre n'est acceptée automatiquement.
- **Élément** : `fichier`, `dossier`, `texte`, `presse-papiers`, `application` (apk, exe, msi, dmg, deb, ipa…).
- **Offre** : un ou plusieurs éléments + message, envoyée à un appareil. Cycle côté émetteur :
  `brouillon → envoyee → acceptee → terminee` (ou `refusee`, `annulee`, `expiree`, `echec`, `en-file` si hors ligne).
  Côté récepteur : `en-attente → acceptee → terminee` (ou `refusee`, `annulee`, `expiree`).

## Utilisation en BERKIOS

Toutes les commandes sont listées dans `COMMANDES.md`. Les exemples ci-dessous sont en **notation illustrative** : la syntaxe exacte d'appel et de récupération des résultats dans un script sera fixée par l'intégration compilateur (étape 4) ; les commandes, arguments et résultats, eux, sont définitifs.

Exemple (réception puis envoi) :

```text
partage-reception-activer "favoris"

partage-element-texte "Bonjour !"          -> t
partage-offre-creer [t] {"vers": "kp_…"}   -> o
partage-offre-envoyer o.id
```

Tester sans second appareil :

```text
partage-simulation-creer "Téléphone de test"      -> tel
partage-simulation-envoyer tel.id ["Salut depuis le téléphone"]
partage-recu-lister "en-attente"
```

## Utilisation en JavaScript

```js
import { KPartage, MemoryHub } from './src/index.mjs';

const hub = new MemoryHub();
const a = new KPartage({ workspace: './a', nom: 'Alice' });
const b = new KPartage({ workspace: './b', nom: 'Bob' });
a.attacherTransport(hub.attach(a)); b.attacherTransport(hub.attach(b));

const codeA = a.enregistrerAppareil(b.carte()).codeAppairage;   // à comparer sur les deux écrans
const codeB = b.enregistrerAppareil(a.carte()).codeAppairage;
a.confirmerAppareil(b.id, codeB); b.confirmerAppareil(a.id, codeA);

b.activerReception('tous');
const offre = a.creerOffre({ items: [await a.elementTexte('Salut')], vers: b.id });
await a.envoyerOffre(offre.id);
await b.accepter(b.recus()[0].id);
```

Événements (`on`) : `offre-recue`, `recu-accepte`, `recu-refuse`, `recu-termine`, `recu-annule`, `element-recu`,
`offre-acceptee`, `offre-refusee`, `offre-terminee`, `offre-echec`, `offre-annulee`, `appareil-ajoute`,
`appareil-verifie`, `reception-changee`.

## Contrat du transport (KConnect / KTransfer)

```js
transport = {
  nom: 'wifi',
  async send(deviceId, enveloppeTexte, { appareil }) { return { ok: true }; },  // ou { ok:false, code } / exception
  onReceive(handler) { /* appeler handler(enveloppeTexte) à chaque message reçu */ },
  async fetch({ offre, de, element, cibleAbs, workspace }) { /* écrire l'élément à cibleAbs, sans écraser */ },
};
```

Le moteur n'a pas confiance dans le transport : chaque message est décodé, assaini et (pour un pair vérifié) sa signature
est contrôlée. Un transport qui écrit lui-même les fichiers appelle `marquerElementRecu(offre, élément)` (commande
`partage-recu-element-terminer`) : taille et SHA-256 sont **revérifiés**, un fichier altéré passe à `corrompu`.

## Sécurité — ce qui est garanti, et ce qui ne l'est pas

Garanti et testé : confinement au workspace (pas de `..`, pas de lien symbolique sortant, pas de chemin absolu), aucun
écrasement (`nom (1).ext`), assainissement des noms (Windows réservés, `:`, bidi…) et des chemins de dossiers reçus,
tailles et empreintes recalculées ou validées, limites (éléments, taille, boîte de réception, historique), rejeu écarté,
secrets (clé privée, clés de lien) jamais renvoyés par une commande et stockés **hors** du workspace avec droits `0600`,
éléments non forgeables (une offre ne référence que des éléments créés localement).

Non garanti : la confidentialité du contenu en transit est du ressort du transport (KConnect/KTransfer chiffrera ; le
transport mémoire ne chiffre rien) ; le nom d'un appareil `inconnu` est déclaré par lui — affichez toujours son
`empreinte` ; le presse-papiers du système n'est pas lu par KPartage (l'application fournit le texte).

## Fichiers

`src/engine.mjs` moteur · `src/commands.mjs` commandes (source unique) · `src/protocol.mjs` enveloppes ·
`src/identity.mjs` clés et appairage · `src/items.mjs` éléments · `src/transport.mjs` transport mémoire ·
`src/runtime.mjs` moteur + appareils simulés · `kpartage.manifest.json` (généré : `npm run manifest`).
Tests : `npm test` (Node ≥ 22, aucune dépendance).