ruvnet--ruflo/v3/@claude-flow/cli/scripts/setup-ipfs-registry.md

IPFS Plugin Registry Setup Guide

This guide walks through setting up a live IPFS plugin registry using Google Cloud and Pinata.

Prerequisites

• Google Cloud account with billing enabled
• Node.js 20+
• gcloud CLI installed

Step 1: Pinata Setup (IPFS Pinning Service)

1.1 Create Pinata Account

1. Go to https://pinata.cloud and create an account
2. Navigate to API Keys section
3. Create a new API key with these permissions:
   • pinning/pinFileToIPFS: true
   • pinning/pinJSONToIPFS: true
   • pinning/unpin: true

1.2 Save Your Credentials

# Add to your shell profile (~/.zshrc or ~/.bashrc)
export PINATA_JWT="your-jwt-token-here"

1.3 Generate IPNS Key (Optional - for stable addressing)

If you have Pinata's paid plan with Dedicated Gateways:

# Via Pinata dashboard or API
curl -X POST "https://api.pinata.cloud/v3/ipfs/keys" \
  -H "Authorization: Bearer $PINATA_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "claude-flow-registry"}'

Step 2: Google Cloud Setup

2.1 Create Project

# Create new project
gcloud projects create claude-flow-registry --name="Claude Flow Registry"

# Set as active project
gcloud config set project claude-flow-registry

# Enable billing (required for Cloud Functions)
gcloud beta billing projects link claude-flow-registry \
  --billing-account=YOUR_BILLING_ACCOUNT_ID

2.2 Enable Required APIs

gcloud services enable \
  cloudfunctions.googleapis.com \
  cloudbuild.googleapis.com \
  storage.googleapis.com \
  secretmanager.googleapis.com

2.3 Create Storage Bucket

# Create bucket for registry source data
gcloud storage buckets create gs://claude-flow-plugin-registry \
  --location=US \
  --uniform-bucket-level-access

# Enable versioning for rollback
gsutil versioning set on gs://claude-flow-plugin-registry

# Make registry.json publicly readable (optional)
gsutil iam ch allUsers:objectViewer gs://claude-flow-plugin-registry

2.4 Create Service Account

# Create service account
gcloud iam service-accounts create plugin-registry-publisher \
  --display-name="Plugin Registry Publisher"

# Grant permissions
gcloud projects add-iam-policy-binding claude-flow-registry \
  --member="serviceAccount:plugin-registry-publisher@claude-flow-registry.iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

gcloud projects add-iam-policy-binding claude-flow-registry \
  --member="serviceAccount:plugin-registry-publisher@claude-flow-registry.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

2.5 Store Secrets

# Store Pinata JWT
echo -n "$PINATA_JWT" | gcloud secrets create pinata-jwt --data-file=-

# Generate and store Ed25519 signing key
node -e "
const crypto = require('crypto');
const { subtle } = require('crypto').webcrypto;
(async () => {
  const keyPair = await subtle.generateKey(
    { name: 'Ed25519', namedCurve: 'Ed25519' },
    true,
    ['sign', 'verify']
  );
  const privateKey = await subtle.exportKey('pkcs8', keyPair.privateKey);
  const privateKeyHex = Buffer.from(privateKey).toString('hex');
  console.log(privateKeyHex);
})();
" | gcloud secrets create registry-private-key --data-file=-

Step 3: Deploy Cloud Function

3.1 Create Function Directory

mkdir -p cloud-functions/publish-registry
cd cloud-functions/publish-registry

3.2 Create package.json

{
  "name": "publish-registry",
  "version": "1.0.0",
  "main": "index.js",
  "type": "module",
  "dependencies": {
    "@google-cloud/storage": "^7.0.0",
    "@google-cloud/secret-manager": "^5.0.0",
    "@noble/ed25519": "^2.0.0"
  }
}

3.3 Create index.js

import { Storage } from '@google-cloud/storage';
import { SecretManagerServiceClient } from '@google-cloud/secret-manager';
import * as ed from '@noble/ed25519';

const storage = new Storage();
const secretManager = new SecretManagerServiceClient();

async function getSecret(name) {
  const [version] = await secretManager.accessSecretVersion({
    name: `projects/claude-flow-registry/secrets/${name}/versions/latest`,
  });
  return version.payload.data.toString();
}

export async function publishRegistry(req, res) {
  try {
    // Get secrets
    const pinataJwt = await getSecret('pinata-jwt');
    const privateKey = await getSecret('registry-private-key');

    // Fetch registry from GCS
    const bucket = storage.bucket('claude-flow-plugin-registry');
    const file = bucket.file('registry.json');
    const [content] = await file.download();
    const registry = JSON.parse(content.toString());

    // Update timestamp
    registry.updatedAt = new Date().toISOString();

    // Sign registry
    const registryToSign = { ...registry };
    delete registryToSign.registrySignature;
    delete registryToSign.registryPublicKey;

    const message = JSON.stringify(registryToSign);
    const signature = await ed.signAsync(
      new TextEncoder().encode(message),
      Buffer.from(privateKey, 'hex')
    );
    const publicKey = await ed.getPublicKeyAsync(Buffer.from(privateKey, 'hex'));

    registry.registrySignature = Buffer.from(signature).toString('hex');
    registry.registryPublicKey = `ed25519:${Buffer.from(publicKey).toString('hex')}`;

    // Pin to IPFS
    const pinResponse = await fetch('https://api.pinata.cloud/pinning/pinJSONToIPFS', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${pinataJwt}`,
      },
      body: JSON.stringify({
        pinataContent: registry,
        pinataMetadata: {
          name: 'claude-flow-plugin-registry',
          keyvalues: {
            version: registry.version,
            updatedAt: registry.updatedAt,
          },
        },
      }),
    });

    if (!pinResponse.ok) {
      throw new Error(`Pinata error: ${await pinResponse.text()}`);
    }

    const pinResult = await pinResponse.json();

    res.json({
      success: true,
      cid: pinResult.IpfsHash,
      updatedAt: registry.updatedAt,
      pluginCount: registry.plugins.length,
      gateways: [
        `https://gateway.pinata.cloud/ipfs/${pinResult.IpfsHash}`,
        `https://ipfs.io/ipfs/${pinResult.IpfsHash}`,
      ],
    });
  } catch (error) {
    console.error('Publish failed:', error);
    res.status(500).json({ error: error.message });
  }
}

3.4 Deploy Function

gcloud functions deploy publish-registry \
  --gen2 \
  --runtime=nodejs20 \
  --region=us-central1 \
  --source=. \
  --entry-point=publishRegistry \
  --trigger-http \
  --allow-unauthenticated \
  --service-account=plugin-registry-publisher@claude-flow-registry.iam.gserviceaccount.com \
  --set-env-vars=GCP_PROJECT=claude-flow-registry

Step 4: Create Initial Registry

4.1 Upload Registry to GCS

# Generate initial registry
npx tsx scripts/publish-registry.ts --dry-run > registry.json

# Upload to GCS
gsutil cp registry.json gs://claude-flow-plugin-registry/registry.json

4.2 Trigger First Publish

# Get function URL
FUNCTION_URL=$(gcloud functions describe publish-registry \
  --gen2 --region=us-central1 --format='value(serviceConfig.uri)')

# Trigger publish
curl -X POST "$FUNCTION_URL"

Step 5: Automate with Cloud Build

5.1 Create cloudbuild.yaml

steps:
  # Update registry from npm stats
  - name: 'node:20'
    entrypoint: 'npx'
    args: ['tsx', 'scripts/publish-registry.ts', '--dry-run']
    dir: 'v3/@claude-flow/cli'

  # Upload to GCS
  - name: 'gcr.io/cloud-builders/gsutil'
    args: ['cp', 'registry.json', 'gs://claude-flow-plugin-registry/registry.json']

  # Trigger Cloud Function
  - name: 'gcr.io/cloud-builders/curl'
    args: ['-X', 'POST', '${_FUNCTION_URL}']

substitutions:
  _FUNCTION_URL: 'https://us-central1-claude-flow-registry.cloudfunctions.net/publish-registry'

# Run daily at 2am UTC
options:
  logging: CLOUD_LOGGING_ONLY

5.2 Create Cloud Scheduler Trigger

gcloud scheduler jobs create http publish-registry-daily \
  --location=us-central1 \
  --schedule="0 2 * * *" \
  --uri="https://us-central1-claude-flow-registry.cloudfunctions.net/publish-registry" \
  --http-method=POST

Step 6: Update Claude Flow CLI

Update DEFAULT_PLUGIN_STORE_CONFIG in discovery.ts:

export const DEFAULT_PLUGIN_STORE_CONFIG: PluginStoreConfig = {
  registries: [
    {
      name: 'claude-flow-official',
      description: 'Official Claude Flow plugin registry',
      // Use the CID from your first publish
      ipnsName: 'YOUR_IPNS_KEY_OR_CID',
      gateway: 'https://gateway.pinata.cloud',
      // Use your public key from the signing step
      publicKey: 'ed25519:YOUR_PUBLIC_KEY',
      trusted: true,
      official: true,
    },
  ],
  // ... rest of config
};

Cost Estimate

Service	Free Tier	Paid Tier
Pinata	1GB storage, 100 pins	$20/mo for 100GB
GCS	5GB free	~$0.02/GB/mo
Cloud Functions	2M invocations free	~$0.40/million
Cloud Scheduler	3 jobs free	$0.10/job/mo
Total	$0	~$20/mo

Troubleshooting

IPNS Resolution Fails

• Ensure the CID is pinned on Pinata
• Try different gateways (ipfs.io, cloudflare-ipfs.com)
• IPNS can take 5-10 minutes to propagate

Signature Verification Fails

• Ensure the public key in config matches the signing key
• Check that the registry wasn't modified after signing

Cloud Function Errors

• Check Cloud Logging for detailed errors
• Verify service account has correct permissions
• Test secrets access manually

References

• Pinata Docs
• Google Cloud Functions
• IPFS Gateway Spec
• Ed25519 Signatures