370025263/red-bucket

Compétence red-bucket

Cette compétence guide les agents IA dans l'interaction avec les serveurs red-bucket. red-bucket est un hub pour les actifs d'agents IA (compétences, configurations MCP, instructions telles que CLAUDE.md et AGENTS.md, sous-agents, plugins) organisé par espace de noms utilisateur/bucket, offrant une traduction de format inter-harnais à la volée entre codex, claude, agents et openclaw.

---

Garde-fous et Invariants de l'Agent

1. Authentification : Toutes les opérations d'écriture et l'accès aux buckets privés appartenant à l'utilisateur nécessitent Authorization: Bearer <token>. La lecture des buckets publics est anonyme et ne nécessite aucun en-tête.
2. Sécurité des Identifiants : N'affichez, ne journalisez et ne divulguez jamais de mots de passe, jetons API ou secrets dans la sortie ou les transcriptions utilisateur.
3. Invariant 404 pour Bucket Privé : Toute requête à un bucket privé ou à ses sous-ressources de la part d'un appelant non authentifié ou d'un non-propriétaire DOIT retourner HTTP 404 Not Found (jamais 403 Forbidden). Les non-propriétaires ne peuvent pas distinguer si un bucket privé existe ou n'existe pas.
4. Quotas et Limites :
   • Quota de buckets par défaut : 5 buckets par utilisateur (le dépassement retourne 403 avec le code bucket_quota_exceeded).
   • Limite de stockage du bucket : 10 Mo par bucket (le dépassement retourne 413 avec le code bucket_storage_exceeded).
5. Portée de l'API : Tous les points de terminaison résident sous /api/v1/.

---

La Règle des Trois Noms

Ne confondez et ne mélangez jamais ces trois opérations :

• copy (POST /api/v1/users/{username}/buckets/{bucket}/copies) : Duplique un actif à partir d'un bucket source lisible dans votre propre bucket de destination avec un historique de provenance. Retourne un objet JSON InstallRecord.
• install-script (GET /api/v1/users/{username}/buckets/{bucket}/install-script) : Retourne le texte d'un script shell exécutable qui télécharge et place les actifs traduits sur le système de fichiers local.
• translated fetch (GET .../translated) : Récupère les octets traduits bruts ou une archive zip transformée à la volée pour un harnais cible spécifié.

---

Installation et Découverte

1. Installation de la Compétence Agent (via npx skills)

Pour installer cette compétence dans un environnement d'agent :

# Installation globale pour l'accès par l'agent
npx skills add 370025263/red-bucket --skill red-bucket -g -y

# Lister les compétences disponibles sans les installer
npx skills add 370025263/red-bucket --list

2. Le client intégré : scripts/rb.mjs

Cette compétence est livrée avec son propre client. Il nécessite Node 18+ et rien d'autre — ni sh, ni curl, ni unzip, ni jq, ni npm install. Préférez-le à la création manuelle des appels HTTP ; il gère déjà correctement la normalisation d'origine, les permissions de fichiers et les écritures atomiques.

node <skill-dir>/scripts/rb.mjs login   --client claude
node <skill-dir>/scripts/rb.mjs status
node <skill-dir>/scripts/rb.mjs logout
node <skill-dir>/scripts/rb.mjs install alice/tools --target claude
node <skill-dir>/scripts/rb.mjs create  alice/tools --visibility private --description "mon kit"
node <skill-dir>/scripts/rb.mjs upload  alice/tools ./my-skill --type skill --harness claude --path skills/my-skill

login affiche le lien, puis attend --wait secondes (20 par défaut) pour le navigateur. Si votre outil shell a un délai d'attente, ce n'est pas grave : en cas de dépassement de délai, il se termine avec 0, conserve le code en attente dans pending.json à côté du fichier d'authentification, et le signale. Dites à l'utilisateur d'approuver, puis réexécutez login ou status ; le jeton est collecté et sauvegardé à ce moment-là. Aucun second code n'est émis tant que le premier est valide, donc ne "réessayez" jamais en tuant le processus et en recommençant.

install écrit dans le répertoire courant ; --dest DIR ou $RED_BUCKET_DEST le place ailleurs. --origin URL ou $RED_BUCKET_URL pointe vers un serveur auto-hébergé. Les buckets privés fonctionnent une fois que vous êtes connecté — la même commande, en utilisant l'identifiant stocké.

create et upload sont le volet publication. upload envoie chaque fichier sous le répertoire local comme un seul actif : les fichiers texte en tant que texte, tout le reste en base64, enraciné à --path (par défaut : le propre nom du répertoire). --type est ce qu'est l'actif (skill, mcp, instructions, subagent, plugin) et --harness est le harnais pour lequel il a été écrit — le serveur traduit à partir de là. Le serveur valide l'actif et le client imprime exactement ce à quoi il s'est opposé, par exemple validation failed: SKILL.md: SKILL.md missing. Les deux nécessitent une connexion. Préférez-les aux corps POST .../assets fabriqués à la main : les points de terminaison bruts ci-dessous sont le contrat, le client est l'outil.

3. Installer un bucket sans cette compétence

GET .../install-script?target=<harness> avec Accept: text/plain retourne un programme Node autonome. Sauvegardez le corps sous le nom rb-install.mjs et exécutez node rb-install.mjs. Même dépendance Node uniquement, mêmes substitutions RED_BUCKET_URL / RED_BUCKET_DEST.

(Pour les buckets privés, il n'y a pas de programme public à coller : récupérez GET .../translated avec Authorization: Bearer <token> à la place, ou utilisez simplement rb.mjs install pendant que vous êtes connecté.)

---

Connexion et Emplacement du Jeton

La lecture des buckets publics ne nécessite rien. Tout ce qui écrit — créer un bucket, télécharger un actif, ouvrir un problème ou une demande de tirage — nécessite un jeton porteur.

Ne demandez jamais à l'utilisateur son mot de passe red-bucket. Utilisez la délégation navigateur ci-dessous. C'est le seul moyen autorisé pour qu'un agent obtienne un jeton.

Où le jeton est conservé

$RED_BUCKET_AUTH                                     si défini, ce fichier exact
%APPDATA%\red-bucket\auth.json                       sur Windows
${XDG_CONFIG_HOME:-~/.config}/red-bucket/auth.json   partout ailleurs

Regardez d'abord là. Si une entrée active pour cette origine existe déjà, utilisez-la — ne renvoyez pas l'utilisateur via le navigateur pour un jeton qu'il vous a déjà accordé.

Mode répertoire 0700, mode fichier 0600. Écrivez-le de manière atomique (fichier temporaire dans le même répertoire, puis renommez) afin qu'une écriture interrompue ne puisse pas laisser un fichier incomplet. Forme, indexée par origine afin qu'un serveur auto-hébergé et le serveur public puissent coexister :

{
  "version": 1,
  "hosts": {
    "https://redbucket.store": {
      "username": "stone91",
      "token": "...",
      "created_at": "2026-09-03T04:07:19Z",
      "client": "claude"
    }
  }
}

Résolvez l'identité dans cet ordre : $RED_BUCKET_TOKEN si défini, puis l'entrée dans ce fichier dont la clé correspond à l'origine à laquelle vous parlez, puis anonyme. Envoyez-la comme Authorization: Bearer <token>.

Normalisez l'origine avant de l'utiliser comme clé, à la fois lors de l'écriture et de la recherche : mettez le schéma et l'hôte en minuscules, supprimez la barre oblique de fin, supprimez le port lorsqu'il s'agit du port par défaut pour le schéma. Ainsi, https://RedBucket.store:443/ et https://redbucket.store sont une seule clé, pas trois. Sautez cette étape et vous renverrez l'utilisateur via le navigateur pour un jeton que vous possédez déjà, et laisserez une entrée en double derrière vous.

Si le fichier ne peut pas être analysé, ou si version est un nombre que vous ne reconnaissez pas, traitez-le comme aucune information d'identification — revenez à l'anonymat et dites à l'utilisateur que le fichier semble erroné. Ne supprimez et n'écrasez jamais un fichier que vous n'avez pas pu lire ; il peut contenir les jetons d'un autre outil.

Lisez, modifiez et écrivez l'intégralité du fichier en une seule fois, et gardez la fenêtre courte. Deux harnais se connectant au même moment lisent tous les deux, écrivent tous les deux, et le plus lent efface l'entrée de l'autre. Le fichier temporaire puis renommage ci-dessus empêche un fichier déchiré, pas une mise à jour perdue.

N'affichez jamais le jeton, ne l'écho pas dans la transcription, ne l'écrivez jamais dans un dépôt, ne le mettez jamais dans une commande shell que l'utilisateur peut voir dans son historique.

Obtenir un jeton : délégation navigateur

Le jeton est créé par le serveur et remis directement à votre processus. Il ne transite jamais par la conversation.

1. Démarrez-le.

POST /api/v1/auth/device
{"client": "claude"}

201 vous donne device_code, user_code, verification_url_complete, expires_in (600) et interval (5).

Le device_code est la moitié secrète — elle reste à l'intérieur de votre processus. Le user_code est le code court que l'humain lit.

2. Montrez le lien à l'humain. Quelque chose comme :

Ouvrez ceci pour vous connecter ou créer un compte : https://redbucket.store/link/BQ7K-2M4X La page devrait afficher le code BQ7K-2M4X. Je vais attendre.

Ils l'ouvrent dans un navigateur, se connectent s'ils ne le sont pas déjà, et voient un écran nommant votre client et listant ce qu'ils accordent. Ils appuient sur Autoriser ou Refuser.

3. Interrogez, pas plus vite que toutes les interval secondes :

POST /api/v1/auth/device/token
{"device_code": "..."}

• {"status": "pending"} — continuez d'attendre.
• {"status": "denied"} — ils ont dit non. Arrêtez et dites-le clairement.
• {"status": "approved", "token": ..., "user": {...}} — vous l'avez.
• 404 — le code a expiré ou a déjà été collecté. Proposez de recommencer. Le device_code est à usage unique ; une deuxième interrogation réussie est toujours une 404.

4. Sauvegardez-le dans le chemin ci-dessus et dites uniquement Connecté en tant que <nom_utilisateur>.

Se déconnecter

POST /api/v1/auth/logout avec le jeton révoque ce jeton côté serveur. Supprimez ensuite l'entrée de cet hôte du fichier d'authentification. Faites les deux ; l'un sans l'autre laisse soit un jeton actif sur le serveur, soit un jeton mort sur le disque.

Il n'y a pas de serveur MCP red-bucket

mcp dans red-bucket est un type d'actif qu'un bucket peut contenir, pas un serveur que nous exécutons. Cette compétence parlant à /api/v1/ constitue l'intégration client complète. Ne cherchez pas de point de terminaison MCP auquel vous connecter.

Flux Côté Utilisateur et Opérations API

1. Enregistrement, Connexion et Profil Utilisateur

• S'enregistrer :

  POST /api/v1/auth/register
  Content-Type: application/json
  
  {
    "username": "alice",
    "email": "[email protected]",
    "password": "strongpassword123"
  }
  

  • Réponse : 201 Created avec Location: /api/v1/users/alice et objet User public (mots de passe hachés avec Argon2id; aucun jeton émis lors de l'enregistrement).

• Connexion :

  POST /api/v1/auth/login
  Content-Type: application/json
  
  {
    "email": "[email protected]",
    "password": "strongpassword123"
  }
  

  • Réponse : 200 OK avec {"token": "<jeton_opaque>", "token_type": "bearer", "user": { ... }}.

• Obtenir le Profil (moi) :

  GET /api/v1/users/me
  Authorization: Bearer <token>
  

  • Réponse : 200 OK avec les détails de l'utilisateur (incluant email, bucket_quota, bucket_count).

---

2. Créer un Bucket à partir d'un Modèle

Crée un bucket sous l'espace de noms de l'utilisateur authentifié :

POST /api/v1/users/{username}/buckets
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "dev-skills",
  "visibility": "public",
  "description": "Compétences générales pour le développement d'agents",
  "template": "claude"
}

• Modèles autorisés : codex, agents, claude, openclaw (ou omettre pour un bucket vide). Cette liste s'agrandit ; GET /api/v1/templates est la liste à jour.
• Visibilité : public ou private (par défaut private).
• Réponse : 201 Created avec Location: /api/v1/users/{username}/buckets/{name} et JSON Bucket.
• Erreurs : 403 (bucket_quota_exceeded si dépassement de 5 buckets), 409 (bucket_name_taken).

---

3. Télécharger des Actifs

Télécharge un actif avec validation de format et application du quota :

POST /api/v1/users/{username}/buckets/{bucket}/assets
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "skill",
  "source_harness": "claude",
  "path": "skills/calculator",
  "files": [
    {
      "path": "SKILL.md",
      "content_text": "---\nname: calculator\ndescription: Effectue des calculs arithmétiques\n---\n\n# Compétence Calculatrice\n"
    }
  ]
}

• Types d'actifs : skill, mcp, instructions, subagent, plugin.
• Harnais sources : claude, codex, agents, openclaw. Cette liste s'agrandit ; GET /api/v1/translation-matrix est la liste à jour. Ne rejetez jamais un harnais nommé par l'utilisateur simplement parce qu'il manque dans ce fichier — laissez le serveur répondre.
• Le contenu du fichier peut être fourni comme content_text (UTF-8) ou content_base64.
• Réponse : 201 Created avec Location: /api/v1/users/{username}/buckets/{bucket}/assets/{asset_id}.
• Erreurs : 413 (bucket_storage_exceeded si le bucket dépasse 10 Mo), 422 (validation_failed avec règle spécifique et violations de chemin).

---

4. Navigation Anonyme et Récupération Traduite

• Naviguer dans le Bucket (Public / Anonyme) :

  GET /api/v1/users/{username}/buckets/{bucket}
  

• Naviguer dans l'Arborescence des Fichiers et les Blobs :

  GET /api/v1/users/{username}/buckets/{bucket}/tree
  GET /api/v1/users/{username}/buckets/{bucket}/blob/{*path}
  

• Récupérer le Bucket Complet Traduit pour un Harnais Cible :

  GET /api/v1/users/{username}/buckets/{bucket}/translated?target=codex
  

  • Réponse : 200 OK (archive zip binaire, en-tête X-Red-Bucket-Lossy: true|false).

• Récupérer un Actif Unique Traduit :

  GET /api/v1/users/{username}/buckets/{bucket}/assets/{asset_id}/translated?target=codex
  

  • Réponse : 200 OK (octets traduits bruts ou archive zip).

---

5. Exécuter le Script d'Installation

Récupère le script d'installation shell généré pour un harnais cible :

GET /api/v1/users/{username}/buckets/{bucket}/install-script?target=claude
Accept: text/plain

• Réponse : 200 OK avec le texte brut du script shell.
• S'exécute côté client pour télécharger l'archive zip traduite et placer les fichiers dans les répertoires locaux du harnais.

---

6. Copier un Actif vers son Propre Bucket (Suivi de Provenance)

Copie un actif d'un bucket source vers votre propre bucket de destination :

POST /api/v1/users/{username}/buckets/{dest_bucket}/copies
Authorization: Bearer <token>
Content-Type: application/json

{
  "source_username": "bob",
  "source_bucket": "public-skills",
  "source_asset_id": 12,
  "dest_path": "skills/calculator"
}

• Réponse : 201 Created avec Location: /api/v1/users/{username}/buckets/{dest_bucket}/copies/{copy_id} et objet JSON InstallRecord.
• Valide l'actif source, vérifie le quota de 10 Mo et enregistre la provenance.

---

7. Problèmes et Commentaires

• Créer un Problème :

  POST /api/v1/users/{username}/buckets/{bucket}/issues
  Authorization: Bearer <token>
  Content-Type: application/json
  
  {
    "title": "Bogue dans la traduction de la compétence calculatrice",
    "body": "Lors de la traduction de...