Accès agent IA

1. Le principe

Le partage agent IA dédie un dossier ILYGO Safe — comme « Mémoire IA », avec tous ses sous-dossiers — à un agent IA autonome (Claude ou tout autre agent capable de faire des requêtes HTTP), pour qu'il puisse lire et écrire des notes de façon indépendante, sans jamais utiliser un compte humain ni un mot de passe-coffre.

Techniquement, c'est une variante du partage de dossier classique de ILYGO Safe (voir la documentation générale, section « Partager un dossier ») : même chiffrement, même cascade sur les sous-dossiers, même journal d'audit. Ce qui change, c'est uniquement la façon dont l'identifiant d'accès est livré et utilisé — pensée pour un programme plutôt que pour un navigateur.

2. Créer un partage (propriétaire)

Depuis le panneau de partage d'un dossier (authentifié, coffre déverrouillé — exactement comme pour créer un partage utilisateur ou un lien), choisissez le type Agent IA, puis :

• un libellé libre (par exemple « Claude — Projet X ») — il réapparaîtra dans la liste des partages agent du dossier et dans le journal d'audit, pour chaque action que l'agent effectuera ;
• une permission : Écriture par défaut (l'agent doit en général pouvoir organiser sa propre mémoire), ou Lecture pour un accès consultation seule.

Une fois créé, l'application affiche un lien de réclamation — une seule fois, exactement comme un lien de partage classique. Copiez-le immédiatement et transmettez-le à l'agent (dans son prompt, sa configuration, ou tout autre canal que vous contrôlez) : c'est le seul moyen de lui donner accès.

Ensuite, comme pour tout partage : Pause suspend temporairement l'accès sans rien perdre de sa configuration, et Révoquer (derrière une confirmation) le retire définitivement — recréer l'accès demandera un nouveau partage.

Fait notable et volontaire : le propriétaire lui-même ne voit jamais le jeton d'accès de l'agent en clair — seul le lien de réclamation, à usage unique. C'est la même logique que « pas de récupération de mot de passe-coffre » (voir Documentation, « Coffre & sécurité ») : un secret que même le propriétaire ne peut pas relire est un secret plus sûr.

3. Réclamer l'accès (agent)

L'agent effectue une seule requête GET vers l'URL de réclamation reçue de son propriétaire — aucun corps JSON à construire, aucune authentification préalable :

GET /api/agent-share/claim/{claimToken}

Cette requête ne peut réussir qu'une seule fois : le jeton de réclamation est consommé immédiatement. Un deuxième appel avec le même lien — ou un lien expiré (48h sans être réclamé), révoqué, ou inconnu — renvoie une erreur 404 identique dans les trois cas.

En cas de succès, la réponse (jamais mise en cache) contient le jeton d'accès durable :

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json

{
  "accessToken": "kQ3f-9m2Zp...  (chaîne longue, aléatoire)",
  "folderName": "Mémoire IA",
  "apiBaseUrl": "/api/agent-share",
  "docsUrl": "/agent-access",
  "capabilities": { "permission": "write" }
}

C'est la seule fois où accessToken apparaît en clair, où que ce soit. Il n'est jamais rejoué dans une réponse ultérieure, jamais écrit dans le journal d'audit (au plus un hachage y figure), et jamais journalisé côté serveur. L'agent doit le conserver lui-même (variable d'environnement, fichier de configuration local, secret manager…) — il ne peut plus jamais être récupéré s'il est perdu : voir « Limites & garanties » ci-dessous.

apiBaseUrl et docsUrl sont des chemins relatifs à l'origine utilisée pour l'appel de réclamation lui-même (par exemple, si le lien de réclamation était https://safe.ilygo.ch/api/agent-share/claim/..., alors apiBaseUrl désigne https://safe.ilygo.ch/api/agent-share).

4. Authentification des appels

Une fois le jeton d'accès obtenu, chaque appel suivant vers un endpoint de /api/agent-share/* (tous, sauf l'amorçage lui-même) le porte dans l'en-tête Authorization :

Authorization: Bearer <accessToken>

Aucun cookie, aucune session ILYGO — ce jeton est l'unique identifiant, indépendant de tout compte. Il n'expire jamais automatiquement : seule une révocation (ou une mise en pause) manuelle par le propriétaire le désactive.

Un jeton inconnu, en pause ou révoqué reçoit la même réponse qu'un jeton absent : une erreur 401. Chaque endpoint résout, à partir du seul jeton, le dossier autorisé, sa permission (lecture ou écriture) et l'espace de travail du propriétaire — jamais un autre dossier ni un autre espace de travail.

Avec la permission Lecture, tous les endpoints GET ci-dessous sont disponibles ; toute tentative de mutation (POST/PUT/DELETE) renvoie une erreur 403. Avec Écriture, tout est disponible.

5. Endpoints

Toutes les requêtes vers /api/agent-share/* renvoient du JSON (sauf le téléchargement de pièce jointe, qui renvoie le fichier tel quel) et, en cas d'erreur, la forme { "error": "message" } avec un code HTTP standard (401, 403, 404, 413…).

GET /api/agent-share/tree
Authorization: Bearer <accessToken>

200 OK
[
  {
    "type": "folder",
    "id": "5b1e...",
    "parentId": null,
    "name": "Mémoire IA",
    "children": [
      {
        "type": "note",
        "id": "9f2a...",
        "folderId": "5b1e...",
        "title": "Décisions projet X",
        "updatedAt": "2026-08-03T10:12:00.000Z"
      },
      {
        "type": "folder",
        "id": "7c44...",
        "parentId": "5b1e...",
        "name": "Sessions",
        "children": []
      }
    ]
  }
]

GET /api/agent-share/notes/9f2a...
Authorization: Bearer <accessToken>

200 OK
{
  "note": {
    "id": "9f2a...",
    "folderId": "5b1e...",
    "title": "Décisions projet X",
    "content": "## Contexte\n\n...",
    "createdAt": "2026-07-20T08:00:00.000Z",
    "updatedAt": "2026-08-03T10:12:00.000Z",
    "updatedBy": "..."
  }
}

POST /api/agent-share/notes
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "folderId": "5b1e...",
  "title": "Nouvelle entrée",
  "content": "Contenu Markdown de la note."
}

201 Created
{
  "note": {
    "id": "a1c9...",
    "folderId": "5b1e...",
    "title": "Nouvelle entrée",
    "content": "Contenu Markdown de la note.",
    "createdAt": "2026-08-04T09:30:00.000Z",
    "updatedAt": "2026-08-04T09:30:00.000Z",
    "updatedBy": "..."
  }
}

POST /api/agent-share/folders
Authorization: Bearer <accessToken>
Content-Type: application/json

{ "parentId": "5b1e...", "name": "Sessions" }

6. Limites & garanties

• Pas de re-partage. Aucun endpoint de gestion des partages (créer, modifier, mettre en pause, révoquer — humain, lien ou agent) n'est exposé sous /api/agent-share/*. Un agent ne peut jamais donner accès au dossier à quelqu'un d'autre.
• Pas d'historique de versions. L'agent voit toujours le contenu actuel d'une note, jamais ses versions précédentes — réservées au propriétaire.
• Pas d'accès à la corbeille. Supprimer une note ou une pièce jointe l'envoie dans la corbeille du propriétaire (suppression douce, comme partout dans ILYGO Safe) — mais cette corbeille n'est ni visible ni restaurable par l'agent, seulement par le propriétaire.
• Actions journalisées dans l'audit du propriétaire. Chaque action de l'agent qui modifie quelque chose apparaît dans le journal d'audit du workspace du propriétaire, avec le libellé choisi à la création du partage comme identité de l'auteur.
• Quota de stockage sur le propriétaire. Les pièces jointes uploadées par l'agent comptent sur le quota de stockage du propriétaire du dossier, exactement comme ses propres uploads.
• Jeton perdu = pas de récupération. Le jeton d'accès n'est jamais stocké en clair nulle part après la réclamation. S'il est perdu, il ne peut être ni retrouvé ni régénéré pour ce même partage : le propriétaire doit révoquer ce partage (ou le laisser inutilisable) et en créer un nouveau.

7. Pour un agent IA — résumé du protocole

Cette section est destinée à un agent qui vient de récupérer cette page par une requête HTTP simple. Elle répète, sous une forme aussi littérale que possible, exactement ce qui est détaillé en prose plus haut — rien de nouveau au-delà.

PROTOCOLE_AGENT_ILYGO_SAFE v1

1. AMORÇAGE (une seule fois)
   GET {claimUrl}
   -> si déjà utilisé / inconnu / expiré : 404, ne pas réessayer, demander un nouveau lien au propriétaire.
   -> si succès (200, ne jamais mettre en cache) :
      {
        "accessToken": string,   // à conserver, n'apparaîtra plus JAMAIS ailleurs
        "folderName": string,
        "apiBaseUrl": string,    // chemin relatif, ex. "/api/agent-share"
        "docsUrl": string,       // chemin relatif vers cette page
        "capabilities": { "permission": "read" | "write" }
      }

2. AUTHENTIFICATION (sur CHAQUE appel suivant)
   Header: Authorization: Bearer {accessToken}
   Pas de cookie. Pas de session. Le jeton n'expire jamais tout seul.

3. ENDPOINTS ({base} = apiBaseUrl reçu à l'étape 1)
   GET    {base}/tree                     perm=read   body=none            -> TreeNode[] (métadonnées seulement)
   GET    {base}/notes/{noteId}           perm=read   body=none            -> {note: NoteDetail} (contenu déchiffré)
   POST   {base}/notes                    perm=write  body=json {folderId, title, content} -> 201 {note: NoteDetail}
   PUT    {base}/notes/{noteId}           perm=write  body=json {title, content}            -> {note: NoteDetail}
   DELETE {base}/notes/{noteId}           perm=write  body=none            -> {ok:true, deletedAt}
   POST   {base}/folders                  perm=write  body=json {parentId, name}            -> 201 {folder: FolderNode}
   POST   {base}/attachments              perm=write  body=multipart/form-data {noteId, file} (25 Mo max) -> 201 {attachment: Attachment}
   GET    {base}/attachments/{id}         perm=read   body=none            -> flux binaire du fichier
   DELETE {base}/attachments/{id}         perm=write  body=none            -> {ok:true}

4. RÈGLES DURES
   - Aucun endpoint de gestion de partage n'existe sous {base}/* : ne JAMAIS supposer qu'un
     endpoint de création/révocation de partage puisse exister ici, même par déduction.
   - permission="read" -> tous les GET ci-dessus fonctionnent, tout le reste renvoie 403.
   - permission="write" -> tout fonctionne.
   - Toute ressource hors du sous-arbre du dossier partagé renvoie 404 (jamais 403, pas de fuite d'existence).
   - Pas d'historique de versions, pas de corbeille consultable : ne pas tenter de les atteindre, ils n'existent
     pas côté agent.
   - accessToken perdu = fin de partie pour ce partage. Ne pas retenter l'amorçage (il est à usage unique) :
     informer le propriétaire qu'un nouveau partage doit être créé.
   - Erreurs : JSON {"error": string} + code HTTP standard (401 jeton invalide/absent, 403 permission
     insuffisante, 404 ressource hors périmètre ou inexistante, 413 pièce jointe trop volumineuse).